Try-AS/400 - User contributions [en]

ZuluSCSI

2026-09-10T16:10:32Z

PoC: /* Tape drive support */ missing word

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

<blockquote>'''Note:''' Current state of affairs is that at least for writes, the SD card itself is a considerable brake shoe for writes, presumably because of so called 'Write Amplification''. This is not meant to stay like this forever. Optimizations are possible and will be implemented eventually.</blockquote>

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for some tasks.

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should be orderly shut down, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives, you can create a directory instead of a file. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named. The ''Eject'' button loads and inserts the next image in order. Individual images can be inserted through the menu via USB.

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
Currently, two tape drives are emulated:
* <code>Device = "AS400_CISC"</code>, a CISC era QIC1000, FC #6343,
* <code>Device = "AS400_PPC"</code>, a PCI/RISC era SLR5 drive.

To use,
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code> command,
* use the serial console to attach image(s) to the drive.

Without any ''Device'' parameter, a standard tape drive is emulated, with no special AS/400 quirks. This works with many PPC/PCI machines. However, the presence of a ''TapeDensity'' parameter seems necessary in ''zuluscsi.ini''.
[SCSI0]
TapeDensity = 0x25

For trying an emulated SLR5 drive:
* ''zuluscsi.ini'':
[SCSI0]
Device = "AS400_PPC"

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.
* The amended (with an explicit ''Device'' statement) tape code as of v2026.08.28 has not yet undergone extensive testing. Initial tests yield mixed results.

=== CD drive support ===
* create directory <code>CD0</code>,
* populate with one or more readymade ISO images,
* use the serial console to attach image(s) to the drive.

No special handling for the ID in ''zuluscsi.ini''.

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware CD drive, make sure to delete your old CD device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

Tested with Firmware 2026-08-07, 9401-150, V4R4, V5R2: IPL only so far, but that works. '''Note:''' CISC era OS/400 has no CD-ROM support whatsoever.

=== Disk drive support ===
The officially released code base is able to present multiple disk drives to the system, initialize, and install SLIC + base OS/400 + LPPs + PTFs.

* Copy ''as400_disk_definitions.txt'' from the official GitHub repository to the SD card.
** Because of serial numbers currently being hard coded, only one disk per type should be used for now!
* ''zuluscsi.ini'':
[SCSI]
System = AS400_PPC

[SCSI6]
AS400_DiskProfile = "09L4044"
PrefetchBytes = 0

When a ''AS400_DiskProfile'' is configured for a given SCSI ID, and the associated image cannot be found on the SD card, a new one is generated automatically, with the correct size. This takes some time, so wait until the activity LED stays unlit.

There is a shell-script <code>utils/extract_as400_disk_data.sh</code> in the original source tree on GitHub to generate more ''as400_disk_definitions.txt'' entries from real disks connected to a SCSI controller when ran under Linux.

Caveats:
* Writes to the emulated disk are very slow compared to reads.

Fully tested with Firmware v2026.08.27RC1, 9401-150, V4R4, V5R2.

== Current state ==
We have to differ three hardware generations when considering Zulu vs. AS/400:
{|class="wikitable"
! 
!CISC/IMPI, 520 bytes/block disks
!RISC/SPD, 520/522 bytes/block disks
!RISC/PCI, 522 bytes/block disks
|-
!CD-ROM
|Not supported
|Untested
|Works
|-
!Tape
|Fails, hangs with SRC early.
|Untested
|Works
|-
!Disk
|Fails, hangs with SRC early.
|Untested
|Works
|}

All successful tests so far have been based on a ZuluSCSI wide board on a 9401-150, while the CISC tests have been done with a ZuluSCSI Blaster on a 9401-P02.

There are success reports of more 150's working, and one of a 9406-270 becoming stuck with A6000244, ''Contact was lost with device indicated''.

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

ZuluSCSI

2026-09-10T16:09:38Z

PoC: /* Tape drive support */ Rework

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

<blockquote>'''Note:''' Current state of affairs is that at least for writes, the SD card itself is a considerable brake shoe for writes, presumably because of so called 'Write Amplification''. This is not meant to stay like this forever. Optimizations are possible and will be implemented eventually.</blockquote>

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for some tasks.

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should be orderly shut down, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives, you can create a directory instead of a file. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named. The ''Eject'' button loads and inserts the next image in order. Individual images can be inserted through the menu via USB.

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
Currently, two tape drives are emulated:
* <code>Device = "AS400_CISC"</code>, a CISC era QIC1000, FC #6343,
* <code>Device = "AS400_PPC"</code>, a PCI/RISC era SLR5 drive.

To use,
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code>,
* use the serial console to attach image(s) to the drive.

Without any ''Device'' parameter, a standard tape drive is emulated, with no special AS/400 quirks. This works with many PPC/PCI machines. However, the presence of a ''TapeDensity'' parameter seems necessary in ''zuluscsi.ini''.
[SCSI0]
TapeDensity = 0x25

For trying an emulated SLR5 drive:
* ''zuluscsi.ini'':
[SCSI0]
Device = "AS400_PPC"

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.
* The amended (with an explicit ''Device'' statement) tape code as of v2026.08.28 has not yet undergone extensive testing. Initial tests yield mixed results.

=== CD drive support ===
* create directory <code>CD0</code>,
* populate with one or more readymade ISO images,
* use the serial console to attach image(s) to the drive.

No special handling for the ID in ''zuluscsi.ini''.

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware CD drive, make sure to delete your old CD device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

Tested with Firmware 2026-08-07, 9401-150, V4R4, V5R2: IPL only so far, but that works. '''Note:''' CISC era OS/400 has no CD-ROM support whatsoever.

=== Disk drive support ===
The officially released code base is able to present multiple disk drives to the system, initialize, and install SLIC + base OS/400 + LPPs + PTFs.

* Copy ''as400_disk_definitions.txt'' from the official GitHub repository to the SD card.
** Because of serial numbers currently being hard coded, only one disk per type should be used for now!
* ''zuluscsi.ini'':
[SCSI]
System = AS400_PPC

[SCSI6]
AS400_DiskProfile = "09L4044"
PrefetchBytes = 0

When a ''AS400_DiskProfile'' is configured for a given SCSI ID, and the associated image cannot be found on the SD card, a new one is generated automatically, with the correct size. This takes some time, so wait until the activity LED stays unlit.

There is a shell-script <code>utils/extract_as400_disk_data.sh</code> in the original source tree on GitHub to generate more ''as400_disk_definitions.txt'' entries from real disks connected to a SCSI controller when ran under Linux.

Caveats:
* Writes to the emulated disk are very slow compared to reads.

Fully tested with Firmware v2026.08.27RC1, 9401-150, V4R4, V5R2.

== Current state ==
We have to differ three hardware generations when considering Zulu vs. AS/400:
{|class="wikitable"
! 
!CISC/IMPI, 520 bytes/block disks
!RISC/SPD, 520/522 bytes/block disks
!RISC/PCI, 522 bytes/block disks
|-
!CD-ROM
|Not supported
|Untested
|Works
|-
!Tape
|Fails, hangs with SRC early.
|Untested
|Works
|-
!Disk
|Fails, hangs with SRC early.
|Untested
|Works
|}

All successful tests so far have been based on a ZuluSCSI wide board on a 9401-150, while the CISC tests have been done with a ZuluSCSI Blaster on a 9401-P02.

There are success reports of more 150's working, and one of a 9406-270 becoming stuck with A6000244, ''Contact was lost with device indicated''.

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

IBM BOOK format

2026-09-10T08:57:47Z

PoC: Updated page

'''IBM BookManager Softcopy''' is IBM's legacy online documentation system, created in the 1980s. It was historically used mostly on mainframes, midrange (AS/400) and OS/2, although it also saw some use in other areas including AIX.

IBM no longer uses it for new documentations of its products, but there is an immense quantity of legacy electronic documentation from the period when IBM actively used it (from the 1980s thru 2010s), particularly documentation CD-ROMs/DVD-ROMs and images thereof.

The file-internal style (?) format apparently is called IBMIDDOC.

The standard DOS style extension is <code>BOO</code>, and "application/book" is sometimes used as MIME type, but was never officially registered.

== Internal structure ==
The internal structure is fully documented as a part of the ''Geist'' reference implementation on GitHub.

== See also ==
* [[Reviving InfoSeeker]]

== Weblinks ==
* [https://github.com/cyberdotgent/geist Geist IBM Book format reference implementation]
** [https://github.com/cyberdotgent/geist/tree/main/doc/boo-spec Geist Book format documentation]
* [http://www.edm2.com/index.php/BookManager BookManager Releases] contains history of IBM BookManager releases
* [https://www.ibm.com/support/pages/using-pdfs-and-bookmanager-books-your-workstation-or-mainframe Using PDFs and BookManager Books on your workstation or mainframe], IBM.com
* [https://en.wikipedia.org/wiki/Terse_(file_format) Terse (file format)], Wikipedia
* [https://en.wikipedia.org/wiki/LZ77_and_LZ78 LZ77 and LZ78] compression algorithms, Wikipedia
* [https://patents.google.com/patent/US4814746A/en?oq=4814746 Data compression method] for TERSE, patents.google.com
* [http://fileformats.archiveteam.org/wiki/ZIP ZIP archive file format], archiveteam.org, mentions TERSE.
* [https://hercules-390.yahoogroups.narkive.com/gYwJ3QUu/terse-for-pcs-windows-aix-linux terse for PCs (Windows, AIX, Linux ....)], hercules-390@yahoogroups.com
* [https://bit.listserv.ibm-main.narkive.com/82nDDwrh/trsmain-question TRSMAIN question], IBM-Main mailing list
* [https://share.confex.com/share/121/webprogram/Handout/Session14242/14242-%20zOS%20Documentation%20Search%20Strategies%20%28Final%20Edition%29.pdf 14242: z/OS Documentation Search Strategies], presentation slides in PDF format

== Footnotes ==
<references />

[[Category: System Internals]]

ZuluSCSI

2026-09-08T12:15:29Z

PoC: /* Examples */ More precise on tapes

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

<blockquote>'''Note:''' Current state of affairs is that at least for writes, the SD card itself is a considerable brake shoe for writes, presumably because of so called 'Write Amplification''. This is not meant to stay like this forever. Optimizations are possible and will be implemented eventually.</blockquote>

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for some tasks.

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should be orderly shut down, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives, you can create a directory instead of a file. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named. The ''Eject'' button loads and inserts the next image in order. Individual images can be inserted through the menu via USB.

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
Currently, two tape drives are emulated:
* a CISC era QIC1000, FC #6343,
* a PCI/RISC era SLR5 drive.

* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code>,
* use the serial console to attach image(s) to the drive.
* ''zuluscsi.ini'':
[SCSI0]
Device = "AS400_PPC"

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.
* The amended (with an explicit ''Device'' statement) tape code as of v2026.08.28 has not yet undergone extensive testing. Initial tests yield mixed results.

=== CD drive support ===
* create directory <code>CD0</code>,
* populate with one or more readymade ISO images,
* use the serial console to attach image(s) to the drive.

No special handling for the ID in ''zuluscsi.ini''.

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware CD drive, make sure to delete your old CD device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

Tested with Firmware 2026-08-07, 9401-150, V4R4, V5R2: IPL only so far, but that works. '''Note:''' CISC era OS/400 has no CD-ROM support whatsoever.

=== Disk drive support ===
The officially released code base is able to present multiple disk drives to the system, initialize, and install SLIC + base OS/400 + LPPs + PTFs.

* Copy ''as400_disk_definitions.txt'' from the official GitHub repository to the SD card.
** Because of serial numbers currently being hard coded, only one disk per type should be used for now!
* ''zuluscsi.ini'':
[SCSI]
System = AS400_PPC

[SCSI6]
AS400_DiskProfile = "09L4044"
PrefetchBytes = 0

When a ''AS400_DiskProfile'' is configured for a given SCSI ID, and the associated image cannot be found on the SD card, a new one is generated automatically, with the correct size. This takes some time, so wait until the activity LED stays unlit.

There is a shell-script <code>utils/extract_as400_disk_data.sh</code> in the original source tree on GitHub to generate more ''as400_disk_definitions.txt'' entries from real disks connected to a SCSI controller when ran under Linux.

Caveats:
* Writes to the emulated disk are very slow compared to reads.

Fully tested with Firmware v2026.08.27RC1, 9401-150, V4R4, V5R2.

== Current state ==
We have to differ three hardware generations when considering Zulu vs. AS/400:
{|class="wikitable"
! 
!CISC/IMPI, 520 bytes/block disks
!RISC/SPD, 520/522 bytes/block disks
!RISC/PCI, 522 bytes/block disks
|-
!CD-ROM
|Not supported
|Untested
|Works
|-
!Tape
|Fails, hangs with SRC early.
|Untested
|Works
|-
!Disk
|Fails, hangs with SRC early.
|Untested
|Works
|}

All successful tests so far have been based on a ZuluSCSI wide board on a 9401-150, while the CISC tests have been done with a ZuluSCSI Blaster on a 9401-P02.

There are success reports of more 150's working, and one of a 9406-270 becoming stuck with A6000244, ''Contact was lost with device indicated''.

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

Panel Usage

2026-09-06T19:42:13Z

PoC: /* Elements */ Amber LED

Every AS/400 or later machines have a '''panel''', either as hardware, or emulated in Software (for logical partitions, ''LPAR''s).

== Elements ==
The panel is comprised of these elements:
* Pushbutton ↑
* Pushbutton ↓
* Pushbutton ''Enter'' often colored blue,
* LC-Display, for output of System Reference Codes (SRC),
* Power pushbutton ⌽,
* LED (green) for showing the power state,
* LED (green), with a pictogram reminding of stairs (main processor activity),<ref>It is not the disk activity LED as it was usual with PCs was into the 2000s.</ref>
* LED (amber) with a vertical bar, cut in half and one half moved slightly horizontal (error<ref>In other words: System activity is halted and will not try to recover until a reset is issued. Reset means power cycle.</ref>).

Usually after plugging the power, the LCD will light up green.

== Changing settings ==
Normally, the LCD shows two chars and two digits, like
01 B N
The meaning is:
* 01 - Show current IPL-Parameters
* B - (A B C D) IPL-Source
* N (N M) IPL-Mode

<blockquote>Beware, the panel allows to set a multitude of parameters to the system service processor card. Please don't wildly push buttons to see what will happen. Chances are you will change a setting and the machine will no longer IPL, or console connection is broken, or probably worse things.</blockquote>

=== Setting IPL Mode to source D, and mode manual ===
This example setting is needed to make the machine IPL from install media, such as tape or optical.

* Push ↑ once to set the digit display from 01 to 02. Confirm with ''Enter''.
* Push ↑ oder ↓ until the character display is showing <code>D M</code>.<ref>Older machines support concurrent setting of Source and Mode, newer support setting Source and Mode separately.</ref> Confirm with ''Enter''.
* Push the power button ⌽. You can now insert the I_BASE-CD into the optical drive.

== See also ==
* [[SRC 0000BBBB]]

== Weblinks ==
* [https://www.ibm.com/docs/en/i/7.5.0?topic=functions-normal-control-panel Normal control panel functions], IBM.com

== Footnotes ==
<references />

[[Category:Basic Knowledge]]

Post-Install Optimizations

2026-09-03T16:23:04Z

PoC: /* Security System Values */ Typo

OS/400 provides a lot of default values for variables (affecting the run-time environment) and program options. Some of these make sense, some of them are kept consistent with earlier versions of the OS because of compatibility reasons by IBM.

Some of these recommendations might not be appropriate for you by various reasons. Don't apply blindly. Know what you do, use the online help to retrieve background information on the topic in question.

The findings below are based on V4R5 with annotated exceptions for newer releases.

== Housekeeping ==
These are settings and scheduled jobs to keep your system uncluttered.

=== Change unneeded programs to not run ===
We most likely don't need to run ''lpd'' and ''smtpd'' to run per default.
CHGLPDA AUTOSTART(*NO)
CHGSMTPA AUTOSTART(*NO)

You can easily check all settings at once by using <code>UPDDTA QUSRSYS/QATOCSTART</code>. These are not needed in general.
* *DIRSRV
* *NETSVR
* *SLP

Depending on OS version, not all entries may be available.

=== Change uninstalled programs to not run ===
If you did not install the Ultimedia package, you can remove the pre started job from the QSYSWRK subsystem description to make it not generate an error message at IPL time.
RMVPJE SBSD(QSYSWRK) PGM(QUMEDIA/QUMBPJTC)

If you did not install the Directory Services package (aka LDAP), you can remove the auto started jobs from the QSYSWRK subsystem description to make them not generate an error message at IPL time.
RMVAJE SBSD(QSYSWRK) JOB(QGLDPUBA)
RMVAJE SBSD(QSYSWRK) JOB(QGLDPUBE)

Both is valid and tested for V4R5. Note that newer releases moved the background jobs to the base OS so there is no error message when starting them. I have not tested if they're required to run, though.

If you did not install the performance tools, you don't need trying to start the performance data collector:
RMVAJE SBSD(QCTL) JOB(QPFRCOL)

I can't remember if the latter is valid for V4R5. It's valid for V3R2, though.

=== Cleanup unneeded stuff ===
These objects come by default at OS install time, are not needed to my knowledge, and thus can be safely deleted:
DLTOUTQ OUTQ(QDKT)
DLTOUTQ OUTQ(QPFROUTQ)
DLTOUTQ OUTQ(QPRINTS)
DLTF FILE(QPRINTS)
DLTOUTQ OUTQ(QPRINT2)
DLTF FILE(QPRINT2)
DLTOUTQ OUTQ(QTPPPOUTQ)
DLTDEVD DEVD(QESPAP)
DLTDEVD DEVD(QIADSP)
DLTDEVD DEVD(QIAPRT)
DLTDEVD DEVD(QQAHOST)
DLTDEVD DEVD(QTIDA)
DLTDEVD DEVD(QTIDA2)
DLTCTLD CTLD(QESCTL)
DLTCTLD CTLD(QTICTL)
DLTLIND LIND(QESLINE)
DLTLIND LIND(QTILINE)

== System Values ==
System values are like environment variables as known from common operating systems. They influence system operation. I recommend the following changes.

=== System Control ===
* Change work environment to separate subsystems for different kind of jobs. This also makes it easy to introduce your own subsystems.
CHGSYSVAL SYSVAL(QCTLSBSD) VALUE('QCTL QSYS')
* Set automatic DST adjustment, and UTC offset. This value is valid for Central Europe (Berlin, Paris, …) '''Note!''' This variable is not available in V4R5. See [[#Weblinks|Weblinks]] below.
CHGSYSVAL SYSVAL(QTIMZON) VALUE('QP0100CET2')
* Adjust time to automatically end disconnected interactive jobs (sessions) to one day.
CHGSYSVAL SYSVAL(QDSCJOBITV) VALUE('1440')

=== (Memory) Allocation ===
* Adjust automatic performance values only at runtime, not at IPL.<ref>If you change the amount of memory for the machine, temporarily adjust the value to '2', make the memory change and then change the value back to '3' — no further IPL needed.</ref> This allows the system to automatically adjust memory allocations and activity levels to minimize paging (disk I/O).
CHGSYSVAL SYSVAL(QPFRADJ) VALUE('3')
* Allow memory pools to self adjust the paging block size depending on jobs running. This is called ''Expert Cache''. You can adjust the maximum active jobs per pool in the <code>WRKSHRPOOL</code> display.<ref>Press <code>F21</code> to switch to view 2 or 3 to have adjustment possibilities.</ref>
CHGSHRPOOL POOL(*BASE) PAGING(*CALC)
CHGSHRPOOL POOL(*INTERACT) PAGING(*CALC)
CHGSHRPOOL POOL(*SPOOL) PAGING(*CALC)
* Reservations for job related data structures at IPL time. See <code>DSPSYSSTS</code> and set to slightly more than the ''Jobs in System'' value to be seen there when the system is working "normal".<ref>Press <code>F21</code> to switch to view 2 or 3 to see the overall job count.</ref>
CHGSYSVAL SYSVAL(QTOTJOB) VALUE(100)
* Reservations for job related data structures at IPL time. See <code>WRKACTJOB</code> and set to slightly more than the ''Active Jobs'' value to be seen there when the system is working "normal".
CHGSYSVAL SYSVAL(QACTJOB) VALUE(95)
* Maximize TCP buffers for maximum performance, especially on faster links.
CHGTCPA TCPRCVBUF(8388608) TCPSNDBUF(8388608)
* Make sure, database tasks can use system resources as needed.
CHGSYSVAL SYSVAL(QQRYDEGREE) VALUE(*OPTIMIZE)
* When interactive jobs require more CPU time than being allowed by default (2 seconds),<ref>This is set in *CLS objects.</ref> to finish a block of processing, allow that memory to be taken from the *BASE pool. Advantage: The QINTER subsystem pool will not be subject to auto adjustment because of jobs which are supposed to run in batch.
CHGSYSVAL SYSVAL(QTSEPOOL) VALUE(*BASE)

=== Message-and-Logging ===
* Allow immediate deletion of problem reports.
CHGSYSVAL SYSVAL(QPRBHLDITV) VALUE(0)
* Do not log software errors. We can't do much about these anyway, seen from a hobbyist viewpoint.
CHGSYSVAL SYSVAL(QSFWERRLOG) VALUE(*NOLOG)
* Maximize Central Syslog (viewable with <code>DSPLOG</code> size to lessen rotation frequency. Depending on OS version only ''VALUE(32767)'' may be valid.
CHGSYSVAL SYSVAL(QHSTLOGSIZ) VALUE(*DAILY)
* Raise allowed unsuccessful sign on tries before taking action.
CHGSYSVAL SYSVAL(QMAXSIGN) VALUE('15')
* Minimize logging for sessions disconnected beause of device errors.
CHGSYSVAL SYSVAL(QDEVRCYACN) VALUE(*ENDJOBNOLIST)

=== Security System Values ===
* Unrestrict automatic creation of system objects triggered by external (network) requests.
CHGSYSVAL SYSVAL(QAUTOVRT) VALUE(*NOMAX)
* Allow restore with all security relevant flags.
CHGSYSVAL SYSVAL(QALWOBJRST) VALUE(*ALL)
* For TCP connections to work, we need encrypted passwords.
CHGDDMTCPA PWDRQD(*ENCRYPTED)
* Allow ''QSYSOPR'' sign-on to all devices.
CHGSYSVAL SYSVAL(QLMTSECOFR) VALUE('0')
* Raise maximum password length to maximum value.<ref>In newer OS versions, an additional variable ''QPWDLVL'' allows even longer passwords.</ref>
CHGSYSVAL SYSVAL(QPWDMAXLEN) VALUE(10)
* Raise minimum passsword length for security reasons.
CHGSYSVAL SYSVAL(QPWDMINLEN) VALUE(8)

=== Misc ===
* PTF install shall be done on unattended IPL time, and don't try to report problems to IBM directly.<ref>Needs prior setup for ''Electronic Customer Support''.</ref>
CHGSRVA PTFINSTYP(*DLYALL) RPTPRBAUTO(*NO)
* Provide European style formatting.
CHGSYSVAL SYSVAL(QCURSYM) VALUE('€')
CHGSYSVAL SYSVAL(QDECFMT) VALUE('J')
CHGSYSVAL SYSVAL(QSRTSEQ) VALUE(*LANGIDUNQ)<ref>This value isn't available with V4R5. You can use ''*LANGIDSHR'' there.</ref>
CHGSYSVAL SYSVAL(QDATFMT) VALUE('DMY')<ref>Default value for 2924 (US English) is MDY.</ref>
* Allow background compiling in PDM as ordinary user, and submitting batch jobs in general.
GRTOBJAUT OBJ(QGPL/QBATCH) OBJTYPE(*JOBD) USER(*PUBLIC) AUT(*USE)
* Tweaking automatic cleanup (like ''logrotate'').
CHGCLNUP ALWCLNUP(*YES) STRTIME('02:22:22') USRMSG(7) SYSMSG(3) SYSPRT(7) SYSLOG(14) CALITM(*KEEP)
* Change general SNA networking attributes. This is one '''long''' line. Take care to get it completely.
CHGNETA JOBACN(*SEARCH) VRTAUTODEV(254) MDMCNTRYID(DE)

=== Charset Conversion ===
In addition, OS/400 has a default value of 65535 for <code>QCCSID</code>. It should be set to a value being dependent on the installed language, to enable automatic translation of data on disk to the display device, and back. For Germany, the correct value is 273, and for US, it's 37. A good hint is to check your 5250 emulator program for possible values.

== IPL Customization ==
With this procedure, the current startup program for the OS can be retrieved for easy customization.
RTVCLSRC PGM(QSTRUP) SRCFILE(QCLSRC)
WRKMBRPDM FILE(QCLSRC) MBR(QSTRUP) MBRTYPE(CLP)
CRTCLPGM PGM(QGPL/QSTRUP)

To activate your changes, run <code>WRKSYSVAL SYSVAL(QSTRUPPGM)</code> and change the values to reflect the new program object in QGPL. '''Note''': On a used system's install, the previous owner might have already done a customized QSTRUP. See <code>DSPSYSVAL QSTRUPPGM</code> which one is the currently set startup program before accidentally overwriting!

Notable use cases for changing <code>QSTRUP</code> would be to make SNA Distribution Services, and TCP/IP (on older releases than V4R5) start at IPL time.

New entries must be located after the ''IF COND'' statement and ''DONE:'' label. Always put a ''MONMSG MSGID(CPF0000)'' after each statement. Failing to do so will not ignore any errors but make the IPL script terminate abnormally in case of an error and possibly leave you with an inaccessible system.

Examples:
* Start TCP/IP:
QSYS/STRTCP
MONMSG MSGID(CPF0000)
<blockquote>'''Note:''' TCP/IP on V4R5 and later is by IBM provided default automatically started with an appropriate autostart entry <code>struptcpip</code> in the <code>qsyswrk</code> subsystem description. No action is necessary in the startup CL!</blockquote>

* Start SNADS:
QSYS/STRSBS SBSD(QSNADS)
MONMSG MSGID(CPF0000)

== Change Program Defaults ==
This establishes different default behavior of some programs which makes life somewhat easier.<ref>Some people highly oppose against changing default values because the default values have been provided for a reason. But then, the <code>CHGCMDDFT</code> also has been provided for a reason.</ref> At least noting down the changed programs and their former values is recommended, for example in <code>QGPL/QTXTSRC.CMDDFT</code>.
<blockquote>'''Note:''' CL applications might run a command with the changed default values, in turn combining (new) defaults and submitted parameters into an invalid combination of parameters which might lead to run-time errors. As far as I'm aware, my proposed changes are compatible with such situations.</blockquote>

* File creation and change defaults:
** Enforce immediate return to program error handling instead of make programs seem to hang (<code>wait…</code>),
** Enforce reusing deleted record space,<ref>If there is no access path defined, sequentially read records are no longer guaranteed to *be in timely order (FIFO)!</ref>
** Remove sizing restrictions,<ref>A runaway process filling the disks to 100 % is not stopped prior!</ref>
** Use a smaller access path size for probably increased performance,
** Allow automatic LF rebuild when running <code>chgpf</code>.
CHGCMDDFT CMD(CRTPF) NEWDFT('SIZE(*NOMAX *N *N) WAITFILE(*IMMED) WAITRCD(*IMMED) REUSEDLT(*YES)')
CHGCMDDFT CMD(CRTSRCPF) NEWDFT('SIZE(*NOMAX *N *N) ACCPTHSIZ(*MAX4GB)')
CHGCMDDFT CMD(CHGPF) NEWDFT('DLTDEPLF(*YES) SIZE(*NOMAX *N *N) WAITFILE(*IMMED) WAITRCD(*IMMED) REUSEDLT(*YES)')
CHGCMDDFT CMD(CRTLF) NEWDFT('WAITFILE(*IMMED) WAITRCD(*IMMED) ACCPTHSIZ(*MAX4GB)')
CHGCMDDFT CMD(CHGLF) NEWDFT('WAITFILE(*IMMED) WAITRCD(*IMMED) ACCPTHSIZ(*MAX4GB)')
* Menus usually go into the library with the application's other objects. Change current library to there, so applications can find their objects.<ref>It might be beneficial to individually use <code>CURLIB(*NOCHG)</code> for higher level menu objects being put into libraries which are part of the default library search list (''*LIBL'') — such as ''QGPL'' — to not needlessly change the default library in a for some users unexpected way.</ref>
CHGCMDDFT CMD(CRTMNU) NEWDFT('CURLIB(*MNULIB)')
* No unnecessary wait for power down. <code>CONFIRM(*NO)</code> can be added for newer releases to suppress prompting.
CHGCMDDFT CMD(PWRDWNSYS) NEWDFT('OPTION(*IMMED) ENDSBSOPT(*NOJOBLOG)')
* Don't waste time displaying a not so very much interesting screen prior to connection.
CHGCMDDFT CMD(STRPASTHR) NEWDFT('PASTHRSCN(*NO)')

Be aware that reinstalls, or applying PTFs can overwrite command objects and thus their changed default values. Also note, hat installing a secondary language on a system also installs a separate set of <code>*cmd</code> objects for that language. You may want to apply the defaults with qualified object names to these, too.

== Regular Cleanup jobs ==
See job comment TEXT for details. These are '''long''' lines. Take care to get it completely.
ADDJOBSCDE JOB(PRGPRB) CMD(DLTPRB STATUS(*CLOSED)) FRQ(*WEEKLY) SCDDATE(*NONE) SCDDAY(*ALL) SCDTIME('13:22:00') MSGQ(*LIBL/QSYSOPR) TEXT('Purge closed and deletable problem entries')
ADDJOBSCDE JOB(RCLTMPSTG) CMD(RCLTMPSTG DAYS(30)) FRQ(*MONTHLY) SCDDATE(*MONTHSTR) SCDDAY(*NONE) SCDTIME('13:24:00') MSGQ(*LIBL/QSYSOPR) TEXT('Reclaim temporary storage')
ADDJOBSCDE JOB(RTVDSKINF) CMD(RTVDSKINF) FRQ(*MONTHLY) SCDDATE(*MONTHSTR) SCDDAY(*NONE) SCDTIME('13:34:00') MSGQ(*LIBL/QSYSOPR) TEXT('Retrieve disk space stats')
ADDJOBSCDE JOB(QPGMRCLR) CMD(CLRMSGQ MSGQ(QPGMR) CLEAR(*KEEPUNANS)) FRQ(*WEEKLY) SCDDATE(*NONE) SCDDAY(*ALL) SCDTIME('07:07:07') RCYACN(*NOSBM) MSGQ(*NONE) TEXT('Delete uninteresting messages')

== PTF handling ==
To save space on disk and backup media, you may want to consider applying all PTFs permanently. You cannot remove them afterwards, but that largely doesn't really matter for older and hobbyist systems.

From a console, first run an `ENDSYS (*IMMED)` to get the system into restricted, state. Then run
APYPTF LICPGM(*ALL) SELECT(*ALL) APY(*PERM) DELAYED(*YES) IPLAPY(*YES)

This will apply all PTFs permanently upon next normal IPL. Note you should IPL from the A-side to allow changes to the B side being made.

A final IPL to the B side gets you the fully PTF'd system.

== Re-Enable InfoSeeker ==
Only necessary for newer V4R4 and newer. If the command isn't known, don't bother: Then your release is so new that it's gone entirely.

See also: [[Reviving InfoSeeker]]

CRTDTAARA DTAARA(QUSRSYS/QBMGINFSKR) TYPE(*CHAR) LEN(8)<ref>Works in V4R5. The <code>STRINFSKR</code> command is not included anymore in IBM i 7.1, and probably earlier releases.</ref>

== Additional Steps tested with V7R2 ==
After trying to enter SST, one gets the message that the password has expired. But the password cannot be changed. Re-IPL '''in manual mode''', do not IPL but enter DST, and change password as directed.

* Choose ''5. Work with DST environment'' and ''3. Service tools user IDs''.
** Disable the "backdoor" profile ''11111111'',
** ''Change password'' for ''QSECOFR'', ''Set password to expired'' to ''2=No''.
* Press F12 and choose ''6. Service tools security data''.
** Enter 0 into the field ''8. Password expiration interval in days'', 8 into the ''Selection'' field, and press return.
** Enter a high number (like 12) into the field ''9. Maximum sign-on attempts allowed'', 9 into the ''Selection'' field, and press return.
** Enter 0 into the field ''10. Duplicate password control'', 10 into the ''Selection'' field, and press return.

Now exit DST.

You may choose to enter SST, enter 7 for ''Work with system security'', and set ''Allow a service tools user ID with a default and expired password to change its own password'' to ''1=Yes''. Since we changed password expiry to ''never'', this step is entirely optional.

== See also ==
* [[Change Command Defaults for File-Commands]]
* [[How to properly shut down your AS/400]]

== Weblinks ==
* [https://archive.midrange.com/midrange-l/199912/msg01738.html STRINFSKR], Midrange Mailing-List
* [https://github.com/PoC-dev/as400-autodst as400-autodst], GitHub

== Footnotes ==
<references />

[[Category: System Administration]]

ZuluSCSI

2026-08-29T20:59:40Z

PoC: /* Tape drive support */ Removed inert entry

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

<blockquote>'''Note:''' Current state of affairs is that at least for writes, the SD card itself is a considerable brake shoe for writes, presumably because of so called 'Write Amplification''. This is not meant to stay like this forever. Optimizations are possible and will be implemented eventually.</blockquote>

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for some tasks.

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should be orderly shut down, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives, you can create a directory instead of a file. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named. The ''Eject'' button loads and inserts the next image in order. Individual images can be inserted through the menu via USB.

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code>,
* use the serial console to attach image(s) to the drive.
* ''zuluscsi.ini'':
[SCSI0]
Device = "AS400_PPC"

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.
* The amended (with an explicit ''Device'' statement) tape code as of v2026.08.28 has not yet undergone extensive testing.

=== CD drive support ===
* create directory <code>CD0</code>,
* populate with one or more readymade ISO images,
* use the serial console to attach image(s) to the drive.

No special handling for the ID in ''zuluscsi.ini''.

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware CD drive, make sure to delete your old CD device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

Tested with Firmware 2026-08-07, 9401-150, V4R4, V5R2: IPL only so far, but that works.

=== Disk drive support ===
The officially released code base is able to present multiple disk drives to the system, initialize, and install SLIC + base OS/400 + LPPs + PTFs.

* Copy ''as400_disk_definitions.txt'' from the official GitHub repository to the SD card.
** Because of serial numbers currently being hard coded, only one disk per type should be used for now!
* ''zuluscsi.ini'':
[SCSI]
System = AS400_PPC

[SCSI6]
AS400_DiskProfile = "09L4044"
PrefetchBytes = 0

When a ''AS400_DiskProfile'' is configured for a given SCSI ID, and the associated image cannot be found on the SD card, a new one is generated automatically, with the correct size. This takes some time, so wait until the activity LED stays unlit.

There is a shell-script <code>utils/extract_as400_disk_data.sh</code> in the original source tree on GitHub to generate more ''as400_disk_definitions.txt'' entries from real disks connected to a SCSI controller when ran under Linux.

Caveats:
* Writes to the emulated disk are very slow compared to reads.

Fully tested with Firmware v2026.08.27RC1, 9401-150, V4R4, V5R2.

== Current state ==
We have to differ three hardware generations when considering Zulu vs. AS/400:
{|class="wikitable"
! 
!CISC/IMPI, 520 bytes/block disks
!RISC/SPD, 520/522 bytes/block disks
!RISC/PCI, 522 bytes/block disks
|-
!CD-ROM
|Not supported
|Untested
|Works
|-
!Tape
|Fails, hangs with SRC early.
|Untested
|Works
|-
!Disk
|Fails, hangs with SRC early.
|Untested
|Works
|}

All successful tests so far have been based on a ZuluSCSI wide board on a 9401-150, while the CISC tests have been done with a ZuluSCSI Blaster on a 9401-P02.

There are success reports of more 150's working, and one of a 9406-270 becoming stuck with A6000244, ''Contact was lost with device indicated''.

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

ZuluSCSI

2026-08-29T20:58:27Z

PoC: /* Tape drive support */ Typo

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

<blockquote>'''Note:''' Current state of affairs is that at least for writes, the SD card itself is a considerable brake shoe for writes, presumably because of so called 'Write Amplification''. This is not meant to stay like this forever. Optimizations are possible and will be implemented eventually.</blockquote>

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for some tasks.

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should be orderly shut down, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives, you can create a directory instead of a file. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named. The ''Eject'' button loads and inserts the next image in order. Individual images can be inserted through the menu via USB.

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code>,
* use the serial console to attach image(s) to the drive.
* ''zuluscsi.ini'':
[SCSI]
System = "AS400_PPC"

[SCSI0]
Device = "AS400_PPC"

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.
* The amended (with an explicit ''Device'' statement) tape code as of v2026.08.28 has not yet undergone extensive testing.

=== CD drive support ===
* create directory <code>CD0</code>,
* populate with one or more readymade ISO images,
* use the serial console to attach image(s) to the drive.

No special handling for the ID in ''zuluscsi.ini''.

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware CD drive, make sure to delete your old CD device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

Tested with Firmware 2026-08-07, 9401-150, V4R4, V5R2: IPL only so far, but that works.

=== Disk drive support ===
The officially released code base is able to present multiple disk drives to the system, initialize, and install SLIC + base OS/400 + LPPs + PTFs.

* Copy ''as400_disk_definitions.txt'' from the official GitHub repository to the SD card.
** Because of serial numbers currently being hard coded, only one disk per type should be used for now!
* ''zuluscsi.ini'':
[SCSI]
System = AS400_PPC

[SCSI6]
AS400_DiskProfile = "09L4044"
PrefetchBytes = 0

When a ''AS400_DiskProfile'' is configured for a given SCSI ID, and the associated image cannot be found on the SD card, a new one is generated automatically, with the correct size. This takes some time, so wait until the activity LED stays unlit.

There is a shell-script <code>utils/extract_as400_disk_data.sh</code> in the original source tree on GitHub to generate more ''as400_disk_definitions.txt'' entries from real disks connected to a SCSI controller when ran under Linux.

Caveats:
* Writes to the emulated disk are very slow compared to reads.

Fully tested with Firmware v2026.08.27RC1, 9401-150, V4R4, V5R2.

== Current state ==
We have to differ three hardware generations when considering Zulu vs. AS/400:
{|class="wikitable"
! 
!CISC/IMPI, 520 bytes/block disks
!RISC/SPD, 520/522 bytes/block disks
!RISC/PCI, 522 bytes/block disks
|-
!CD-ROM
|Not supported
|Untested
|Works
|-
!Tape
|Fails, hangs with SRC early.
|Untested
|Works
|-
!Disk
|Fails, hangs with SRC early.
|Untested
|Works
|}

All successful tests so far have been based on a ZuluSCSI wide board on a 9401-150, while the CISC tests have been done with a ZuluSCSI Blaster on a 9401-P02.

There are success reports of more 150's working, and one of a 9406-270 becoming stuck with A6000244, ''Contact was lost with device indicated''.

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

ZuluSCSI

2026-08-29T20:51:58Z

PoC: /* Disk drive support */ Typo

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

<blockquote>'''Note:''' Current state of affairs is that at least for writes, the SD card itself is a considerable brake shoe for writes, presumably because of so called 'Write Amplification''. This is not meant to stay like this forever. Optimizations are possible and will be implemented eventually.</blockquote>

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for some tasks.

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should be orderly shut down, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives, you can create a directory instead of a file. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named. The ''Eject'' button loads and inserts the next image in order. Individual images can be inserted through the menu via USB.

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code>,
* use the serial console to attach image(s) to the drive.
* ''zuluscsi.ini'':
[SCSI]
System="AS400_PPC"

[SCSI0]
Device = "AS400_PPC"

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.
* The amended (with an explicit ''Device'' statement) tape code as of v2026.08.28 has not yet undergone extensive testing.

=== CD drive support ===
* create directory <code>CD0</code>,
* populate with one or more readymade ISO images,
* use the serial console to attach image(s) to the drive.

No special handling for the ID in ''zuluscsi.ini''.

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware CD drive, make sure to delete your old CD device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

Tested with Firmware 2026-08-07, 9401-150, V4R4, V5R2: IPL only so far, but that works.

=== Disk drive support ===
The officially released code base is able to present multiple disk drives to the system, initialize, and install SLIC + base OS/400 + LPPs + PTFs.

* Copy ''as400_disk_definitions.txt'' from the official GitHub repository to the SD card.
** Because of serial numbers currently being hard coded, only one disk per type should be used for now!
* ''zuluscsi.ini'':
[SCSI]
System = AS400_PPC

[SCSI6]
AS400_DiskProfile = "09L4044"
PrefetchBytes = 0

When a ''AS400_DiskProfile'' is configured for a given SCSI ID, and the associated image cannot be found on the SD card, a new one is generated automatically, with the correct size. This takes some time, so wait until the activity LED stays unlit.

There is a shell-script <code>utils/extract_as400_disk_data.sh</code> in the original source tree on GitHub to generate more ''as400_disk_definitions.txt'' entries from real disks connected to a SCSI controller when ran under Linux.

Caveats:
* Writes to the emulated disk are very slow compared to reads.

Fully tested with Firmware v2026.08.27RC1, 9401-150, V4R4, V5R2.

== Current state ==
We have to differ three hardware generations when considering Zulu vs. AS/400:
{|class="wikitable"
! 
!CISC/IMPI, 520 bytes/block disks
!RISC/SPD, 520/522 bytes/block disks
!RISC/PCI, 522 bytes/block disks
|-
!CD-ROM
|Not supported
|Untested
|Works
|-
!Tape
|Fails, hangs with SRC early.
|Untested
|Works
|-
!Disk
|Fails, hangs with SRC early.
|Untested
|Works
|}

All successful tests so far have been based on a ZuluSCSI wide board on a 9401-150, while the CISC tests have been done with a ZuluSCSI Blaster on a 9401-P02.

There are success reports of more 150's working, and one of a 9406-270 becoming stuck with A6000244, ''Contact was lost with device indicated''.

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

ZuluSCSI

2026-08-29T20:51:30Z

PoC: Reworked after release

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

<blockquote>'''Note:''' Current state of affairs is that at least for writes, the SD card itself is a considerable brake shoe for writes, presumably because of so called 'Write Amplification''. This is not meant to stay like this forever. Optimizations are possible and will be implemented eventually.</blockquote>

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for some tasks.

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should be orderly shut down, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives, you can create a directory instead of a file. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named. The ''Eject'' button loads and inserts the next image in order. Individual images can be inserted through the menu via USB.

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code>,
* use the serial console to attach image(s) to the drive.
* ''zuluscsi.ini'':
[SCSI]
System="AS400_PPC"

[SCSI0]
Device = "AS400_PPC"

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.
* The amended (with an explicit ''Device'' statement) tape code as of v2026.08.28 has not yet undergone extensive testing.

=== CD drive support ===
* create directory <code>CD0</code>,
* populate with one or more readymade ISO images,
* use the serial console to attach image(s) to the drive.

No special handling for the ID in ''zuluscsi.ini''.

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware CD drive, make sure to delete your old CD device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

Tested with Firmware 2026-08-07, 9401-150, V4R4, V5R2: IPL only so far, but that works.

=== Disk drive support ===
The officially released code base is able to present multiple disk drives to the system, initialize, and install SLIC + base OS/400 + LPPs + PTFs.

* Copy ''as400_disk_definitions.txt'' from the official GitHub repository to the SD card.
** Because of serial numbers currently being hard coded, only one disk per type should be used for now!
* ''zuluscsi.ini'':
[SCSI]
System = AS400_PPC

[SCSI6]
AS400_DiskProfile = "09L4044"
PrefetchBytes = 0

When a ''AS400_DiskProfile'' is configured for a given SCSI ID, and the associated image cannot be found on the SD card, a new one is generated automatically, with the correct size. This takes some time, so wait until the activity LED stays unlit.

There is a shell-script <code>utils/extract_as400_disk_data.sh</code> in the original source tree on GitHub to generate more ''as400_disk_definitions.txt'' entries from real disks connected to a SCSI controller when ran under Linux.

Caveats:
* Writes to the emulated disk are very slow compared to reads.

Fully tested with Firmware v2026.08.27RC1, 9401-150, V4R4, V5R2.

== Current state ==
We have to differ three hardware generations when considering Zulu vs. AS/400:
{|class="wikitable"
! 
!CISC/IMPI, 520 bytes/block disks
!RISC/SPD, 520/522 bytes/block disks
!RISC/PCI, 522 bytes/block disks
|-
!CD-ROM
|Not supported
|Untested
|Works
|-
!Tape
|Fails, hangs with SRC early.
|Untested
|Works
|-
!Disk
|Fails, hangs with SRC early.
|Untested
|Works
|}

All successful tests so far have been based on a ZuluSCSI wide board on a 9401-150, while the CISC tests have been done with a ZuluSCSI Blaster on a 9401-P02.

There are success reports of more 150's working, and one of a 9406-270 becoming stuck with A6000244, ''Contact was lost with device indicated''.

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

ZuluSCSI

2026-08-29T19:54:09Z

PoC: Reworked

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

<blockquote>'''Note:''' Current state of affairs is that at least for writes, the SD card itself is a considerable brake shoe for writes, presumably because of so called 'Write Amplification''. This is not meant to stay like this forever. Optimizations are possible and will be implemented eventually.</blockquote>

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for some tasks.

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should be orderly shut down, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives, you can create a directory instead of a file. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named. The ''Eject'' button loads and inserts the next image in order. Individual images can be inserted through the menu via USB.

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code>,
* use the serial console to attach image(s) to the drive.
* ''zuluscsi.ini'':
[SCSI]
System="AS400_PPC"

[SCSI0]
TapeDensity = 0x25

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

This configuration has been tested over the course of multiple weeks:
* Occasional <tt>go save</tt> 21,
* daily differential backups,
* occasional single file restores.

Tested with Firmware 2026-06-12, 9401-150, V4R5.

=== CD drive support ===
* create directory <code>CD0</code>,
* populate with one or more readymade ISO images,
* use the serial console to attach image(s) to the drive.

No special handling for the ID in ''zuluscsi.ini''.

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware CD drive, make sure to delete your old CD device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

Tested with Firmware 2026-08-07, 9401-150, V4R4: IPL only so far.

=== Disk drive support ===
The officially released code base is able to present a singular #6717, 8.5 GiB disk drive to the system, initialize, and install SLIC + base OS/400 + LPPs + PTFs.

* Generate disk image:
dd if=/dev/zero of=HD6.img bs=522 count=17177940 status=progress
* ''zuluscsi.ini'':
[SCSI]
System = AS400_PPC

[SCSI6]
PrefetchBytes = 0

Caveats:
* Writes to the emulated disk are very slow compared to reads.
* One user with a RP2040 reported failure for the disk to be recognized. Prerelease firmware solved the issue.

Fully tested with Firmware 2026-08-21, 9401-150, V4R4, V5R2.

== Current state ==
We have to differ three hardware generations when considering Zulu vs. AS/400:
{|class="wikitable"
! 
!CISC/IMPI, 520 bytes/block disks
!RISC/SPD, 520/522 bytes/block disks
!RISC/PCI, 522 bytes/block disks
|-
!CD-ROM
|Not supported
|Untested
|Works
|-
!Tape
|Fails, hangs with SRC early.
|Untested
|Works
|-
!Disk
|Fails, hangs with SRC early.
|Untested
|Works
|}

All successful tests so far have been based on a ZuluSCSI wide board on a 9401-150, while the CISC tests have been done with a ZuluSCSI Blaster on a 9401-P02.

There are success reports of more 150's working, and one of a 9406-270 becoming stuck with A6000244, ''Contact was lost with device indicated''.

== Next ==
These features are completed, partially tested, but did not make it to the official releases yet:
* More disk profiles, loadable in ''zuluscsi.ini'' via external file ''as400_disk_definitions.txt'', so different types than the built-in 522 bytes, 8.5 GiB #6717 can be assigned.
** Shellscript to generate more ''as400_disk_definitions.txt'' entries from real disks connected to a SCSI controller when ran under Linux
** Because of serial numbers currently being hard coded, only one disk per type should be used
* Allowed more memory to accommodate the necessary VPD SCSI pages for multiple disks
* Present captured real tape VPD/SCSI data from IBM SLR5/QIC1000 when using <code>Device = "AS400_PPC"</code> or <code>Device = "AS400_CISC"</code> in an ID stanza

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

ZuluSCSI

2026-08-28T08:01:13Z

PoC: /* Current state */ updates

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for some tasks.

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named, and are used in alphabetical order.<ref>Either through the ''Eject'' button, or the media menu.</ref>

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code>,
* use the serial console to attach image(s) to the drive.
* ''zuluscsi.ini'':
[SCSI]
System="AS400_PPC"

[SCSI0]
TapeDensity = 0x25

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

This configuration has been tested over the course of multiple weeks:
* Occasional <tt>go save</tt> 21,
* daily differential backups,
* occasional single file restores.

Tested with Firmware 2026-06-12, 9401-150, V4R5.

=== CD drive support ===
* create directory <code>CD0</code>,
* populate with one or more readymade ISO images,
* use the serial console to attach image(s) to the drive.

No special handling for the ID in ''zuluscsi.ini''.

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware CD drive, make sure to delete your old CD device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

Tested with Firmware 2026-08-07, 9401-150, V4R4: IPL only so far.

=== Disk drive support ===
The officially released code base is able to present a singular #6717, 8.5 GiB disk drive to the system, initialize, and install SLIC + base OS/400 + LPPs + PTFs.

* Generate disk image:
dd if=/dev/zero of=HD6.img bs=522 count=17177940 status=progress
* ''zuluscsi.ini'':
[SCSI]
System = AS400_PPC

[SCSI6]
PrefetchBytes = 0

Caveats:
* Writes to the emulated disk are very slow compared to reads.
* One user with a RP2040 reported failure for the disk to be recognized. Prerelease firmware solved the issue.

Fully tested with Firmware 2026-08-21, 9401-150, V4R4.

== Current state ==
We have to differ three hardware generations when considering Zulu vs. AS/400:
{|class="wikitable"
! 
!CISC/IMPI, 520 bytes/block disks
!RISC/SPD, 520/522 bytes/block disks
!RISC/PCI, 522 bytes/block disks
|-
!CD-ROM
|Not supported
|Untested
|Works
|-
!Tape
|Fails, hangs with SRC early.
|Untested
|Works
|-
!Disk
|Fails, hangs with SRC early.
|Untested
|Works
|}

All successful tests so far have been based on a ZuluSCSI wide board on a 9401-150, while the CISC tests have been done with a ZuluSCSI Blaster on a 9401-P02.

There are success reports of more 150's working, and one of a 9406-270 becoming stuck with A6000244, ''Contact was lost with device indicated''.

== Next ==
These features are completed, partially tested, but did not make it to the official releases yet:
* More disk profiles, loadable in ''zuluscsi.ini'' via external file ''as400_disk_definitions.txt'', so different types than the built-in 522 bytes, 8.5 GiB #6717 can be assigned.
** Shellscript to generate more ''as400_disk_definitions.txt'' entries from real disks connected to a SCSI controller when ran under Linux
** Because of serial numbers currently being hard coded, only one disk per type should be used
* Allowed more memory to accommodate the necessary VPD SCSI pages for multiple disks
* Present captured real tape VPD/SCSI data from IBM SLR5/QIC1000 when using <code>Device = "AS400_PPC"</code> or <code>Device = "AS400_CISC"</code> in an ID stanza

Currently contained in v2026.08.27-RC1.

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

ZuluSCSI

2026-08-28T07:39:26Z

PoC: /* Next */ Updated things

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for some tasks.

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named, and are used in alphabetical order.<ref>Either through the ''Eject'' button, or the media menu.</ref>

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code>,
* use the serial console to attach image(s) to the drive.
* ''zuluscsi.ini'':
[SCSI]
System="AS400_PPC"

[SCSI0]
TapeDensity = 0x25

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

This configuration has been tested over the course of multiple weeks:
* Occasional <tt>go save</tt> 21,
* daily differential backups,
* occasional single file restores.

Tested with Firmware 2026-06-12, 9401-150, V4R5.

=== CD drive support ===
* create directory <code>CD0</code>,
* populate with one or more readymade ISO images,
* use the serial console to attach image(s) to the drive.

No special handling for the ID in ''zuluscsi.ini''.

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware CD drive, make sure to delete your old CD device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

Tested with Firmware 2026-08-07, 9401-150, V4R4: IPL only so far.

=== Disk drive support ===
The officially released code base is able to present a singular #6717, 8.5 GiB disk drive to the system, initialize, and install SLIC + base OS/400 + LPPs + PTFs.

* Generate disk image:
dd if=/dev/zero of=HD6.img bs=522 count=17177940 status=progress
* ''zuluscsi.ini'':
[SCSI]
System = AS400_PPC

[SCSI6]
PrefetchBytes = 0

Caveats:
* Writes to the emulated disk are very slow compared to reads.
* One user with a RP2040 reported failure for the disk to be recognized. Prerelease firmware solved the issue.

Fully tested with Firmware 2026-08-21, 9401-150, V4R4.

== Current state ==
We have to differ three hardware generations when considering Zulu vs. AS/400:
{|class="wikitable"
! 
!CISC/IMPI, 520 bytes/block disks
!RISC/SPD, 520/522 bytes/block disks
!RISC/PCI, 522 bytes/block disks
|-
!CD-ROM
|Not supported
|Untested
|Works
|-
!Tape
|Fails, hangs with SRC early.
|Untested
|Works
|-
!Disk
|Fails, hangs with SRC early.
|Untested
|Works
|}

All successful tests so far have been based on a ZuluSCSI wide board, while the CISC tests have been done with a ZuluSCSI Blaster.

== Next ==
These features are completed, partially tested, but did not make it to the official releases yet:
* More disk profiles, loadable in ''zuluscsi.ini'' via external file ''as400_disk_definitions.txt'', so different types than the built-in 522 bytes, 8.5 GiB #6717 can be assigned.
** Shellscript to generate more ''as400_disk_definitions.txt'' entries from real disks connected to a SCSI controller when ran under Linux
** Because of serial numbers currently being hard coded, only one disk per type should be used
* Allowed more memory to accommodate the necessary VPD SCSI pages for multiple disks
* Present captured real tape VPD/SCSI data from IBM SLR5/QIC1000 when using <code>Device = "AS400_PPC"</code> or <code>Device = "AS400_CISC"</code> in an ID stanza

Currently contained in v2026.08.27-RC1.

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

Serial networking scenarios with Cisco-Routers

2026-08-25T21:17:59Z

PoC: /* Configuration: OS/400 (Fiona) */ Fixed inconsistency

Sometimes, older, donated hardware comes without LAN I/O-adapters. Sometimes it has serial, synchronous capable communication I/O-adapters, though. This article shows several ways how to "network" AS/400 machines through these, with the help of (older) Cisco hard- and software, and points out pros and cons.

<blockquote>'''Note:''' This article is probably more about Cisco configuration than AS/400.</blockquote>

Cisco has provided a lot of configuration options to support different networking scenarios. Emphasis is to multiplex once separated IBM SNA and PC-/Workstation based traffic onto the same physical wiring. Expectably, huge cost savings for recurring bills resulted, because expensive leased lines could now be shared. 
Decades later, the focus shifted from commercial applications to hobbyist uses, with their own set of use cases.

Technologies exploited for the desired outcomes are:
* SDLC as transport protocol for SNA,
* X.25 as transport protocol for higher-level protocols (SNA, IP),
* Data Link Switching Plus (DLSw+) for transport of SNA over IP based links,
* Local or remote media conversion between LANs and SDLC or QLLC (X.25).

This article does intentionally not cover SNASw, a reduced SNA "routing" stack within Cisco IOS. Depending on use case, it has proven to be awfully slow, may even crash routers in some scenarios, and may be of limited use because it's configuration is fixed as a Branch Extender (BEX) node.

For clarity, the scenarios mentioned later always refer to two machines:
* An existing AS/400 with LAN attachment (Token Ring, Ethernet), already established as APPN Network Node in the local LAN. This is the 9401-150 shown on the network plan's right side. This machine's name is ''Nibbler''.
* An additional machine with no LAN I/O adapters, which is meant to establish a network connection of sorts to the existing AS/400. This is the 9401-P03 shown on the network plan's left side. This machine's Name is ''Fiona''.

Additional information is provided in the individual scenario descriptions.

== Physical Layer Requirements ==
[[File:IBM 2652.jpg|thumb|right|#6152 serial IOA (SPD), located in a P02]]
[[File:IBM 2609.jpg|thumb|right|#2609 serial IOA (SPD), located in a P03]]
[[File:IBM 2609 Brick.jpg|thumb|right|2609 Breakout-Brick — note that the Cisco cable is plugged directly which is '''wrong''', and only shown for illustrational purposes.]]
[[File:IBM-2720-Base-PCI-WAN-Twinaxial-IOA.jpg|thumb|right|IBM #2720 combined twinax- and serial IOA (PCI)]]
[[File:IBM-2721-PCI-Two-Line-WAN-IOA.jpg|thumb|right|IBM #2721 dual serial IOA (PCI)]]

On the physical layer, some kind of serial connection is required. In earlier times, AS/400's often had an external modem, providing remote diagnostics capabilities through ''ECS'' (Electronic Customer Support), connected to a serial port. For the sake of simplicity, the AS/400 in question is assumed to already have a serial port, RS-232 style.

<blockquote>'''Note:''' DE-9 or DB-25 connectors directly screwed to the chassis are meant for diagnostics and UPS connection. These are '''not''' normal serial ports!</blockquote>

Matching IBM V.24 Modem Cables for your particular hardware can be sourced e. g. through shops on the internet.

'''Cable designations:'''
{|class="wikitable"
!Description
!Length
!Part Number
!Feature Code
|-
|valign="top"|RS232 Cable DB-25F to DB-25M
|valign="top" rowspan="6"|6.1 m
|valign="top"|22F0149
|valign="top" rowspan="3"|#9022
|-
|valign="top"|(Germany)
|valign="top"|22F0150
|-
|valign="top"|(Japan)
|valign="top"|22F0151
|-
|valign="top"|RS232 PCI Communications Cable Mini-Centronics to DB-25M
|valign="top"|44H7480
|valign="top" rowspan="3"|#0348
|-
|valign="top"|(Germany)
|valign="top"| 44H7482
|-
|valign="top"|(Japan)
|valign="top"| 44H7484
|}

There are other serial connectivity options but these are very rare.

On the Cisco-side of affairs, just two things are necessary:
* Cisco 16xx, 25xx, 26xx or similar router model with T-Type serial interface (card),
* Cisco CAB-232 FC.

<blockquote>'''Note!''' It is of utmost importance to keep in mind that the AS/400 serial ports have ''sense pins'', to know which kind of cable is attached. If you plug in an ordinary PC serial cable, and vary on the line description, you’ll eventually find the succinct message in the QSYSOPR message queue, that a cable could not be found. Therefore the requirement of an ''IBM V.24 Modem Cable'', or a self made cable, or adapter, providing the necessary sense pin connectivity.

'''For this reason, you'll need to plug the DB-25F socket connector of the Cisco cable to the modem cable, and not directly to the AS/400’s port.'''</blockquote>

It seems desirable to also provide means of Integration of serial only machinery into LANs. Cisco IOS provides functionality for such scenarios.

== Software Requirements ==
Basically:
* Some flavor of OS/400,
* Cisco IOS for your particular model with a certain feature set.

See the ''Cisco Feature Navigator'' weblink for additional information. Over a long time, Cisco has flooded the market with many different Cisco routers. They fall into broad generation groups, but there are still differences which model can (may) run which IOS feature set. Also, there is the definition of "officially supported" of "works", and the unofficial "works anyway in certain scenarios". Bottom line: The resulting combinations are way too many to be described here. A general rule of thumb: The bigger the image, and the more characters the classic feature set description has, the more likely it will have what you need.

It's important to understand the roles of the different involved components.
* the serial-only machine ''Fiona'' is an ''APPN end node'',
* the protocol to running over the serial cable is either SDLC, or X.25,
* the Cisco router converts the SDLC (SDLLC) or X.25 (QLLC) frames to a format being compatible with Token Ring,
* Fiona's APPN session terminates on ''Nibbler''.<ref>This can be another AS/400 but is not necessarily so.</ref>

== Configuration preparations ==
Obtain the resource names of the serial ports.

On the AS/400 systems, type <code>wrkhdwrsc *cmn</code> to get a list of communication hardware, and associated ports. Examples:

* V3/SPD:
'''Resource Type Text'''
CMB01 917B Combined function IOP
LIN01 2609 Comm Adapter
LIN011 2609 V.24 Port
LIN012 2609 V.24 Port

* V4/PCI:
'''Resource Type Status Text'''
LIN01 2720 Operational Comm Adapter
CMN01 2720 Operational V.24 Port

<blockquote>'''Note!''' OS/400 V3 seems to not designate ports as ''CMN'', but as ''LIN'' with three digits. Newer releases designate ports on an adapter as ''CMN''.</blockquote>

On Cisco IOS, type <code>show interfaces description</code> to get a list of interfaces. Serial interfaces are designated by starting with ''Se''.
Interface Status Protocol Description
Et0 up up
Se0 down down

Apart from this, components are expected to have some basic configuration settings applied:
* OS/400:
** Basic network settings reviewed in <code>dspneta</code> and subsequently <code>chgneta</code>
** <code>QAUTOCFG</code> system variable switched to ''on''
** LAN configuration established for LAN capable machines
* Cisco IOS:
** Basic settings applied
** Basic network configuration established

== Scenario 1: Purely local SNA APPN connection over SDLC ==
[[File:AS400-SDLC-Cisco-Ring-AS400.png|frame|center|Network Plan]]

This scenario is for when all involved components are reasonably close together physically, e. g. in the same room.

* Pro: Fairly easy to configure, applicable to other machinery than just AS/400's,
* Con: Maximum speed is 19200 bps.

=== Configuration: Cisco IOS (2612) ===
source-bridge ring-group 512
dlsw local-peer
!
interface Serial0/0
bandwidth 19
no ip address
encapsulation sdlc
load-interval 60
clock rate 19200
sdlc role prim-xid-poll
sdlc vmac 0004.acad.5900
sdlc address C0
sdlc partner 0004.acad.50d5 C0
sdlc line-speed 19200
sdlc simultaneous full-datmode
sdlc dlsw C0
hold-queue 128 out
no shutdown
!
interface TokenRing0/0
[…]
source-bridge 59 1 512

=== Configuration: OS/400 (Fiona) ===
crtctlappc ctld(nibbler) linktype(*sdlc) maxframe(1033) rmtcpname(nibbler) stnadr(c0) nodetype(*calc) tmsgrpnbr(*calc) autodltdev(*no) cmnrcylmt(10 1)

crtlinsdlc lind(sdlclin) rsrcname(lin011) nrzi(*no) linespeed(19200) maxframe(1033) duplex(*full) linkspeed(19200) ctl(nibbler) cmnrcylmt(10 1)

=== Notes ===
* The number in <code>source-bridge ring-group 512</code> is completely arbitrary.
* <code>sdlc vmac</code> is the virtual MAC address Fiona is assigned on the Token Ring. The last byte '''must''' be 00, while IOS sets the last byte to the SDLC station address being given later.
* <code>sdlc address</code> must be the same value as the <code>STNADR</code> parameter in the controller description.
* <code>sdlc partner</code> creates an association from Nibbler’s MAC address on the Token Ring to the SDLC address of Fiona.
* <code>clock rate</code> and <code>sdlc line-speed</code> must match each other, and the <code>LINESPEED</code> parameter of the line description.
* <code>sdlc simultaneous full-datmode</code> corresponds (most likely<ref>There are also ''half-duplex'' and ''full-duplex'' commands to configure an interface which aren't used here.</ref>) to the line description's ''DUPLEX(*FULL)''.
* The <code>source-bridge</code> statement in the physical Token Ring interface assigns the attached ring the number 59, designates it to the source bridge number 1, and bridges traffic to the virtual ring (group) number 512.
* Because auto configuration is enabled, the controller- and device descriptions for Fiona system will be created automatically at the first successful connection attempt to Nibbler.

Unclear:
* How is the serial interface’s traffic redirected to the ring group 512? The group number is referenced globally, and in the Token Ring interface, which hints to the fact that you can’t use this in a complex configuration with more than one ring group, probably?

Proven to work:
* Cisco 2612 with added WIC-1T, and image C2600-BINO3S3, Version 12.3(26)
* Cisco 1601-R, and image C1600-BNR2SY, Version 12.3(26)

=== Initiation, and function verification ===
* On Fiona, vary on line and controller descriptions:
vrycfg cfgobj(sdlclin) cfgtype(*lin) status(*on)
* After a brief pause, the Cisco console should indicate that the serial port goes up:<ref>If you’re connected remotely, make sure you’ve set <code>term moni</code>.</ref>
%LINK-3-UPDOWN: Interface Serial0/0, changed state to up
%LINEPROTO-5-UPDOWN: Line protocol on Interface Serial0/0, changed state to up
* On Fiona, looking into the QSYSOPR-Message Queue should show that the line has successfully been varied on, and a connection to the controller ''NIBBLER'' has been established through SDLCLIN.
* On the Cisco Router, you should see output of <code>show interface ser0/0</code> similar to the following:
Serial0/0 is up, line protocol is up
Hardware is PowerQUICC Serial
MTU 1500 bytes, BW 19 Kbit, DLY 20000 usec,
reliability 255/255, txload 1/255, rxload 1/255
Encapsulation SDLC, loopback not set
Router link station role: PRIMARY (DCE)
Router link station metrics:
slow-poll not configured
T1 (reply time out) 300 milliseconds
N1 (max frame size) 16472 bits
N2 (retry count) 7
poll-pause-timer 10 milliseconds
poll-limit-value 1
k (windowsize) 7
modulo 8
sdlc vmac: 0004.ACAD.59--
sdlc addr C0 state is CONNECT
cls_state is CLS_IN_SESSION
VS 5, VR 6, Remote VR 5, Current retransmit count 0
Hold queue: 0/200 IFRAMEs 1109/1325
TESTs 0/0 XIDs 2258/19, DMs 0/0 FRMRs 0/1
RNRs 1/0 SNRMs 10/0 DISC/RDs 3/1 REJs 0/0
Poll: clear, Poll count: 0, ready for poll, chain: C0/C0
Last input never, output 00:00:00, output hang never
Last clearing of "show interface" counters 1d17h
Input queue: 0/75/0/0 (size/max/drops/flushes); Total output drops: 0
Queueing strategy: fifo
Output queue: 0/128 (size/max)
1 minute input rate 0 bits/sec, 49 packets/sec
1 minute output rate 0 bits/sec, 49 packets/sec
7467200 packets input, 15548792 bytes, 0 no buffer
Received 0 broadcasts, 0 runts, 21 giants, 0 throttles
21 input errors, 0 CRC, 0 frame, 0 overrun, 0 ignored, 0 abort
7468810 packets output, 15116960 bytes, 0 underruns
0 output errors, 0 collisions, 26 interface resets
0 output buffer failures, 0 output buffers swapped out
10 carrier transitions
DCD=up DSR=up DTR=up RTS=up CTS=up
* On the Cisco Router, you should see output of <code>show dlsw local-circuit</code> similar to the following:
key mac-addr sap state port rif
2197187452 0004.acad.59c0 04 CONNECTED Se0/0 --no rif--
PCEP: 82AB8B88 UCEP: 82F66B7C
0004.acad.50d5 04 CONNECTED To0/0 0600.2001.03B0
PCEP: 82F511AC UCEP: 82F66B7C

* On Nibbler, you should see Fiona in <code>wrkappnsts option(*loc)</code><ref>Note that this command doesn't exist in V3.</ref>.

=== Configuration corrections ===
The APPC Controller on Nibbler has been automatically created with default values. This includes <code>maxframe</code> being set to the default for Token Ring, aka 16393 Bytes. This '''will''' result in connection instabilities, if not corrected.
* On Fiona vary off line and controller descriptions (optional):
vrycfg cfgobj(sdlclin) cfgtype(*lin) status(*off)
* On the Token Ring-AS/400 vary off the controller description:
vrycfg cfgobj(fiona) cfgtype(*ctl) status(*off)
* Change configuration to match parameters:
chgctlappc ctld(fiona) maxframe(1033) inlcnn(*ans) nodetype(*calc) autodltdev(*no) cmnrcylmt(10 1) ctlown(*user)
* I suggest to run <code>wrkctld</code> and manually set <code>swtdsc</code> (press F11) to ''*no''. Otherwise, you'll get a log of unneeded messages about torn down connections. It depends on the OS release if this option shows up.
* Vary on configuration objects on both AS/400, starting with Nibbler.
vrycfg cfgobj(fiona) cfgtype(*ctl) status(*on)
vrycfg cfgobj(sdlclin) cfgtype(*lin) status(*on)

You now should be able to enjoy a stable, albeit somewhat slow connection to your incarnation of Fiona, with each and every service running over SNA.

== Scenario 2: Remote SNA APPN connection over SDLC and DLSw ==
[[File:AS400-SDLC-Cisco-DLSw-Ring-AS400.png|frame|center|Network Plan]]

This scenario shows a configuration when connectivity between the two involved AS/400's is limited to TCP/IP, e. g. Ethernet or even WAN/VPN. An additional Router is required, here this is a Cisco 1601-R. This scenario uses DLSw transport for passing traffic between the involved routers. Otherwise, the configuration on Fiona and Nibbler is the same. Hence, this isn't repeated here.

* Pro: Still fairly easy to configure, applicable to other machinery than just AS/400's,
* Con: Maximum speed is still 19200 bps.

The main differences for the Cisco configuration is the establishment of ''Data Link Switching'' (DLSw), because of this, only configuration differences are pointed out.

=== Configuration: Cisco IOS (2612) ===
This one has the IP address 192.168.1.5.
no dlsw local-peer
source-bridge fst-peername 192.168.1.5
source-bridge keepalive 12
source-bridge ring-group 512
dlsw local-peer peer-id 192.168.1.5 lf 1500 keepalive 12 biu-segment
dlsw remote-peer 0 tcp 192.168.1.97

=== Configuration: Cisco IOS (1601-R) ===
This one has the IP address 192.168.1.97.
source-bridge fst-peername 192.168.1.97
source-bridge keepalive 12
source-bridge ring-group 512
dlsw local-peer peer-id 192.168.1.97 lf 1500 keepalive 12 biu-segment
dlsw remote-peer 0 tcp 192.168.1.5

=== Notes ===
The purely router-local ring-group 512 has now been connected through a TCP-Session over DLSw between both involved routers.

If both routers are located in the same L2 segment, one can use FST instead of TCP. I didn't get this to work, most likely because I'm using Ethernet Subinterfaces with Vlan-Tags on my 2612.

Proven to work:
* Cisco 2612 with added WIC-1T, and image C2600-BINO3S3, Version 12.3(26)
* Cisco 1601-R, and image C1600-BNR2SY, Version 12.3(26)

=== Initiation, and function verification ===
Initiation procedure is the same as noted above.

You should see output akin to the following for the <code>show dlsw peers</code> command.
Peers: state pkts_rx pkts_tx type drops ckts TCP uptime
TCP 192.168.1.5 CONNECT 131 131 conf 0 1 0 00:19:47
Total number of connected peers: 1
Total number of connections: 1

=== Configuration corrections ===
Corrections procedure is the same as noted above, if the controller description has been created automatically.

== Scenario 3: Remote SNA APPN connection over X.25 and DLSw ==
[[File:AS400-X25-Cisco-DLSw-Ring-AS400.png|frame|center|Network Plan]]

This scenario builds on the previously established DLSw scenario. The main difference is that instead of SDLC, X.25 is used as transport protocol on the serial link. All other configurations are the same.

* Pro: Maximum speed is 64 kbps, more than three times SDLC,
* Con: More complicated to configure, possibly not applicable to other machinery than just AS/400's

The main differences for the Cisco configuration is the establishment of ''X.25'', because of this, only configuration differences are pointed out.

=== Configuration: Cisco IOS (1601-R) ===
First, you need to reset the serial interface to its default values, to get rid of the SDLC configuration quickly.
default interface Serial0

Next, the new configuration is established.
interface Serial0
description Fiona LIN011
bandwidth 64
no ip address
encapsulation x25 dce
load-interval 60
x25 modulo 128
x25 ltc 100
x25 win 8
x25 wout 8
x25 ips 1024
x25 ops 1024
x25 pvc 1 qllc 0004.acad.59c0
ignore-dcd
clock rate 64000
qllc dlsw pvc 1 vmacaddr 0004.acad.59c0 partner 0004.acad.50d5

=== Configuration: OS/400 (Fiona) ===
crtlinx25 lind(x25line) rsrcname(lin011) lglchle((001 *pvc)) netadr(00000000000000) cnninit(*local) interface(*rs232v24) linespeed(19200) dftpktsize(1024) modulus(128) dftwdwsize(8) linkspeed(64000) cmnrcylmt(10 1)

crtctlappc ctld(nibbler) linktype(*x25) line(x25line) maxframe(1024) rmtcpname(nibbler) exchid(05641700) netlvl(1984) lglchlid(001) nodetype(*calc) tmsgrpnbr(*calc) autodltdev(*no) cmnrcylmt(10 1)

=== Notes ===
* The <code>x25 pvc</code>, and <code>qllc dlsw pvc 1</code> work together to establish a virtual MAC address for the X.25 virtual circuit, and the eventual Token Ring peer.
* You cannot create the line description with the full speed outright due to error CPD26DC (Maximum line speed for RS-232/V.24 is 19200 bps.). Create the line with <code>linespeed(19200)</code>, and subsequently edit the lind again, setting the desired speed of 64 kbps.
* The ''exchid'' of Nibbler can be found by viewing its line description for the Token Ring IOA.

Proven to work:
* Cisco 2612 with added WIC-1T, and image C2600-BINO3S3, Version 12.3(26)
* Cisco 1601-R, and image C1600-BNR2SY, Version 12.3(26)

=== Initiation, and function verification ===
Initiation procedure is the same as noted above.

You should see output akin to the following for the <code>show x25 interface serial0</code> command.
PVC 1, State: D1, Interface: Serial0
Started 00:20:54, last input 00:10:30, output 00:10:31
qllc 0004.acad.59c0
Window size input: 8, output: 8
Packet size input: 1024, output: 1024
PS: 80 PR: 80 ACK: 79 Remote PR: 80 RCNT: 1 RNR: no
P/D state timeouts: 0 timer (secs): 0
data bytes 21173/110662 packets 208/209 Resets 1/0 RNRs 0/0 REJs 0/0 INTs 0/0

You should see output akin to the following for the <code>show qllc serial0</code> command.
Interface Serial0
vc 1
Circuit State P4/D1, Logical Link State QLOpened 0004.acad.59c0(04)->0004.acad.50d5(04)
0 packets held

=== Configuration corrections ===
Corrections procedure is the same as noted for Scenario 1, if the controller description has been created automatically.

== Scenario 3a: IP over X.25 ==
This scenario builds on the previously established X.25 scenario. It adds TCP/IP transport over a secondary X.25 virtual circuit.

* 192.168.1.246 is the IP address for Fiona,
* 192.168.1.245 is the IP address for the Cisco 1601-R.

=== Configuration: Cisco IOS (1601-R) ===
Only parameters to be changed are mentioned.
interface Serial0
ip address 192.168.1.245 255.255.255.252
x25 pvc 2 ip 192.168.1.246

=== Configuration: OS/400 (Fiona) ===
First, you need to add another virtual circuit to the line description. You can't do that remotely, because you must vary off the line.
vrycfg cfgobj(x25lin011) cfgtype(*lin) status(*off)
chglinx25 lind(x25line) lglchle((001 *pvc) (002 *pvc))
vrycfg cfgobj(x25lin011) cfgtype(*lin) status(*on)

Then you can add the according TCP/IP interface configuration.
addtcpifc intnetadr('192.168.1.246') lind(x25line) subnetmask('255.255.255.252') mtu(1024) pvclglchli(002)
addtcprte rtedest(*dftroute) subnetmask(*none) nexthop('192.168.1.245') mtu(1024)
addtcprsi intnetadr('192.168.1.245') pvclglchli(002)

=== Notes ===
Proven to work:
* Cisco 1601-R, and image C1600-BNR2SY, Version 12.3(26)

=== Initiation, and function verification ===
Depending on if you have started TCP/IP before, you need to issue either <code>strtcp</code>, or <code>strtcpifc intnetadr('192.168.1.246')</code>.

You should see output akin to the following for the <code>show x25 interface serial0</code> command.
PVC 1, State: D1, Interface: Serial0
Started 03:07:34, last input 00:09:47, output 00:09:47
qllc 0004.acad.59c0
Window size input: 8, output: 8
Packet size input: 1024, output: 1024
PS: 122 PR: 36 ACK: 35 Remote PR: 122 RCNT: 1 RNR: no
P/D state timeouts: 0 timer (secs): 0
data bytes 2915564/2073274 packets 3733/2832 Resets 3/0 RNRs 0/0 REJs 0/0 INTs 0/0
PVC 2, State: D1, Interface: Serial0
Started 00:22:29, last input 00:18:33, output 00:18:33
Connects <no address> <-> ip 192.168.59.246
Data PID none
Window size input: 8, output: 8
Packet size input: 1024, output: 1024
PS: 29 PR: 24 ACK: 23 Remote PR: 29 RCNT: 1 RNR: no
P/D state timeouts: 0 timer (secs): 0
data bytes 1965/1917 packets 29/24 Resets 0/1 RNRs 0/0 REJs 0/0 INTs 0/0

=== Configuration corrections ===
How to establish routing within your local LAN for the example subnet being described above is not within the scope of this article.

Also, issue <code>go cfgtcp</code>, and check/correct configurations, such as DNS information, services to be started at IPL time, etc.

== See also ==
* [[Serial Cables IDs]]
* [[RS-232 Modem Cable Pinout]]
* [[Integrating LAN-less Machines into a local Token Ring]]
* [[Configuring X.25 link through Cisco IP network]]
* [[Configuring TCP/IP and SLIP with Cisco-Router and V3R2]]
* [[Start TCP/IP at IPL]]

== Weblinks ==
* [https://en.wikipedia.org/wiki/RS-232#Timing_signals RS-232 timing signals], Wikipedia
* [https://www.cisco.com/c/en/us/support/docs/routers/10000-series-routers/46800-cab232mtfc.html#cab-232fc Serial Cable CAB-232FC], Cisco.com
* [https://cfnng.cisco.com/archived-data Cisco Feature Navigator], Cisco.com
* [https://www.cisco.com/c/en/us/td/docs/ios/bridging/configuration/guide/15-s/br-15-s-book/br_dlsw_plus.html#wp1075136 DLSw+ translation between SDLC and Token Ring media example], Cisco.com
* [https://en.wikipedia.org/wiki/RS-232#Timing_signals RS-232 timing signals], Wikipedia
* [https://www.cisco.com/c/en/us/td/docs/ios/bridging/configuration/guide/15SY/br_15_sy_book.html Bridging and IBM Networking Configuration Guide], Cisco IOS Release 15SY
* [https://website.fis.agh.edu.pl/complab/doc/Cisco_IOS_11.0/cbook/cx25.htm Configuring X.25 and LAPB] on Cisco IOS, Faculty of Physics and Applied Computer Science Poland<ref>Very old documentation linked intentionally. Note: The configuration option ''tunnel'' was renamed to ''xot'' in newer IOS releases.</ref>
* [https://public.dhe.ibm.com/systems/power/docs/systemi/v6r1/en_US/sc415405.pdf X.25 Network Support] for OS/400, IBM.com

== Footnotes ==
<references />

== Acknowledgements ==
Thanks to Dave Brown for initial pointers.

[[Category: Hardware Configuration Guide‏]]
[[Category: Software Configuration Guide‏]]

ZuluSCSI

2026-08-25T11:40:00Z

PoC: /* Disk drive support */ Caveat added

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for some tasks.

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named, and are used in alphabetical order.<ref>Either through the ''Eject'' button, or the media menu.</ref>

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code>,
* use the serial console to attach image(s) to the drive.
* ''zuluscsi.ini'':
[SCSI]
System="AS400_PPC"

[SCSI0]
TapeDensity = 0x25

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

This configuration has been tested over the course of multiple weeks:
* Occasional <tt>go save</tt> 21,
* daily differential backups,
* occasional single file restores.

Tested with Firmware 2026-06-12, 9401-150, V4R5.

=== CD drive support ===
* create directory <code>CD0</code>,
* populate with one or more readymade ISO images,
* use the serial console to attach image(s) to the drive.

No special handling for the ID in ''zuluscsi.ini''.

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware CD drive, make sure to delete your old CD device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

Tested with Firmware 2026-08-07, 9401-150, V4R4: IPL only so far.

=== Disk drive support ===
The officially released code base is able to present a singular #6717, 8.5 GiB disk drive to the system, initialize, and install SLIC + base OS/400 + LPPs + PTFs.

* Generate disk image:
dd if=/dev/zero of=HD6.img bs=522 count=17177940 status=progress
* ''zuluscsi.ini'':
[SCSI]
System = AS400_PPC

[SCSI6]
PrefetchBytes = 0

Caveats:
* Writes to the emulated disk are very slow compared to reads.
* One user with a RP2040 reported failure for the disk to be recognized. Prerelease firmware solved the issue.

Fully tested with Firmware 2026-08-21, 9401-150, V4R4.

== Current state ==
We have to differ three hardware generations when considering Zulu vs. AS/400:
{|class="wikitable"
! 
!CISC/IMPI, 520 bytes/block disks
!RISC/SPD, 520/522 bytes/block disks
!RISC/PCI, 522 bytes/block disks
|-
!CD-ROM
|Not supported
|Untested
|Works
|-
!Tape
|Fails, hangs with SRC early.
|Untested
|Works
|-
!Disk
|Fails, hangs with SRC early.
|Untested
|Works
|}

All successful tests so far have been based on a ZuluSCSI wide board, while the CISC tests have been done with a ZuluSCSI Blaster.

== Next ==
These features are completed, partially tested, but did not make it to the official releases yet:
* More disk profiles, loadable in ''zuluscsi.ini'' via external file ''as400_disk_definitions.txt'', so different types than the built-in 522 bytes, 8.5 GiB #6717 can be assigned.
** Shellscript to generate more ''as400_disk_definitions.txt'' entries from real disks connected to a SCSI controller when ran under Linux
** Because of serial numbers currently being hard coded, only one disk per type should be used
* Allowed more memory to accommodate the necessary VPD SCSI pages for multiple disks
* Present captured real tape VPD/SCSI data from IBM SLR5/QIC1000 when using <code>Device = "AS400_PPC"</code> or <code>Device = "AS400_CISC"</code> in an ID stanza
* Created a new build profile for the ZuluSCSI Blaster, removing all the add-on code being unneeded when used with AS/400

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

ZuluSCSI

2026-08-25T10:45:14Z

PoC: Next

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for some tasks.

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named, and are used in alphabetical order.<ref>Either through the ''Eject'' button, or the media menu.</ref>

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code>,
* use the serial console to attach image(s) to the drive.
* ''zuluscsi.ini'':
[SCSI]
System="AS400_PPC"

[SCSI0]
TapeDensity = 0x25

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

This configuration has been tested over the course of multiple weeks:
* Occasional <tt>go save</tt> 21,
* daily differential backups,
* occasional single file restores.

Tested with Firmware 2026-06-12, 9401-150, V4R5.

=== CD drive support ===
* create directory <code>CD0</code>,
* populate with one or more readymade ISO images,
* use the serial console to attach image(s) to the drive.

No special handling for the ID in ''zuluscsi.ini''.

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware CD drive, make sure to delete your old CD device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

Tested with Firmware 2026-08-07, 9401-150, V4R4: IPL only so far.

=== Disk drive support ===
The officially released code base is able to present a singular #6717, 8.5 GiB disk drive to the system, initialize, and install SLIC + base OS/400 + LPPs + PTFs.

* Generate disk image:
dd if=/dev/zero of=HD6.img bs=522 count=17177940 status=progress
* ''zuluscsi.ini'':
[SCSI]
System = AS400_PPC

[SCSI6]
PrefetchBytes = 0

Caveats:
* Writes to the emulated disk are very slow compared to reads.

Fully tested with Firmware 2026-08-21, 9401-150, V4R4.

== Current state ==
We have to differ three hardware generations when considering Zulu vs. AS/400:
{|class="wikitable"
! 
!CISC/IMPI, 520 bytes/block disks
!RISC/SPD, 520/522 bytes/block disks
!RISC/PCI, 522 bytes/block disks
|-
!CD-ROM
|Not supported
|Untested
|Works
|-
!Tape
|Fails, hangs with SRC early.
|Untested
|Works
|-
!Disk
|Fails, hangs with SRC early.
|Untested
|Works
|}

All successful tests so far have been based on a ZuluSCSI wide board, while the CISC tests have been done with a ZuluSCSI Blaster.

== Next ==
These features are completed, partially tested, but did not make it to the official releases yet:
* More disk profiles, loadable in ''zuluscsi.ini'' via external file ''as400_disk_definitions.txt'', so different types than the built-in 522 bytes, 8.5 GiB #6717 can be assigned.
** Shellscript to generate more ''as400_disk_definitions.txt'' entries from real disks connected to a SCSI controller when ran under Linux
** Because of serial numbers currently being hard coded, only one disk per type should be used
* Allowed more memory to accommodate the necessary VPD SCSI pages for multiple disks
* Present captured real tape VPD/SCSI data from IBM SLR5/QIC1000 when using <code>Device = "AS400_PPC"</code> or <code>Device = "AS400_CISC"</code> in an ID stanza
* Created a new build profile for the ZuluSCSI Blaster, removing all the add-on code being unneeded when used with AS/400

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

ZuluSCSI

2026-08-25T10:21:23Z

PoC: /* Examples */ Disk support

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for some tasks.

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named, and are used in alphabetical order.<ref>Either through the ''Eject'' button, or the media menu.</ref>

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code>,
* use the serial console to attach image(s) to the drive.
* ''zuluscsi.ini'':
[SCSI]
System="AS400_PPC"

[SCSI0]
TapeDensity = 0x25

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

This configuration has been tested over the course of multiple weeks:
* Occasional <tt>go save</tt> 21,
* daily differential backups,
* occasional single file restores.

Tested with Firmware 2026-06-12, 9401-150, V4R5.

=== CD drive support ===
* create directory <code>CD0</code>,
* populate with one or more readymade ISO images,
* use the serial console to attach image(s) to the drive.

No special handling for the ID in ''zuluscsi.ini''.

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware CD drive, make sure to delete your old CD device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

Tested with Firmware 2026-08-07, 9401-150, V4R4: IPL only so far.

=== Disk drive support ===
The officially released code base is able to present a singular #6717, 8.5 GiB disk drive to the system, initialize, and install SLIC + base OS/400 + LPPs + PTFs.

* Generate disk image:
dd if=/dev/zero of=HD6.img bs=522 count=17177940 status=progress
* ''zuluscsi.ini'':
[SCSI]
System = AS400_PPC

[SCSI6]
PrefetchBytes = 0

Caveats:
* Writes to the emulated disk are very slow compared to reads.

Fully tested with Firmware 2026-08-21, 9401-150, V4R4.

== Current state ==
We have to differ three hardware generations when considering Zulu vs. AS/400:
{|class="wikitable"
! 
!CISC/IMPI, 520 bytes/block disks
!RISC/SPD, 520/522 bytes/block disks
!RISC/PCI, 522 bytes/block disks
|-
!CD-ROM
|Not supported
|Untested
|Works
|-
!Tape
|Fails, hangs with SRC early.
|Untested
|Works
|-
!Disk
|Fails, hangs with SRC early.
|Untested
|Works
|}

All successful tests so far have been based on a ZuluSCSI wide board, while the CISC tests have been done with a ZuluSCSI Blaster.

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

ZuluSCSI

2026-08-25T10:08:52Z

PoC: /* Current state */ Reworked

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for some tasks.

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named, and are used in alphabetical order.<ref>Either through the ''Eject'' button, or the media menu.</ref>

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code>,
* use the serial console to attach image(s) to the drive.
* ''zuluscsi.ini'':
[SCSI]
System="AS400_PPC"

[SCSI0]
TapeDensity = 0x25

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

This configuration has been tested over the course of multiple weeks:
* Occasional <tt>go save</tt> 21,
* daily differential backups,
* occasional single file restores.

Tested with Firmware 2026-06-12, 9401-150, V4R5.

=== CD drive support ===
* create directory <code>CD0</code>,
* populate with one or more readymade ISO images,
* use the serial console to attach image(s) to the drive.

No special handling for the ID in ''zuluscsi.ini''.

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware CD drive, make sure to delete your old CD device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

Tested with Firmware 2026-08-07, 9401-150, V4R4: IPL only so far.

== Current state ==
We have to differ three hardware generations when considering Zulu vs. AS/400:
{|class="wikitable"
! 
!CISC/IMPI, 520 bytes/block disks
!RISC/SPD, 520/522 bytes/block disks
!RISC/PCI, 522 bytes/block disks
|-
!CD-ROM
|Not supported
|Untested
|Works
|-
!Tape
|Fails, hangs with SRC early.
|Untested
|Works
|-
!Disk
|Fails, hangs with SRC early.
|Untested
|Works
|}

All successful tests so far have been based on a ZuluSCSI wide board, while the CISC tests have been done with a ZuluSCSI Blaster.

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

Post-Install Optimizations

2026-08-22T16:02:13Z

PoC: PTF handling

OS/400 provides a lot of default values for variables (affecting the run-time environment) and program options. Some of these make sense, some of them are kept consistent with earlier versions of the OS because of compatibility reasons by IBM.

Some of these recommendations might not be appropriate for you by various reasons. Don't apply blindly. Know what you do, use the online help to retrieve background information on the topic in question.

The findings below are based on V4R5 with annotated exceptions for newer releases.

== Housekeeping ==
These are settings and scheduled jobs to keep your system uncluttered.

=== Change unneeded programs to not run ===
We most likely don't need to run ''lpd'' and ''smtpd'' to run per default.
CHGLPDA AUTOSTART(*NO)
CHGSMTPA AUTOSTART(*NO)

You can easily check all settings at once by using <code>UPDDTA QUSRSYS/QATOCSTART</code>. These are not needed in general.
* *DIRSRV
* *NETSVR
* *SLP

Depending on OS version, not all entries may be available.

=== Change uninstalled programs to not run ===
If you did not install the Ultimedia package, you can remove the pre started job from the QSYSWRK subsystem description to make it not generate an error message at IPL time.
RMVPJE SBSD(QSYSWRK) PGM(QUMEDIA/QUMBPJTC)

If you did not install the Directory Services package (aka LDAP), you can remove the auto started jobs from the QSYSWRK subsystem description to make them not generate an error message at IPL time.
RMVAJE SBSD(QSYSWRK) JOB(QGLDPUBA)
RMVAJE SBSD(QSYSWRK) JOB(QGLDPUBE)

Both is valid and tested for V4R5. Note that newer releases moved the background jobs to the base OS so there is no error message when starting them. I have not tested if they're required to run, though.

If you did not install the performance tools, you don't need trying to start the performance data collector:
RMVAJE SBSD(QCTL) JOB(QPFRCOL)

I can't remember if the latter is valid for V4R5. It's valid for V3R2, though.

=== Cleanup unneeded stuff ===
These objects come by default at OS install time, are not needed to my knowledge, and thus can be safely deleted:
DLTOUTQ OUTQ(QDKT)
DLTOUTQ OUTQ(QPFROUTQ)
DLTOUTQ OUTQ(QPRINTS)
DLTF FILE(QPRINTS)
DLTOUTQ OUTQ(QPRINT2)
DLTF FILE(QPRINT2)
DLTOUTQ OUTQ(QTPPPOUTQ)
DLTDEVD DEVD(QESPAP)
DLTDEVD DEVD(QIADSP)
DLTDEVD DEVD(QIAPRT)
DLTDEVD DEVD(QQAHOST)
DLTDEVD DEVD(QTIDA)
DLTDEVD DEVD(QTIDA2)
DLTCTLD CTLD(QESCTL)
DLTCTLD CTLD(QTICTL)
DLTLIND LIND(QESLINE)
DLTLIND LIND(QTILINE)

== System Values ==
System values are like environment variables as known from common operating systems. They influence system operation. I recommend the following changes.

=== System Control ===
* Change work environment to separate subsystems for different kind of jobs. This also makes it easy to introduce your own subsystems.
CHGSYSVAL SYSVAL(QCTLSBSD) VALUE('QCTL QSYS')
* Set automatic DST adjustment, and UTC offset. This value is valid for Central Europe (Berlin, Paris, …) '''Note!''' This variable is not available in V4R5. See [[#Weblinks|Weblinks]] below.
CHGSYSVAL SYSVAL(QTIMZON) VALUE('QP0100CET2')
* Adjust time to automatically end disconnected interactive jobs (sessions) to one day.
CHGSYSVAL SYSVAL(QDSCJOBITV) VALUE('1440')

=== (Memory) Allocation ===
* Adjust automatic performance values only at runtime, not at IPL.<ref>If you change the amount of memory for the machine, temporarily adjust the value to '2', make the memory change and then change the value back to '3' — no further IPL needed.</ref> This allows the system to automatically adjust memory allocations and activity levels to minimize paging (disk I/O).
CHGSYSVAL SYSVAL(QPFRADJ) VALUE('3')
* Allow memory pools to self adjust the paging block size depending on jobs running. This is called ''Expert Cache''. You can adjust the maximum active jobs per pool in the <code>WRKSHRPOOL</code> display.<ref>Press <code>F21</code> to switch to view 2 or 3 to have adjustment possibilities.</ref>
CHGSHRPOOL POOL(*BASE) PAGING(*CALC)
CHGSHRPOOL POOL(*INTERACT) PAGING(*CALC)
CHGSHRPOOL POOL(*SPOOL) PAGING(*CALC)
* Reservations for job related data structures at IPL time. See <code>DSPSYSSTS</code> and set to slightly more than the ''Jobs in System'' value to be seen there when the system is working "normal".<ref>Press <code>F21</code> to switch to view 2 or 3 to see the overall job count.</ref>
CHGSYSVAL SYSVAL(QTOTJOB) VALUE(100)
* Reservations for job related data structures at IPL time. See <code>WRKACTJOB</code> and set to slightly more than the ''Active Jobs'' value to be seen there when the system is working "normal".
CHGSYSVAL SYSVAL(QACTJOB) VALUE(95)
* Maximize TCP buffers for maximum performance, especially on faster links.
CHGTCPA TCPRCVBUF(8388608) TCPSNDBUF(8388608)
* Make sure, database tasks can use system resources as needed.
CHGSYSVAL SYSVAL(QQRYDEGREE) VALUE(*OPTIMIZE)
* When interactive jobs require more CPU time than being allowed by default (2 seconds),<ref>This is set in *CLS objects.</ref> to finish a block of processing, allow that memory to be taken from the *BASE pool. Advantage: The QINTER subsystem pool will not be subject to auto adjustment because of jobs which are supposed to run in batch.
CHGSYSVAL SYSVAL(QTSEPOOL) VALUE(*BASE)

=== Message-and-Logging ===
* Allow immediate deletion of problem reports.
CHGSYSVAL SYSVAL(QPRBHLDITV) VALUE(0)
* Do not log software errors. We can't do much about these anyway, seen from a hobbyist viewpoint.
CHGSYSVAL SYSVAL(QSFWERRLOG) VALUE(*NOLOG)
* Maximize Central Syslog (viewable with <code>DSPLOG</code> size to lessen rotation frequency. Depending on OS version only ''VALUE(32767)'' may be valid.
CHGSYSVAL SYSVAL(QHSTLOGSIZ) VALUE(*DAILY)
* Raise allowed unsuccessful sign on tries before taking action.
CHGSYSVAL SYSVAL(QMAXSIGN) VALUE('15')
* Minimize logging for sessions disconnected beause of device errors.
CHGSYSVAL SYSVAL(QDEVRCYACN) VALUE(*ENDJOBNOLIST)

=== Security System Values ===
* Unrestrict automatic creation of system objects triggered by external (network) requests.
CHGSYSVAL SYSVAL(QAUTOVRT) VALUE(*NOMAX)
* Allow restore with all security relevant flags.
CHGSYSVAL SYSVAL(QALWOBJRST) VALUE(*ALL)
* For TCP connections to work, we need encrypted passwords.
CHGDDMTCPA PWDRQD(*ENCRYPTED)
* Allow ''QSYSOPR'' signon to all devices.
CHGSYSVAL SYSVAL(QLMTSECOFR) VALUE('0')
* Raise maximum password length to maximum value.<ref>In newer OS versions, an additional variable ''QPWDLVL'' allows even longer passwords.</ref>
CHGSYSVAL SYSVAL(QPWDMAXLEN) VALUE(10)
* Raise minimum passsword length for security reasons.
CHGSYSVAL SYSVAL(QPWDMINLEN) VALUE(8)

=== Misc ===
* PTF install shall be done on unattended IPL time, and don't try to report problems to IBM directly.<ref>Needs prior setup for ''Electronic Customer Support''.</ref>
CHGSRVA PTFINSTYP(*DLYALL) RPTPRBAUTO(*NO)
* Provide European style formatting.
CHGSYSVAL SYSVAL(QCURSYM) VALUE('€')
CHGSYSVAL SYSVAL(QDECFMT) VALUE('J')
CHGSYSVAL SYSVAL(QSRTSEQ) VALUE(*LANGIDUNQ)<ref>This value isn't available with V4R5. You can use ''*LANGIDSHR'' there.</ref>
CHGSYSVAL SYSVAL(QDATFMT) VALUE('DMY')<ref>Default value for 2924 (US English) is MDY.</ref>
* Allow background compiling in PDM as ordinary user, and submitting batch jobs in general.
GRTOBJAUT OBJ(QGPL/QBATCH) OBJTYPE(*JOBD) USER(*PUBLIC) AUT(*USE)
* Tweaking automatic cleanup (like ''logrotate'').
CHGCLNUP ALWCLNUP(*YES) STRTIME('02:22:22') USRMSG(7) SYSMSG(3) SYSPRT(7) SYSLOG(14) CALITM(*KEEP)
* Change general SNA networking attributes. This is one '''long''' line. Take care to get it completely.
CHGNETA JOBACN(*SEARCH) VRTAUTODEV(254) MDMCNTRYID(DE)

=== Charset Conversion ===
In addition, OS/400 has a default value of 65535 for <code>QCCSID</code>. It should be set to a value being dependent on the installed language, to enable automatic translation of data on disk to the display device, and back. For Germany, the correct value is 273, and for US, it's 37. A good hint is to check your 5250 emulator program for possible values.

== IPL Customization ==
With this procedure, the current startup program for the OS can be retrieved for easy customization.
RTVCLSRC PGM(QSTRUP) SRCFILE(QCLSRC)
WRKMBRPDM FILE(QCLSRC) MBR(QSTRUP) MBRTYPE(CLP)
CRTCLPGM PGM(QGPL/QSTRUP)

To activate your changes, run <code>WRKSYSVAL SYSVAL(QSTRUPPGM)</code> and change the values to reflect the new program object in QGPL. '''Note''': On a used system's install, the previous owner might have already done a customized QSTRUP. See <code>DSPSYSVAL QSTRUPPGM</code> which one is the currently set startup program before accidentally overwriting!

Notable use cases for changing <code>QSTRUP</code> would be to make SNA Distribution Services, and TCP/IP (on older releases than V4R5) start at IPL time.

New entries must be located after the ''IF COND'' statement and ''DONE:'' label. Always put a ''MONMSG MSGID(CPF0000)'' after each statement. Failing to do so will not ignore any errors but make the IPL script terminate abnormally in case of an error and possibly leave you with an inaccessible system.

Examples:
* Start TCP/IP:
QSYS/STRTCP
MONMSG MSGID(CPF0000)
<blockquote>'''Note:''' TCP/IP on V4R5 and later is by IBM provided default automatically started with an appropriate autostart entry <code>struptcpip</code> in the <code>qsyswrk</code> subsystem description. No action is necessary in the startup CL!</blockquote>

* Start SNADS:
QSYS/STRSBS SBSD(QSNADS)
MONMSG MSGID(CPF0000)

== Change Program Defaults ==
This establishes different default behavior of some programs which makes life somewhat easier.<ref>Some people highly oppose against changing default values because the default values have been provided for a reason. But then, the <code>CHGCMDDFT</code> also has been provided for a reason.</ref> At least noting down the changed programs and their former values is recommended, for example in <code>QGPL/QTXTSRC.CMDDFT</code>.
<blockquote>'''Note:''' CL applications might run a command with the changed default values, in turn combining (new) defaults and submitted parameters into an invalid combination of parameters which might lead to run-time errors. As far as I'm aware, my proposed changes are compatible with such situations.</blockquote>

* File creation and change defaults:
** Enforce immediate return to program error handling instead of make programs seem to hang (<code>wait…</code>),
** Enforce reusing deleted record space,<ref>If there is no access path defined, sequentially read records are no longer guaranteed to *be in timely order (FIFO)!</ref>
** Remove sizing restrictions,<ref>A runaway process filling the disks to 100 % is not stopped prior!</ref>
** Use a smaller access path size for probably increased performance,
** Allow automatic LF rebuild when running <code>chgpf</code>.
CHGCMDDFT CMD(CRTPF) NEWDFT('SIZE(*NOMAX *N *N) WAITFILE(*IMMED) WAITRCD(*IMMED) REUSEDLT(*YES)')
CHGCMDDFT CMD(CRTSRCPF) NEWDFT('SIZE(*NOMAX *N *N) ACCPTHSIZ(*MAX4GB)')
CHGCMDDFT CMD(CHGPF) NEWDFT('DLTDEPLF(*YES) SIZE(*NOMAX *N *N) WAITFILE(*IMMED) WAITRCD(*IMMED) REUSEDLT(*YES)')
CHGCMDDFT CMD(CRTLF) NEWDFT('WAITFILE(*IMMED) WAITRCD(*IMMED) ACCPTHSIZ(*MAX4GB)')
CHGCMDDFT CMD(CHGLF) NEWDFT('WAITFILE(*IMMED) WAITRCD(*IMMED) ACCPTHSIZ(*MAX4GB)')
* Menus usually go into the library with the application's other objects. Change current library to there, so applications can find their objects.<ref>It might be beneficial to individually use <code>CURLIB(*NOCHG)</code> for higher level menu objects being put into libraries which are part of the default library search list (''*LIBL'') — such as ''QGPL'' — to not needlessly change the default library in a for some users unexpected way.</ref>
CHGCMDDFT CMD(CRTMNU) NEWDFT('CURLIB(*MNULIB)')
* No unnecessary wait for power down. <code>CONFIRM(*NO)</code> can be added for newer releases to suppress prompting.
CHGCMDDFT CMD(PWRDWNSYS) NEWDFT('OPTION(*IMMED) ENDSBSOPT(*NOJOBLOG)')
* Don't waste time displaying a not so very much interesting screen prior to connection.
CHGCMDDFT CMD(STRPASTHR) NEWDFT('PASTHRSCN(*NO)')

Be aware that reinstalls, or applying PTFs can overwrite command objects and thus their changed default values. Also note, hat installing a secondary language on a system also installs a separate set of <code>*cmd</code> objects for that language. You may want to apply the defaults with qualified object names to these, too.

== Regular Cleanup jobs ==
See job comment TEXT for details. These are '''long''' lines. Take care to get it completely.
ADDJOBSCDE JOB(PRGPRB) CMD(DLTPRB STATUS(*CLOSED)) FRQ(*WEEKLY) SCDDATE(*NONE) SCDDAY(*ALL) SCDTIME('13:22:00') MSGQ(*LIBL/QSYSOPR) TEXT('Purge closed and deletable problem entries')
ADDJOBSCDE JOB(RCLTMPSTG) CMD(RCLTMPSTG DAYS(30)) FRQ(*MONTHLY) SCDDATE(*MONTHSTR) SCDDAY(*NONE) SCDTIME('13:24:00') MSGQ(*LIBL/QSYSOPR) TEXT('Reclaim temporary storage')
ADDJOBSCDE JOB(RTVDSKINF) CMD(RTVDSKINF) FRQ(*MONTHLY) SCDDATE(*MONTHSTR) SCDDAY(*NONE) SCDTIME('13:34:00') MSGQ(*LIBL/QSYSOPR) TEXT('Retrieve disk space stats')
ADDJOBSCDE JOB(QPGMRCLR) CMD(CLRMSGQ MSGQ(QPGMR) CLEAR(*KEEPUNANS)) FRQ(*WEEKLY) SCDDATE(*NONE) SCDDAY(*ALL) SCDTIME('07:07:07') RCYACN(*NOSBM) MSGQ(*NONE) TEXT('Delete uninteresting messages')

== PTF handling ==
To save space on disk and backup media, you may want to consider applying all PTFs permanently. You cannot remove them afterwards, but that largely doesn't really matter for older and hobbyist systems.

From a console, first run an `ENDSYS (*IMMED)` to get the system into restricted, state. Then run
APYPTF LICPGM(*ALL) SELECT(*ALL) APY(*PERM) DELAYED(*YES) IPLAPY(*YES)

This will apply all PTFs permanently upon next normal IPL. Note you should IPL from the A-side to allow changes to the B side being made.

A final IPL to the B side gets you the fully PTF'd system.

== Re-Enable InfoSeeker ==
Only necessary for newer V4R4 and newer. If the command isn't known, don't bother: Then your release is so new that it's gone entirely.

See also: [[Reviving InfoSeeker]]

CRTDTAARA DTAARA(QUSRSYS/QBMGINFSKR) TYPE(*CHAR) LEN(8)<ref>Works in V4R5. The <code>STRINFSKR</code> command is not included anymore in IBM i 7.1, and probably earlier releases.</ref>

== Additional Steps tested with V7R2 ==
After trying to enter SST, one gets the message that the password has expired. But the password cannot be changed. Re-IPL '''in manual mode''', do not IPL but enter DST, and change password as directed.

* Choose ''5. Work with DST environment'' and ''3. Service tools user IDs''.
** Disable the "backdoor" profile ''11111111'',
** ''Change password'' for ''QSECOFR'', ''Set password to expired'' to ''2=No''.
* Press F12 and choose ''6. Service tools security data''.
** Enter 0 into the field ''8. Password expiration interval in days'', 8 into the ''Selection'' field, and press return.
** Enter a high number (like 12) into the field ''9. Maximum sign-on attempts allowed'', 9 into the ''Selection'' field, and press return.
** Enter 0 into the field ''10. Duplicate password control'', 10 into the ''Selection'' field, and press return.

Now exit DST.

You may choose to enter SST, enter 7 for ''Work with system security'', and set ''Allow a service tools user ID with a default and expired password to change its own password'' to ''1=Yes''. Since we changed password expiry to ''never'', this step is entirely optional.

== See also ==
* [[Change Command Defaults for File-Commands]]
* [[How to properly shut down your AS/400]]

== Weblinks ==
* [https://archive.midrange.com/midrange-l/199912/msg01738.html STRINFSKR], Midrange Mailing-List
* [https://github.com/PoC-dev/as400-autodst as400-autodst], GitHub

== Footnotes ==
<references />

[[Category: System Administration]]

Post-Install Optimizations

2026-08-22T14:29:41Z

PoC: /* Housekeeping */ Short cut

OS/400 provides a lot of default values for variables (affecting the run-time environment) and program options. Some of these make sense, some of them are kept consistent with earlier versions of the OS because of compatibility reasons by IBM.

Some of these recommendations might not be appropriate for you by various reasons. Don't apply blindly. Know what you do, use the online help to retrieve background information on the topic in question.

The findings below are based on V4R5 with annotated exceptions for newer releases.

== Housekeeping ==
These are settings and scheduled jobs to keep your system uncluttered.

=== Change unneeded programs to not run ===
We most likely don't need to run ''lpd'' and ''smtpd'' to run per default.
CHGLPDA AUTOSTART(*NO)
CHGSMTPA AUTOSTART(*NO)

You can easily check all settings at once by using <code>UPDDTA QUSRSYS/QATOCSTART</code>. These are not needed in general.
* *DIRSRV
* *NETSVR
* *SLP

Depending on OS version, not all entries may be available.

=== Change uninstalled programs to not run ===
If you did not install the Ultimedia package, you can remove the pre started job from the QSYSWRK subsystem description to make it not generate an error message at IPL time.
RMVPJE SBSD(QSYSWRK) PGM(QUMEDIA/QUMBPJTC)

If you did not install the Directory Services package (aka LDAP), you can remove the auto started jobs from the QSYSWRK subsystem description to make them not generate an error message at IPL time.
RMVAJE SBSD(QSYSWRK) JOB(QGLDPUBA)
RMVAJE SBSD(QSYSWRK) JOB(QGLDPUBE)

Both is valid and tested for V4R5. Note that newer releases moved the background jobs to the base OS so there is no error message when starting them. I have not tested if they're required to run, though.

If you did not install the performance tools, you don't need trying to start the performance data collector:
RMVAJE SBSD(QCTL) JOB(QPFRCOL)

I can't remember if the latter is valid for V4R5. It's valid for V3R2, though.

=== Cleanup unneeded stuff ===
These objects come by default at OS install time, are not needed to my knowledge, and thus can be safely deleted:
DLTOUTQ OUTQ(QDKT)
DLTOUTQ OUTQ(QPFROUTQ)
DLTOUTQ OUTQ(QPRINTS)
DLTF FILE(QPRINTS)
DLTOUTQ OUTQ(QPRINT2)
DLTF FILE(QPRINT2)
DLTOUTQ OUTQ(QTPPPOUTQ)
DLTDEVD DEVD(QESPAP)
DLTDEVD DEVD(QIADSP)
DLTDEVD DEVD(QIAPRT)
DLTDEVD DEVD(QQAHOST)
DLTDEVD DEVD(QTIDA)
DLTDEVD DEVD(QTIDA2)
DLTCTLD CTLD(QESCTL)
DLTCTLD CTLD(QTICTL)
DLTLIND LIND(QESLINE)
DLTLIND LIND(QTILINE)

== System Values ==
System values are like environment variables as known from common operating systems. They influence system operation. I recommend the following changes.

=== System Control ===
* Change work environment to separate subsystems for different kind of jobs. This also makes it easy to introduce your own subsystems.
CHGSYSVAL SYSVAL(QCTLSBSD) VALUE('QCTL QSYS')
* Set automatic DST adjustment, and UTC offset. This value is valid for Central Europe (Berlin, Paris, …) '''Note!''' This variable is not available in V4R5. See [[#Weblinks|Weblinks]] below.
CHGSYSVAL SYSVAL(QTIMZON) VALUE('QP0100CET2')
* Adjust time to automatically end disconnected interactive jobs (sessions) to one day.
CHGSYSVAL SYSVAL(QDSCJOBITV) VALUE('1440')

=== (Memory) Allocation ===
* Adjust automatic performance values only at runtime, not at IPL.<ref>If you change the amount of memory for the machine, temporarily adjust the value to '2', make the memory change and then change the value back to '3' — no further IPL needed.</ref> This allows the system to automatically adjust memory allocations and activity levels to minimize paging (disk I/O).
CHGSYSVAL SYSVAL(QPFRADJ) VALUE('3')
* Allow memory pools to self adjust the paging block size depending on jobs running. This is called ''Expert Cache''. You can adjust the maximum active jobs per pool in the <code>WRKSHRPOOL</code> display.<ref>Press <code>F21</code> to switch to view 2 or 3 to have adjustment possibilities.</ref>
CHGSHRPOOL POOL(*BASE) PAGING(*CALC)
CHGSHRPOOL POOL(*INTERACT) PAGING(*CALC)
CHGSHRPOOL POOL(*SPOOL) PAGING(*CALC)
* Reservations for job related data structures at IPL time. See <code>DSPSYSSTS</code> and set to slightly more than the ''Jobs in System'' value to be seen there when the system is working "normal".<ref>Press <code>F21</code> to switch to view 2 or 3 to see the overall job count.</ref>
CHGSYSVAL SYSVAL(QTOTJOB) VALUE(100)
* Reservations for job related data structures at IPL time. See <code>WRKACTJOB</code> and set to slightly more than the ''Active Jobs'' value to be seen there when the system is working "normal".
CHGSYSVAL SYSVAL(QACTJOB) VALUE(95)
* Maximize TCP buffers for maximum performance, especially on faster links.
CHGTCPA TCPRCVBUF(8388608) TCPSNDBUF(8388608)
* Make sure, database tasks can use system resources as needed.
CHGSYSVAL SYSVAL(QQRYDEGREE) VALUE(*OPTIMIZE)
* When interactive jobs require more CPU time than being allowed by default (2 seconds),<ref>This is set in *CLS objects.</ref> to finish a block of processing, allow that memory to be taken from the *BASE pool. Advantage: The QINTER subsystem pool will not be subject to auto adjustment because of jobs which are supposed to run in batch.
CHGSYSVAL SYSVAL(QTSEPOOL) VALUE(*BASE)

=== Message-and-Logging ===
* Allow immediate deletion of problem reports.
CHGSYSVAL SYSVAL(QPRBHLDITV) VALUE(0)
* Do not log software errors. We can't do much about these anyway, seen from a hobbyist viewpoint.
CHGSYSVAL SYSVAL(QSFWERRLOG) VALUE(*NOLOG)
* Maximize Central Syslog (viewable with <code>DSPLOG</code> size to lessen rotation frequency. Depending on OS version only ''VALUE(32767)'' may be valid.
CHGSYSVAL SYSVAL(QHSTLOGSIZ) VALUE(*DAILY)
* Raise allowed unsuccessful sign on tries before taking action.
CHGSYSVAL SYSVAL(QMAXSIGN) VALUE('15')
* Minimize logging for sessions disconnected beause of device errors.
CHGSYSVAL SYSVAL(QDEVRCYACN) VALUE(*ENDJOBNOLIST)

=== Security System Values ===
* Unrestrict automatic creation of system objects triggered by external (network) requests.
CHGSYSVAL SYSVAL(QAUTOVRT) VALUE(*NOMAX)
* Allow restore with all security relevant flags.
CHGSYSVAL SYSVAL(QALWOBJRST) VALUE(*ALL)
* For TCP connections to work, we need encrypted passwords.
CHGDDMTCPA PWDRQD(*ENCRYPTED)
* Allow ''QSYSOPR'' signon to all devices.
CHGSYSVAL SYSVAL(QLMTSECOFR) VALUE('0')
* Raise maximum password length to maximum value.<ref>In newer OS versions, an additional variable ''QPWDLVL'' allows even longer passwords.</ref>
CHGSYSVAL SYSVAL(QPWDMAXLEN) VALUE(10)
* Raise minimum passsword length for security reasons.
CHGSYSVAL SYSVAL(QPWDMINLEN) VALUE(8)

=== Misc ===
* PTF install shall be done on unattended IPL time, and don't try to report problems to IBM directly.<ref>Needs prior setup for ''Electronic Customer Support''.</ref>
CHGSRVA PTFINSTYP(*DLYALL) RPTPRBAUTO(*NO)
* Provide European style formatting.
CHGSYSVAL SYSVAL(QCURSYM) VALUE('€')
CHGSYSVAL SYSVAL(QDECFMT) VALUE('J')
CHGSYSVAL SYSVAL(QSRTSEQ) VALUE(*LANGIDUNQ)<ref>This value isn't available with V4R5. You can use ''*LANGIDSHR'' there.</ref>
CHGSYSVAL SYSVAL(QDATFMT) VALUE('DMY')<ref>Default value for 2924 (US English) is MDY.</ref>
* Allow background compiling in PDM as ordinary user, and submitting batch jobs in general.
GRTOBJAUT OBJ(QGPL/QBATCH) OBJTYPE(*JOBD) USER(*PUBLIC) AUT(*USE)
* Tweaking automatic cleanup (like ''logrotate'').
CHGCLNUP ALWCLNUP(*YES) STRTIME('02:22:22') USRMSG(7) SYSMSG(3) SYSPRT(7) SYSLOG(14) CALITM(*KEEP)
* Change general SNA networking attributes. This is one '''long''' line. Take care to get it completely.
CHGNETA JOBACN(*SEARCH) VRTAUTODEV(254) MDMCNTRYID(DE)

=== Charset Conversion ===
In addition, OS/400 has a default value of 65535 for <code>QCCSID</code>. It should be set to a value being dependent on the installed language, to enable automatic translation of data on disk to the display device, and back. For Germany, the correct value is 273, and for US, it's 37. A good hint is to check your 5250 emulator program for possible values.

== IPL Customization ==
With this procedure, the current startup program for the OS can be retrieved for easy customization.
RTVCLSRC PGM(QSTRUP) SRCFILE(QCLSRC)
WRKMBRPDM FILE(QCLSRC) MBR(QSTRUP) MBRTYPE(CLP)
CRTCLPGM PGM(QGPL/QSTRUP)

To activate your changes, run <code>WRKSYSVAL SYSVAL(QSTRUPPGM)</code> and change the values to reflect the new program object in QGPL. '''Note''': On a used system's install, the previous owner might have already done a customized QSTRUP. See <code>DSPSYSVAL QSTRUPPGM</code> which one is the currently set startup program before accidentally overwriting!

Notable use cases for changing <code>QSTRUP</code> would be to make SNA Distribution Services, and TCP/IP (on older releases than V4R5) start at IPL time.

New entries must be located after the ''IF COND'' statement and ''DONE:'' label. Always put a ''MONMSG MSGID(CPF0000)'' after each statement. Failing to do so will not ignore any errors but make the IPL script terminate abnormally in case of an error and possibly leave you with an inaccessible system.

Examples:
* Start TCP/IP:
QSYS/STRTCP
MONMSG MSGID(CPF0000)
<blockquote>'''Note:''' TCP/IP on V4R5 and later is by IBM provided default automatically started with an appropriate autostart entry <code>struptcpip</code> in the <code>qsyswrk</code> subsystem description. No action is necessary in the startup CL!</blockquote>

* Start SNADS:
QSYS/STRSBS SBSD(QSNADS)
MONMSG MSGID(CPF0000)

== Change Program Defaults ==
This establishes different default behavior of some programs which makes life somewhat easier.<ref>Some people highly oppose against changing default values because the default values have been provided for a reason. But then, the <code>CHGCMDDFT</code> also has been provided for a reason.</ref> At least noting down the changed programs and their former values is recommended, for example in <code>QGPL/QTXTSRC.CMDDFT</code>.
<blockquote>'''Note:''' CL applications might run a command with the changed default values, in turn combining (new) defaults and submitted parameters into an invalid combination of parameters which might lead to run-time errors. As far as I'm aware, my proposed changes are compatible with such situations.</blockquote>

* File creation and change defaults:
** Enforce immediate return to program error handling instead of make programs seem to hang (<code>wait…</code>),
** Enforce reusing deleted record space,<ref>If there is no access path defined, sequentially read records are no longer guaranteed to *be in timely order (FIFO)!</ref>
** Remove sizing restrictions,<ref>A runaway process filling the disks to 100 % is not stopped prior!</ref>
** Use a smaller access path size for probably increased performance,
** Allow automatic LF rebuild when running <code>chgpf</code>.
CHGCMDDFT CMD(CRTPF) NEWDFT('SIZE(*NOMAX *N *N) WAITFILE(*IMMED) WAITRCD(*IMMED) REUSEDLT(*YES)')
CHGCMDDFT CMD(CRTSRCPF) NEWDFT('SIZE(*NOMAX *N *N) ACCPTHSIZ(*MAX4GB)')
CHGCMDDFT CMD(CHGPF) NEWDFT('DLTDEPLF(*YES) SIZE(*NOMAX *N *N) WAITFILE(*IMMED) WAITRCD(*IMMED) REUSEDLT(*YES)')
CHGCMDDFT CMD(CRTLF) NEWDFT('WAITFILE(*IMMED) WAITRCD(*IMMED) ACCPTHSIZ(*MAX4GB)')
CHGCMDDFT CMD(CHGLF) NEWDFT('WAITFILE(*IMMED) WAITRCD(*IMMED) ACCPTHSIZ(*MAX4GB)')
* Menus usually go into the library with the application's other objects. Change current library to there, so applications can find their objects.<ref>It might be beneficial to individually use <code>CURLIB(*NOCHG)</code> for higher level menu objects being put into libraries which are part of the default library search list (''*LIBL'') — such as ''QGPL'' — to not needlessly change the default library in a for some users unexpected way.</ref>
CHGCMDDFT CMD(CRTMNU) NEWDFT('CURLIB(*MNULIB)')
* No unnecessary wait for power down. <code>CONFIRM(*NO)</code> can be added for newer releases to suppress prompting.
CHGCMDDFT CMD(PWRDWNSYS) NEWDFT('OPTION(*IMMED) ENDSBSOPT(*NOJOBLOG)')
* Don't waste time displaying a not so very much interesting screen prior to connection.
CHGCMDDFT CMD(STRPASTHR) NEWDFT('PASTHRSCN(*NO)')

Be aware that reinstalls, or applying PTFs can overwrite command objects and thus their changed default values. Also note, hat installing a secondary language on a system also installs a separate set of <code>*cmd</code> objects for that language. You may want to apply the defaults with qualified object names to these, too.

== Regular Cleanup jobs ==
See job comment TEXT for details. These are '''long''' lines. Take care to get it completely.
ADDJOBSCDE JOB(PRGPRB) CMD(DLTPRB STATUS(*CLOSED)) FRQ(*WEEKLY) SCDDATE(*NONE) SCDDAY(*ALL) SCDTIME('13:22:00') MSGQ(*LIBL/QSYSOPR) TEXT('Purge closed and deletable problem entries')
ADDJOBSCDE JOB(RCLTMPSTG) CMD(RCLTMPSTG DAYS(30)) FRQ(*MONTHLY) SCDDATE(*MONTHSTR) SCDDAY(*NONE) SCDTIME('13:24:00') MSGQ(*LIBL/QSYSOPR) TEXT('Reclaim temporary storage')
ADDJOBSCDE JOB(RTVDSKINF) CMD(RTVDSKINF) FRQ(*MONTHLY) SCDDATE(*MONTHSTR) SCDDAY(*NONE) SCDTIME('13:34:00') MSGQ(*LIBL/QSYSOPR) TEXT('Retrieve disk space stats')
ADDJOBSCDE JOB(QPGMRCLR) CMD(CLRMSGQ MSGQ(QPGMR) CLEAR(*KEEPUNANS)) FRQ(*WEEKLY) SCDDATE(*NONE) SCDDAY(*ALL) SCDTIME('07:07:07') RCYACN(*NOSBM) MSGQ(*NONE) TEXT('Delete uninteresting messages')

== Re-Enable InfoSeeker ==
Only necessary for newer V4R4 and newer. If the command isn't known, don't bother: Then your release is so new that it's gone entirely.

See also: [[Reviving InfoSeeker]]

CRTDTAARA DTAARA(QUSRSYS/QBMGINFSKR) TYPE(*CHAR) LEN(8)<ref>Works in V4R5. The <code>STRINFSKR</code> command is not included anymore in IBM i 7.1, and probably earlier releases.</ref>

== Additional Steps tested with V7R2 ==
After trying to enter SST, one gets the message that the password has expired. But the password cannot be changed. Re-IPL '''in manual mode''', do not IPL but enter DST, and change password as directed.

* Choose ''5. Work with DST environment'' and ''3. Service tools user IDs''.
** Disable the "backdoor" profile ''11111111'',
** ''Change password'' for ''QSECOFR'', ''Set password to expired'' to ''2=No''.
* Press F12 and choose ''6. Service tools security data''.
** Enter 0 into the field ''8. Password expiration interval in days'', 8 into the ''Selection'' field, and press return.
** Enter a high number (like 12) into the field ''9. Maximum sign-on attempts allowed'', 9 into the ''Selection'' field, and press return.
** Enter 0 into the field ''10. Duplicate password control'', 10 into the ''Selection'' field, and press return.

Now exit DST.

You may choose to enter SST, enter 7 for ''Work with system security'', and set ''Allow a service tools user ID with a default and expired password to change its own password'' to ''1=Yes''. Since we changed password expiry to ''never'', this step is entirely optional.

== See also ==
* [[Change Command Defaults for File-Commands]]
* [[How to properly shut down your AS/400]]

== Weblinks ==
* [https://archive.midrange.com/midrange-l/199912/msg01738.html STRINFSKR], Midrange Mailing-List
* [https://github.com/PoC-dev/as400-autodst as400-autodst], GitHub

== Footnotes ==
<references />

[[Category: System Administration]]

System Internals:SLIC DASD device recognition

2026-08-21T14:09:55Z

PoC: Removed erroneous information

ZuluSCSI

2026-08-17T19:00:23Z

PoC: +CD

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for some tasks.

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named, and are used in alphabetical order.<ref>Either through the ''Eject'' button, or the media menu.</ref>

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code>,
* use the serial console to attach image(s) to the drive.
* ''zuluscsi.ini'':
[SCSI]
System="AS400_PPC"

[SCSI0]
TapeDensity = 0x25

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

This configuration has been tested over the course of multiple weeks:
* Occasional <tt>go save</tt> 21,
* daily differential backups,
* occasional single file restores.

Tested with Firmware 2026-06-12, 9401-150, V4R5.

=== CD drive support ===
* create directory <code>CD0</code>,
* populate with one or more readymade ISO images,
* use the serial console to attach image(s) to the drive.

No special handling for the ID in ''zuluscsi.ini''.

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware CD drive, make sure to delete your old CD device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

Tested with Firmware 2026-08-07, 9401-150, V4R4: IPL only so far.

== Current state ==
In the scope of AS/400's, ZuluSCSI's disk support is still incomplete, while CD- and tape emulation are seemingly solid. Some progress has been made, but there are still some rough edges, normally leading to crash of the Operating System with a given ''System Reference Code''.

At the moment, the firmware supports only a single AS/400 specific DASD device type for PPC-AS (522 Bytes per sector).

=== Reports ===
* 2026-08-16, mikerm, 9406-170, Zulu firmware 2026-08-07. Trying to install V4R4 on the Zulu emulated DASD. Disk was created with <code>dd if=/dev/zero of=HD6.img bs=522 count=17177940 status=progress</code><ref>Per directions of one of the firmware developers.</ref>
** First try, ''prefetch'' setting at default (8k): halts at <code>B1934505</code> after IPL takes place from DASD
** Second try, ''prefetch'' set to 0: <code>B6080801</code> after IPL takes place from DASD. More progress, and much quicker LIC install, though.
** Configuration file used:
[SCSI]
LogModeData = 1
System = AS400_BS522

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

ZuluSCSI

2026-08-16T21:28:06Z

PoC: /* Hardware overview */ finished sentence

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for some tasks.

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named, and are used in alphabetical order.<ref>Either through the ''Eject'' button, or the media menu.</ref>

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code>,
* use the serial console to attach image(s) to the drive.
* ''zuluscsi.ini'':
[SCSI]
System="AS400_PPC"

[SCSI0]
TapeDensity = 0x25

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

This configuration has been tested on a 9401-150 running V4R5 over the course of multiple weeks:
* Occasional <tt>go save</tt> 21,
* daily differential backups,
* occasional single file restores.

== Current state ==
In the scope of AS/400's, ZuluSCSI's disk support is still incomplete, while CD- and tape emulation are seemingly solid. Some progress has been made, but there are still some rough edges, normally leading to crash of the Operating System with a given ''System Reference Code''.

At the moment, the firmware supports only a single AS/400 specific DASD device type for PPC-AS (522 Bytes per sector).

=== Reports ===
* 2026-08-16, mikerm, 9406-170, Zulu firmware 2026-08-07. Trying to install V4R4 on the Zulu emulated DASD. Disk was created with <code>dd if=/dev/zero of=HD6.img bs=522 count=17177940 status=progress</code><ref>Per directions of one of the firmware developers.</ref>
** First try, ''prefetch'' setting at default (8k): halts at <code>B1934505</code> after IPL takes place from DASD
** Second try, ''prefetch'' set to 0: <code>B6080801</code> after IPL takes place from DASD. More progress, and much quicker LIC install, though.
** Configuration file used:
[SCSI]
LogModeData = 1
System = AS400_BS522

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

ZuluSCSI

2026-08-16T21:26:21Z

PoC: /* Examples */ typo

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named, and are used in alphabetical order.<ref>Either through the ''Eject'' button, or the media menu.</ref>

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</code>,
* use the serial console to attach image(s) to the drive.
* ''zuluscsi.ini'':
[SCSI]
System="AS400_PPC"

[SCSI0]
TapeDensity = 0x25

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

This configuration has been tested on a 9401-150 running V4R5 over the course of multiple weeks:
* Occasional <tt>go save</tt> 21,
* daily differential backups,
* occasional single file restores.

== Current state ==
In the scope of AS/400's, ZuluSCSI's disk support is still incomplete, while CD- and tape emulation are seemingly solid. Some progress has been made, but there are still some rough edges, normally leading to crash of the Operating System with a given ''System Reference Code''.

At the moment, the firmware supports only a single AS/400 specific DASD device type for PPC-AS (522 Bytes per sector).

=== Reports ===
* 2026-08-16, mikerm, 9406-170, Zulu firmware 2026-08-07. Trying to install V4R4 on the Zulu emulated DASD. Disk was created with <code>dd if=/dev/zero of=HD6.img bs=522 count=17177940 status=progress</code><ref>Per directions of one of the firmware developers.</ref>
** First try, ''prefetch'' setting at default (8k): halts at <code>B1934505</code> after IPL takes place from DASD
** Second try, ''prefetch'' set to 0: <code>B6080801</code> after IPL takes place from DASD. More progress, and much quicker LIC install, though.
** Configuration file used:
[SCSI]
LogModeData = 1
System = AS400_BS522

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

ZuluSCSI

2026-08-16T21:25:30Z

PoC: Expanded article

'''ZuluSCSI''' by Rabbit Hole Computing is a comparatively new family of SCSI device emulators featuring an SD card based backing store. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

For most AS/400 machines, you actually want a ZuluSCSI wide, because it offers the best performance.

The ZuluSCSI firmware can emulate multiple devices at once. There is no real need to add multiple Zulus to a given SCSI bus. One Zulu can easily saturate even the UltraWide SCSI bus of a 9401-150, and due to the SD card, delays are minimal. You can gain more performance with bigger machines, if they have multiple SCSI buses, though.

== Hardware overview ==
Depending on the exact model, boards themselves have three DIP switches and tiny push buttons:
* 1: switch to initator mode,
* 2: enable debug log,
* 3: enable SCSI termination.

The push buttons call the functions:
* Bootloader, for firmware-recovery,
* Eject.

Also, three LEDs are provided, for indication of
* 2.8 V power OK,
* 3.3 V power OK,
* SD-card activity.

The device itself needs 5 V power, and can be powered by:
* the USB port,
* the termpower line of the SCSI bus,
* molex style power connectors.

Usually, the integrated USB port is configured as USB modem, for usage with a terminal emulator. You can use the Linux or macOS ''screen'' command for that. Depending on your operating system, you need to find out what device file is created when plugging the Zulu's USB port. On Linux, it's <tt>/dev/ttyACM''n''</tt> — ''n'' being a digit, usually 0. On macOS, it's <tt>/dev/tty.usbmodem*</tt>, with a row of digits appended on behalf of the <tt>*</tt>.

The firmware presents a simple menu driven UI for

There is no need to shut down the device itself, it's safe to "pull the plug" when there is no activity. The Operating System running on the attached computer should, though.

== Configuration ==
Configuration itself is usually automatic, according to the files and directories found on the SD card. The SD card has either a FAT32<ref>Limiting files to max. 4 GiB in size</ref> or exFAT file system, the firmware understands both. It's easier to use the SD card with a card reader on a newer computer to create configurations, and files. The SD card is hotplug capable, and upon reinsertation, the ZuluSCSI reinitializes itself according to the SD card's content.

Three devices classes are of general interest in the AS/400 world:
* Disk (DASD),
* CD/DVD (Optical),
* Tape.

=== Files ===
File names are composed as follows:
<nowiki><TT><ID>[any text].<ext></nowiki>
^^ ^
| +-------------- SCSI ID character (byte offset 2)
+------------------- two-character type prefix (case-insensitive)

* '''TT''':
:{|class="wikitable"
!TT
!Device type
!Default block size
|-
|HD
|Hard disk (fixed)
|align="right"|512 Bytes
|-
|CD
|CD-ROM (optical)
|align="right"|2048 Bytes
|-
|TP
|Sequential (tape)
|align="right"|512 Bytes
|}
* The '''ID''' is exactly one char, and must be given in hexadecimal. This matters only for IDs ≥ 10.
* '''any text''' is entirely optional.
* The '''file extension''' doesn't matter.

=== Directories ===
For a device usually allowing dynamic addition and removal of media — CD-ROM-, and tape drives. The naming scheme follows the same structure as files, but ''[any text]'' must be omitted.

Files within the directories can be freely named, and are used in alphabetical order.<ref>Either through the ''Eject'' button, or the media menu.</ref>

=== Configuration file ===
In addition, a configuration file can be supplied to provide additional information to either all or one emulated device. Having a ''zuluscsi.ini'' is normally optional, but for enabling AS/400 quirks, it's mandatory.

The configuration file must be named ''zuluscsi.ini'', and is in a simple ini-style format. It has a global <tt>[SCSI]</tt> section to apply settings to all devices, and <tt>[SCSI''n'']</tt>, where ''n'' is the ID of the given SCSI devices.

== Examples ==
These are in the scope of AS/400.

=== Tape drive support ===
* create directory <code>TP0</code>,
* populate with one or more 0 byte files named <code>*.tap</code> files, e. g. by using the Unix <code>touch</command>,
* use the serial console to attach image(s) to the drive.
* ''zuluscsi.ini'':
[SCSI]
System="AS400_PPC"

[SCSI0]
TapeDensity = 0x25

Caveats:
* When you choose an image file through the USB port's media menu, make sure that you not only choose an image file, but afterwards ''insert'' it!
* If you replace a hardware tape drive, make sure to delete your old tape device file first, then IPL, check/set the new device name in DST, and have auto-configuration create the new device file during the following IPL.

This configuration has been tested on a 9401-150 running V4R5 over the course of multiple weeks:
* Occasional <tt>go save</tt> 21,
* daily differential backups,
* occasional single file restores.

== Current state ==
In the scope of AS/400's, ZuluSCSI's disk support is still incomplete, while CD- and tape emulation are seemingly solid. Some progress has been made, but there are still some rough edges, normally leading to crash of the Operating System with a given ''System Reference Code''.

At the moment, the firmware supports only a single AS/400 specific DASD device type for PPC-AS (522 Bytes per sector).

=== Reports ===
* 2026-08-16, mikerm, 9406-170, Zulu firmware 2026-08-07. Trying to install V4R4 on the Zulu emulated DASD. Disk was created with <code>dd if=/dev/zero of=HD6.img bs=522 count=17177940 status=progress</code><ref>Per directions of one of the firmware developers.</ref>
** First try, ''prefetch'' setting at default (8k): halts at <code>B1934505</code> after IPL takes place from DASD
** Second try, ''prefetch'' set to 0: <code>B6080801</code> after IPL takes place from DASD. More progress, and much quicker LIC install, though.
** Configuration file used:
[SCSI]
LogModeData = 1
System = AS400_BS522

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

ZuluSCSI

2026-08-16T19:56:28Z

PoC: Moore precise

'''ZuluSCSI'' is a comparatively new family of SCSI device emulators. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

== Current state ==
In the scope of AS/400's, ZuluSCSI's disk support is still in its infancy, while CD- and tape emulation are seemingly solid. Some progress has been made, but there are still some rough edges, normally leading to crash of the Operating System with a given ''System Reference Code''.

At the moment, the firmware supports only a single DASD device type.

=== Reports ===
* 2026-08-16, mikerm, 9406-170, Zulu firmware 2026-08-07. Trying to install V4R4 on the Zulu emulated DASD. Disk was created with <code>dd if=/dev/zero of=HD6.img bs=522 count=17177940 status=progress</code><ref>Per directions of one of the firmware developers.</ref>
** First try, ''prefetch'' setting at default (8k): halts at <code>B1934505</code> after IPL takes place from DASD
** Second try, ''prefetch'' set to 0: <code>B6080801</code> after IPL takes place from DASD. More progress, and much quicker LIC install, though.
** Configuration file used:
[SCSI]
LogModeData = 1
System = AS400_BS522

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

== Footnotes ==
<references />

[[Category:Hardware Configuration Guide]]

ZuluSCSI

2026-08-16T19:49:26Z

PoC: Preliminary

'''ZuluSCSI'' is a comparatively new family of SCSI device emulators. Distinct features to older, similar devices is support for Wide-SCSI, Ultra-Speed, and a fast CPU.

ZuluSCSI also features an OpenSource firmware, so it can be extended comparatively easily.

__TOC__

== Current state ==
In the scope of AS/400's, ZuluSCSI's disk support is still in its infancy. Some progress has been made, but there are still some rough edges, normally leading to crash of the Operating System with a given ''System Reference Code''.

At the moment, the firmware supports only a single DASD device.

=== Reports ===
* 2026-08-16, mikerm, 9406-170, Zulu firmware 2026-08-07. Trying to install V4R4 on the Zulu emulated DASD.
** First try, ''prefetch'' setting at default (8k): halts at <code>B1934505</code>
** Second try, ''prefetch'' set to 0: <code>B6080801</code>. More progress, and much quicker LIC install, though.

== See also ==
* [[Ordinary Harddisks on the AS/400]]
* [[Tape Drives on old AS/400]]
* [[SRC]], aka System Reference Code

== Weblinks ==
* [https://zuluscsi.com ZuluSCSI Website] — see the <tt>☰</tt> button top right for more details
* [https://github.com/ZuluSCSI/ZuluSCSI-firmware ZuluSCSI-firmware], GitHub

[[Category:Hardware Configuration Guide]]

System Internals:SLIC DASD device recognition

2026-08-16T19:22:48Z

PoC: ±Cat/AI heading

{{AI generated not reviewed}}
The '''SLIC DASD device recognition''' table is the static list, inside the OS/400 Licensed Internal Code (SLIC), of which SCSI disk drives the system will accept as a DASD (disk) unit. This page describes how that recognition works, how to find and decode the table in a SLIC image, and — as a worked example — the complete list a V4R4 machine accepts. The method generalises to any release and to other SLIC device tables.

Understanding it matters for preservation: OS/400 refuses ordinary SCSI disks, so keeping a machine alive after a disk failure means presenting a drive (real or emulated) that answers the SCSI bus the way SLIC expects.

== How SLIC decides a disk is acceptable ==

A disk becomes an eligible DASD unit only if it passes three independent gates, all implemented in the SLIC disk device driver:

# '''SCSI INQUIRY must match a static table.''' SLIC compares the drive's INQUIRY vendor id (bytes 8–15) and product id (bytes 16–31) against a built-in table. Only IBM-badged units qualify: the vendor id is normally <code>IBMAS400</code> (a handful of early units use <code>IBM␠␠␠␠␠</code> and two OEM units use <code>QUANTUM␠</code>). An off-the-shelf drive reports its own vendor and is rejected. This is exactly what the "custom firmware" on IBM's 660x/671x disks does: IBM reflashed standard Ultrastar/Corsair mechanisms to answer INQUIRY with an IBM vendor id and an IBM product id.
# '''Vendor-unique SKIP READ / SKIP WRITE.''' The driver issues IBM vendor-unique SCSI commands that read or write a run of sectors while skipping masked ones, used by the Single-Level Store paging path. A faithful drive must implement these, not just standard READ/WRITE.
# '''Capacity from VPD.''' The unit's size is taken at run time from the drive's Vital Product Data / <code>READ CAPACITY</code>, not from the table — the table has no capacity column. An impersonating drive must report a capacity that is legal for the feature type it claims.

== Finding and decoding the table ==

In a SLIC image the table is a run of fixed-size records. On V4R4 each record is 40 bytes:

<pre>
bytes 0- 3 feature type EBCDIC digits, e.g. F6F6F0F7 = "6607"
bytes 4- 5 model EBCDIC, e.g. "1 "
byte 6 class flag 0x00 normal; 0x80 on the 18 GB Ultra2/LVD units
bytes 7-15 reserved 0x40 (EBCDIC space) padding
bytes 16-23 INQUIRY vendor ASCII, matched against INQUIRY bytes 8-15
bytes 24-39 INQUIRY product ASCII, matched against INQUIRY bytes 16-31
</pre>

The type and model are EBCDIC (digit ''n'' = byte <code>0xF''n''</code>); the INQUIRY strings are ASCII. To locate the table, search the image for the ASCII vendor strings <code>IBMAS400</code> / <code>QUANTUM␠</code>: the records sit at a fixed 40-byte stride around them. The same trick — anchor on a known ASCII string, then read the fixed-width record around it — recovers other SLIC hardware tables (IOP/controller CCIN tables, adapter tables, and so on).

== The V4R4 list ==

Every drive a V4R4 system accepts, decoded from the image. "Physical drive" is identification from IBM/Quantum model nomenclature, not read from the binary; the feature type, model and INQUIRY strings are.

{| class="wikitable"
! Feature/Model !! INQUIRY vendor !! INQUIRY product !! Physical drive
|-
| 6109 / 0 || <code>IBM␠␠␠␠␠</code> || <code>0663H12</code> || IBM 0663 "Corsair", ~2 GB
|-
| 6109 / 1 || <code>IBM␠␠␠␠␠</code> || <code>0661371</code> || IBM 0661 "Pixie", ~0.37 GB
|-
| 6105 / 0 || <code>IBM␠␠␠␠␠</code> || <code>0661467</code> || IBM 0661 "Pixie", ~0.47 GB
|-
| 6107 / 0 || <code>IBMAS400</code> || <code>0664M1H</code> || IBM 0664 "Corsair-4", ~4 GB
|-
| 6603 / 0 || <code>IBMAS400</code> || <code>0664N1H</code> || IBM 0664 "Corsair-4", ~4 GB
|-
| 6603 / 1 || <code>IBMAS400</code> || <code>0662S12</code> || IBM 0662 "Corsair", ~1.2 GB
|-
| 6602 / 0 || <code>IBMAS400</code> || <code>0662SW1</code> || IBM 0662 "Corsair", ~1.0 GB
|-
| 6602 / 1 || <code>IBMAS400</code> || <code>DFHSS1W</code> || IBM Ultrastar XP, ~1 GB
|-
| 6605 / 1 || <code>IBMAS400</code> || <code>DFHSS2W</code> || IBM Ultrastar XP, ~2 GB
|-
| 6606 / 1 || <code>IBMAS400</code> || <code>DFHSS4W</code> || IBM Ultrastar XP, ~4 GB
|-
| '''6607 / 1''' || <code>IBMAS400</code> || <code>DCHS09W</code> || IBM Ultrastar 2XP, ~9 GB
|-
| 6713 / 1 || <code>IBMAS400</code> || <code>DGHS18U</code> || IBM Ultrastar 18XP, ~18 GB
|-
| 6714 / 1 || <code>IBMAS400</code> || <code>DGVS09U</code> || IBM Ultrastar 9ES/9LZX, ~9 GB
|-
| 6717 / 1 || <code>QUANTUM␠</code> || <code>SSQD107</code> || Quantum, ~10.7 GB
|-
| 6730 / 0 || <code>QUANTUM␠</code> || <code>SSQD160</code> || Quantum, ~16.0 GB
|-
| 6731 / 0 || <code>IBMAS400</code> || <code>DRVS18D</code> || IBM Ultrastar 18ES/18LZX, ~18 GB, Ultra2/LVD
|}

Feature-type numbers do not track capacity linearly: the type encodes the AS/400 usable-capacity class (after 520-byte-sector overhead), not the drive's native size. The much-cited 6607 is here as <code>IBMAS400</code> / <code>DCHS09W</code>.

== Notes ==

* "Ide" in SLIC symbol names (e.g. the driver classes handling these disks) is the disk device-driver namespace, '''not''' ATA/IDE.
* Numbers like 2748, 6502, 6512, 6751, 6753, 6754 that appear on other SLIC symbols are IOP / disk-controller CCINs, not drive models.
* An emulated target (for example on open SCSI-emulator firmware) must present one of the vendor+product pairs above verbatim, space-padded to the SCSI field widths, implement the vendor-unique SKIP commands, and report a legal capacity via <code>READ CAPACITY</code>.

[[Category:System Internals]]

System Files:QFILEMCD

2026-08-16T19:22:17Z

PoC: ±Cat/AI heading

{{AI generated not reviewed}}
'''<code>QFILEMCD</code>''' is the larger of the two container files found on AS/400 SAVSYS and Licensed Internal Code installation media. It is a backup of '''SLIC''' itself — the System Licensed Internal Code that sits below OS/400 — stored as a small number of very large memory segments. Its internal format is called '''<code>COPYDIR</code>''' after the eyecatcher at offset zero.

Practically, this is the file to reach for if you want to read the machine's own code without touching a running system. Its segments are a byte-for-byte image of what the link loader maps into memory, so an address recovered from a crash, a trace or a [[SRC|system reference code]] can be looked up directly in a file on your workstation. The companion file [[System Files:QFILEIML]] carries the loadable IOP, adapter and service processor microcode instead.

Both files are containers of [[Data Structures:LID|LIDs]], but at different granularities, and the relationship between them is described under ''Two directories, two granularities'' below.

The figures quoted here come from one V4R4 image of 472,846,336 bytes (451 MiB). Treat structure as general and numbers as release-specific; the format is unchanged from V4R4 through V7R4, across install media and SAVSYS output alike.

== Header ==
{|class="wikitable"
!Offset
!Contents
|-
|<code>0x00</code>
|Eyecatcher <code>COPYDIR </code> in EBCDIC (<code>C3 D6 D7 E8 C4 C9 D9 40</code>), a zero byte, then the two EBCDIC characters <code>00</code>
|-
|<code>0x1C</code>
|32-bit total size of the payload area — see below. Confirmed on three independent samples
|-
|<code>0x26</code>
|Release level, then the '''system serial number''', EBCDIC
|-
|<code>0x50</code>
|Licensed Internal Code banner, EBCDIC, in 48-character chunks
|-
|<code>0x1C0</code>
|Start of the directory
|}

The string in a V4R4 image reads:

<pre>
V4R4M044-C6295 2606071417
</pre>

and in a V7R4 one taken by SAVSYS from a running machine:

<pre>
V7R4M021-7886W
</pre>

The first field is the release and modification level. '''The five characters after the hyphen are the system serial number.''' That is not an inference: the owner of the V7R4 machine confirms its serial is <code>7886W</code>.

On '''installation media''' the same field carries a build or media tag instead — a V7R4 install ISO reads <code>V7R4M021-821BV</code> — so what the field means depends on how the image was produced. Both forms are five characters, which makes them easy to confuse.

<blockquote>'''Note!''' A LIC backup is therefore '''not anonymous''': it records the serial number of the machine it came from. The serial is also one of the values the system password is keyed on (see [[CISC AS/400 LIC Tapes]]), so treat these files as identifying if you share them.</blockquote>

In the V4R4 sample the ten digits after the serial parse naturally as a timestamp of the form <code>YYMMDDHHMM</code>, making that backup 2026-06-07 14:17. That part '''is''' an inference from the shape of the field, and the V7R4 sample carries binary rather than digits in the same place, so the layout after the serial is not fixed.

<blockquote>'''Note!''' The header is '''not''' a fixed 192 (<code>0xC0</code>) bytes, despite older format notes saying so. The IBM legal banner runs on well past that point, and in this V4R4 image the directory does not begin until <code>0x1C0</code>. A parser should locate the directory by scanning for the first 64-byte-aligned block that has the shape of an entry, rather than seeking to a constant.</blockquote>

The 32-bit field at <code>0x1C</code> holds <code>0x1C2F0000</code>, which is exactly the end of the last segment's data. It is a total-payload-size field and makes a good consistency check after parsing the directory: accumulate the entries and you should arrive at the same number.

== The directory ==
The directory is a run of 64-byte entries beginning at <code>0x1C0</code>.

{|class="wikitable"
!Offset
!Size
!Field
|-
|<code>+0x00</code>
|8
|Always zero in observed data
|-
|<code>+0x08</code>
|8
|Flags. See the bit-numbering warning below
|-
|<code>+0x10</code>
|8
|SLS address of the saved segment
|-
|<code>+0x18</code>
|8
|Segment attributes; the top 16 bits carry the useful value
|-
|<code>+0x20</code>
|8
|Always zero in observed data
|-
|<code>+0x28</code>
|8
|Offset to the segment data, '''absolute from the start of the file'''
|-
|<code>+0x30</code>
|4
|Segment length, in '''raw bytes''' — not blocks
|-
|<code>+0x34</code>
|4
|Always zero in observed data
|-
|<code>+0x38</code>
|8
|Always zero in observed data
|}

Two details cause most of the trouble people have with this structure, and both were originally got wrong here:

* '''Flags use IBM's MSB-first bit numbering.''' Older notes describe the field as <code>bbt 0:3</code>, and a reader used to LSB-first numbering will look in the bottom nibble and find nothing. Bit 0 is the ''most'' significant bit, so the value lives in the '''top''' nibble of the 8-byte field. A normal entry reads <code>0x1000000000000000</code>; the end-of-directory marker reads <code>0xF000000000000000</code>.
* '''The data offset is absolute.''' It is measured from the start of the file, not from the end of the directory. Reading it as relative shifts every extracted segment by the size of the directory, which produces code that disassembles almost plausibly and is wrong everywhere.

In this image the directory holds '''32 entries''', with the terminator at <code>0x9C0</code> and the directory ending at <code>0xA00</code>. The first entry has a data offset of zero, which means the header and directory physically occupy the first <code>0xA00</code> bytes of the first segment's stored image. This is expected rather than a bug, but a tool that extracts that segment will see the container's own header at the front of it.

Segment lengths are consistently a whole number of 4 KiB pages less than a power-of-two boundary: <code>0xFFF000</code> is 16 MiB minus one page, <code>0x7FF000</code> is 8 MiB minus one page, and so on.

== Contents of a typical backup ==
The 32 segments of this image, with names from a community-maintained SLS address reference. Where the name column is blank, the segment's purpose has not been established.

{|class="wikitable"
!SLS address
!Length
!Name
|-
|<code>FFFFFFFFB1 000000</code>
|16 MiB
|
|-
|<code>FFFFFFFFB2 000000</code>
|16 MiB
|
|-
|<code>FFFFFFFFB3 000000</code>
|16 MiB
|
|-
|<code>FFFFFFFFB5 000000</code>
|16 MiB
|
|-
|<code>FFFFFFFFC1 000000</code>
|16 MiB
|Link Loader — LIC Code
|-
|<code>FFFFFFFFC2 000000</code>
|16 MiB
|Link Loader — LIC Data
|-
|<code>FFFFFFFFC3 000000</code>
|16 MiB
|Link Loader — LIC Code (2)
|-
|<code>FFFFFFFFC4 000000</code>
|16 MiB
|Link Loader — LIC Code (3)
|-
|<code>FFFFFFFFC5 000000</code>
|16 MiB
|Link Loader — LIC Code (4)
|-
|<code>FFFFFFFFC6 000000</code>
|8 MiB
|Link Loader — LIC Code (5)
|-
|<code>FFFFFFFFC7 000000</code>
|16 MiB
|Mixed — component code and NLS text pools
|-
|<code>FFFFFFFFC8 000000</code>
|8 MiB
|Mixed — bignum/JVM code and NLS text pools
|-
|<code>FFFFFFFFF1 000000</code>
|4 MiB
|Link Loader TOC
|-
|<code>FFFFFFFFF2 000000</code>
|16 MiB
|Service LID
|-
|<code>FFFFFFFFF4 000000</code>
|16 MiB
|Service LID (2)
|-
|<code>FFFFFFFFFE 000000</code>
|15 MiB
|Pageable BLA
|-
|<code>FFFFFFFFD1 000000</code>
|16 MiB
|Link Loader Information
|-
|<code>FFFFFFFFD2 000000</code>
|16 MiB
|Link Loader Information, Code, Data
|-
|<code>FFFFFFFFD3 000000</code>
|16 MiB
|Link Loader Information (2)
|-
|<code>FFFFFFFFD4 000000</code>
|16 MiB
|Mixed — JVM strings and DST debug symbol table
|-
|<code>FFFFFFFF90 010000</code>
|60 KiB
|LID Directory
|-
|<code>FFFFFFFF91 000000</code>
|16 MiB
|LID NUC2 A-Side
|-
|<code>FFFFFFFF92 000000</code>
|16 MiB
|LID NUC2 B-Side
|-
|<code>FFFFFFFF93 000000</code>
|16 MiB
|LID NUC1 A-Side
|-
|<code>FFFFFFFF94 000000</code>
|16 MiB
|LID NUC1 B-Side
|-
|<code>FFFFFFFF95 000000</code>
|16 MiB
|
|-
|<code>FFFFFFFF96 000000</code>
|16 MiB
|
|-
|<code>FFFFFFFF9A 000000</code>
|8 MiB
|
|-
|<code>FFFFFFFF9B 000000</code>
|8 MiB
|
|-
|<code>FFFFFFFFA1 000000</code>
|16 MiB
|LID Manager
|-
|<code>FFFFFFFFA2 000000</code>
|16 MiB
|
|-
|<code>FFFFFFFF69 000000</code>
|16 MiB
|IDE
|}

So a backup of this shape is the SLIC boot and loader nucleus: link loader code and data, the loader's table of contents, the LID subsystem's own bookkeeping, and both IPL sides of the two nucleus LIDs. It is not the whole of the machine's code.

=== A and B sides ===
Several segments appear twice, distinguished as ''A-side'' and ''B-side''. An AS/400 keeps two copies of its Licensed Internal Code so that an update can be applied to one while the other remains a fallback. A normal, unattended IPL runs the '''B side''', so B is what a running machine is executing and B is what static analysis should be done against. Because the two sides are normally near-identical, a byte comparison against the A side is not evidence that A is the live one — the test only means something on a segment that actually differs between them.

== Two directories, two granularities ==
A common source of confusion is that <code>QFILEMCD</code> appears to have two completely different directory formats. It does, and they nest:

* The '''coarse''' level is <code>COPYDIR</code>'s own directory, documented above: 64-byte entries, one per 16 MiB-class memory segment, 32 of them.
* The '''fine''' level is a catalogue of individual LIDs, thousands of entries, using the 32-byte record described at [[Data Structures:LID]].

The fine level is not a second header in the file. It is simply '''the contents of one particular segment''' — the one named ''LID Directory'', at <code>FFFFFFFF90 010000</code>. Extract that segment and you find, after a preamble of about 1536 bytes, an EBCDIC <code>Directory.</code> eyecatcher, a version label, and then the records. In this image the label reads <code>v4r4m01204.0.03</code>, which is the same label carried by [[System Files:QFILEIML]] — a quick way to confirm that two files came off the same media.

That is also why tools which dump this file emit two dissimilar-looking listings: a short table of large memory extents, and a long list of LIDs. They are two levels of one structure, not two formats.

== Extracting a segment ==
The practical recipe, and the reason this file is worth knowing about:

# Read the <code>COPYDIR</code> eyecatcher at offset 0 to confirm the format.
# Find the directory by scanning 64-byte-aligned offsets for the first entry-shaped block, rather than assuming <code>0xC0</code> or <code>0x1C0</code>.
# Walk entries until the flags field has <code>0xF</code> in its '''top''' nibble.
# For the segment you want, seek to the data offset '''as an absolute file offset''' and read ''length'' raw bytes.
# Load the result at its SLS address in a disassembler. The bytes are what the link loader maps, so addresses match.

Step 5 is the payoff. A 64-bit address such as <code>FFFFFFFFC6 1F1690</code> can be typed straight into the DST ''Display/Alter storage'' panel on a live machine of the same build, and the sixteen rows it displays will match the extracted file byte for byte. Static and live analysis share one address space, which means you can do the slow work offline and use the machine only for confirmation.

Two caveats on addresses. They are per-'''build''', not per-release, so comparisons are only meaningful between identical builds; the same class sits at a quite different address on a V5R4 machine. And the SLS address recorded in the directory is the address the segment was '''saved from''', which is not always where it runs — the resident nucleus segment, for instance, is stored in the container under the SID of the B-side nucleus LID rather than its runtime SID.

== Reading the code ==
Once a segment is loaded, two structures make it navigable, and both are worth knowing because they turn addresses into names:

* '''Traceback trailers.''' Every compilation unit ends its code with a <code>TBTB</code> trailer, and many carry the module's name. A trailer names a whole compilation unit rather than a single function, so a hit means "this address is inside module X", not "this address is function X".
* '''Link-loader descriptor blocks.''' Considerably richer: one block per procedure, carrying the entry address at <code>+0x08</code> and the name in EBCDIC at <code>+0x38</code>. Names beginning with <code>#</code> are SLIC-internal modules; the rest are C++ mangled symbols.

Merging both across every segment of this V4R4 image yields roughly 184,000 named records, which is enough to name a substantial fraction of any address you encounter. See [[SRC]] for how to use that to get from a reference code back to a module.

Calls between modules do not go through a conventional dispatch table, which surprises people disassembling SLIC for the first time. An external call is a two-instruction sequence — <code>ori r11,r13,''ordinal''</code> followed by <code>bla</code> into a transfer vector at the very top of the address space — and the 16-byte stub it lands on computes the target arithmetically. There is no table to read off; the ordinal ''is'' the callee's word offset within a window, and the stub supplies the window. The stub constants cannot be derived and must be read from a dump of the transfer vector.

== The trailing page ==
The payload area ends at <code>0x1C2F0000</code>, but the file is one 4 KiB page longer than that. The final page is not padding: it holds 468 non-zero 8-byte records, which appear to be address-and-value pairs.

They fall into two clear populations. The first 110 are in ascending address order with a value of 8, addressing the ''Link Loader — LIC Data'' segment among others. The remaining 256 are identical to each other: the same address <code>0xFE911220</code>, in the ''Pageable BLA'' segment, paired with the value <code>0x48000002</code> — which as PowerPC is a branch-absolute to zero, the shape of a deliberately poisoned entry.

This has the flavour of a fixup or relocation list applied after the segments are restored, but that is a guess from shape alone. It is recorded here because it is real, reproducible and unexplained, and because a parser that assumes the file ends with the payload will silently ignore it.

== Open questions ==
* The purpose of the trailing page.
* The header bytes other than the eyecatcher, size field, release string and banner.
* The meaning of the segment attribute field's top 16 bits, which take values <code>0x0001</code>, <code>0x0040</code>, <code>0x0080</code> and <code>0x0100</code> and correlate loosely with segment size.
* Names for the nine segments left blank in the table above.

== See also ==
* [[System Files:QFILEIML]]
* [[Data Structures:LID]]
* [[SRC]]
* [[CISC AS/400 LIC Tapes]]

[[Category: System Internals]]

System Files:QFILEIML

2026-08-16T19:21:56Z

PoC: ±Cat/AI heading

{{AI generated not reviewed}}
'''<code>QFILEIML</code>''' is one of the two large container files found on AS/400 SAVSYS and Licensed Internal Code installation media. It holds the machine's ''loadable'' microcode: IOP and adapter firmware, service processor firmware, and a quantity of SLIC modules. Its internal format is identified by the four-byte magic '''<code>IMD1</code>''' and is a container of [[Data Structures:LID|LIDs]].

The companion file <code>QFILEMCD</code> holds SLIC proper, via a directory called <code>COPYDIR</code>. Both files use the same 32-byte [[Data Structures:LID|LID directory record]], and a record present in both is byte-for-byte identical, so the two are two views of one packaging scheme rather than two unrelated formats.

The name is not documented by IBM as far as is known here. <code>IML</code> almost certainly stands for ''Initial Microprogram Load'' — the phase in which the machine's microcode is brought up, before OS/400 itself exists — which matches the file's contents. Treat the expansion as an inference.

This description is based on two samples: a V4R4 image of 81,287,680 bytes (77.5 MiB), build label <code>v4r4m01204.0.03</code>, and a V7R2 one of 288.7 MiB, label <code>v7r2m00000.0.00</code>, taken from an installation ISO. Unless a figure is attributed to a release, it comes from the V4R4 sample; the section ''Across releases'' sets out what is format and what merely happened to be true of one image.

== File layout ==
The layout is '''not at fixed offsets'''. It is carried in the header, and it differs between releases — a decoder that assumes the V4R4 offsets will read a V7R2 container as having no entries at all, without reporting an error.

The field at <code>+0x08</code>, low 24 bits, is the offset to the Licensed Internal Code banner. The directory header sits at exactly '''twice''' that offset, its records <code>0x20</code> further on, and the build label at header <code>+0x10</code>.

{|class="wikitable"
!Release
!<code>+0x08</code>
!Banner
!Directory header
!Records
!Build label
|-
|V4R4
|<code>ff000200</code>
|<code>0x200</code>
|<code>0x400</code>
|<code>0x420</code>
|<code>v4r4m01204.0.03</code>
|-
|V7R2
|<code>ff000800</code>
|<code>0x800</code>
|<code>0x1000</code>
|<code>0x1020</code>
|<code>v7r2m00000.0.00</code>
|}

So the general layout is:

{|class="wikitable"
!Offset
!Contents
|-
|<code>0x000</code>
|Magic <code>C9 D4 C4 F1</code>, which is <code>IMD1</code> in EBCDIC
|-
|<code>0x008</code>
|Low 24 bits: offset to the banner. The rest of the header is not understood
|-
|''banner''
|Licensed Internal Code banner in EBCDIC, carrying the LIC product identifiers
|-
|''banner'' × 2
|Directory header: a four-byte preamble, the literal string <code>Directory.</code>, two zero bytes, then a 16-byte build label
|-
|''banner'' × 2 + <code>0x20</code>
|The directory: a run of 32-byte LID records
|-
|''varies''
|Terminator record, identifier <code>0xC5D5C440</code> (<code>END </code> in EBCDIC)
|}

The first sixteen bytes of a V4R4 container are:

<pre>
00000000: c9d4 c4f1 0000 0000 ff00 0200 00e0 0000
</pre>

and of a V7R2 one:

<pre>
00000000: c9d4 c4f1 0000 0000 ff00 0800 0010 0000
</pre>

The banner reads, in EBCDIC:

<pre>
LICENSED INTERNAL CODE - PROPERTY OF IBM 5763999, 5716999, 5769999
(C) COPYRIGHT IBM CORP. 1980, 1998. ALL RIGHTS RESERVED. ...
</pre>

The seven-digit numbers are LIC product identifiers, and the same ones appear in <code>QFILEMCD</code>. The build label is likewise identical between the two container files from the same media, which is a convenient way to confirm that a given <code>QFILEIML</code> and <code>QFILEMCD</code> belong together.

The field at <code>+0x0C</code> differs between the two samples (<code>00e00000</code> against <code>00100000</code>) and is not understood. Two samples are not enough to fit it.

== The directory ==
The directory begins at <code>0x420</code> and runs, in this image, for 632 records before the <code>END </code> terminator at <code>0x5320</code>. The record layout is documented at [[Data Structures:LID]] and is not repeated here.

Of the 632 records:
* 341 carry the compressed flag.
* 631 name an SLS staging address in the <code>FFFFFFFFxx</code> band. Exactly one does not: LID <code>80900818</code> stages at <code>000000024A 000000</code>.
* 7 have payloads that are themselves runs of LID records — see ''Directory extents'' below.

== Payload addressing ==
<blockquote>'''Note!''' This is the single point on which it is easiest to go wrong, and doing so silently produces plausible-looking nonsense.</blockquote>

The <code>offset</code> field in each record is '''not''' an offset into the container. It is a load-source LBA, describing where the payload sits on the installation medium, and it has no useful meaning inside the file.

Reading it as a file offset is superficially attractive and definitively wrong. Doing so on a V4R4 image yields 608 overlapping extents out of 632, a maximum extent of 34,550 blocks against a 158,765-block file, and a minimum offset of block 3, which lands inside the header. That the lengths happen to sum to approximately the file size is a coincidence and should not be taken as confirmation.

The actual rule is simpler: '''payloads are stored sequentially, in directory order, immediately after the directory''', each one <code>length</code> blocks long. There are no gaps and no padding between them.

'''Payloads begin at the next 512-byte block boundary after the directory terminator.''' That is block 42 for the V4R4 sample and block 69 for the V7R2 one. This rule needs only the directory, so it also works on a container embedded in a larger image — an install ISO, for instance — where the file size is not a meaningful quantity.

An older formulation, ''file size in blocks minus the sum of all lengths'', gives the same answer for a standalone file and is a useful cross-check: on the V4R4 sample the two agree exactly, and the implied container size matches the real file size to the byte at 81,287,680. But it cannot be used on an embedded container, so prefer the terminator rule.

To locate a payload, therefore, walk the directory from the beginning and accumulate lengths; do not index by the offset field.

== Contents ==
Laid out correctly, the payloads fall into two clear populations, distinguishable without decompression by looking for 32-bit <code>stwu r1,-x(r1)</code> prologues versus 64-bit <code>std</code> stores:

{|class="wikitable"
!Population
!Count
!Identification
|-
|32-bit PowerPC
|75
|<code>stwu</code> prologues present, no <code>std</code> at all
|-
|64-bit PowerPC AS (SLIC)
|210
|<code>std</code> present, no <code>stwu</code> at all
|-
|Neither
|347
|Compressed payloads, data, tables, and directory extents
|}

The split is clean — no payload shows both — which is what makes the heuristic trustworthy. The 32-bit population is the interesting one: the main processor of these machines is 64-bit PowerPC AS, so 32-bit code in this file is by definition destined for something else. That is the IOP, adapter and service processor microcode.

=== Service processor firmware ===
LID <code>80900702</code> is service processor Licensed Internal Code: 128 KiB, stored uncompressed, staged at SLS <code>FFFFFFFF9A 001000</code>. Its EBCDIC strings include a ''9400 Licensed Internal Code'' banner and a 1998 copyright, and its code is unambiguously 32-bit.

This confirms a long-standing claim in the trade press that AS/400 service processor firmware is loaded from the load source rather than residing wholly in flash on the card. As the rest of this section shows, that turns out to be only half true.

About 30 payloads carry an <code>AJS</code> build identifier and are service-processor code, ranging from a few tens of kilobytes to a few hundred. A further handful carry <code>AJG</code> identifiers and are I/O offload (MFIOP) code instead; several of those carry an <code>ATM</code> marker, i.e. ATM networking, which is not something a service processor does. The two families are ''mostly'' disjoint but not perfectly: at least one payload contains both identifiers.

==== Module headers ====
Each of these images is not a monolithic firmware blob but a collection of '''linkable modules''', each introduced by a header with the EBCDIC eyecatcher '''<code>PGPM</code>''' (<code>D7 C7 D7 D4</code>) — 119 of them in a V4R4 container and 104 in a V7R2 one, decoding identically. The useful fields are:

{|class="wikitable"
!Offset
!Contents
|-
|<code>+0x00</code>
|<code>PGPM</code> eyecatcher
|-
|<code>+0x04</code>
|A LID identifier — but see the caveat below
|-
|<code>+0x24</code>
|EBCDIC version string, e.g. <code>0100</code>
|-
|<code>+0x30</code>
|8-byte build identifier, e.g. <code>AJSFGVB3</code>
|-
|<code>+0x54</code>
|8-byte name of the module this header '''defines'''
|-
|<code>+0x60</code>
|Slot table, 4-byte values
|-
|<code>+0xC0</code>
|Import table: 12-byte entries, each an 8-byte name and a 4-byte linkage slot, terminated by eight EBCDIC <code>F</code> characters
|}

<blockquote>'''Note!''' Strings such as <code>SP MOPT1</code>, <code>SP SPCI3</code> or <code>SP WT</code> are '''module names in a link table''', not feature or capability tags. An earlier version of this article described them as component tags whose differing sets indicated capability tiers across the hardware range. That reading was wrong: the sets differ because different modules import different things.</blockquote>

Worked example, from the header at <code>+0x59C</code> of LID <code>A07008C2</code>: build <code>AJSFGVB3</code>, defines <code>SP SB</code>, and imports <code>SP SPCI1</code> through <code>SP SPCI5</code> and <code>CUANSI</code>, with the import table running to its terminator at <code>+0x1B4</code>.

Both families share a common utility layer, which is why their vocabulary overlaps: <code>CUANSI</code>, <code>CUCONV</code>, <code>CUIO</code>, <code>CUMEMORY</code>, <code>CUMISC</code> and <code>CUSTO</code>, plus <code>SRASCOMN</code> for RAS common code.

==== Reading the dependency graph ====
Because every module declares what it defines and what it imports, the link tables can simply be read off as a dependency graph — which is more informative than any amount of disassembly, and is the main reason the <code>PGPM</code> header is worth knowing about.

Doing so reveals a clean pattern. The '''numbered''' names — <code>SP SPCI1</code> to <code>SPCI5</code>, <code>SP MOPT1</code> to <code>MOPT9</code>, <code>SP MOPD1</code> — are imported by many modules and '''defined by none'''. The '''lettered''' members of the same families — <code>MOPTA</code>, <code>MOPTB</code>, <code>MOPTC</code>, <code>MOPD2</code> — each import their immediate predecessor and are present as real modules.

The natural reading is that numbered names are resident firmware on the card and lettered ones are downloadable extensions layered on top. Which is exactly what the following section establishes by a completely independent route.

<blockquote>'''Caveat.''' The LID identifier at <code>+0x04</code> of a <code>PGPM</code> header frequently disagrees with the container LID that the sequential payload layout assigns to that region. Most of these values are valid LID identifiers from the directory, and in one region a run of 21 consecutive modules is spaced exactly by the directory lengths of the LIDs they name. Either the layout is displaced there, or modules are stored under a delivery LID distinct from their own. Findings about module ''contents'' are unaffected, since they come from the headers themselves — but do not quote a byte offset against a specific LID until this is resolved.</blockquote>

=== What is not in the file ===
Notably, the service processor's own '''supervisor is absent'''. Two independent lines of evidence agree on this.

'''From the instruction stream.''' All payloads were searched for <code>rfi</code> (<code>0x4C000064</code>), which any PowerPC exception-returning kernel must contain, and for exception vector tables at the architectural <code>0x100</code>, <code>0x200</code> and subsequent offsets of every 4 KiB boundary. Across 4.1 MB of service-processor code there is not one <code>rfi</code>, and no payload has a vector table. Privileged operations are almost as scarce: six instructions of the <code>mtmsr</code> family and four cache or TLB operations in the whole set.

Consistent with that, LID <code>80900702</code> begins mid-function, with a function ''tail'' rather than an entry point, and manipulates no privileged state at all — only LR, CTR and XER are touched. It does contain 31 <code>sc</code> supervisor calls.

'''From the link tables.''' As described above, the numbered module names are imported by many modules and defined by none. The code that provides them is therefore not on this medium.

The conclusion is that the service processor runs a resident supervisor of its own, held in flash on the card, and that this file supplies only loadable task modules that sit on top of it. That is consistent with the hardware — the operator panel carries its own flash, and SLIC has an explicit message for instructing the service processor to IPL itself.

==== The supervisor call interface ====
Since the supervisor itself is absent, the <code>sc</code> instructions are the entire visible boundary between these modules and the firmware they run on. Across the family there are 668 supervisor calls using just 9 distinct call numbers, with the number in <code>r0</code> and arguments from <code>r3</code>:

{|class="wikitable"
!Call
!Count
!Observed arguments
|-
|<code>0x020C</code>
|262
|—
|-
|<code>0x0208</code>
|131
|<code>r3 = 0x16</code> in every instance
|-
|<code>0x03A4</code>
|106
|<code>r3 = 0x64</code>, <code>r4 = 5</code>; unique to one module
|-
|<code>0x0358</code>
|
|<code>r3</code> is one of exactly three values: <code>0x83010000</code>, <code>0x83020000</code>, <code>0x83030000</code>
|}

The first two are the interesting pair: <code>0x0208</code> occurs exactly half as often as <code>0x020C</code>, and always on the same resource number, which is the signature of an acquire/release pair around a critical section. The <code>0x0358</code> window is the only region passed explicitly to a supervisor call, which is what registering or mapping a device or shared-memory window looks like.

Beyond that the call numbers cannot be decoded, because the code that implements them is not on this medium.

==== A caution about what this firmware does ====
It is tempting to assume this firmware covers the obvious service-processor duties — power control, thermal and fan management, SPCN, driving the panel and its LCD, VPD storage, error logging and SRC posting. '''No such claim is supported by this file.'''

These modules contain almost no descriptive text. The complete inventory of readable strings is the Licensed Internal Code banner, the copyright boilerplate, the EBCDIC-to-ASCII translation tables, and the <code>PGPM</code> link names. A search for the entire relevant vocabulary — <code>POWER</code>, <code>FAN</code>, <code>THERMAL</code>, <code>SPCN</code>, <code>VPD</code>, <code>PASSWORD</code>, <code>SECUR</code>, <code>SERIAL</code> and more, in both EBCDIC and ASCII, over every byte — returns nothing in any service-processor module. The same vocabulary ''is'' present elsewhere in the container, but only inside SLIC payloads.

So the honest position is that the functional surface visible here is nine supervisor call numbers into firmware nobody has. What the service processor actually does is implemented on the other side of that boundary.

One bound on that negative: readable code averages about 46 % of 1 KiB blocks across these images, and one 119 KiB payload is entirely opaque. The supported statement is that nothing is visible in the readable portion, not that nothing exists.

=== Directory extents ===
Seven payloads are not data but further runs of 32-byte LID records, largely duplicating entries from the root directory byte for byte. The two largest hold 294 and 133 records. They appear to be indexes rather than nested containers, and a tool walking this file should recognise them so as not to mistake an index for a firmware image. A payload whose first few records parse as plausible LID records, with identifiers matching known LIDs, is an extent.

== Compression ==
341 of the 632 payloads are flagged compressed. The codec is the LZW variant used throughout SLIC and is described at [[Data Structures:LID#The compressed flag]]. It has not been needed to read the service processor firmware, which is stored plain, but it stands between the reader and roughly half the file.

== Tooling ==
No IBM-supplied tool for reading this file outside the machine is known. A parser must, at minimum:
# check the <code>IMD1</code> magic at offset 0;
# read the banner offset from <code>+0x08</code> and '''derive''' the directory position from it, rather than assuming a constant;
# read 32-byte records until an identifier of <code>0xC5D5C440</code> or zero;
# place the payload area at the next block boundary after that terminator;
# lay payloads out sequentially in directory order.

Step 2 is the one that catches people. An implementation that hardcodes the V4R4 directory offset of <code>0x420</code> does not fail loudly on a V7R2 container — it reports zero records and a nonsensical payload start. Deriving the offsets costs nothing and works on both.

== Across releases ==
Comparing a V4R4 image with a V7R2 one shows how much of this is format and how much was accident of a single sample.

{|class="wikitable"
!
!V4R4
!V7R2
|-
|Records
|632
|961
|-
|Compressed
|341
|557
|-
|Payload
|77.5 MiB
|288.7 MiB
|-
|<code>PGPM</code> module headers
|119
|104
|}

The record format, the <code>PGPM</code> module header and its field offsets, the payload tiling rule and the <code>END </code> terminator are all unchanged. What varies is the header offsets, which the header itself declares.

The service processor module namespace is also strikingly stable. Fourteen <code>SP</code> module names are defined in both releases, and the pattern of numbered names being imported but never defined — the evidence that they live in flash on the card — reproduces exactly sixteen years apart. So does the supervisor call vocabulary, with V7R2 adding one new call number.

What did change is on the SLIC side, and it is what you would expect once the service processor and panel stop being discrete cards. The concrete hardware driver classes are simply gone in V7R2, while the message protocol and resource model that sat on top of them survive and grow. In their place, the panel and service processor objects are constructed from new ''virtual'' VPD providers. The interface is preserved and the implementation behind it is virtualised — which is why code written against the older message classes still reads as recognisable on a modern machine.

== Open questions ==
* The header field at <code>+0x0C</code>, which differs between samples (<code>00e00000</code> against <code>00100000</code>).
* The rest of the header between <code>+0x0C</code> and the banner.
* The meaning of most LID identifier families.
* Why some payloads carry the compressed flag yet begin with plainly readable 32-bit code.
* Whether the load-source LBAs in the offset field can be used to reconstruct the physical layout of the original installation medium.
* The <code>PGPM</code> identifier discrepancy described above.

== See also ==
* [[Data Structures:LID]]
* [[CISC AS/400 LIC Tapes]]
* [[Copying disks with Linux]]

== Weblinks ==
* [https://www.mcpressonline.com/ MC Press Online], which carries older documentation describing service processor microcode as being loaded from the load source

[[Category: System Internals]]

SRC

2026-08-16T19:21:35Z

PoC: ±Cat/AI heading

{{AI generated not reviewed}}
A '''system reference code''' ('''SRC''') is the AS/400's primary way of telling you what it is doing or what went wrong. It is the string of hexadecimal characters shown on the operator panel's display, and the same codes appear in the system's logs and on the console. Because the platform is designed to be serviced by someone who may not have a working console, the SRC is deliberately the lowest-common-denominator channel: it works when nothing else does.

This article covers what an SRC ''is'' and, more usefully, '''how to work back from one to the piece of Licensed Internal Code that produced it'''. Individual codes are catalogued elsewhere — see [[Disk device related system reference codes]], [[Tape device related system reference codes]] and [[SRC 0000BBBB]] for worked cases.

== What an SRC looks like ==
The panel displays eight hexadecimal characters. That display is only the first of several ''words'' the machine has available; the remainder are reached with the panel's extended functions, and all of them are recorded in the logs.

The leading character is the most informative part, because it identifies what kind of event you are looking at:

{|class="wikitable"
!Leading character
!Meaning
|-
|<code>A</code>
|Attended IPL — the machine is waiting for you
|-
|<code>B</code>
|A problem was detected, most often by Licensed Internal Code
|-
|<code>C</code>
|IPL progress; the machine is working normally
|-
|<code>D</code>
|Power-down progress
|}

The distinction that matters when something appears stuck is between <code>C</code> and <code>B</code>. A <code>C</code> code is a progress report, and a machine sitting on one for a long time may simply be doing something slow. A <code>B</code> code is a failure, and it will not clear itself.

Progress codes are genuinely informative about sequence. The IPL-time verification sequence, for instance, runs:

{|class="wikitable"
!SRC
!Meaning
|-
|<code>C600 4500</code>
|Verifying network attributes
|-
|<code>C600 4504</code>
|Verifying system serial number
|-
|<code>C600 4505</code>
|Verifying system type
|-
|<code>C600 4506</code>
|Verifying system-unique ID
|-
|<code>C600 4507</code>
|Starting 'before DST' DASD checker
|-
|<code>C600 4508</code>
|Verifying system password
|-
|<code>C600 450A</code>
|Starting 'after DST' DASD checker
|}

Read as a whole, that tells you the order of dependency inside the IPL — serial number, then type, then unique ID, then disk state, then the system password — which is information you will not find stated anywhere as prose. Progress codes are a free execution trace of the boot path, and reading a long capture of them is a cheap way to understand a sequence you cannot otherwise observe.

== Where SRCs are recorded ==
The panel shows the current one. Everything else is in the machine:

* '''Panel extended functions''' step through the additional words of the current SRC.
* The '''Product Activity Log''', under DST or SST, holds hardware-detected events with their full word set and timestamps.
* The '''Licensed Internal Code log''' holds LIC-detected events. This is the one that matters for the technique below, because for a LIC-detected error it records the failing '''module''' — not just a code.
* '''Main storage dumps''' capture machine state at the point of failure.

If you are trying to understand a failure rather than merely clear it, go to the logs. The panel gives you one word of what may be a nine-word record.

== How SRCs are produced ==
Inside SLIC there is a family of classes that construct reference codes, one per flavour of event:

<pre>
IoMFSystemRefCode base
IoMFGenericSystemRefCode generic
IoMFAttentionSystemRefCode attention
IoMFIplStatusSystemRefCode IPL status
IoMFRunStatusSystemRefCode run-time status
IoMFTerminalSystemRefCode terminal
IoMFExtendedSrc / IoMFExtendedSrcHyp
</pre>

alongside a set of categories that amount to the machine's error taxonomy — <code>IoMFSrcDeviceFailure</code>, <code>IoMFSrcIoError</code>, <code>IoMFSrcIopCodeDetectedFailure</code>, <code>IoMFSrcSlicDetectedError</code>, <code>IoMFSrcIopFailureNoDeviceVpd</code> and several more. Persistent logging goes through an entry point named <code>putSrc</code> on the persistent-machine class.

Getting the code onto the panel is a separate step, handled by a request/acknowledge message protocol to the service processor. The panel-related messages include <code>IoMFCEMessageSRCDisplay</code> to display a code and <code>IoMFCEMessagePNLClearSRC</code> to clear it, in among messages for panel button notifications, power control and IPL mode. The panel is a small subassembly with its own microcontroller, driven over what appears from the software side to be a simple serial link.

The practical consequence is that '''posting an SRC is an ordinary function call''' made from ordinary code. It is not a hardware trap or a magic register. So the code that posted a given SRC is findable by the same means as any other caller.

== Working back from an SRC to a LIC module ==
This is the part worth generalising, because the same route serves any question of the form "which code did this?" — not only SRCs.

=== On the machine ===
For a LIC-detected error, the Licensed Internal Code log entry names the failing module directly. That is the short path and should always be tried first: DST or SST, the LIC log, then the detailed display for the entry in question. You are looking for a module name and an offset within it.

Module names follow visible conventions once you have seen a few. Names beginning with <code>#</code> are SLIC-internal modules; the rest are C++ symbols and are mangled, so a name like <code>putSrc__16NuPersistMachineFUtPv</code> decomposes into a method <code>putSrc</code> on class <code>NuPersistMachine</code> taking an unsigned halfword and a pointer.

=== Offline, from installation media ===
When the log does not name a module, or when you want to read the code rather than just identify it, the route runs through [[System Files:QFILEMCD]]:

# '''Extract the segments.''' <code>QFILEMCD</code> contains SLIC as large memory segments stored at the addresses the link loader maps them to.
# '''Build a name index.''' Two structures in the code give you addresses paired with names. Every compilation unit ends with a <code>TBTB</code> traceback trailer, many carrying the unit's name; and the link loader leaves a descriptor block per procedure, with the entry address at <code>+0x08</code> and the name in EBCDIC at <code>+0x38</code>. Merging both across every segment of a V4R4 image gives on the order of 184,000 named records.
# '''Look the address up.''' Prefer descriptor hits, which name exactly one procedure, over traceback hits, which cover a whole compilation unit and so only tell you which module an address is in.
# '''Find who posts the code.''' Because SRC posting is a normal call, you can find every site that posts one by resolving the calls to the <code>IoMF*SystemRefCode</code> constructors and reading what the caller places in the code fields just beforehand.

Step 4 needs one piece of SLIC-specific knowledge. External calls do not go through a dispatch table you can read off. A call is <code>ori r11,r13,''ordinal''</code> followed by <code>bla</code> into a transfer vector at the top of the address space, and the 16-byte stub it lands on computes the target arithmetically from the ordinal. To resolve calls you need the stub constants, which are not derivable and must be read from a dump of the transfer vector segment. With them, every external call in a segment resolves mechanically.

=== A worked example ===
The DST module that verifies the system password illustrates the whole path. Immediately before it calls <code>IoMFGenericSystemRefCode</code>, it does this:

<pre>
li r0, 0x12 ; 18
li r31, 0x21 ; 33
lhz r6, 0x18(r29) ; the password status halfword
cmpwi r6, 0x30
bne ...
sth r0, 0x44(r1) ; status == 0x30 -> code 0x12
b ...
sth r31, 0x44(r1) ; otherwise -> code 0x21
ori r11, r13, 0xd45c
bla ... ; IoMFGenericSystemRefCode
</pre>

Read backwards, this is exactly the inference you want to be able to make. The reference code is chosen from a status halfword; a status of <code>0x30</code> produces one code and anything else produces another. So the two codes are not two unrelated faults but two branches of one test, and knowing which one appeared tells you which branch was taken. Working ''forward'' from the SRC list would never reveal that relationship.

=== What the method will not give you ===
Two honest limits. A traceback trailer names a compilation unit, which may contain many entry points, so it localises rather than pinpoints. And addresses are per-'''build''', not per-release: the same class sits at a completely different address on a machine of another build, so a name index is only valid against the media it was built from. Always match your extracted image to the machine you are investigating, using the build label carried in both container files.

== Why this is worth learning ==
The technique generalises well beyond diagnosing faults. An SRC sequence is an execution trace with names attached, and the machine emits one on every IPL whether or not anything is wrong. Combined with a name index over the LIC image, it lets you ask questions the documentation does not answer — what the machine checks and in what order, which subsystem owns a given behaviour, where a slow phase is actually spending its time — using only a panel display and a copy of the installation media.

== See also ==
* [[System Files:QFILEMCD]]
* [[System Files:QFILEIML]]
* [[Data Structures:LID]]
* [[SRC 0000BBBB]]
* [[Disk device related system reference codes]]
* [[Tape device related system reference codes]]
* [[Panel Usage]]

== Weblinks ==
* [https://www.ibm.com/docs/en/i/7.4.0?topic=finder-system-reference-code-list System reference code list], IBM Documentation
* [https://www.ibm.com/resources/publications/OutputPubsDetails?PubID=SY44590100 AS/400e Service Functions], which documents the panel functions and the IPL progress code sequences

[[Category: System Internals]]

Reverse engineering SLIC

2026-08-16T19:21:11Z

PoC: ±Cat/AI heading

{{AI generated not reviewed}}

Reverse engineering '''SLIC''' — the Licensed Internal Code below the Machine Interface — is mostly a problem of turning addresses into names and getting bytes off the machine. This article collects the techniques that work, in the order you would actually use them, and the traps that cost the most time.

It assumes access to a machine's DST or SST service tools, and installation media or a SAVSYS for offline work.

== Start with the machine's own link map ==
Before writing any tooling, get the '''SLIC link map''' from the machine. It is reached through Display/Alter/Dump and can be printed to a spooled file, then exported.

The printed format is one row per module:

<pre>
NICKNAME ADDRESS(10+6) PART NAME VERSION RELEASE REL DATE/TIME INST DATE/TIME
###FLITE FFFFFFFFF4 C29820 SRVC_MACRO_FLIGHTLOG 0007 0400 20190217 094024 ...
</pre>

A V7R4 machine yields around 21,000 distinct modules. This single artefact answers "what is at this address" and "where is this module" authoritatively, for that machine, and it is the first thing to obtain.

Two properties make it more useful than it first appears:

* '''The spacing between consecutive entries equals the module's text length.''' Verified against the lengths ''Find LIC Module'' reports — exact matches. So the map gives extents as well as bases, which means any address can be resolved to a module ''and'' an offset within it.
* '''Module names are stable across PTFs; addresses are not.''' Look modules up by name whenever possible.

<blockquote>'''Note!''' Part names are upper-cased in the printout but the ''Find LIC Module by name'' panel is '''case-sensitive'''. <code>IoHriTaggedVpd</code> resolves; <code>IOHRITAGGEDVPD</code> does not. Take the spelling from the on-screen display, not the print.</blockquote>

== Getting bytes off the machine ==
Display/Alter/Dump can print a storage range to a spooled file. Exported as PDF and run through <code>pdftotext -layout</code>, each line is an address and 32 bytes:

<pre>
FFFFFFFFC5 943160 3C40CC4DFBC1FFF0 FBE1FFF87C0802A6 F8010028F821FF01 3C000010F8010008
</pre>

<blockquote>'''Note!''' The formatter '''collapses repeated lines''':
<pre>
127 LINES FFFFFFFF84 11B020 TO FFFFFFFF84 11BFE0 SAME AS ABOVE
</pre>
A naive parser silently sees a fraction of the data — in one case 44 % of a 1 MiB region — and reports no error. Any parser must expand these runs.</blockquote>

Dumping a whole module at once is usually better than dumping the function you think you want: module extents are known from the link map, and the surrounding code frequently answers the next question.

== Addresses ==
An SLS address is a '''40-bit segment identifier and a 24-bit offset''', which is exactly how the ''Specify Address'' panel splits it, so segments are 16 MiB.

'''Probe before dumping.''' Entering an address in an unmapped segment returns

<pre>
80 exception, segment does not exist.
</pre>

This is a free existence oracle. But probe the '''address you actually care about''', not offset zero of its segment — segments are sparsely populated, and offset 0 being unmapped says nothing about the rest. A segment can be mapped at <code>0x010000</code> and raise the exception at <code>0x120000</code>.

For a mapped address, the '''ADDRESSINFO''' Advanced Analysis command reports the page-directory entry and hardware page-table entries, confirming backing and page size.

=== Runtime and staged addresses differ ===
The same module may appear at one address in the link map and another as its runtime text. Where these differ, '''module-relative offsets are stable''': a symbol at <code>+0x26d0</code> in the staged image is at <code>+0x26d0</code> in the runtime image. Deriving runtime addresses this way works reliably; assuming a constant delta between two images does not.

== Names from the code ==
Two structures let a container image be turned into a link map offline.

* '''Traceback trailers.''' Every compilation unit ends with a <code>TBTB</code> eyecatcher (<code>E3C2E3C2</code>) followed by a pointer to a descriptor. A trailer covers a whole compilation unit, so it localises rather than pinpoints — and a forward scan for "the next trailer" will silently attribute a ''later'' function's name if the target has no trailer of its own.
* '''Link-loader descriptors.''' Richer: one per procedure, with the entry address at <code>+0x08</code> and the name at <code>+0x38</code>. Names beginning <code>#</code> are SLIC-internal modules; the rest are C++ mangled symbols.

<blockquote>'''Note!''' Two mistakes here are expensive. First, '''do not require the entry address to fall inside a segment the container carries''' — runtime-only segments exist, and filtering on containment silently drops every module in them. Second, the name is not always at a fixed offset from the descriptor; scanning for the longest identifier run within the descriptor is more robust than assuming one.</blockquote>

== Module metadata ==
''Find LIC Module'' reports, for any address: module name, nickname, compile and link/load timestamps, version and release level, '''PTF level''', and the text, data and BSS extents plus the TOC address.

The same record exists on media, anchored by the EBCDIC PTF-level string (<code>SYSBASE</code> for an unpatched module):

<pre>
+0x00 PTF level 7 bytes "SYSBASE"
+0x07 version 4 bytes "0007" = V7
+0x0B release/mod 4 bytes "0400" = R4M0
+0x0F nickname 8 bytes
+0x27 build id 7 bytes "AJDG301"
</pre>

These records cluster in their own segments rather than sitting beside the code they describe. A V7R4 SAVSYS yields about 34,000 of them.

The '''PTF level''' field is the useful one: it distinguishes base modules from patched ones without a changelog, which is exactly what you need when a running machine and its install media disagree on addresses.

<blockquote>'''Note!''' <code>SYSBASE</code> means "no PTF applied to this module" — '''not''' "identical to your install media". Two machines can both report <code>SYSBASE</code> and differ, because base levels themselves differ between RS releases. Compile and link dates make this checkable.</blockquote>

== Calls between modules ==
External calls do not go through a table you can read off.

A call is a two-instruction sequence — an ordinal loaded into <code>r11</code>, then a <code>bla</code> into the '''BLA vector''' at the top of the address space. IBM's own term, from the Static Directory, is ''Pageable BLA'' for the pageable half.

<pre>
V4R4 ori r11,r13,<ordinal> ; bla <vector>
V7R4 li r11,<ordinal> ; bla <vector>
</pre>

The stub reached by the <code>bla</code> computes the target arithmetically:

<pre>
rldicr r11,r11,sh,59 ; ordinal x 4 (V4R4) or x 16 (V7R4)
addis r11,r11,<simm>
mtctr r11
bctr
</pre>

so <code>callee = (sext16(simm) << 16) + (ordinal << sh)</code>. The <code>simm</code> values are not derivable and must be read from the vector — which is not carried in any container, so a dump is required once per build.

The stub array is findable '''structurally''' — runs of 16-byte blocks with three constant words and one varying — which locates it without knowing the shift. Searching for a specific opcode pattern from another release will not find it.

== Reading conditional branches ==

Every policy decision in SLIC is a conditional branch, and getting one backwards silently inverts whatever it decides — the listing looks the same either way. The encoding is ordinary PowerPC, but two things about it are easy to get wrong when reading a listing rather than writing an assembler.

'''<code>BO</code> selects the sense, <code>BI</code> selects the bit.''' <code>BO = 12</code> is branch-if-true and <code>BO = 4</code> is branch-if-false. <code>BI</code> numbers the condition register's bits end to end — <code>BI = 4 × field + bit</code> — and the four bits of a field are, in order, '''LT, GT, EQ, SO'''. So within <code>CR0</code>, <code>BI = 0</code> is LT, '''<code>BI = 1</code> is GT''' and <code>BI = 2</code> is EQ; within <code>CR1</code> the EQ bit is <code>BI = 6</code>.

That matters most after the idiom SLIC tests a policy bit with:

LWZ 4, 1148(16) ; a flag byte out of an object
RLDICL. 3, 4, 0, 63 ; r3 = byte & 0x01, and set CR0
BC 4, 1, ... ; BO=4 branch-if-false, BI=1 GT

<code>RLDICL.</code> leaves 0 or 1 and sets <code>CR0</code> by comparing it against zero, so GT is set exactly when the bit is on, and '''branch-if-not-GT is taken when the bit is CLEAR'''. Read <code>BI = 1</code> as EQ instead and the same branch appears to be taken when the bit is '''set''' — the exact opposite, with nothing in the listing to show which reading is in force.

A routine that uses two condition register fields settles the numbering without any external reference: a dispatch chain alternating <code>CMPI 0,…</code> / <code>BCLR 12,2</code> with <code>CMPI 1,…</code> / <code>BCLR 12,6</code> is comparing a value against a series of constants and returning on each match, which is only a dispatch if <code>BI</code> 2 and 6 are the EQ bits of <code>CR0</code> and <code>CR1</code>.

'''Two rendering traps make listings read backwards.''' Both apply to any disassembler that prints raw encoding fields instead of assembler syntax:

* '''The destination is not always the first operand.''' <code>ADDI</code>, <code>ADD</code> and <code>SUBF</code> print it first; the logical forms <code>ORI</code>, <code>AND</code> and <code>ANDC</code> print <code>rS</code> first and the destination <code>rA</code> '''second'''. A load/modify/store triple is the giveaway: <code>LBZ 27,28(28)</code> / <code>ORI 27,26,1</code> / <code>STB 26,28(28)</code> only makes sense as "load into r27, or in 1 giving r26, store r26". Read left to right, whole routines look like a run of dead stores.
* '''The <code>Rc</code> dot can go missing.''' <code>rlwinm.</code> and <code>rlwimi.</code> do set <code>CR0</code>, but a decoder that appends the dot only for primary opcode 31 prints them without it — and then the branch after them looks like it is testing a condition register nothing wrote. Check bit 31 of the raw word before concluding a test is stale.

== Traps worth knowing ==
* '''Never resolve a live pointer against a container image.''' A pointer read from a running machine names a runtime address; dereferencing it in a saved image lands on unrelated data and produces a plausible, wrong answer.
* '''Verify cross-image mappings by content, at the address you intend to use.''' A delta confirmed at one address does not hold across a segment.
* '''A positional coincidence looks exactly like a structural fact.''' Runs of plausible-looking pointers, matching offsets and familiar constants all occur by chance in images this size. Confirm with bytes.
* '''TOC contents are filled in at IPL.''' Container images hold unrelocated placeholders, so a TOC walk is only meaningful against live storage.
* '''Decode <code>BO</code> and <code>BI</code> from the raw word before believing a branch, and record the sense you decoded.''' A branch that decides a policy bit is worth the thirty seconds; getting it wrong produces working-looking code that does the opposite of what the machine does, and the mistake survives review because the reasoning around it was written to match. See [[#Reading conditional branches]].
* '''A field the machine rebuilds at startup is an output, not an input.''' Configuration areas on disk are often regenerated from the machine's live configuration during power-on, and the code that later reads one may also stamp it on the way past. Reading such a field back as though it decided something is the same tautology as a model agreeing with its only caller, moved from code into data — and it is unusually convincing, because the value really is there and really is self-consistent. Establish who last wrote a field before deciding what it means.

== See also ==
* [[System Files:QFILEMCD]]
* [[System Files:QFILEIML]]
* [[Data Structures:LID]]
* [[SRC]]

[[Category: System Internals]]
[[Category:AI generated not reviewed]]

File Formats:SAVF

2026-08-16T19:20:59Z

PoC: ±Cat/AI heading

{{AI generated not reviewed}}
A '''SAVF''' (''save file'') is the container OS/400 and IBM i write with <code>SAVOBJ</code> and <code>SAVLIB</code>, and read back with <code>RSTOBJ</code> and <code>RSTLIB</code>. It holds Machine Interface objects — programs, files, data areas, libraries — in the form they have on disk, together with a catalogue describing what was saved and from which machine.

Understanding the format is useful well beyond restoring a save file on a machine. It is the only practical way to get at the bytes of an MI object ''offline'': the same byte stream also appears inside optical images and tape images, so a distribution medium, a PTF, or a backup is an extractable archive of real MI objects. What can be done with one once it is extracted is described in [[File Formats:PGM]] for programs.

Everything below is big endian, and every text field is EBCDIC.

== Three layers ==
It helps to separate three things that are often run together:

* the '''chunk''' layer, which wraps the save stream in 528-byte units with a checksum on each;
* the '''item''' layer, which is a chain of saved objects, each a 512-byte descriptor followed by that object's segments;
* the '''catalogue''', a single special item per save that lists the library and its objects.

Only the chunk layer is specific to a save file held in <code>QSYS</code>. When the same save is carried on optical or tape media, the chunk wrapper is absent and the item chain sits in the medium directly. A reader that separates the layers handles all three media with one item parser.

== The chunk layer ==
A save file is exactly ''chunk count'' × 528 bytes. Chunk ''n'', counting from zero, begins at file offset <code>n × 528</code> and consists of 512 bytes of save-stream data followed by a 16-byte checksum. The logical save stream is the concatenation of the data halves, so translating a stream offset to a file offset is

<pre>
file_offset = (stream_offset / 512) * 528 + (stream_offset % 512)
</pre>

=== File header ===
The first 512 bytes of the stream — which are also the data half of chunk 1 — describe the container.

{|class="wikitable"
!Offset
!Size
!Field
!Notes
|-
|<code>+0x00</code>
|8
|MI creation timestamp
|Also the seed for every chunk checksum.
|-
|<code>+0x08</code>
|4
|Chunk count
|32-bit form.
|-
|<code>+0x10</code>
|8
|Machine type and model
|EBCDIC, model first: <code>42A 8286</code> is an 8286-42A.
|-
|<code>+0x30</code>
|4
|Release level
|-
|<code>+0x34</code>
|4
|Header length
|The first item starts here. Zero means 512.
|-
|<code>+0x38</code>
|8
|Chunk count
|64-bit form, used when the 32-bit field would overflow.
|-
|<code>+0x40</code>
|16
|Global checksum backup
|See below.
|}

A valid file satisfies <code>chunk count == file size / 528</code>; anything else means truncation. Because the header is itself chunk 1, verifying its checksum is the cheapest reliable test of whether a file is a save file at all.

=== The global checksum displaces real data ===
This is the trap worth knowing about before writing any extractor. The last 16 bytes of the ''logical'' stream, at <code>chunk count × 512 − 16</code>, are overwritten with a whole-file checksum. The data bytes they replaced are preserved in the file header at <code>+0x40</code>, and a reader must put them back. A reader that does not will silently corrupt the tail of the last object it extracts, in a way that no chunk checksum will catch, because the chunk checksums are computed over the overwritten bytes.

=== The chunk checksum ===
Each chunk's 16-byte trailer is the chunk number, counting from one, as a 4-byte big-endian integer, followed by a 12-byte digest. The digest is two folding passes built from a single primitive:

<pre>
chkadd(a, b): # b is exactly one byte longer than a
b[1:] += a << 1 # big-endian magnitudes, carry propagated
b[0] += carry + (the bit shifted out of the top of a)
</pre>

The first pass takes the chunk number followed by the 512 data bytes and cuts them into eight parts of 61, 62, 63, 64, 65, 66, 67 and 68 bytes, then folds them in ascending order: <code>chkadd</code> of the 61-byte part into the 62-byte part, that into the 63-byte part, and so on. The second pass takes the resulting 68 bytes, cuts them into parts of 5, 6, 7, 8, 9, 10, 11 and 12 bytes, and folds them the same way, leaving 12 bytes. The first 8 of those are then XORed with the file header's MI timestamp.

There is one non-obvious detail. In both passes the parts are ''filled'' from the input in the order 61, 62, 63, 64, 65, 66, '''68, 67''' — and 5, 6, 7, 8, 9, 10, '''12, 11''' — while being ''folded'' in ascending order. An implementation that fills them in plain ascending order produces a plausible-looking wrong answer.

The construction is a checksum, not a cryptographic hash. It detects media damage. It is not a tamper seal, and it carries no secret beyond a timestamp printed in the same header.

== The item layer ==
Items are chained: parse the descriptor at the header length, add the item's computed length, repeat, and stop when the next item would begin past <code>(chunk count − 1) × 512</code>. Every descriptor begins with <code>FFFFFFFF</code>, which makes resynchronising after damage feasible.

=== Item descriptor ===
{|class="wikitable"
!Offset
!Size
!Field
!Notes
|-
|<code>+0x00</code>
|4
|<code>FFFFFFFF</code>
|Eyecatcher.
|-
|<code>+0x04</code>
|10
|Object name
|EBCDIC. Replaced by a file ID for integrated file system objects.
|-
|<code>+0x0E</code>
|20
|Member name
|Empty unless the object has members.
|-
|<code>+0x22</code>
|2
|MI object type
|The same code space used throughout the machine: <code>0x0201</code> <code>*PGM</code>, <code>0x0401</code> <code>*LIB</code>, <code>0x1901</code> <code>*FILE</code>, <code>0x19DB</code> <code>*SRDS</code>.
|-
|<code>+0x24</code>
|1
|Flags
|Bit <code>0x40</code> or <code>0x80</code> means the item is an IFS object.
|-
|<code>+0x25</code>
|3
|Catalogue offset
|Where this object's entry sits inside the catalogue.
|-
|<code>+0x44</code>
|4
|Header occupation
|Bytes of the descriptor page actually used.
|-
|<code>+0x48</code>
|4
|Stored length
|In 512-byte units, minus one.
|-
|<code>+0x54</code>
|2
|Release created for
|Governs the section-entry layout below.
|-
|<code>+0x56</code>
|4
|Metadata length
|For a catalogue item, the size of the catalogue.
|-
|<code>+0x64</code>
|4
|Section count
|-
|<code>+0xC0</code>
|8
|Save timestamp
|-
|<code>+0xCC</code>
|4
|Total length
|In 512-byte units.
|-
|<code>+0xD4</code>
|4
|Data length
|In 512-byte units. Always the total length less 4096 bytes.
|-
|<code>+0x100</code>
|14 × 8
|Pointer array
|See below.
|-
|<code>+0x170</code>
|8
|Packed length
|Stored as the length less 512.
|}

The pointer array holds single-level store addresses, but only the low 24 bits matter: they are an offset into the item, biased by 4096, so <code>(pointer & 0xFFFFFF) − 4096</code> gives an offset within the descriptor page. Index 1 locates the section length table and index 8 the section type table.

=== Sections ===
A saved MI object is a set of segments, and each segment is one ''section'' of the item. Sections start at the first 4096-byte boundary after the descriptor and run consecutively, which is why the data length is always the total length less one page.

The length table has one entry per section. On any modern release — when the ''release created for'' field exceeds 32 — an entry is 16 bytes: capacity, length, and the segment's single-level store address. Older saves use a 10-byte entry with a shifted 6-byte address and no separate length.

The type table has one 8-byte entry per section, of which the first halfword is the segment type. This is the '''same value as the first halfword of the segment's own segment header''', which is a useful consistency check when extracting: the item's idea of what a section is must agree with the segment's own.

=== Item length and compression ===
An uncompressed item occupies its stored length. A packed item records a non-zero packed length, and the writer then realigns the following item on the enclosing 512-byte boundary, so the step from one item to the next is

<pre>
if packed == 512: step = stored
elif packed > stored: step = packed
else:
slack = stored - packed
within = item_offset % 512
if within == 0: step = stored
elif within < slack: step = packed + slack - within
else: step = stored + 512 - within
</pre>

The compression method is identifiable from the first six bytes of the packed data, which are EBCDIC eyecatchers:

{|class="wikitable"
!Bytes
!EBCDIC
!<code>DTACPR</code>
|-
|<code>D3C46DE3D9E2</code>
|<code>LD_TRS</code>
|<code>*MEDIUM</code>, the TERSE algorithm
|-
|<code>D3C46DD3E9F1</code>
|<code>LD_LZ1</code>
|<code>*HIGH</code>, IBM's LZ1
|-
|<code>D3C46DE9D3C2</code>
|<code>LD_ZLB</code>
|<code>*ZLIB</code>; the deflate stream begins 12 bytes in
|-
|none
|
|<code>*LOW</code>, an SNA-style run-length scheme, recognisable only by decoding it
|}

Note that these are ''not'' the compression used for a compressed LID payload; see [[Data Structures:LID]], where all four of these were tried and rejected.

== The catalogue ==
Every save writes one save/restore descriptor space item, MI type <code>0x19DB</code>, named <code>QSRDSSPC.''n''</code>, ahead of the objects it describes. Items named <code>QSR.ADDITIONAL_INFO.*</code> or <code>QSRDSSPC.EA SRD*</code> are continuation blocks belonging to the preceding descriptor, not new saves.

The catalogue itself is the '''last''' ''metadata length'' bytes of that item's data. Its first byte is the save command, and that selects the shape: a library save has the layout below, while a save of the integrated file system produces a different, tree-structured descriptor.

{|class="wikitable"
!Offset
!Size
!Field
|-
|<code>+0x00</code>
|1
|Save command
|-
|<code>+0x01</code>
|1
|Target release
|-
|<code>+0x02</code>
|30
|Saved library name
|-
|<code>+0x20</code>
|2
|Base object type, <code>0x0401</code>
|-
|<code>+0x22</code>
|8
|Save timestamp
|-
|<code>+0x2A</code>
|4
|Object count
|-
|<code>+0x34</code>
|8
|System serial number
|-
|<code>+0x3C</code>
|2
|ASP number
|-
|<code>+0x3E</code>
|10
|Create authority
|-
|<code>+0x4C</code>
|1
|Save-while-active indicator
|-
|<code>+0x50</code>
|10
|ASP name, target release 66 and later only
|}

Object descriptors follow, at <code>+0x50</code> or at <code>+0x70</code> when the ASP name is present. Each is 151 bytes on target release 49 and later, and 87 bytes before that. The first fields are the object name at <code>+0x00</code> for 30 bytes, the MI object type at <code>+0x1E</code>, and the owning user profile at <code>+0x20</code> for 10 bytes. The size is a 4-byte field at <code>+0x43</code>, multiplied by a second 4-byte field at <code>+0x79</code> when that is non-zero. The remainder of the descriptor holds offsets, into the same buffer, of chains of length-prefixed records carrying the object's text description, service description, usage information, work-unit references and user information.

Worth noticing for its own sake: the catalogue records the '''serial number of the machine that produced the save'''. A save file is not anonymous.

== Practical consequences ==
* Any MI object can be lifted out of a save file byte for byte, with its segments separated and their segment identifiers intact. That is what makes offline analysis of a program object possible without console access to a machine and without printing a storage dump.
* Verifying the chunk checksums is a genuine integrity check on an archived save file, and can be done without a machine.
* The item chain and the catalogue are independent descriptions of the same set of objects. Where they disagree, the file has been damaged or truncated.
* Because the chunk layer is only present for a save file held in <code>QSYS</code>, a save carved out of an optical or tape image is parsed by the same code with the chunk translation switched off.

== Scope of this description ==
The layout was mapped with reference to jSAVF, an independently developed third-party reader, and then verified field by field against a real V7R4 save file. Where an object in that file also had a printed Display/Alter/Dump available, the bytes extracted here matched the printout exactly. The chunk checksum was reimplemented from scratch and verifies every chunk of the test file.

Not established: the meaning of the 4-byte field at <code>+0x0C</code> of the file header, the layout of the integrated file system catalogue, and the LZ1 and TERSE decompressors.

== Weblinks ==
* [https://www.anerty.net/software/file/jSAVF/?lang=en jSAVF] — a maintained third-party reader for save files, and the starting point for the layout described here.

[[Category: System Internals]]

File Formats:PGM

2026-08-16T19:20:34Z

PoC: ±Cat/AI heading

{{AI generated not reviewed}}
A '''<code>*PGM</code>''' is a Machine Interface ''program object''. It is not a file with a text section and a symbol table. It is a set of single-level store '''segments''', chained together by 8-byte SLS pointers, with the executable instructions embedded in the first segment among the metadata that describes them.

This page describes enough of that structure to walk a program object offline — that is, without a console session and without printing a storage dump for every object of interest. The bytes can come from a [[File Formats:SAVF|save file]], which makes any distribution medium, PTF or backup a source of real program objects to examine.

Everything below is big endian, and text fields are EBCDIC.

== Addressing ==
Pointers are 8 bytes: a 40-bit segment identifier in the high bits and a 24-bit offset in the low bits, so a segment is 16 MiB. This is the same split used throughout the machine, including by the DST ''Display/Alter storage'' panel and by the SLS address field of a [[Data Structures:LID|LID]] directory record.

<pre>
segment = pointer >> 24
offset = pointer & 0xFFFFFF
</pre>

An all-zero pointer means the object has no data for that structure. That is precisely what the <code>###INFO: OBJECT DOES NOT CONTAIN DATA FOR THIS SECTION</code> line in a Display/Alter/Dump printout is reporting.

Some fields are not pointers but '''<code>SEGOFF</code>''' pairs: a 4-byte segment ''index'', counting from one into the object's own segment table, followed by a 4-byte offset. These appear where a genuine pointer would have to be relocated when the object moves.

The segments of one program have unrelated segment identifiers. A decoder therefore needs the whole set: a single segment cannot resolve its own pointers.

== Segments ==
A single-module bound program typically has four segments, distinguished by the type field in each segment's own header:

{|class="wikitable"
!Type
!Role
|-
|<code>0x0001</code>
|The program object proper: all headers, tables, and the instruction stream.
|-
|<code>0x0022</code>
|Module constants and the module string directory.
|-
|<code>0x0018</code>
|Static storage.
|-
|<code>0x0028</code>
|Trace-back and mapping data.
|}

Note that a program's segment table records a segment ''use'' code, while each segment's own header records a ''type''. They are different numberings and should not be conflated.

=== Segment header ===
Every MI segment opens with a header, called <code>YYSGHDR</code> in IBM's own dump formatting.

{|class="wikitable"
!Offset
!Size
!Field
|-
|<code>+0x00</code>
|2
|Segment type
|-
|<code>+0x02</code>
|2
|Size, in 512-byte units
|-
|<code>+0x04</code>
|1
|New flags
|-
|<code>+0x05</code>
|1
|Flags
|-
|<code>+0x08</code>
|8
|Address of the owning object
|-
|<code>+0x18</code>
|8
|Space address
|}

=== Object header ===
Immediately after it, at <code>+0x20</code> of the first segment, sits the object header, <code>YYEPAHDR</code>. Offsets below are relative to it.

{|class="wikitable"
!Offset
!Size
!Field
!Notes
|-
|<code>+0x02</code>
|1
|MI object type
|Together with the next byte, <code>0x0201</code> for a program.
|-
|<code>+0x03</code>
|1
|MI object subtype
|
|-
|<code>+0x04</code>
|30
|Object name
|EBCDIC.
|-
|<code>+0x24</code>
|4
|Space size
|
|-
|<code>+0x30</code>
|8
|Creation timestamp
|
|-
|<code>+0x38</code>
|8
|Owning user profile
|A pointer to the profile object.
|-
|<code>+0x48</code>
|8
|Context
|That is, the library.
|-
|<code>+0x50</code>
|8
|Object space
|'''The pointer to the program header.''' Everything else hangs off this.
|-
|<code>+0x5A</code>
|2
|ASP
|
|-
|<code>+0x60</code>
|8
|Last-modified timestamp
|
|}

The type and subtype pair uses the same code space as the item descriptors in a save file, so one table of MI type codes serves both.

== The program header ==
Found through the object header's object-space pointer; in practice it sits at offset <code>0x1000</code> of the first segment.

{|class="wikitable"
!Offset
!Size
!Field
|-
|<code>+0x00</code>
|8
|Program attributes
|-
|<code>+0x08</code>
|8
|Pointer to the version table
|-
|<code>+0x10</code>
|8
|Pointer to the segment table
|-
|<code>+0x18</code>
|8
|Pointer to the activation header
|-
|<code>+0x20</code>
|8
|Pointer to the signature table
|-
|<code>+0x28</code>
|8
|Pointer to the program string directory
|-
|<code>+0x30</code>
|8
|Pointer to activation group information
|-
|<code>+0x40</code>
|8
|Activation start
|-
|<code>+0x48</code>
|8
|Activation end
|-
|<code>+0x50</code>
|8
|'''Activation and PEP end''' — the last byte of the code
|-
|<code>+0x58</code>
|2
|Flags
|-
|<code>+0x5C</code>
|2
|Program state
|-
|<code>+0x90</code>
|1
|Program type
|-
|<code>+0x94</code>
|4
|Program entry procedure module number
|-
|<code>+0x9C</code>
|4
|Program entry procedure string ID
|-
|<code>+0xA0</code>
|2
|Minimum parameters
|-
|<code>+0xA2</code>
|2
|Maximum parameters
|-
|<code>+0xD0</code>
|8
|Pointer to the program header extension
|-
|<code>+0xD8</code>
|8
|Pointer to the trace-back locator
|-
|<code>+0xE0</code>
|8
|Pointer to the module table
|-
|<code>+0xE8</code>
|8
|Pointer to observability information
|-
|<code>+0xF0</code>
|8
|Pointer to the maintenance header
|}

The header extension adds a pointer to the GLU code list, <code>SEGOFF</code> pairs for the program history and the segment table extension, and a 16-byte hardware feature set at <code>+0x50</code>.

=== Version table ===
Forty bytes of packed version-release-modification halfwords, where <code>0x0740</code> reads as V7R4M0. Among them are the binder's internal and MI levels at <code>+0x02</code> and <code>+0x04</code>, the '''target''' release at <code>+0x06</code>, the '''created-on''' release at <code>+0x08</code>, the language release at <code>+0x10</code>, the CCSID at <code>+0x1E</code> and the low and high optimisation levels at <code>+0x20</code> and <code>+0x22</code>.

The target and created-on values here are what decide whether an object will restore onto a given release, so they are worth reading before attempting a restore that might fail.

=== Segment table ===
A header of allocated size, entry count and version, then the entries beginning at <code>+0x10</code>. '''Entries are a fixed 48 bytes'''; the size field is the allocation, not header plus count times entry, so deriving the stride from it gives the wrong answer.

Each entry holds the segment address at <code>+0x00</code>, a limbo address at <code>+0x08</code>, a declared page count at <code>+0x10</code>, and a one-byte ''segment use'' at <code>+0x12</code>: <code>0x01</code> static storage, <code>0x02</code> the program object, <code>0x04</code> constants, <code>0x06</code> trace-back.

A parallel ''segment table extension'', reached by a <code>SEGOFF</code> in the program header extension, records how much of each segment is actually used as opposed to allocated. Its entries begin at <code>+0x18</code> and are 24 bytes, of which the first four are the byte count.

=== Activation header ===
{|class="wikitable"
!Offset
!Size
!Field
|-
|<code>+0x00</code>
|8
|'''Program entry procedure entry point''' — the first instruction
|-
|<code>+0x08</code>
|4
|PBV size
|-
|<code>+0x10</code>
|8
|Pointer to the PBV relocation array
|-
|<code>+0x18</code>
|8
|Pointer to the static PBV array
|-
|<code>+0x20</code>
|4
|PBV relocation count
|-
|<code>+0x24</code>
|4
|Dependent service program count
|-
|<code>+0x28</code>
|8
|Pointer to the dependent service program array
|-
|<code>+0x4C</code>
|4
|Constant frame count
|-
|<code>+0x50</code>
|8
|Pointer to the constant frame definition array
|-
|<code>+0x58</code>
|8
|Pointer to the program export array
|-
|<code>+0x60</code>
|4
|Export count
|}

For a bound program with no exports most of these are zero. For a service program they are the published interface, and the dependent service program array is the object's dependency list — which makes it possible to work out what a program binds to without a machine to run <code>DSPPGM</code> on.

=== Maintenance header ===
Holds the copyright list size and count and a <code>SEGOFF</code> to the copyright text — a 4-byte length followed by EBCDIC — along with <code>SEGOFF</code> pairs for the external object list, static activation and export information, the last non-observable segment and size, and the lowest and highest PBV identifiers.

== Modules ==
The module table has the same shape as the segment table: header, then 48-byte entries from <code>+0x10</code>, each giving a pointer to a module header, a module domain and a module subtype.

A module header is a long run of pointers: to the program header it belongs to, the copyright table, the module version table, binding information, static information, the end-of-line table, observability information, the module string directory, the entry point table, the VLIC table, the procedure table, module constants, and the module header extension. It also carries the module type at <code>+0x01</code> — <code>0x01</code> for OPM and <code>0x03</code> for ILE — the module attributes at <code>+0xA8</code>, and the program entry procedure's dictionary ID, string ID, procedure number and parameter counts from <code>+0xAC</code> to <code>+0xBC</code>.

Two of its pointers characteristically leave the program segment: the module string directory and the module constants both live in the <code>0x0022</code> segment. When hunting for literal data referenced by the code — message identifiers, format names, table constants — that is the segment to search, and these two pointers give its exact extent.

=== Module version table ===
This is the most immediately informative structure in the whole object.

{|class="wikitable"
!Offset
!Size
!Field
|-
|<code>+0x02</code>
|2
|Language release
|-
|<code>+0x0A</code>
|2
|Instruction release
|-
|<code>+0x0C</code>
|2
|Target release
|-
|<code>+0x0E</code>
|2
|Created-on release
|-
|<code>+0x10</code>
|2
|Optimisation level
|-
|<code>+0x14</code>
|30
|Source module name
|-
|<code>+0x32</code>
|30
|Source module qualifier
|-
|<code>+0x50</code>
|20
|Compiler name
|-
|<code>+0x64</code>
|2
|Earliest compiler release
|}

Read the compiler name before spending any time on a disassembly. A module reporting <code>MX CONVERTED</code> was ''translated'' from an older object rather than compiled from source at this release, and the generated code will not resemble what a current compiler emits.

== The instruction stream ==
The code is a single contiguous run inside the first segment, bounded by two fields already listed above:

<pre>
start = activation header, program entry procedure entry point
end = program header, activation and PEP end (inclusive)
</pre>

It is 64-bit big-endian '''PowerPC AS'''. A stock disassembler invoked as <code>objdump -D -b binary -m powerpc:common64 -EB</code>, with the load address adjusted to the start offset, will produce a listing whose addresses line up with anything printed by Display/Alter/Dump.

Two caveats apply, and both matter.

PowerPC AS is not plain PowerPC. The tagged-pointer instructions and other AS-only operations have no encoding in a stock PowerPC disassembler and will appear as invalid, or worse, as an unrelated mnemonic that looks plausible. Treat such a listing as a starting point rather than as authority.

The run is also not pure code. Trace-back tables and constants are interleaved with instructions, so a linear sweep will decode data as code somewhere. For an object that still has its observability information, the trace-back locator and the module tables provide the boundaries needed to separate the two; for an object whose observability has been removed, they do not, and the separation has to be inferred from the code itself.

== Scope of this description ==
Field offsets were derived by lining a printed Display/Alter/Dump of a program object up against the same object's bytes extracted from a save file, and then checked by decoding the object independently and comparing every field against the printout. Structures that the dump prints but that were empty in the object used — the signature table, the export and import arrays, the service program tables and the secondary entry point table — are located by pointer but their contents are not described here; establishing those needs a service program to work from.

Only <code>*PGM</code> is covered. <code>*SRVPGM</code> and <code>*MODULE</code> share much of this layout but have additional tables of their own.

== See also ==
* [[File Formats:SAVF]] — how to get a program object's bytes off a machine or out of a distribution medium
* [[Data Structures:LID]] — the same single-level store address split, in a different container

[[Category: System Internals]]

Data Structures:LID

2026-08-16T19:20:11Z

PoC: ±Cat/AI heading

{{AI generated not reviewed}}
A '''LID''' (''Load ID'') is IBM's general-purpose container for shipping a blob of code or data to a machine. It is not specific to any one file, release, or processor architecture: the same 32-byte directory record describes SLIC modules, IOP and adapter microcode, and service processor firmware, and the same idea survives into modern POWER hardware.

Because the record format is shared between several container files, it is documented here once rather than repeated in each. The container that uses it is described in [[System Files:QFILEIML]].

== The directory record ==
A LID container consists of a header, a directory of fixed 32-byte records, and the payloads. Every record has the following layout. All fields are big endian.

{|class="wikitable"
!Offset
!Size
!Field
!Notes
|-
|<code>+0x00</code>
|4
|LID identifier
|Not a sequence number. The high halfword is a ''family'' — see below.
|-
|<code>+0x04</code>
|4
|Offset
|In 512-byte blocks. '''Base and meaning depend on the container''' — see the warning below.
|-
|<code>+0x08</code>
|4
|Length
|In 512-byte blocks.
|-
|<code>+0x0C</code>
|4
|Flags
|<code>0x80000000</code> = compressed. No other bit has been observed set.
|-
|<code>+0x10</code>
|8
|SLS address
|Where the payload is to be staged in single-level store.
|-
|<code>+0x18</code>
|4
|Time
|Packed BCD <code>HHMM</code>; read the field as hexadecimal to display it. <code>0x00001757</code> is 17:57.
|-
|<code>+0x1C</code>
|4
|Date
|Packed BCD <code>YYYYMMDD</code>, likewise. <code>0x19970318</code> is 1997-03-18.
|}

The directory is terminated by a record whose identifier field is <code>0xC5D5C440</code>, which is the EBCDIC string <code>END </code>. A zero identifier also terminates.

<blockquote>'''Note!''' The '''offset''' field is the field most likely to mislead. It is ''not'' universally a byte or block offset into the container file. In the <code>IMD1</code> container it is a load-source LBA — an address on the installation medium — and is meaningless as a file offset; payloads there are instead laid out sequentially in directory order. See [[System Files:QFILEIML]] for the worked case. Always establish the addressing base for a given container before extracting anything.</blockquote>

=== Worked example ===
The first record of the <code>IMD1</code> directory in a V4R4 <code>QFILEIML</code>, at file offset <code>0x420</code>:

<pre>
00000420: 8070 0830 0000 0210 0000 0004 0000 0000
00000430: ffff ffff 9300 1000 0000 1757 1997 0318
</pre>

decodes as LID <code>80700830</code>, offset block 528, length 4 blocks (2 KiB), flags 0 (not compressed), SLS address <code>FFFFFFFF93 001000</code>, timestamp 1997-03-18 17:57.

That same record appears byte for byte as the sixth LID of <code>QFILEMCD</code>'s nested <code>COPYDIR</code> LID directory, which is what establishes that the two containers share one record format.

== The SLS address field ==
The 8-byte address is a single-level store address, split 40/24 into a segment identifier and a byte offset within the segment, so segments are 16 MiB. Printed with that split, the example above is segment <code>FFFFFFFF93</code>, offset <code>0x001000</code>. This is the same notation the DST ''Display/Alter storage'' panel accepts.

The <code>FFFFFFFFxx</code> band is resident Licensed Internal Code. Note that a segment identifier recorded in a directory is the ''load source'' segment — where the payload was saved from, or is staged into — which is not necessarily the segment the code eventually executes in. Payloads destined for an IOP or the service processor are staged into a SLIC segment first and then transferred over the bus to the target card, so an <code>FFFFFFFFxx</code> address does '''not''' imply the payload is SLIC code.

== LID identifier families ==
The identifier is structured rather than sequential: the high halfword groups LIDs into families, and members of a family share a purpose. In a V4R4 <code>QFILEIML</code> the most populous families are:

{|class="wikitable"
!Family
!Records
!Observed contents
|-
|<code>a170</code>
|144
|Not established
|-
|<code>a0b0</code>
|66
|Not established
|-
|<code>a100</code>
|56
|Not established
|-
|<code>8190</code>
|54
|Not established
|-
|<code>a0c0</code>
|37
|Not established
|-
|<code>8390</code>
|36
|Not established
|-
|<code>a090</code>
|33
|Largely 32-bit PowerPC firmware images
|-
|<code>8590</code>
|30
|Largely 32-bit PowerPC firmware images
|-
|<code>8090</code>
|29
|Mixed; includes the service processor firmware and the two large SLIC LIDs
|}

The purpose of most families has not been established. The <code>80xxxxxx</code> range is the only one <code>QFILEMCD</code> uses.

== The compressed flag ==
Bit <code>0x80000000</code> marks a payload as compressed. The codec is the LZW variant implemented in SLIC by the routines <code>LZdcomp</code> and <code>cpdcomp</code>, which supports 9-, 10- and 12-bit codes and dispatches on a leading format byte of <code>0x11</code> or <code>0x21</code>. It is '''not''' any of the OS/400 <code>*LOW</code>, <code>*MEDIUM</code> or <code>*HIGH</code> save-file compression methods, nor zlib or raw deflate; all of those have been tried against real payloads and fail immediately.

The flag should be treated as advisory rather than exact. In one V4R4 <code>QFILEIML</code>, 31 payloads carry the compressed flag yet begin with clean, plainly readable 32-bit PowerPC function prologues. Whatever the flag governs, it is not a simple "this entire payload is one compressed stream".

== Containers and consumers ==
* '''<code>COPYDIR</code>''', the directory in <code>QFILEMCD</code>, carries SLIC itself as a nested LID directory.
* '''<code>IMD1</code>''', the format of [[System Files:QFILEIML]], carries IOP, adapter and service processor microcode alongside SLIC modules.
* SLIC contains an interactive '''LID filesystem'''. The commands <code>IdeLidFileSystem</code>, <code>IdeCopyLidCmd</code>, <code>IdeFindLidCmd</code>, <code>IdeVerifyLid</code>, <code>IdeCompressLidCmd</code>, <code>IdeDecompressLidCmd</code>, <code>IdeLidListCmd</code> and <code>IdeMakeTempLidCmd</code> all appear in a V4R4 name index, so a LID is a first-class object to the machine rather than merely an installation-media artefact.
* Adapter and IOP classes in SLIC expose a <code>downLoadLid</code> method, which is the mechanism by which a staged LID reaches the card.
* On modern POWER hardware the '''flexible service processor''' holds a filesystem of LIDs containing the hypervisor, the Open Firmware image used by AIX and Linux partitions, the component that replaces the physical front panel, and adapter firmware for several third-party network and storage cards.<ref>Reported by a machine owner familiar with FSP internals; not independently verified here, but consistent with IBM's evident reuse of the container across generations.</ref>

== Scope of this description ==
Everything above was read from a single V4R4 installation image and cross-checked between its two container files. Field offsets, sizes and the terminator are considered established. Family meanings, and the exact semantics of the compressed flag, are not.

== See also ==
* [[System Files:QFILEIML]]
* [[CISC AS/400 LIC Tapes]]

== Footnotes ==
<references />

[[Category: System Internals]]

Template:AI generated not reviewed

2026-08-16T19:17:42Z

PoC: New

<div id="Template_AI">
{|width="100%" border="0" cellspacing="8" cellpadding="0" style="border: 1px solid #e94949; font-size: 95%; margin-top: 2px; margin-bottom: 2px; clear: both"
|style="width: 24px" | [[File:Qsicon Fixme.png|24px]]
|This article has been generated or amended by AI and not yet been checked for correctness.
|}
</div>
[[Category:AI generated not reviewed]]

Data Structures:LID

2026-08-16T19:09:09Z

PoC: +cat

A '''LID''' (''Load ID'') is IBM's general-purpose container for shipping a blob of code or data to a machine. It is not specific to any one file, release, or processor architecture: the same 32-byte directory record describes SLIC modules, IOP and adapter microcode, and service processor firmware, and the same idea survives into modern POWER hardware.

Because the record format is shared between several container files, it is documented here once rather than repeated in each. The container that uses it is described in [[System Files:QFILEIML]].

== The directory record ==
A LID container consists of a header, a directory of fixed 32-byte records, and the payloads. Every record has the following layout. All fields are big endian.

{|class="wikitable"
!Offset
!Size
!Field
!Notes
|-
|<code>+0x00</code>
|4
|LID identifier
|Not a sequence number. The high halfword is a ''family'' — see below.
|-
|<code>+0x04</code>
|4
|Offset
|In 512-byte blocks. '''Base and meaning depend on the container''' — see the warning below.
|-
|<code>+0x08</code>
|4
|Length
|In 512-byte blocks.
|-
|<code>+0x0C</code>
|4
|Flags
|<code>0x80000000</code> = compressed. No other bit has been observed set.
|-
|<code>+0x10</code>
|8
|SLS address
|Where the payload is to be staged in single-level store.
|-
|<code>+0x18</code>
|4
|Time
|Packed BCD <code>HHMM</code>; read the field as hexadecimal to display it. <code>0x00001757</code> is 17:57.
|-
|<code>+0x1C</code>
|4
|Date
|Packed BCD <code>YYYYMMDD</code>, likewise. <code>0x19970318</code> is 1997-03-18.
|}

The directory is terminated by a record whose identifier field is <code>0xC5D5C440</code>, which is the EBCDIC string <code>END </code>. A zero identifier also terminates.

<blockquote>'''Note!''' The '''offset''' field is the field most likely to mislead. It is ''not'' universally a byte or block offset into the container file. In the <code>IMD1</code> container it is a load-source LBA — an address on the installation medium — and is meaningless as a file offset; payloads there are instead laid out sequentially in directory order. See [[System Files:QFILEIML]] for the worked case. Always establish the addressing base for a given container before extracting anything.</blockquote>

=== Worked example ===
The first record of the <code>IMD1</code> directory in a V4R4 <code>QFILEIML</code>, at file offset <code>0x420</code>:

<pre>
00000420: 8070 0830 0000 0210 0000 0004 0000 0000
00000430: ffff ffff 9300 1000 0000 1757 1997 0318
</pre>

decodes as LID <code>80700830</code>, offset block 528, length 4 blocks (2 KiB), flags 0 (not compressed), SLS address <code>FFFFFFFF93 001000</code>, timestamp 1997-03-18 17:57.

That same record appears byte for byte as the sixth LID of <code>QFILEMCD</code>'s nested <code>COPYDIR</code> LID directory, which is what establishes that the two containers share one record format.

== The SLS address field ==
The 8-byte address is a single-level store address, split 40/24 into a segment identifier and a byte offset within the segment, so segments are 16 MiB. Printed with that split, the example above is segment <code>FFFFFFFF93</code>, offset <code>0x001000</code>. This is the same notation the DST ''Display/Alter storage'' panel accepts.

The <code>FFFFFFFFxx</code> band is resident Licensed Internal Code. Note that a segment identifier recorded in a directory is the ''load source'' segment — where the payload was saved from, or is staged into — which is not necessarily the segment the code eventually executes in. Payloads destined for an IOP or the service processor are staged into a SLIC segment first and then transferred over the bus to the target card, so an <code>FFFFFFFFxx</code> address does '''not''' imply the payload is SLIC code.

== LID identifier families ==
The identifier is structured rather than sequential: the high halfword groups LIDs into families, and members of a family share a purpose. In a V4R4 <code>QFILEIML</code> the most populous families are:

{|class="wikitable"
!Family
!Records
!Observed contents
|-
|<code>a170</code>
|144
|Not established
|-
|<code>a0b0</code>
|66
|Not established
|-
|<code>a100</code>
|56
|Not established
|-
|<code>8190</code>
|54
|Not established
|-
|<code>a0c0</code>
|37
|Not established
|-
|<code>8390</code>
|36
|Not established
|-
|<code>a090</code>
|33
|Largely 32-bit PowerPC firmware images
|-
|<code>8590</code>
|30
|Largely 32-bit PowerPC firmware images
|-
|<code>8090</code>
|29
|Mixed; includes the service processor firmware and the two large SLIC LIDs
|}

The purpose of most families has not been established. The <code>80xxxxxx</code> range is the only one <code>QFILEMCD</code> uses.

== The compressed flag ==
Bit <code>0x80000000</code> marks a payload as compressed. The codec is the LZW variant implemented in SLIC by the routines <code>LZdcomp</code> and <code>cpdcomp</code>, which supports 9-, 10- and 12-bit codes and dispatches on a leading format byte of <code>0x11</code> or <code>0x21</code>. It is '''not''' any of the OS/400 <code>*LOW</code>, <code>*MEDIUM</code> or <code>*HIGH</code> save-file compression methods, nor zlib or raw deflate; all of those have been tried against real payloads and fail immediately.

The flag should be treated as advisory rather than exact. In one V4R4 <code>QFILEIML</code>, 31 payloads carry the compressed flag yet begin with clean, plainly readable 32-bit PowerPC function prologues. Whatever the flag governs, it is not a simple "this entire payload is one compressed stream".

== Containers and consumers ==
* '''<code>COPYDIR</code>''', the directory in <code>QFILEMCD</code>, carries SLIC itself as a nested LID directory.
* '''<code>IMD1</code>''', the format of [[System Files:QFILEIML]], carries IOP, adapter and service processor microcode alongside SLIC modules.
* SLIC contains an interactive '''LID filesystem'''. The commands <code>IdeLidFileSystem</code>, <code>IdeCopyLidCmd</code>, <code>IdeFindLidCmd</code>, <code>IdeVerifyLid</code>, <code>IdeCompressLidCmd</code>, <code>IdeDecompressLidCmd</code>, <code>IdeLidListCmd</code> and <code>IdeMakeTempLidCmd</code> all appear in a V4R4 name index, so a LID is a first-class object to the machine rather than merely an installation-media artefact.
* Adapter and IOP classes in SLIC expose a <code>downLoadLid</code> method, which is the mechanism by which a staged LID reaches the card.
* On modern POWER hardware the '''flexible service processor''' holds a filesystem of LIDs containing the hypervisor, the Open Firmware image used by AIX and Linux partitions, the component that replaces the physical front panel, and adapter firmware for several third-party network and storage cards.<ref>Reported by a machine owner familiar with FSP internals; not independently verified here, but consistent with IBM's evident reuse of the container across generations.</ref>

== Scope of this description ==
Everything above was read from a single V4R4 installation image and cross-checked between its two container files. Field offsets, sizes and the terminator are considered established. Family meanings, and the exact semantics of the compressed flag, are not.

== See also ==
* [[System Files:QFILEIML]]
* [[CISC AS/400 LIC Tapes]]

== Footnotes ==
<references />

[[Category: System Internals]]
[[Category:AI generated not reviewed]]

SRC

2026-08-16T19:08:48Z

PoC: +cat

A '''system reference code''' ('''SRC''') is the AS/400's primary way of telling you what it is doing or what went wrong. It is the string of hexadecimal characters shown on the operator panel's display, and the same codes appear in the system's logs and on the console. Because the platform is designed to be serviced by someone who may not have a working console, the SRC is deliberately the lowest-common-denominator channel: it works when nothing else does.

This article covers what an SRC ''is'' and, more usefully, '''how to work back from one to the piece of Licensed Internal Code that produced it'''. Individual codes are catalogued elsewhere — see [[Disk device related system reference codes]], [[Tape device related system reference codes]] and [[SRC 0000BBBB]] for worked cases.

== What an SRC looks like ==
The panel displays eight hexadecimal characters. That display is only the first of several ''words'' the machine has available; the remainder are reached with the panel's extended functions, and all of them are recorded in the logs.

The leading character is the most informative part, because it identifies what kind of event you are looking at:

{|class="wikitable"
!Leading character
!Meaning
|-
|<code>A</code>
|Attended IPL — the machine is waiting for you
|-
|<code>B</code>
|A problem was detected, most often by Licensed Internal Code
|-
|<code>C</code>
|IPL progress; the machine is working normally
|-
|<code>D</code>
|Power-down progress
|}

The distinction that matters when something appears stuck is between <code>C</code> and <code>B</code>. A <code>C</code> code is a progress report, and a machine sitting on one for a long time may simply be doing something slow. A <code>B</code> code is a failure, and it will not clear itself.

Progress codes are genuinely informative about sequence. The IPL-time verification sequence, for instance, runs:

{|class="wikitable"
!SRC
!Meaning
|-
|<code>C600 4500</code>
|Verifying network attributes
|-
|<code>C600 4504</code>
|Verifying system serial number
|-
|<code>C600 4505</code>
|Verifying system type
|-
|<code>C600 4506</code>
|Verifying system-unique ID
|-
|<code>C600 4507</code>
|Starting 'before DST' DASD checker
|-
|<code>C600 4508</code>
|Verifying system password
|-
|<code>C600 450A</code>
|Starting 'after DST' DASD checker
|}

Read as a whole, that tells you the order of dependency inside the IPL — serial number, then type, then unique ID, then disk state, then the system password — which is information you will not find stated anywhere as prose. Progress codes are a free execution trace of the boot path, and reading a long capture of them is a cheap way to understand a sequence you cannot otherwise observe.

== Where SRCs are recorded ==
The panel shows the current one. Everything else is in the machine:

* '''Panel extended functions''' step through the additional words of the current SRC.
* The '''Product Activity Log''', under DST or SST, holds hardware-detected events with their full word set and timestamps.
* The '''Licensed Internal Code log''' holds LIC-detected events. This is the one that matters for the technique below, because for a LIC-detected error it records the failing '''module''' — not just a code.
* '''Main storage dumps''' capture machine state at the point of failure.

If you are trying to understand a failure rather than merely clear it, go to the logs. The panel gives you one word of what may be a nine-word record.

== How SRCs are produced ==
Inside SLIC there is a family of classes that construct reference codes, one per flavour of event:

<pre>
IoMFSystemRefCode base
IoMFGenericSystemRefCode generic
IoMFAttentionSystemRefCode attention
IoMFIplStatusSystemRefCode IPL status
IoMFRunStatusSystemRefCode run-time status
IoMFTerminalSystemRefCode terminal
IoMFExtendedSrc / IoMFExtendedSrcHyp
</pre>

alongside a set of categories that amount to the machine's error taxonomy — <code>IoMFSrcDeviceFailure</code>, <code>IoMFSrcIoError</code>, <code>IoMFSrcIopCodeDetectedFailure</code>, <code>IoMFSrcSlicDetectedError</code>, <code>IoMFSrcIopFailureNoDeviceVpd</code> and several more. Persistent logging goes through an entry point named <code>putSrc</code> on the persistent-machine class.

Getting the code onto the panel is a separate step, handled by a request/acknowledge message protocol to the service processor. The panel-related messages include <code>IoMFCEMessageSRCDisplay</code> to display a code and <code>IoMFCEMessagePNLClearSRC</code> to clear it, in among messages for panel button notifications, power control and IPL mode. The panel is a small subassembly with its own microcontroller, driven over what appears from the software side to be a simple serial link.

The practical consequence is that '''posting an SRC is an ordinary function call''' made from ordinary code. It is not a hardware trap or a magic register. So the code that posted a given SRC is findable by the same means as any other caller.

== Working back from an SRC to a LIC module ==
This is the part worth generalising, because the same route serves any question of the form "which code did this?" — not only SRCs.

=== On the machine ===
For a LIC-detected error, the Licensed Internal Code log entry names the failing module directly. That is the short path and should always be tried first: DST or SST, the LIC log, then the detailed display for the entry in question. You are looking for a module name and an offset within it.

Module names follow visible conventions once you have seen a few. Names beginning with <code>#</code> are SLIC-internal modules; the rest are C++ symbols and are mangled, so a name like <code>putSrc__16NuPersistMachineFUtPv</code> decomposes into a method <code>putSrc</code> on class <code>NuPersistMachine</code> taking an unsigned halfword and a pointer.

=== Offline, from installation media ===
When the log does not name a module, or when you want to read the code rather than just identify it, the route runs through [[System Files:QFILEMCD]]:

# '''Extract the segments.''' <code>QFILEMCD</code> contains SLIC as large memory segments stored at the addresses the link loader maps them to.
# '''Build a name index.''' Two structures in the code give you addresses paired with names. Every compilation unit ends with a <code>TBTB</code> traceback trailer, many carrying the unit's name; and the link loader leaves a descriptor block per procedure, with the entry address at <code>+0x08</code> and the name in EBCDIC at <code>+0x38</code>. Merging both across every segment of a V4R4 image gives on the order of 184,000 named records.
# '''Look the address up.''' Prefer descriptor hits, which name exactly one procedure, over traceback hits, which cover a whole compilation unit and so only tell you which module an address is in.
# '''Find who posts the code.''' Because SRC posting is a normal call, you can find every site that posts one by resolving the calls to the <code>IoMF*SystemRefCode</code> constructors and reading what the caller places in the code fields just beforehand.

Step 4 needs one piece of SLIC-specific knowledge. External calls do not go through a dispatch table you can read off. A call is <code>ori r11,r13,''ordinal''</code> followed by <code>bla</code> into a transfer vector at the top of the address space, and the 16-byte stub it lands on computes the target arithmetically from the ordinal. To resolve calls you need the stub constants, which are not derivable and must be read from a dump of the transfer vector segment. With them, every external call in a segment resolves mechanically.

=== A worked example ===
The DST module that verifies the system password illustrates the whole path. Immediately before it calls <code>IoMFGenericSystemRefCode</code>, it does this:

<pre>
li r0, 0x12 ; 18
li r31, 0x21 ; 33
lhz r6, 0x18(r29) ; the password status halfword
cmpwi r6, 0x30
bne ...
sth r0, 0x44(r1) ; status == 0x30 -> code 0x12
b ...
sth r31, 0x44(r1) ; otherwise -> code 0x21
ori r11, r13, 0xd45c
bla ... ; IoMFGenericSystemRefCode
</pre>

Read backwards, this is exactly the inference you want to be able to make. The reference code is chosen from a status halfword; a status of <code>0x30</code> produces one code and anything else produces another. So the two codes are not two unrelated faults but two branches of one test, and knowing which one appeared tells you which branch was taken. Working ''forward'' from the SRC list would never reveal that relationship.

=== What the method will not give you ===
Two honest limits. A traceback trailer names a compilation unit, which may contain many entry points, so it localises rather than pinpoints. And addresses are per-'''build''', not per-release: the same class sits at a completely different address on a machine of another build, so a name index is only valid against the media it was built from. Always match your extracted image to the machine you are investigating, using the build label carried in both container files.

== Why this is worth learning ==
The technique generalises well beyond diagnosing faults. An SRC sequence is an execution trace with names attached, and the machine emits one on every IPL whether or not anything is wrong. Combined with a name index over the LIC image, it lets you ask questions the documentation does not answer — what the machine checks and in what order, which subsystem owns a given behaviour, where a slow phase is actually spending its time — using only a panel display and a copy of the installation media.

== See also ==
* [[System Files:QFILEMCD]]
* [[System Files:QFILEIML]]
* [[Data Structures:LID]]
* [[SRC 0000BBBB]]
* [[Disk device related system reference codes]]
* [[Tape device related system reference codes]]
* [[Panel Usage]]

== Weblinks ==
* [https://www.ibm.com/docs/en/i/7.4.0?topic=finder-system-reference-code-list System reference code list], IBM Documentation
* [https://www.ibm.com/resources/publications/OutputPubsDetails?PubID=SY44590100 AS/400e Service Functions], which documents the panel functions and the IPL progress code sequences

[[Category: System Internals]]
[[Category:AI generated not reviewed]]

System Files:QFILEIML

2026-08-16T19:08:14Z

PoC: +cat

'''<code>QFILEIML</code>''' is one of the two large container files found on AS/400 SAVSYS and Licensed Internal Code installation media. It holds the machine's ''loadable'' microcode: IOP and adapter firmware, service processor firmware, and a quantity of SLIC modules. Its internal format is identified by the four-byte magic '''<code>IMD1</code>''' and is a container of [[Data Structures:LID|LIDs]].

The companion file <code>QFILEMCD</code> holds SLIC proper, via a directory called <code>COPYDIR</code>. Both files use the same 32-byte [[Data Structures:LID|LID directory record]], and a record present in both is byte-for-byte identical, so the two are two views of one packaging scheme rather than two unrelated formats.

The name is not documented by IBM as far as is known here. <code>IML</code> almost certainly stands for ''Initial Microprogram Load'' — the phase in which the machine's microcode is brought up, before OS/400 itself exists — which matches the file's contents. Treat the expansion as an inference.

This description is based on two samples: a V4R4 image of 81,287,680 bytes (77.5 MiB), build label <code>v4r4m01204.0.03</code>, and a V7R2 one of 288.7 MiB, label <code>v7r2m00000.0.00</code>, taken from an installation ISO. Unless a figure is attributed to a release, it comes from the V4R4 sample; the section ''Across releases'' sets out what is format and what merely happened to be true of one image.

== File layout ==
The layout is '''not at fixed offsets'''. It is carried in the header, and it differs between releases — a decoder that assumes the V4R4 offsets will read a V7R2 container as having no entries at all, without reporting an error.

The field at <code>+0x08</code>, low 24 bits, is the offset to the Licensed Internal Code banner. The directory header sits at exactly '''twice''' that offset, its records <code>0x20</code> further on, and the build label at header <code>+0x10</code>.

{|class="wikitable"
!Release
!<code>+0x08</code>
!Banner
!Directory header
!Records
!Build label
|-
|V4R4
|<code>ff000200</code>
|<code>0x200</code>
|<code>0x400</code>
|<code>0x420</code>
|<code>v4r4m01204.0.03</code>
|-
|V7R2
|<code>ff000800</code>
|<code>0x800</code>
|<code>0x1000</code>
|<code>0x1020</code>
|<code>v7r2m00000.0.00</code>
|}

So the general layout is:

{|class="wikitable"
!Offset
!Contents
|-
|<code>0x000</code>
|Magic <code>C9 D4 C4 F1</code>, which is <code>IMD1</code> in EBCDIC
|-
|<code>0x008</code>
|Low 24 bits: offset to the banner. The rest of the header is not understood
|-
|''banner''
|Licensed Internal Code banner in EBCDIC, carrying the LIC product identifiers
|-
|''banner'' × 2
|Directory header: a four-byte preamble, the literal string <code>Directory.</code>, two zero bytes, then a 16-byte build label
|-
|''banner'' × 2 + <code>0x20</code>
|The directory: a run of 32-byte LID records
|-
|''varies''
|Terminator record, identifier <code>0xC5D5C440</code> (<code>END </code> in EBCDIC)
|}

The first sixteen bytes of a V4R4 container are:

<pre>
00000000: c9d4 c4f1 0000 0000 ff00 0200 00e0 0000
</pre>

and of a V7R2 one:

<pre>
00000000: c9d4 c4f1 0000 0000 ff00 0800 0010 0000
</pre>

The banner reads, in EBCDIC:

<pre>
LICENSED INTERNAL CODE - PROPERTY OF IBM 5763999, 5716999, 5769999
(C) COPYRIGHT IBM CORP. 1980, 1998. ALL RIGHTS RESERVED. ...
</pre>

The seven-digit numbers are LIC product identifiers, and the same ones appear in <code>QFILEMCD</code>. The build label is likewise identical between the two container files from the same media, which is a convenient way to confirm that a given <code>QFILEIML</code> and <code>QFILEMCD</code> belong together.

The field at <code>+0x0C</code> differs between the two samples (<code>00e00000</code> against <code>00100000</code>) and is not understood. Two samples are not enough to fit it.

== The directory ==
The directory begins at <code>0x420</code> and runs, in this image, for 632 records before the <code>END </code> terminator at <code>0x5320</code>. The record layout is documented at [[Data Structures:LID]] and is not repeated here.

Of the 632 records:
* 341 carry the compressed flag.
* 631 name an SLS staging address in the <code>FFFFFFFFxx</code> band. Exactly one does not: LID <code>80900818</code> stages at <code>000000024A 000000</code>.
* 7 have payloads that are themselves runs of LID records — see ''Directory extents'' below.

== Payload addressing ==
<blockquote>'''Note!''' This is the single point on which it is easiest to go wrong, and doing so silently produces plausible-looking nonsense.</blockquote>

The <code>offset</code> field in each record is '''not''' an offset into the container. It is a load-source LBA, describing where the payload sits on the installation medium, and it has no useful meaning inside the file.

Reading it as a file offset is superficially attractive and definitively wrong. Doing so on a V4R4 image yields 608 overlapping extents out of 632, a maximum extent of 34,550 blocks against a 158,765-block file, and a minimum offset of block 3, which lands inside the header. That the lengths happen to sum to approximately the file size is a coincidence and should not be taken as confirmation.

The actual rule is simpler: '''payloads are stored sequentially, in directory order, immediately after the directory''', each one <code>length</code> blocks long. There are no gaps and no padding between them.

'''Payloads begin at the next 512-byte block boundary after the directory terminator.''' That is block 42 for the V4R4 sample and block 69 for the V7R2 one. This rule needs only the directory, so it also works on a container embedded in a larger image — an install ISO, for instance — where the file size is not a meaningful quantity.

An older formulation, ''file size in blocks minus the sum of all lengths'', gives the same answer for a standalone file and is a useful cross-check: on the V4R4 sample the two agree exactly, and the implied container size matches the real file size to the byte at 81,287,680. But it cannot be used on an embedded container, so prefer the terminator rule.

To locate a payload, therefore, walk the directory from the beginning and accumulate lengths; do not index by the offset field.

== Contents ==
Laid out correctly, the payloads fall into two clear populations, distinguishable without decompression by looking for 32-bit <code>stwu r1,-x(r1)</code> prologues versus 64-bit <code>std</code> stores:

{|class="wikitable"
!Population
!Count
!Identification
|-
|32-bit PowerPC
|75
|<code>stwu</code> prologues present, no <code>std</code> at all
|-
|64-bit PowerPC AS (SLIC)
|210
|<code>std</code> present, no <code>stwu</code> at all
|-
|Neither
|347
|Compressed payloads, data, tables, and directory extents
|}

The split is clean — no payload shows both — which is what makes the heuristic trustworthy. The 32-bit population is the interesting one: the main processor of these machines is 64-bit PowerPC AS, so 32-bit code in this file is by definition destined for something else. That is the IOP, adapter and service processor microcode.

=== Service processor firmware ===
LID <code>80900702</code> is service processor Licensed Internal Code: 128 KiB, stored uncompressed, staged at SLS <code>FFFFFFFF9A 001000</code>. Its EBCDIC strings include a ''9400 Licensed Internal Code'' banner and a 1998 copyright, and its code is unambiguously 32-bit.

This confirms a long-standing claim in the trade press that AS/400 service processor firmware is loaded from the load source rather than residing wholly in flash on the card. As the rest of this section shows, that turns out to be only half true.

About 30 payloads carry an <code>AJS</code> build identifier and are service-processor code, ranging from a few tens of kilobytes to a few hundred. A further handful carry <code>AJG</code> identifiers and are I/O offload (MFIOP) code instead; several of those carry an <code>ATM</code> marker, i.e. ATM networking, which is not something a service processor does. The two families are ''mostly'' disjoint but not perfectly: at least one payload contains both identifiers.

==== Module headers ====
Each of these images is not a monolithic firmware blob but a collection of '''linkable modules''', each introduced by a header with the EBCDIC eyecatcher '''<code>PGPM</code>''' (<code>D7 C7 D7 D4</code>) — 119 of them in a V4R4 container and 104 in a V7R2 one, decoding identically. The useful fields are:

{|class="wikitable"
!Offset
!Contents
|-
|<code>+0x00</code>
|<code>PGPM</code> eyecatcher
|-
|<code>+0x04</code>
|A LID identifier — but see the caveat below
|-
|<code>+0x24</code>
|EBCDIC version string, e.g. <code>0100</code>
|-
|<code>+0x30</code>
|8-byte build identifier, e.g. <code>AJSFGVB3</code>
|-
|<code>+0x54</code>
|8-byte name of the module this header '''defines'''
|-
|<code>+0x60</code>
|Slot table, 4-byte values
|-
|<code>+0xC0</code>
|Import table: 12-byte entries, each an 8-byte name and a 4-byte linkage slot, terminated by eight EBCDIC <code>F</code> characters
|}

<blockquote>'''Note!''' Strings such as <code>SP MOPT1</code>, <code>SP SPCI3</code> or <code>SP WT</code> are '''module names in a link table''', not feature or capability tags. An earlier version of this article described them as component tags whose differing sets indicated capability tiers across the hardware range. That reading was wrong: the sets differ because different modules import different things.</blockquote>

Worked example, from the header at <code>+0x59C</code> of LID <code>A07008C2</code>: build <code>AJSFGVB3</code>, defines <code>SP SB</code>, and imports <code>SP SPCI1</code> through <code>SP SPCI5</code> and <code>CUANSI</code>, with the import table running to its terminator at <code>+0x1B4</code>.

Both families share a common utility layer, which is why their vocabulary overlaps: <code>CUANSI</code>, <code>CUCONV</code>, <code>CUIO</code>, <code>CUMEMORY</code>, <code>CUMISC</code> and <code>CUSTO</code>, plus <code>SRASCOMN</code> for RAS common code.

==== Reading the dependency graph ====
Because every module declares what it defines and what it imports, the link tables can simply be read off as a dependency graph — which is more informative than any amount of disassembly, and is the main reason the <code>PGPM</code> header is worth knowing about.

Doing so reveals a clean pattern. The '''numbered''' names — <code>SP SPCI1</code> to <code>SPCI5</code>, <code>SP MOPT1</code> to <code>MOPT9</code>, <code>SP MOPD1</code> — are imported by many modules and '''defined by none'''. The '''lettered''' members of the same families — <code>MOPTA</code>, <code>MOPTB</code>, <code>MOPTC</code>, <code>MOPD2</code> — each import their immediate predecessor and are present as real modules.

The natural reading is that numbered names are resident firmware on the card and lettered ones are downloadable extensions layered on top. Which is exactly what the following section establishes by a completely independent route.

<blockquote>'''Caveat.''' The LID identifier at <code>+0x04</code> of a <code>PGPM</code> header frequently disagrees with the container LID that the sequential payload layout assigns to that region. Most of these values are valid LID identifiers from the directory, and in one region a run of 21 consecutive modules is spaced exactly by the directory lengths of the LIDs they name. Either the layout is displaced there, or modules are stored under a delivery LID distinct from their own. Findings about module ''contents'' are unaffected, since they come from the headers themselves — but do not quote a byte offset against a specific LID until this is resolved.</blockquote>

=== What is not in the file ===
Notably, the service processor's own '''supervisor is absent'''. Two independent lines of evidence agree on this.

'''From the instruction stream.''' All payloads were searched for <code>rfi</code> (<code>0x4C000064</code>), which any PowerPC exception-returning kernel must contain, and for exception vector tables at the architectural <code>0x100</code>, <code>0x200</code> and subsequent offsets of every 4 KiB boundary. Across 4.1 MB of service-processor code there is not one <code>rfi</code>, and no payload has a vector table. Privileged operations are almost as scarce: six instructions of the <code>mtmsr</code> family and four cache or TLB operations in the whole set.

Consistent with that, LID <code>80900702</code> begins mid-function, with a function ''tail'' rather than an entry point, and manipulates no privileged state at all — only LR, CTR and XER are touched. It does contain 31 <code>sc</code> supervisor calls.

'''From the link tables.''' As described above, the numbered module names are imported by many modules and defined by none. The code that provides them is therefore not on this medium.

The conclusion is that the service processor runs a resident supervisor of its own, held in flash on the card, and that this file supplies only loadable task modules that sit on top of it. That is consistent with the hardware — the operator panel carries its own flash, and SLIC has an explicit message for instructing the service processor to IPL itself.

==== The supervisor call interface ====
Since the supervisor itself is absent, the <code>sc</code> instructions are the entire visible boundary between these modules and the firmware they run on. Across the family there are 668 supervisor calls using just 9 distinct call numbers, with the number in <code>r0</code> and arguments from <code>r3</code>:

{|class="wikitable"
!Call
!Count
!Observed arguments
|-
|<code>0x020C</code>
|262
|—
|-
|<code>0x0208</code>
|131
|<code>r3 = 0x16</code> in every instance
|-
|<code>0x03A4</code>
|106
|<code>r3 = 0x64</code>, <code>r4 = 5</code>; unique to one module
|-
|<code>0x0358</code>
|
|<code>r3</code> is one of exactly three values: <code>0x83010000</code>, <code>0x83020000</code>, <code>0x83030000</code>
|}

The first two are the interesting pair: <code>0x0208</code> occurs exactly half as often as <code>0x020C</code>, and always on the same resource number, which is the signature of an acquire/release pair around a critical section. The <code>0x0358</code> window is the only region passed explicitly to a supervisor call, which is what registering or mapping a device or shared-memory window looks like.

Beyond that the call numbers cannot be decoded, because the code that implements them is not on this medium.

==== A caution about what this firmware does ====
It is tempting to assume this firmware covers the obvious service-processor duties — power control, thermal and fan management, SPCN, driving the panel and its LCD, VPD storage, error logging and SRC posting. '''No such claim is supported by this file.'''

These modules contain almost no descriptive text. The complete inventory of readable strings is the Licensed Internal Code banner, the copyright boilerplate, the EBCDIC-to-ASCII translation tables, and the <code>PGPM</code> link names. A search for the entire relevant vocabulary — <code>POWER</code>, <code>FAN</code>, <code>THERMAL</code>, <code>SPCN</code>, <code>VPD</code>, <code>PASSWORD</code>, <code>SECUR</code>, <code>SERIAL</code> and more, in both EBCDIC and ASCII, over every byte — returns nothing in any service-processor module. The same vocabulary ''is'' present elsewhere in the container, but only inside SLIC payloads.

So the honest position is that the functional surface visible here is nine supervisor call numbers into firmware nobody has. What the service processor actually does is implemented on the other side of that boundary.

One bound on that negative: readable code averages about 46 % of 1 KiB blocks across these images, and one 119 KiB payload is entirely opaque. The supported statement is that nothing is visible in the readable portion, not that nothing exists.

=== Directory extents ===
Seven payloads are not data but further runs of 32-byte LID records, largely duplicating entries from the root directory byte for byte. The two largest hold 294 and 133 records. They appear to be indexes rather than nested containers, and a tool walking this file should recognise them so as not to mistake an index for a firmware image. A payload whose first few records parse as plausible LID records, with identifiers matching known LIDs, is an extent.

== Compression ==
341 of the 632 payloads are flagged compressed. The codec is the LZW variant used throughout SLIC and is described at [[Data Structures:LID#The compressed flag]]. It has not been needed to read the service processor firmware, which is stored plain, but it stands between the reader and roughly half the file.

== Tooling ==
No IBM-supplied tool for reading this file outside the machine is known. A parser must, at minimum:
# check the <code>IMD1</code> magic at offset 0;
# read the banner offset from <code>+0x08</code> and '''derive''' the directory position from it, rather than assuming a constant;
# read 32-byte records until an identifier of <code>0xC5D5C440</code> or zero;
# place the payload area at the next block boundary after that terminator;
# lay payloads out sequentially in directory order.

Step 2 is the one that catches people. An implementation that hardcodes the V4R4 directory offset of <code>0x420</code> does not fail loudly on a V7R2 container — it reports zero records and a nonsensical payload start. Deriving the offsets costs nothing and works on both.

== Across releases ==
Comparing a V4R4 image with a V7R2 one shows how much of this is format and how much was accident of a single sample.

{|class="wikitable"
!
!V4R4
!V7R2
|-
|Records
|632
|961
|-
|Compressed
|341
|557
|-
|Payload
|77.5 MiB
|288.7 MiB
|-
|<code>PGPM</code> module headers
|119
|104
|}

The record format, the <code>PGPM</code> module header and its field offsets, the payload tiling rule and the <code>END </code> terminator are all unchanged. What varies is the header offsets, which the header itself declares.

The service processor module namespace is also strikingly stable. Fourteen <code>SP</code> module names are defined in both releases, and the pattern of numbered names being imported but never defined — the evidence that they live in flash on the card — reproduces exactly sixteen years apart. So does the supervisor call vocabulary, with V7R2 adding one new call number.

What did change is on the SLIC side, and it is what you would expect once the service processor and panel stop being discrete cards. The concrete hardware driver classes are simply gone in V7R2, while the message protocol and resource model that sat on top of them survive and grow. In their place, the panel and service processor objects are constructed from new ''virtual'' VPD providers. The interface is preserved and the implementation behind it is virtualised — which is why code written against the older message classes still reads as recognisable on a modern machine.

== Open questions ==
* The header field at <code>+0x0C</code>, which differs between samples (<code>00e00000</code> against <code>00100000</code>).
* The rest of the header between <code>+0x0C</code> and the banner.
* The meaning of most LID identifier families.
* Why some payloads carry the compressed flag yet begin with plainly readable 32-bit code.
* Whether the load-source LBAs in the offset field can be used to reconstruct the physical layout of the original installation medium.
* The <code>PGPM</code> identifier discrepancy described above.

== See also ==
* [[Data Structures:LID]]
* [[CISC AS/400 LIC Tapes]]
* [[Copying disks with Linux]]

== Weblinks ==
* [https://www.mcpressonline.com/ MC Press Online], which carries older documentation describing service processor microcode as being loaded from the load source

[[Category: System Internals]]
[[Category:AI generated not reviewed]]

System Files:QFILEMCD

2026-08-16T19:07:53Z

PoC: +cat

'''<code>QFILEMCD</code>''' is the larger of the two container files found on AS/400 SAVSYS and Licensed Internal Code installation media. It is a backup of '''SLIC''' itself — the System Licensed Internal Code that sits below OS/400 — stored as a small number of very large memory segments. Its internal format is called '''<code>COPYDIR</code>''' after the eyecatcher at offset zero.

Practically, this is the file to reach for if you want to read the machine's own code without touching a running system. Its segments are a byte-for-byte image of what the link loader maps into memory, so an address recovered from a crash, a trace or a [[SRC|system reference code]] can be looked up directly in a file on your workstation. The companion file [[System Files:QFILEIML]] carries the loadable IOP, adapter and service processor microcode instead.

Both files are containers of [[Data Structures:LID|LIDs]], but at different granularities, and the relationship between them is described under ''Two directories, two granularities'' below.

The figures quoted here come from one V4R4 image of 472,846,336 bytes (451 MiB). Treat structure as general and numbers as release-specific; the format is unchanged from V4R4 through V7R4, across install media and SAVSYS output alike.

== Header ==
{|class="wikitable"
!Offset
!Contents
|-
|<code>0x00</code>
|Eyecatcher <code>COPYDIR </code> in EBCDIC (<code>C3 D6 D7 E8 C4 C9 D9 40</code>), a zero byte, then the two EBCDIC characters <code>00</code>
|-
|<code>0x1C</code>
|32-bit total size of the payload area — see below. Confirmed on three independent samples
|-
|<code>0x26</code>
|Release level, then the '''system serial number''', EBCDIC
|-
|<code>0x50</code>
|Licensed Internal Code banner, EBCDIC, in 48-character chunks
|-
|<code>0x1C0</code>
|Start of the directory
|}

The string in a V4R4 image reads:

<pre>
V4R4M044-C6295 2606071417
</pre>

and in a V7R4 one taken by SAVSYS from a running machine:

<pre>
V7R4M021-7886W
</pre>

The first field is the release and modification level. '''The five characters after the hyphen are the system serial number.''' That is not an inference: the owner of the V7R4 machine confirms its serial is <code>7886W</code>.

On '''installation media''' the same field carries a build or media tag instead — a V7R4 install ISO reads <code>V7R4M021-821BV</code> — so what the field means depends on how the image was produced. Both forms are five characters, which makes them easy to confuse.

<blockquote>'''Note!''' A LIC backup is therefore '''not anonymous''': it records the serial number of the machine it came from. The serial is also one of the values the system password is keyed on (see [[CISC AS/400 LIC Tapes]]), so treat these files as identifying if you share them.</blockquote>

In the V4R4 sample the ten digits after the serial parse naturally as a timestamp of the form <code>YYMMDDHHMM</code>, making that backup 2026-06-07 14:17. That part '''is''' an inference from the shape of the field, and the V7R4 sample carries binary rather than digits in the same place, so the layout after the serial is not fixed.

<blockquote>'''Note!''' The header is '''not''' a fixed 192 (<code>0xC0</code>) bytes, despite older format notes saying so. The IBM legal banner runs on well past that point, and in this V4R4 image the directory does not begin until <code>0x1C0</code>. A parser should locate the directory by scanning for the first 64-byte-aligned block that has the shape of an entry, rather than seeking to a constant.</blockquote>

The 32-bit field at <code>0x1C</code> holds <code>0x1C2F0000</code>, which is exactly the end of the last segment's data. It is a total-payload-size field and makes a good consistency check after parsing the directory: accumulate the entries and you should arrive at the same number.

== The directory ==
The directory is a run of 64-byte entries beginning at <code>0x1C0</code>.

{|class="wikitable"
!Offset
!Size
!Field
|-
|<code>+0x00</code>
|8
|Always zero in observed data
|-
|<code>+0x08</code>
|8
|Flags. See the bit-numbering warning below
|-
|<code>+0x10</code>
|8
|SLS address of the saved segment
|-
|<code>+0x18</code>
|8
|Segment attributes; the top 16 bits carry the useful value
|-
|<code>+0x20</code>
|8
|Always zero in observed data
|-
|<code>+0x28</code>
|8
|Offset to the segment data, '''absolute from the start of the file'''
|-
|<code>+0x30</code>
|4
|Segment length, in '''raw bytes''' — not blocks
|-
|<code>+0x34</code>
|4
|Always zero in observed data
|-
|<code>+0x38</code>
|8
|Always zero in observed data
|}

Two details cause most of the trouble people have with this structure, and both were originally got wrong here:

* '''Flags use IBM's MSB-first bit numbering.''' Older notes describe the field as <code>bbt 0:3</code>, and a reader used to LSB-first numbering will look in the bottom nibble and find nothing. Bit 0 is the ''most'' significant bit, so the value lives in the '''top''' nibble of the 8-byte field. A normal entry reads <code>0x1000000000000000</code>; the end-of-directory marker reads <code>0xF000000000000000</code>.
* '''The data offset is absolute.''' It is measured from the start of the file, not from the end of the directory. Reading it as relative shifts every extracted segment by the size of the directory, which produces code that disassembles almost plausibly and is wrong everywhere.

In this image the directory holds '''32 entries''', with the terminator at <code>0x9C0</code> and the directory ending at <code>0xA00</code>. The first entry has a data offset of zero, which means the header and directory physically occupy the first <code>0xA00</code> bytes of the first segment's stored image. This is expected rather than a bug, but a tool that extracts that segment will see the container's own header at the front of it.

Segment lengths are consistently a whole number of 4 KiB pages less than a power-of-two boundary: <code>0xFFF000</code> is 16 MiB minus one page, <code>0x7FF000</code> is 8 MiB minus one page, and so on.

== Contents of a typical backup ==
The 32 segments of this image, with names from a community-maintained SLS address reference. Where the name column is blank, the segment's purpose has not been established.

{|class="wikitable"
!SLS address
!Length
!Name
|-
|<code>FFFFFFFFB1 000000</code>
|16 MiB
|
|-
|<code>FFFFFFFFB2 000000</code>
|16 MiB
|
|-
|<code>FFFFFFFFB3 000000</code>
|16 MiB
|
|-
|<code>FFFFFFFFB5 000000</code>
|16 MiB
|
|-
|<code>FFFFFFFFC1 000000</code>
|16 MiB
|Link Loader — LIC Code
|-
|<code>FFFFFFFFC2 000000</code>
|16 MiB
|Link Loader — LIC Data
|-
|<code>FFFFFFFFC3 000000</code>
|16 MiB
|Link Loader — LIC Code (2)
|-
|<code>FFFFFFFFC4 000000</code>
|16 MiB
|Link Loader — LIC Code (3)
|-
|<code>FFFFFFFFC5 000000</code>
|16 MiB
|Link Loader — LIC Code (4)
|-
|<code>FFFFFFFFC6 000000</code>
|8 MiB
|Link Loader — LIC Code (5)
|-
|<code>FFFFFFFFC7 000000</code>
|16 MiB
|Mixed — component code and NLS text pools
|-
|<code>FFFFFFFFC8 000000</code>
|8 MiB
|Mixed — bignum/JVM code and NLS text pools
|-
|<code>FFFFFFFFF1 000000</code>
|4 MiB
|Link Loader TOC
|-
|<code>FFFFFFFFF2 000000</code>
|16 MiB
|Service LID
|-
|<code>FFFFFFFFF4 000000</code>
|16 MiB
|Service LID (2)
|-
|<code>FFFFFFFFFE 000000</code>
|15 MiB
|Pageable BLA
|-
|<code>FFFFFFFFD1 000000</code>
|16 MiB
|Link Loader Information
|-
|<code>FFFFFFFFD2 000000</code>
|16 MiB
|Link Loader Information, Code, Data
|-
|<code>FFFFFFFFD3 000000</code>
|16 MiB
|Link Loader Information (2)
|-
|<code>FFFFFFFFD4 000000</code>
|16 MiB
|Mixed — JVM strings and DST debug symbol table
|-
|<code>FFFFFFFF90 010000</code>
|60 KiB
|LID Directory
|-
|<code>FFFFFFFF91 000000</code>
|16 MiB
|LID NUC2 A-Side
|-
|<code>FFFFFFFF92 000000</code>
|16 MiB
|LID NUC2 B-Side
|-
|<code>FFFFFFFF93 000000</code>
|16 MiB
|LID NUC1 A-Side
|-
|<code>FFFFFFFF94 000000</code>
|16 MiB
|LID NUC1 B-Side
|-
|<code>FFFFFFFF95 000000</code>
|16 MiB
|
|-
|<code>FFFFFFFF96 000000</code>
|16 MiB
|
|-
|<code>FFFFFFFF9A 000000</code>
|8 MiB
|
|-
|<code>FFFFFFFF9B 000000</code>
|8 MiB
|
|-
|<code>FFFFFFFFA1 000000</code>
|16 MiB
|LID Manager
|-
|<code>FFFFFFFFA2 000000</code>
|16 MiB
|
|-
|<code>FFFFFFFF69 000000</code>
|16 MiB
|IDE
|}

So a backup of this shape is the SLIC boot and loader nucleus: link loader code and data, the loader's table of contents, the LID subsystem's own bookkeeping, and both IPL sides of the two nucleus LIDs. It is not the whole of the machine's code.

=== A and B sides ===
Several segments appear twice, distinguished as ''A-side'' and ''B-side''. An AS/400 keeps two copies of its Licensed Internal Code so that an update can be applied to one while the other remains a fallback. A normal, unattended IPL runs the '''B side''', so B is what a running machine is executing and B is what static analysis should be done against. Because the two sides are normally near-identical, a byte comparison against the A side is not evidence that A is the live one — the test only means something on a segment that actually differs between them.

== Two directories, two granularities ==
A common source of confusion is that <code>QFILEMCD</code> appears to have two completely different directory formats. It does, and they nest:

* The '''coarse''' level is <code>COPYDIR</code>'s own directory, documented above: 64-byte entries, one per 16 MiB-class memory segment, 32 of them.
* The '''fine''' level is a catalogue of individual LIDs, thousands of entries, using the 32-byte record described at [[Data Structures:LID]].

The fine level is not a second header in the file. It is simply '''the contents of one particular segment''' — the one named ''LID Directory'', at <code>FFFFFFFF90 010000</code>. Extract that segment and you find, after a preamble of about 1536 bytes, an EBCDIC <code>Directory.</code> eyecatcher, a version label, and then the records. In this image the label reads <code>v4r4m01204.0.03</code>, which is the same label carried by [[System Files:QFILEIML]] — a quick way to confirm that two files came off the same media.

That is also why tools which dump this file emit two dissimilar-looking listings: a short table of large memory extents, and a long list of LIDs. They are two levels of one structure, not two formats.

== Extracting a segment ==
The practical recipe, and the reason this file is worth knowing about:

# Read the <code>COPYDIR</code> eyecatcher at offset 0 to confirm the format.
# Find the directory by scanning 64-byte-aligned offsets for the first entry-shaped block, rather than assuming <code>0xC0</code> or <code>0x1C0</code>.
# Walk entries until the flags field has <code>0xF</code> in its '''top''' nibble.
# For the segment you want, seek to the data offset '''as an absolute file offset''' and read ''length'' raw bytes.
# Load the result at its SLS address in a disassembler. The bytes are what the link loader maps, so addresses match.

Step 5 is the payoff. A 64-bit address such as <code>FFFFFFFFC6 1F1690</code> can be typed straight into the DST ''Display/Alter storage'' panel on a live machine of the same build, and the sixteen rows it displays will match the extracted file byte for byte. Static and live analysis share one address space, which means you can do the slow work offline and use the machine only for confirmation.

Two caveats on addresses. They are per-'''build''', not per-release, so comparisons are only meaningful between identical builds; the same class sits at a quite different address on a V5R4 machine. And the SLS address recorded in the directory is the address the segment was '''saved from''', which is not always where it runs — the resident nucleus segment, for instance, is stored in the container under the SID of the B-side nucleus LID rather than its runtime SID.

== Reading the code ==
Once a segment is loaded, two structures make it navigable, and both are worth knowing because they turn addresses into names:

* '''Traceback trailers.''' Every compilation unit ends its code with a <code>TBTB</code> trailer, and many carry the module's name. A trailer names a whole compilation unit rather than a single function, so a hit means "this address is inside module X", not "this address is function X".
* '''Link-loader descriptor blocks.''' Considerably richer: one block per procedure, carrying the entry address at <code>+0x08</code> and the name in EBCDIC at <code>+0x38</code>. Names beginning with <code>#</code> are SLIC-internal modules; the rest are C++ mangled symbols.

Merging both across every segment of this V4R4 image yields roughly 184,000 named records, which is enough to name a substantial fraction of any address you encounter. See [[SRC]] for how to use that to get from a reference code back to a module.

Calls between modules do not go through a conventional dispatch table, which surprises people disassembling SLIC for the first time. An external call is a two-instruction sequence — <code>ori r11,r13,''ordinal''</code> followed by <code>bla</code> into a transfer vector at the very top of the address space — and the 16-byte stub it lands on computes the target arithmetically. There is no table to read off; the ordinal ''is'' the callee's word offset within a window, and the stub supplies the window. The stub constants cannot be derived and must be read from a dump of the transfer vector.

== The trailing page ==
The payload area ends at <code>0x1C2F0000</code>, but the file is one 4 KiB page longer than that. The final page is not padding: it holds 468 non-zero 8-byte records, which appear to be address-and-value pairs.

They fall into two clear populations. The first 110 are in ascending address order with a value of 8, addressing the ''Link Loader — LIC Data'' segment among others. The remaining 256 are identical to each other: the same address <code>0xFE911220</code>, in the ''Pageable BLA'' segment, paired with the value <code>0x48000002</code> — which as PowerPC is a branch-absolute to zero, the shape of a deliberately poisoned entry.

This has the flavour of a fixup or relocation list applied after the segments are restored, but that is a guess from shape alone. It is recorded here because it is real, reproducible and unexplained, and because a parser that assumes the file ends with the payload will silently ignore it.

== Open questions ==
* The purpose of the trailing page.
* The header bytes other than the eyecatcher, size field, release string and banner.
* The meaning of the segment attribute field's top 16 bits, which take values <code>0x0001</code>, <code>0x0040</code>, <code>0x0080</code> and <code>0x0100</code> and correlate loosely with segment size.
* Names for the nine segments left blank in the table above.

== See also ==
* [[System Files:QFILEIML]]
* [[Data Structures:LID]]
* [[SRC]]
* [[CISC AS/400 LIC Tapes]]

[[Category: System Internals]]
[[Category:AI generated not reviewed]]

File Formats:SAVF

2026-08-16T19:07:34Z

PoC: +cat

A '''SAVF''' (''save file'') is the container OS/400 and IBM i write with <code>SAVOBJ</code> and <code>SAVLIB</code>, and read back with <code>RSTOBJ</code> and <code>RSTLIB</code>. It holds Machine Interface objects — programs, files, data areas, libraries — in the form they have on disk, together with a catalogue describing what was saved and from which machine.

Understanding the format is useful well beyond restoring a save file on a machine. It is the only practical way to get at the bytes of an MI object ''offline'': the same byte stream also appears inside optical images and tape images, so a distribution medium, a PTF, or a backup is an extractable archive of real MI objects. What can be done with one once it is extracted is described in [[File Formats:PGM]] for programs.

Everything below is big endian, and every text field is EBCDIC.

== Three layers ==
It helps to separate three things that are often run together:

* the '''chunk''' layer, which wraps the save stream in 528-byte units with a checksum on each;
* the '''item''' layer, which is a chain of saved objects, each a 512-byte descriptor followed by that object's segments;
* the '''catalogue''', a single special item per save that lists the library and its objects.

Only the chunk layer is specific to a save file held in <code>QSYS</code>. When the same save is carried on optical or tape media, the chunk wrapper is absent and the item chain sits in the medium directly. A reader that separates the layers handles all three media with one item parser.

== The chunk layer ==
A save file is exactly ''chunk count'' × 528 bytes. Chunk ''n'', counting from zero, begins at file offset <code>n × 528</code> and consists of 512 bytes of save-stream data followed by a 16-byte checksum. The logical save stream is the concatenation of the data halves, so translating a stream offset to a file offset is

<pre>
file_offset = (stream_offset / 512) * 528 + (stream_offset % 512)
</pre>

=== File header ===
The first 512 bytes of the stream — which are also the data half of chunk 1 — describe the container.

{|class="wikitable"
!Offset
!Size
!Field
!Notes
|-
|<code>+0x00</code>
|8
|MI creation timestamp
|Also the seed for every chunk checksum.
|-
|<code>+0x08</code>
|4
|Chunk count
|32-bit form.
|-
|<code>+0x10</code>
|8
|Machine type and model
|EBCDIC, model first: <code>42A 8286</code> is an 8286-42A.
|-
|<code>+0x30</code>
|4
|Release level
|-
|<code>+0x34</code>
|4
|Header length
|The first item starts here. Zero means 512.
|-
|<code>+0x38</code>
|8
|Chunk count
|64-bit form, used when the 32-bit field would overflow.
|-
|<code>+0x40</code>
|16
|Global checksum backup
|See below.
|}

A valid file satisfies <code>chunk count == file size / 528</code>; anything else means truncation. Because the header is itself chunk 1, verifying its checksum is the cheapest reliable test of whether a file is a save file at all.

=== The global checksum displaces real data ===
This is the trap worth knowing about before writing any extractor. The last 16 bytes of the ''logical'' stream, at <code>chunk count × 512 − 16</code>, are overwritten with a whole-file checksum. The data bytes they replaced are preserved in the file header at <code>+0x40</code>, and a reader must put them back. A reader that does not will silently corrupt the tail of the last object it extracts, in a way that no chunk checksum will catch, because the chunk checksums are computed over the overwritten bytes.

=== The chunk checksum ===
Each chunk's 16-byte trailer is the chunk number, counting from one, as a 4-byte big-endian integer, followed by a 12-byte digest. The digest is two folding passes built from a single primitive:

<pre>
chkadd(a, b): # b is exactly one byte longer than a
b[1:] += a << 1 # big-endian magnitudes, carry propagated
b[0] += carry + (the bit shifted out of the top of a)
</pre>

The first pass takes the chunk number followed by the 512 data bytes and cuts them into eight parts of 61, 62, 63, 64, 65, 66, 67 and 68 bytes, then folds them in ascending order: <code>chkadd</code> of the 61-byte part into the 62-byte part, that into the 63-byte part, and so on. The second pass takes the resulting 68 bytes, cuts them into parts of 5, 6, 7, 8, 9, 10, 11 and 12 bytes, and folds them the same way, leaving 12 bytes. The first 8 of those are then XORed with the file header's MI timestamp.

There is one non-obvious detail. In both passes the parts are ''filled'' from the input in the order 61, 62, 63, 64, 65, 66, '''68, 67''' — and 5, 6, 7, 8, 9, 10, '''12, 11''' — while being ''folded'' in ascending order. An implementation that fills them in plain ascending order produces a plausible-looking wrong answer.

The construction is a checksum, not a cryptographic hash. It detects media damage. It is not a tamper seal, and it carries no secret beyond a timestamp printed in the same header.

== The item layer ==
Items are chained: parse the descriptor at the header length, add the item's computed length, repeat, and stop when the next item would begin past <code>(chunk count − 1) × 512</code>. Every descriptor begins with <code>FFFFFFFF</code>, which makes resynchronising after damage feasible.

=== Item descriptor ===
{|class="wikitable"
!Offset
!Size
!Field
!Notes
|-
|<code>+0x00</code>
|4
|<code>FFFFFFFF</code>
|Eyecatcher.
|-
|<code>+0x04</code>
|10
|Object name
|EBCDIC. Replaced by a file ID for integrated file system objects.
|-
|<code>+0x0E</code>
|20
|Member name
|Empty unless the object has members.
|-
|<code>+0x22</code>
|2
|MI object type
|The same code space used throughout the machine: <code>0x0201</code> <code>*PGM</code>, <code>0x0401</code> <code>*LIB</code>, <code>0x1901</code> <code>*FILE</code>, <code>0x19DB</code> <code>*SRDS</code>.
|-
|<code>+0x24</code>
|1
|Flags
|Bit <code>0x40</code> or <code>0x80</code> means the item is an IFS object.
|-
|<code>+0x25</code>
|3
|Catalogue offset
|Where this object's entry sits inside the catalogue.
|-
|<code>+0x44</code>
|4
|Header occupation
|Bytes of the descriptor page actually used.
|-
|<code>+0x48</code>
|4
|Stored length
|In 512-byte units, minus one.
|-
|<code>+0x54</code>
|2
|Release created for
|Governs the section-entry layout below.
|-
|<code>+0x56</code>
|4
|Metadata length
|For a catalogue item, the size of the catalogue.
|-
|<code>+0x64</code>
|4
|Section count
|-
|<code>+0xC0</code>
|8
|Save timestamp
|-
|<code>+0xCC</code>
|4
|Total length
|In 512-byte units.
|-
|<code>+0xD4</code>
|4
|Data length
|In 512-byte units. Always the total length less 4096 bytes.
|-
|<code>+0x100</code>
|14 × 8
|Pointer array
|See below.
|-
|<code>+0x170</code>
|8
|Packed length
|Stored as the length less 512.
|}

The pointer array holds single-level store addresses, but only the low 24 bits matter: they are an offset into the item, biased by 4096, so <code>(pointer & 0xFFFFFF) − 4096</code> gives an offset within the descriptor page. Index 1 locates the section length table and index 8 the section type table.

=== Sections ===
A saved MI object is a set of segments, and each segment is one ''section'' of the item. Sections start at the first 4096-byte boundary after the descriptor and run consecutively, which is why the data length is always the total length less one page.

The length table has one entry per section. On any modern release — when the ''release created for'' field exceeds 32 — an entry is 16 bytes: capacity, length, and the segment's single-level store address. Older saves use a 10-byte entry with a shifted 6-byte address and no separate length.

The type table has one 8-byte entry per section, of which the first halfword is the segment type. This is the '''same value as the first halfword of the segment's own segment header''', which is a useful consistency check when extracting: the item's idea of what a section is must agree with the segment's own.

=== Item length and compression ===
An uncompressed item occupies its stored length. A packed item records a non-zero packed length, and the writer then realigns the following item on the enclosing 512-byte boundary, so the step from one item to the next is

<pre>
if packed == 512: step = stored
elif packed > stored: step = packed
else:
slack = stored - packed
within = item_offset % 512
if within == 0: step = stored
elif within < slack: step = packed + slack - within
else: step = stored + 512 - within
</pre>

The compression method is identifiable from the first six bytes of the packed data, which are EBCDIC eyecatchers:

{|class="wikitable"
!Bytes
!EBCDIC
!<code>DTACPR</code>
|-
|<code>D3C46DE3D9E2</code>
|<code>LD_TRS</code>
|<code>*MEDIUM</code>, the TERSE algorithm
|-
|<code>D3C46DD3E9F1</code>
|<code>LD_LZ1</code>
|<code>*HIGH</code>, IBM's LZ1
|-
|<code>D3C46DE9D3C2</code>
|<code>LD_ZLB</code>
|<code>*ZLIB</code>; the deflate stream begins 12 bytes in
|-
|none
|
|<code>*LOW</code>, an SNA-style run-length scheme, recognisable only by decoding it
|}

Note that these are ''not'' the compression used for a compressed LID payload; see [[Data Structures:LID]], where all four of these were tried and rejected.

== The catalogue ==
Every save writes one save/restore descriptor space item, MI type <code>0x19DB</code>, named <code>QSRDSSPC.''n''</code>, ahead of the objects it describes. Items named <code>QSR.ADDITIONAL_INFO.*</code> or <code>QSRDSSPC.EA SRD*</code> are continuation blocks belonging to the preceding descriptor, not new saves.

The catalogue itself is the '''last''' ''metadata length'' bytes of that item's data. Its first byte is the save command, and that selects the shape: a library save has the layout below, while a save of the integrated file system produces a different, tree-structured descriptor.

{|class="wikitable"
!Offset
!Size
!Field
|-
|<code>+0x00</code>
|1
|Save command
|-
|<code>+0x01</code>
|1
|Target release
|-
|<code>+0x02</code>
|30
|Saved library name
|-
|<code>+0x20</code>
|2
|Base object type, <code>0x0401</code>
|-
|<code>+0x22</code>
|8
|Save timestamp
|-
|<code>+0x2A</code>
|4
|Object count
|-
|<code>+0x34</code>
|8
|System serial number
|-
|<code>+0x3C</code>
|2
|ASP number
|-
|<code>+0x3E</code>
|10
|Create authority
|-
|<code>+0x4C</code>
|1
|Save-while-active indicator
|-
|<code>+0x50</code>
|10
|ASP name, target release 66 and later only
|}

Object descriptors follow, at <code>+0x50</code> or at <code>+0x70</code> when the ASP name is present. Each is 151 bytes on target release 49 and later, and 87 bytes before that. The first fields are the object name at <code>+0x00</code> for 30 bytes, the MI object type at <code>+0x1E</code>, and the owning user profile at <code>+0x20</code> for 10 bytes. The size is a 4-byte field at <code>+0x43</code>, multiplied by a second 4-byte field at <code>+0x79</code> when that is non-zero. The remainder of the descriptor holds offsets, into the same buffer, of chains of length-prefixed records carrying the object's text description, service description, usage information, work-unit references and user information.

Worth noticing for its own sake: the catalogue records the '''serial number of the machine that produced the save'''. A save file is not anonymous.

== Practical consequences ==
* Any MI object can be lifted out of a save file byte for byte, with its segments separated and their segment identifiers intact. That is what makes offline analysis of a program object possible without console access to a machine and without printing a storage dump.
* Verifying the chunk checksums is a genuine integrity check on an archived save file, and can be done without a machine.
* The item chain and the catalogue are independent descriptions of the same set of objects. Where they disagree, the file has been damaged or truncated.
* Because the chunk layer is only present for a save file held in <code>QSYS</code>, a save carved out of an optical or tape image is parsed by the same code with the chunk translation switched off.

== Scope of this description ==
The layout was mapped with reference to jSAVF, an independently developed third-party reader, and then verified field by field against a real V7R4 save file. Where an object in that file also had a printed Display/Alter/Dump available, the bytes extracted here matched the printout exactly. The chunk checksum was reimplemented from scratch and verifies every chunk of the test file.

Not established: the meaning of the 4-byte field at <code>+0x0C</code> of the file header, the layout of the integrated file system catalogue, and the LZ1 and TERSE decompressors.

== Weblinks ==
* [https://www.anerty.net/software/file/jSAVF/?lang=en jSAVF] — a maintained third-party reader for save files, and the starting point for the layout described here.

[[Category: System Internals]]
[[Category:AI generated not reviewed]]

File Formats:PGM

2026-08-16T19:07:22Z

PoC: /* See also */ +cat

A '''<code>*PGM</code>''' is a Machine Interface ''program object''. It is not a file with a text section and a symbol table. It is a set of single-level store '''segments''', chained together by 8-byte SLS pointers, with the executable instructions embedded in the first segment among the metadata that describes them.

This page describes enough of that structure to walk a program object offline — that is, without a console session and without printing a storage dump for every object of interest. The bytes can come from a [[File Formats:SAVF|save file]], which makes any distribution medium, PTF or backup a source of real program objects to examine.

Everything below is big endian, and text fields are EBCDIC.

== Addressing ==
Pointers are 8 bytes: a 40-bit segment identifier in the high bits and a 24-bit offset in the low bits, so a segment is 16 MiB. This is the same split used throughout the machine, including by the DST ''Display/Alter storage'' panel and by the SLS address field of a [[Data Structures:LID|LID]] directory record.

<pre>
segment = pointer >> 24
offset = pointer & 0xFFFFFF
</pre>

An all-zero pointer means the object has no data for that structure. That is precisely what the <code>###INFO: OBJECT DOES NOT CONTAIN DATA FOR THIS SECTION</code> line in a Display/Alter/Dump printout is reporting.

Some fields are not pointers but '''<code>SEGOFF</code>''' pairs: a 4-byte segment ''index'', counting from one into the object's own segment table, followed by a 4-byte offset. These appear where a genuine pointer would have to be relocated when the object moves.

The segments of one program have unrelated segment identifiers. A decoder therefore needs the whole set: a single segment cannot resolve its own pointers.

== Segments ==
A single-module bound program typically has four segments, distinguished by the type field in each segment's own header:

{|class="wikitable"
!Type
!Role
|-
|<code>0x0001</code>
|The program object proper: all headers, tables, and the instruction stream.
|-
|<code>0x0022</code>
|Module constants and the module string directory.
|-
|<code>0x0018</code>
|Static storage.
|-
|<code>0x0028</code>
|Trace-back and mapping data.
|}

Note that a program's segment table records a segment ''use'' code, while each segment's own header records a ''type''. They are different numberings and should not be conflated.

=== Segment header ===
Every MI segment opens with a header, called <code>YYSGHDR</code> in IBM's own dump formatting.

{|class="wikitable"
!Offset
!Size
!Field
|-
|<code>+0x00</code>
|2
|Segment type
|-
|<code>+0x02</code>
|2
|Size, in 512-byte units
|-
|<code>+0x04</code>
|1
|New flags
|-
|<code>+0x05</code>
|1
|Flags
|-
|<code>+0x08</code>
|8
|Address of the owning object
|-
|<code>+0x18</code>
|8
|Space address
|}

=== Object header ===
Immediately after it, at <code>+0x20</code> of the first segment, sits the object header, <code>YYEPAHDR</code>. Offsets below are relative to it.

{|class="wikitable"
!Offset
!Size
!Field
!Notes
|-
|<code>+0x02</code>
|1
|MI object type
|Together with the next byte, <code>0x0201</code> for a program.
|-
|<code>+0x03</code>
|1
|MI object subtype
|
|-
|<code>+0x04</code>
|30
|Object name
|EBCDIC.
|-
|<code>+0x24</code>
|4
|Space size
|
|-
|<code>+0x30</code>
|8
|Creation timestamp
|
|-
|<code>+0x38</code>
|8
|Owning user profile
|A pointer to the profile object.
|-
|<code>+0x48</code>
|8
|Context
|That is, the library.
|-
|<code>+0x50</code>
|8
|Object space
|'''The pointer to the program header.''' Everything else hangs off this.
|-
|<code>+0x5A</code>
|2
|ASP
|
|-
|<code>+0x60</code>
|8
|Last-modified timestamp
|
|}

The type and subtype pair uses the same code space as the item descriptors in a save file, so one table of MI type codes serves both.

== The program header ==
Found through the object header's object-space pointer; in practice it sits at offset <code>0x1000</code> of the first segment.

{|class="wikitable"
!Offset
!Size
!Field
|-
|<code>+0x00</code>
|8
|Program attributes
|-
|<code>+0x08</code>
|8
|Pointer to the version table
|-
|<code>+0x10</code>
|8
|Pointer to the segment table
|-
|<code>+0x18</code>
|8
|Pointer to the activation header
|-
|<code>+0x20</code>
|8
|Pointer to the signature table
|-
|<code>+0x28</code>
|8
|Pointer to the program string directory
|-
|<code>+0x30</code>
|8
|Pointer to activation group information
|-
|<code>+0x40</code>
|8
|Activation start
|-
|<code>+0x48</code>
|8
|Activation end
|-
|<code>+0x50</code>
|8
|'''Activation and PEP end''' — the last byte of the code
|-
|<code>+0x58</code>
|2
|Flags
|-
|<code>+0x5C</code>
|2
|Program state
|-
|<code>+0x90</code>
|1
|Program type
|-
|<code>+0x94</code>
|4
|Program entry procedure module number
|-
|<code>+0x9C</code>
|4
|Program entry procedure string ID
|-
|<code>+0xA0</code>
|2
|Minimum parameters
|-
|<code>+0xA2</code>
|2
|Maximum parameters
|-
|<code>+0xD0</code>
|8
|Pointer to the program header extension
|-
|<code>+0xD8</code>
|8
|Pointer to the trace-back locator
|-
|<code>+0xE0</code>
|8
|Pointer to the module table
|-
|<code>+0xE8</code>
|8
|Pointer to observability information
|-
|<code>+0xF0</code>
|8
|Pointer to the maintenance header
|}

The header extension adds a pointer to the GLU code list, <code>SEGOFF</code> pairs for the program history and the segment table extension, and a 16-byte hardware feature set at <code>+0x50</code>.

=== Version table ===
Forty bytes of packed version-release-modification halfwords, where <code>0x0740</code> reads as V7R4M0. Among them are the binder's internal and MI levels at <code>+0x02</code> and <code>+0x04</code>, the '''target''' release at <code>+0x06</code>, the '''created-on''' release at <code>+0x08</code>, the language release at <code>+0x10</code>, the CCSID at <code>+0x1E</code> and the low and high optimisation levels at <code>+0x20</code> and <code>+0x22</code>.

The target and created-on values here are what decide whether an object will restore onto a given release, so they are worth reading before attempting a restore that might fail.

=== Segment table ===
A header of allocated size, entry count and version, then the entries beginning at <code>+0x10</code>. '''Entries are a fixed 48 bytes'''; the size field is the allocation, not header plus count times entry, so deriving the stride from it gives the wrong answer.

Each entry holds the segment address at <code>+0x00</code>, a limbo address at <code>+0x08</code>, a declared page count at <code>+0x10</code>, and a one-byte ''segment use'' at <code>+0x12</code>: <code>0x01</code> static storage, <code>0x02</code> the program object, <code>0x04</code> constants, <code>0x06</code> trace-back.

A parallel ''segment table extension'', reached by a <code>SEGOFF</code> in the program header extension, records how much of each segment is actually used as opposed to allocated. Its entries begin at <code>+0x18</code> and are 24 bytes, of which the first four are the byte count.

=== Activation header ===
{|class="wikitable"
!Offset
!Size
!Field
|-
|<code>+0x00</code>
|8
|'''Program entry procedure entry point''' — the first instruction
|-
|<code>+0x08</code>
|4
|PBV size
|-
|<code>+0x10</code>
|8
|Pointer to the PBV relocation array
|-
|<code>+0x18</code>
|8
|Pointer to the static PBV array
|-
|<code>+0x20</code>
|4
|PBV relocation count
|-
|<code>+0x24</code>
|4
|Dependent service program count
|-
|<code>+0x28</code>
|8
|Pointer to the dependent service program array
|-
|<code>+0x4C</code>
|4
|Constant frame count
|-
|<code>+0x50</code>
|8
|Pointer to the constant frame definition array
|-
|<code>+0x58</code>
|8
|Pointer to the program export array
|-
|<code>+0x60</code>
|4
|Export count
|}

For a bound program with no exports most of these are zero. For a service program they are the published interface, and the dependent service program array is the object's dependency list — which makes it possible to work out what a program binds to without a machine to run <code>DSPPGM</code> on.

=== Maintenance header ===
Holds the copyright list size and count and a <code>SEGOFF</code> to the copyright text — a 4-byte length followed by EBCDIC — along with <code>SEGOFF</code> pairs for the external object list, static activation and export information, the last non-observable segment and size, and the lowest and highest PBV identifiers.

== Modules ==
The module table has the same shape as the segment table: header, then 48-byte entries from <code>+0x10</code>, each giving a pointer to a module header, a module domain and a module subtype.

A module header is a long run of pointers: to the program header it belongs to, the copyright table, the module version table, binding information, static information, the end-of-line table, observability information, the module string directory, the entry point table, the VLIC table, the procedure table, module constants, and the module header extension. It also carries the module type at <code>+0x01</code> — <code>0x01</code> for OPM and <code>0x03</code> for ILE — the module attributes at <code>+0xA8</code>, and the program entry procedure's dictionary ID, string ID, procedure number and parameter counts from <code>+0xAC</code> to <code>+0xBC</code>.

Two of its pointers characteristically leave the program segment: the module string directory and the module constants both live in the <code>0x0022</code> segment. When hunting for literal data referenced by the code — message identifiers, format names, table constants — that is the segment to search, and these two pointers give its exact extent.

=== Module version table ===
This is the most immediately informative structure in the whole object.

{|class="wikitable"
!Offset
!Size
!Field
|-
|<code>+0x02</code>
|2
|Language release
|-
|<code>+0x0A</code>
|2
|Instruction release
|-
|<code>+0x0C</code>
|2
|Target release
|-
|<code>+0x0E</code>
|2
|Created-on release
|-
|<code>+0x10</code>
|2
|Optimisation level
|-
|<code>+0x14</code>
|30
|Source module name
|-
|<code>+0x32</code>
|30
|Source module qualifier
|-
|<code>+0x50</code>
|20
|Compiler name
|-
|<code>+0x64</code>
|2
|Earliest compiler release
|}

Read the compiler name before spending any time on a disassembly. A module reporting <code>MX CONVERTED</code> was ''translated'' from an older object rather than compiled from source at this release, and the generated code will not resemble what a current compiler emits.

== The instruction stream ==
The code is a single contiguous run inside the first segment, bounded by two fields already listed above:

<pre>
start = activation header, program entry procedure entry point
end = program header, activation and PEP end (inclusive)
</pre>

It is 64-bit big-endian '''PowerPC AS'''. A stock disassembler invoked as <code>objdump -D -b binary -m powerpc:common64 -EB</code>, with the load address adjusted to the start offset, will produce a listing whose addresses line up with anything printed by Display/Alter/Dump.

Two caveats apply, and both matter.

PowerPC AS is not plain PowerPC. The tagged-pointer instructions and other AS-only operations have no encoding in a stock PowerPC disassembler and will appear as invalid, or worse, as an unrelated mnemonic that looks plausible. Treat such a listing as a starting point rather than as authority.

The run is also not pure code. Trace-back tables and constants are interleaved with instructions, so a linear sweep will decode data as code somewhere. For an object that still has its observability information, the trace-back locator and the module tables provide the boundaries needed to separate the two; for an object whose observability has been removed, they do not, and the separation has to be inferred from the code itself.

== Scope of this description ==
Field offsets were derived by lining a printed Display/Alter/Dump of a program object up against the same object's bytes extracted from a save file, and then checked by decoding the object independently and comparing every field against the printout. Structures that the dump prints but that were empty in the object used — the signature table, the export and import arrays, the service program tables and the secondary entry point table — are located by pointer but their contents are not described here; establishing those needs a service program to work from.

Only <code>*PGM</code> is covered. <code>*SRVPGM</code> and <code>*MODULE</code> share much of this layout but have additional tables of their own.

== See also ==
* [[File Formats:SAVF]] — how to get a program object's bytes off a machine or out of a distribution medium
* [[Data Structures:LID]] — the same single-level store address split, in a different container

[[Category: System Internals]]
[[Category:AI generated not reviewed]]

Reverse engineering SLIC

2026-08-16T19:06:58Z

PoC: /* See also */ +cat

Reverse engineering '''SLIC''' — the Licensed Internal Code below the Machine Interface — is mostly a problem of turning addresses into names and getting bytes off the machine. This article collects the techniques that work, in the order you would actually use them, and the traps that cost the most time.

It assumes access to a machine's DST or SST service tools, and installation media or a SAVSYS for offline work.

== Start with the machine's own link map ==
Before writing any tooling, get the '''SLIC link map''' from the machine. It is reached through Display/Alter/Dump and can be printed to a spooled file, then exported.

The printed format is one row per module:

<pre>
NICKNAME ADDRESS(10+6) PART NAME VERSION RELEASE REL DATE/TIME INST DATE/TIME
###FLITE FFFFFFFFF4 C29820 SRVC_MACRO_FLIGHTLOG 0007 0400 20190217 094024 ...
</pre>

A V7R4 machine yields around 21,000 distinct modules. This single artefact answers "what is at this address" and "where is this module" authoritatively, for that machine, and it is the first thing to obtain.

Two properties make it more useful than it first appears:

* '''The spacing between consecutive entries equals the module's text length.''' Verified against the lengths ''Find LIC Module'' reports — exact matches. So the map gives extents as well as bases, which means any address can be resolved to a module ''and'' an offset within it.
* '''Module names are stable across PTFs; addresses are not.''' Look modules up by name whenever possible.

<blockquote>'''Note!''' Part names are upper-cased in the printout but the ''Find LIC Module by name'' panel is '''case-sensitive'''. <code>IoHriTaggedVpd</code> resolves; <code>IOHRITAGGEDVPD</code> does not. Take the spelling from the on-screen display, not the print.</blockquote>

== Getting bytes off the machine ==
Display/Alter/Dump can print a storage range to a spooled file. Exported as PDF and run through <code>pdftotext -layout</code>, each line is an address and 32 bytes:

<pre>
FFFFFFFFC5 943160 3C40CC4DFBC1FFF0 FBE1FFF87C0802A6 F8010028F821FF01 3C000010F8010008
</pre>

<blockquote>'''Note!''' The formatter '''collapses repeated lines''':
<pre>
127 LINES FFFFFFFF84 11B020 TO FFFFFFFF84 11BFE0 SAME AS ABOVE
</pre>
A naive parser silently sees a fraction of the data — in one case 44 % of a 1 MiB region — and reports no error. Any parser must expand these runs.</blockquote>

Dumping a whole module at once is usually better than dumping the function you think you want: module extents are known from the link map, and the surrounding code frequently answers the next question.

== Addresses ==
An SLS address is a '''40-bit segment identifier and a 24-bit offset''', which is exactly how the ''Specify Address'' panel splits it, so segments are 16 MiB.

'''Probe before dumping.''' Entering an address in an unmapped segment returns

<pre>
80 exception, segment does not exist.
</pre>

This is a free existence oracle. But probe the '''address you actually care about''', not offset zero of its segment — segments are sparsely populated, and offset 0 being unmapped says nothing about the rest. A segment can be mapped at <code>0x010000</code> and raise the exception at <code>0x120000</code>.

For a mapped address, the '''ADDRESSINFO''' Advanced Analysis command reports the page-directory entry and hardware page-table entries, confirming backing and page size.

=== Runtime and staged addresses differ ===
The same module may appear at one address in the link map and another as its runtime text. Where these differ, '''module-relative offsets are stable''': a symbol at <code>+0x26d0</code> in the staged image is at <code>+0x26d0</code> in the runtime image. Deriving runtime addresses this way works reliably; assuming a constant delta between two images does not.

== Names from the code ==
Two structures let a container image be turned into a link map offline.

* '''Traceback trailers.''' Every compilation unit ends with a <code>TBTB</code> eyecatcher (<code>E3C2E3C2</code>) followed by a pointer to a descriptor. A trailer covers a whole compilation unit, so it localises rather than pinpoints — and a forward scan for "the next trailer" will silently attribute a ''later'' function's name if the target has no trailer of its own.
* '''Link-loader descriptors.''' Richer: one per procedure, with the entry address at <code>+0x08</code> and the name at <code>+0x38</code>. Names beginning <code>#</code> are SLIC-internal modules; the rest are C++ mangled symbols.

<blockquote>'''Note!''' Two mistakes here are expensive. First, '''do not require the entry address to fall inside a segment the container carries''' — runtime-only segments exist, and filtering on containment silently drops every module in them. Second, the name is not always at a fixed offset from the descriptor; scanning for the longest identifier run within the descriptor is more robust than assuming one.</blockquote>

== Module metadata ==
''Find LIC Module'' reports, for any address: module name, nickname, compile and link/load timestamps, version and release level, '''PTF level''', and the text, data and BSS extents plus the TOC address.

The same record exists on media, anchored by the EBCDIC PTF-level string (<code>SYSBASE</code> for an unpatched module):

<pre>
+0x00 PTF level 7 bytes "SYSBASE"
+0x07 version 4 bytes "0007" = V7
+0x0B release/mod 4 bytes "0400" = R4M0
+0x0F nickname 8 bytes
+0x27 build id 7 bytes "AJDG301"
</pre>

These records cluster in their own segments rather than sitting beside the code they describe. A V7R4 SAVSYS yields about 34,000 of them.

The '''PTF level''' field is the useful one: it distinguishes base modules from patched ones without a changelog, which is exactly what you need when a running machine and its install media disagree on addresses.

<blockquote>'''Note!''' <code>SYSBASE</code> means "no PTF applied to this module" — '''not''' "identical to your install media". Two machines can both report <code>SYSBASE</code> and differ, because base levels themselves differ between RS releases. Compile and link dates make this checkable.</blockquote>

== Calls between modules ==
External calls do not go through a table you can read off.

A call is a two-instruction sequence — an ordinal loaded into <code>r11</code>, then a <code>bla</code> into the '''BLA vector''' at the top of the address space. IBM's own term, from the Static Directory, is ''Pageable BLA'' for the pageable half.

<pre>
V4R4 ori r11,r13,<ordinal> ; bla <vector>
V7R4 li r11,<ordinal> ; bla <vector>
</pre>

The stub reached by the <code>bla</code> computes the target arithmetically:

<pre>
rldicr r11,r11,sh,59 ; ordinal x 4 (V4R4) or x 16 (V7R4)
addis r11,r11,<simm>
mtctr r11
bctr
</pre>

so <code>callee = (sext16(simm) << 16) + (ordinal << sh)</code>. The <code>simm</code> values are not derivable and must be read from the vector — which is not carried in any container, so a dump is required once per build.

The stub array is findable '''structurally''' — runs of 16-byte blocks with three constant words and one varying — which locates it without knowing the shift. Searching for a specific opcode pattern from another release will not find it.

== Reading conditional branches ==

Every policy decision in SLIC is a conditional branch, and getting one backwards silently inverts whatever it decides — the listing looks the same either way. The encoding is ordinary PowerPC, but two things about it are easy to get wrong when reading a listing rather than writing an assembler.

'''<code>BO</code> selects the sense, <code>BI</code> selects the bit.''' <code>BO = 12</code> is branch-if-true and <code>BO = 4</code> is branch-if-false. <code>BI</code> numbers the condition register's bits end to end — <code>BI = 4 × field + bit</code> — and the four bits of a field are, in order, '''LT, GT, EQ, SO'''. So within <code>CR0</code>, <code>BI = 0</code> is LT, '''<code>BI = 1</code> is GT''' and <code>BI = 2</code> is EQ; within <code>CR1</code> the EQ bit is <code>BI = 6</code>.

That matters most after the idiom SLIC tests a policy bit with:

LWZ 4, 1148(16) ; a flag byte out of an object
RLDICL. 3, 4, 0, 63 ; r3 = byte & 0x01, and set CR0
BC 4, 1, ... ; BO=4 branch-if-false, BI=1 GT

<code>RLDICL.</code> leaves 0 or 1 and sets <code>CR0</code> by comparing it against zero, so GT is set exactly when the bit is on, and '''branch-if-not-GT is taken when the bit is CLEAR'''. Read <code>BI = 1</code> as EQ instead and the same branch appears to be taken when the bit is '''set''' — the exact opposite, with nothing in the listing to show which reading is in force.

A routine that uses two condition register fields settles the numbering without any external reference: a dispatch chain alternating <code>CMPI 0,…</code> / <code>BCLR 12,2</code> with <code>CMPI 1,…</code> / <code>BCLR 12,6</code> is comparing a value against a series of constants and returning on each match, which is only a dispatch if <code>BI</code> 2 and 6 are the EQ bits of <code>CR0</code> and <code>CR1</code>.

'''Two rendering traps make listings read backwards.''' Both apply to any disassembler that prints raw encoding fields instead of assembler syntax:

* '''The destination is not always the first operand.''' <code>ADDI</code>, <code>ADD</code> and <code>SUBF</code> print it first; the logical forms <code>ORI</code>, <code>AND</code> and <code>ANDC</code> print <code>rS</code> first and the destination <code>rA</code> '''second'''. A load/modify/store triple is the giveaway: <code>LBZ 27,28(28)</code> / <code>ORI 27,26,1</code> / <code>STB 26,28(28)</code> only makes sense as "load into r27, or in 1 giving r26, store r26". Read left to right, whole routines look like a run of dead stores.
* '''The <code>Rc</code> dot can go missing.''' <code>rlwinm.</code> and <code>rlwimi.</code> do set <code>CR0</code>, but a decoder that appends the dot only for primary opcode 31 prints them without it — and then the branch after them looks like it is testing a condition register nothing wrote. Check bit 31 of the raw word before concluding a test is stale.

== Traps worth knowing ==
* '''Never resolve a live pointer against a container image.''' A pointer read from a running machine names a runtime address; dereferencing it in a saved image lands on unrelated data and produces a plausible, wrong answer.
* '''Verify cross-image mappings by content, at the address you intend to use.''' A delta confirmed at one address does not hold across a segment.
* '''A positional coincidence looks exactly like a structural fact.''' Runs of plausible-looking pointers, matching offsets and familiar constants all occur by chance in images this size. Confirm with bytes.
* '''TOC contents are filled in at IPL.''' Container images hold unrelocated placeholders, so a TOC walk is only meaningful against live storage.
* '''Decode <code>BO</code> and <code>BI</code> from the raw word before believing a branch, and record the sense you decoded.''' A branch that decides a policy bit is worth the thirty seconds; getting it wrong produces working-looking code that does the opposite of what the machine does, and the mistake survives review because the reasoning around it was written to match. See [[#Reading conditional branches]].
* '''A field the machine rebuilds at startup is an output, not an input.''' Configuration areas on disk are often regenerated from the machine's live configuration during power-on, and the code that later reads one may also stamp it on the way past. Reading such a field back as though it decided something is the same tautology as a model agreeing with its only caller, moved from code into data — and it is unusually convincing, because the value really is there and really is self-consistent. Establish who last wrote a field before deciding what it means.

== See also ==
* [[System Files:QFILEMCD]]
* [[System Files:QFILEIML]]
* [[Data Structures:LID]]
* [[SRC]]

[[Category: System Internals]]
[[Category:AI generated not reviewed]]

System Internals:SLIC DASD device recognition

2026-08-16T19:06:47Z

PoC: +cat

The '''SLIC DASD device recognition''' table is the static list, inside the OS/400 Licensed Internal Code (SLIC), of which SCSI disk drives the system will accept as a DASD (disk) unit. This page describes how that recognition works, how to find and decode the table in a SLIC image, and — as a worked example — the complete list a V4R4 machine accepts. The method generalises to any release and to other SLIC device tables.

Understanding it matters for preservation: OS/400 refuses ordinary SCSI disks, so keeping a machine alive after a disk failure means presenting a drive (real or emulated) that answers the SCSI bus the way SLIC expects.

== How SLIC decides a disk is acceptable ==

A disk becomes an eligible DASD unit only if it passes three independent gates, all implemented in the SLIC disk device driver:

# '''SCSI INQUIRY must match a static table.''' SLIC compares the drive's INQUIRY vendor id (bytes 8–15) and product id (bytes 16–31) against a built-in table. Only IBM-badged units qualify: the vendor id is normally <code>IBMAS400</code> (a handful of early units use <code>IBM␠␠␠␠␠</code> and two OEM units use <code>QUANTUM␠</code>). An off-the-shelf drive reports its own vendor and is rejected. This is exactly what the "custom firmware" on IBM's 660x/671x disks does: IBM reflashed standard Ultrastar/Corsair mechanisms to answer INQUIRY with an IBM vendor id and an IBM product id.
# '''Vendor-unique SKIP READ / SKIP WRITE.''' The driver issues IBM vendor-unique SCSI commands that read or write a run of sectors while skipping masked ones, used by the Single-Level Store paging path. A faithful drive must implement these, not just standard READ/WRITE.
# '''Capacity from VPD.''' The unit's size is taken at run time from the drive's Vital Product Data / <code>READ CAPACITY</code>, not from the table — the table has no capacity column. An impersonating drive must report a capacity that is legal for the feature type it claims.

== Finding and decoding the table ==

In a SLIC image the table is a run of fixed-size records. On V4R4 each record is 40 bytes:

<pre>
bytes 0- 3 feature type EBCDIC digits, e.g. F6F6F0F7 = "6607"
bytes 4- 5 model EBCDIC, e.g. "1 "
byte 6 class flag 0x00 normal; 0x80 on the 18 GB Ultra2/LVD units
bytes 7-15 reserved 0x40 (EBCDIC space) padding
bytes 16-23 INQUIRY vendor ASCII, matched against INQUIRY bytes 8-15
bytes 24-39 INQUIRY product ASCII, matched against INQUIRY bytes 16-31
</pre>

The type and model are EBCDIC (digit ''n'' = byte <code>0xF''n''</code>); the INQUIRY strings are ASCII. To locate the table, search the image for the ASCII vendor strings <code>IBMAS400</code> / <code>QUANTUM␠</code>: the records sit at a fixed 40-byte stride around them. The same trick — anchor on a known ASCII string, then read the fixed-width record around it — recovers other SLIC hardware tables (IOP/controller CCIN tables, adapter tables, and so on).

== The V4R4 list ==

Every drive a V4R4 system accepts, decoded from the image. "Physical drive" is identification from IBM/Quantum model nomenclature, not read from the binary; the feature type, model and INQUIRY strings are.

{| class="wikitable"
! Feature/Model !! INQUIRY vendor !! INQUIRY product !! Physical drive
|-
| 6109 / 0 || <code>IBM␠␠␠␠␠</code> || <code>0663H12</code> || IBM 0663 "Corsair", ~2 GB
|-
| 6109 / 1 || <code>IBM␠␠␠␠␠</code> || <code>0661371</code> || IBM 0661 "Pixie", ~0.37 GB
|-
| 6105 / 0 || <code>IBM␠␠␠␠␠</code> || <code>0661467</code> || IBM 0661 "Pixie", ~0.47 GB
|-
| 6107 / 0 || <code>IBMAS400</code> || <code>0664M1H</code> || IBM 0664 "Corsair-4", ~4 GB
|-
| 6603 / 0 || <code>IBMAS400</code> || <code>0664N1H</code> || IBM 0664 "Corsair-4", ~4 GB
|-
| 6603 / 1 || <code>IBMAS400</code> || <code>0662S12</code> || IBM 0662 "Corsair", ~1.2 GB
|-
| 6602 / 0 || <code>IBMAS400</code> || <code>0662SW1</code> || IBM 0662 "Corsair", ~1.0 GB
|-
| 6602 / 1 || <code>IBMAS400</code> || <code>DFHSS1W</code> || IBM Ultrastar XP, ~1 GB
|-
| 6605 / 1 || <code>IBMAS400</code> || <code>DFHSS2W</code> || IBM Ultrastar XP, ~2 GB
|-
| 6606 / 1 || <code>IBMAS400</code> || <code>DFHSS4W</code> || IBM Ultrastar XP, ~4 GB
|-
| '''6607 / 1''' || <code>IBMAS400</code> || <code>DCHS09W</code> || IBM Ultrastar 2XP, ~9 GB
|-
| 6713 / 1 || <code>IBMAS400</code> || <code>DGHS18U</code> || IBM Ultrastar 18XP, ~18 GB
|-
| 6714 / 1 || <code>IBMAS400</code> || <code>DGVS09U</code> || IBM Ultrastar 9ES/9LZX, ~9 GB
|-
| 6717 / 1 || <code>QUANTUM␠</code> || <code>SSQD107</code> || Quantum, ~10.7 GB
|-
| 6730 / 0 || <code>QUANTUM␠</code> || <code>SSQD160</code> || Quantum, ~16.0 GB
|-
| 6731 / 0 || <code>IBMAS400</code> || <code>DRVS18D</code> || IBM Ultrastar 18ES/18LZX, ~18 GB, Ultra2/LVD
|}

Feature-type numbers do not track capacity linearly: the type encodes the AS/400 usable-capacity class (after 520-byte-sector overhead), not the drive's native size. The much-cited 6607 is here as <code>IBMAS400</code> / <code>DCHS09W</code>.

== Notes ==

* "Ide" in SLIC symbol names (e.g. the driver classes handling these disks) is the disk device-driver namespace, '''not''' ATA/IDE.
* Numbers like 2748, 6502, 6512, 6751, 6753, 6754 that appear on other SLIC symbols are IOP / disk-controller CCINs, not drive models.
* An emulated target (for example on open SCSI-emulator firmware) must present one of the vendor+product pairs above verbatim, space-padded to the SCSI field widths, implement the vendor-unique SKIP commands, and report a legal capacity via <code>READ CAPACITY</code>.

[[Category:System Internals]]
[[Category:AI generated not reviewed]]

Category:AI generated not reviewed

2026-08-16T19:04:13Z

PoC: New

Pages in this category are generated by AI and have not been examined for correctness.

Configuring X.25 link through Cisco IP network

2026-08-12T18:55:40Z

PoC: typo

Sometimes, older, donated hardware comes without LAN I/O-adapters. Sometimes it has serial communication I/O-adapters, though. This article points out how to network two AS/400's with the help of (older) Cisco hard- and software through the [[wikipedia:X.25|X.25]] protocol, and XOT. This example does not make use of switched virtual circuits (SVC), but permanent virtual circuits (PVC).

== Motivation ==
[[File:Cisco_1005_disassembled.jpg|thumb|right|Cisco 1005, disassembled for de-dusting, and power connector replacement]]
I wanted my 9401-P03 to be optically present on my desk instead in a dusty corner. The dusty corner had a Cisco 2513 nearby for SDLC network integration, but the new place just has Ethernet. So, another router was needed. Because this machine already generates considerable noise, a fanless router was desired.

First try was with a very old 1005. But even with the latest IOS release 12.0(28d), that model doesn't support SDLC encapsulation on its serial interface. Hence I decided to switch to a common protocol both machines understand: X.25, or Frame Relay. Using ''Frame Relay'' was not feasible, because OS/400 supports Frame Relay only with certain cabling options and IO-Adapters I don't have. Hence I chose X.25 as the last common denominator for RS-232/V.24.

Sadly, the 1005 makes the connection fail as soon as actual transfers are attempted. I tested line speeds down to 9600 bps without success. For fault isolation, I grabbed an old Cisco 1601-R, and copied over the configuration. Connection was working at the first try with 9600 bps. I increased the line speed to 64 Kbps — the same speed the 2612 connected to the other Machine showed was possible without problems. Most notable benefit to use X.25 compared to a direct SLDC link is that serial speeds up to 64 Kbps are allowed and apparently possible, instead of just 19200 bps with SDLC.

== Requirements ==
[[File:IBM 2652.jpg|thumb|right|6152 Adapter, located in a P02]]
[[File:IBM 2609.jpg|thumb|right|2609 Adapter socket, located in a P03]]
[[File:IBM 2609-plugged.jpg|thumb|right|2609 Plug with heavy cable]]
[[File:IBM 2609 Brick.jpg|thumb|right|2609 Breakout-Brick — note that the Cisco cable is plugged directly which is '''wrong''', and only shown for illustration purposes.]]
* Two AS/400 machines, complete and functioning
** <code>QAUTOCFG</code> system variable switched to on
** Local serial port with required breakouts, such as a #2609, #2652, #2720, etc.
** Matching IBM V.24 Modem Cable<ref>If the machine was attached to a modem in earlier times, and you obtained all the cables, all requirements are satisfied.</ref>
<blockquote>'''Note!''' It is of utmost importance to keep in mind that the AS/400 serial ports have ''sense pins'', to know which kind of cable is attached. If you plug in just an ordinary PC serial cable, you’ll eventually find the succinct message in the QSYSOPR message queue, that a cable could not be found. Therefore the requirement of an ''IBM V.24 Modem Cable'', or a self made cable, or adapter, providing the necessary sense pin connectivity.

'''For this reason, you'll need to plug the DB-25F socket connector of the Cisco cable to the modem cable, and not directly to the AS/400’s port.'''</blockquote>

* Cisco 16xx, 26xx or similar router model with T-Type serial interface (card),
** Cisco CAB-232 FC,
** Router LAN ports configured so they can reach each other via IP.

The basic network topology is symmetric. Both AS/400s are connected to their respective Cisco routers through their serial port, and both Cisco routers are connected to each other with some LAN technology, presumably Ethernet.

''Fiona'' → Cisco 1601-R (192.168.1.97) → Cisco 2612 (192.168.1.5) → ''Nibbler''

== Configuration ==
Assumption is that the routers already have a basic configuration applied.

After plugging everything together like pointed out above, obtain the resource names of the serial ports. Type <code>wrkhdwrsc *cmn</code> to get a list of communication hardware, and associated ports. Example:

'''Resource Type Text'''
CMB01 917B Combined function IOP
LIN01 2609 Comm Adapter
LIN011 2609 V.24 Port
LIN012 2609 V.24 Port

<blockquote>'''Note!''' OS/400 V3 seems to not designate ports as ''CMN'', but as ''LIN'' with three digits. Newer releases designate ports on an adapter as ''CMN''.</blockquote>

After you have created the line description, run <code>dsplind x25line</code> to find the generated Exchange-ID.

Here is a table to help configuring what, where, and in which order.

{|class="wikitable"
!Configuration
!Cisco 1601-R (192.168.1.97)
!Cisco 2612 (192.168.1.5)
|-
|valign="top"|'''Cisco IOS'''
|valign="top"|
x25 routing

interface Serial0
description Fiona LIN011
encapsulation x25 dce
x25 modulo 128
x25 ltc 100
x25 pvc 6 xot 192.168.1.5 interface Serial 0/1 pvc 5 packetsize 512 512
clockrate 64000

interface Ethernet0
ip address 192.168.1.97 255.255.255.0
|valign="top"|
x25 routing

interface Serial0/1
description Nibbler CMN01
encapsulation x25 dce
load-interval 60
x25 modulo 128
x25 ltc 100
x25 pvc 5 xot 192.168.1.97 interface Serial 0 pvc 6 packetsize 512 512
clock rate 64000

interface FastEthernet1/0
ip address 192.168.1.5 255.255.255.0
|-
! 
!Fiona (V3R2)
!Nibbler (V4R5)
|-
|valign="top"|'''Serial resource'''
|valign="top"|LIN011
|valign="top"|CMN01
|-
|valign="top"|'''Line description'''
|valign="top"|<code>crtlinx25 lind(x25line) rsrcname(lin011) lglchle((006 *pvc)) netadr(00000000000000) cnninit(*local) interface(*rs232v24) linespeed(19200) dftpktsize(512) modulus(128) adrinsert(*no) linkspeed(64000) cmnrcylmt(1 10)</code>
|valign="top"|<code>crtlinx25 lind(x25line) rsrcname(cmn01) lglchle((005 *pvc)) netadr(00000000000000) cnninit(*local) interface(*rs232v24) linespeed(19200) dftpktsize(512) modulus(128) adrinsert(*no) linkspeed(64000) cmnrcylmt(1 10)</code>
|-
|valign="top"|'''Exchange-ID'''
|valign="top"|05608945
|valign="top"|05641700
|-
|valign="top"|'''Controller description'''
|valign="top"|<code>crtctlappc ctld(nibbler) linktype(*x25) line(x25line) maxframe(512) rmtcpname(nibbler) exchid(05641700) netlvl(1984) lglchlid(006) nodetype(*calc) tmsgrpnbr(*calc) autodltdev(*no) cmnrcylmt(10 1)</code>
|valign="top"|<code>crtctlappc ctld(fiona) linktype(*x25) line(x25line) maxframe(512) rmtcpname(fiona) exchid(05608945) netlvl(1984) lglchlid(005) nodetype(*calc) tmsgrpnbr(*calc) autodltdev(*no) cmnrcylmt(10 1)</code>
|}

=== Notes ===
* If you change the serial encapsulation value, all X.25 related configuration is discarded!
* The PVC-ID for Cisco IOS is a decimal value, and for OS/400, it's a hex value!
* You can use the same PVC on both sides.
* You cannot create the line description with the full speed outright due to error CPD26DC (Maximum line speed for RS-232/V.24 is 19200 bps.). Create the line with <code>linespeed(19200)</code>, and edit the lind again, setting the desired speed of 64 kbps.

Proven to work:
* Cisco 2612 with added WIC-1T, and image C2600-BINO3S3, Version 12.3(26)
* Cisco 1601-R, and image C1600-BNR2SY, Version 12.3(26)

When one side is powered down, the other side frequently posts error messages to the ''qsysopr'' message queue and problem reporting facility.

== Initiation, and function verification ==
Turn on debugging on the Cisco routers:
term moni
debug x25

Run <code>wrkcfgsts *lin x25line</code> and use the interactive screen to vary on the line on both sides. You should see the lines coming up.
%LINK-3-UPDOWN: Interface Serial0/0, changed state to up
%LINEPROTO-5-UPDOWN: Line protocol on Interface Serial0/0, changed state to up

On the Cisco Router(s), you should see output of <code>show int ser0/1</code> similar to the following:
Serial0/1 is up, line protocol is up
Hardware is PowerQUICC Serial
Description: Nibbler CMN01
MTU 1500 bytes, BW 19200 Kbit, DLY 20000 usec,
reliability 255/255, txload 1/255, rxload 1/255
Encapsulation X25, loopback not set
X.25 DCE, version 1984, address <none>, state R1, modulo 128, timer 0
Defaults: idle VC timeout 0
cisco encapsulation
input/output window sizes 2/2, packet sizes 128/128
Timers: T10 60, T11 180, T12 60, T13 60
Channels: Incoming-only none, Two-way 100-1024, Outgoing-only none
RESTARTs 32/0 CALLs 0+0/0+0/0+0 DIAGs 34/0
LAPB DCE, state CONNECT, modulo 8, k 7, N1 12056, N2 20
T1 3000, T2 0, interface outage (partial T3) 0, T4 0
VS 6, VR 4, tx NR 4, Remote VR 6, Retransmissions 0
Queues: U/S frames 0, I frames 0, unack. 0, reTx 0
IFRAMEs 1664/1953 RNRs 0/0 REJs 0/0 SABM/Es 55/0 FRMRs 0/0 DISCs 0/24
Last input never, output 00:50:34, output hang never
Last clearing of "show interface" counters 23:57:07
Input queue: 0/75/0/0 (size/max/drops/flushes); Total output drops: 0
Queueing strategy: fifo
Output queue: 0/40 (size/max)
1 minute input rate 0 bits/sec, 0 packets/sec
1 minute output rate 0 bits/sec, 0 packets/sec
3654 packets input, 76438 bytes, 0 no buffer
Received 0 broadcasts, 0 runts, 0 giants, 0 throttles
29 input errors, 0 CRC, 29 frame, 0 overrun, 0 ignored, 0 abort
3526 packets output, 81439 bytes, 0 underruns
0 output errors, 0 collisions, 917 interface resets
0 output buffer failures, 0 output buffers swapped out
51 carrier transitions
DCD=up DSR=up DTR=up RTS=up CTS=up

== See also ==
* [[Serial Cables IDs]]
* [[RS-232 Modem Cable Pinout]]
* [[Integrating LAN-less Machines into a local Token Ring]]
* [[Configuring TCP/IP and SLIP with Cisco-Router and V3R2]]
* [[Serial networking scenarios with Cisco-Routers]]

== Weblinks ==
* [https://website.fis.agh.edu.pl/complab/doc/Cisco_IOS_11.0/cbook/cx25.htm Configuring X.25 and LAPB] on Cisco IOS, Faculty of Physics and Applied Computer Science Poland<ref>Very old documentation linked intentionally. Note: The configuration option ''tunnel'' was renamed to ''xot'' in newer IOS releases.</ref>
* [https://public.dhe.ibm.com/systems/power/docs/systemi/v6r1/en_US/sc415405.pdf X.25 Network Support]
* [https://en.wikipedia.org/wiki/RS-232#Timing_signals RS-232 timing signals], Wikipedia
* [https://www.cisco.com/c/en/us/support/docs/routers/10000-series-routers/46800-cab232mtfc.html#cab-232fc Serial Cable CAB-232FC], Cisco.com
* [https://www.ibm.com/resources/publications/OutputPubsDetails?PubID=SY44590203 AS/400 Service Functions], SY44-5902-03<ref>PDF page 245, Table 51, bottom line on that page displays the cable-id connected pins. See also the notes on the top of the next page.</ref>

== Footnotes ==
<references />

[[Category: Hardware Configuration Guide‏]]
[[Category: Software Configuration Guide‏]]

Apple SNA•ps

2026-08-09T21:18:56Z

PoC: Precise naming

[[File:Apple SNAps Carton.jpg|thumb|right|Package]]
[[File:5250term.gif|thumb|right|Active 5250 client connection]]
[[File:Snagw-run.gif|thumb|right|SNA•ps Gateway information windows]]
'''Apple SNA•ps''' is an application software package for Apple Macintosh computers running System 7. Its purpose is to provide Macintosh users access to resources located on IBM Midrange and Mainframe computers. It is the result of a collaboration between Apple and IBM in the early 1990s and has been developed by ''Orion Network Systems, Inc.'' SNA•ps is short for ''Systems Networking Architecture protocols and services''.

SNA•ps uses IBMs proprietary ''Systems Network Architecture'' family of network protocols to talk to the IBM side of affairs,<ref>Newer versions of the SNA•ps 5250 client also support IP/tn5250 as alternate network transport.</ref> and Apple’s proprietary AppleTalk on the Macintosh side.

So far, only two publicly available releases are known: version 1.1 from 1992, and version 2.0.1 from 1994. The beta-level release of SNA•ps 1.1 was available during 1991 and was the primary testing level for the ''IBM/Apple IBM Enterprise Networking Guide for SNA Products'' guide.

The main differences between version 1.0, and version 1.1 are the introduction of 3287 printer emulation, and 16 Mbps Token Ring support.

SNA•ps comprises of a client and server component. Both can run on the same Macintosh computer, though.
* ''Gateway'' software with a license dependent maximum count of
** 8, 32, or 64 [[wikipedia:IBM Systems Network Architecture#Logical Unit (LU)|LU]]-sessions for version 1.1
** 10, 35, or 70 users for version 2.0.1
* ''Gateway Client''<ref>Designated ''GC'' in product descriptions.</ref> for 3270 and 5250 terminal services, as well as printing services.

<blockquote>'''Note:''' Further restrictions in terms of session count may apply depending on selected transport option technology, and available memory on said transport option.</blockquote>

This article focuses on AS/400 and thus on 5250 connectivity. Since the AS/400 platform also has 3270 compatibility support, the SNA•ps 3270 client for 3270 sessions can be used when required, and with an appropriately configured AS/400 system. See below for Macintosh System Software version requirements.

Different versions of ''SNA•ps'' are available on Apple’s [https://macintoshgarden.org/apps/apple-cdsn-computers-connectivity-demonstration-and-support-network-reference-cd ''Computer's Connectivity Demonstration and Support Network'' Reference CD] at Macintosh Garden. Note that version 2.0.1 requires a serial number to be entered at install time.

== General overview ==
The ''SNA•ps Gateway'' makes resources provided by the mainframe or the AS/400 via [[wikipedia:Systems Network Architecture#Physical Unit (PU)|SNA PUs]]/LUs or [[wikipedia:IBM Advanced Peer-to-Peer Networking|APPN]]/[[wikipedia:IBM Advanced Program-to-Program Communication|APPC]] available to AppleTalk connected Macs. This means that an (expensive) card for connecting to the mainframe does not have to be installed in every Mac, but one can be shared by many users. Also, adding such a card is not possible in some cases: Compact Macs like the Mac Plus or Mac SE have no or only limited expansion options. In addition, the required network cabling may not exist.

Examples of clients are the terminal emulations [[wikipedia:IBM 3270|3270]], and [[wikipedia:IBM 5250|5250]]). These allow Macs that are connected to the [[[wikipedia:AppleTalk|AppleTalk]] network (e. g. via [[wikipedia:LocalTalk|LocalTalk]]) to establish terminal sessions to a SNA host.

An example of reverse direction is printing support. The ''SNA•ps Print'' client emulates an IBM 8312 printer. Print jobs spooled into a printer queue on the AS/400 are picked up by ''SNA•ps Print'', to be printed using the default (AppleTalk) printer, set in the [[wikipedia:Chooser (Mac_OS)|Chooser]], or saved as text in a file. 
This was a way of making the Apple [[wikipedia:LaserWriter|LaserWriter]] usable from midrange, and indirectly from mainframe computers. The LaserWriter was very expensive at its introduction time.

The counterpart to the ''SNA•ps Gateway'' is a system extension called ''SNA•ps Access''. Client applications use API routines provided by this extension. The SNA•ps API can also be used by third parties; examples have been published by Apple through their developer CDs. An example of this is [[wikipedia:Database abstraction layer|DAL]] for the Macintosh. It can utilize several ways to connect to the actual database; such as IP (via MacTCP) and SNA (via SNA•ps Access).

In the 1990s, IBM made LocalTalk add-on cards for the older AS/400's SPD slots, and released additional software for OS/400 to implement the AppleTalk protocol stack on the AS/400 as well. The implementation on the AS/400 corresponded roughly to the SNA•ps gateway, so that no Mac was required as a gateway: the necessary software ran only on the AS/400. It was only meant to provide display and print functions instead of full APPC capabilities, though. This enabled Macs to function as a console device to the AS/400, but made it impossible to use APPC based services, such as DAL, over the integrated LocalTalk connection.

The IBM document ''Using Apple Macintosh with the AS/400'', Document Number GG24-4071-00 (March 1994) provides detailed insight about SNA•ps, and AS/400 configuration. Unfortunately, this document is no longer available publicly.

== System compatibility ==
The SNA•ps 5250 client requires System 7.0 or higher. Launching it on System 6 gets you a corresponding error message, and the client does not open. Saying that, the 3270 terminal client officially runs under System 6.0.5, and later, though.

The client works on Mac operating system versions up to, and including 8.1. OpenTransport compatibility seems sufficient to support that old software without changes. The client crashes upon connecting via a SNA•ps gateway when ran on PowerPC Macs, though.

A connection via TCP (possible with client version 1.1) provokes the message that the other party doesn’t use the 5250 protocol. This is reproducible under System 7.6.1/OT/PPC as well as under 7.1/MacTCP/68k. Reasons are unknown.

The gateway software requires special hardware for the SNA network connection and is therefore limited to NuBus systems. Documentation states, the gateway needs at least System 7.0 to run. This has not yet been verified. Testing of the gateway software on the first generation NuBus equipped PowerMacs also hasn’t been done, yet.

== Performance ==
Comfortable performance can be attained by running at least the client on 68040 equipped Macs, connected to the gateway through Ethernet.<ref>AppleTalk and IP performance for AFP transfers over the ''Apple Token Ring 4/16 NB Card'' do not exceed 200 kiB/s. In this regard, attainable performance is less than optimal.</ref> This provides answer times of less than a second, e. g. when scrolling through help texts, etc. Measuring of answer times for the gateway running on different classes Macs has not been done, yet.

Running the client on Low End Macs such as the SE/30 yields answer times of around two seconds. All in all, fluid work is not attainable. Comparing LocalTalk and Ethernet with the SE/30 shows no significant differences in answer time, hinting towards the network not being the bottleneck.

== Network transport options ==
The following options to connect to IBM machinery are supported in general:
{|class="wikitable"
! Phy
! Hardware
|-
|Serial/SDLC
|Apple Serial NB Card
|-
|Token Ring
|Apple Token Ring 4/16 NB Card, Apple TokenTalk NB Card<ref>This is a pure 4 Mbps card, but already designed according to MCP specs.</ref>
|-
|<s>Twinax</s><ref>5250 sessions over Twinax are not supported. Implementation was planned, but never was put into code before development ceased. The Enterprise Networking Guide mentions third party products having been ''available which can utilize the twinax feature on this adapter.''</ref>
|Apple Coax/Twinax Card
|}

All of these cards feature their own 68000 CPU, and local memory. They conform to the ''Macintosh Coprocessor Platform'' specification. A more or less small process runs on the card, which exchanges data via message passing with its counterpart ''A/ROSE'' in the Mac OS.

As a novel feature, part of the ''SNA•ps'' gateway software runs on the processor of the respective MCP card. Along with the rest of the software running on the Mac’s main CPU, APPC sessions are encapsulated in AppleTalk, and available to other Macs connected to the network, including LocalTalk. The minimum amount of memory for SNA•ps use is 1 MB. For the 64 LU- and 70 user license, 2.5 MB are required.

<gallery mode="packed">
File:Apple-Token-Ring-NB-Compside.jpg|Apple Token Ring 4/16 NB card, front
File:Apple-Token-Ring-NB-Solderside.jpg|Apple Token Ring 4/16 NB card, back
File:Apple-Coax-Twinax-Compside.jpg|Apple Coax/Twinax card, front
File:Apple-Coax-Twinax-Solderside.jpg|Apple Coax/Twinax card, back
</gallery>

I do not own an Apple Serial NB card, yet.

== AS/400 configuration ==
On the AS/400 side, autoconfiguration for controller, and device descriptions should — at least temporarily — be allowed. See the <code>WRKSYSVAL</code> command and the ''QAUTOCFG'', ''QAUTORMT'' and ''QAUTOVRT'' variables. Maybe also adjust the variables ''QLMTDEVSSN'' and ''QLMTSECOFR''. See help texts for details.

The setting of the network attribute ''ALWVRTAPPN'' doesn't matter.

A working Token Ring connection is also required. In its line description, the ''AUTOCRTCTL'' parameter should (temporarily) be set to ''*YES''. It is recommended that the associated ''AUTODLTCTL'' parameter be set to ''*NONE'' if <code>AUTOCRTCTL(*YES)</code> is to be retained.

This preparation saves the tedious and error-prone configuration of the OS/400 controller (*CTLD) and device (*DEVD) descriptions for communication with the gateway on the Mac side.

In addition, the ''IBM/Apple IBM Enterprise Networking Guide'' contains detailed configuration for configuring 3270 sessions to an AS/400 starting page 30 (PDF page 40).

== Gateway configuration ==
[[File:Cfg-snaps.gif|thumb|right|Overview of the filled configuration window]]
The configuration is created with the ''SNA•ps Config'' program and built layer by layer.

It is easily possible to configure several AS/400 peers in one configuration document. To do this, each machine must have its own definitions created for
* Lines,
* Partners,
* Remote 6.2 LUs,
* Modes.

Contrary, ''Local 6.2 LUs'' und ''Transaction Points'' apply to all configured peers.

If several AS/400’s are already internetworked via APPN, the gateway configuration can be made much easier. Just configure the AS/400 designated as APPN ''Network Node'' as partner connection. APPC sessions originating on the Macs are forwarded by the gateway to the (directly adjacent) Network Node AS/400. This one in turn forwards the LU sessions to the destination machines. 
Note that the ''Network Node'' machine needs to have adjacencies to the desired other machines for this to work. SNA•ps can only use connections being already configured.

=== Lines ===
[[File:Cfg-line.gif|thumb|right|Line configuration]]
First, the Line configuration needs to be created. The name can be chosen relatively freely.<ref>Only CAPS, may not start with a number, and may only contain these special chars: #$_</ref> 
Increasing the ''Maximum I-Field Length'' parameter increases the data throughput and thus the speed at which data is forwarded through the gateway. The highest accepted value is 4105 bytes. Use of the maximum value is recommended. The line description of the AS/400 — corresponding to the line configuration of SNA•ps — usually contains 16393 bytes. The actual value used is negotiated dynamically at session establishment time.

Leave the other settings at default values.

=== Partners ===
[[File:Cfg-peer.gif|thumb|right|Partner configuration]]
As long as the just created ''line'' is highlighted, the description for the actual network connection to the AS/400 can be defined in the ''partners'' field next to it. 
The following table shows parameters of the ''partner'' configuration and the related parameters on the AS/400:
{|class="wikitable"
!Partner setting
!Corresponding AS/400 setting
!Remark
|-
|Name
|<code>DSPNETA</code>, local control point name (LCLCPNAME)
|Naming restrictions as in the line configuration apply.
|-
|Link Address
|<code>DSPLIND</code>, local adapter address (ADPTADR)
| 
|-
|Partner XID
|<code>DSPLIND</code>, exchange identifier (EXCHID)
| 
|-
|Gateway XID
| 
|Generate yourself. Has to start with ''056'', and must be unique at least on both sides of the adjacency-link.<ref>This value is copied to the AS/400’s controller description at the connection’s first start by auto configuration.</ref><ref>XID exchanges stay local to directly adjacent hosts, thus XID duplicates should not matter network-wide.</ref>
|-
|Gateway Network Name
| 
|Generate yourself. You can probably use the name from the ''Sharing'' control panel. Naming restrictions as in the line configuration apply.
|-
|Gateway Network Qualifier
|<code>DSPNETA</code>, local network ID (LCLNETID)
| 
|}

Other necessary ''Characteristics'' settings are:
* Peer: Set to Node Type 2.1,
* SAP address, (remains at) 4.

=== Local 6.2 LUs ===
[[File:Cfg-loclu.gif|thumb|right|Local 6.2 LUs]]
{|class="wikitable"
!LU setting
!Corresponding AS/400 setting
!Remark
|-
|Name
| 
|Must be ''PASSTHRU''. Corresponds to the ''SNA•ps Access'' Control Panel setting on the SNA•ps clients.
|-
|''Network LU Name''
| 
|Desired name for the gateway on the APPN network. Naming restrictions as in the line configuration apply.
|-
|Network Qualifier
|<code>DSPNETA</code>, local network ID (LCLNETID)
| 
|}

=== Transaction points (TPs) ===
[[File:Cfg-tp.gif|thumb|right|Transaction Points]]
The ''Local 6.2 LU'' just defined must be highlighted so a new ''transaction point'' can be created.
{|class="wikitable"
!TP setting
!Corresponding AS/400 setting
!Remark
|-
|Name
| 
|Must be ''*'' (asterisk).
|-
|Network LU name
|<code>DSPNETA</code>, local control point name (LCLCPNAME)
| 
|-
|Network name
|<code>DSPNETA</code>, local network ID (LCLNETID)
| 
|}

Leave the other settings at default.

=== Remote 6.2 LUs ===
[[File:Cfg-remlu.gif|thumb|right|Remote 6.2 LUs]]
The ''partner'' created above must be highlighted in order to create an associated LU configuration.
{|class="wikitable"
!LU setting
!Corresponding AS/400 setting
!Remark
|-
|Name
|<code>DSPNETA</code>, local control point name (LCLCPNAME)
| 
|-
|Network LU name
|<code>DSPNETA</code>, local control point name (LCLCPNAME)
| 
|-
|Network Qualifier
|<code>DSPNETA</code>, local network ID (LCLNETID)
| 
|}

Leave the other settings at default.

If you have more than one AS/400 in an APPN network, just add the corresponding LU names and Network Qualifiers from the other AS/400’s in the same manner. This enables session forwarding by the ''Network Node'' AS/400 as described above.

=== Modes ===
[[File:Cfg-mode.gif|thumb|right|APLSNAPS mode description]]
The Remote 6.2 LU(s) created above must be highlighted in order to create an associated mode description.

Since there is no ''good enough'' mode description on the AS/400 by default, create a custom mode ''APLSNAPS'':
CRTMODD MODD(APLSNAPS) COS(#CONNECT) MAXSSN(32) MAXCNV(32) LCLCTLSSN(0) INPACING(7) OUTPACING(7) TEXT('For Apple SNA.ps')

Now, set the values of the fields on the right side in the ''Characteristics'' pane in the Window as follows:
{|class="wikitable"
!Mode setting
!Value
!Corresponding AS/400 setting
|-
|Maximum Sessions
|32
|Maximum sessions (MAXSSN)
|-
|Contention Winner
|32
|Maximum conversations (MAXCNV)
|-
|Prebound Sessions
|0
|Pre-established sessions (PREESTSSN)
|-
|Send Pacing
|7
|Inbound pacing value (INPACING)
|-
|Receive Pacing
|7
|Outbound pacing value (OUTPACING)
|-
|Maximum RU Upper
|4096
| 
|-
|Maximum RU Lower
|256
| 
|}

Leave the other settings at default.

'''Note:''' Modes aren’t shared. For each remote LU, you need to re-enter the values outlined above.

It may happen that the gateway refuses to start because it claims there isn’t not enough memory (on the MCP card). Recommended action is to lower ''Maximum Sessions'', and ''Contention Winner'' settings locally, and on the AS/400 with the <code>CHGMODD</code> command.

== Gateway Activation ==
After the gateway configuration has been saved, it is assigned to the existing physical connection using the ''SNA•ps Admin'' application. Launch it. The ''Network Gateway Status'' window appears. One line is displayed for each SNA capable card in the Mac, as shown in the second screen shot above.

Highlight the desired card’s entry, and choose ''Select configuration…'' from the ''Gateway'' menu. Use the dialog box to locate and select the configuration file you've created and saved before. 
In the same menu, select ''Change Settings …'' and
* probably assign a nicer AppleTalk name to the gateway, and
* in ''Characteristics'' tick all checkboxes except ''Initially Log Line Trace''.

The gateway can then be started in the Gateway menu with ''Start Gateway …''. A dialog window is shown with a summary. Click ''Start''.

<blockquote>'''Note:''' It has been shown that — at least with ''SNA•ps Gateway'' version 1.1 — trying out configuration settings with manual stop and start sometimes provokes the message that there is insufficient memory. This statement refers to the memory on the corresponding MCP card. Apparently, resources there are not reliably freed. After restarting the computer, the error message is gone.</blockquote>

Also in the ''Gateway'' menu, an overview of the available resources can now be displayed with ''Show Gateway …''. An example can be seen in the second screen shot above.

=== Screenshots ===
These screenshots show examples of all entities being displayed in short in the ''Show Gateway…'' window, in the second screen shot above.
<gallery mode="nolines">
File:Stat-line.gif
File:Stat-peer.gif
File:Stat-loclu.gif
File:Stat-tp.gif
File:Stat-remlu.gif
File:Stat-mode-snasvcmg.gif
File:Stat-mode-aplsnaps.gif
File:Stat-sess-snasvcmg.gif
File:Stat-sess-aplsnaps.gif
</gallery>

== Client configuration: SNA•ps 5250 ==
In the ''SNA•ps Access/5250'' control panel, switch to ''Virtual Controller'' in the ''Display Configuration''. The controller name is usually ''QPACTL01''; the default entry has way too many zeros. Close the control panel to save the changes.

[[File:Dft-connsel.gif|right|thumb|Dialog window to select a default session ]]
The minimal client configuration just requires the selection of the default connection in the ''Pref(erence)s'' menu. Alternatively, the desired session can be configured directly in the client: Menu ''Session'' → ''Connection …''. Both ways show a dialog window to select a gateway resource in the AppleTalk network.

Finally, the connection to the SNA gateway selected above is established by selecting ''Connect'' from the ''Session'' menu. After a few seconds, the familiar AS/400 sign-on screen should appear.

Other parameters can then also be set: Larger font for large monitors, alternative key assignments for small Mac keyboards: the numeric keypad is ideal here as a substitute for the lack of function keys, etc. The settings then can be saved in a connection document. When opening such a document, the session is established automatically.

All other settings can be made according to taste.

== Client configuration: SNA•ps Print ==
Before using this function, a printer on the AS/400 must be configured in the ''SNA•ps Access'' control panel.

In the ''Printer Configuration'' section of the Control Panel, click ''Printer Device List…'' and type in a valid AS/400 style print queue name. This name should '''not''' exist on the AS/400, it will be automatically created with the correct settings.

Close the control panel to save the settings. If you get an error message stating the control panel can't be opened, you probably have the ''SNA•ps 5250'' client running in the background. Close it, and try again.

After launching ''SNA•ps Print'' you will be asked for a file name for the newly to-be-created printer connection. Simply save this document with a meaningful name.

The minimal configuration just requires the selection of the default connection in the ''Pref(erence)s'' menu. Alternatively, the desired session can be configured directly in the client: Menu ''Session'' → ''Connection …''. Both ways show a dialog window to select a gateway resource in the AppleTalk network.

Finally, the connection to the previously selected SNA gateway is established in the ''Session'' menu by selecting ''Connect''. The AS/400 creates a printer device file (*DEVD) and a corresponding output queue (*OUTQ) which can then be used by applications on the system.

An IBM 3812 Model 1 printer in SCS mode is emulated.

Everything that is spooled to this new queue ends up in the print routine of ''SNA•ps Print''.

See the other menu items for the mostly self-explaining further functions of ''SNA•ps Print''.

== Pitfalls ==
* Neither SNA•ps 5250, nor SNA•ps print can be used on PowerPC machines when connecting via a ''SNA•ps gateway''. As soon as the connection is to be set, the client crashes with an ''illegal instruction'' error.<ref>This is the first and so far only (productivity) 68k program I’m aware of not running on PowerPC.</ref>
* Using the AppleTalk diagnostic tool ''Trawl'' on the gateway Mac itself somehow messes up the AppleTalk stack on it, so that the gateway no longer appears in the manager application. Only a reboot of the gateway computer fixes that error.

== External links ==
* Wikipedia:
** [https://en.wikipedia.org/wiki/IBM_Systems_Network_Architecture IBM Systems Network Architecture]
** [https://en.wikipedia.org/wiki/IBM_Advanced_Program-to-Program_Communication IBM Advanced Program-to-Program Communication]
** [https://en.wikipedia.org/wiki/IBM_Advanced_Peer-to-Peer_Networking IBM Advanced Peer-to-Peer Networking]
** [https://en.wikipedia.org/wiki/Synchronous_Data_Link_Control Synchronous Data Link Control]
** [https://en.wikipedia.org/wiki/A/ROSE Apple Real-time Operating System Environment]
** [https://en.wikipedia.org/wiki/Message_passing Message Passing]
** [https://en.wikipedia.org/wiki/AppleTalk AppleTalk]
** [https://en.wikipedia.org/wiki/LocalTalk LocalTalk]
* [http://www.mactech.com/articles/develop/issue_04/coprocessor.html Inside The Macintosh Coprocessor Platform And A/ROSE]
* [https://www.computerwoche.de/a/terminalemulation-bindet-apple-welt-an-as-400-mac-user-haben-direkten-zugriff-auf-as-400-daten,1128406 Terminalemulation bindet Apple-Welt an AS/400], Computerwoche 1993-06-11 (German)
* [https://www.ibm.com/support/knowledgecenter/en/SSEQ5Y_5.9.0/com.ibm.pcomm.doc/books/html/admin_guide19.htm Administrator's Guide and Reference, SNA Client/Server Concepts], IBM
* [https://www.ibm.com/support/knowledgecenter/zosbasics/com.ibm.zos.znetwork/znetwork_6.htm Introduction to networking on the mainframe], IBM
* [https://web.archive.org/web/20181229140138/http://docwiki.cisco.com/wiki/IBM_Systems_Network_Architecture_Protocols IBM Systems Network Architecture Protocols], Cisco Docwiki (aus dem Archiv)
* [https://bitsavers.org/pdf/ibm/sna/Z325-6027-0_IBM-Apple_Enterprise_Networking_Guide_for_SNA_Products_199110.pdf Z325-6027-00] IBM/Apple IBM Enterprise Networking Guide for SNA Products, IBM
* [https://www.ibm.com/common/ssi/cgi-bin/ssialias?infotype=DD&subtype=SM&htmlfid=897/ENUS5733-CSR 5733-CSR IBM AS/400 Client Series End User Products], IBM
* [https://www.buriedbits.org/macintosh-networking-pre-osx Macintosh networking (pre-OSX)], buriedbits.org

== Notes ==
<references />

[[Category: Software Configuration Guide]]
[[Category: System Administration]]

Main Page

2026-08-08T18:53:44Z

PoC: +S/3x

This Wiki is intended to help average computer users (probably you) who also are curious about '''AS/400''', '''iSeries''', or '''IBM i''' to get started with the system. The platform is in parts dramatically different from many you've probably learned about before. This makes it hard to understand the underlying concepts. Additionally, there's a certain amount of ''slang''. Without proper translation into terms we know, it's even more complicated to get going.

Fortunately, there's a wealth of online resources available in the web. Unfortunately, these are scattered around, sometimes providing insight to special topics while omitting basic information for helping novice users to just get started.

The intention of this information resource is trying to explain the platform in terms of, and comparison to, stuff you might be more familiar with.

Lately, this Wiki will also showcase information regarding other IBM midrange platforms, such as S/36 and S/38.

== Why? ==
The AS/400 is a huge area to explore. As you probably wouldn’t expect to learn ''everything Linux'' from reading three Wikipedia articles, the same is true for the AS/400 platform. This Wiki has a lot of content but maybe never enough. But it's slowly growing. Also, existing content is prone to being enhanced and corrected of errors. You may help with this by writing me to <[mailto:webhamster@pocnet.net webhamster@pocnet.net]> and submit correction requests, enhancement requests, or even ask for write access.

The basic motivation for this Wiki is: I had a hard time to learn the basics, and I want to make it easier for you to just get started.

Most content in this Wiki is based on my own experiences with an older 9401-150 machine, running OS/400 V4R5 with latest patches from the early 2000’s. When I describe different machines or OS releases, I‘ll indicate that in the respective text.

Please read '''[[The Naming of the System]]''' for my thoughts regarding the regularly fought battle about ''It’s not an AS/400 anymore!''.

=== Evolution ===
<blockquote>But why should you care for V4? The current version is V7.something!</blockquote>

Every OS does evolve over time. So does OS/400, or IBM i, as it’s called today. Windows Server 20something bears a certain resemblance to Windows 2000 (not counting the UI changes!). Much stuff you learned in the 2000’s era is outdated and never needed again in modern systems, though. Mac OS 9 from 2001 bears only a slight resemblance to today’s OS X (or ''macOS'' as it’s now called). Most conventional platforms don’t just evolve, they change, often in incompatible ways.

This is different with OS/400. Newer releases of OS/400 carry over ''almost'' all stuff you'd know from V4. Most knowledge you acquired with just V4 isn’t worthless with V7. V7 has '''additional''' capabilities to learn.

If you are interested in background information how and by whom the system was developed, see '''[[History]]'''.

== Getting started ==
If you are interested in getting to know (more) about AS/400 basics, you may read '''[[About Green Screens and mouse-clickable UIs]]''' as well as about '''[[Features that separate the AS/400 from common computer systems]]''' to get a first glance what makes this platform so unique. This might provide a better decision-making about if you want to continue exploring the AS/400 beyond theoretical statements.

Want to dive deep? You should decide if you want your own machine or if it’s sufficient to have remote access to a machine to start exploring as an ordinary user, without administrative rights. You may start with the latter and get your own machine at a later point in time, though.

* [http://www.rzkh.de ''Holger Scherer''] has been providing free access to an [http://pub400.com IBM i installation] hosted in his company’s bunker, for people to explore the system, learn and perhaps start programming.
* If you decide having your own machine is the way to go, I encourage you to start looking at internet auction sites and companies with IBM i expertise for a used box to eventually call [[Your own AS/400|your own]].

The ever growing '''[[UNIX-User's Cheater Table]]''' could probably be helpful in finding out a certain command when you know the command in UNIX, or Linux.

If you’re coming from the IBM mainframe world, you’ll be relieved that many concepts are borrowed from the predecessors of z/OS. If there’s demand, I’ll probably add an extra article for an overview of similarities and differences.

== A word on virtualization ==
Currently there is no known way to run OS/400 on (virtual) x86 platforms. OS/400 ''can'' be virtualized – on appropriate hardware, driven by IBM POWER CPUs. That is, some kind of IBM POWER based system. But if you have this hardware in the first place, virtualization is probably superfluous.

OS/400 in recent versions can host LPARs for Linux, AIX, and itself, so it’s quite possible to have a good deal of integration the other way 'round.<ref>POWER 8 is the first CPU with complete little endian support, which is required by most free and current Linux distros like Debian (ppc64el). For older machines you need to find an appropriately older distro version that still supports big endian (PPC64) CPUs. Currently, Debian PPC64 support is unofficial. See [https://wiki.debian.org/SupportedArchitectures SupportedArchitectures] in the Debian Wiki.</ref>

== Further Reading ==
This selection of initial reading may be not applicable to your particular situation, maybe because you’re not (yet) owning an AS/400 or your box came with OS/400 preinstalled.

* [[Getting started with the hardware]], and how to boot the system
* [[How to access your AS/400]]
* [[Basic Usage Instructions]]
* [[How to properly shut down your AS/400]]

A little more advanced topics:
* [[Installing OS/400]]
* [[Basic System Administration Tasks explained]]
* [[Getting Data in and out of your AS/400]]
* [[Basic Software Development]]

Regarding software development, it might be of interest to have a look at my [https://github.com/PoC-dev GitHub Projects Page].

=== Links to IBM documentation ===
In the beginning of 2023 I was forced by IBM UK to take offline my publicly available [https://ibmdocs.pocnet.net IBM documents collection]. No opportunity was given to challenge that decision. In addition, it proved to be impossible for me to find/identify a responsible person within IBM to overturn that decision.

Links in this Wiki thus point directly to the [https://www.ibm.com/resources/publications/searchInput IBM Publications Center]. If the list of results is empty, this means IBM doesn't publish the linked document any longer. Since I'm not allowed to publicly publish ''IBM copyrighted material'', you probably need to find the linked documents [https://web.archive.org/web/20220221081333/https://ibmdocs.pocnet.net/ elsewhere].

=== See also ===
* From the English Wikipedia:
** [[wikipedia:IBM_System_i|IBM System i]]
** [[wikipedia:IBM_i|IBM i]]

== Restrictions regarding this Wiki ==
This Wiki is ''read only'' for guest users because of frequent vandalism and spamming. Also, self-creating user accounts isn’t allowed for the very same reasons.

Volunteers are very welcome, especially for correcting my possibly numerous syntactic errors and misplaced commas. Feel free write an e-mail to <[mailto:webhamster@pocnet.net webhamster@pocnet.net]> and I’ll add an account for you.

I’m also happy with any feedback. Even if it’s only to say ''thank you''.

== Rules regarding this Wiki ==
Quality of the content comes before quantity. Also, to provide reasonable understandability and searchability for articles, please adhere to the following points:
* Keep a high quality of language,
** avoid spelling errors, slipshod procedure descriptions, and abstruse language.
* Name articles concise and distinctly (Wikis don’t provide a hierarchy),
** avoid repeating terms in several article names that are better used as a category name.
* Always add category-tags at end of articles. This permits automatic grouping of related articles and better retrieval if the search function doesn’t provide expected results.
* Add images sparsely and as additional reference only. Main explanation must be actual text, so
** automatic translation services can actually translate content,
** disabled persons can make better use of this Wiki.
* Don’t flood/plaster articles with full-size pictures. It strains the eyes to read!
* Adhere to Wikipedia Style when outlining articles:
** Begin articles with a sentence or two that roughly describes what the article is about, highlight keywords also appearing in the article name,
** Use separate sections for Weblink collections and footnotes at the very end of the article,
** Don’t use the Single-Equals sign for sections, this is already implied by the article heading.
* Be precise when mentioning actual products.

Please consult me before introducing new categories.

== Footnotes ==
<references />

[[Category: Musings]]

UNIX-User's Cheater Table

2026-08-07T12:48:22Z

PoC: Precise command

This table lists commands available in the ''CL-Environment'', the classical OS/400-Shell, so to say. These do '''not''' apply to ''QSH'' or ''PASE'', that are UNIX-like environments within OS/400.

{|class="wikitable"
!UNIX Command
!OS/400 Equivalent
!Remarks
|-
|colspan="3"|'''Files and File System'''
|-
|valign="top"|<code>cat</code>
|valign="top"|<code>cpyf</code>
|valign="top"|Since OS/400 has no concept of stdin/stdout, these functions of cat don't apply here.
|-
|valign="top"|<code>cd</code>
|valign="top"|<code>chgcurlib</code>
|valign="top"| 
|-
|valign="top"|<code>chmod</code>
|valign="top"|<code>chgaut</code>, <code>grtobjaut</code>, <code>rvkobjaut</code>
|valign="top"| 
|-
|valign="top"|<code>chown</code>, <code>chgrp</code>
|valign="top"|<code>chgobjown</code>, <code>chgobjpgp</code>
|valign="top"| 
|-
|valign="top"|<code>cp</code>
|valign="top"|<code>crtdupobj</code>
|valign="top"| 
|-
|valign="top"|<code>dump</code>, <code>tar c</code>
|valign="top"|<code>sav(lib|obj| )</code>
|valign="top"| 
|-
|valign="top"|<code>ls</code>
|valign="top"|<code>dspobjaut</code>, <code>wrklib</code>, <code>wrkobj</code>
|valign="top"|Shows a scrollable list of selected objects, helps in modifying access rights.
|-
|valign="top"|<code>mv</code>
|valign="top"|<code>rnmobj</code> <code>movobj</code>
|valign="top"| 
|-
|valign="top"|<code>restore</code>, <code>tar [x|t]</code>
|valign="top"|<code>rst(lib|obj| )</code>, <code>dspsavf</code>, <code>dsptap</code>
|valign="top"| 
|-
|valign="top"|<code>test -f</code>
|valign="top"|<code>chkobj</code> <code>chkifsobj</code>
|valign="top"| 
|-
|valign="top"|<code>vi</code>
|valign="top"|<code>strseu</code> for source physical files, <code>edtf</code> for stream files, <code>upddta</code> for database files.
|valign="top"|See [[Filesystems and Files on the AS/400]] for details. See [[IBM HTTP-Server for AS/400 Configuration]] for specialised command regarding web server config.
|-
|colspan="3"|'''Memory and Processes'''
|-
|valign="top"|<code>free</code>
|valign="top"|<code>wrkshrpool</code>
|valign="top"|This is for displaying the amount of built-in RAM.
|-
|valign="top"|<code>crontab -e</code> <code>at</code> (scheduler)
|valign="top"|<code>wrkjobscde</code> <code>sbmjob</code> <code>wrkjobq qbatch</code>
|valign="top"| 
|-
|valign="top"|<code>ps aux</code>, <code>ps -edf</code>, <code>top</code>
|valign="top"|<code>wrkactjob</code>, <code>wrksysact</code>
|valign="top"| 
|-
|colspan="3"|'''Disk and I/O'''
|-
|valign="top"|<code>df</code>
|valign="top"|<code>strsst</code>
|valign="top"|Access to precise disk space stats is available within ''system service tools'' only.
|-
|valign="top"|<code>fsck</code>
|valign="top"|<code>rclstg</code>
|valign="top"|System needs to be in restricted mode.
|-
|valign="top"|<code>iostat -x</code>
|valign="top"|<code>wrkdsksts</code>
|valign="top"| 
|-
|valign="top"|<code>vmstat</code>
|valign="top"|<code>dspsyssts</code>
|valign="top"|Choose view option ''3'' after pressing <code>F19</code>.
|-
|colspan="3"|'''Networking'''
|-
|valign="top"|<code>ping</code>, <code>aping</code>
|valign="top"|<code>ping</code>
|valign="top"|Surprise, command has same name! The latter is for SNA APPN.
|-
|valign="top"|<code>netstat</code>, <code>wrkappnsts</code>
|valign="top"|<code>netstat</code>
|valign="top"|Surprise, command has same name! The latter is for SNA APPN.
|-
|colspan="3"|'''Development'''
|-
|valign="top"|<code>cc</code>
|valign="top"|<code>crtcmod</code>
|valign="top"|Create Object File from C-Source.
|-
|valign="top"|<code>ld</code>
|valign="top"|<code>crtpgm</code>, <code>crtsrvpgm</code>
|valign="top"|Create runnable Program from Object File(s), create Service Program ("Shared Library") from Object File(s).
|-
|valign="top"|<code>make</code>
|valign="top"| 
|valign="top"|There is a crude port of ''make'' in the QUSRTOOLS library called [[Setting up TMKMAKE|TMKMAKE]]. See ''QUSRTOOLS/QATTINFO.TMKINFO'' for details.<ref>See also [https://www.mcpressonline.com/programming-other/general/programming-with-make-on-the-as400-part-i Programming with Make on the AS/400, Part I], and [https://www.mcpressonline.com/programming-other/general/programming-with-make-on-the-as400-part-2 Programming with Make on the AS/400, Part 2] on McPress Online.</ref>
|-
|valign="top"|<code>configure</code>
|valign="top"| 
|valign="top"|No equivalent to GNU autoconf. Possible workaround: Manually tailored, static, universal ''config.h'' for each OS-Release (Compiler Version) based on existing documentation and/or manual tests.
|-
|valign="top"|<code>diff</code>
|valign="top"|<code>cmppfm</code>
|valign="top"| 
|-
|valign="top"|<code>patch</code>
|valign="top"|<code>mrgsrc</code>
|valign="top"| 
|-
|colspan="3"|'''Other Topics'''
|-
|valign="top"|<code>lpq</code>
|valign="top"|<code>wrkoutq</code>
|valign="top"|Displays all configured printer queues and count of entries.
|-
|valign="top"|<code>mailx</code>
|valign="top"|<code>dspmsg</code>, <code>snddst</code>
|valign="top"|Cron and at send mail if there was output. OS/400 sends ''messages'' and generates printer output (spooled file). Sending (SMTP) mail from the command line utilises a completely different facility.
|-
|valign="top"|<code>mt</code>
|valign="top"|<code>dsptap</code>, <code>chktap</code>
|valign="top"| 
|-
|valign="top"|<code>mysql</code>, <code>isql</code>
|valign="top"|<code>strsql</code>
|valign="top"|Not limited to ''mysql'', but more like a placeholder for any command line client accessing a database for entering SQL queries directly.
|-
|valign="top"|<code>whoami</code>
|valign="top"|<code>dspjob</code>
|valign="top"| 
|}

The table will be expanded over time.

== See also ==
* [[Basic Commands]]

== Footnotes ==
<references/>

[[Category: Basic Knowledge‏]]

Post-Install Optimizations

2026-08-05T23:58:16Z

PoC: /* Change Program Defaults */ Secondary Language

OS/400 provides a lot of default values for variables (affecting the run-time environment) and program options. Some of these make sense, some of them are kept consistent with earlier versions of the OS because of compatibility reasons by IBM.

Some of these recommendations might not be appropriate for you by various reasons. Don't apply blindly. Know what you do, use the online help to retrieve background information on the topic in question.

The findings below are based on V4R5 with annotated exceptions for newer releases.

== Housekeeping ==
These are settings and scheduled jobs to keep your system uncluttered.

=== Change unneeded programs to not run ===
We most likely don't need to run ''lpd'' and ''smtpd'' to run per default.
CHGLPDA AUTOSTART(*NO)
CHGSMTPA AUTOSTART(*NO)

You can easily check all settings at once by using <code>STRDFU OPTION(5)</code> on the file ''QUSRSYS/QATOCSTART''. These are not needed in general. Depending on OS version, not all entries may be available.
* *DIRSRV
* *NETSVR
* *SLP

=== Change uninstalled programs to not run ===
If you did not install the Ultimedia package, you can remove the pre started job from the QSYSWRK subsystem description to make it not generate an error message at IPL time.
RMVPJE SBSD(QSYSWRK) PGM(QUMEDIA/QUMBPJTC)

If you did not install the Directory Services package (aka LDAP), you can remove the auto started jobs from the QSYSWRK subsystem description to make them not generate an error message at IPL time.
RMVAJE SBSD(QSYSWRK) JOB(QGLDPUBA)
RMVAJE SBSD(QSYSWRK) JOB(QGLDPUBE)

Both is valid and tested for V4R5. Note that newer releases moved the background jobs to the base OS so there is no error message when starting them. I have not tested if they're required to run, though.

If you did not install the performance tools, you don't need trying to start the performance data collector:
RMVAJE SBSD(QCTL) JOB(QPFRCOL)

I can't remember if the latter is valid for V4R5. It's valid for V3R2, though.

=== Cleanup unneeded stuff ===
These objects come by default at OS install time, are not needed to my knowledge, and thus can be safely deleted:
DLTOUTQ OUTQ(QDKT)
DLTOUTQ OUTQ(QPFROUTQ)
DLTOUTQ OUTQ(QPRINTS)
DLTF FILE(QPRINTS)
DLTOUTQ OUTQ(QPRINT2)
DLTF FILE(QPRINT2)
DLTOUTQ OUTQ(QTPPPOUTQ)
DLTDEVD DEVD(QESPAP)
DLTDEVD DEVD(QIADSP)
DLTDEVD DEVD(QIAPRT)
DLTDEVD DEVD(QQAHOST)
DLTDEVD DEVD(QTIDA)
DLTDEVD DEVD(QTIDA2)
DLTCTLD CTLD(QESCTL)
DLTCTLD CTLD(QTICTL)
DLTLIND LIND(QESLINE)
DLTLIND LIND(QTILINE)

== System Values ==
System values are like environment variables as known from common operating systems. They influence system operation. I recommend the following changes.

=== System Control ===
* Change work environment to separate subsystems for different kind of jobs. This also makes it easy to introduce your own subsystems.
CHGSYSVAL SYSVAL(QCTLSBSD) VALUE('QCTL QSYS')
* Set automatic DST adjustment, and UTC offset. This value is valid for Central Europe (Berlin, Paris, …) '''Note!''' This variable is not available in V4R5. See [[#Weblinks|Weblinks]] below.
CHGSYSVAL SYSVAL(QTIMZON) VALUE('QP0100CET2')
* Adjust time to automatically end disconnected interactive jobs (sessions) to one day.
CHGSYSVAL SYSVAL(QDSCJOBITV) VALUE('1440')

=== (Memory) Allocation ===
* Adjust automatic performance values only at runtime, not at IPL.<ref>If you change the amount of memory for the machine, temporarily adjust the value to '2', make the memory change and then change the value back to '3' — no further IPL needed.</ref> This allows the system to automatically adjust memory allocations and activity levels to minimize paging (disk I/O).
CHGSYSVAL SYSVAL(QPFRADJ) VALUE('3')
* Allow memory pools to self adjust the paging block size depending on jobs running. This is called ''Expert Cache''. You can adjust the maximum active jobs per pool in the <code>WRKSHRPOOL</code> display.<ref>Press <code>F21</code> to switch to view 2 or 3 to have adjustment possibilities.</ref>
CHGSHRPOOL POOL(*BASE) PAGING(*CALC)
CHGSHRPOOL POOL(*INTERACT) PAGING(*CALC)
CHGSHRPOOL POOL(*SPOOL) PAGING(*CALC)
* Reservations for job related data structures at IPL time. See <code>DSPSYSSTS</code> and set to slightly more than the ''Jobs in System'' value to be seen there when the system is working "normal".<ref>Press <code>F21</code> to switch to view 2 or 3 to see the overall job count.</ref>
CHGSYSVAL SYSVAL(QTOTJOB) VALUE(100)
* Reservations for job related data structures at IPL time. See <code>WRKACTJOB</code> and set to slightly more than the ''Active Jobs'' value to be seen there when the system is working "normal".
CHGSYSVAL SYSVAL(QACTJOB) VALUE(95)
* Maximize TCP buffers for maximum performance, especially on faster links.
CHGTCPA TCPRCVBUF(8388608) TCPSNDBUF(8388608)
* Make sure, database tasks can use system resources as needed.
CHGSYSVAL SYSVAL(QQRYDEGREE) VALUE(*OPTIMIZE)
* When interactive jobs require more CPU time than being allowed by default (2 seconds),<ref>This is set in *CLS objects.</ref> to finish a block of processing, allow that memory to be taken from the *BASE pool. Advantage: The QINTER subsystem pool will not be subject to auto adjustment because of jobs which are supposed to run in batch.
CHGSYSVAL SYSVAL(QTSEPOOL) VALUE(*BASE)

=== Message-and-Logging ===
* Allow immediate deletion of problem reports.
CHGSYSVAL SYSVAL(QPRBHLDITV) VALUE(0)
* Do not log software errors. We can't do much about these anyway, seen from a hobbyist viewpoint.
CHGSYSVAL SYSVAL(QSFWERRLOG) VALUE(*NOLOG)
* Maximize Central Syslog (viewable with <code>DSPLOG</code> size to lessen rotation frequency. Depending on OS version only ''VALUE(32767)'' may be valid.
CHGSYSVAL SYSVAL(QHSTLOGSIZ) VALUE(*DAILY)
* Raise allowed unsuccessful sign on tries before taking action.
CHGSYSVAL SYSVAL(QMAXSIGN) VALUE('15')
* Minimize logging for sessions disconnected beause of device errors.
CHGSYSVAL SYSVAL(QDEVRCYACN) VALUE(*ENDJOBNOLIST)

=== Security System Values ===
* Unrestrict automatic creation of system objects triggered by external (network) requests.
CHGSYSVAL SYSVAL(QAUTOVRT) VALUE(*NOMAX)
* Allow restore with all security relevant flags.
CHGSYSVAL SYSVAL(QALWOBJRST) VALUE(*ALL)
* For TCP connections to work, we need encrypted passwords.
CHGDDMTCPA PWDRQD(*ENCRYPTED)
* Allow ''QSYSOPR'' signon to all devices.
CHGSYSVAL SYSVAL(QLMTSECOFR) VALUE('0')
* Raise maximum password length to maximum value.<ref>In newer OS versions, an additional variable ''QPWDLVL'' allows even longer passwords.</ref>
CHGSYSVAL SYSVAL(QPWDMAXLEN) VALUE(10)
* Raise minimum passsword length for security reasons.
CHGSYSVAL SYSVAL(QPWDMINLEN) VALUE(8)

=== Misc ===
* PTF install shall be done on unattended IPL time, and don't try to report problems to IBM directly.<ref>Needs prior setup for ''Electronic Customer Support''.</ref>
CHGSRVA PTFINSTYP(*DLYALL) RPTPRBAUTO(*NO)
* Provide European style formatting.
CHGSYSVAL SYSVAL(QCURSYM) VALUE('€')
CHGSYSVAL SYSVAL(QDECFMT) VALUE('J')
CHGSYSVAL SYSVAL(QSRTSEQ) VALUE(*LANGIDUNQ)<ref>This value isn't available with V4R5. You can use ''*LANGIDSHR'' there.</ref>
CHGSYSVAL SYSVAL(QDATFMT) VALUE('DMY')<ref>Default value for 2924 (US English) is MDY.</ref>
* Allow background compiling in PDM as ordinary user, and submitting batch jobs in general.
GRTOBJAUT OBJ(QGPL/QBATCH) OBJTYPE(*JOBD) USER(*PUBLIC) AUT(*USE)
* Tweaking automatic cleanup (like ''logrotate'').
CHGCLNUP ALWCLNUP(*YES) STRTIME('02:22:22') USRMSG(7) SYSMSG(3) SYSPRT(7) SYSLOG(14) CALITM(*KEEP)
* Change general SNA networking attributes. This is one '''long''' line. Take care to get it completely.
CHGNETA JOBACN(*SEARCH) VRTAUTODEV(254) MDMCNTRYID(DE)

=== Charset Conversion ===
In addition, OS/400 has a default value of 65535 for <code>QCCSID</code>. It should be set to a value being dependent on the installed language, to enable automatic translation of data on disk to the display device, and back. For Germany, the correct value is 273, and for US, it's 37. A good hint is to check your 5250 emulator program for possible values.

== IPL Customization ==
With this procedure, the current startup program for the OS can be retrieved for easy customization.
RTVCLSRC PGM(QSTRUP) SRCFILE(QCLSRC)
WRKMBRPDM FILE(QCLSRC) MBR(QSTRUP) MBRTYPE(CLP)
CRTCLPGM PGM(QGPL/QSTRUP)

To activate your changes, run <code>WRKSYSVAL SYSVAL(QSTRUPPGM)</code> and change the values to reflect the new program object in QGPL. '''Note''': On a used system's install, the previous owner might have already done a customized QSTRUP. See <code>DSPSYSVAL QSTRUPPGM</code> which one is the currently set startup program before accidentally overwriting!

Notable use cases for changing <code>QSTRUP</code> would be to make SNA Distribution Services, and TCP/IP (on older releases than V4R5) start at IPL time.

New entries must be located after the ''IF COND'' statement and ''DONE:'' label. Always put a ''MONMSG MSGID(CPF0000)'' after each statement. Failing to do so will not ignore any errors but make the IPL script terminate abnormally in case of an error and possibly leave you with an inaccessible system.

Examples:
* Start TCP/IP:
QSYS/STRTCP
MONMSG MSGID(CPF0000)
<blockquote>'''Note:''' TCP/IP on V4R5 and later is by IBM provided default automatically started with an appropriate autostart entry <code>struptcpip</code> in the <code>qsyswrk</code> subsystem description. No action is necessary in the startup CL!</blockquote>

* Start SNADS:
QSYS/STRSBS SBSD(QSNADS)
MONMSG MSGID(CPF0000)

== Change Program Defaults ==
This establishes different default behavior of some programs which makes life somewhat easier.<ref>Some people highly oppose against changing default values because the default values have been provided for a reason. But then, the <code>CHGCMDDFT</code> also has been provided for a reason.</ref> At least noting down the changed programs and their former values is recommended, for example in <code>QGPL/QTXTSRC.CMDDFT</code>.
<blockquote>'''Note:''' CL applications might run a command with the changed default values, in turn combining (new) defaults and submitted parameters into an invalid combination of parameters which might lead to run-time errors. As far as I'm aware, my proposed changes are compatible with such situations.</blockquote>

* File creation and change defaults:
** Enforce immediate return to program error handling instead of make programs seem to hang (<code>wait…</code>),
** Enforce reusing deleted record space,<ref>If there is no access path defined, sequentially read records are no longer guaranteed to *be in timely order (FIFO)!</ref>
** Remove sizing restrictions,<ref>A runaway process filling the disks to 100 % is not stopped prior!</ref>
** Use a smaller access path size for probably increased performance,
** Allow automatic LF rebuild when running <code>chgpf</code>.
CHGCMDDFT CMD(CRTPF) NEWDFT('SIZE(*NOMAX *N *N) WAITFILE(*IMMED) WAITRCD(*IMMED) REUSEDLT(*YES)')
CHGCMDDFT CMD(CRTSRCPF) NEWDFT('SIZE(*NOMAX *N *N) ACCPTHSIZ(*MAX4GB)')
CHGCMDDFT CMD(CHGPF) NEWDFT('DLTDEPLF(*YES) SIZE(*NOMAX *N *N) WAITFILE(*IMMED) WAITRCD(*IMMED) REUSEDLT(*YES)')
CHGCMDDFT CMD(CRTLF) NEWDFT('WAITFILE(*IMMED) WAITRCD(*IMMED) ACCPTHSIZ(*MAX4GB)')
CHGCMDDFT CMD(CHGLF) NEWDFT('WAITFILE(*IMMED) WAITRCD(*IMMED) ACCPTHSIZ(*MAX4GB)')
* Menus usually go into the library with the application's other objects. Change current library to there, so applications can find their objects.<ref>It might be beneficial to individually use <code>CURLIB(*NOCHG)</code> for higher level menu objects being put into libraries which are part of the default library search list (''*LIBL'') — such as ''QGPL'' — to not needlessly change the default library in a for some users unexpected way.</ref>
CHGCMDDFT CMD(CRTMNU) NEWDFT('CURLIB(*MNULIB)')
* No unnecessary wait for power down. <code>CONFIRM(*NO)</code> can be added for newer releases to suppress prompting.
CHGCMDDFT CMD(PWRDWNSYS) NEWDFT('OPTION(*IMMED) ENDSBSOPT(*NOJOBLOG)')
* Don't waste time displaying a not so very much interesting screen prior to connection.
CHGCMDDFT CMD(STRPASTHR) NEWDFT('PASTHRSCN(*NO)')

Be aware that reinstalls, or applying PTFs can overwrite command objects and thus their changed default values. Also note, hat installing a secondary language on a system also installs a separate set of <code>*cmd</code> objects for that language. You may want to apply the defaults with qualified object names to these, too.

== Regular Cleanup jobs ==
See job comment TEXT for details. These are '''long''' lines. Take care to get it completely.
ADDJOBSCDE JOB(PRGPRB) CMD(DLTPRB STATUS(*CLOSED)) FRQ(*WEEKLY) SCDDATE(*NONE) SCDDAY(*ALL) SCDTIME('13:22:00') MSGQ(*LIBL/QSYSOPR) TEXT('Purge closed and deletable problem entries')
ADDJOBSCDE JOB(RCLTMPSTG) CMD(RCLTMPSTG DAYS(30)) FRQ(*MONTHLY) SCDDATE(*MONTHSTR) SCDDAY(*NONE) SCDTIME('13:24:00') MSGQ(*LIBL/QSYSOPR) TEXT('Reclaim temporary storage')
ADDJOBSCDE JOB(RTVDSKINF) CMD(RTVDSKINF) FRQ(*MONTHLY) SCDDATE(*MONTHSTR) SCDDAY(*NONE) SCDTIME('13:34:00') MSGQ(*LIBL/QSYSOPR) TEXT('Retrieve disk space stats')
ADDJOBSCDE JOB(QPGMRCLR) CMD(CLRMSGQ MSGQ(QPGMR) CLEAR(*KEEPUNANS)) FRQ(*WEEKLY) SCDDATE(*NONE) SCDDAY(*ALL) SCDTIME('07:07:07') RCYACN(*NOSBM) MSGQ(*NONE) TEXT('Delete uninteresting messages')

== Re-Enable InfoSeeker ==
Only necessary for newer V4R4 and newer. If the command isn't known, don't bother: Then your release is so new that it's gone entirely.

See also: [[Reviving InfoSeeker]]

CRTDTAARA DTAARA(QUSRSYS/QBMGINFSKR) TYPE(*CHAR) LEN(8)<ref>Works in V4R5. The <code>STRINFSKR</code> command is not included anymore in IBM i 7.1, and probably earlier releases.</ref>

== Additional Steps tested with V7R2 ==
After trying to enter SST, one gets the message that the password has expired. But the password cannot be changed. Re-IPL '''in manual mode''', do not IPL but enter DST, and change password as directed.

* Choose ''5. Work with DST environment'' and ''3. Service tools user IDs''.
** Disable the "backdoor" profile ''11111111'',
** ''Change password'' for ''QSECOFR'', ''Set password to expired'' to ''2=No''.
* Press F12 and choose ''6. Service tools security data''.
** Enter 0 into the field ''8. Password expiration interval in days'', 8 into the ''Selection'' field, and press return.
** Enter a high number (like 12) into the field ''9. Maximum sign-on attempts allowed'', 9 into the ''Selection'' field, and press return.
** Enter 0 into the field ''10. Duplicate password control'', 10 into the ''Selection'' field, and press return.

Now exit DST.

You may choose to enter SST, enter 7 for ''Work with system security'', and set ''Allow a service tools user ID with a default and expired password to change its own password'' to ''1=Yes''. Since we changed password expiry to ''never'', this step is entirely optional.

== See also ==
* [[Change Command Defaults for File-Commands]]
* [[How to properly shut down your AS/400]]

== Weblinks ==
* [https://archive.midrange.com/midrange-l/199912/msg01738.html STRINFSKR], Midrange Mailing-List
* [https://github.com/PoC-dev/as400-autodst as400-autodst], GitHub

== Footnotes ==
<references />

[[Category: System Administration]]