Notes on Installing Hercules, Cygwin, and MUSIC/SP -------------------------------------------------- Date written: Oct 30, 2004 Author: Dave Edwards Last updated: Aug 7, 2007 (c) Copyright by Dave Edwards 2004-2007. All rights reserved. Contents: 1. Introduction 2. MUSIC/SP background and history 3. References and resources 4. Download the files you will need 5. Install Cygwin on Windows 6. Install Hercules 7. Set up MUSIC/SP under Hercules 8. Using MUSIC/SP - - - - - - - 1. Introduction --------------- These notes give detailed, step-by-step instructions for installing Cygwin and Hercules under Windows, and setting up MUSIC/SP to run under Hercules. The Hercules mainframe emulator is a powerful tool, but setting it up is not particularly easy. To use it on Windows, you may also need to install Cygwin. The interaction between Hercules and Cygwin is not very clearly explained in the Hercules documentation. There is a lot of helpful information available on the web, but I found that it tends to be scattered among several sites, and there is not much info about running the MUSIC/SP operating system (see the section on MUSIC/SP background and history) under Hercules, and how Hercules compares with the Sim390 mainframe emulator. (NOTE: Since I originally wrote these notes, later versions of Hercules have become available, and it is possible to run it on Windows without Cygwin.) These notes are my attempt to help the new user through the steps needed to set up Cygwin and Hercules under Windows, and set up and run MUSIC/SP under Hercules. My experience is with Windows, but much of the info here (excluding Cygwin) also applies to Hercules on Linux. It definitely *is* possible to run MUSIC/SP under Hercules on Linux. The same MUSIC volume files work in both Windows and Linux environments. Hercules under Linux requires Linux kernel 2.2.x or higher (e.g. Red Hat Linux 6.1 or higher). Disk space requirements (approximate): Downloaded files: 30 MB (more if you include more Cygwin packages) Cygwin and Hercules: 60 MB (more if you include more Cygwin packages) MUSIC/SP demo system (version 6.2): 150 MB Total: 240 MB My system: Pentium 4, 256 MB RAM, Windows 2000 Professional SP4. How to reach me: See the "Contact the author" page at: http://www.geocities.com/sim390 Or post a message to the H390-music discussion group: http://groups.yahoo.com/group/H390-music/ It is possible to run the MUSIC/SP operating system on a real IBM 360/370/390 mainframe (either stand-alone or under VM), or under either the Sim390 or Hercules mainframe emulator. Earlier versions (5.x) of MUSIC/SP use a 370-mode nucleus. A more recent version (e.g. the 1-volume demo system provided with Sim390) uses an ESA/390-mode nucleus. Sim390 supports only ESA/390 mode. Hercules supports both modes, controlled by the ARCHMODE statement in the configuration file. The ESA/390 version of MUSIC/SP is also sometimes referred to as MUSIC/ESA. Comparing Hercules and Sim390 emulators: One of the strengths of MUSIC/SP is its support for TCP/IP protocols, via socket calls. For example, it can act as a web server, an FTP server, an FTP client, and a TN3270 (telnet) client. It can send email using the SMTP protocol. However, TCP/IP in MUSIC/SP requires either a VM environment (with the TCPIP virtual machine providing the TCP/IP support) or the Sim390 emulator (which does not use VM but which emulates VM's TCPIP virtual machine and the IUCV protocol used for communication between MUSIC and the TCPIP virtual machine). When MUSIC/SP is run under Hercules, without VM, Hercules itself currently has only very limited support for the IUCV instruction (opcode B2F0): in Problem State it gives PI 1 (Invalid Opcode); in Supervisor State it gives Condition Code 3 to indicate that IUCV is not supported. Furthermore, since the license-free VM/370 available for Hercules does not support TCP/IP, it is currently not possible to run MUSIC/SP TCP/IP applications under Hercules. If you want to use MUSIC/SP as a web or FTP server, or transfer files to/from MUSIC using FTP, you need Sim390. On the other hand, Hercules emulation is faster, and supports more devices, such as emulated tape drives. 2. MUSIC/SP background and history ---------------------------------- MUSIC/SP (Multi-User System for Interactive Computing / System Product) is an operating system, similar in some ways to Unix, which was developed and marketed by McGill University (Montreal) in the years 1970 to 2002. It runs on an IBM mainframe (360/370/390), either stand-alone or under VM. It has roots in the early IBM time-sharing system called RAX, which was one of the first (perhaps *the* first) general-purpose interactive systems to run under System/360. For example, I have paper copies of the IBM manuals "System/360 Remote Access Computing System (RAX) (360A-CX-17X) User's Manual" H20-0354-0 1967, "System/360 Remote Access Computing System (RAX) (360A-CX-17X) Version 3 Operations Manual" H20-0355-1 2nd ed. 1968, and "System/360 Remote Access Computing System (RAX) (360A-CX-17X) Version 4 System Manual" GY20-0101-2 3rd ed. 1968. People involved in the development of MUSIC and MUSIC/SP include Roy Miller, Alan Greenberg, Wilf Mandel, Dave Edwards (starting 1971), Kevin McNamee, Don Farnsworth (IBM), Dean Daniele (IBM), Glen Matthews, Pierre Goyette (Pierre wrote PCWS and the TN3270 clients Net3270 and TCP3270, later to become Hummingbird's HostExplorer product), Simon Fulleringer (PANEL), Linda Chernabrow, Frank Pettinicchio, Earl Lindberg, Simone Spiller, Kathy Wilmot (documentation), Shirley Knight, David Thorpe, Gerald Ratzer, Harry Williams (Marist College), Dave Juraschek (Northern Virginia Community Colleges), Christian Robert (Ecole Polytechnique, Univ of Montreal), Mike Short (PL/1 (F) and other compilers). My apologies if I have left anyone out - send me a note. In 1967, McGill University installed its first System/360 computer, and began running RAX as its first interactive time-sharing system. In the late 1960s, McGill took over the RAX code base and began heavy modifications and enhancements to it. McGill distributed its version of RAX to a few other universities, some of which, notably Boston University, contributed significant mods. In 1972, McGill, in an agreement with IBM, renamed the heavily modified RAX system to MUSIC (McGill University System for Interactive Computing), and IBM began marketing it for McGill as a for-charge IUP (Installed User Program). MUSIC IUP went through version numbers 1.0 to 5.2 (1983). The name MUSIC/SP (the MU now stands for Multi-User rather than McGill University) dates from about 1985, when MUSIC/SP 1.0 was released. McGill Systems Inc. (MSI), a corporation wholly owned by McGill, was formed for marketing and support purposes. In 1988, McGill, through MSI, began distributing MUSIC/SP independently of IBM. At its peak in the early 1990s, MUSIC/SP had over 200 customers, mostly colleges and universities in North America, but including several in Europe, South America (notably Brazil), and Asia (Hong Kong, Japan), and some commercial sites (notably the Financial Research Institute in Montreal). The support group had 12 staff members. There was an active users group (MUG), with yearly meetings. In 2001, the MUSIC/SP office was closed and its remaining staff members were assigned to other duties at McGill. In 2003, McGill officially ended support and development of the MUSIC/SP product, but some unofficial development (mostly by Dave Edwards) continued, and the MSI web site and FTP server were still operating. At that time there were about 7 customer sites. In 2004, McGill stopped running its large IBM mainframe and production MUSIC/SP systems, although it continued to run a P/370 machine. In 2007, the MSI web site and FTP server (domain musicm.mcgill.ca) were shut down, but much info is still available on Dave Edwards's staff web page at McGill and on the Sim390 home page. In July 2000, with the impending shutdown of McGill's mainframe, Dave Edwards began writing an ESA/390 mainframe emulator, called Sim390, with the goal of running MUSIC/SP on an off-the-shelf Windows machine, with very easy installation and minimal system requirements. In 2001, an early demo version of Sim390, with local 3270 support but no TCP/IP support, was distributed to a few people. In 2003, TCP/IP support was completed, including sockets and remote 3270 log-in from TN3270 clients. A small 1-volume (3370 FBA disk) MUSIC/SP demo system was made available in January 2004, for personal non-commercial use. Note that Sim390 was written from scratch by Dave Edwards, as a personal project separate from his McGill job. It is not based on any Hercules source code. 3. References and resources --------------------------- You are advised to review the following web pages before starting installation. MUSIC/SP: http://webpages.mcgill.ca/staff/group3/dedwar1/web Sim390 mainframe emulator: http://www.geocities.com/sim390 Hercules home page: http://www.hercules-390.org/ Hercules Frequently Asked Questions: http://www.hercules-390.org/hercfaq.html Hercules config file: http://www.hercules-390.org/hercconf.html Cygwin: http://www.cygwin.com Installing Cygwin: http://www.bsp-gmbh.com/hercules/herc_cygwin.html Jay Moseley's site: http://www.jaymoseley.com/hercules/ Hercules New User Documentation Effort: http://www.bsp-gmbh.com/hercules/ http://www.kiyoinc.com/hercdoc.html Other software for Hercules: http://www.ibiblio.org/jmaynard/ Hummingbird HostExplorer 3270 and VT terminal emulator (tn3270 client): http://connectivity.hummingbird.com/products/nc/he/index.html QWS3270 free tn3270 client, version 3.2f of June/1995: http://www.geocities.com/sim390/qws3270.zip c3270, x3270, wc3270 free tn3270 clients: http://x3270.bgp.nu/ http://www.geocities.com/SiliconValley/Peaks/7814 wc3270 is the version of c3270/x3270 for Windows. The easiest way to install it is to download and run the setup.exe file. Discussion groups: http://groups.yahoo.com/group/H390-music/ http://groups.yahoo.com/group/hercules-390/ http://groups.yahoo.com/group/H390-VM/ 4. Download the files you will need ----------------------------------- - To run Hercules on a Windows machine (I used Windows 2000 Professional), you need the Cygwin software, which provides a partial Unix-like environment under Windows. Go to www.cygwin.com and click on the "Download" icon, which downloads the latest copy of Cygwin's setup.exe program (about 263 K). Save it somewhere on your hard disk, e.g. in directory c:\download\cygwin. Running setup.exe does the actual download and install of the Cygwin software. (NOTE: Later versions of Hercules for Windows do not require Cygwin, but when I wrote these notes, Hercules was 3.01 and needed Cygwin.) At the time I downloaded and installed Cygwin, setup.exe was version 2.427, and Cygwin was version 1.5.11. When you run setup.exe, you must choose one of 3 options: (1) Install from Internet, (2) Download from Internet, or (3) Install from Local Directory. Normally you choose (1), which downloads Cygwin to a local directory on your hard disk, then installs it. If you want to download to one machine but install Cygwin on another machine, you can use option (2) on the first machine, then transfer the resulting local directory to the 2nd machine (e.g. via a CD or some other removable media), and use option (3) on the 2nd machine. This is useful, for example, if you have a high-speed connection at the office (1st machine), but only a slow dial-up connection at home (2nd machine). The directory where you store the downloaded files (e.g. c:\download\cygwin) is referred to as the "local package directory". The directory where you actually install Cygwin is called the "root directory". I recommend that you specify c:\cygwin as the root directory, since the Hercules install uses that name by default. Other options I specified: Install for all users; Default Text File Type = Unix. The root directory becomes the root (/) for commands entered on the Unix command line in Cygwin. For the download, you must choose a mirror site. It should be geographically as close to you as possible. Since I am in Canada (Montreal), I chose http://mirror.cpsc.ucalgary.ca, which seems to be quite fast. You must also select which "packages" (groups of Cygwin software) to download. Depending on what you select, the total download size may be a few MBs, or several hundred MBs. For selection purposes, packages are grouped into "categories". Some "base" packages which are always needed for Cygwin are automatically included. The Hercules web site says that you also need the libintl-2 package, which is in the Libs category. So, in the Select Packages screen in setup.exe, leave all the categories as "Default" (clicking on that word or on the circle-with-2-arrow-heads icon beside it toggles it to "Install"), click on the + beside the Libs category, look for the libintl-2 package, and click on its "Skip" word. The word "Skip" then changes to a level number. Finally, click on the Next button. For me, the resulting download files in the local package directory totalled about 11 MB. (If you are using the Install from Local Directory option, you want to install all packages contained in the local directory, so click on the word "Default" on the "+ All" line, which toggles the word to "Install", then click on Next.) If you want to build Hercules from source files, or do things in Cygwin other than just run Hercules, you may need to select more packages. Note: Be careful when specifying the local package directory; if you enter the wrong directory name, setup.exe may abort with an Application error. The Cygwin install process creates the root directory c:\cygwin if it does not already exist, and creates several files and subdirectories. The install step takes a couple of minutes. For me, the resulting total size of c:\cygwin was about 39 MB. - Download the Hercules pre-built binary for Windows, from the Hercules home page. For example, see the section "Installing on Windows" in http://www.hercules-390.org/hercinst.html. When I did this, the current (stable) Hercules version was 3.01, and I downloaded file hercules301-i586f.exe (1.6 MB), which is a self-extracting archive. "i586" indicates the binary is for Pentium. Another alternative is "i686", which is for Pentium Pro/Pentium II and above. "f" in the filename stands for "Fish optimized threads" version, which is recommended over the "p" (standard POSIX threads) version. (NOTE: Later versions of Hercules are now available, and it is possible to use it on Windows without Cygwin. See the Hercules web site. Version 3.01 still works well for my purposes.) - You will need a tn3270 (telnet 3270) client program, to connect to your MUSIC/SP system and sign on as a 3270 terminal. There are many good tn3270 clients available, including: (a) Hummingbird's HostExplorer (not free): see the link in the References section. It can also be used (in VT220 terminal mode) as a telnet client for connecting to Hercules as the operator console (3215 device) for MUSIC/SP. HostExplorer is an excellent, full-featured product, and is highly recommended. (b) QWS3270 (free), written by Jim Rymerson, Queen's University, Kingston, Ontario. See the links in the References section. The keyboard mapping for QWS3270 is: Clear: Ctrl+C or Keypad + PA1: Alt+F1 PA2: Alt+F2 PF13 to PF24: Shift+F1 to Shift+F12 New Line: Ctrl+N Erase EOF: Ctrl+E or Keypad - PF7: PgUp or F7 PF8: PgDn or F8 Note: QWS3270 supports 3278 models 2 (24x80), 3, (32x80), and 4 (43x80). If you have a problem with the "button line" being displayed in the middle of the model 3 or 4 screen, edit the file qws3270.ini and set: termtype=IBM-3278-4 BUTTON LINE 1=0 BUTTON LINE 2=0 After getting the MUSIC/SP logo screen, you may have to press Enter twice (instead of once), to get the MUSIC sign-on screen. The free QWS3270 supports only 4 colours. (c) You can use MUSIC/SP running under Sim390 as a tn3270 client. First, sign on to MUSIC/SP using a local 3270 session, then use the command "tn3270 hostname portnum", as explained in http://www.geocities.com/sim390/tn3270.txt This tn3270 client supports four screen sizes and 16 colours. (d) The open-source, free x3270, c3270, and wc3270 tn3270 clients. x3270 and c3270 run on various systems including Linux. wc3270 is the version for Windows. - Download the FBA volume file, musicxd.vol, for the 1-volume demo MUSIC/SP system, from the Sim390 site. Originally it was contained in file sim390dm_a.zip (about 4 MB) along with Sim390, and musicxd.vol was 92 MB. Later versions (6.2 and higher) package it separately from Sim390. For example, 6.2 is in sim390dm_b.zip (about 11 MB), and musicxd.vol is larger (160 MB). Use WinZip (or equivalent) to extract the files from a compressed .zip distribution file. 5. Install Cygwin on Windows ---------------------------- Installing Cygwin is done as part of the setup.exe program, as described in the preceding Download section of these notes. It is strongly recommended that you specify c:\cygwin as the root directory. 6. Install Hercules ------------------- Execute the self-extracting archive file hercules301-i586f.exe that you downloaded. This opens the unzip dialog window. Leave the "Unzip to folder" setting as the default (c:\cygwin\usr\local). Leave the option "Overwrite files without prompting" selected. Click on the Unzip button. Initially the target directory c:\cygwin\usr\local, as set up by Cygwin, is empty except for 3 empty folders: bin, etc, lib. Hercules writes several files to these directories, including the Hercules emulator itself c:\cygwin\usr\local\bin\hercules.exe, and creates some new directories (some of which are empty). The man directory contains documentation. The share\hercules directory contains some HTML files from the Hercules home page, including release notes and documentation on the Hercules configuration file. Start at index.html. Total size of c:\cygwin\usr\local is about 4.3 MB. It is possible to run Hercules from the Cygwin Unix command-line prompt (obtained by starting Cygwin, e.g. double-click on the Cygwin icon on the Windows desktop). However, I find it easier to run Hercules outside of Cygwin, by executing a .bat file from the a Windows Command Prompt window. The critical file that hercules.exe needs from Cygwin is c:\cygwin\bin\cygwin1.dll. The .bat file can set up the required PATH, and execute hercules.exe with the configuration file that you need for whatever operating system you will be running under Hercules. For example, to run MUSIC/SP under Hercules, I created a directory c:\herc\hercmus, which contains the file hercmusd.bat for starting Hercules, the configuration file hercmusd.cng for the demo 1-volume MUSIC/SP system downloaded from the Sim390 site, and the FBA volume file musicxd.vol that contains MUSIC/SP. NOTE: I used the extension .cng for Hercules config files, rather than the usual .cnf, since my Windows considers .cnf files to be "SpeedDial" shortcut files used by the Windows Phone Dialer application. The actual extension does not matter to Hercules. The file hercmusd.bat contains something similar to this: rem Use this .bat file to start Hercules c: cd \herc\hercmus set path=c:\cygwin\usr\local\bin;c:\cygwin\bin hercules -f c:\herc\hercmus\hercmusd.cng rem Restore (most of) normal PATH: set path=c:\misc;C:\WINNT\system32;C:\WINNT For the file hercmusd.cng, see the section on setting up MUSIC/SP. Then, to start the Hercules emulator and load an operating system: (1) Open a Windows Command Prompt window. You can do this by Start / Run / cmd.exe (on Win 95 or 98, use command.com). (2) Type: c:\herc\hercmus\hercmusd.bat (3) Connect a telnet client to the Hercules console port, to act as the operator console for the operating system you will be IPL'ing. For telnet, see the section on setting up MUSIC/SP in these notes. The port number is defined in the Hercules config file by the CNSLPORT statement. (4) On the Hercules emulator screen, enter the command: ipl xxx where xxx is the device address of the disk volume containing the system to be loaded. E.g. for MUSIC/SP: ipl 201 The device addresses are defined in the Hercules config file. (5) Do whatever is necessary on the operator console (the telnet client screen) to complete the IPL of the operating system. E.g. for MUSIC/SP, press Enter in response to the message "M077 Enter operator id or special options or HELP". MUSIC/SP may take a few seconds to load. (6) To sign-on as a MUSIC/SP user, via an emulated 3270 terminal, connect a tn3270 client to the Hercules console port. You should see the MUSIC/SP logo screen. Press Enter to get the sign-on screen. The userid to enter is $000, and the password is initially music (you should change it to something else by the MUSIC/SP newpw command). See the following sections on MUSIC/SP in these notes. The port number is defined in the Hercules config file by the CNSLPORT statement. You can have several tn3270 sessions going at the same time. At this point, you have at least 3 windows: one for the Hercules emulator (the Hercules control window), one for the operator console (telnet client), and one or more 3270 user sessions (tn3270 clients). To shut down MUSIC/SP, enter the command stop on the operator console. To shut down Hercules, enter the command exit in the control window. 7. Set up MUSIC/SP under Hercules --------------------------------- You can use the following Hercules config file, hercmusd.cng, for the demo 1-volume MUSIC/SP system: * Hercules sample config file for 1-vol demo MUSIC/SP system. * First, start the Hercules emulator, specifying this config file. * Then: (1) Connect telnet client as console, port 3270 - see notes below. * (2) ipl 201 (as a Hercules command). * (3) Press Enter on telnet console, to complete MUSIC/SP IPL. * (4) Connect tn3270 client (for MUSIC/SP sign-on), port 3270. * To exit Hercules: exit (as a Hercules command) ARCHMODE ESA/390 CPUSERIAL 000611 CPUMODEL 3090 CPUVERID FD MAINSIZE 16 XPNDSIZE 0 NUMCPU 1 NUMVEC 0 SYSEPOCH 1900 * Time zone: use -0400 for EDT, -0500 for EST, etc. TZOFFSET -0500 CNSLPORT 3270 * Card reader: 00C 3505 * Operator console, Telnet client connection (connect before IPL): * For Hummingbird HostExplorer: VT220; Keybd Opt: Send Enter as CR-LF; * Preferences: Local Echo; VT model options: VT 220, 8-bit. * You can also use the Windows telnet client (telnet.exe). 00F 3215 * User terminals, tn3270 client connection: * For Hummingbird HostExplorer: e.g. 3279 model 4 ExtAttr. * You can also use other tn3270 clients such as QWS3270. 0F0-0F7 3270 * FBA-512 disk (copied exactly from Sim390 FBA volume file): 201 3370 c:\herc\hercmus\musicxd.vol You can change some of the settings in the config file, if you like, such as the main storage size (MAINSIZE), the CPU serial and model number, the time zone (TZOFFSET), and the console TCP/IP port number (CNSLPORT). You can add more 3270 devices, or more disk volumes. You can experiment with adding tape devices, printer, card reader, and card punch; MUSIC/SP supports such devices, but can run without them. See the MUSIC/SP on-line manuals for device details. However, do not change the ARCHMODE statement, since the MUSIC/SP demo system (level 6.x) requires ESA/390 mode. Earlier versions (5.x) of MUSIC/SP need ARCHMODE S/370. MUSIC/SP defines its own time zone and whether or not Daylight Saving Time is in effect, in its file $tcp:tcpip.config . Ideally that file and the Hercules config file should match. This is not particularly important unless you allow other people to sign on to your MUSIC/SP system or allow them access to it as a web or FTP server. The nucleus of the demo system can accept FBA disk volumes on device addresses 201 thru 206 and 301 thru 306, tape devices on 100 and 101, and 3270s on 0F0 thru 0FF. Unit record devices are 00F (console), 00E (printer), 00C (reader), 00D (punch). Telnet client: Hercules uses a telnet client, connected to its console port, as the 3215 operator console for MUSIC/SP. Not all telnet clients seem to work for this. I have found that the best solution is to use Window's telnet.exe program, running in a Command Prompt window. Start it by the command telnet, with no parameters. You can then enter various subcommands. Enter the ? or help command for info. You may have to use the display, set, and unset commands to adjust the default settings. Local echo should be on. Both CR and LF characters should be sent at line end. Output of the display command should be similar to the following: Escape Character is 'CTRL+]' WILL AUTH (NTLM Authentication) LOCAL_ECHO on Sending both CR & LF WILL TERM TYPE Preferred Term Type is ANSI To connect to Hercules, enter the command: open localhost nnnn where nnnn is the port number specified on the CNSLPORT statement in the Hercules config file, after starting Hercules. To shutdown the telnet client, enter Ctrl+], then the quit command. NOTE: You can enlarge the Command Prompt window and allow more scroll-back, by clicking on the icon in the top left, and choosing Properties. In the Layout tab, specify (for example) 300 as the Height for the Screen Buffer Size (scroll-back buffer), and Height 43 for the Window Size. Do this before starting telnet. If you use Hummingbird's HostExplorer as the telnet client, specify terminal type VT 220 in the Open Session dialog window. You may also have to adjust some settings in Config or Preferences: Local echo, 8 bit, Send Enter as CR LF. Tn3270 client: For user sign-on, Hercules uses a tn3270 (telnet with 3270 negotiation) client. Various tn3270 clients can be used. See the Download section of these notes. Since tn3270 is a TCP/IP protocol, you can connect from a remote machine, if your network is set up to allow this. The default telnet port is 23, but you should use the port number you specified on CNSLPORT in the Hercules config file. MUSIC/SP supports 4 3270 screen sizes (I usually use 43x80) and up to 16 colours. If you use Hummingbird's HostExplorer, specify Terminal Type 3270 and Terminal Model 3279 ExtAttr (extended attributes). If you use QWS3270, you may have to press Enter twice (instead of once), to get from the MUSIC/SP logo screen to the sign-on screen. MUSIC/SP DASD (disk) volumes: I recommend that you use the 3370 disk device type (FBA 512-byte blocks) for MUSIC/SP volumes under Hercules. MUSIC/SP supports both Count-Key-Data DASD (disk) devices (2314, 3330, 3350, 3340, 3375, 3380, 3390, 9345) and FBA-512 (Fixed Block Architecture) disks (3370, 9332, 9335). Sim390 supports only FBA-512 disks. Hercules supports both types, but it is simplest to use FBA-512 (3370), since then the same volume file (a Windows file) can be used with both emulators, and in fact a volume can be shared (read-write by one emulator, read-only by the other). The file format for an emulated FBA disk volume is very simple: a sequence of 512-byte blocks, with no other control info. Block 0 of the FBA volume is at byte displacement 0 in the Windows file, block 1 is at byte displacement 512, etc. The size of the FBA volume (number of 512-byte blocks) is determined by the size of the Windows file, which can be up to about 4 GB. However, the max usable size for a MUSIC/SP FBA volume is about 1 GB (2,097,152 blocks), because some control blocks use a 16-bit track number, where 1 (logical) track = 32 512-byte blocks. The MUSIC/SP utility program INITFBA can be used to initialize an FBA volume (write a volume label and create the VTOC - Volume Table of Contents). An FBA volume file can be enlarged after it is created, since the VTOC does not define the size of the volume; for example, you can use the program wipezero.exe (available from the Sim390 site) to extend a volume file; specify the existing size of the file (or e) as the byte displacement for zeroing. MUSIC/SP can use multiple volumes, and the Save Library (where most user files are stored) can extend over several volumes. Additional MUSIC/SP configuration: Once you have MUSIC/SP up and running, and have signed on as the administrator (userid $000), there are some other one-time things you may wish to do. - Use the newpw command to change the administrator password. You must enter the command /vip on before newpw, in order to enable the VIP privilege. Id $000 has all privileges, but the VIP privilege is not enabled by default, for safety reasons. - Since MUSIC/SP TCP/IP applications are not supported under Hercules, you should disable the INETD background task (BTRM). Otherwise it tries to start every few minutes, producing error messages on the console. From the MUSIC *Go prompt, enter the following commands: vip on codupd change cfmn003 autoprog() end console cancel 3 (Then press F3 to exit from Console) The original setting was: autoprog($tcp:inetd) To re-enable INETD at some later time, enter from *Go: vip on codupd change cfmn003 autoprog($tcp:inetd) end console reset 3 (Then press F3 to exit from Console) NOTE: If userid $000 starts with the Admin menu, you can exit to *Go mode by pressing F3. To return to the menu, enter: admin - You can change the info text displayed by the sysdate and ver commands by editing the file: $gen:mus.hostinfo - You can restore various groups of files, downloadable as MUSIC/SP archive files (.arc or .mfarc) from the Sim390 and MUSIC/SP sites. See the instructions in the information files there. The archive file for an update is usually packaged within a .zip compressed file. Follow all instructions carefully. These files contain bug fixes, enhancements, additional compilers and utilities, etc. General rules for restoring these files: (a) Restore the archive files in the order they are listed on the web site, i.e. in date order. This is because some archive files contain a newer version of MUSIC/SP files contained in an earlier archive file. Make sure you have enough free space in the MUSIC/SP Save Library before restoring the files; use the LIBSPACE command to check. (b) Use the following options in the MFREST restore utility: ALL=T,REPL=T,SETUI=T (c) Read the notes for each archive file in the accompanying text file. Some files require that you execute some files after the restore, in order to update system components such as members in the Load Library. (d) After the restore, you can delete the achive file if you wish, to save space in the Save Library. Note: The archive files are normally transferred to MUSIC/SP by using FTP (File Transfer Protocol). But FTP does not work under Hercules, since TCP/IP is not available. One solution is to first set up the MUSIC/SP demo system under Sim390 (which supports TCP/IP), restore all the archive files to it, then use the resulting .vol file as the basis for the Hercules MUSIC/SP system. Other solutions exist. See the web site. - Other settings (mostly for TCP/IP) can be changed by editing the files $tcp:tcpip.config and $tcp:inetd.ports. You need to re-IPL MUSIC/SP for these changes to take effect. - You can add more userids for signing on to MUSIC/SP, by using the CODUPD (Code Table Update) utility. - To update the system catalog, change the nucleus or the MUSIC/SP device configuration, and do other advanced functions, please refer to the MUSIC/SP manuals. Use the "manx" command to access the on-line manuals. The MUSIC/SP web site has printable versions (slightly out of date) of some of the manuals. The Sim390 home page has additional technical info about MUSIC/SP that you may find useful. The Admin menus (invoked by the admin command on the $000 userid) can be used to display and configure various settings in MUSIC/SP. 8. Using MUSIC/SP ----------------- Most of what you need to start MUSIC/SP and sign on as a user is covered in the preceding sections of these notes. To terminate a user session (sign off), use the off command. To shut down MUSIC/SP, enter the stop command on the operator console. This terminates all user sessions, closes the accounting file, and enters disabled wait state. A 3270 user session in MUSIC/SP operates in one of 2 modes: (1) Line mode (also called *Go mode): The top part of the screen is used for displaying command output, and there is a single input line near the bottom of the screen for entering the next command. To advance to the next screen of output when the "More..." indicator appears in the lower right corner, press Enter or PA2. (The actual key or key sequence for 3270 functions such as PA1 and PA2 depends on the particular tn3270 client you are using.) You can interrupt output or job execution by pressing PA1 to get **Attn** mode, then enter /can or /skip n (skip n lines of output) or ? (display job time). In *Go mode, but not in **Attn** mode, the leading / on commands is optional. For example, edit and /edit are equivalent. In *Go mode, various PFn (Fn) keys have predefined actions; type showpfk to see the definitions. For example, normally F12 recalls the previous command entered. When typing a MUSIC/SP command into the command area of the Editor (or similar applications such as Admin, Help, View), you may need to include the leading "/", for example if the command has the same name as an Editor command. (2) Full-screen mode (also called Panel mode): The entire 3270 screen is controlled by the application program that is running. Input fields can be located at various positions on the screen. Examples are the Editor screen (invoked by the edit command), the Admin menu screens (invoked by the admin command), and the Help facility (invoked by the help command). In full-screen mode, most 3270 actions keys (like PFn) are controlled by the application. An exception is PA2, which is used for control of Multi-Session (add a new session, or go to the next or previous session in the ring) and for printing the screen. Full-screen applications can be designed and programmed using the Panel facility; currently, Panel applications can use only the top 24 lines of the 3270 screen. Here are some of the important commands in MUSIC/SP. Some of these commands requires privileges and work only on the administrator id ($000) or a similar privileged id. edit filename - Edits a file. view filename - Views a file (no changes to the file). attrib filename - Displays attributes of a file. library - Displays a list of filenames matching a specified pattern, optionally with attribute info. It is similar to the dir command, except it crosses directory boundaries. Type "help library" for details. For example, to list all files contained in the userid $TCP, use the command: lib $tcp:* x To list all files on the system which contain "abc" in the name: lib *:*abc* help - Invokes the Help facility (on-line help for commands, utility programs, library subroutines, etc.) Examples: help help help help edit man - On-line manuals (for non-administrators). manx - All on-line manuals. admin - Invokes the Admin menus, for administering the system. Administration can also be done by entering commands in *Go mode. Not all Admin menu items are enabled in the Demo version of MUSIC/SP. console - Displays the operator console messages, and allows MUSIC/SP operator commands to be entered. whoson - Displays the tasks currently running. Each task is associated with a TCB (Task Control Block or Terminal Control Block). Tasks of type BTRM are background tasks. Tasks shown as OFF or *GO are not currently running. sstat - Displays system status info. The screen is updated automatically every few seconds. Press F3 to exit. ustat - Displays job and user session status info. The screen is updated every few seconds. Press F3 to exit. output - Invokes the Output facility, which displays job output files. For example, the output of the print command is sent (at least initially) to the Output facility. sysdate - Display date, time, system version, and other info. mail - Starts the Mail Facility, which can be used to send email messages between users, internally within a MUSIC/SP system. (When MUSIC/SP is run under VM, the Mail Facility can send email to, and receive it from, any Internet email address, using VM's SMTP.) vip on - This command enables the VIP (super user) privilege, if the user has the right to this privilege. At the start of each login session, VIP is off. You need to turn it on before using some commands such as PROFILE, NEWPW, and CODUPD. codupd - Invokes the Code Table Update utility, which is used to display, change, add, and delete user ids. A user id is needed to sign on to MUSIC/SP, and files are organized by user id. (In some older documentation, a "userid" is called a "code" or "user code".) profile - Invokes the user version of Codupd. Allows a user to display and change various settings for his/her userid. ucb - Displays disk and tape devices currently defined in the MUSIC/SP nucleus. devb - Displays the table of Device Blocks, used by MUSIC/SP for managing ESA/390 i/o. cdump - Interactive display of memory (main storage). dskdmp - Displays disk volume info. For example, to display the data sets on volume MUSICX, enter the subcommand: listv,v='musicx' libspace - Displays space usage info for the Save Library. Most user files are stored in the Save Library, which is composed of several data sets named SYS1.MUSIC.ULnn, where nn is a sequence number, and the index data set SYS1.MUSIC.UIDX. Additional info about MUSIC/SP can be found on the MUSIC/SP and Sim390 web sites, and on the H390-music Yahoo discussion group. See the References section of these notes. - - - - - - -