Try-AS/400 - User contributions [en]

Apple SNA•ps

2023-05-14T19:40:35Z

Mlc:

[[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 Software. 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 [https://en.wikipedia.org/wiki/IBM_Systems_Network_Architecture#Logical_Unit_.28LU.29 LU]-sessions for version 1.1
** 10, 40, or 70 LU-sessions 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. 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 [https://en.wikipedia.org/wiki/IBM_Systems_Network_Architecture#Physical_Unit_.28PU.29 SNA PUs]/LUs or [https://en.wikipedia.org/wiki/IBM_Advanced_Peer-to-Peer_Networking APPN]/[https://en.wikipedia.org/wiki/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 [https://en.wikipedia.org/wiki/IBM_3270 3270], and [https://en.wikipedia.org/wiki/IBM_5250 5250]). These allow Macs that are connected to the [https://en.wikipedia.org/wiki/AppleTalk AppleTalk] network (e. g. via [https://en.wikipedia.org/wiki/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 [https://en.wikipedia.org/wiki/Chooser_(Mac_OS) Chooser], or saved as text in a file. 
This was a way of making the Apple [https://en.wikipedia.org/wiki/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 [https://en.wikipedia.org/wiki/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 AS/400, and additional software for OS/400 to implement the AppleTalk protocol stack on the AS/400 as well. The implementation on the AS/400 corresponded to the SNA•ps gateway, so that no Mac was required as a gateway: the necessary software ran only on the AS/400.

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

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

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

== Notes ==
<references />

== 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

[[Category: Software Configuration Guide]]
[[Category: System Administration]]

Ordinary Harddisks on the AS/400

2023-02-11T21:29:38Z

Mlc: /* AS/400-Disk in a Linux box */

The following article is an excerpt from the [https://kb.pocnet.net/wiki/Standard-Festplatten_an_der_AS/400 PoCnet-Wiki], translated to english language.

Ordinary SCSI-Disks cannot be used with the AS/400. They don’t even show up in DST<ref>Roughly what’s known on PC platforms as ''BIOS''.</ref>.

== AS/400 disk in a Linux box ==
This is a shortened sample output from a Linux box’ kernel log:
scsi 5:0:3:0: Direct-Access IBMAS400 DFHSS4W 5959 PQ: 0 ANSI: 2
scsi5:A:3:0: Tagged Queuing enabled. Depth 8
scsi target5:0:3: Beginning Domain Validation
scsi target5:0:3: wide asynchronous
scsi target5:0:3: FAST-10 WIDE SCSI 20.0 MB/s ST (100 ns, offset 8)
sd 5:0:3:0: [sdb] Unsupported sector size 522.
sd 5:0:3:0: [sdb] 0 512-byte logical blocks: (0 B/0 B)
sd 5:0:3:0: [sdb] 522-byte physical blocks
sd 5:0:3:0: [sdb] Write Protect is off
sd 5:0:3:0: [sdb] Mode Sense: b3 00 10 08
sd 5:0:3:0: [sdb] Write cache: disabled, read cache: enabled, supports DPO and FUA
sd 5:0:3:0: [sdb] Unsupported sector size 522.
sd 5:0:3:0: [sdb] Attached SCSI disk
sd 5:0:3:0: [sdb] Unsupported sector size 522.

As you can see, these disks utilize 522 bytes per sector instead of 512 as the rest of the world does. There is a command line utility called [http://micha.freeshell.org/scsi/ setblocksize] by Michael Baeuerle. It provides the possibility to reformat disks (supporting changeable block sizes) with different sector sizes.

== Ordinary harddisks on the AS/400 ==
Unfortunately, it’s not sufficient to just reformat disks to the proper sector size. It may even happen that disks with a vendor ID different from ''IBM'' won’t show up in DST regardless of the sector size.

Newer research suggests that AS/400 approved disks have a custom IDENTITY response, additional VPD<ref>Vital Product Data.</ref> tables, and two additional, vendor defined SCSI commands: SKIP READ and SKIP WRITE. It is not clear which combination of the differences are mandatory for getting a disk to run on an AS/400.

I tried to get an IBM DCHS 9 GB 3.5" disk to work on a 9401-150, without success. The disk shows up in DST and when trying to start a surface test, the following error message appears:
Error Report

Note: Some action will need to be taken for the errors listed
below. Please select an error to display the detailed
information for it. The detailed information will indicate
what action may need to be taken to correct the error.

Type option, press Enter.
5=Display Detailed Report

OPT Error
_ Disk units without the system support
Entering 5 (for continue), the next message reads:
Disk Units without the System Support

The following disk units do not have the correct system
support. The function you requested can not be completed
until the correct system support is applied. Call for service.

Serial Resource
ASP Unit Number Type Model Name Status
[Output of details for the disk in question]
Trying to format the disk within DST yields the following error:
Combined Error/Attention Report

Note: Some action may need to be taken for the errors and/or
problems listed below. Please select an error or problem to
display the detailed information for it. The detailed
information will indicate what action may need to be taken
to correct the error or the problem.

Type option, press Enter.
5=Display Detailed Report

OPT Error
_ Disk unit I/O failure, check reference code
Entering 5 (for continue), the next message reads:
I/O Error

The system encountered an error while it was attempting to
read or write to a disk unit.

Contact your service representative with the following
information:

--Reference Codes--
Serial Resource I/O
Number Type Model Name Processor Device
The reference codes are 0. Not helpful.

== Background Information ==
Disks for AS/400 systems come in two flavours, 520 bytes and 522 bytes per sector. The 520 bytes format is considered outdated by IBM. 520 bytes formatted disks were used with old CISC machines only.<ref>Exception: AS/400 5xx models with disks attached on the internal Multi-Function I/O Processor.</ref>

The 520 bytes format is composed of:
* 8 bytes header,
* 512 bytes payload

The 522 bytes format composed of:
* 8 bytes header,
* 512 bytes payload,
* 2 bytes trailer

The 522 bytes format is mandatory for:
* RAID,
* Compression

Metadata for these (and probably more) features are kept in these trailer bytes.

The header consists of metadata for the block’s payload. Example: Protection (RAID1, RAID5 or similar). Also it contains flags if the block contains valid data, an individual block address (probably needed for the famous single level storage addressing scheme), and more. Metatada is exclusively utilized by the I/O processor. The OS itself handles 512 bytes per sector data as known from other systems.

Header and trailer will be written while formatting a drive with the accompanying AS/400 tool (DST).

== Alternative Solutions ==
A UK based company offers an adapter board that makes it possible to use standard compact flash media instead of spinning disks. It seems that this solution has never been tested in the field. I got a product sample for testing but it fails to be recognized by the system: This adapter also works with 512 Bytes per sector and as such won’t be recognized by the system.

The adapter also provides emulation of a tape drive. This works like a charm.

== Weblinks ==
* [http://pissedoffadmins.com/general/unsupported-sector-size-520.html Unsupported sector size 520] at PissedOffAdmins
* [http://www.ndwiki.org/wiki/User:Tingo/setblocksize Setblocksize] at Norsk Data Wiki
* [http://www.redbooks.ibm.com/redbooks/pdfs/sg245693.pdf AS/400 Disk Storage Topics and Tools], IBM Redbook
* [http://www-304.ibm.com/partnerworld/gsd/solutiondetails.do?solution=51352&expand=true&lc=en Flash Disk SSD/IBM] in IBM Global Solutions Directory
** [http://www.peripheral-vision.com/products/scsi-to-compact-flash/ SCSICFDISK - SCSI to Compact Flash Disk] from Peripheral Vision
* [http://friedkiwi.github.io/scsi2sd/ SCSI2SD/400]
* [http://qseco.fr/research/demystifying-as400-dasd/ Demystifying AS/400 DASD]
* [http://ps-2.kev009.com/rs6000/manuals/SAN/ESS/2105_Model_ExxFxx/ESS_SCSI_Command_Reference_ExxFxx_SC26-7297-01.PDF IBM SCSI Command Reference,] 2105 Models E10, E20, F10, and F20

== Footnotes ==
<references />

[[Category: Hardware Configuration Guide]]

Ordinary Harddisks on the AS/400

2023-02-11T21:29:29Z

Mlc: /* AS/400-Disk in a Linux box */

The following article is an excerpt from the [https://kb.pocnet.net/wiki/Standard-Festplatten_an_der_AS/400 PoCnet-Wiki], translated to english language.

Ordinary SCSI-Disks cannot be used with the AS/400. They don’t even show up in DST<ref>Roughly what’s known on PC platforms as ''BIOS''.</ref>.

== AS/400-Disk in a Linux box ==
This is a shortened sample output from a Linux box’ kernel log:
scsi 5:0:3:0: Direct-Access IBMAS400 DFHSS4W 5959 PQ: 0 ANSI: 2
scsi5:A:3:0: Tagged Queuing enabled. Depth 8
scsi target5:0:3: Beginning Domain Validation
scsi target5:0:3: wide asynchronous
scsi target5:0:3: FAST-10 WIDE SCSI 20.0 MB/s ST (100 ns, offset 8)
sd 5:0:3:0: [sdb] Unsupported sector size 522.
sd 5:0:3:0: [sdb] 0 512-byte logical blocks: (0 B/0 B)
sd 5:0:3:0: [sdb] 522-byte physical blocks
sd 5:0:3:0: [sdb] Write Protect is off
sd 5:0:3:0: [sdb] Mode Sense: b3 00 10 08
sd 5:0:3:0: [sdb] Write cache: disabled, read cache: enabled, supports DPO and FUA
sd 5:0:3:0: [sdb] Unsupported sector size 522.
sd 5:0:3:0: [sdb] Attached SCSI disk
sd 5:0:3:0: [sdb] Unsupported sector size 522.

As you can see, these disks utilize 522 bytes per sector instead of 512 as the rest of the world does. There is a command line utility called [http://micha.freeshell.org/scsi/ setblocksize] by Michael Baeuerle. It provides the possibility to reformat disks (supporting changeable block sizes) with different sector sizes.

== Ordinary harddisks on the AS/400 ==
Unfortunately, it’s not sufficient to just reformat disks to the proper sector size. It may even happen that disks with a vendor ID different from ''IBM'' won’t show up in DST regardless of the sector size.

Newer research suggests that AS/400 approved disks have a custom IDENTITY response, additional VPD<ref>Vital Product Data.</ref> tables, and two additional, vendor defined SCSI commands: SKIP READ and SKIP WRITE. It is not clear which combination of the differences are mandatory for getting a disk to run on an AS/400.

I tried to get an IBM DCHS 9 GB 3.5" disk to work on a 9401-150, without success. The disk shows up in DST and when trying to start a surface test, the following error message appears:
Error Report

Note: Some action will need to be taken for the errors listed
below. Please select an error to display the detailed
information for it. The detailed information will indicate
what action may need to be taken to correct the error.

Type option, press Enter.
5=Display Detailed Report

OPT Error
_ Disk units without the system support
Entering 5 (for continue), the next message reads:
Disk Units without the System Support

The following disk units do not have the correct system
support. The function you requested can not be completed
until the correct system support is applied. Call for service.

Serial Resource
ASP Unit Number Type Model Name Status
[Output of details for the disk in question]
Trying to format the disk within DST yields the following error:
Combined Error/Attention Report

Note: Some action may need to be taken for the errors and/or
problems listed below. Please select an error or problem to
display the detailed information for it. The detailed
information will indicate what action may need to be taken
to correct the error or the problem.

Type option, press Enter.
5=Display Detailed Report

OPT Error
_ Disk unit I/O failure, check reference code
Entering 5 (for continue), the next message reads:
I/O Error

The system encountered an error while it was attempting to
read or write to a disk unit.

Contact your service representative with the following
information:

--Reference Codes--
Serial Resource I/O
Number Type Model Name Processor Device
The reference codes are 0. Not helpful.

== Background Information ==
Disks for AS/400 systems come in two flavours, 520 bytes and 522 bytes per sector. The 520 bytes format is considered outdated by IBM. 520 bytes formatted disks were used with old CISC machines only.<ref>Exception: AS/400 5xx models with disks attached on the internal Multi-Function I/O Processor.</ref>

The 520 bytes format is composed of:
* 8 bytes header,
* 512 bytes payload

The 522 bytes format composed of:
* 8 bytes header,
* 512 bytes payload,
* 2 bytes trailer

The 522 bytes format is mandatory for:
* RAID,
* Compression

Metadata for these (and probably more) features are kept in these trailer bytes.

The header consists of metadata for the block’s payload. Example: Protection (RAID1, RAID5 or similar). Also it contains flags if the block contains valid data, an individual block address (probably needed for the famous single level storage addressing scheme), and more. Metatada is exclusively utilized by the I/O processor. The OS itself handles 512 bytes per sector data as known from other systems.

Header and trailer will be written while formatting a drive with the accompanying AS/400 tool (DST).

== Alternative Solutions ==
A UK based company offers an adapter board that makes it possible to use standard compact flash media instead of spinning disks. It seems that this solution has never been tested in the field. I got a product sample for testing but it fails to be recognized by the system: This adapter also works with 512 Bytes per sector and as such won’t be recognized by the system.

The adapter also provides emulation of a tape drive. This works like a charm.

== Weblinks ==
* [http://pissedoffadmins.com/general/unsupported-sector-size-520.html Unsupported sector size 520] at PissedOffAdmins
* [http://www.ndwiki.org/wiki/User:Tingo/setblocksize Setblocksize] at Norsk Data Wiki
* [http://www.redbooks.ibm.com/redbooks/pdfs/sg245693.pdf AS/400 Disk Storage Topics and Tools], IBM Redbook
* [http://www-304.ibm.com/partnerworld/gsd/solutiondetails.do?solution=51352&expand=true&lc=en Flash Disk SSD/IBM] in IBM Global Solutions Directory
** [http://www.peripheral-vision.com/products/scsi-to-compact-flash/ SCSICFDISK - SCSI to Compact Flash Disk] from Peripheral Vision
* [http://friedkiwi.github.io/scsi2sd/ SCSI2SD/400]
* [http://qseco.fr/research/demystifying-as400-dasd/ Demystifying AS/400 DASD]
* [http://ps-2.kev009.com/rs6000/manuals/SAN/ESS/2105_Model_ExxFxx/ESS_SCSI_Command_Reference_ExxFxx_SC26-7297-01.PDF IBM SCSI Command Reference,] 2105 Models E10, E20, F10, and F20

== Footnotes ==
<references />

[[Category: Hardware Configuration Guide]]

Ordinary Harddisks on the AS/400

2023-02-11T21:26:27Z

Mlc:

The following article is an excerpt from the [https://kb.pocnet.net/wiki/Standard-Festplatten_an_der_AS/400 PoCnet-Wiki], translated to english language.

Ordinary SCSI-Disks cannot be used with the AS/400. They don’t even show up in DST<ref>Roughly what’s known on PC platforms as ''BIOS''.</ref>.

== AS/400-Disk in a Linux box ==
This is a shortened sample output from a linux box’ kernel log:
scsi 5:0:3:0: Direct-Access IBMAS400 DFHSS4W 5959 PQ: 0 ANSI: 2
scsi5:A:3:0: Tagged Queuing enabled. Depth 8
scsi target5:0:3: Beginning Domain Validation
scsi target5:0:3: wide asynchronous
scsi target5:0:3: FAST-10 WIDE SCSI 20.0 MB/s ST (100 ns, offset 8)
sd 5:0:3:0: [sdb] Unsupported sector size 522.
sd 5:0:3:0: [sdb] 0 512-byte logical blocks: (0 B/0 B)
sd 5:0:3:0: [sdb] 522-byte physical blocks
sd 5:0:3:0: [sdb] Write Protect is off
sd 5:0:3:0: [sdb] Mode Sense: b3 00 10 08
sd 5:0:3:0: [sdb] Write cache: disabled, read cache: enabled, supports DPO and FUA
sd 5:0:3:0: [sdb] Unsupported sector size 522.
sd 5:0:3:0: [sdb] Attached SCSI disk
sd 5:0:3:0: [sdb] Unsupported sector size 522.

As you can see, these disks utilize 522 bytes per sector instead of 512 as the rest of the world does. There is a command line utility called [http://micha.freeshell.org/scsi/ setblocksize] by Michael Baeuerle. It provides the possibility to reformat disks (supporting changeable block sizes) with different sector sizes.

== Ordinary harddisks on the AS/400 ==
Unfortunately, it’s not sufficient to just reformat disks to the proper sector size. It may even happen that disks with a vendor ID different from ''IBM'' won’t show up in DST regardless of the sector size.

Newer research suggests that AS/400 approved disks have a custom IDENTITY response, additional VPD<ref>Vital Product Data.</ref> tables, and two additional, vendor defined SCSI commands: SKIP READ and SKIP WRITE. It is not clear which combination of the differences are mandatory for getting a disk to run on an AS/400.

I tried to get an IBM DCHS 9 GB 3.5" disk to work on a 9401-150, without success. The disk shows up in DST and when trying to start a surface test, the following error message appears:
Error Report

Note: Some action will need to be taken for the errors listed
below. Please select an error to display the detailed
information for it. The detailed information will indicate
what action may need to be taken to correct the error.

Type option, press Enter.
5=Display Detailed Report

OPT Error
_ Disk units without the system support
Entering 5 (for continue), the next message reads:
Disk Units without the System Support

The following disk units do not have the correct system
support. The function you requested can not be completed
until the correct system support is applied. Call for service.

Serial Resource
ASP Unit Number Type Model Name Status
[Output of details for the disk in question]
Trying to format the disk within DST yields the following error:
Combined Error/Attention Report

Note: Some action may need to be taken for the errors and/or
problems listed below. Please select an error or problem to
display the detailed information for it. The detailed
information will indicate what action may need to be taken
to correct the error or the problem.

Type option, press Enter.
5=Display Detailed Report

OPT Error
_ Disk unit I/O failure, check reference code
Entering 5 (for continue), the next message reads:
I/O Error

The system encountered an error while it was attempting to
read or write to a disk unit.

Contact your service representative with the following
information:

--Reference Codes--
Serial Resource I/O
Number Type Model Name Processor Device
The reference codes are 0. Not helpful.

== Background Information ==
Disks for AS/400 systems come in two flavours, 520 bytes and 522 bytes per sector. The 520 bytes format is considered outdated by IBM. 520 bytes formatted disks were used with old CISC machines only.<ref>Exception: AS/400 5xx models with disks attached on the internal Multi-Function I/O Processor.</ref>

The 520 bytes format is composed of:
* 8 bytes header,
* 512 bytes payload

The 522 bytes format composed of:
* 8 bytes header,
* 512 bytes payload,
* 2 bytes trailer

The 522 bytes format is mandatory for:
* RAID,
* Compression

Metadata for these (and probably more) features are kept in these trailer bytes.

The header consists of metadata for the block’s payload. Example: Protection (RAID1, RAID5 or similar). Also it contains flags if the block contains valid data, an individual block address (probably needed for the famous single level storage addressing scheme), and more. Metatada is exclusively utilized by the I/O processor. The OS itself handles 512 bytes per sector data as known from other systems.

Header and trailer will be written while formatting a drive with the accompanying AS/400 tool (DST).

== Alternative Solutions ==
A UK based company offers an adapter board that makes it possible to use standard compact flash media instead of spinning disks. It seems that this solution has never been tested in the field. I got a product sample for testing but it fails to be recognized by the system: This adapter also works with 512 Bytes per sector and as such won’t be recognized by the system.

The adapter also provides emulation of a tape drive. This works like a charm.

== Weblinks ==
* [http://pissedoffadmins.com/general/unsupported-sector-size-520.html Unsupported sector size 520] at PissedOffAdmins
* [http://www.ndwiki.org/wiki/User:Tingo/setblocksize Setblocksize] at Norsk Data Wiki
* [http://www.redbooks.ibm.com/redbooks/pdfs/sg245693.pdf AS/400 Disk Storage Topics and Tools], IBM Redbook
* [http://www-304.ibm.com/partnerworld/gsd/solutiondetails.do?solution=51352&expand=true&lc=en Flash Disk SSD/IBM] in IBM Global Solutions Directory
** [http://www.peripheral-vision.com/products/scsi-to-compact-flash/ SCSICFDISK - SCSI to Compact Flash Disk] from Peripheral Vision
* [http://friedkiwi.github.io/scsi2sd/ SCSI2SD/400]
* [http://qseco.fr/research/demystifying-as400-dasd/ Demystifying AS/400 DASD]
* [http://ps-2.kev009.com/rs6000/manuals/SAN/ESS/2105_Model_ExxFxx/ESS_SCSI_Command_Reference_ExxFxx_SC26-7297-01.PDF IBM SCSI Command Reference,] 2105 Models E10, E20, F10, and F20

== Footnotes ==
<references />

[[Category: Hardware Configuration Guide]]

About Green Screens and mouse-clickable UIs

2023-01-25T02:05:05Z

Mlc: /* How the AS/400 Text-UI works */

There are plenty of resources online in the web regarding this topic. It seems to be something religious, like the [[wikipedia:Editor war|Editor War]] EMACS versus vi or vim.

== Introduction ==
Some people insist that character based UIs are hopelessly outdated and '''must''' be modernized. That usually<ref>Due to constraints of the money made available to achieve this goal.</ref> means: Apply some technology that hides the crude text UI behind a fancy web UI, running in any decent web browser.<ref>Modern Web browsers incorporate so much more functionality than just rendering text and graphics, as it was in 1993. This fact is reflected in numerous fixed security holes in modern Web Browsers. There are so much more yet to be discovered, though. See also Donald Rumsfeld's musings about [[wikipedia:There are known knowns|(Un)known (un)knowns]].</ref> 
Others insist that point-'n-click-interfaces are a serious brake of true productivity. All this constant arm motion between mouse and keyboard does obviously lower the amount of information flowing back and forth between the user and the system: Arm moving overhead.<ref>Nowadays, people are expected to know how to use a computer. Training at company level isn't done anymore. This leads to even worse efficiency: How many times did you wince in silent pain when someone actually clicked into another field of a form instead of just pressing the <code>Tab</code>-Key?</ref>

Let me add a third party and then clean up the resulting mess. Unix/Linux<ref>To keep the text reasonably readable, I refuse to make a difference between UNIX (as in SystemV, BSD and whatnot) versus GNU Linux Systems. Today, both platforms are akin enough to justify this heresy.</ref> Sysadmins as well as Linux Power Users usually insist on using the ''shell'', a character based UI in itself. It provides for the concatenation of simple tools to do tasks on files or data streams, or whole directory structures. This feature proved to be powerful for experienced users. Do a maximum of work with a minimum of effort. 
These very same people see an (emulated) AS/400 screen and almost immediately the expected behavior kicks in: Old, outdated, legacy, you name it.

Seen from another point of view, the AS/400 is commonly perceived as ultimately boring. That is because the AS/400 is mostly running stuff considered boring (by geeks). Commercial IT at its best<ref>Or worst.</ref>: Warehouse management, personnel administration, tracking account movements, to name a few. Stuff that makes sure civilisation as we know it won’t collapse, because money stops flowing, carriage of goods ceases, personnel isn't directed to where needed.

Then, there are also some people who argue that by keeping the ''green screen'' alive, the '''perceived''' outdatedness of the system to others is even more increased. They emphasize that this is doing great harm to the IBM i platform at large, because all effort to convince people that it's not about green screens anymore, is negated. So, interestingly, they’re not appalled against green screens because they don't like them themselves, but because they care about '''other people's perceptions''' over reasonable facts that green screens still have their use cases.<ref>Weird? I think so, also.</ref>

== The Best of both Worlds ==
Well, almost.

* Graphical User Interfaces allow the users to point (either with a mouse or a finger/stylus on a touch sensitive screen) on and activate graphical elements on the screen, trying to resemble objects in our physical world. Icons can provide additional, non-textual information regarding the elements on the screen. Until one needs to actually enter data in a classical sense (by typing)<ref>I want to emphasize that using a mouse is also a perfectly valid data acquisition method. One example is the refinement of pixel based pictures. Automatic methods work only to a certain extent and some pixel-modifications still are best done by a hand guiding an input device to steer a cursor on screen.</ref>, everything can be done with just one facility: The translation tool between the physical world and the logical world, most often the mouse but increasingly often by using fingers or a stylus. The user can actually guess which steps to take to complete a given task by contextual conjunction of screen content with expected outcome. The given task is often accomplished step by step instead of one go.
* Command Line Interfaces aim to minimize often time consuming interaction between user and system and sacrifice this by expecting that the user knows which command(s) to enter for a given task to be done. Often a command is started and runs without intervention until the task is complete. Complex tasks usually result in long commands-with-options (or chained commands via [[wikipedia:Pipeline (Unix)|pipes]]), usually requiring a lot of typing. This is somewhat leveraged by the advent of [[wikipedia:Command-line completion|Autocompletion]] capable command shells.

Some (rare) tasks feature very high complexity which makes it almost impossible to create an user friendly Graphical User Interface to collect parameters, while maintaining a certain amount of intuitive UI design Graphical User Interfaces are praised for. Seen from another point of view: Graphical User Interfaces hide complexity and sacrifice that with less flexibility.

Use the right tool for the task in front of you. This is a fundamental statement holding true for every task in computing<ref>And in real life.</ref> and is not restricted to Unix environments.

== How the AS/400 Text-UI works ==
The AS/400 was created as a business aid. This comes down to efficient handling of structured data that has to be entered, processed, stored, reviewed and maybe printed. The system was designed to help people interact in a reasonably user friendly way with it with the then state of the art technology: Character based interfaces utilizing a keyboard for command and data input, and a CRT screen for immediate display of the system’s responses.<ref>Keep in mind that commercial and scientifical computing relied on punched card decks for input and paper prints for output right into the 1970s: Classical Batch Processing.</ref> But this doesn’t automatically equate to a command line interface.

The AS/400 has a unique feature that distinguishes it from other character based systems, like Unix: The whole UI revolves mainly around forms and menus, accompanied by static text. The layouts of these screens are somewhat standardized. AS/400 screens are very recognizable because of this.

[[File:Main-menu.png|thumb|right|German Main Menu after Signon.]]
The classic AS/400 green screen consists of numbered menu items with an input line beneath. One may enter a number and press <code>Enter</code> to pick a menu choice. Or someone may enter a command with accompanying parameters into the same space, if one knows what to enter. If one doesn’t know the exact parameters and allowed values of a command, a keypress of <code>F4</code> invokes a full screen form for the requested command, aiding the user in choosing the right parameters for the desired action to be taken.

Sometimes, choosing a menu item reveals another menu. Sometimes a form with text input fields is displayed for the user to fill in needed parameters, so the command may be run with the desired outcome. Rarely no parameters are supported and the command just runs.

For every editable field on the screen, the user is allowed to place the cursor there and again press <code>F4</code> to be presented with ''another'' screen, listing allowed values for this particular parameter.<ref>Interestingly, there are situations when you are forced to enter data from your (brain based) memory into a field instead of the system letting the user choose from available choices on another <code>F4</code>-invoked screen. A notable example is when you want to create a ''line description'' configuration object, you’ll need to do a manual lookup of available hardware IDs before.</ref>

If this facility also fails to provide proper enlightenment, one may press <code>F1</code> at any time to invoke a [[wikipedia:Context-sensitive_help|context-sensitive]]<ref>This means: The shown help text is different for different cursor positions on the screen.</ref> help text, which is almost always surprisingly helpful<ref>Compared to the help texts in early Windows operating systems.</ref>. See [[CL Tricks]] for an overview. These features are unique among text based UIs.

The ubiquitous ''command shell'' of Unix, macOS, Windows and others is restricted to commands to be entered, together with (sometimes mandatory) parameters. Commands are entered into the last line of the terminal window. Output from commands appears over this line and scrolls to the top until it’s out of sight<ref>Depending on the terminal emulator, a scrollback-buffer can be configured to allow retrieval of older output messages within the GUI.</ref>. 
Any help for a command’s parameters must be invoked by separate facilities (e. g. invoking the command with a [[wikipedia:Command-line interface#Command-line option|parameter]] to show an usually terse online help, or by reading Unix [[wikipedia:man page|Man-Pages]]), and manually complete the command line by re-entering the needed command options.<ref>The only other known system with a comparable function is Apple’s legacy Unix system ''A/UX'': Double-clicking a command (as opposed to an Application Program) opens a modal graphical display box, helping in completing the command line utilizing familiar graphical UI elements.</ref>

Concluding: The AS/400 is located somewhere in between GUI and CLI. As one might see now, intuitive user interfaces must not necessarily equate to being graphic (pixel-based).
* CLIs are unintuitive because their cursors blink at the user, patiently waiting for a command to be entered but hinting no clue what to type.<ref>Entering <code>help</code> within a ''bash'' Linux Command Line prints overwhelming 46 lines of internal commands. The important lines how to actually get more help have scrolled out of the usual 80×25 window.</ref>
* AS/400 menus, forms and GUIs present structured information to the user that (hopefully) guide the user to take the right steps for completing a given task. They ''interact'' with the user.

== Why still text, then? ==
Someone might object that if there's no operational difference between GUIs and AS/400 menus/forms regarding intuitive handling of the system, why does the modern AS/400 still lack a GUI? Well, only IBM can answer this question without making guesses. If I should make a guess, I'd say: Because it would be a change that
# just isn't implementable with hardware already bought by customers,
# existing applications would only take minor advantage of (if any!),
# it would upset system operators who mostly learned to love the text UI.

[[File:Main-menu-wsg.png|thumb|right|Main Menu shown in a browser's window through ''Workstation Gateway''.]]
IBM tried to make the AS/400 more click'n'pointy. There is a facility called ''Workstation Gateway''<ref>Usually available on ''<nowiki>http://your-as400-ip:5061/wsg</nowiki>'' after starting the appropriate TCP service.</ref>, translating AS/400 screen elements on the fly into their HTML counterpart, if existing. It basically works and it's clickable but it looks gross compared to modern standards: No icons, no color, no eye candy.

There's a program called ''Operations Navigator'' that comes as a Client Application, running (only) on Windows, providing graphical equivalents of some operating system commands/tasks. Some things (like the management of the integrated CIFS/SMB-Server) could be configured solely with ''OpNav'' but not with Green Screen commands and forms.<ref>If you find out who took this decision, please let me know. I'd love to unload some serious cusses on him.</ref>

Also, the Configuration of the IBM http server is done via Web Browser, and CGI-Programs running on the AS/400. Unfortunately, this facility is painfully slow, at least on a 150. Not exactly the best promotion for IBM, trying to convince programmers and system administrators to abandon text interfaces in favor to Web Based Applications.<ref>Fortunately, the [[IBM HTTP-Server for AS/400 Configuration|configuration]] is text based and saved in a database file.</ref>

So, the main reason for IBM retaining the text interface is compatibility. For the rest of us, the fact that they're displayed very quickly with a lot less of resources (memory, data transfer speed, cpu cycles) needed when compared to a graphical UI is possibly of equal importance.

Concluding, the majority of information we humans consume is still text. We look at web pages, word processing documents and read PDF files in the digital world. Graphical UIs make it easier to fake screen output into ''looks like a book'', with nice fonts, screen antialiasing and very high resolution displays like Apple's Retina Display, first introduced on the iOS platform. And it truly makes a difference! Reading long texts is easier from paper or such screens compared to a typewriter page. Or a monospaced terminal screen, be it 5250 or VT100. '''But''' reading long texts isn't what's usually be done in terminals.<ref>MUDders and Zork-Players: I know you will gasp now. Sorry, but you're really the opposite of ''usually''. Don't take it personal.</ref>

== Pros and Cons ==
… regarding AS/400 forms and menus versus GUIs:
* AS/400 forms and menus run in a space constrained area with an adressable matrix of either 80×24 or 132×27 characters. Larger screens provide larger characters but not more usable space. This is different with GUIs. Larger screens usually (can) display more pixels and as such (can) display more information concurrently. The former can be seen as a challenge for programmers to concentrate on necessary information for the immediate task at hand while omitting or postponing less important information to screens later in the necessary sequence. This could lead to improved clarity of the application's UI, and/or to the user losing overview by no longer seeing information that may be important for a given step of a task at hand.
* AS/400 forms and menus are built from tiny chunks of data compared to graphical UIs. So they can be transferred and displayed very fast. In environments where client and server are connected through high latency networks, GUIs perform poorly because of lagging response from the UI. Also, GUIs graphical representation must be built by program code running in part on the displaying client's CPU and GPU. Just displaying characters on a CRT can be done with comparatively tiny resources (a few kiB of RAM, and a processor clocked in the single-digit Megahertz range).

The only feature the AS/400 UI itself lacks is [[wikipedia:Cut, copy, and paste|Copy & Paste]]. So by utilizing a terminal emulator on current GUI based desktop systems to connect to the AS/400 terminal session, one can benefit from the best of both worlds. Also, one may connect a [[Using the Mouse on a Hardware Terminal|PS/2-Mouse to certain IBM terminals]], also providing facilities for selecting and duplicating text.

== Footnotes ==
<references />

[[Category: Musings]]

About Green Screens and mouse-clickable UIs

2023-01-25T02:00:45Z

Mlc: /* Introduction */

There are plenty of resources online in the web regarding this topic. It seems to be something religious, like the [[wikipedia:Editor war|Editor War]] EMACS versus vi or vim.

== Introduction ==
Some people insist that character based UIs are hopelessly outdated and '''must''' be modernized. That usually<ref>Due to constraints of the money made available to achieve this goal.</ref> means: Apply some technology that hides the crude text UI behind a fancy web UI, running in any decent web browser.<ref>Modern Web browsers incorporate so much more functionality than just rendering text and graphics, as it was in 1993. This fact is reflected in numerous fixed security holes in modern Web Browsers. There are so much more yet to be discovered, though. See also Donald Rumsfeld's musings about [[wikipedia:There are known knowns|(Un)known (un)knowns]].</ref> 
Others insist that point-'n-click-interfaces are a serious brake of true productivity. All this constant arm motion between mouse and keyboard does obviously lower the amount of information flowing back and forth between the user and the system: Arm moving overhead.<ref>Nowadays, people are expected to know how to use a computer. Training at company level isn't done anymore. This leads to even worse efficiency: How many times did you wince in silent pain when someone actually clicked into another field of a form instead of just pressing the <code>Tab</code>-Key?</ref>

Let me add a third party and then clean up the resulting mess. Unix/Linux<ref>To keep the text reasonably readable, I refuse to make a difference between UNIX (as in SystemV, BSD and whatnot) versus GNU Linux Systems. Today, both platforms are akin enough to justify this heresy.</ref> Sysadmins as well as Linux Power Users usually insist on using the ''shell'', a character based UI in itself. It provides for the concatenation of simple tools to do tasks on files or data streams, or whole directory structures. This feature proved to be powerful for experienced users. Do a maximum of work with a minimum of effort. 
These very same people see an (emulated) AS/400 screen and almost immediately the expected behavior kicks in: Old, outdated, legacy, you name it.

Seen from another point of view, the AS/400 is commonly perceived as ultimately boring. That is because the AS/400 is mostly running stuff considered boring (by geeks). Commercial IT at its best<ref>Or worst.</ref>: Warehouse management, personnel administration, tracking account movements, to name a few. Stuff that makes sure civilisation as we know it won’t collapse, because money stops flowing, carriage of goods ceases, personnel isn't directed to where needed.

Then, there are also some people who argue that by keeping the ''green screen'' alive, the '''perceived''' outdatedness of the system to others is even more increased. They emphasize that this is doing great harm to the IBM i platform at large, because all effort to convince people that it's not about green screens anymore, is negated. So, interestingly, they’re not appalled against green screens because they don't like them themselves, but because they care about '''other people's perceptions''' over reasonable facts that green screens still have their use cases.<ref>Weird? I think so, also.</ref>

== The Best of both Worlds ==
Well, almost.

* Graphical User Interfaces allow the users to point (either with a mouse or a finger/stylus on a touch sensitive screen) on and activate graphical elements on the screen, trying to resemble objects in our physical world. Icons can provide additional, non-textual information regarding the elements on the screen. Until one needs to actually enter data in a classical sense (by typing)<ref>I want to emphasize that using a mouse is also a perfectly valid data acquisition method. One example is the refinement of pixel based pictures. Automatic methods work only to a certain extent and some pixel-modifications still are best done by a hand guiding an input device to steer a cursor on screen.</ref>, everything can be done with just one facility: The translation tool between the physical world and the logical world, most often the mouse but increasingly often by using fingers or a stylus. The user can actually guess which steps to take to complete a given task by contextual conjunction of screen content with expected outcome. The given task is often accomplished step by step instead of one go.
* Command Line Interfaces aim to minimize often time consuming interaction between user and system and sacrifice this by expecting that the user knows which command(s) to enter for a given task to be done. Often a command is started and runs without intervention until the task is complete. Complex tasks usually result in long commands-with-options (or chained commands via [[wikipedia:Pipeline (Unix)|pipes]]), usually requiring a lot of typing. This is somewhat leveraged by the advent of [[wikipedia:Command-line completion|Autocompletion]] capable command shells.

Some (rare) tasks feature very high complexity which makes it almost impossible to create an user friendly Graphical User Interface to collect parameters, while maintaining a certain amount of intuitive UI design Graphical User Interfaces are praised for. Seen from another point of view: Graphical User Interfaces hide complexity and sacrifice that with less flexibility.

Use the right tool for the task in front of you. This is a fundamental statement holding true for every task in computing<ref>And in real life.</ref> and is not restricted to Unix environments.

== How the AS/400 Text-UI works ==
The AS/400 was created as a business aid. This comes down to efficient handling of structured data that has to be entered, processed, stored, reviewed and maybe printed. The system was designed to help people interact in a reasonably user friendly way with it with the then state of the art technology: Character based interfaces utilizing a Keyboard for command and data input, and a CRT Screen for immediate display of the system's responses.<ref>Keep in mind that commercial and scientifical computing relied on punched card decks for input and paper prints for output right into the 1970s: Classical Batch Processing.</ref> But this doesn't automatically equate to a command line interface.

The AS/400 has a unique feature that distinguishes it from other character based systems, like Unix: The whole UI revolves mainly around forms and menus, accompanied by static text. The layouts of these screens are somewhat standardized. AS/400 screens are very recognizable because of this.

[[File:Main-menu.png|thumb|right|German Main Menu after Signon.]]
The classic AS/400 green screen consists of numbered menu items with an input line beneath. One may enter a number and press <code>Enter</code> to pick a menu choice. Or someone may enter a command with accompanying parameters into the same space, if one knows what to enter. If one doesn't know the exact parameters and allowed values of a command, a keypress of <code>F4</code> invokes a full screen form for the requested command, aiding the user in choosing the right parameters for the desired action to be taken.

Sometimes, choosing a menu item reveals another menu. Sometimes a form with text input fields is displayed for the user to fill in needed parameters, so the command may be run with the desired outcome. Rarely no parameters are supported and the command just runs.

For every editable field on the screen, the user is allowed to place the cursor there and again press <code>F4</code> to be presented with ''another'' screen, listing allowed values for this particular parameter.<ref>Interestingly, there are situations when you are forced to enter data from your (brain based) memory into a field instead of the system letting the user choose from available choices on another <code>F4</code>-invoked screen. A notable example is when you want to create a ''line description'' configuration object, you'll need to do a manual lookup of available hardware IDs before.</ref>

If this facility also fails to provide proper enlightenment, one may press <code>F1</code> at any time to invoke a [[wikipedia:Context-sensitive_help|context-sensitive]]<ref>This means: The shown help text is different for different cursor positions on the screen.</ref> help text, which is almost always surprisingly helpful<ref>Compared to the help texts in early Windows operating systems.</ref>. See [[CL Tricks]] for an overview. These features are unique among text based UIs.

The ubiquitous ''command shell'' of Unix, Mac OS X, Windows and others is restricted to commands to be entered, together with (sometimes mandatory) parameters. Commands are entered into the last line of the terminal window. Output from commands appears over this line and scrolls to the top until it's out of sight<ref>Depending on the terminal emulator, a scrollback-buffer can be configured to allow retrieval of older output messages within the GUI.</ref>. 
Any help for a command's parameters must be invoked by separate facilities (e. g. invoking the command with a [[wikipedia:Command-line interface#Command-line option|parameter]] to show an usually terse online help, or by reading Unix [[wikipedia:man page|Man-Pages]]), and manually complete the command line by re-entering the needed command options.<ref>The only other known system with a comparable function is Apple's legacy Unix system ''A/UX'': Double-clicking a command (as opposed to an Application Program) opens a modal graphical display box, helping in completing the command line utilizing familiar graphical UI elements.</ref>

Concluding: The AS/400 is located somewhere in between GUI and CLI. As one might see now, intuitive user interfaces must not necessarily equate to being graphic (pixel-based).
* CLIs are unintuitive because their cursors blink at the user, patiently waiting for a command to be entered but hinting no clue what to type.<ref>Entering <code>help</code> within a ''bash'' Linux Command Line prints overwhelming 46 lines of internal commands. The important lines how to actually get more help have scrolled out of the usual 80×25-Window.</ref>
* AS/400 menus, forms and GUIs present structured information to the user that (hopefully) guide the user to take the right steps for completing a given task. They ''interact'' with the user.

== Why still text, then? ==
Someone might object that if there's no operational difference between GUIs and AS/400 menus/forms regarding intuitive handling of the system, why does the modern AS/400 still lack a GUI? Well, only IBM can answer this question without making guesses. If I should make a guess, I'd say: Because it would be a change that
# just isn't implementable with hardware already bought by customers,
# existing applications would only take minor advantage of (if any!),
# it would upset system operators who mostly learned to love the text UI.

[[File:Main-menu-wsg.png|thumb|right|Main Menu shown in a browser's window through ''Workstation Gateway''.]]
IBM tried to make the AS/400 more click'n'pointy. There is a facility called ''Workstation Gateway''<ref>Usually available on ''<nowiki>http://your-as400-ip:5061/wsg</nowiki>'' after starting the appropriate TCP service.</ref>, translating AS/400 screen elements on the fly into their HTML counterpart, if existing. It basically works and it's clickable but it looks gross compared to modern standards: No icons, no color, no eye candy.

There's a program called ''Operations Navigator'' that comes as a Client Application, running (only) on Windows, providing graphical equivalents of some operating system commands/tasks. Some things (like the management of the integrated CIFS/SMB-Server) could be configured solely with ''OpNav'' but not with Green Screen commands and forms.<ref>If you find out who took this decision, please let me know. I'd love to unload some serious cusses on him.</ref>

Also, the Configuration of the IBM http server is done via Web Browser, and CGI-Programs running on the AS/400. Unfortunately, this facility is painfully slow, at least on a 150. Not exactly the best promotion for IBM, trying to convince programmers and system administrators to abandon text interfaces in favor to Web Based Applications.<ref>Fortunately, the [[IBM HTTP-Server for AS/400 Configuration|configuration]] is text based and saved in a database file.</ref>

So, the main reason for IBM retaining the text interface is compatibility. For the rest of us, the fact that they're displayed very quickly with a lot less of resources (memory, data transfer speed, cpu cycles) needed when compared to a graphical UI is possibly of equal importance.

Concluding, the majority of information we humans consume is still text. We look at web pages, word processing documents and read PDF files in the digital world. Graphical UIs make it easier to fake screen output into ''looks like a book'', with nice fonts, screen antialiasing and very high resolution displays like Apple's Retina Display, first introduced on the iOS platform. And it truly makes a difference! Reading long texts is easier from paper or such screens compared to a typewriter page. Or a monospaced terminal screen, be it 5250 or VT100. '''But''' reading long texts isn't what's usually be done in terminals.<ref>MUDders and Zork-Players: I know you will gasp now. Sorry, but you're really the opposite of ''usually''. Don't take it personal.</ref>

== Pros and Cons ==
… regarding AS/400 forms and menus versus GUIs:
* AS/400 forms and menus run in a space constrained area with an adressable matrix of either 80×24 or 132×27 characters. Larger screens provide larger characters but not more usable space. This is different with GUIs. Larger screens usually (can) display more pixels and as such (can) display more information concurrently. The former can be seen as a challenge for programmers to concentrate on necessary information for the immediate task at hand while omitting or postponing less important information to screens later in the necessary sequence. This could lead to improved clarity of the application's UI, and/or to the user losing overview by no longer seeing information that may be important for a given step of a task at hand.
* AS/400 forms and menus are built from tiny chunks of data compared to graphical UIs. So they can be transferred and displayed very fast. In environments where client and server are connected through high latency networks, GUIs perform poorly because of lagging response from the UI. Also, GUIs graphical representation must be built by program code running in part on the displaying client's CPU and GPU. Just displaying characters on a CRT can be done with comparatively tiny resources (a few kiB of RAM, and a processor clocked in the single-digit Megahertz range).

The only feature the AS/400 UI itself lacks is [[wikipedia:Cut, copy, and paste|Copy & Paste]]. So by utilizing a terminal emulator on current GUI based desktop systems to connect to the AS/400 terminal session, one can benefit from the best of both worlds. Also, one may connect a [[Using the Mouse on a Hardware Terminal|PS/2-Mouse to certain IBM terminals]], also providing facilities for selecting and duplicating text.

== Footnotes ==
<references />

[[Category: Musings]]

Main Page

2023-01-22T22:58:21Z

Mlc: typografische Apostrophen, Großschreibung an Engl. angepaßt. Keine inhaltlichen Änderungen.

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.

== 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, you may possibly understand that this Wiki has a lot of content and is constantly growing and being filled with more information. 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]>.

I had a hard time to learn 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, that is from the early 2000’s. When I describe different machines or OS releases, I‘ll indicate that in the 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 2019 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].

=== 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]]

How to access your AS/400

2023-01-20T22:10:20Z

Mlc: /* Today */

Today, there are multiple ways to access an AS/400. This article is mainly about ''terminal access''.

Terminal access is defined by transmission of cursor position, text, fields and their attributes as well as data from database tables, transferred according to a definition called ''[[wikipedia:IBM 5250|5250 data stream]]''. This is somewhat analog to the well known [[wikipedia:VT100|VT100]] protocol in character-based terminal systems.

Additionally, recent implementations of OS/400 feature ssh-Access. But it's different than one would think: This facility provides shell access to the built-in UNIX environment, called PASE. See [[The Split Personality of OS/400]].

== Block- versus character-oriented transmissions ==
However, a huge difference between those is that with the former, the user is presented with a form, to look at and/or fill out. Changes are only made locally, in the memory of the terminal or emulator. When everything is finished, a special key is pressed and the form is transmitted in its entirety back to the host for processing. 
This is quite like a HTML form being displayed and filled out in a browser window, getting also transferred back in its entirety by pressing the ''submit''-button.<ref>It is rarely labelled like that today, though.</ref>

This is in stark contrast to terminals in the Unix world, where the host is handling communications and screen appearance itself. Every single keypress will go back to the host, trigger an action, based on which appropriate data will be sent back to the terminal for updating on-screen content.

Block oriented protocols like 5250 (and 3270) were useful when computing resources were scarce. Imagine hundreds of users typing data into fields of forms and thus interrupting the CPU for simple cursor movement and character-echoing. 
On the other hand, block-oriented transmissions have drawbacks in interactivity. The user can only do what the protocol permits locally. Such stuff as incremental search as one types a search string while the application narrows possible matches with every additional character from that string is not possible in block oriented mode.<ref>Through special programming techniques, it is indeed possible to achieve such a high grade of interactivity. It is simply based on really frequent data exchange with the host. But since the whole machine and OS are built around this block-oriented approach, it is ugly to implement, creates additional processing load on the machine and thus will most likely affect other users on the same machine.</ref>

== History ==
Historically, all access to the machine involved terminal sessions which were established with, well, terminals: A combination of a CRT display, a controller chip and a keyboard. Rarely accompanied by the possibility to connect a PS/2 mouse.<ref>Example: IBM 3486, which also provided a graphical rendition of some on-screen objects, like window frames.</ref> Today, they're called ''dumb'' which is plainly wrong. These terminals included a basic SNA stack and coded logic for local processing of input and screen appearance. They're not quite as dumb as, say, a VT100. 
Terminals were attached through [[wikipedia:Twinaxial cabling|Twinaxial Cables]], thick as a small finger with bulky connectors. The whole system was expensive, complicated to run through a building (because of a large minimum bending radius) but rock solid.

An AS/400 could utilize at least one twinax controller (board) with at least four independent ports for daisy chaining terminals. Because the terminals ran a subset of SNA, they could be daisy chained, easing cabling requirements somewhat. Transmission rate was 1 Mbit/s per port, providing almost instant screen updates.<ref>Compare that with the 9600 bps of standard ASCII terminals of that era.</ref> There were controllers available with supported eight-port bricks as well. Bigger machines could have multiple twinax controllers inside to support hundreds of terminals simultaneously.

Today, the twinax attachment is still a necessity with old hardware, since it provides console services, for OS installation and running backups without any users keeping files open. And for troubleshooting, of course. See also details to the [[Your own AS/400#Console|Console]].

=== Twinax without terminals ===
IBM and other manufacturers built [[wikipedia:Industry Standard Architecture|ISA cards]] and provided software for MS-DOS and early Windows versions for accessing AS/400 terminal sessions over twinax. These combination behaved like a true hardware terminal.

Apple once built a combined coax/twinax card. The coax port was used for connecting to communication controllers attached to a mainframe, to support 3270 terminal sessions. Unfortunately, there seems to be no software support for the twinax port ever being implemented.

=== ASCII Terminals ===
IBM provided expansion cards for SPD-slot based machines called ''ASCII Workstation Controller''. These boards and SLIC integrated firmware allowed the attachment of standard serial terminals (vt100 and the like) to the AS/400, as a way of investment protection. They handled the steady data flow from users typing and protocol conversion from 5250 to vt100 and other then-standard protocols of that era.

=== Network-attached gateway solutions ===
For very slow machines it could be of certain interest to minimize the usage of IP on the machine itself, to save CPU cycles for processing of actual data.<ref>Transferring binary stream files to or from IFS with FTP over a standard 10 Mbit/s adapter easily brings the CPU of a 9401-150 to 100 % load. Transferring data with SNADS over 16 Mbit/s Token Ring yields about 30 % CPU load.</ref> Multiple solutions exist(ed) for communicating solely via SNA to AS/400s, and mainframes:
* ''Apple SNA•ps'' was the outcome of a collaboration with IBM in the early 1990s. Orion Software programmed a gateway and client applications for terminal access and printing in both 5250 and 3270 worlds, that permitted en-/decapsulating APPC traffic in/from AppleTalk. Hardware attachment was provided by a combined Coax/Twinax-Card, a Token Ring Card or a multiport Serial Card for SDLC transport. Each of these NuBus cards featured their own m68k CPU and between 0.5 to 2.5 MiB of local RAM. Part of the gateway software runs on that CPU. Included is additional software and documentation for developing custom solutions based on APPC over AppleTalk.
* ''[https://en.wikipedia.org/wiki/Microsoft_Host_Integration_Server Microsoft SNA Server]'' is a gateway solution for SNA communications running on Microsoft Windows Server systems. It provides protocol conversion between SNA and IP based telnet protocols (tn3270, tn5250) as well as printing services by obtaining spooled files from AS/400 printer queues and either saving it as a local text file or sending it to the Windows printing system. It also provides protocol conversion services for database access via OLE and ODBC. Additionally, it exploits the AS/400 ''shared folder subsystem'' to re-export folders within ''/QDLS'' with standard Windows SMB protocol provided by the Windows operating system. Microsoft SNA Server evolved to the ''Microsoft Host Integration Server'', that is still in active development.
* ''Novell Netware for SAA'' was an enhancement for Netware installations. Details will be provided when I had time to install and test this software.
* ''IBM Communications Manager/2'' was an enhancement for OS/2, providing similar services.

=== Branch Office Solutions ===
IBM and other vendors offered terminal multiplexors for twinax-based 5250 nodes, to enable a single leased line being shared by multiple terminals in a branch office. Leased-line capable modems provided the physical connection. The protocol involved SNA over SDLC. Examples are the IBM 5394 Twinax Remote Controller or the Perle 594M.

Cisco Systems offers some features within their router software, IOS, to help integrate IBM SNA into the conventional LAN and WAN world. There are certain combinations of Routers and IOS Features in a given image, sometimes accompanied by the need to purchase a license key, that enable to exploit these SNA integration services. See the [https://www.cisco.com/go/fn Cisco Feature Navigator] for finding appropriate combinations. A selection of probably interesting solutions:
* STUN provides a transparent back to back serial port connection for SDLC communication over existing IP networks. This involves the addition of compatible serial port add-on cards with appropriate cabling to the router.
* (Remote) Source Route Bridging provides the extension of physical token ring media via virtual bridges over Ethernet or even TCP connections.
* SNA Switching Services provide PU (physical unit), LU (logical unit) and session services to SNA hosts to eliminate the need for bridging whole networks over WAN links. Usually, connections are initiated from the IBM hosts over Token Ring, Ethernet and probably other media. This enables a router to be the central hub of an APPN network. Every node just needs a connection (PU) definition to the router while the router handles establishment of direct LU-LU APPC connections between peers. SNAsw can be combined with (R)SRB or Enterprise Extender<ref>IBMs own implementation of transporting SNA/APPC traffic over IP.</ref> to provide true APPN functionality over WAN (VPN) connections. Unfortunately, this code proved to be in bad shape. Certain combinations of configuration parameters tend to crash IOS in such a way that a power cycle is necessary to get the router back to life. Worse, this crashes aren't easy to relate to certain network activity: Routers may run for days until they halt for no apparent reason. Sometimes, they just reload when initiating a bulk data transfer.<ref>Seen with Cisco 2901 routers, IOS 15.4(3)M9 SNAsw Port definition on an Ethernet Subinterface with VLAN tagging, and a second ''Virtual-Tokenring'', connecting another Router via RSRB.</ref>

More modern solutions are provided by LAN-attached terminal servers, having Twinax-Ports for Terminals or Printers and an Ethernet-Port for LAN attachment. Communication takes place via tn5250 on the LAN side that makes it possible to use existing IP based VPNs for providing remote access. One notable example is the [http://www.bosanova.net/twinaxcontroller/index.html BOSCOM e-Twin@x-Controller].

== Today ==
Today, most accesses to terminal sessions will take place over ordinary LAN (Ethernet) attachment, IP as transport and tn5250 as high-level protocol. See above for possible drawbacks of this.

Some manufacturers built so called ''smart terminals'' with an integrated tn5250 emulator and an ordinary ethernet port for integration in today’s IP networks.

There are multiple software-based tn5250 clients available, for free and for a fee, and for many operating systems. I strongly recommend utilizing one of those because they usually just work. My favorite is [http://www.mochasoft.dk/tn5250macx.htm Mocha TN5250 for macOS]. It runs very stable, has a sensible mapping of special keys and a support that at least answers to email requests.<ref>Additionally, they released their older programs as freeware, which is a very nice thing to do. Unfortunately, a 5250 client for 68k based Macs isn’t available. This can only be accomplished with SNA•ps, see above.</ref>

See also:
* [[Editing Database Files and other Data]],
* [[Getting Data in and out of your AS/400]].

=== Client Setup ===
Since ''tn5250'' is a protocol with proper standardization, clients share some configuration options. For starters, I strongly recommend to leave any settings at default. You '''must''' change connection relevant parameters, though:
* Hostname or IP address to connect to,
* SSL yes or no, (mostly no for self-owned boxes, SSL needs additional setup on the AS/400 itself).

You '''may''' change secondary parameters, if necessary:
* EBDIC code page, (for umlauts, etc.)
* TCP port to connect to, (if not running on default)
* Terminal type, (monochome/color and 24×80 only vs. additionally 27×132)

You should '''not''' change:<ref>Without knowing the implications.</ref>
* Device name.

=== Telnet ===
It is indeed possible to use plain VT100 over telnet to access AS/400s. The machine (or part of it) will see increased load because of the host based protocol handling when just typing into a terminal. In practice this effect is negligible, especially when there were only half a dozen users working.

Depending on the emulator software (the client) there may be issues with special chars in other languages than english. Sometimes, function keys will not work or function keys larger <code>F12</code> cannot be accessed. Additionally, special command keys like System Request or Attention have no equivalent on a standard PC keyboard.

For these reasons, I strongly recommend utilizing a real 5250 client.

== Footnotes ==
<references />

== Weblinks ==
* [https://kb.pocnet.net/wiki/Apple_SNA•ps_Konfiguration_für_5250-Sitzungen Apple SNA•ps Konfiguration für 5250-Sitzungen], PoCnet Knowledgebase.
* [https://en.wikipedia.org/wiki/A/ROSE Apple Real-time Operating System Environment], Wikipedia.
* [https://www.cisco.com/c/en/us/td/docs/ios/bridging/configuration/guide/15_2s/br_15_2s_book.pdf Bridging and IBM Networking Configuration Guide], PDF.

[[Category: Basic Knowledge]]

Integrating LAN-less Machines into a local Token Ring

2023-01-20T22:02:36Z

Mlc:

Sometimes, older, donated hardware comes without LAN I/O-adapters. Sometimes it has serial communication I/O-adapters, and Twinax, though. This article points out how to integrate such hardware into a local Token Ring network with the help of (older) Cisco hard- and software.

This description is based on a proven to work setup. Surely, there are further ideas to explore, such as bridging the ring to Ethernet for SNA communications to Ethernet connected nodes, or eliminate the ring altogether by replacing it with just a ''Virtual-TokenRing'' interface on the Cisco router.

== Requirements ==
[[File:AS400-SDLC-Cisco-Ring-AS400.png|thumb|right|Network Plan]]
[[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.]]
* AS/400, complete and functioning
** <code>QAUTOCFG</code> system variable switched to on
** Local serial port with required breakouts, such as a #2609, or a #2652
** 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 providing the necessary sense pin connectivity.

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

* Cisco 2502, 2513, 2612 or similar router model with Token Ring interface (card), and a T-Type serial interface (card), running an IOS release with the ''Desktop'' featureset (BINO3S3) for SDLC support.
** Cisco CAB-232 FC
* Other AS/400, complete and functioning, attached and already configured to use a Token Ring LAN
** <code>QAUTOCFG</code> system variable switched to on

== SDLC configuration on AS/400 ==
* After plugging everything together like pointed out above, the serial-only machine is to be configured. Type ''WRKHDWRSC *CMN'' 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>

* Next, the controller description (equivalent to a PU definition in VTAM) to the peer system is to be created. This needs to be done before the line description, because it is referenced there.
CRTCTLAPPC CTLD(OTHERHOST) LINKTYPE(*SDLC) MAXFRAME(1033) RMTCPNAME(REMOTEAS) STNADR(C0) NODETYPE(*CALC) TMSGRPNBR(*CALC) AUTODLTDEV(*NO) CMNRCYLMT(10 1)<ref>Note that this is an example configuration for integrating a new machine into an existing APPN network. Thus, CTLD, and RMTCPNAME might not match the Token Ring AS/400’s settings.</ref>
* Armed with this, a line description is to be created, and the controller decription referenced:
CRTLINSDLC LIND(SDLCLIN) RSRCNAME(LIN011) NRZI(*NO) LINESPEED(19200)<ref>Depending on I/O-adapter and machine model, this might parameter limited to higher or lower values.</ref> MAXFRAME(1033) DUPLEX(*FULL) LINKSPEED(19200) CTL(OTHERHOST) CMNRCYLMT(10 1)
* I suggest to run WRKCTLD and manually set the SWTDSC (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.
* Because auto configuration is enabled, the device description (equivalent to a LU definition in VTAM) for the peer system will be created automatically at the first connection.
* ''REMOTEAS'' in the controller description is the Token Ring machine.

== Configuration on the Cisco router ==
Assumption is that the router has already a basic configuration applied. This includes the Token Ring interface.

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

Proven to work:
* Cisco 2513 with Image C2500-DOS-L, Version 12.2(29b)<ref>This means, a Cisco 2502 (Token Ring and two T-type serial ports) will also work.</ref>
* Cisco 2612 with added WIC-1T, and image C2600-BINO3S3, Version 12.3(26)

=== Notes ===
* <code>sdlc vmac</code> is the virtual MAC address the SDLC AS/400 is assigned on the Token Ring. The last byte '''must''' be 00, while IOS sets the last byte to the SDLC address being given later.
* <code>sdlc address</code> must be the same value as the STNADR parameter in the controller description.
* <code>sdlc partner</code> creates an association from the already existing AS/400’s MAC address on the Token Ring to the SDLC address of the SDLC-AS/400.
* <code>clock rate</code> and <code>sdlc line-speed</code> must match each other, and the LINESPEED 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 gives the attached ring the number 59, designates it to the source bridge 1, and bridges traffic to the virtual ring (group) 512.

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?

== Initiation, and function verification ==
* On the SDLC-AS/400 vary on line and controller descriptions:
VRYCFG CFGOBJ(SDLCLIN) CFGTYPE(*LIN) STATUS(*ON)
* After a brief pause, the Cisco console should show 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 the SDLC-AS/400, looking into the QSYSOPR-Message Queue should show that the line has successfully been varied on, and a connection to the controller ''OTHERHOST'' has been established through SDLCLIN.
* On the Cisco Router, you should see output of <code>show line 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 the Token Ring attached AS/400, you should see the SDLC-attached AS/400 in <code>WRKAPPNSTS OPTION(*LOC)</code>.

=== Configuration corrections ===
The APPC Controller on the Token Ring attached machine has been created with default values. This includes MAXFRAME being set to the default for Token Ring, aka 16393. This '''will''' result in connection instabilities, if not corrected.

* On the SDLC-AS/400 vary off line and controller descriptions:
VRYCFG CFGOBJ(SDLCLIN) CFGTYPE(*LIN) STATUS(*OFF)
* On the Token Ring-AS/400 vary off the controller description:
VRYCFG CFGOBJ(SDLCAS) CFGTYPE(*CTL) STATUS(*OFF)<ref>The name of the controller description depends on the name of the SDLC machine.</ref>
* Change configuration to better matching parameters:
CHGCTLAPPC CTLD(SDLCAS) MAXFRAME(1033) INLCNN(*ANS) NODETYPE(*CALC) AUTODLTDEV(*NO) CMNRCYLMT(10 1) CTLOWN(*USER)
* I suggest to run WRKCTLD and manually set the SWTDSC (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 the Token Ring machine.
VRYCFG CFGOBJ(SDLCAS) CFGTYPE(*CTL) STATUS(*ON)
VRYCFG CFGOBJ(SDLCLIN) CFGTYPE(*LIN) STATUS(*ON)

You now should be able to enjoy a stable, albeit slow connection to your SDLC-Connected AS/400, with each and every service running over SNA.

== Possible Errors ==
It is important that involved configuration settings are fixed to a maximum frame size of 1033, or less:
* SDLC Line Description on the serial AS/400,
* Controller Description for the APPN peer on the serial AS/400,
* Controller Description for the APPN peer on the Token Ring AS/400.

Failing to adhere will lead to connection errors when trying to transfer more data than occasional screen updates. Cisco IOS Debugging helps to find the culprit:
%PQUICC-1-TOOBIG: PQUICC(0/0), packet too big, packet size was 2059 bytes
SDLC Reset, Serial0/0 D2 CONNECT: N2 Expired (iframe(s) resent > N2)

Also important is to provide the proper remote CP-Name for the SDLC machine’s APPC controller description pointing to the Token Ring machine. Failing to do so will prevent CP-CP sessions to be established, and outgoing sessions from the SDLC machine will fail with a ''no path found'' error.<ref>A former revision of this article stated ''RMTCPNAME(*ANY)''. This has been discovered to be wrong.</ref>

== Bridging to Ethernet ==
Cisco IOS has a builtin feature called translational bridging. It allows to bridge source routed (Token Ring) traffic to other media types, such as Ethernet via a “standard” transparent bridge configuration.

Configuration involves a "pseudo ring". This is a completely internal thing to IOS. No configuration necessary. Just make sure the ring number you use for it is unique within a multiple-rings network, no matter if virtual or real rings are involved.

There is no physical Token Ring interface required. You can see in the interface configuration above that the physical ring number 59 is just source bridged over bridge 1 (just a router-locally unique number) to the earlier defined ring-group 512:
source-bridge 59 1 512

=== Configuration ===
Create a transparent bridging configuration, tied to just an Ethernet interface:
bridge irb
!
interface FastEthernet1/0
bridge-group 1
bridge-group 1 subscriber-loop-control
bridge-group 1 spanning-disabled

The last step is to tie the existing ring-group 512 (see above) to a pseudo-ring (256), over a source-bridge 2 (again just a router-locally unique number) to the already created transparent bridge 1. Note that this configuration is global and not in an interface sub-configuration context.
source-bridge transparent 512 256 2 1

Parameters to <code>source-bridge transparent</code> are:
# Source-route ring group attached to the transparent bridge
# Pseudo-ring number of the transparent bridge
# Bridge number to the transparent bridge
# Transparent bridge group attached to the virtual ring

MAC addresses involved can be seen with <code>show bridge 1</code>.

'''Note!''' Token Ring and Ethernet use different bit orderings for MAC addresses! Thus, if you want to configure a node on the Ethernet side of affairs to connect to the "fake" MAC Token Ring address of your SDLC machine, you must bit-swap the address <code>0004.acad.5900</code>.<ref>One example is the “Windows only” [http://www.bttsoftware.co.uk/canon.html BTT Canonical Address converter]. I haven’t found a web-form based converter.</ref> The result is <code>0020.35b5.9a00</code>.

== See also ==
* [[Serial cables IDs]]
* [[RS-232 modem cable pinout]]
* [[Creating Configuring TCP/IP and SLIP with Cisco router and V3R2]]

== Weblinks ==
* [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/support/docs/routers/10000-series-routers/46800-cab232mtfc.html#cab-232fc Serial Cable CAB-232FC], Cisco.com
* [https://ibmdocs.pocnet.net/SY44-5902-03.pdf 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>
* [https://www.cisco.com/c/en/us/td/docs/ios/bridging/configuration/guide/15SY/br_15_sy_book/br_overview_brdg.html Bridging and IBM Networking Configuration Guide], Cisco IOS Release 15SY

== Footnotes ==
<references />

== Acknowledgements ==
Thanks to Ben Huntsman, Alexander Huemer, and Herman val Kleef for hints and nudges to the right direction.

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

Features that separate the AS/400 from common computer systems

2023-01-20T21:51:12Z

Mlc: /* Split OS */

The AS/400 as a whole of Soft- and Hardware has a bunch of unique features as advertised by IBM:
* High Level Machine,
* Object Orientation,
* Single Level Storage,
* Hierarchy of Microprocessors,
* Operating System: OS/400.

These are nicely explained in the video linked [[#Weblinks|below]].

Reviewed in 2022, some are still relevant, some are no longer. Additionally, I'll highlight features that I think are unique compared to common platforms, and not listed above.

== Split OS ==
OS/400 may be seen as split in half.<ref>Not necessarily evenly sized halves.</ref> An good deal of it (about 1 GiB with V4) is called ''System Licensed Internal Code'' (SLIC) and handles hardware dependent stuff. This includes features like multiple processors with dedicated memory just for I/O tasks.<ref>This may be seen as a technical borrowing from the mainframe world within IBM. This technique is called ''Channel'' there.</ref>

Above the SLIC is the OS/400 and its components system administrators and users usually see and deal with. This is called [[wikipedia:Control Program Facility|CPF]]<ref>Control Program Facility</ref>, a leftover from the AS/400’s ancestor, the System/38.

== Byte Code ==
Compilers don't output CPU native byte code but kind of intermediate code, for example like Java does. This makes compiled programs surprisingly large in size but enables an unprecedented backwards compatibility on binary level.

Binary programs copied to a newer machine with different processor technology can just be started like on the old platform. The start will take a few moments in that the SLIC recognizes missing CPU native code, compiles the intermediate byte code and adds the result to the program object. After that, the program is started and runs as native code on a possibly completely different CPU architecture.

IBM exploited this possibility when they switched the hardware from a custom 48-Bit CISC CPU architecture<ref>Derived from the CPUs in IBM Mainframes of the 1980s era.</ref> to the PowerPC AS architecture in the mid-1990s. In later incarnations, there have been some restrictions regarding this feature, requiring applications compiled with ''obervability'' turned on.

== Backwards Compatibility ==
IBM has a long history building platforms that span a multi-decade backward compatibility at binary level. The AS/400 is no exception. Programs compiled on earlier platforms and/or versions can be transferred to a newer machine and usually run without hassle. 
Source code written with older releases of OS/400 usually compiles without any changes on newer platforms.

These features aren't of much interested on the first look. But it enables one to develop an application on an older system and run it on newer platforms. This could be seen as a base requirement for more free and Open Source Software: It's easier to acquire an older machine.

Unfortunately, transferring stuff from newer systems to older isn't that easy. The ''Savlib'' command writes stuff into a pre-created Save-File and records the release string of OS/400 where it was run. It is possible to set pre-set different values but the newer the utilized OS version, the newer the oldest possible compatibility level. V4R5 permits V3R2 as oldest release and select V4 releases. 
Transfers from old to new systems are painless, though.

== Single Level Storage ==
Since it's first incarnations the AS/400 creates a virtual 128 Bit address space for the upper OS layer and application programs. <ref>When looking a bit closer, the addresses are split into a 64 Bit actual ''address component'' and a 64 Bit numbered ''object type''. So, the claim of a 128 Bit address space aren't exactly wrong, but also not exactly right.</ref> This comprises physical memory and hard disk space.

A hard disk may be seen as a giant memory area mmap'ed into the address space of upper layer OS components. Swapping and Paging isn't done on the application layer as most conventional systems do, but on the address layer. Applications simply request contents from addresses and the layer below the OS called SLIC takes care of shuffling the data into RAM, should a page fault occur. Thus, page faults can occur also for data, not only for executables.

This concept also explains why the AS/400 platform lacks a conventional File System on it's disks. Since disks are essentially memory mapped into virtual memory space, everything visible is just an object at an address with certain properties. This allows to easily share these objects between requesting entities.

The advantage of this approach is the ability to do very fast context switches (if no or only a few page faults occur).<ref>According to Frank Soltis as written in his Books ''Inside the AS/400'', and ''Fortress Rochester''.</ref> This is the reason why even older machines with 100 % loaded CPU still have an astonishing fast response time when compared with common platforms of that era. If disk accesses are necessary for a context switch to take place, there's no notable speed difference to common platforms, though.

=== Disk Allocations ===
The usual way the system allocates space on secondary storage (aka: hard disks) is to spread objects over as many disks as possible. In modern RAID terminology, this is referred to as ''spindles'' (from the stack of rotating platters' axis), while IBM AS/400 documentation refers to the same concept as ''disk arms'': The actuator moving the read/write heads over the desired cylinder — a set of tracks — on the rotating platters.<ref>Once, disks with two actuators have been built, but these have been a development on the fringes and quickly vanished from the market.</ref>

This spreading of data has the same advantages and disadvantages as RAID 0:
* with increasing count of disk arms, the chance that a given data block is located on an idle drive increases and thus decreases latency through exploiting parallelism: the more applications run, the more data can be picked up from individual disks, the more overall processing work can be done.
* since data is located in the system just once, the failure of (at least) one disk has hard to predict ramifications. Objects become ''damaged'' because parts of them are no longer accessible.<ref>The necessity of a solid, and '''tested''' backup and restore concept is self-explanatory, but also emphasized in IBM documentation.</ref>

From early on, the concept of a dedicated I/O processor allowed for easy implementation of ''data mirroring'', to compensate for data loss because of a malfunctioning disk drive through redundancy.

Later, the well-known RAID-Levels have been made available through the availability of dedicated storage controllers.

=== Memory Pools ===
The described concept of the platform relying on paging as primary means to bring in data and code into the faster main memory for actual processing has some implications on main memory constrained machines. Once, RAM was extraordinarily expensive. Without precautions, it was easily possible to start many programs at the same time, each one competing for presence in RAM. When seriously overwhelmed with concurrent requests, this situation leads to [https://en.wikipedia.org/wiki/Thrashing_(computer_science) Thrashing], a situation where the machine is completely busy with paging activity, but does no useful work anymore because of competing tasks.

OS/400 introduced the concept of memory pools for that purpose. A memory pool mainly has these attributes:
* Size,
* Shared or Private,
* Maximum Activity Level.

''Pool'' can be more or less translated to ''RAM Cache'': What's already in the pool's memory is ''cached'', because it mustn't be handled by the paging logic.

==== Pool Size ====
The ''Size'' of a memory pool is just how much RAM is set aside for applications being directed to run in this pool. More RAM means more cache and less disk activity for shoveling work into RAM.

==== Shared or Private Pool ====
''Shared pools'' allow more than one group of applications to utilize a memory pool, while ''private pools'' are reserved for just one group. See ''Subsystems'' below for the explanation of this grouping. This brings in another consideration: The more pools one creates, the more unused memory is left over from excess memory partitioning. <ref>OS/400 has a function called ''performance adjustment''. This function periodically checks paging activity and adjusts memory allocations between pools, as well as the pool's activity levels.</ref>

==== Maximum Activity Level ====
The ''Maximum Activity Level'' of a memory pool is the overall count of applications which are eligible to actively ''run'' in a given pool in parallel. This eligible count only considers applications which require actual access to the CPU, but not ''sleeping'' ones, waiting for some application-external event. This setting reduces competition for memory amongst applications within that pool. But at the same time — to a lesser extent — overall competition for main memory, system-wide.

==== Pool Summary ====
It is important to consider that this competition for RAM is not limited to actual code being in main memory, but also for data. Heavy paging can be quite normal for a batch job reading through a huge database file, and only a minor brake on other applications running. As long as the application code stays in main memory, that application can run again as soon as more data arrives in main memory to be processed. Because batch applications (ideally) use a different memory pool than interactive applications, there is no competition for main memory for these two application ''classes'' being confined in their respective pools.<ref>There ''is'' a certain degree of competition for disk I/O, though. As long as both pools need to access data on a common set of disks, I/O latency for both pools will go up, and response time for interactive applications will degrade. Again, this latency increase should happen most often for paging of data, not application code.</ref>

Many Books have been written about ''performance tuning'' the AS/400 system. As you can see, there are many aspects to consider which values of these settings lead to the sweet spot of a machine doing maximum (batch) work while minimally affecting interactive users. Dynamic scenarios have been described where interactive users are not considered at non-office hours, giving batch jobs more memory and thus allowing faster processing.

In current reality, there are two groups of users, and both of them rarely need to consider the points outlined above:
* Hobbyists are most often the sole users of a system. Thus, overall system activity levels are low — most often, the machine idles.
* Professional users with current systems have RAM in abundance. In addition, the increasing ubiquity of solid state storage with its intrinsic lack of mechanical positioning latency boosts I/O throughput.

For both groups, the directions given in the [[Post-Install Optimizations]] article gives an almost perfect starting point for the self-adjustment of the system itself to balance into a good partitioning of RAM into existing shared pools.

=== Expert Cache ===
In short, this is a setting of a pool where the system itself decides the block size of data being read from disk and put into memory. Without this, transferred blocks are of a fixed size, thus increasing processing overhead. <code>CHGSHRPOOL PAGING(*CALC)</code> switches Expert Cache on for a given pool. On the other hand, smaller data transfers decrease the wait time until some other disk access can be satisfied. 
Usually the recommended setting is ''enabled''. Allow the system to adjust itself. Note: The default setting is ''disabled''.

=== Subsystems ===
A subsystem is a way to group application programs. Subsystems are defined by a subsystem definition object. This object allows for many attributes to be set, to prepare the desired run-time environment. See [[Subsystems]] for a more in-depth illustration about the underlying concept.

=== Running Application Programs: Activation and Activation Groups ===
Since programs are already existent as objects in the single level store memory space, there's no need to load them from disk as common OS' need(ed) to do. To actually run such an application program needs some housekeeping, though. Commonly a program needs a [[wikipedia:Stack-based memory allocation|Stack]] and a [[wikipedia:Memory_management#Dynamic_memory_allocation|Heap]] for variables and other internal data structures to be able to run. The AS/400 is no different in this case, although this stuff is buried very deep into the LIC's innards.

Actually starting a program to be run on an AS/400 is called ''activation''. This task creates necessary storage as outlined above and adds the program to to the job scheduling queue. This is also necessary to provide a properly isolated environment when multiple users start the same application.

Completely different compared to common platforms, it's possible to ''share'' some of this space between programs. This shared space is called an ''activation group''. That is, while creating a new program (by compiling and linking), one can tell the compiler/linker if the program is to be run in
* the default activation group, that contains most of the OS,
* the caller's activation group, to allow a more dynamic approach, or
* a new activation group that is to be created for every instance the program has,
* a common activation group with a programmer specified name.

As long as any program of any activation group is activated, so is the activation group. Data structures will be destroyed only when the last program terminates, or ''the job ends'', <ref>A job is defined as work that needs to be done by the system. Work can be done by a single program or mutiple.</ref> or when a group is explicitly deallocated with the RCLACTGRP program. For details see weblinks.

Sharing an activation group shares (amongst other data):
* Static variables,
* Open files and file pointer positions,
* and more…

There's a certain intersection of functionality between a common activation group and <code>fork()</code>ing an application on Linux/Unix platforms. Even if it is not exactly the same but maybe it gives you an idea. 
On OS/400, programs to share an activation group must exist as separate objects while on Linux/Unix all code is either linked to a monolithic program or uses additional code with the aid of ''shared libraries''.<ref>A concept that ''also'' exists on the AS/400. There, they are called ''service programs''.</ref>

== Standardized UI ==
The whole UI revolves mainly around forms and menus, accompanied by static text. The layouts of these screens are somewhat standardized. AS/400 screens are very recognizable because of this.

See also: [[About Green Screens and mouse-clickable UIs]].

== Predictable Command Naming ==
For experienced users who won't repeatedly navigate though nested menus, commands may be entered on the command line instead of menu numbers. These commands consist of two or more parts, built of abbreviated english words. Abbreviations often take place by omitting vowels and shortening the result to less or equal four characters. The first one being a ''verb'' and the second one a ''subject'', optionally followed by more building blocks.

A few examples may illustrate the previous statements:
; wrksplf
: Work with Spooled Files
; chgmsgq
: Change Message Queue Properties
; crtdspf
: Create Display File
; dltf
: Delete File
; dspmsg
: Display Messages (from Message Queue)

See also [[wikipedia:IBM i Control Language|IBM i Control Language]] and [[CL Tricks]].

== Outstanding Reliability ==
Software is a complex thing built by humans. Humans make errors. Thus, Software contains errors. This is an inevitable fact.

IBM managed to make OS/400 not bug free but caught most problems that lead to a complete crash of the operating system. There may be edge cases that are usually hard to spot.

Also, IBM built multiple measures against ''defective sectors on hard disks being catastrophic'' into the OS from early on. Since there is no classical file system, most often, read errors only affect one or more objects that can be easily restored from backup.<ref>You don't have a backup? Own fault! No backup, no pity.</ref>

Reliability is '''not''' the same as availability. Some tasks can only be done when OS/400 is running in a restricted state.<ref>In Unix this would be called Single User Mode, with not much more than ''init'' and a root-shell running.</ref> This includes but is not limited to a full system backup or certain hardware failure recovery procedures.

== Rapid Development ==
OS/400 comes with a set of tools and supportive facilities within the OS to ease development of application programs. Usually, development comprises of:
* Definition and creation of database tables, display forms and printer output,
* Writing code that references these files and shovels data just by issuing proper READ and WRITE (among other) requests to these files.

The mentioned files are typed in a format called ''Data Definition Specifications'' or ''DDS''. It provides data field definitions, field definition references between files, arbitrary placement of static text (not for database files) and a multitude of flags for content to be shaped to fit for the desired presentation. 
The ''Screen Design Agent'' program (<code>strsda</code>) provides a pseudo-[[wikipedia:WYSIWYG|WYSIWYG]]-interface for creating screen forms and menus. 
The ''Report Layout Utility'' program (<code>strrlu</code>) provides a pseudo-WYSIWYG-interface for creating layouts for printer output files.

Actual programming can be done in RPG, COBOL, and C/C++. Output of the compilers (called ''modules'') created by any of these languages can be linked together to create an actual program object or a shared library (''service program''). Any language may call functions of any other language as long as parameters have been defined to be compatible.

The compilable CL "shell"-script language and REXX-Interpreter help in easing traditional automation tasks on the command line level.

Programming is done within the ''Program Development Manager'' collection of programs (<code>strpdm</code>). The most used component is the ''Work with File Members'' application, <code>wrkmbrpdm</code>, to list source code physical file content. This in turn calls the ''Source Entry Utility'' (''SEU'') with the appropriate parameters for actual code writing/editing with the desired existing or new file member.

''SEU'' provides a linetype-aware form for RPG and DDS, easing the matching of the appropriate columnns. It can be invoked as usual: With <code>F4</code>.

See also: [[How to program an Application]]

=== Times they are a changin' ===
Today, development tasks are most often done on Windows PCs, with IBM provided tools, that pull a local copy of a source file to edit.

Also, since the late 1990's, IBM has been trying to establish Java as ''the'' language of choice, along with helper programs for shifting away from the old fashioned character based applications (''green screen'') to a pure web-browser based way of user's interaction with the system.

Also, '''the''' AS/400 Language, RPG, has been enhanced and modernised slowly but constantly. While most examples in this collection of knowledge are based on ''ILE RPG IV'', newer OS releases were accompanied by compilers allowing to escape the punched card appeal of RPG more and more. V5 introduced the possibility to write actual code (not definition statements, though) in a free form, while with some V7 all parts of a RPG program may be written without being forced to write statements at a certain position within a line. This generates a load of syntactical changes to be learned.

Examples of positional code are slowly vanishing from Internet Websites. Looking up how to do stuff in positional code is getting increasingly difficult. Asking around in mailing lists for positional code examples sometimes yield unhelpful and cynic comments. 
Still, many companies have old to very old code to be maintained that predates compilers allowing free syntax. Providing mainly positional RPG examples is supposed to help understanding this old way of writing RPG, while examples for newer techniques are easily found with an internet search engine of choice.

== Weblinks ==
* [https://www.youtube.com/watch?v=5pY6Xxptp9A IBM AS/400 The Best Architecture In The World 1992], Video at YouTube.
* [https://www.mcpressonline.com/programming/rpg/introduction-to-ile-rpg-activation-groups Introduction to ILE RPG Activation Groups], McPress online.
* [https://www.mcpressonline.com/operating-systems/ibm-i-os400-i5os/i5os-v6r1-upgrade-now-or-later i5/OS V6R1: Upgrade Now or Later?], MC Press Online, with some background information regarding code observability.
* [https://www.itjungle.com/2020/11/23/frank-soltis-discusses-a-possible-future-for-single-level-storage/ Frank Soltis Discusses A Possible Future for Single-Level Storage], IT Jungle, also explaining the benefits of SLS for task switching.

== Footnotes ==
<references />

[[Category: Basic Knowledge]]
[[Category: Musings]]

Apple SNA•ps

2023-01-07T03:55:24Z

Mlc: /* AS/400 configuration */

[[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 Software.

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 releases are known: version 1.1 from 1992, and version 2.0.1 from 1994.

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 [https://en.wikipedia.org/wiki/IBM_Systems_Network_Architecture#Logical_Unit_.28LU.29 LU]-Sessions (10, 40, or 70 for version 2.0.1),
* ''Client software'' for 5250 terminal- and printing services.

This article focuses on AS/400 and thus on 5250 connectivity.

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 [https://en.wikipedia.org/wiki/IBM_Systems_Network_Architecture#Physical_Unit_.28PU.29 SNA PUs]/LUs or [https://en.wikipedia.org/wiki/IBM_Advanced_Peer-to-Peer_Networking APPN]/[https://en.wikipedia.org/wiki/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 [https://en.wikipedia.org/wiki/IBM_3270 3270], and [https://en.wikipedia.org/wiki/IBM_5250 5250]). These allow Macs that are connected to the [https://en.wikipedia.org/wiki/AppleTalk AppleTalk] network (e. g. via [https://en.wikipedia.org/wiki/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 [https://en.wikipedia.org/wiki/Chooser_(Mac_OS) Chooser], or saved as text in a file. 
This was a way of making the Apple [https://en.wikipedia.org/wiki/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 [https://en.wikipedia.org/wiki/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 AS/400, and additional software for OS/400 to implement the AppleTalk protocol stack on the AS/400 as well. The implementation on the AS/400 corresponded to the SNA•ps gateway, so that no Mac was required as a gateway: the necessary software ran only on the AS/400.

== 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. The 3270 terminal client runs under System 6.0.7 with no errors, 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. It does not work 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 System 7 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.</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 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.

== 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
|-
|<s>Twinax</s><ref>5250 sessions over Twinax are not supported. Implementation was planned, but never was put into code before development ceased.</ref>
|Apple Koax/Twinax Card
|}

All of these cards feature their own 68000 CPU, and local memory. They conform to the ''Macintosh Coprocessor Platform'' specification. A 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.

<gallery mode="packed">
File:Apple-Token-Ring-NB-Compside.jpg|Apple Token Ring 4/16 NB Karte, front
File:Apple-Token-Ring-NB-Solderside.jpg|Apple Token Ring 4/16 NB Karte, back
File:Apple-Coax-Twinax-Compside.jpg|Apple Coax/Twinax Karte, front
File:Apple-Coax-Twinax-Solderside.jpg|Apple Coax/Twinax Karte, 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.

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.

== 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 freely. 
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)
| 
|-
|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''.<ref>This value is copied to the AS/400's controller description at the connection's first start by auto configuration.</ref>
|-
|Gateway Network Name
| 
|Generate yourself. You can probably use the name from the ''Sharing'' control panel.
|-
|Gateway Network Qualifier
|<code>DSPNETA</code>, local network ID (LCLNETID)
| 
|}

Other ''Characteristics'' settings are:
* Peer (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: ''PASSTHRU''
| 
|Corresponds to the ''SNA•ps Access'' Control Panel setting on the clients
|-
|''Network LU Name''
| 
|Desired name for the gateway on the APPN network<ref>Only CAPS, may not start with a number, and may only contain these special chars: #$_</ref>
|-
|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
| 
|''*'' (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
|-
|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 is 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.

=== Screen shots ===
These screen shots 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 ''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 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.

== Notes ==
<references />

== 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)

[[Category: Software Configuration Guide]]
[[Category: System Administration]]

User:Mlc

2022-07-26T22:24:04Z

Mlc: Created page with "Götz @: 3rz.de"

Götz @: 3rz.de