UCLA/IPC-370 Installation (IPCINST) V1.410 University of California Office of Academic Computing 5628 Math Sciences Addition Los Angeles, California 90024 Michael Stein OAC Systems CSYSMAS@OAC.UCLA.EDU Copyright Regents University of California, 1984, 1985, 1986. DISCLAIMER __________ The University of California requires the following disclaimer concerning all distributed programs: Although this program has been tested by its contributor, no warranty, expressed or implied, is made by the contributor or the University of California, as to the accuracy and functioning of the program and related program material, nor shall the fact of the distribution constitute any such warranty, and no responsibility is assumed by the contributor or the University of California, in connection therewith. 06/21/91 17:40 UCLA/IPC-370 Installation (IPCINST) Page i CONTENTS ________ User Modifications . . . . . . . . . . . . . . . . . . . 1 UCLA/IPC-370 description . . . . . . . . . . . . . . . . 1 Planning and Installation . . . . . . . . . . . . . . . . 2 Prerequisites . . . . . . . . . . . . . . . . . . . . 2 Installation . . . . . . . . . . . . . . . . . . . . . 2 Distribution Tape Format . . . . . . . . . . . . . 2 Installation tasks . . . . . . . . . . . . . . . . 4 UCLA/IPC-370 initialization statements . . . . . . . . 8 IEFSSN parmlib member . . . . . . . . . . . . . . . . 8 PPT entry (optional - for non-swap) . . . . . . . . . 9 Authorized Library Requirement . . . . . . . . . . . . 9 IPC initialization options . . . . . . . . . . . . . . 9 STC name . . . . . . . . . . . . . . . . . . . . 10 Subsystem name . . . . . . . . . . . . . . . . . 10 Protect key . . . . . . . . . . . . . . . . . . . 10 Changing module names . . . . . . . . . . . . . . 10 IPC SVC number . . . . . . . . . . . . . . . . . 10 Running alternate IPC's . . . . . . . . . . . . . . . . 11 Restrictions . . . . . . . . . . . . . . . . . . . . . 11 CSA buffer not available when required . . . . . . . 11 MVS/XA changes . . . . . . . . . . . . . . . . . . . . 11 MVS/ESA V3 and V4 changes . . . . . . . . . . . . . . . 12 INDEX . . . . . . . . . . . . . . . . . . . . . . . 13 UCLA/IPC-370 Installation (IPCINST) Page 1 USER MODIFICATIONS UCLA/IPC-370 is intended to run authorized and to interface with MVS via the subsystem interface. The design of IPC included a large amount of study of MVS and S/370 constraints and requirements. Multiprocessors, system integrity, RAS capabilities, and failure modes were considered in the design. THE ORDER OF INDIVIDUAL INSTRUCTIONS IS SIGNIFICANT. A full understanding of 370/POP section "Sequence of Storage References" plus knowledge and understanding of the design tradeoffs made in UCLA/IPC-370 are required to change *ANY* instruction or data area. Bugs undoubtedly exist in this product, but modifications are not recommended. This distribution is intended to be pseudo-object-code-only. The source is not intended to be modified by the user. It should be recognized by the user that any modification of this product may require an extreme effort and cost to the installation completely unrelated to the size of the modification. UCLA/IPC-370 DESCRIPTION Inter-Process-Communication (IPC) is a product developed by UCLA/OAC to provide communication services between processes for MVS and future systems. Since MVS differs from previous systems in many ways most of the approaches previously used were not considered viable for MVS and future systems. IPC has the ability to evolve with the operating system. IPC's relatively simple, fixed external interface hides the changes to the internals required by system changes. This simple interface assumes that future communication (hardware/software) capabilities will eventually eliminate hardware forced protocols. Communication link speed is also assumed to be fast enough to avoid requiring special transmission options to maintain efficiency. This is certainly true for the current version of IPC as all data transfer is storage to storage in a single MVS system. UCLA/IPC-370 Installation (IPCINST) Page 2 PLANNING AND INSTALLATION Prerequisites _____________ * conditional swapping feature (CS and CDS instructions) * PSW-key handling (IPK, SPKA instructions) * MVS/SP1.3.0 This is a minimum level. We are currently running MVS/ESA 4.2. IPC uses most IBM macros in a SPLEVEL SET=1 environment. Several different versions of MVS have contained "broken" IBM macros, which have since been fixed. These can cause assembly errors in IPC. If you get an assembly error on an IBM macro in IPC this is the most likely cause. See IBM for a fix to the macro. Note: UCLA/IPC-370 does run on XA even though it does not exploit MVS/XA features. It only uses AMODE 31 where forced to by MVS/XA requirements (during initialization) but otherwise does NOT use storage above the 16 Meg line or run in Amode 31. UCLA/IPC-370 REQUIRES that all user passed addresses be 31 (or 32) bits in length and point BELOW the 16 Meg line. The distributed modules in IPCMOD were assembled on a MVS/ESA 4.1 system at UCLA and should run on pre-XA, as well as XA, and V3 ESA systems. All these combinations have NOT been tested. Prior to the reassembly on MVS/ESA 4.1, IPC had been assembled on MVS/XA 2.2 and run on MVS/XA 2.2 through MVS/ESA 4.1. Installation ____________ Distribution Tape Format ________________________ The distribution tape for UCLA/IPC-370 is standard label and will usually contain other UCLA products in addition to IPC. The first file of the tape contains the JCL required to load the entire tape. It also contains JCL comments indicating which file is where on the tape (and approximate sizes). The first file is sequential and has the following attributes: dataset name: 'TAPEJCL' LRECL: 80 RECFM: FB BLKSIZE: 6160 UCLA/IPC-370 Installation (IPCINST) Page 3 Most of the files after the first are IEBCOPY unloaded partitioned datasets. The file which are a "part" of UCLA/IPC-370 are the following: DOCLIB - combined document library (script output) IPCJCL - UCLA/IPC-370 JCL/utility/script input IPCMOD - UCLA/IPC-370 module library IPCSRC - UCLA/IPC-370 source library IPCMAC - UCLA/IPC-370 macro library MSSMAC - UCLA general purpose macro library The IPCJCL file contains JCL, control statements, and small utilities used in the installation and maintenance of IPC. It also contains the SCRIPT/VS input statements for the IPC documents so that they can be "scripted" for your local output device. The JCL and some of the control statements will need to be modified to match your local conventions. $ASM - JCL to assemble one IPC section $ASMALL - JCL to assemble all IPC sections $FMT - JCL to run IPCFMT (AMDPRDMP verb format exit) $FMTXA - JCL to run IPCFMT (AMDPRDMP verb format exit) for XA system $IPCSDEF - define IPCS clusters $IPCSJCL - run IPCFMT under IPCS $JCL - JCL to run test IPC as a batch job $JCLTERM - JCL to run test IPC as a batch job & only clean up CSA $LINKLST - copy IPCCSA and IPCINIT to linklist library for IEFSSN use $LKED - link IPC modules (all) $MAKFMT - JCL to copy/zap AMDPRECT to add IPCFMT verb #PARM - IPC parm member #PARMTST - IPC parm for alternate IPC #PROC - IPC STC procedure #SSN - IPC IEFSSN member IPCINST - script input: UCLA/IPC-370 Installation IPCPROG - script input: UCLA/IPC-370 Programmers Guide SCRIPTP - script "profile" member SVCPRT - program which prints the SVC table (SVC #, 8 byte entry, 1st SVC # with same entry) The IPCMAC library contains the IPC macros. The IPCREQ macro *MUST* be updated to contain the local SVC number selected for IPC before any application programs are assembled. (IPC itself uses the macro, but never uses it to generate the SVC number). The IPCREQ macro is shipped with the UCLA IPC SVC number 230. The IPCSPLVL copy member in IPCMAC may need to be updated for non-XA systems. See the installation instructions below. The IPCMOD library is just an assembly and linkage edit of the UCLA/IPC-370 source. It should be identical with the UCLA/IPC-370 Installation (IPCINST) Page 4 modules you would get by assembling the source except for differences due to different system (MVS) macro levels and different assembly dates. There are two basic documents on UCLA/IPC-370. IPCINST - UCLA/IPC-370 Installation (this document) IPCPROG - UCLA/IPC-370 Programmers Guide Installation tasks __________________ * Load distribution tape * Read IPCINST (this document) * Install prerequisites * Assign IPC SVC number The IPC SVC must be a non-IBM number which is not generated as used, even to a dummy SVC routine. This number is a initialization parameter to IPC, which changes the SVC table entry to point to the SVC routine required. * Update IPCREQ macro with the IPC SVC number The IPCREQ macro is in IPCMAC. Only the SVC= keyword in the prototype statement requires updating. IPC itself never uses the IPCREQ macro to generate the SVC, thus an assembly is not required to change the SVC number. * Update IPCSPLVL copy member (if required) MVS/XA and later systems don't require any changes. Earlier systems will need to update the IPCSPLVL copy member in IPCMAC. Non-XA systems will need to comment out the the SPLEVEL macro call and change the operand of the SETB for &IPCXA to 0 instead of 1. This will cause the assemble of IPCINIT to skip generating the dual code paths required for operation on both XA and non-XA systems and only generate the non-XA code path. Note: With the SPLEVEL SET=1 NOT commented out, the "non-XA" version of IPC should work on MVS/XA 2.1.7 systems. We ran the non-XA version on our MVS/XA 2.1.7 system before we installed MVS/XA 2.2.0. To assemble IPC on a non-XA system it will be necessary to change the SETB for &IPCXA to 0 instead of 1 in the IPCSPLVL macro in IPCMAC. * Allocate an authorized library for IPC This library is the STEPLIB for the IPC STC. IPC initialization requires authorization and the name of this library must be added to the IEAAPF member of SYS1.PARMLIB. This library *MUST* be a UCLA/IPC-370 Installation (IPCINST) Page 5 controlled-access library as it will contain the AC(1) module IPCMAIN. Only the IPC STC (or JOB) and maintenance personal should have access to this library. Note: This library can contain modules from other products, IPC only adds four load modules. At UCLA we also place the UCLA/Mail module in this library. * Alter IPCEXITL if required (user exit). This user exit module contains only one exit IPCXLUSR. This routine sets the installation dependent userid for this side of an IPC connection. This is the userid which will be returned when an an IPC QUSER request is made for this connection from the other side. The QUSER request is used by UCLA/Mail to determine the userid of the other side of the IPC connection. The supplied exit is the UCLA version. If needed, assemble IPCEXITL into IPCMOD at this point (unless all of IPC will be assembled). Note: If the JOB name is not the user identifier at your installation then you will want to change this routine to find and return your user identifier (8 characters max). It has been suggested that on systems where the JOB name wasn't the userid (as it is at UCLA), that the userid might be obtained from the ACEE. The macro for the ACEE is IHAACEE in SYS1.MACLIB. The ACEE is valid on recent RACF and ACF2 systems. The ACEE is pointed to by either TCBSENV or ASXBSENV. * (OPTIONAL): Re-assemble all of IPC IPCJCL($ASMALL) is the JCL to assemble all the IPC modules. This completely re-builds the IPCMOD library and may be required if your system is at a very different level from ours. The non-"IPC" prefixed modules are general subroutines, not all of which are used by IPC. Note: Each separate module will link with return code 0 OR 4, this is normal. The undefined external references will all be defined when the pieces are all linked together. * Run "$LKED" into your chosen APF library This will create 4 load modules: IPCMAIN AC(1) - IPC task load module (name on STC EXEC card) IPCINIT - IPC initialization module (subsystem init) IPCCSA - IPC CSA module (SVC/SRB routines) IPCFMT - IPC AMDPRDMP verb format module * Run "$MAKFMT" (pre MVS/XA 2.2.0 systems only) UCLA/IPC-370 Installation (IPCINST) Page 6 This JOB will copy AMDPRECT from SYS1.LINKLIB into the IPC APF library and zap the copy to include the IPCFMT verb. This allows formatting IPC control blocks when the IPC library is used as a STEPLIB for AMDPRDMP. This is only needed if you run AMDPRDMP on your dumps, not if you run IPCS. On some systems the AMDPRECT table no longer exists, instead it has been replaced with "person readable" member BLSCECT in SYS1.PARMLIB. In that case you can copy BSLCECT and add then add the line: EXIT EP(IPCFMT) VERB(IPCFMT) Note that if you use IPCS it is NOT necessary to update BLSCECT. * Install IPC parameter member Copy IPCJCL(#PARM) and modify as required. * Install IPC STC proc Copy IPCJCL(#PROC) to your STC procedure library and modify it to point to the modified version of #PARM. Note: The IPC STC should *NOT* be a generated as a valid subsystem name. If IPC were made a subsystem it would be unable to have any sysout files and all of the datasets it referenced would have to be cataloged in the master catalog. * Initial IPC tests Note: Even though an IPL is not required to install IPC, be aware that this is new authorized code for your installation. It is suggested that the first test be during system test time. The following instructions assume the IPC STC procedure name is "IPC" and the IPC subsystem name is "IPC2". Start the IPC STC "S IPC" You should receive the following messages: IPC012I (IPCINIT) IPC2 IPC CSA INITIALIZATION COMPLETE IPC800I START OPT: At this point IPC is up. Now continue testing by stopping IPC. Stop IPC "P IPC" IPC should terminate without abending. Note that the IPC task is down, but the CSA environment is still in existence (but unuseable). Now restart the IPC STC "S IPC" UCLA/IPC-370 Installation (IPCINST) Page 7 The messages will differ from the previous start as IPC will delete the previous CSA environment and rebuild it. The following message will appear before the "CSA INITIALIZATION COMPLETE" message. IPC014I (IPCINIT) IPC2 CSA CLEANUP COMPLETE Now take a sample dump of the IPC STC and CSA. "DUMP COMM=(IPC INST SAMPLE DUMP)" R ##,JOBNAME=(IPC) Wait for MVS dump complete message. If you plan on using AMDPRDMP to format dumps then adjust $FMT (or $FMTXA) to point to the dump dataset just used and run the IPC dump formatter to test it. If you plan to use IPCS then run $IPCSDEF to define the VSAM file used by IPCS (if you don't already have one). Then enter IPCS by entering from TSO: ALLOC F(IPCSDDIR) DA(--IPCS directory cluster name--) IPCS NOPARM TASKLIB('SYS1.IPCAPF') OPEN DA('SYS1.DUMPnn') DEFAULT If you get a prompt about using SUMDUMP data reply Y to it. Note that this prompt/reply is why you can't run IPCS OPEN in batch. (or try the IPCS SETDEF NOCONFIRM statement). Now enter "VERBEXIT IPCFMT 'IPC2'" and the IPC formatter will format the sample IPC dump. * "TERM" option This option exists more for development and is not normally used. After IPC initialization completes the CSA cleanup, initialization terminates without rebuilding IPC's CSA environment. This leaves the IPC subsystem interface disconnected from the system and the IPC SVC undefined. * IPC initialization at IPL (optional) Since the IPC SVC is not defined until IPC initialization runs and places it in CSA, some sequencing problems can arise with other services attempting to use IPC services before it is started (during IPL for instance). This results in an Fnn abend for the requester which is the standard MVS abend code for an undefined SVC. IPC initialization can be run as a subsystem initialization module via an IEFSSN member in SYS1.PARMLIB (and pointed to by IEASYS member). This is optional. To allow MVS to find the IPC modules they must be copied to a LINKLST library. UCLA/IPC-370 Installation (IPCINST) Page 8 Adjust the JCL in member $LINKLST and run it to copy the modules to the selected linklist library. Adjust the contents of member #SSN and copy it to 'SYS1.PARMLIB(IEFSSN??)' Add SSN=(..) parm to IEASYS member so that the IEFSSN.. list will be used at each IPL. This will not automatically start IPC. To have the IPC STC started at IPL add a "S IPC" command to your COMMND member. These options require an IPL to test. Note: The modules in LINKLST must be the same as the modules in the IPC APF library. There have been problems with incompatible modules between these libraries. One major symptom of this problem is a bug which only shows up after an IPL and is fixed by an IPC restart (without an IPL). UCLA/IPC-370 initialization statements ______________________________________ IPC initialization statements are LRECL 80 (card images). Any card with column 1 containing an asterisk is a comment. Statements may not be continued, and only columns 1 through 71 are inspected. There is only one non-comment initialization statement "IEFSSN". The operand of this statement is the same format as an IEFSSN parmlib member statement. * --- SAMPLE IPC INITIALIZATION PARAMETERS --- * IEFSSN IPC2,IPCINIT,'230,2,IPCCSA,30,X''000200E0''' IEFSSN parmlib member _____________________ IPC2,IPCINIT,'230,2,IPCCSA,30,X''000200E0''' The parameters of the standard MVS IEFSSN statement are: subsystem name (4 characters), subsystem initialization module, initialization string (in quotes) The contents of initialization string for IPC are: IPC SVC number IPC system protect key IPC CSA load module name maximum # of IPC nodes (memories) in use at once IPC RAS option flag bytes The only default is for the number of IPC nodes. It defaults to the PARMLIB(IEASYS) MAXUSER + 3 value. Each IPC node costs 16 bytes of CSA plus the length of one SRB (about 48 bytes). UCLA/IPC-370 Installation (IPCINST) Page 9 The IPC RAS option bytes contain the following: byte 0 80 - test mode 02 - GTRACE internal msg traffic byte 1 (FRR control/options) 80 - any error is fatal 04 - CUE - count user errors (toward maximum errors) 02 - RUE - record user errors (LOGREC) 01 - SUE - SDUMP user errors byte 2 (must be zero) byte 3 (IPCTASK trace message control - internal to STC only) 80 - trace messages 40 - trace connections 20 - internal log Note: "user errors" are program checks/abends caught by the IPC FRR which IPC believes were caused by user error and not IPC errors. For more information on the IEFSSN parmlib member and statement syntax see chapter 9 of "OS/VS2 MVS SYSTEM PROGRAMING LIBRARY: JOB MANAGEMENT" (GC28-1303-0). PPT entry (optional - for non-swap) ___________________________________ The IPC STC is only used for connection open/close. If there is excessive swapping or objectionable swapin delay you may change the PPT to make IPC non-swappable (this is never required). This is recommended if UCLA/Mail's "mail check at TSO logon" option is also used. Later systems have a SYS1.PARMLIB(SCHED00) member instead of a PPT module. An entry for IPC would look like: PPT PGMNAME(IPCMAIN) NOSWAP KEY(8) Authorized Library Requirement ______________________________ All IPC modules (IPCMAIN, IPCINIT, IPCCSA) must reside in an authorized library. If the IEFSSN parmlib member is not used then all three modules may be placed in the controlled authorized STEPLIB used by the IPC STC. If the IEFSSN parmlib member is used then IPCINIT and IPCCSA must be in a linklist library to be available to subsystem initialization during IPL. IPCMAIN must not be placed in a linklist library. This would allow *ANYONE* to run IPCMAIN with any parameters. IPC initialization options __________________________ IPC has very few options and it is usually unnecessary to change any of them unless they conflict with some previously installed product. UCLA/IPC-370 Installation (IPCINST) Page 10 STC name ________ The IPC STC name is only used by the operator. There is no internal use of this name. To change the IPC STC name just change the name of the procedure used to start IPC. Subsystem name ______________ The IPC subsystem name is used to find (or build) the IPC subsystem vector table. This name also appears in any logrec records created by IPC's FRR. Protect key ___________ This specifies the system key IPC is to use for it's control blocks both in CSA and private address spaces. IPC is designed to run as much as possible in this key and avoid key zero (and user key). This keeps most IPC failures local to IPC and was a real help during initial IPC development. VM/XA note: VM/XA sites should avoid usage of key 3 as VM/XA uses key 3 to indicate idle time (it loops). An otherwise unused system key is recommended, but IPC doesn't care if other products are using the same key (this is not recommended if you have keys which are unused). At UCLA the production IPC runs in key 2. It is recommended that zero not be specified as this does not avoid the internal IPC key changes, but just defeats their purpose. It is suggested that the protect key be part of the IPC subsystem name as in "IPC2", but this is not required. The protect key is an initialization time parameter and is part of the IEFSSN parameter which appears in the IPC initialization file and the parmlib IEFSSN member (if used). Changing module names _____________________ The names of the IPC modules can be changed if conflicts exist with other products. All module names are parameters or are specified only on an EXEC JCL statement. IPC SVC number ______________ IPC checks before it changes the SVC table entry that the entry looks unused. It requires it to be a non-IBM number, and to point to the same place as another SVC slot. (This assumes that more than one SVC is unused). When changing the SVC number, remember to update the IPCREQ macro. UCLA/IPC-370 Installation (IPCINST) Page 11 RUNNING ALTERNATE IPC'S By altering the STC name, subsystem name, and SVC number an alternate IPC may be run. If the module names are also altered (or a steplib used), a completely different version may be run at the same time as a production version. RESTRICTIONS CSA buffer not available when required ______________________________________ If IPC is unable to find a free CSA buffer when required the connection will be abnormally closed. This could also happen to an internal IPC connection causing all IPC open/close requests for this or all address spaces to hang. Since IPC only ties up a CSA buffer during the actual transfer from one memory to another (not while data is just queued) this is unlikely, and has never happened here. This is a restriction of the current IPC implemention. MVS/XA CHANGES The original version of UCLA/IPC-370 ran on MVS/SP 1.3.0 and later systems including MVS/XA 2.1.7. It will NOT run on MVS/XA 2.2.0, but will die (0C4) during initialization when it tries to "install" the IPC SVC. The following changes were made to allow running this new version of IPC on MVS/XA 2.2.0 and earlier systems. Note that the XA sensitive changes are active on any XA system, not just 2.2.0. * IPCINIT has been changed to generate XA or non-XA code at assemble time. The XA code versions are the ones shipped in IPCMOD and should be capable of running on a non-XA system (however this has not been tested). See the installation instructions above for how to assemble IPC on a non-XA system. On XA systems, IPCINIT will now use the XA SVCUPDTE macro to update the the system SVC table. Also the references to the SVC table (fetch only) are now made with the AMODE set to 31. * SVCPRT has been changed to work on MVS/XA 2.2 by setting to AMODE 31 for the SVC table fetches. * A private copy of the OACCALL macro has been added to IPCMAC (must be before MSSMAC). This version of UCLA/IPC-370 Installation (IPCINST) Page 12 OACCALL defaults to generating a BALR instead of the newer BASR which the MSSMAC version generates. MVS/ESA V3 AND V4 CHANGES None. UCLA/IPC-370 Installation (IPCINST) Page 13 INDEX _____ A Authorized Library Requirement 9 C Changing module names 10 CSA buffer not available when required 11 D Distribution Tape Format 2 I IEFSSN parmlib member 8 Installation 2 Installation tasks 4 IPC initialization options 9 IPC SVC number 10 M MVS ESA V3 and V4 changes 12 XA changes 11 P Planning and Installation 2 PPT entry (optional - for non-swap) 9 Prerequisites 2 Protect key 10 R Restrictions 11 Running alternate IPC's 10 S STC name 9 Subsystem name 10 U UCLA IPC-370 description 1 UCLA/IPC-370 Installation (IPCINST) Page 14 IPC-370 initialization statements 8 User Modifications 1