HP NonStop Remote Server Call (RSC/MP) Installation and Configuration Guide

Transcription

1 HP NonStop Remote Server Call (RSC/MP) Installation and Configuration Guide Abstract This manual describes the installation, configuration, and management of RSC/MP software on a HP NonStop system acting as a server and on a variety of client workstations. Product Version RSC/MP R7.3.7 Supported Release Version Updates (RVUs) This publication supports J06.09 and all subsequent J-series RVUs, H06.20 and all subsequent H-series RVUs, and G06.20 and all subsequent G-series RVUs until otherwise indicated by its replacement publication. Part Number Published March 2012

2 Document History Part Number Product Version Published RSC/MP R7.2 March RSC/MP R7.2 October RSC/MP R7.2 April RSC/MP R7.2 September RSC/MP R7.3 June RSC/MP R7.3.3 May RSC/MP R7.3.7 March 2012

3 HP NonStop Remote Server Call (RSC/MP) Installation and Configuration Guide Index Figures Tables What s New in This Manual ix Manual Information ix New and Changed Information ix About This Manual xiii Manual Contents and Organization xiii AudienceRequirements xiv Related Manuals xiv Notation Conventions xv 1. Introduction What is RSC/MP? 1-1 The RSC/MP Environment 1-1 Workstation Components 1-2 Host Components 1-3 RSC/MP Requirements 1-4 Communications Protocols 1-5 RSC/MP Installation 1-5 General Steps for Installation 1-5 Testing RSC/MP RSC/MP Quick Start Guide RSC/MP Host Installation and Configuration 2-1 Installing RSC/MP on the Host 2-1 Configuring RSC/MP on the Host 2-2 Client Workstation Installation and Configuration 2-5 Installing the RSC/MP Win32 Client 2-5 Configuring the RSC/MP Win32 Client 2-5 Testing the RSC/MP Installation Installing RSC/MP on the Host Installation from the CD 3-1 Files Installed on the RSC/MP Host 3-2 Hewlett-Packard Compa ny i

4 Contents 4. Installing RSC/MP on Windows Workstations 4. Installing RSC/MP on Windows Workstations Installation from the CD 4-1 Installing the Win32 Client from CD 4-1 Installing the Win32+TSE Client from CD 4-2 Installing the Windows Vista Client from CD 4-3 Files Installed on the Windows Workstation 4-5 Running RSC/MP as a Service 4-8 Running the RSC/MP Win32 Client as a Service 4-9 Running the RSC/MP Win32+TSE Client as a Service 4-9 Running the RSC/MP Windows Vista Client as a Service 4-9 Changing the RSC Service Startup Mode 4-10 Using RSC/MP from Another Service (Win32+TSE Client Only) 4-11 Installing RSC/MP as a Service 4-12 Removing the RSC and Piccolo Services 4-12 Querying the Current RSC Service Configuration 4-12 Viewing Error Messages 4-13 Un-installing RSC/MP when RSC/MP is Running as a Service 4-13 Using Multiple Instances of RSC/MP 4-13 Running RSC/MP From a File Server Configuring the RSC/MP Transport (Piccolo) Configuration Steps 5-1 Backup Process 5-2 Overview of Piccolo 5-3 Configuring Piccolo (general instructions) 5-4 Configuring a Single Instance of Piccolo (for most installations) 5-5 Configuring Multiple Instances of Piccolo (for advanced installations) 5-5 Managing Multiple Instances of Piccolo (for advanced installations) 5-7 Combining Piccolo and RSC/MP Configuration Settings (workstations only) 5-9 Configuring Using the RSC/MP Configuration Wizard 5-10 Creating the Configuration File (for all installations) 5-10 Creating the [PIPEMAN] Section (for all installations) 5-12 System Names and Addresses 5-12 Configuring Network Connections 5-12 Automatic Startup of Piccolo 5-13 Large Message Support 5-13 Optional Entries 5-15 Creating the [RESOLVER] Section (optional, for workstations only) 5-15 Specifying Piccolo Logging 5-17 ii

5 Contents 6. Installing RSC/MP on UNIX Workstations Creating the [NIF-nifname] Sections (for all installations) 5-18 Configuration Options Reference 5-19 Pipeman Section ([PIPEMAN]) 5-19 Resolver Section ([RESOLVER]) Installing RSC/MP on UNIX Workstations Installation from the CD 6-1 Installing on AIX from a CD 6-3 Installing on HP-UX from a CD 6-4 Installing on Linux from a CD 6-5 Installing on Solaris from a CD 6-6 Files Installed on the UNIX Workstation 6-7 IPC Resource Requirements 6-8 System V Shared Memory 6-8 System V Message Queues 6-9 System V Semaphores NetBIOS Network Interface Configuration Prerequisites to Configuring 7-1 NetBIOS Network Interface Addressing 7-1 Configuration Options Reference 7-2 Network Interface Section ([NIF-nifname]) 7-2 NetBIOS Example PIPE.INI and PIPEINI Configuration Files TCP/IP Network Interface Configuration Prerequisites to Configuring 8-1 TCP/IP Network Interface Addressing 8-2 Extended Address Processing 8-2 Selecting the TCP/IP Port 8-3 Configuration Options Reference 8-3 Network Interface Section ([NIF-nifname]) 8-3 TCP/IP Example PIPE.INI Configuration File Managing the RSC/MP Transport (Piccolo) Running the PIPECP Program 9-1 PIPECP Commands Configuring and Managing the RSC/MP TDP Process Starting the RSC/MP Host Processes 10-1 Preserving Your Changes 10-1 iii

6 Contents 11. RSCCOM Command Reference Editing the STARTRSC File 10-2 Running Processes at High PINs 10-4 Configuring TDP Objects 10-4 RSC/MP Configuration Limits 10-5 TERM Object 10-6 PIPE Object 10-6 Files Used to Configure RSC/MP 10-6 Retaining Modifications 10-6 TDP Logging 10-6 Setting Up a Log File 10-6 Logging Using EMS Tokens 10-7 Suppressing Event Types 10-8 Logging Events RSCCOM Command Reference Overview of RSCCOM Commands 11-1 RSCCOM Command Descriptions 11-1! Command 11-2 [ Comment Indicator 11-2 ASSUME Command 11-3 EXIT Command 11-3 FC Command 11-4 HELP Command 11-5 HISTORY Command 11-6 MAXERRORS Command 11-6 MAXWARNINGS Command 11-6 OBEY Command 11-7 RSCCOM TDP Control Commands 11-8 CONTROL TDP BACKUPCPU Command 11-8 CONTROL TDP SECURITY Command 11-9 CONTROL TDP SUPPRESSEMS Command 11-9 LOGOPEN Command LOGCLOSE Command OPEN Command STATUS TDP Command VERSION Command TDP Object Management using RSCCOM Commands ABORT Command ADD Command ALTER Command iv

7 Contents 12. Configuring the RSC/MP Client DELETE Command INFO Command RESET Command SET Command SHOW Command START Command STATS Command STATUS Command STOP Command TELL Command TDP Object Attributes and Configuration Notes ACS Object Attributes PIPE Object Attributes TERM Object Attributes Configuring the RSC/MP Client RSC/MP Client Configuration and Verification 12-1 Prerequisites to Configuring RSC/MP 12-1 Basic RSC.INI Configuration 12-2 Starting the RSC/MP Transport Manager (Pipeman) 12-4 Configuring the RSC/MP I/O Manager Process (RSCPIPE) 12-4 Testing the RSC/MP Client Configuration 12-8 A. Migration to RSC/MP 7.3 Differences Between RSC/MP 7.x and Earlier Versions A-1 Features No Longer Supported A-2 Migration Tips A-2 Migrating from RSC/MP 6.x to RSC/MP 7.3 A-3 B. Installation Troubleshooting Notes About Diagnostic Clues B-1 How to Test the Configuration B-1 How to Trace Errors B-2 Step 1. Determine if Your RSC/MP Software is Current and Compatible B-2 Step 2. Determine if the Communications Transport is Functional B-3 Step 3. Check the Piccolo Configuration Files B-3 Step 4. Check the Host Configuration B-4 Step 5. Run the Workstation RSC/MP Test Program B-5 Step 6. Interpret the Workstation and Host Error Messages B-5 Step 7. Check the Status of the TDP Objects B-7 Step 8. Check the Status of the Components B-8 v

8 Contents C. RSCCOM Syntax Summary Step 9. Run Your RSC/MP Application B-8 Step 10. Turn on Additional Logging B-8 How to Use Logging B-9 RSC/MP API Logging B-10 RSCPIPE Logging B-11 Piccolo Logging B-12 TDP Logging B-13 How to Report Problems B-14 C. RSCCOM Syntax Summary Working with RSCCOM C-1 Working With the TDP as a Whole C-2 Working With Objects Within the TDP C-3 D. Resolver Reference Tags All NIF Reference Tags D-1 NetBIOS Reference Tags (nifnb) D-1 TCP/IP Reference Tags (nifsock) D-2 E. Best Practices Guide Model Configuration Scenarios E-1 Scenario 1 E-1 Scenario 2 E-6 Scenario 3 E-10 Host Home-Terminal Considerations E-12 vi

9 Contents Index Index Figures Tables Figure 1-1. The RSC/MP Environment 1-2 Figure 5-1. The Piccolo Components 5-3 Figure 5-2. Components in a Single Instance of Piccolo 5-5 Figure 5-3. Multiple Piccolo Environments 5-8 Figure Static Terminal Configuration Figure B-1. Log Collection Points B-9 Figure E-1. Scenario 1 E-2 Figure E-2. Scenario 1 improved with NIFs on the same network adapter E-4 Figure E-3. Scenario 1 improved with NIFs on different network adapters E-5 Figure E-4. Scenario 2 E-6 Figure E-5. Scenario 2 modified to run without round-robin DNS E-8 Figure E-6. Scenario 2 improved with multiple PIPEMAN instances E-9 Figure E-7. Scenario 3 E-10 Ta ble 1-1. Versions of RSC/MP on the Host 1-4 Ta ble 1-2. Versions of RSC/MP on the Client Workstation 1-4 Ta ble 1-3. RSC/MP Communication Protocols 1-5 Ta ble 3-1. Files Installed on the RSC/MP Host 3-2 Ta ble 4-1. Files Installed on the Windows Workstation 4-5 Ta ble 6-1. Shared Library Names 6-1 Ta ble 6-2. Files Installed on the UNIX Workstation 6-7 Ta ble 8-1. Resolver Formats 8-2 Table Configuration Limits 10-5 Table Sample Configuration and Management Files 10-6 Table ACS Object Attributes Table PIPE Object Attributes Table TERM Object Attributes vii

10 Contents Index viii

11 What s New in This Manual Manual Information Abstract This manual describes the installation, configuration, and management of RSC/MP software on a HP NonStop system acting as a server and on a variety of client workstations. Product Version RSC/MP R7.3.7 Supported Release Version Updates (RVUs) This publication supports J06.09 and all subsequent J-series RVUs, H06.20 and all subsequent H-series RVUs, and G06.20 and all subsequent G-series RVUs until otherwise indicated by its replacement publication. Part Number Published March 2012 Document History Part Number Product Version Published RSC/MP R7.2 March RSC/MP R7.2 October RSC/MP R7.2 April RSC/MP R7.2 September RSC/MP R7.3 June RSC/MP R7.3.3 May RSC/MP R7.3.7 March 2012 New and Changed Information These are the new or omitted features, and additional changes, in this manual for this release: Version number has been updated. RSC/MP is now thread-safe on Linux and AIX platforms as noted in the Installing RSC/MP on UNIX Workstations secton. ix

12 What s New in This Manual New and Changed Information Changed reference of SUSE Linux in Table 1-2, Versions of RSC/MP on the Client Workstation to include both 32-bit and 64-bit versions. Table 6-1, Shared Library Names has been updated to include new 64-bit shared library names on Linux platforms. Installation steps for Installing on Linux from a CD on page 6-5, has been modified to include the installation of the 32 or 64-bit Linux clients. References to RPW32EXE.EXE, in the Installing the Win32 Client from CD section on page 4-1, have been changed to RPW32EXE.MSI since RSC/MP is now installed on Windows with an.msi installer. References to RPTSEEXE.EXE, in the Installing the Win32+TSE Client from CD section on page 4-2, have been changed to RPTSEEXE.MSI since RSC/MP is now installed on Windows with an.msi installer. A notation was added to Table 4-1, Files Installed on the Windows workstation, stating that rscnt.dll is required for applications that were linked with rscw32.lib included in and releases of the T0810 product. Restriction of IpcKey option when installing RSC/MP as a service on Windows was noted in the IpcKey Option section on page 5-23, Installing RSC/MP as a Service section on page 4-12 and Configuring Multiple Instances of Piccolo (for advanced installations) section on page 5-6. Additional information was added to the LinkRequestRetryInterval option description on pages 7-7 and 8-6 noting when a longer time interval may be necessary. A comma-separated list of backup CPUs may be used in the BackupCPU Option field in the Host Piccolo configuration file (PIPEINI) or passed as the argument to the PIPECP BACKUP START command. Removed rscserv -install and rscserv -remove steps from the Installing RSC/MP as a Service and Removing the RSC and Piccolo Services sections since these opions are no longer supported. The Silent Installations on Windows feature is no longer supported. x

13 About This Manual HP NonStop Remote Server Call (RSC/MP) allows workstation-based client applications to communicate with NonStop system host-based Pathway servers and named Guardian processes. RSC/MP is made up of workstation and host components. This guide describes how to install, configure, and manage these components and also describes the RSC/MP configurable attributes which are controlled dynamically and interactively. Manual Contents and Organization This guide provides in-depth tutorials about installing and configuring RSC/MP for a NonStop system and client workstations. The remaining sections provide reference information. This list summarizes the contents of sections and appendixes in this guide: Section 1, Introduction, describes RSC/MP and its components in the NonStop environment, the versions of RSC/MP that are available, an overview of the installation and configuration process, and information about testing RSC/MP. Section 2, RSC/MP Quick Start Guide, shows how to install and configure RSC/MP on a NonStop host and RSC/MP Win32 on a Windows workstation, and how to test the installation. Section 3, Installing RSC/MP on the Host, presents step-by-step procedures for installing and configuring RSC/MP on the NonStop host and lists the files that will be installed. Section 4, Installing RSC/MP on Windows Workstations, presents step-by-step procedures for installing and configuring the Win32 and Win32+TSE versions of RSC/MP on Windows workstations, lists the files that will be installed, and discusses using RSC as a Windows Service. Section 5, Configuring the RSC/MP Transport (Piccolo), describes how to configure the Pipeman process using the Pipeman and Resolver sections in the PIPE.INI file. Section 6, Installing RSC/MP on UNIX Workstations, presents step-by-step procedures for installing and configuring RSC/MP on UNIX workstations, using the Sun SPARC Station running the Solaris operating system as an example, and lists the files that will be installed. Section 7, NetBIOS Network Interface Configuration, describes how to configure the NIFNB section of the PIPE.INI file for the NetBIOS interface. Section 8, TCP/IP Network Interface Configuration, describes how to configure the NIFSOCK section of the PIPE.INI file for the TCP/IP interface. xiii

14 About This Manual Audience Requirements Section 9, Managing the RSC/MP Transport (Piccolo), describes the PIPECP program and lists the PIPECP commands. Section 10, Configuring and Managing the RSC/MP TDP Process, discusses starting the host process, the TDP commands that you can use to configure the TDP, and TDP logging. Section 11, RSCCOM Command Reference, describes the RSCCOM commands that are used to manage the RSC/MP environment and to manage the ACS, PIPE, and TERM TDP objects. Section 12, Configuring the RSC/MP Client, shows how to create configuration files for client workstations using the RSC/MP Configuration Wizard or a text editor. Appendix A, Migration to RSC/MP 7.3, shows the procedures for migrating an application to use RSC/MP 7.3. Appendix B, Installation Troubleshooting, describes how to test an RSC/MP configuration, how to trace errors, how to use logging, and how to report problems. Appendix C, RSCCOM Syntax Summary, shows the syntax of commands and parameters for TDP configuration and management. Appendix D, Resolver Reference Tags, lists the extended address tags for the NetBIOS and TCP/IP protocols. Appendix E, Best Practices Guide, contains additional information intended to help with effective use of RSC/MP. Audience Requirements This guide is intended for application developers who will use RSC/MP to create and maintain RSC/MP applications. These users must have the following experience: Programming in one of the supported workstation environments Writing applications using an API Using C or COBOL programming languages Designing and developing Pathway/TS applications Related Manuals The RSC/MP documentation set includes this manual and the following two HP NonStop manuals: Remote Server Call (RSC/MP) Programming Manual Remote Server Call (RSC/MP) Messages Manual You can find detailed information about other NonStop system components in the appropriate HP manuals. xiv

15 About This Manual Notation Conventions Notation Conventions General Syntax Notation The following list summarizes the notation conventions for syntax presentation in this manual. Uppercase letters. Uppercase letters indicate keywords and reserved words; enter these items exactly as shown. Items not enclosed in brackets are required. For example: MAXATTACH Lowercase italic letters. Lowercase italic letters indicate variable items that you supply. Items not enclosed in brackets are required. For example: filename [ ] Brackets. Brackets enclose optional syntax items. For example: TERM [\system-name.]$terminal-name INT[ERRUPTS] A group of items enclosed in brackets is a list from which you can choose one item or none. The items in the list can be arranged either vertically, with aligned brackets on each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines. For example: LIGHTS [ ON ] [ OFF ] [ SMOOTH [ num ] ] K [ X D ] address-1 { } Braces. A group of items enclosed in braces is a list from which you are required to choose one item. The items in the list can be arranged either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines. For example: LISTOPENS PROCESS { $appl-mgr-name } { $process-name } ALLOWSU { ON OFF } Vertical line. A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces. For example: INSPECT { OFF ON SAVEABEND } xv

16 About This Manual Notation for Messages Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times. For example: M address [, new-value ] [ - ] { } An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times. For example: "s-char " Punctuation. Parentheses, commas, semicolons, and other symbols not previously described must be entered as shown. For example: error := NEXTFILENAME ( filename ) ; LISTOPENS SU $process-name.#su-name Quotation marks around a symbol such as a bracket or brace indicate the symbol is a required character that you must enter as shown. For example: "[" repetition-constant-list "]" Item spacing. Spaces shown between items are required unless one of the items is a punctuation symbol such as a parenthesis or a comma. For example: CALL STEPMOM ( process-id ) ; If there is no space between two items, spaces are not permitted. In the following example, there are no spaces permitted between the period and any other items: $process-name.#su-name Line spacing. If the syntax of a command is too long to fit on a single line, each continuation line is indented three spaces and is separated from the preceding line by a blank line. This spacing distinguishes items in a continuation line from items in a vertical list of selections. For example: ALTER [ / OUT file-spec / ] CONTROLLER [, attribute-spec ]... Notation for Messages The following list summarizes the notation conventions for the presentation of displayed messages in this manual. Non-italic text. Non-italic letters, numbers, and punctuation indicate text that is displayed or returned exactly as shown. For example: Backup Up. xvi

17 About This Manual Notation for Messages Lowercase italic letters. Lowercase italic letters indicate variable items whose values are displayed or returned. For example: p-register process-name [ ] Brackets. Brackets enclose items that are sometimes, but not always, displayed. For example: Event number = number [ Subject = first-subject-value ] A group of items enclosed in brackets is a list of all possible items that can be displayed, of which one or none might actually be displayed. The items in the list might be arranged either vertically, with aligned brackets on each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines. For example: LDEV ldev [ CU %ccu CU %... ] UP [ (cpu,chan,%ctlr,%unit) ] { } Braces. A group of items enclosed in braces is a list of all possible items that can be displayed, of which one is actually displayed. The items in the list might be arranged either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines. For example: LBU { X Y } POWER FAIL process-name State changed from old-objstate to objstate { Operator Request. } { Unknown. } Vertical line. A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces. For example: Transfer status: { OK Failed } For example, this host error message contains two sets of alternatives, and reports one item from each set: <'Fatal' 'Unexpected'> file system error <error code> occurred during a <'ADD_NAME' 'LISTEN' 'RECEIVE_ANY' 'SEND'> attempt. The error message that you see contains this information: Fatal or Unexpected ADD_NAME or LISTEN or RECEIVE_ANY or SEND % Percent Sign. A percent sign precedes a number that is not in decimal notation. The % notation precedes an octal number. The %B notation precedes a binary number. The %H notation precedes a hexadecimal number. For example: % %B %H2F xvii

18 About This Manual Change Bar Notation P=%p-register E=%e-register Change Bar Notation Change bars are used to indicate substantive differences between this manual and its preceding version. Change bars are vertical rules placed in the right margin of changed portions of text, figures, tables, examples, and so on. Change bars highlight new or revised information. For example: The message types specified in the REPORT clause are different in the COBOL85 environment and the Common Run-Time Environment (CRE). The CRE has many new message types and some new message type codes for old message types. In the CRE, the message type SYSTEM includes all messages except LOGICAL-CLOSE and LOGICAL-OPEN. xviii

19 1 Introduction What is RSC/MP? Remote Server Call/MP (RSC/MP) software lets you use personal computers (PCs) and workstations to communicate with Pathway servers and other NonStop processes on a NonStop system. The NonStop system can act as the host to one or many client workstations. RSC/MP permits workstations to invoke NonStop Transaction Services/MP (TS/MP) servers on NonStop servers. By providing a client-server environment, RSC/MP can improve the performance of NonStop TS/MP applications while maintaining the ability to handle high-transaction volumes. RSC/MP provides the link between NonStop servers and client workstations over existing communication networks. Clients may communicate with a NonStop server over a LAN using TCP/IP or NetBIOS. The RSC/MP application program interface (API) lets you develop custom user interfaces to the NonStop system. Application programs running on the workstation use RSC/MP s API to send and receive messages from NonStop processes. These RSC/MP application programs can be written in a variety of programming languages, including C, Visual Basic, and PowerBuilder. For an extensive description of the RSC/MP API, see the Remote Server Call (RSC/MP) Programming Manual. The RSC/MP Environment RSC/MP is made up of components on the workstation (the client) and the NonStop system (the server). Figure 1-1 illustrates the RSC/MP components and shows how RSC/MP provides access to Pathway servers and other Guardian processes. In this diagram, ovals represent processes. The double arrow between the workstation and host represents the communication line or network that connects the two. Other arrows show the directions of data movement among the components. Components shown in gray are supplied by RSC/MP. The other components are either written by the user, or are system components. 1-1

20 Introduction Workstation Components Figure 1-1. The RSC/MP Environment Workstation NonStop Host System Application Program ACS API RSCCOM Guardian Process TDP Communications Subsystem Communications Subsystem LINKMON R S C P I P E P I P E M A N nifsock nifnb nifsock nifnb P I P E M A N RSC IDS Requester User-written IDS Requester PIPECP PIPECP Pathway Server CDT001 Supplied by RSC/MP Legend User-written or system components Workstation Components RSC/MP on the client workstation has the following components: Application Program Interface (API) a set of function calls, plus parameters, that provide a standard interface between an application and the NonStop host. RSC/MP I/O Manager (RSCPIPE) RSC/MP Transport (Piccolo) contains: 1. PIPE manager (Pipeman) that maintains the transport connections. 1-2

21 Introduction Host Components 2. Network interfaces (NIFs) for the various protocols (nifsock or nifnb) that are protocol-specific interfaces to the communications facility. 3. Piccolo control program (PIPECP) that provides a command line interface to control Pipeman. Host Components RSC/MP on the NonStop host system has the following components: RSC/MP Transport (Piccolo) that contains three components: 1. PIPE manager (Pipeman) that maintains the transport connections. 2. Network interfaces (NIFs) for the various platforms (nifsock or nifnb). 3. Piccolo control program (PIPECP) that provides a command line interface to control Pipeman. RSC/MP Command interface (RSCCOM) configures and controls the TDP. Access Control Server (ACS) grants or denies workstations the access to RSC/MP services on the NonStop host. RSC/MP users must design and implement this optional security feature. Transaction Delivery Process (TDP) a persistent NonStop process pair that delivers and receives messages sent between workstations and the host. Through the TDP, a workstation can communicate with any Pathway server or named NonStop process. LINKMON the standard communication interface provided by the NonStop host environment through which the TDP interacts with Pathway servers. RSC IDS Requester alternative mechanism provided by RSC/MP for server access through user-written custom IDS Requesters. Application Server the NonStop application server that processes transactions, which can be either a Guardian process or a Pathway server. 1-3

22 Introduction RSC/MP Requirements RSC/MP Requirements HP provides specific versions of RSC/MP for the NonStop host and for the clients on the platforms shown in Table 1-1 and Table 1-2. For specific Software Environment requirements, review the softdoc associated with the appropriate RSC/MP component. Table 1-1. Versions of RSC/MP on the Host RSC/MP Version H P Order Number HP Product Number Hardware Platform Software Environment Host (NonStop) HSM58 T9711 HP Integrity NonStop server NonStop OS Host (NonStop) SM58 T9711 HP NonStop S-series server NonStop OS Table 1-2. Versions of RSC/MP on the Client Workstation Platform Type RSC/MP Version HP Order Number HP Product Number UNIX Windows IBM AIX SM64 T7985 HP-UX MT SM63 T2825 HP-UX(i) SM51 T2827 HP-UX 64-bit SM48 T2847 Solaris (for SPARC) 32-bit and 64-bit SM65 T7984 Solaris (for x86) SM65xV1 T0884 SUSE Linux 32- SM79 T0762 bit and 64-bit Win32 SM67 T7981 Win32+TSE SM55 T2793 Windows Vista (32-bit and 64-bit) SM76 T

23 Introduction Communications Protocols Communications Protocols Ta ble 1-3 shows the communications protocols available for each RSC/MP product. Table 1-3. RSC/MP Communication Protocols Communication Protocol Platform TCP/IP NetBIOS UNIX X Win32 X X Win32+TSE X Windows Vista X RSC/MP Installation RSC/MP includes the following software: Host software Different versions of the host software exist for Integrity NonStop servers and for NonStop S-series servers. Workstation software Each client platform requires specific software. For new installations or upgrades, install the host software first, then install the workstation software. Note. If you are already running RSC/MP, back up all existing program and configuration files before installing new software. You should read the host and workstation softdocs (provided as files with the RSC/MP software) before installing the software. General Steps for Installation RSC/MP software installation includes these general steps: 1. Install the RSC/MP software on the NonStop host system. 2. Configure the host software for the communications protocol that you will use on each client workstation. 3. Download the workstation software from the host to each workstation (see the appropriate section for Windows or UNIX ). 4. Configure each workstation for the communications protocols that RSC/MP will use (see the appropriate section for TCP/IP or NetBIOS). 1-5

24 Introduction Testing RSC/MP Testing RSC/MP Before testing RSC/MP, you must determine that the workstation is correctly connected to the NonStop host. The method of testing connectivity depends on the type of physical connection and protocol used; for example, use a PING command for TCP/IP networks. After you install and start RSC/MP, use an RSC/MP test program (RSCTESTW for Windows, or RSCTEST for UNIX) to check the installation. This application program sends messages of a specified length to the NonStop host. An echo server, TDDSVR, on the host returns the messages. The RSC/MP Windows clients also provide a simple connection test program, RSCPINGW. This test program will not attempt to contact any server, it will simply attempt a connection. Note. The RSC/MP test programs are not appropriate for benchmarking. 1-6

25 2 RSC/MP Quick Start Guide This section describes how to set up an RSC/MP host on a NonStop system and an RSC/MP Win32 client on a workstation. The Quick Start Guide describes a very basic configuration, which may be too simplistic for your requirements. If the configuration described here does not work, check the TroubleShooting section Appendix B, Installation Troubleshooting for information about analyzing problems, and refer to the rest of the manual for more detailed setup instructions. The procedures outlined in this section assume: The connection between the host and client workstation uses a TCP/IP protocol The network is configured with Domain Name Services (DNS) name-resolution The RSC/MP Session type is Interprocess (not IDS). RSC/MP Host Installation and Configuration These are the procedures for installing and configuring RSC/MP on a NonStop system. For new installations or upgrades, install the host software first, followed by the workstation software. Installing RSC/MP on the Host To install the RSC/MP host component: 1. Follow the directions in the README.TXT file on the RSC/MP CD to copy the RSC/MP host software archive from the CD to the host via a PC. 2. Follow the directions in the IPSetup User s Guide (USRGUIDE.PDF) on the CD (under the INSTALL directory) to transfer the archive files from the PC to the host. 3. Log onto the host as SUPER.SUPER and run SETUPRUN to expand the archive file to a distributed subvolume (DSV). 4. If you manage your software configuration using DSM/SCM (distributed system management/system configuration management), use DSM/SCM to transfer the DSVs to the proper install subvolumes ISVs. Non-DSM/SCM users must manually rename the DSVs to the necessary ISVs. Refer to the README.TXT file for the proper ISV names. 2-1

26 RSC/MP Quick Start Guide Configuring RSC/MP on the Host Configuring RSC/MP on the Host To configure RSC/MP: 1. Use FUP to copy STARTRSC, STOPRSC, PIPETXT, PWYCFG, and TDPCFG from the ISV to your own subvolume and position to that subvolume. 2. The STARTRSC TACL macro assumes that the TDP and RSCCOM objects are in $SYSTEM.SYSTEM and that the other RSC/MP objects are in $SYSTEM.ZRSCHOST. If this arrangement is not true for your installation, edit the STARTRSC file you copied in Step 1 and make the following changes: Change $SYSTEM.SYSTEM to the subvolume name containing the TDP and RSCCOM objects. #SET RSCSYS $SYSTEM.SYSTEM Change $SYSTEM.ZRSCHOST to the subvolume name containing the other RSC/MP objects. #SET RSCISV $SYSTEM.ZRSCHOST 3. Rename the PIPETXT file to PIPEINI and edit the PIPEINI file. The next table identifies information that needs to be modified and provides references to the full description of the options. The table displays sample [sections] needed for RSC to start its network interface(s) automatically. To do this, there needs to be one [PIPEMAN] section and one or more [NIF-nifname] sections in the PIPEINI file. For each NifList entry in the [PIPEMAN] section, there must be a corresponding [NIF-nifname] section where nifname is a symbolic network interface name. Note: This table represents a configuration for one TCP/IP network interface. Sample data is provided following the table. Identifier [PIPEMAN] DomainName SystemName Comments Locate the PIPEMAN section identifier in the PIPEINI file. Refer to Creating the [PIPEMAN] Section (for all installations) on page 5-12 for details. Enter your domain name here. If you do not know the domain name, see your system administrator. Refer to DomainName Option on page 5-21 for details. Enter your system name here. The system name is the name of the NonStop host system as defined in the DNS server. Refer to SystemName Option on page 5-33 for details. 2-2

27 RSC/MP Quick Start Guide Configuring RSC/MP on the Host Identifier IN OUT Term NifList [NIF-nifsock] ProgramFile ServicePort ProcessName Comments (Optional, but recommended to allow Piccolo to work properly if you exit from the terminal used to start Piccolo.) Enter an input file name. Refer to IN Option on page 5-22 for details. (Optional, but recommended to allow Piccolo to work properly if you exit from the terminal used to start Piccolo.) Enter an output file name. Refer to OUT Option on page 5-29 for details. (Optional, but recommended to allow Piccolo to work properly if you exit from the terminal used to start Piccolo.) Enter a home terminal name. Refer to Te rm Option on page 5-35 for details. Set this entry to nifsock, which matches an entry later in the file. Refer to NifList Option on page 5-28 for details. Locate the [NIF-nifsock] identifier in the file. Refer to Network Interface Section ([NIF-nifname]) on page 8-3 for details. Leave ProgramFile set to nifsock, which is the executable for the TCP/IP network interface. Refer to ProgramFile Option on page 8-9 for details. If you are using the default Piccolo ServicePort of 2787, put a semicolon (;) in front of the line starting with ServicePort. Enter a ServicePort if you are using a port other than the default. See your System Adminstrator if you are not sure which port to use. Refer to ServicePort Option on page 8-11 for details. (Optional) If your TCP/IP process name is not the default $ZTCO, enter the process name here. Refer to ProcessName Option on page 8-9 for details. 2-3

28 RSC/MP Quick Start Guide Configuring RSC/MP on the Host Below is an example of an updated PIPEINI file. [PIPEMAN] DomainName=mycompany.com SystemName=rscmp1 in=\rscmp1.$ymiop.#clci out=\rscmp1.$ymiop.#clci term=\rscmp1.$ymiop.#clci NifList=nifsock ;the TCP/IP network interface [NIF-nifsock] ProgramFile=nifsock ; executable for TCP/IP network interface ServicePort=5678 ; overrides default of 2787 ProcessName=$ZTC6 ; overrides default of $ZTC0 Note. The PIPEINI file must be closed before Piccolo can be started as part of the next step. 4. To start RSC/MP, enter this command from a TACL prompt: > run startrsc 2-4

29 RSC/MP Quick Start Guide Client Workstation Installation and Configuration Client Workstation Installation and Configuration Follow this procedure to install the RSC/MP Win32 client on a workstation running Windows. The workstation must have least 4 MB of free disk space and have the TCP/IP network enabled. Use the PING command to check the TCP/IP configuration on the workstation. Installing the RSC/MP Win32 Client To install the RSC/MP Win32 client on a workstation, follow the directions in the README.TXT file on the RSC/MP CD. For further information and a description of the files installed on Windows, see Section 4, Installing RSC/MP on Windows Workstations Configuring the RSC/MP Win32 Client Follow these steps to configure the RSC/MP Win32 client on a workstation: 1. Copy PIPE.INI from the SAMPLES directory to the BIN directory and edit the file as follows: [PIPEMAN] DomainName=<enter your domain name> If you do not know the domain name, see your system administrator. SystemName=<enter your system name> The system name is the name of the local workstation. NifList=tcp ;the TCP/IP network interface [NIF-tcp] ProgramFile=nifsock ; executable for TCP/IP network interface ServicePort=<enter TCP/IP port number> The TCP/IP port number should match the value assigned to ServicePort entry in the RSC/MP host PIPEINI file (ServicePort=5678 ; overrides default of 2787 on page 2-4). Note. The PIPE.INI file must be closed before Piccolo can be started. 2. Copy RSC.INI from the SAMPLES directory to the BIN directory and edit the file as follows: HOST_PIPENAME=RSC@yourrschost Change yourrschost to match the SystemName set in the RSC/MP host PIPEINI file (Enter your system name here. on page 2-2). 2-5

30 RSC/MP Quick Start Guide Testing the RSC/MP Installation Testing the RSC/MP Installation To test the RSC/MP installation: 1. Start the transport by using the PIPECP START command. 2. Run the RSCTESTW program. 3. When the RSC/MP Diagnostic Test Utility window appears, click on the Start button. The test program is set to use a Guardian named process and should run without making any modifications to the options. 4. If the test program connects and sends messages between the client and server, RSC/MP is installed correctly. 5. To stop the test, click on the Stop button. 2-6

31 3 Installing RSC/MP on the Host The main component of the RSC/MP NonStop host software is the Transaction Delivery Process (TDP) that manages transactions between the NonStop host and client workstations. The files that are installed on the host are listed in Files Installed on the RSC/MP Host on page 3-2. For new installations or upgrades, install the host software first and then the workstation software. To install RSC/MP on a NonStop host, do the following: Make sure you are running the minimum software and hardware requirements. Refer to the README.TXT file on the RSC/MP CD. Perform the installation according to the instructions provided with the CD. Verify that the correct files have been installed. Configure and start the RSC/MP host (see Section 10, Configuring and Managing the RSC/MP TDP Process). Installation from the CD Follow these steps to install the software from the CD: 1. Follow the directions in the README.TXT file on the RSC/MP CD to copy the RSC/MP host software archive from the CD to the host via a PC. 2. Follow the directions in the IPSetup User s Guide (USRGUIDE.PDF) on the CD, under the INSTALL directory, to transfer the archive files from the PC to the host. Refer to the Manual Software Placement Using the IPSetup TACL Program section. 3. Log onto the host as SUPER.SUPER and run SETUPRUN to expand the archive file to a distributed subvolume (DSV) by following the instructions in section Manual Software Placement Using the IPSetup TACL Program. 4. If you manage your software configuration using DSM/SCM (distributed system management/system configuration management), use DSM/SCM to transfer the DSVs to the proper install subvolumes ISVs. Non-DSM/SCM users will need to manually rename the DSVs to the necessary ISVs. Refer to the README.TXT file for the proper ISV names. 5. (Optional.) Perform a receive software and build/apply using DSM/SCM to save the software in the DSM/SCM archives and move it to the NonStop ISV (installation subvolume). 6. (Optional.) After completing the DSM/SCM build/apply the files in the NonStop ISV will be installed as shown in Files Installed on the RSC/MP Host on page Set the volume to the NonStop ISV (ZRSCHOST). 3-1

32 Installing RSC/MP on the Host Files Installed on the RSC/MP Host 8. Obtain the name of the current EMS template files. You will need this information if you want to restore the original system templates. See the DSM Template Services Manual or the EMS Messages Manual for more information. 9. Run the command RUN TMPLMRG to merge the RSC/MP EMS templates into the system template files. After this procedure has completed, the files in Files Installed on the RSC/MP Host on page 3-2 will have been created or modified. 10. To restore the unmerged EVENTTD file, rename $SYSTEM.SYSTEM.EVENTOLD to EVENTTD. 11. To restore the unmerged EMS template files, run $SYSTEM.SYSTEM.COUP or $SYSTEM.SYSTEM.SCF to assign the templates to the name of the EMS template file that you obtained in Step 8. Files Installed on the RSC/MP Host The following table lists the files that are copied onto the host system during the RSC/MP installation. Note. Any changes to this list appear in the softdoc that comes with each RSC/MP version. Table 3-1. Files Installed on the RSC/MP Host (page 1 of 3) RSC/MP Host Location File Name Description ZRSCHOST ADVTMPL RSC/MP EMS advisory text compiled templates Required for product use? no IDSCOD IDSDIR IDSSAMPL IDSSYM NIFNB Sample SCOBOL IDS requester program file. Sample SCOBOL IDS requester directory file. Sample SCOBOL IDS requester source code file. Sample SCOBOL IDS requester symbol file. NetBIOS protocol network interface no no no no yes 1,2 NIFSOCK TCP/IP protocol network interface yes 1 PCFGCHK Piccolo configuration file check program no 3-2

33 Installing RSC/MP on the Host Files Installed on the RSC/MP Host Table 3-1. Files Installed on the RSC/MP Host (page 2 of 3) RSC/MP Host Location File Name Description ZRSCHOST PIPECP Pipe transport control program yes PIPEMAN Piccolo Manager process yes PWYCFG Sample Pathway configuration no RSCH RSC/MP application includes no SAMPACSC SAMPACS SAMPUMSC SAMPUMS STARTRSC STOPRSC Access Control Server (ACS) sample source code Access Control Server (ACS) sample program Unsolicited Message Service (UMS) sample source code Unsolicited Message Service (UMS) sample program Sample RSC/MP host startup TACL macro Sample RSC/MP host shutdown TACL macro TDDSVR RSCTEST echo server no TDDSVRC RSCTEST echo server source no TDPCFG Sample TDP configuration (RSCCOM input) file TMPLMRG Template merge TACL macro no ZRSCC ZRSCCOB C header for RSC/MP EMS applications COBOL header for RSC/MP EMS applications ZRSCDDL RSC/MP EMS DDL source no ZRSCPAS ZRSCTACL ZRSCTAL ZRSCTMPL Pascal header for RSC/MP EMS applications TACL header for RSC/MP EMS applications TAL header for RSC/MP EMS applications RSC/MP EMS message text compiled templates Required for product use? no no no no no no no no no no no no no 3-3

34 Installing RSC/MP on the Host Files Installed on the RSC/MP Host Table 3-1. Files Installed on the RSC/MP Host (page 3 of 3) RSC/MP Host Location File Name Description $SYSTEM.SYSTEM RSCCOM RSC/MP command program yes RSCHELP RSCCOM help text no TDP TDP object yes LIBPIPE dynamic link library yes $genvol.softdocs SOFTDOC RSC/MP host release documentation 1. At least one NIF is required. Required for product use? 2. Included with RSC/MP for HP NonStop S-series; not included with RSC/MP for HP Integrity NonStop. no 3-4

35 4 Installing RSC/MP on Windows Workstations Three RSC/MP clients are available for Windows workstations: Win32, Win32+TSE and Windows Vista (32-bit and 64-bit platforms). To install RSC/MP on Windows workstations, do the following: Verify you have the minimum RSC/MP requirements on your workstation by reviewing the documentation on the RSC/MP Windows CD. Perform the installation according to the instructions provided with the CD. Verify that the correct files have been installed (see Files Installed on the Windows Workstation on page 4-5). Configure the Windows client. Installation from the CD Follow the installation steps for your particular RSC/MP Windows client. The following installation information is provided: Installing the Win32 Client from CD: describes how to install a single Win32 client. Installing the Win32+TSE Client from CD: describes how to install a single Win32+TSE client. Installing the Windows Vista Client from CD: describes how to install the Vista client as a Windows Service. Installing the Win32 Client from CD To install the Win32 client software from the CD: 1. Insert the RSC/MP Win32 Client CD into a drive attached to a Windows workstation. 2. Navigate to the WS_SW folder on the CD. 3. Select one of these installation methods: a. Install directly onto the workstation attached to the CD drive by double-clicking on the RPW32EXE.MSI file. b. Install on multiple workstations by copying the RPW32EXE.MSI file to a central workstation that can be accessed by all workstations. Log on to each 4-1

36 Installing RSC/MP on Windows Workstations Installing the Win32+TSE Client from CD workstation and locate the RPW32EXE.MSI file on the central workstation. Either double-click on the RPW32EXE.MSI file, type RPW32EXE.MSI at a DOS prompt, or select Start->Run and enter the full path of the RPW32EXE.MSI file. c. Transfer the RPW32EXE.MSI file to the NonStop and then transfer RPW32EXE.MSI to the target workstation. The file must be transferred in BINARY mode. Log on to the workstation and locate the RPW32EXE.MSI file. Either double-click on the RPW32EXE.MSI file, type RPW32EXE.MSI at a DOS prompt, or select Start->Run and enter the full path of the RPW32EXE.MSI file. 4. The files after extraction are listed in subsection Files Installed on the Windows Workstation on page 4-5. Installing the Win32+TSE Client from CD To install the Win32+TSE client software from the CD: 1. Insert the RSC/MP Win32+TSE Client CD into a drive attached to a Windows workstation. 2. Navigate to the WS_SW folder on the CD. 3. Select one of these installation methods: a. Install directly onto the workstation attached to the CD drive by double-clicking on the RPTSEEXE.MSI file. b. Install on multiple workstations by copying the RPTSEEXE.MSI file to a central workstation that can be accessed by all workstations. Log on to each workstation and locate the RPTSEEXE.MSI file on the central workstation. Either double-click on the RPTSEEXE.MSI file, type RPTSEEXE.MSI at a DOS prompt, or select Start->Run and enter the full path of the RPTSEEXE.MSI file. c. Transfer the RPTSEEXE.MSI file to the NonStop and then transfer RPTSEEXE.MSI to the target workstation. The file must be transferred in BINARY mode. Log on to the workstation and locate the RPTSEEXE.MSI file. Either double-click on the RPTSEEXE.MSI file, type RPTSEEXE.MSI at a DOS prompt, or select Start->Run and enter the full path of the RPTSEEXE.MSI file. 4. When the installation program asks the question Do you want RSC to run as a Service?, answer Yes. See Running the RSC/MP Win32+TSE Client as a Service on page The files after extraction are listed in subsection Files Installed on the Windows Workstation on page

37 Installing RSC/MP on Windows Workstations Installing the Windows Vista Client from CD Installing the Windows Vista Client from CD To install the Windows Vista client software from the CD: 1. Insert the RSC/MP Windows Vista Client CD into a drive attached to a Windows workstation. 2. Navigate to the WS_SW folder on the CD. 3. Select one of these installation methods: a. Install directly onto the workstation attached to the CD drive by double-clicking on the RPSETUP.MSI file. b. Install on multiple workstations by copying the RPSETUP.MSI file to a central workstation that can be accessed by all workstations. Log on to each workstation and locate the RPSETUP.MSI file on the central workstation. Either double-click on the RPSETUP.MSI file, or select Start->Run and enter the full path of the RPSETUP.MSI file. c. Transfer the RPSETUP.MSI file to the NonStop and then transfer RPSETUP.MSI to the target workstation. The file must be transferred in BINARY mode. Log on to the workstation and locate the RPSETUP.MSI file. Either double-click on the RPSETUP.MSI file, or select Start->Run and enter the full path of the RPSETUP.MSI file. 4. The Windows Vista client is installed as a Windows Service as a default. This is the only supported configuration for the Vista client. See Running the RSC/MP Windows Vista Client as a Service on page 4-9. At time of installation, the Allow Service to Interact with Desktop property is set by default. 5. The files after extraction are listed in subsection Files Installed on the Windows Workstation on page 4-5. Windows Vista and Windows 7 Installation Restrictions If RSC/MP is installed under the C:\Program Files directory on a Windows Vista or Windows 7 system, Microsoft uses "folder redirect" to protect against malware accessing the application data files (such as pipe.ini). Therefore, at time of installation, the pipe.ini file is redirected to a different location then the bin folder within the installation directory. Because of this redirection, RSC/MP cannot locate the pipe.ini file to start the services during the installation process, causing an error The pipe.ini file will be redirected to a VirtualStore hidden folder such as: C:\Users\"Name"\AppData\Local\VirtualStore\Program Files\... Note. To view such folders, "Show hidden folders" needs to be selected within Windows Explorer. 4-3

38 Installing RSC/MP on Windows Workstations Installing the Windows Vista Client from CD To avoid this folder redirection, the following should be done: 1. Install RSC/MP as "THE Administrator" on the system, NOT a USER with Administrator privileges. OR 1. Set PIPEINI environment variable to point to intended installation directory. For example, c:\program Files\RSC\bin\pipe.ini. 2. Open a DOS command window as an Administrator (window will display "Administrator: Command Prompt" in the title). 3. Change to the directory where the RPSETUP.MSI file is located and execute it manually from the DOS prompt. Do NOT attempt to run the RPSETUP.MSI file from within Windows Explorer even if you opened Windows Explorer as an Administrator since the folder redirect would then occur. 4. Enter valid settings with the configuration wizard to create a pipe.ini file (i.e. set the domain name, system name and valid port number). 5. The pipe.ini file should be written to the selected installation directory (i.e. C:\Program Files\RSC\bin) and NOT redirected to a folder such as C:\Users\"Name"\AppData\Local\VirtualStore\Program Files\... Note. The same issue exists with running the "Configure RSC" option from the start menu. In order to avoid the folder redirection, rscconfig.exe would need to be run manually from a DOS window run as an administrator. 4-4

39 Installing RSC/MP on Windows Workstations Files Installed on the Windows Workstation Files Installed on the Windows Workstation The following table lists the RSC/MP files that will be installed with on a Windows workstation. Table 4-1. Files Installed on the Windows Workstation (page 1 of 3) Directory File Name Description bin libpipe.dll Piccolo 32-bit DLL yes7 libpipe64.dll Piccolo 64-bit DLL yes8,9 nifnb.exe NetBIOS protocol network interface nifsock.exe TCP/IP protocol network interface yes1,3 pcfgchk Piccolo configuration file check program pipecp.exe Pipe transport control program yes pipeman.exe Pipe transport manager yes pipeserv.exe Piccolo Service installation utility no 4 readme.txt post installation information no rsc.err RSC/MP error message reference file rscconfig.exe RSC/MP configuration tool no Required for product use? yes1,2,6 no yes rscconfig.hlp RSC/MP configuration tool help no text rscnt.dll RSC/MP API DLL (CDECL calling no 5 convention) rscpingw.exe RSC/MP Windows connection test no program rscpipe.exe RSC/MP I/O manager yes rscserv.exe RSC Service installation utility no 4 rsctest.exe RSC/MP test console application program (32-bit) rsctest64.exe RSC/MP test console application program (64-bit) rsctestw.exe RSC/MP test Windows application program (32-bit) rsctestw64.exe RSC/MP test Windows application program (64-bit) no no 8 no no 8 4-5

40 Installing RSC/MP on Windows Workstations Files Installed on the Windows Workstation Table 4-1. Files Installed on the Windows Workstation (page 2 of 3) Directory File Name Description bin rscvproc.exe RSC/MP client VPROC utility no rscw32.dll rscw64.dll RSC/MP API 32-bit DLL (MS standard calling convention) RSC/MP API 64-bit DLL (MS standard calling convention) include rsc.bas RSC/MP API Visual Basic declarations Required for product use? yes7 yes8,9 rsc.vb RSC/MP API Visual Basic no declarations for.net environment rsc.h RSC/MP API includes yes lib rscw32.lib RSC/MP API import 32-bit library (MS standard calling convention) rscw64.lib RSC/MP API import 64-bit library (MS standard calling convention) no yes7 yes8,9 samples java Folder containing sample Java yes6 application pipe.ini sample Piccolo configuration file yes, copy to BIN directory RSC.INI sample RSC/MP configuration file yes, copy to BIN directory testvb Folder containing sample VB6 source code no 6 testvbnet umsclient.c Folder containing sample VB.net source code Unsolicited Message Service (UMS) sample source code umsclient.exe Unsolicited Message Service (UMS) sample program source rsctest.c RSC/MP test console application source rsctest.mak rsctestw.c rsctestw.def RSC/MP test application make file for MS Visual Studio 6 RSC/MP test Windows application source RSC/MP test Windows application definitions no 6 no 6 no 6 no no no no 4-6

41 Installing RSC/MP on Windows Workstations Files Installed on the Windows Workstation Table 4-1. Files Installed on the Windows Workstation (page 3 of 3) Directory File Name Description source rsctestw.h RSC/MP test Windows application includes rsctestw.ico rsctestw.rc RSC/MP test Windows application icon RSC/MP test Windows application resource file Required for product use? no no no 1. At least one NIF is required for Win Not included with Win32+TSE. 3. Required on Win32+TSE and Vista. 4. Required only if RSC/MP is to be run as a service. 5. Required for applications that were linked with rscnt.lib prior to Release 6.0 and for applications that were linked with rscw32.lib included in Releases and of the T0810 product. 6. Not included with Windows Vista. 7. Required for running 32-bit applications. 8. Only included with Windows Vista installed on a 64-bit platform. 9. Required for running 64-bit applications. 4-7

42 Installing RSC/MP on Windows Workstations Running RSC/MP as a Service Running RSC/MP as a Service The RSC/MP clients for Windows have the ability to run under the control of the Windows Service Control Manager (SCM) on versions of Windows that contain the SCM. When configured to run this way, RSC/MP provides two services Piccolo and RSC which must both be running in order for applications to use RSC/MP. In any place where the RSC/MP product or this product documentation refers to RSC/MP running as a service, this is shorthand for as the two services registered with the SCM as Piccolo and RSC. When installed as a service, RSC/MP can be started automatically at system boot time, and started and stopped manually (locally or remotely) through use of the Services control panel or administrative tool. In order to run as a service, the product must be installed to a local disk. The service installation can be done during product installation by answering Yes to the question Do you want RSC to run as a Service? or at a later time using the instructions Installing RSC/MP as a Service on page It is also possible to remove just the RSC/MP services while keeping the RSC/MP product installed and ready for use in a non-service mode (see Removing the RSC and Piccolo Services on page 4-12). Note. When selecting to run RSC/MP as a Service at time of installation, be aware that the pipe.ini configuration file must either be created at the same time or exist prior to the Services being started. Otherwise, an error 1920 will occur because the Services could not be started. If this happens, place a copy of the configuration file into the appropriate directory (usually RSC/bin) and select the Retry button to complete the installation. The system requirements and capabilities of the RSC/MP Windows clients vary as described on the next page. 4-8

43 Installing RSC/MP on Windows Workstations Running the RSC/MP Win32 Client as a Service Running the RSC/MP Win32 Client as a Service The Win32 client is intended for use by traditional, single-user workstation applications. The RSC/MP service mechanism is a convenience feature which provides a method by which the necessary RSC/MP processes can be started automatically before they are needed by the RSC/MP application. It is not designed to support other system services such as web servers that might serve multiple end users. RSC/MP can be installed as a service under Windows XP, Windows 2000, Windows 2000 Server and Windows 2003 Server. When installed as a service, RSC/MP will be usable only from applications that are running in the interactive (console) desktop. The RSC/MP service cannot be used from another service and cannot be used from user sessions running under Microsoft Terminal Services. If automatic startup of RSC/MP is required on these platforms, then Piccolo AutoStart should be configured (see Automatic Startup of Piccolo on page 5-13). Running the RSC/MP Win32+TSE Client as a Service The Win32+TSE client is intended for use in a Windows-based server environment where it can support multiple end users by way of a web server or terminal services. To be usable from other services and from user sessions running under Microsoft Terminal Services, always install the RSC/MP Win32+TSE client to run as a service. If RSC/MP is not run as a service, it will not reliably serve client applications running in different security contexts, such as those running in separate user sessions. Running the RSC/MP Windows Vista Client as a Service The Windows Vista client is automatically installed as a service with the Allow Service to Interact with Desktop property set by the installer. Due to the enhanced security features of Windows Vista it is not recommended that the RSC/MP Vista client be run as a stand-alone application. Running RSC/MP Vista client as a service will enable multiple client applications running in different security contexts to access RSC/MP, both from within the local system as well as remote clients accessing RSC/MP using Remote Desktop Connection or terminal services. 4-9

44 Installing RSC/MP on Windows Workstations Changing the RSC Service Startup Mode Changing the RSC Service Startup Mode If you install RSC/MP to run as a service, the installation program sets the RSC Service and Piccolo Service startup modes to Automatic in order to have Piccolo Service and RSC Service start automatically at system boot time. If the RSC Service or Piccolo Service is installed, the result of attempting to access RSC/MP or Piccolo will rely on the state of the service at the time of the attempted access, as described in the table below. Automatic Manual Piccolo Service The Piccolo Service is started at boot time and is available for use without any user action. You manually start the Piccolo Service using one of the following: 1. Run PIPECP START from a command line. or 2. Start the RSC Service (which starts the Piccolo Service as well as the RSC Service). or 3. Start the Piccolo Service from the Control Panel. RSC Service The RSC Service is started at boot time and is available for use without any user action. You manually start the RSC Service by: 1. Using the Control Panel to start the RSC Service (which will also start the Piccolo Service). NOTE: If the service is not started when an RSC/MP application is run, and RSCPIPE is included in the path, the RSC/MP API will work but will not run the RSC Service. This method is not recommended. Disabled Piccolo Service Not recommended. This setting prevents the Piccolo Service from running under any conditions, which will prevent an application that relies on Piccolo from running. If you installed Piccolo as a service and no longer wish to use it as a service you should remove the Piccolo Service, described in Removing the RSC and Piccolo Services on page RSC Service Not recommended. This setting prevents the RSC Service from running under any conditions. If RSCPIPE is included in your path, the RSC/MP API will work under this condition, but will not run the RSC Service. If you installed RSC/MP as a service and no longer wish to use it as a service, you should remove the RSC Service as described in Removing the RSC and Piccolo Services on page

45 Installing RSC/MP on Windows Workstations Using RSC/MP from Another Service ( Wi n32+ts E Client Only) To change the startup mode on Windows 2000 or Windows XP: 1. Open the Control Panel. 2. Open Administrative Tools folder, then open Computer Management. 3. Open the Services and Applications group and select Services. 4. Double-click on RSC to open the RSC Properties sheet. 5. Choose the General tab and adjust the Startup type to Automatic, Manual, or Disabled. 6. Close the RSC Properties sheet. 7. Double-click on Piccolo to open the Piccolo Properties sheet. 8. Choose the General tab and adjust the Startup type to Automatic, Manual, or Disabled. 9. Close the Piccolo Properties sheet. Note. The Interact with Desktop setting must be set to YES in order for the Win32 client to function properly. This restriction does not apply to the Win32+TSE client. Using RSC/MP from Another Service (Win32+TSE Client Only) The internal name for the RSC Service is RemoteServerCall. If you write a service that depends upon RSC/MP, your service should register its dependency on RemoteServerCall with the Service Control Manager. Because the RSC Service itself is already dependent upon the Piccolo Service, your service does not need to explicitly register its dependency upon Piccolo

46 Installing RSC/MP on Windows Workstations Installing RSC/MP as a Service Installing RSC/MP as a Service If you installed RSC/MP and elected not to run RSC/MP as a service and later decide that you want RSC/MP as a service, you will need to uninstall RSC/MP and reinstall it electing to run RSC/MP as a service. When RSC/MP is installed as a service on the Windows platform, only one Piccolo instance is allowed. The Piccolo configuration file is required to be named pipe.ini and to reside in the bin subdirectory under the RSC/MP product installation directory. The default IPC key must be used. If an IPC key with a name other than the default piccolo is included in the Piccolo configuration file, errors will occur during the installation process. Removing the RSC and Piccolo Services If you have installed RSC/MP as a service, and later need to run RSC/MP in its nonservice format, you will need to stop the Piccolo and RSC Services from the Control Panel, uninstall RSC/MP and reinstall it electing to run RSC/MP as a service. Querying the Current RSC Service Configuration You can use the RSCSERV program to produce a report of the current RSC and Piccolo Service configurations and status by following these steps: 1. Locate the rscserv.exe file (located in the bin subdirectory under the main directory into which you installed RSC/MP). 2. From the command prompt, invoke the rscserv.exe program by using this command: rscserv -query 4-1 2

47 Installing RSC/MP on Windows Workstations Viewing Error Messages Viewing Error Messages In general, RSC/MP error messages are reported using return codes from the RSC/MP API. Additional information in the form of log messages are written to the RSC/MP and Piccolo log files as described in Specifying Piccolo Logging on page When RSC/MP runs as a service, however, fatal startup errors are written to the system event logs to assist in troubleshooting unattended startup failures. On starting the RSC and Piccolo Services using the Services Control Panel, failure to start either will be reported with a service-specific error code. This code can be used to show the details of the error by following these steps: 1. Open the system Event Viewer. 2. From the Log menu, choose Application. 3. Find the event logged event: Source is RSC or Piccolo, and Event number that matches the service-specific error code that was reported by the Services Control Panel. 4. Double-click on the matching event to see a detailed error message. When RSC/MP is configured to start automatically at system boot and the startup fails, the Service Control Manager will log the service-specific error code to the system event log under the System log. To diagnose a failed automatic startup, access the System log first to retrieve this code, then use the Application log to look it up according to the steps shown above. Un-installing RSC/MP when RSC/MP is Running as a Service To remove RSC/MP cleanly, you must un-install the RSC and Piccolo Services first (if installed) then remove the RSC/MP product. Un-installing RSC and Piccolo Services is described in Removing the RSC and Piccolo Services on page Using Multiple Instances of RSC/MP Multiple instances of RSCPIPE are not allowed when RSC/MP is installed as a service. However, this rule does not prevent multiple instances of RSC/MP applications. The single RSC Service supports all RSC/MP applications. Additionally, the value of the API option SUBSYSTEM_NAME is ignored when RSC/MP is installed as a service

48 Installing RSC/MP on Windows Workstations Running RSC/MP From a File Server Running RSC/MP From a File Server In order to run RSC/MP from a file server, the RSC/MP product must be installed to a directory on a mapped drive (for example, NET USE R: \\SERVER\RSCSHARE) so that the BIN subdirectory can be added to the PATH (for example, PATH=%PATH%;R:\BIN). During installation to a file server, answer No to the question Do you want to run RSC/MP as a service?. When sharing configuration files stored on the file server, use the automatic SystemName generation function and follow the rules by which the Pipeman process and the Piccolo API locate the Piccolo configuration file (see RSC/MP components use the following search sequence to locate Piccolo configuration files: on page 5-6). Also consider that the Pipeman process will hold a read lock on its configuration file while it runs; this means that a shared configuration file cannot be altered until Piccolo is stopped on every user's machine. The Pipeman process, the RSCPIPE process, and the RSC/MP API all provide diagnostic logging capabilities. To avoid contention for output files, do one of the following: Specify different names for output files on the file server. Direct output files to the local workstations. For example, in the PIPE.INI file use LogFileName=C:\RSC_LOG\PIPELOG, which will cause the Piccolo diagnostic output to be written to a local file on the C: drive of each workstation

49 5 Configuring the RSC/MP Transport (Piccolo) The network transport mechanism that RSC/MP uses is called Piccolo. RSC/MP uses Piccolo both on the NonStop host and on the client workstation. Although the RSC/MP functional components are different at both ends TDP runs on the host, RSC/MP applications and RSCPIPE run on the workstation Piccolo itself is almost the same at both ends. This section describes how to configure the RSC/MP transport (Piccolo) both on the NonStop host and the client workstation. The following concepts are also discussed in this section: Using a backup process to recover during a failure, see Backup Process on page 5-2. Creating and configuring the RSC/MP transport (Piccolo) configuration file (PIPE.INI). Running more than one copy of Piccolo, see Configuring Multiple Instances of Piccolo (for advanced installations) on page 5-5. Creating the [PIPEMAN], [RESOLVER], and [NIF-nifname] sections and their options. Using logs, see Specifying Piccolo Logging on page Configuration Steps To complete the RSC/MP transport configuration: 1. Create a PIPE.INI file either manually or by using the RSC/MP Configuration Wizard. 2. In the Pipeman section of the PIPE.INI file, configure the SystemName and DomainName options, as described in Configuration Options Reference on page Configure a network interface (NIF). See the appropriate section in this guide: Section 7, NetBIOS Network Interface Configuration Section 8, TCP/IP Network Interface Configuration 4. Determine whether the network name resolution services will resolve the name of your NonStop host. If not, define the Resolver section of the PIPE.INI file. This section is usually not required; see the Resolver section described in Configuration Options Reference on page 5-19 to help determine if you need the Resolver section. 5-1

50 Configuring the RSC/MP Transport (Piccolo) Backup Process 5. Start the Pipeman and NIF processes using the PIPECP START command. See Automatic Startup of Piccolo on page 5-13 for information about automatically starting the subsystem. See PIPECP Commands on page 9-2 for information about the PIPECP START command. Note. The configuration file must be closed before Piccolo can be started. 6. Verify that your system is up and running and that your network interface is registered by using the STATUS command in the PIPECP window. 7. Using the PIPECP CONNECT command with the system name of the NonStop host, check that the RSC/MP Transport (Piccolo) is functioning correctly. Backup Process For NonStop systems only, the Piccolo Active Backup feature is implemented using the persistent model. Upon failure of the primary Pipeman process or primary CPU, the backup process will recover a subset of the configuration information at the time of the failure and will begin running using that configuration. The TDP PIPE object will report a PIPERC_PIPEMAN_NOT_RUNNING or PIPERC_PIPEMAN_RESTARTED error and will enter an automatic restart loop. All outstanding open pipes will be closed. Limited information is recovered from the backup process. Changes to the Piccolo configuration file while the primary process is running may produce undesirable effects. The following configuration information is recovered from the backup process: The current LogLevel. When the backup process takes over it uses the log level that was set in the primary process when the primary process fails. The LogLevel entry in the configuration file is ignored. See Specifying Piccolo Logging on page 5-17 for more information about using logs. The list of currently running NIFs. The NifList entry in the configuration file is ignored. All other configuration information other than the LogLevel and NifList are read from the copy of the Piccolo configuration file that is current at the time of recovery. See the PIPECP STATUS command in section PIPECP Commands on page 9-2 for a status of the primary and backup processes. 5-2

51 Configuring the RSC/MP Transport (Piccolo) Overview of Piccolo Overview of Piccolo Piccolo consists of a single manager process (Pipeman) and one or more network interface processes (NIFSOCK or NIFNB). These processes running together provide the communications mechanism that connects the RSC/MP application running on the workstation to the TDP running on the NonStop host, through RSCPIPE (which also runs on the workstation). A single instance of Piccolo can support multiple TDP processes on the NonStop host or multiple instances of RSCPIPE and RSC/MP applications on a workstation as shown in Figure 5-1: Figure 5-1. The Piccolo Components NonStop Host Workstation TDP RSC/MP application TDP RSCPIPE RSCPIPE RSC/MP application PIPEMAN PIPEMAN NIF NIF CDT003 Configuration information for the Piccolo components (Pipeman and the NIF programs) is read from a single Piccolo configuration file which is required to exist and to be readable by the Piccolo components at all times while the system is running. Along with other information, the configuration file contains the unique name of the machine on which Piccolo is running. This means that every Piccolo configuration file on the host and workstation must be different. Note. Do not alter the Piccolo configuration file while Piccolo is running. On Windows and Non Stop platforms, the PIPEMAN process locks its configuration file for read access, and holds that lock for as long as Piccolo continues running. On UNIX platforms, the file is not locked by Piccolo; changing the file while Piccolo is running will result in unpredictable behavior. 5-3

52 Configuring the RSC/MP Transport (Piccolo) Configuring Piccolo (general instructions) On systems that use a single Pipeman process, you should isolate the TDP, the RSC/MP client application, and the RSCPIPE process from the Piccolo configuration file on their respective systems. However, on systems requiring multiple concurrent instances of Piccolo, these processes (through the Piccolo API) must be able to access the configuration file to find the correct Pipeman process. Instructions for configuring multiple instances of Piccolo are discussed Configuring Multiple Instances of Piccolo (for advanced installations) on page 5-5. Configuring Piccolo (general instructions) Before configuring Piccolo, determine whether you need to run multiple concurrent instances of Piccolo. For most installations, a single instance is sufficient. A single Pipeman instance can support multiple TDP processes (on the host) or multiple RSCPIPE and/or RSC/MP application processes (on the workstation). Multiple concurrent instances can be useful when there are classes of users or services that must be kept isolated from each other, for example, when supporting development and production environments simultaneously on a single system. Any given TDP or RSCPIPE can communicate with only a single Piccolo instance, so the use of multiple Piccolo instances makes sense only when multiple, fully isolated TDP or RSCPIPE instances are planned. To configure Piccolo, you will create one or more Piccolo configuration files. These files are plain text files that can be created and maintained using an ordinary text editor. The format and content of the Piccolo configuration file is described in Creating the Configuration File (for all installations) on page Note. The RSC/MP Configuration Wizard (RSCCONFIG.EXE file) is included with Windows RSC/MP packages. The Wizard provides an alternate, possibly more convenient way, to create a Piccolo configuration file on the Windows platform only. Because the configuration file format is simple, and text editors are available on all platforms, this guide describes the configuration file format itself, rather than specific help on the Wizard. 5-4

53 Configuring the RSC/MP Transport (Piccolo) Configuring a Single Instance of Piccolo (for mos t installations) Configuring a Single Instance of Piccolo (for most installations) By default, the Pipeman and NIF processes search for a configuration file named PIPEINI (on the NonStop host) or PIPE.INI (on all workstation platforms) located in the same subvolume or directory in which Pipeman is started. Using this default name and location is recommended, and is suitable for all systems that will run a single instance of Piccolo. Figure 5-2. Components in a Single Instance of Piccolo NonStop Host Workstation RSC/MP application TDP PIPEMAN PIPEMAN RSCPIPE NIF NIF optional optional required Piccolo configuration file Piccolo configuration file required CDT004 If the default configuration file cannot be opened in the current directory, the Piccolo components search additional directories according to the PATH environment variable, until a file having the default name is found and opened successfully. This behavior can be exploited in cases where the configuration file must be kept in a different location than the RSC/MP and Piccolo executable files. Configuring Multiple Instances of Piccolo (for advanced installations) To run multiple concurrent instances of Piccolo, each Pipeman process must be configured by a separate configuration file which will contain a unique identifier. This identifier, called the IPC key, allows Pipeman to communicate with its network interfaces (NIFs), and allows a TDP, RSCPIPE, or RSC/MP application to communicate with a specific Pipeman process. The IPC key specified in the Piccolo configuration file has a format and interpretation that depends on the operating system: 5-5

54 Configuring the RSC/MP Transport (Piccolo) Configuring Multiple Instances of Piccolo (for advanced installations) On the NonStop host, the IPC key is the process name of the Pipeman process for example, $PIPE1, $PIPE2, and so on. The default IPC key is $PIPE. On UNIX workstations, the IPC key is the full name of an existing file or directory that will not change while Pipeman is running for example, /usr/users/rsc_production, /usr/users/rsc_debug, /usr/users/rsc_run/pipe.ini, and so on. The default IPC key is /etc. On Windows workstations, the IPC key names a Windows kernel object that Piccolo will create in the global namespace. The IPC key is a case-sensitive string of up to 255 characters that must not contain a backslash character (\). The default IPC key is piccolo. Note. When RSC/MP is installed as a service on the Windows platform, only one Piccolo instance is allowed. The Piccolo configuration file is required to be named pipe.ini and to reside in the bin subdirectory under the RSC/MP product installation directory. The default IPC key must be used. If an IPC key with a name other than the default piccolo is included in the Piccolo configuration file, errors will occur during the installation process. The following discussion of Multiple Instances of Piccolo is applicable only when RSC/MP is installed but NOT run as a service. When the IPC key is missing from the configuration file or the configuration file cannot be read the default IPC key is used. Therefore, in multi-instance installations, all Piccolo configuration files must contain the correct IPC keys, and all RSC/MP components must have access to the correct Piccolo configuration files. The Piccolo Control Program (PIPECP) will indicate which configuration file it found when it starts. RSC/MP components use the following search sequence to locate Piccolo configuration files: 1. Expand the PIPEINI environment variable, if it exists, and use the result as the fully qualified path and file name of the configuration file. (Do not confuse this environment variable name with the default Piccolo configuration file name for NonStop host, which is also PIPEINI.) 2. If the PIPEINI environment variable is not set, then attempt to open the default configuration file PIPEINI (on the NonStop host) or PIPE.INI (on all workstation platforms) located in the current directory. 3. If the default configuration file is not found in the current directory, then search for the default configuration file in other directories according to the PATH environment variable. The recommended approach is to use the PIPEINI environment variable to guide each TDP, RSCPIPE, or RSC/MP application directly to the correct configuration file in all cases where one must be found. Compared with PATH searches, this approach is less error-prone from a maintenance viewpoint. Note. A system reboot may be required after setting, changing or deleting the PIPEINI environment variable to be certain the correct path is found/used. 5-6

55 Configuring the RSC/MP Transport (Piccolo) Managing Multiple Instances of Piccolo (for advanced installations) Managing Multiple Instances of Piccolo (for advanced installations) For platforms that support multiple instances of Piccolo, changing the configuration file name allows for convenient management of the multiple configurations. For example, you can name each configuration file differently, such as PIPEINI1, PIPEINI2, and so on. The CFGSW command facilitates the management of multiple Piccolo instances on UNIX workstations and the NonStop host. This command switches the configuration file to be used by PIPECP for subsequent commands. Use of the CFGSW configfilename command is equivalent to quitting from PIPECP, setting the environment variable PIPEINI to configfile-name, and restarting PIPECP. The syntax of the CFGSW command is: CFGSW [configfile-name] or CF [configfile-name] The single, optional argument specifies the fully qualified file name of the desired configuration file. If this file name is omitted, CFGSW reports the name of the current configuration file. The following example shows that the current configuration file is PIPEINI, and that the Piccolo instance described by that file is not running: pipecp> cfgsw PIPEINI: \SYSA.$DISKA.VOL1.PIPEINI IPC Key: $PIPE Piccolo is not running. To switch to use a different configuration file for subsequent commands, enter the fully qualified file name: pipecp> cfgsw \sysa.$diska.vol1.pipeini2 PIPEINI: \SYSA.$DISKA.VOL1.PIPEINI2 IPC Key: $PIPE2 Piccolo is running. In this example, the output indicates that the alternate Piccolo instance configured by PIPEINI2 is already running. Subsequent PIPECP commands will refer to this instance. Figure 5-3 shows an example configuration in which a production environment is using the default Piccolo instance, and a second Piccolo instance has been set up for development purposes. 5-7

56 Configuring the RSC/MP Transport (Piccolo) Managing Multiple Instances of Piccolo (for advanced installations) Figure 5-3. Multiple Piccolo Environments NonStop Host Production Environment Workstation Production Environment RSC/MP application TDP PIPEMAN PIPEMAN RSCPIPE NIF NIF PIPEINI PIPE.INI Development Environment PA RAM PIPEINI $USER.RSCDEV.PIPEINID Development Environment setenv PIPEINI /user/users/pipe.ini.dev RSC/MP application TDP PIPEMAN PIPEMAN RSCPIPE NIF NIF PIPEINID PIPE.INI.DEV CDT005 When running multiple Piccolo instances, be aware of the following configuration points (the settings are described in Configuration Options Reference on page 5-19): The NIFs owned by the Piccolo instances should not compete for network resources. For example, only a single NIFSOCK instance can use a given TCP/IP service port number so be sure that two instances of Piccolo running TCP/IP are configured to use different ServicePort option settings in their NIFSOCK configurations. 5-8

57 Configuring the RSC/MP Transport (Piccolo) Combining Piccolo and RSC/MP Configuration Settings (workstations only) To get useful log information from multiple Piccolo instances, the Pipeman processes should not compete for a common log file name. Be sure that the LogFileName option setting is unique for each Piccolo instance. Combining Piccolo and RSC/MP Configuration Settings (workstations only) In cases where an RSC/MP configuration file will be used on the workstation, you can combine the Piccolo configuration settings into that file. This action reduces the total number of configuration files, simplifying management of an RSC/MP installation. In order to use a combined configuration file, follow these two steps: 1. Combine the Piccolo configuration settings (as described in the remainder of this section) into the RSC/MP configuration file described in Basic RSC.INI Configuration on page Preserve all sections, as marked by the titles in square brackets. The sequence of sections within the combined file is not significant. For example: [PIPEMAN] SystemName=myworkstation DomainName=mycompany.com NifList=tcp [NIF-tcp] ProgramFile=nifsock [RSC] TERM_NAME=term01 ERROR_FILE=c:\rsc\rsc.err SUBSYSTEM_NAME=RSCPIPE HOST_PIPENAME=mypipe@myhost 2. Set the PIPEINI environment variable to contain the fully qualified file name of the combined configuration file. For example (on Windows): SET PIPEINI=C:\MYRSCAPP\RSC.INI This environment variable must be set before Piccolo is started, regardless of how Piccolo is started (directly or automatically). Note. On Windows platforms, the PIPEMAN process locks its configuration file for read access, and holds the lock for as long as Piccolo continues running. A combined configuration file cannot be edited while Piccolo is running. If your application requires the ability to alter its RSC.INI on the fly, do not use a combined configuration file. 5-9

58 Configuring the RSC/MP Transport (Piccolo) Configuring Using the RSC/MP Configuration Wizard Configuring Using the RSC/MP Configuration Wizard For Windows workstations, you can configure the NIFs by using the RSC/MP Configuration Wizard program. From the Start menu, click on the Configure RSC/MP icon and the screens will guide you through the configuration steps. The first time you configure RSC/MP, you should use the Configuration Wizard to set up a minimal configuration file for the RSC/MP transport (Piccolo) and related options. During the configuration, you can choose to create the RSC.INI and/or PIPE.INI files. These files can later be edited using any text editor. The RSC.INI file contains the RSC/MP application options (such as ACS and Pathway). The PIPE.INI file contains the transport options (such as Pipeman and TCP/IP). To access the online help press the question mark (Help) and position the cursor on a field on the screen. The section of this manual that describes that field displays to assist you. Note. When installing RSC/MP on a Windows workstation, the RSC/MP Configuration Wizard is automatically installed on your workstation. Start the RSC/MP Configuration Wizard program using one of the following methods: Use the RUN command from either the Windows Program Manager or the File Manager: c:\rsc\rscconfig.exe Using the File Manager, find the C:\RSC\RSCCONFIG.EXE file in the directory tree and double-click on the file name. Double-click on the Configure RSC icon in the RSC folder to start the program. Note. Refer to the notation at the end of the Windows Vista and Windows 7 Installation Restrictions section, on page 4-4 for restrictions on using the RSC/MP Configuration Wizard when RSC/MP is installed under the Program Files directory. Creating the Configuration File (for all installations) Each Piccolo configuration file contains a number of sections and each section contains a number of option settings. Section names are shown in square braces (for example, [SECTION]); option settings are shown as name-value pairs using the equals sign (OptionName=OptionSetting). Entries in the configuration file are not case sensitive; capitalization is used in the sample configuration files only to improve readability

59 Configuring the RSC/MP Transport (Piccolo) Creating the Configuration File (for all installations) The section named [PIPEMAN] is required; the section named [RESOLVER] is optional. In addition to these two sections, there must be one section for each network interface (NIF) to be used; the [NIF-nifname] sections are described in Creating the [NIF-nifname] Sections (for all installations) on page A minimal configuration file defines the system name and usually the domain name (which together must uniquely identify the host or workstation on which Piccolo is running) and at least one network interface. This sample configuration file is for a workstation myworkstation.mycompany.com that will connect to NonStop hosts using TCP/IP service port 5001: [PIPEMAN] SystemName=myworkstation DomainName=mycompany.com NifList=tcp [NIF-tcp] ProgramFile=nifsock ServicePort=5001 The NifList entry appears in the [PIPEMAN] section of the configuration file, and gives the names of the network interfaces that should be started automatically when Pipeman is started. The NifList setting can span multiple lines as in the following example: NifList=nif1,nif2,nif3,nif4,nif5 NifList1=nif6,nif7,nif8,nif9,nif10 NifList2= NifList3=nif11,nif12 The number of NIFs that can be specified (horizontally) in any one line is limited to 32 by Piccolo, and effectively to a lesser number if the operating system limits the number of characters per line in the configuration file. NifList=nif1,nif2,nif3,nif4,nif5... nif32 The number of NifList configuration entries (vertically) is limited to 32. These lines must be numbered sequentially; without skipping a value, even if no nifname is listed: NifList=nif1 NifList1=nif2 NifList2= NifList3=nif4... NifList31=nif32 In performing the automatic NIF startup, Pipeman continues processing NifListn lines with increasing n, until it fails to find a line. Existing lines that have empty lists (as with NifList2 in the example above) do not stop this search (in the example, the NIF listed in NifList3 will be started). If the whole line containing NifList2 were omitted, Pipeman would stop searching for additional NIFs to start up. Therefore, nif4 would not be automatically started when Pipeman starts. HP NonStop Remote Server Call (RSC/MP) Installation and Configuration G uide

60 Configuring the RSC/MP Transport (Piccolo) Creating the [PIPEMAN] Section (for all installations) Creating the [PIPEMAN] Section (for all installations) System Names and Addresses Every instance of Pipeman in a network is considered a Piccolo system. Each Piccolo system must have a unique system address. The system address of a Pipeman instance is derived by Piccolo by combining the system name and domain name in its configuration file. The SystemName option is required, except for Windows systems where it can be automatically generated at run-time. The DomainName option is optional. For configurations using network name resolution services (such as Domain Name Services with TCP/IP), these two entries together should give the network node name of the machine when joined with a dot. For example, a NonStop host at myhost.mycompany.com would use: SystemName=myhost DomainName=mycompany.com These names must uniquely identify this machine among all machines connected by Piccolo as part of an RSC/MP installation. In particular, be sure that each workstation has a unique name; two workstations having the same name will fail on attempting to connect with a common host. (The system name generated automatically on Windows workstations is derived from the network interface card s identity; therefore, the generated names should be inherently unique.) Configuring Network Connections A network connection is defined by the Network Interface (NIF) section ([NIF-nifname]). Each NIF section supplies the parameters needed to make and/or receive connections. The information supplied in a NIF section identifies the low-level protocol (TCP/IP for example) and the information needed by the protocol to communicate over the network. For instance, a NIF section for a TCP/IP connection would, as a minimum, state that TCP/IP is the protocol and supply the service port. One or more NIF sections may be defined. The NifList option entry in the [PIPEMAN] section lists the name of one or more network interfaces that should be started when Pipeman starts. Each NIF is identified by an arbitrary name that must match the name in the [NIF-nifname] section header. NIF sections not included in the NifList must be started manually using the PIPECP START nifname command in order to be operable

61 Configuring the RSC/MP Transport (Piccolo) Automatic Startup of Piccolo Automatic Startup of Piccolo Piccolo must be running in order for RSC/MP to be usable. Piccolo can be started directly by using the PIPECP START command, or it can be configured to start automatically when needed by RSC/MP. To use automatic startup, set the AutoStart entry in the [PIPEMAN] section to 1: AutoStart=1 Automatic startup can be used on the host, the workstation, or both. If used on the host, the TDP starts Piccolo. If used on the workstation, Piccolo will be started by the RSC/MP API library when an RSC/MP application makes its first call to RscConnect(). The following conditions must be met: 1. The TDP (on the host) or RSC/MP application process (on the workstation) must be able to locate and read the Piccolo configuration file. Therefore, you should set the PIPEINI environment variable to contain the fully qualified file name of the Piccolo configuration file before running the TDP or the RSC/MP application. The TDP or RSC/MP application must have read access to the Piccolo configuration file (see Figure 5-2 and consider the access marked optional to be r equired for automatic startup). 2. The TDP or RSC/MP application process must be able to execute the Piccolo PIPEMAN executable. On the host, PIPEMAN should be installed to the same subvolume that holds the TDP executable. This is its default installation location. On the workstation, the PIPEMAN executable ( pipeman on UNIX, pipeman.exe on Windows) must be present in the RSC/MP application process's current working directory, or must be found in a directory named in the PATH environment variable. In this regard, automatic startup of PIPEMAN works just the same as the automatic startup of RSCPIPE. Therefore, the PIPEMAN and RSCPIPE executables should generally be located in the same directory, as they are in a default installation of the RSC/MP product. 3. On Windows, RSC/MP must not be installed as a service. (Instead of using the AutoStart option, RSC/MP can be installed as a service and configured to start automatically when the system starts up. See Running RSC/MP as a Service on page 4-8 for information on installing RSC/MP as a service.) Large Message Support In its default configuration, Piccolo provides the support necessary for RSC/MP to transfer messages of up to bytes, which was the maximum message size for RscWrite, RscWriteRead, and UMS message traffic in all versions prior to RSC/MP

62 Configuring the RSC/MP Transport (Piccolo) Large-Message Support Starting with RSC/MP 7.0, the maximum message size has been increased from bytes to bytes for RscWrite and RscWriteRead to a named server. Where applications require the new expanded maximum message size, Piccolo must be explicitly configured on both the host and the workstation to provide large-message support. If either the host or the workstation is not configured to allow large messages, then the lesser limit of bytes will apply to RscWrite and RscWriteRead traffic, and attempts to send UMS messages larger than bytes will cause incorrect operation. To configure Piccolo for large-message support, set the EnableLargeMessages entry in the [PIPEMAN] section to 1: EnableLargeMessages=1 The following conditions must be met in order to use large messages successfully: Piccolo must be configured for large-message support on both the host and the workstation. This configuration can be verified by using the PIPECP utility. If the correct configuration setting has been made, the output of the PIPECP STATUS should include the following line: Large Messages: Enabled The TDP (on the host), RSCPIPE, and RSC/MP application processes (on the workstation) all must be able to locate and read the Piccolo configuration file. Therefore, set the PIPEINI environment variable to contain the fully qualified file name of the Piccolo configuration file before any TDP or client-side processes are run. The TDP (on the host), RSCPIPE, and RSC/MP application processes (on the workstation) must have read access to the Piccolo configuration file (see Components in a Single Instance of Piccolo on page 5-5 and consider the access marked optional to be required when large messages will be used). The NonStop operating system must be RVU D48 or higher. If the NonStop RVU is insufficient to allow Piccolo to provide large-message support, and EnableLargeMessages=1 is added to the [PIPEMAN] section of the Piccolo configuration file,the output of PIPECP STATUS will include the following: Large Messages: Not available Failure to meet any of these conditions will result in incorrect operation. In particular, if the TDP does not run with a correct PARAM PIPEINI or if a workstation-side RSC/MP process (either RSCPIPE or the RSC/MP application) does not run with a correct PIPEINI environment variable value, RSC/MP will fail to transfer large messages even when the PIPECP STATUS output indicates that large messages are enabled

63 Configuring the RSC/MP Transport (Piccolo) Optional Entries The PIPECP STATUS LINKS command indicates which links are capable of processing large messages. Within the ver (version) column, a three-digit number specifies the version of the Piccolo software that is running at the remote end of the link. When executed on the host, PIPECP STATUS LINKS shows client version information. When executed on the client, PIPECP STATUS LINKS shows host version information. Immediately following the three digit version number, the letter L will be shown for links across which large messages can be sent. The letter L indicates both the client and the host are properly configured for large messages. The absence of the letter L indicates that either the client or the host has not been successfully configured for large-message support. Optional Entries Other optional entries can be given in the [PIPEMAN] section. These entities are listed in the [PIPEMAN] configuration reference Configuration Options Reference on page Creating the [RESOLVER] Section (optional, for workstations only) Use the [RESOLVER] section to allow a workstation to reach hosts that are not reachable by name through your network name resolution facilities. You must use a Resolver section if: 1. Name Resolution Services are not available to your system. 2. Name Resolution Services are available but you want to override it to use a specific address to identify a particular host. 3. You are using the NetBIOS transport to a NonStop (NBT). In the preferred mode of operation, Piccolo relies upon your network name-resolution facilities to reach an RSC/MP host by name. For example, a workstation running TCP/IP might use Domain Name Services (DNS) to convert the name myhost.mycompany.com into an IP address when connecting to the host. You should use the [RESOLVER] section if: Your network is not configured to provide DNS. You need to override the DNS behavior. You use a network protocol that doesn t support name resolution at all

64 Configuring the RSC/MP Transport (Piccolo) Creating the [RESOLVER] Section (optional, for workstations only) Each entry in the [RESOLVER] section gives the detailed information that a network interface (NIF) needs to reach the remote host. Several alternative methods can be supplied for a given system; in this case, the methods will be attempted in order from left to right. The format of each particular method in a [RESOLVER] entry depends upon the NIF that will process it; the specifics of these formats are described in the NIF reference sections of this guide in these sections: Section 7, NetBIOS Network Interface Configuration Section 8, TCP/IP Network Interface Configuration The following is a sample [RESOLVER] section: [RESOLVER] hosta.mycompany.com=ip: hostb.mycompany.com=ip: hostd.mycompany.com=ip:* A workstation configured this way will take special steps when contacting any of the hosts listed: Host HOSTA How contacted TCP/IP at IP address (using the NIF s default service port). HOSTB TCP/IP at IP address , using service port HOSTC Try TCP/IP (using network name resolution). For any host not listed in the [RESOLVER] section, the normal rules would be followed (using the running NIF s default rules for connecting)

65 Configuring the RSC/MP Transport (Piccolo) Specifying Piccolo Logging Specifying Piccolo Logging All Piccolo log messages are written to a text file by the Pipeman process. The location, size, and detail level of the logs can be specified using the LogFileName, LogFileEntries, and LogLevel options in the [PIPEMAN] section of the configuration file. The LogFileName option specifies the name of the primary log file. The Pipeman process also maintains up to ten secondary log files which are created when the PIPECP LOGSWITCH command is used or when the LogFileEntries value has been exceeded. The secondary log file names consist of the concatenation of the primary log file name and a single digit from 0 through 9, with 0 being the newest and 9 being the oldest copy of the primary log file. When the number of log files exceeds the number of entries specified by the LogFileEntries option, the log files are rolled over as follows: The secondary log file 9, if present, is deleted. The secondary log files are rolled over (for example, file 8 is renamed as file 9, file 7 is renamed as file 8, and so on). The primary log file is renamed as secondary log file 0. A new primary log file is opened. Available disk space and performance are the main considerations when selecting the location and attributes of the log file. Enough disk space must exist to accommodate the specified log entries. If disk space is insufficient for log messages to be written, the Pipeman process suspends logging. When sufficient disk space is made available, logging can be re-enabled using the PIPECP LOGSWITCH command. Details about log level and size specification can be found in Configuration Options Reference on page Because the Pipeman process opens the primary log file for exclusive access, you cannot view the primary log file while the Pipeman process is running. To view the primary log file you must stop the Pipeman process or roll the log files over using the PIPECP LOGSWITCH command. Alternatively, you can also use the PIPECP LOGVIEW command to display log events. See PIPECP Commands on page 9-2 for more information about the PIPECP commands that manage log activity

66 Configuring the RSC/MP Transport (Piccolo) Creating the [NIF-nifname] Sections (for all installations) Creating the [NIF-nifname] Sections (for all installations) Each network interface (NIF) must have its own configuration file section. The protocolspecific content of these sections is described in each NIF-specific section later in this guide. Section 7, NetBIOS Network Interface Configuration Section 8, TCP/IP Network Interface Configuration For simple installations, you will have only a single NIF, corresponding to the available network protocol. In more sophisticated installations involving multiple network protocols or alternative paths, you will use multiple NIFs. When configuring multiple NIFs on a workstation, use the Priority option entries of the [NIF-nifname] sections to guide Piccolo in its connection attempt sequence. NIFs that have lower Priority values are tried first. Consider the following sample configuration: [NIF-tcp1] Priority=10 ProgramFile=nifsock ServicePort=5000 [NIF-nb2] Priority=20 ProgramFile=nifnb AdapterNumber=1 In this configuration, the first attempt to reach a host will be made over TCP/IP (by the NIF named tcp1, which has priority 10). If the host cannot be reached over TCP/IP, then a connection will be attempted over a NetBIOS network by the NIF named nb2, which has priority 20. Because the TDP does not initiate outbound connections through Piccolo, Priority option entries are not required on the NonStop host

67 Configuring the RSC/MP Transport (Piccolo) Configuration Options Reference Configuration Options Reference The following options are available for configuring the Pipeman section in the PIPE.INI file. Pipeman Section ([PIPEMAN]) The Pipeman section contains configuration options that control the operation of the Pipeman process. These settings are preceded by the section name [PIPEMAN]; they are read by the Pipeman process when it starts and by the TDP, RSCPIPE process, and RSC/MP applications when needed. AutoStart Option The AutoStart option causes the Piccolo system to be started by RSC/MP, subject to the conditions outlined under Automatic Startup of Piccolo on page AutoStart=number number The number 1 to enable automatic startup, or 0 to disable it. Required: No. Default: 0 Platforms: All Example: AutoStart=

68 Configuring the RSC/MP Transport (Piccolo) Pipeman Section ([PIPEMAN]) AutoStartTimeout Option The AutoStartTimeout option works with the AutoStart option. When AutoStart is enabled (set to 1), AutoStartTimeout gives the number of seconds to allow for startup of the PIPEMAN process. The default value should be suitable for most installations. On slow or heavily loaded systems where PIPEMAN takes a long time to start, this setting can be increased to prevent RSC/MP from reporting Piccolo error 12 (PIPERC_PIPEMAN_NOT_RUNNING) falsely when Piccolo is being started automatically. AutoStartTimeout=number number The number of seconds to allow for startup of the PIPEMAN process. Required: No. Default: 10 Platforms: All Example: AutoStartTimeout=30 BackupCPU Option The BackupCPU option specifies the CPU on which the Pipeman backup process should be started at Piccolo start-up. If this option is not specified, no backup process is started. If the option is not valid (number out of range, CPUs listed not started, or CPUs listed not available), a critical log message is displayed and Pipeman will not start. BackupCPU=number,number,number... number An integer from 0 through 15, which is the number of an installed and running CPU. If the first CPU in the list is down, the next CPU in the list will be tried. Required: No. Default: None. Platforms: NonStop Example: BackupCPU=1,2,

69 Configuring the RSC/MP Transport (Piccolo) Pipeman Section ([PIPEMAN]) CPU Option The CPU option defines the number of the CPU on which the process is to run. CPU=number number An integer from 0 through 15. Required: Default: No. Platforms: NonStop Example: CPU=1 For Pipeman sections: The CPU on which the PIPECP is running that starts PIPEMAN. For NIF sections: The CPU in which the Pipeman process is running. DomainName Option The DomainName option defines the addressing domain of the local system. DomainName=string string The system name (see SystemName Option on page 5-33) and domain name are concatenated to form the system address, which can be no more than 46 characters in length. The DomainName may contain only the following characters: A through Z, a through z, 0 through 9, period (.) and hyphen (-). Required: Default: No Platforms: All Examples: None. Valid domain names: 1. DomainName=corsof.com 2. DomainName=building02.production.acme.com Invalid domain names: 1. This example contains invalid character &: DomainName=building02.R&D.acme.com 5-2 1

70 Configuring the RSC/MP Transport (Piccolo) Pipeman Section ([PIPEMAN]) 2. In this example, the name is too long; the system address is more than 46 characters: westwing.building02.campus04.widgit.company.com EnableLargeMessages Option The EnableLargeMessages option enables support for large messages (greater than bytes, up to bytes). Ability to use large messages is subject to the system and configuration constraints described in Large-Message Support on page EnableLargeMessages=number number A value of 1 enables large message support; a value of 0 disables it. Required: No. Default: 0 Platforms: All Example: EnableLargeMessages=1 IN Option The IN option specifies the IN file for the Pipeman process. IN=filename filename A valid file name. DEFINES are not supported. Required: Default: No. Platforms: NonStop Example: IN=$CONSOLE For Pipeman sections: The IN file for PIPECP that starts the Pipeman process. For NIF sections: The IN file of the Pipeman process

71 Configuring the RSC/MP Transport (Piccolo) Pipeman Section ([PIPEMAN]) IpcKey Option The IpcKey option defines a unique Interprocess Communications (IPC) path that will be used to communicate with the Pipeman process. Only use this option if you intend to run multiple, concurrent instances of Piccolo. Refer to Configuring Multiple Instances of Piccolo (for advanced installations) on page 5-5 for additional details. When installing RSC/MP as a service on Windows, including the IpcKey option in the Piccolo configuration file with a name other than the default piccolo, will result in errors during the installation process. IpcKey=processname (for NonStop) IpcKey=filename (for UNIX) IpcKey=name (for Windows) processname A valid process name that does not already exist when Pipeman is started. filename name The name of an existing file or directory that will not change while Piccolo is running. A string of up to 255 characters; the backslash character (\) is not valid. The string is case-sensitive. Required: Default: No Platforms: All Examples: NonStop: $PIPE UNIX: /etc Windows: piccolo 1. UNIX systems: IpcKey=/usr/rsc/pipe.ini 2. NonStop systems: IpcKey=$PIPE

72 Configuring the RSC/MP Transport (Piccolo) Pipeman Section ([PIPEMAN]) KeepAliveInterval Option The KeepAliveInterval option defines (in seconds) how long before a keepalive packet is generated for an idle pipe. Keepalives are used to detect loss of a network connection that might otherwise go unnoticed due to absence of RSC/MP message traffic. KeepAliveInterval=number number The number of seconds, 1 through 65535; or 0 to disable Piccolo keepalives. Required: Default: No Platforms: All Example: 3600 (1 hour) KeepAliveInterval=300 LogFileEntries Option The LogFileEntries option determines how many log entries will be written to the Piccolo log file before the log is closed, renamed, and a new log file is opened (meaning the log file is rolled over). If the value is set to 0, then the log file is never rolled over and log entries will continue to accumulate until the log is manually deleted or the PIPECP LOGSWITCH command is issued. A logfile containing entries will use 3 to 4 megabytes of disk space. LogFileEntries=number number A valid integer, 1 through 32767; or 0 to disable automatic log file rollover. Required: No Default: Platforms: All Example: LogFileEntries=

73 Configuring the RSC/MP Transport (Piccolo) Pipeman Section ([PIPEMAN]) LogFileName Option The LogFileName option defines the name and location of the Piccolo log files. Any subvolume (for NonStop) or directory (for workstations) can be supplied. Log files are rolled over when they reach the limit specified in the LogFileEntries option, with the last 10 log files being preserved. On log file rollover, the oldest log file name9 is deleted if it exists, any old files name0 through name8 are renamed to name1 through name9, the current file name is renamed to name0, and a new file name is opened as the current log file. Use caution if you do not specify a directory as part of the name because log files will be created in the current working directory of the process that started the Pipeman process, which may not be the desired location. Note. Be sure that the directory and file names supplied with this option are valid, and that the directory (whether explicitly supplied or defaulting to the current directory) can be written by the Pipeman process. If the Pipeman process attempts to log a message of any severity (critical, error, warning, notice, info, and so on as described in the LogLevel option) and fails to write to the log file, then a critical error message will be displayed. LogFileName=name name A valid log file name (optionally including its path). Required: Default: No Platforms: All Example: pipelog Setting LogFileName=c:\logs\piccolo will produce the Primary and Secondary log files: c:\logs\piccolo c:\logs\piccolo0 c:\logs\piccolo1 c:\logs\piccolo2 c:\logs\piccolo3 c:\logs\piccolo4 c:\logs\piccolo5 c:\logs\piccolo6 c:\logs\piccolo7 c:\logs\piccolo8 c:\logs\piccolo

74 Configuring the RSC/MP Transport (Piccolo) Pipeman Section ([PIPEMAN]) LogLevel Option The LogLevel option defines the level of detail that is written to the Piccolo log file. Note. Setting the log level to 8 or greater can have a serious impact on performance and is not recommended, except as specifically directed by HP Global Customer Support Center (GCSC). Piccolo logs each message to the log file with a specific number representing severity or classification. Each such number is defined as a power of two. The LogLevel represents the sum of all values whose associated messages will be written to the log file. The following log levels are of interest to the general user:. 0 Critical Errors that stop Piccolo operation. 1 Error Serious errors that require user intervention. 2 Warning Errors that may require user intervention. 4 Info Informational messages that do not require user intervention. 8 and up Diagnostic information. Use these setting s only when recommended by HP Global Customer Support Center (GCSC). LogLevel=number number An integer in the range 1 through The number represents the sum of all log levels that will be included in the log file. Required: Default: 3 No Platforms: All 5-2 6

75 Configuring the RSC/MP Transport (Piccolo) Pipeman Section ([PIPEMAN]) Examples: 1. This example causes critical level messages to be logged: LogLevel=0 2. This example causes critical, error, warning, and informational messages to be logged: LogLevel=7 (Note that 7 is the sum of 0, 1, 2, and 4, which represent critical, error, warning and informational messages, respectively.) Note. If the LogFileName option is set, logging of critical errors cannot be suppressed. NifGuardTime Option The NifGuardTime option defines the NIF guard time interval in seconds. NifGuardTime is the amount of time Pipeman waits before trying to restart a NIF that is slow to start up or cannot start due to a resource failure. This option prevents Pipeman from unnecessarily restarting a NIF that takes a longer time to register with Pipeman. Note. Do not alter this value unless instructed to do so by HP Global Customer Support Center (GCSC). NifGuardTime=interval interval The number of seconds, as an integer from 0 through Required: No Default: 15 Platforms: All Example: NifGuardTime=

76 Configuring the RSC/MP Transport (Piccolo) Pipeman Section ([PIPEMAN]) NifList Option The NifList option contains a list of network interface symbolic names, separated by commas, that should be started automatically when Pipeman starts. For each NIF name listed, there must be a corresponding network interface section [NIF-nifname] in the Piccolo configuration file. NIF sections not included in a NifList must be started manually using the PIPECP START nifname command to be operable. Multiple lists of NIFs to be started automatically may be supplied. These entries must be identified as NifList, NifList1, NifList2, NifList3,..., NifList31. When Piccolo is started the Pipeman process searches the configuration file for each of these entries in sequence, and stops when it fails to find one. Each NifList entry can contain one NIF name or several, separated by commas. A NifList entry might also list no NIFs (that is, no text to the right of the equals-sign); in this case, Pipeman will continue with the next number in sequence. NifList=nif1,nif2,nif3,nif4,nif5 NifList1=nif6,nif7,nif8,nif9,nif10 NifList2= NifList3=nif11,nif12 NifList4=nif13 Note. You must not leave gaps in the numbering sequence of the NifList identifiers. For example, in the sample above, you cannot omit the line containing NifList2 because Pipeman would stop searching for additional NIFs to start up. Therefore, nif11, nif12, and nif13 would not be automatically started when Pipeman starts. The limit to the total number of NIFs is 32, regardless of how their names are divided among the NifList configuration entries. While there is no explicit limit to the number of NIFs that can be listed in one configuration entry, the configuration file reader limits the total line length to 2048 characters, and there might be additional, platform-specific limitations that apply to the configuration file (for example, maximum line length of an EDIT file on the NonStop platform). In addition, the combination of all NIFs in all the NIF lists cannot exceed 2048 characters. NifList[number]=[nifname, nifname... ] nifname The name of the NIF section must be the same name as used in the NifList. Any NIF not in the NifList will have to be started manually using the PIPECP START command. Required: Default: No Platforms: All None 5-2 8

77 Configuring the RSC/MP Transport (Piccolo) Pipeman Section ([PIPEMAN]) Example: If the configuration file contains this NifList option in the Pipeman section: NifList=mytcpip, mynetbios, mynifsamp Then the following sections must also exist in the file: [NIF-mytcpip] [NIF-mynetbios] [NIF-mynifsamp] OUT Option The OUT option specifies the OUT file for the Pipeman process. OUT=filename filename A valid file name. Required: Default: No. Platforms: NonStop Example: For Pipeman sections: The OUT file for PIPECP that starts the Pipeman process. OUT=$CONSOLE For NIF sections: The OUT file of the Pipeman process

78 Configuring the RSC/MP Transport (Piccolo) Pipeman Section ([PIPEMAN]) PRI Option The PRI option specifies the execution priority of the Pipeman process. A process that has a higher number will run first. PRI=priority priority A valid integer in the range 1 through 199. Required: Default: No. Platforms: NonStop Example: PRI=128 For Pipeman sections: 1 less than the priority of the PIPECP that starts Pipeman. For NIF sections: The priority of the Pipeman process. RingBufferSize Option The RingBufferSize option sets the size of an internal buffer that Piccolo uses in queuing requests from RSC/MP client and system processes to the PIPEMAN process. The default value should be suitable for most installations. Note. Do not alter this value unless instructed to do so by HP Global Customer Support (GCSC). RingBufferSize=size size The number of slots in the circular IPC input buffer used by the PIPEMAN process. The valid range is an integer from 1 through Required: No. Default: Platforms: Windows (Win32+TSE client only) Example: RingBufferSize=

79 Configuring the RSC/MP Transport (Piccolo) Pipeman Section ([PIPEMAN]) SilentWindowsShutdown Option The SilentWindowsShutdown option defines whether Pipeman will check for running Piccolo clients when Pipeman is stopping as part of an operating system shutdown. This option is effective only under the following conditions: Pipeman is running on the Windows operating system Piccolo is not running as a service Pipeman is stopping as the result of an operating system shut down. This option does not affect Pipeman stopping due to the PIPECP STOP command or other manual methods, such as closing the Pipeman icon in the system taskbar. SilentWindowsShutdown=number number A value of 1 forces Pipeman to shut down without checking for running Piccolo clients; a value of 0 allows Pipeman to check for running Piccolo clients prior to shutting down. Required: Default: 0 No Platforms: Windows Examples: 1. This example causes Pipeman to shut down without checking for running Piccolo clients: SilentWindowsShutdown=1 2. This example causes Pipeman to check for running Piccolo clients : SilentWindowsShutdown=

80 Configuring the RSC/MP Transport (Piccolo) Pipeman Section ([PIPEMAN]) ShowIcon Option The ShowIcon option defines whether Pipeman and all NIF processes should show or hide their icons while they are running. When shown, the icons appear in the system task bar as minimized windows; these cannot be restored or maximized. If RSC/MP is installed as a service, the icons will appear only on the console, and only when the RSC/MP Piccolo service is configured to Allow Service to Interact with Desktop. ShowIcon=number number A value of 1 shows the icon; a value of 0 hides the icon. Required: Default: 0 No Platforms: Windows Examples: 1. This example causes the icons to be displayed: ShowIcon=1 2. This example causes the icons to be hidden: ShowIcon=

81 Configuring the RSC/MP Transport (Piccolo) Pipeman Section ([PIPEMAN]) SystemName Option This option defines the name of the local system. SystemName=string string The system name and domain name (see DomainName Option on page 5-21) are concatenated to form the system address, which can be no more than 46 characters in length. The SystemName may contain only the following characters: A through Z, a through z, 0 through 9, and hyphen (-). The name is not case sensitive and must be unique within the domain. It is understood that Windows systems will be equipped with a network interface card so this option can be omitted and a system name will be assigned when Piccolo starts. The assigned system name is a string of 12 hexadecimal digits that represent the Media Access Controller (MAC) address of the network interface card. Required: Default: Platforms: All Examples: Windows: No UNIX and NonStop: Yes Windows: string of 12-hexadecimal digits representing the MAC address of the network interface card. UNIX and NonStop: None Valid system names: 1. mysystem 2. MySystem 3. System-72 Invalid system names: 1. This example contains an invalid character +: My+System 2. This example contains a period: Joes.PC 5-3 3

82 Configuring the RSC/MP Transport (Piccolo) Pipeman Section ([PIPEMAN]) T1Interval Option The T1Interval option defines (in seconds) the maximum amount of time Pipeman will wait before re-sending a packet that has not been acknowledged. T1 and T2 are calculated by Pipeman based on the throughput rate of the messages. Note. Do not alter this value unless instructed to do so by HP Global Customer Support Center (GCSC). T1Interval=interval interval The amount of time it takes to send a message of maximum size and receive it back again together with any associated processing time using Link Access Protocol Balanced (LAPB). If T1 expires before an acknowledgment is received for a given message from the destination Piccolo, the source Piccolo will retransmit the message. The valid range is an integer from 1 through Required: No. Default: 16 Platforms: All Example: T1Interval=20 T1Retries Option The T1Retries option defines the maximum retry count on T1 Interval expiration used by Piccolo s internal LAPB implementation. Note. Do not alter this value unless instructed to do so by HP Global Customer Support Center (GCSC). T1Retries=number number The number of times a retry will be attempted when the T1 timer expires. If the T1 timer expires, and an acknowledgment has not been received from the destination, the message is retransmitted, the T1 timer is reset, and the number of retries for the message is incremented by one. Using Link Access Protocol Balanced (LAPB), the T1 timer will expire after the number of seconds set in the T1Interval option. A message is sent from the source Piccolo a maximum of T1Retries times. The valid range is an integer from 0 through Required: No

83 Configuring the RSC/MP Transport (Piccolo) Pipeman Section ([PIPEMAN]) Default: 3 Platforms: All Example: T1Retries=10 T2Interval Option The T2Interval option defines the maximum number of seconds before a packet will be explicitly acknowledged by Pipeman. T1 and T2 are calculated by Pipeman based on the throughput rate of the messages. Note. Do not alter this value unless instructed to do so by HP Global Customer Support Center (GCSC). T2Interval=interval interval By strict definition, T2 is defined to be half the amount of time it takes to send a message of maximum size and receive it back again together with any associated processing time using Link Access Protocol Balance (LAPB). If the T2 timer expires before a message is sent from the destination Piccolo to the source Piccolo, the destination Piccolo will send a message with an explicit acknowledgment to the source Piccolo. The valid range is an integer from 0 through Required: Default: 8 No. Platforms: All Example: T2Interval=10 Term Option The Term option specifies the name of the home terminal for the Pipeman process. Term=terminalname terminalname A valid name for a terminal or process (can also contain a node name). Required: Default: No. Home terminal name of the PIPECP that starts Pipeman

84 Configuring the RSC/MP Transport (Piccolo) Resolver Section ([RESOLVER]) Platforms: NonStop Example: Term=$home Resolver Section ([RESOLVER]) The Resolver section can be included in the PIPE.INI file to map (or resolve) system addresses to corresponding extended addresses. Extended addresses consist of network address tags that are understood by Piccolo and user-defined tags. These tags are preceded by the section name [RESOLVER] and are described in Appendix D, Resolver Reference Tags. SystemAddress = ExtendedAddress SystemAddress The system name of the desired destination system, optionally with the domain name of that system included. ExtendedAddress The NIF-specific address tags and their values. The ExtendedAddress may include multiple tags if there are multiple paths to the named destination system. Required: Default: No Platforms: All Example: None This example shows an extended address for a TCP/IP connection and an extended address for a NetBIOS connection. [RESOLVER] host1.corsof.com=ip: host2.corsof.com=nbname:testnbt 5-3 6

85 6 Installing RSC/MP on UNIX Workstations RSC/MP runs on a variety of UNIX platforms, including the following: RS6000 with AIX HP-9000 with HP-UX HP-9000 with HP-UX Integrity HP-Integrity (Itanium), 32-bit and 64-bit Sun SPARC with Sun Solaris, 32-bit and 64-bit IBM-compatible PC with Sun Solaris IBM-compatible PC with SUSE or RedHat Linux, 32-bit and 64-bit To install RSC/MP on UNIX workstations, do the following: Verify you have the minimum RSC/MP requirements on your workstation by reviewing the documentation on the CD. Perform the installation according to the instructions provided with the CD. Verify that the correct files have been installed (see Files Installed on the UNIX Workstation on page 6-7. Configure the workstation. Start the RSC/MP client. Installation from the CD Follow the installation steps for your particular UNIX platform. This table shows the names of the shared library files: Table 6-1. Shared Library Names (page 1 of 2) Platform Shared Library Names Shared Library Environment Variable AIX OS libpipe.o and librsc.o LIBPATH HP-UX (Integrity) libpipe.so and librsc.so SHLIB_PATH HP-UX libpipe.sl and librsc.sl SHLIB_PATH 6-1

86 Installing RSC/MP on UNIX Workstations Installation from the CD Table 6-1. Shared Library Names (page 2 of 2) Platform Shared Library Names Shared Library Environment Variable Linux Solaris (SPARC) Solaris (x86) libpipe.so and librsc.so (on 32-bit platforms) libpipe64.so and librsc64.so (on 64-bit platforms) libpipe.so.1 (and libpipe.so, a symbolic link to libpipe.so.1) 32-bit platforms librsc.so.1 (and librsc.so, a symbolic link to librsc.so.1) 32-bit platforms libpipe64.so.1 (and libpipe64.so, a symbolic link to libpipe64.so.1) 64-bit platforms librsc64.so.1 (and librsc64.so, a symbolic link to librsc64.so.1) 64-bit platforms libpipe.so.1 (and libpipe.so, a symbolic link to libpipe.so.1) librsc.so.1 (and librsc.so, a symbolic link to librsc.so.1) LD_LIBRARY_PATH LD_LIBRARY_PATH LD_LIBRARY_PATH 6-2

87 Installing RSC/MP on UNIX Workstations Installing on AIX From a CD Installing on AIX from a CD Note. This version of RSC/MP supports multithreaded RSC/MP applications on AIX. Depending on the number of threads required by the application, it might be necessary to adjust the AIX system configuration in order to run the application. For more information, refer to Thread Limitations on UNIX-based Operating Systems under the description of RscRegisterThread in the Remote Server Call (RSC/MP) Programming Manual. 1. Insert the RSC/MP AIX Client CD into a drive attached to a Windows workstation. 2. Navigate to the WS_SW folder on the RSC/MP Client CD. 3. Locate the file RPAIXEXE.TAR. 4. Select one of these installation methods: Transfer the TAR file to the UNIX workstation. The file must be transferred in BINARY mode. Log on to the UNIX workstation, navigate to the directory where the TAR file is stored, and type: tar xvf RPAIXEXE.TAR Transfer the TAR file to the NonStop and then transfer the TAR file to the UNIX workstation. The file must be transferred in BINARY mode. Log on to the UNIX workstation, navigate to the directory where the TAR file is stored, and type: tar xvf RPAIXEXE.TAR 6-3

88 Installing RSC/MP on UNIX Workstations Installing on HP-UX From a CD Installing on HP-UX from a CD Note. This version of RSC/MP supports multithreaded RSC/MP applications on HP-UX. Depending on the number of threads required by the application, it might be necessary to adjust the HP-UX system configuration in order to run the application. For more information, refer to Thread Limitations on UNIX-based Operating Systems under the description of RscRegisterThread in the Remote Server Call (RSC/MP) Programming Manual. 1. Insert the RSC/MP HP-UX Client CD into a drive attached to a Windows workstation. 2. Navigate to the WS_SW folder on the RSC/MP Client CD. Use the file RPHPIEXE.TAR from the SM51/T2827 CD. Use the file RPHPTEXE.TAR from the SM63/T2825 CD. Use the file RPHPIEXE.TAR from the SM48/T2847 CD. 3. Select one of these installation methods: Transfer the TAR file to the UNIX workstation. The file must be transferred in BINARY mode. Log on to the UNIX workstation, navigate to the directory where the TAR file is stored, and type: tar xvf RPHPIEXE.TAR or tar xvf RPHPTEXE.TAR Transfer the TAR file to the NonStop and then transfer the TAR file to the UNIX workstation. The file must be transferred in BINARY mode. Log on to the UNIX workstation, navigate to the directory where the TAR file is stored, and type: tar xvf RPHPIEXE.TAR or tar xvf RPHPTEXE.TAR 6-4

89 Installing RSC/MP on UNIX Workstations Installing on Linux From A CD Installing on Linux from a CD Note. This version of RSC/MP supports multithreaded RSC/MP applications on Linux. Depending on the number of threads required by the application, it might be necessary to adjust the Linux system configuration in order to run the application. For more information, refer to Thread Limitations on UNIX-based Operating Systems under the description of RscRegisterThread in the Remote Server Call (RSC/MP) Programming Manual. 1. Insert the RSC/MP Linux Client CD into a drive attached to a Windows workstation. 2. Navigate to the WS_SW folder on the RSC/MP Client CD. 3. Locate the file RPLINEXE.TAR. 4. Select one of these installation methods: Transfer the TAR file to the UNIX workstation. The file must be transferred in BINARY mode. Log on to the UNIX workstation, navigate to the directory where the TAR file is stored, and type: tar xvf RPLINEXE.TAR Transfer the TAR file to the NonStop and then transfer the TAR file to the UNIX workstation. The file must be transferred in BINARY mode. Log on to the UNIX workstation, navigate to the directory where the TAR file is stored, and type: tar xvf RPLINEXE.TAR 5. When installing on Linux, the RPLINEXE.TAR file contains two additional TAR files, RPLIN32EXE.TAR and RPLIN64EXE.TAR. These are the TAR files containing the 32 and 64-bit clients respectively. Extract the desired client by un-taring the appropriate TAR file with the command: tar xvf RPLIN32EXE.TAR or tar xvf RPLIN64EXE.TAR 6-5

90 Installing RSC/MP on UNIX Workstations Installing on Solaris From A CD Installing on Solaris from a CD Note. The current version of RSC/MP supports multithreaded RSC/MP applications on Solaris. Depending on the number of threads required by the application, it might be necessary to adjust the Solaris system configuration in order to run the application. For more information, refer to Thread Limitations on UNIX-based Operating Systems under the description of RscRegisterThread in the Remote Server Call (RSC/MP) Programming Manual. 1. Insert the RSC/MP Solaris Client CD into a drive attached to a Windows workstation. 2. Navigate to the WS_SW folder on the RSC/MP Client CD. 3. Locate the file RPSOLEXE.TAR. 4. Select one of these installation methods: Transfer the TAR file to the UNIX workstation. The file must be transferred in BINARY mode. Log on to the UNIX workstation, navigate to the directory where the TAR file is stored, and type: tar xvf RPSOLEXE.TAR Transfer the TAR file to the NonStop and then transfer the TAR file to the UNIX workstation. The file must be transferred in BINARY mode. Log on to the UNIX workstation, navigate to the directory where the TAR file is stored, and type: tar xvf RPSOLEXE.TAR 5. When installing on Solaris (SPARC), the RPSOLEXE.TAR file contains two additional TAR files, RPSOL32EXE.TAR and RPSOL64EXE.TAR. These are the TAR files containing the 32 and 64-bit clients respectively. Extract the desired client by un-taring the appropriate TAR file with the command: tar xvf RPSOL32EXE.TAR or tar xvf RPSOL64EXE.TAR 6-6

91 Installing RSC/MP on UNIX Workstations Files Installed on the UNIX Workstation Files Installed on the UNIX Workstation The files installed on a workstation vary with the platform. The following table lists files using Solaris (x86) as an example. Shared library filenames vary according to system convention. Table 6-2. Files Installed on the UNIX Workstation Directory File Name Description Required for product use? libpipe.so Piccolo shared library yes 1 librsc.so RSC/MP API shared library yes 1 nifsock TCP/IP protocol network interface yes pcfgchk Piccolo configuration file check program no pipecp Pipe transport control program yes pipeman Pipe transport manager yes RSC.ERR RSC/MP error message reference file yes rsc.h RSC/MP.API includes yes rscpipe.exe RSC/MP I/O manager yes rsctest.c RSC/MP test console application source no rsctest.e RSC/MP test console application program no rsctest.mak RSC/MP test application make file no rscvproc.e RSC/MP client VPROC utility no samples java Folder containing sample Java application. no 2 pipe.ini 3 sample Piccolo configuration file yes, copy to installation directory RSC.INI 3 sample RSC/MP configuration file yes, copy to installation directory umsclient.c umsclient.e Unsolicited Message Service (UMS) sample source code. Unsolicited Message Service (UMS) sample program. 1. See Table 6-1 on page 6-1 for actual shared library names for your platform. 2. Available on AIX, HP-UX, and Solaris. Not available on SUSE Linux. 3. Lowercase pipe.ini and uppercase RSC.INI are required for default file names but can be overridden by use of PIPEINI environment variable (Section 6) or programmatically by using RscLoadOptions (see RSC/MP Programming Manual). no no 6-7

92 Installing RSC/MP on UNIX Workstations IPC Resource Requirements IPC Resource Requirements RSC/MP makes use of certain System V IPC resources in transferring messages between RSC/MP client processes and the PIPEMAN process and between PIPEMAN and NIF processes. In order for RSC/MP to operate correctly, certain system parameters may need to be adjusted to reflect some absolute and usage-based IPC requirements. System V Shared Memory RSC/MP uses shared memory segments ranging in size from 256 to bytes (up to if using the EnableLargeMessages option). SHMMIN (minimum size of shared memory segment) must be less than or equal to 256. SHMMAX (maximum size of a shared memory segment) must be greater than or equal to (57344 if using the EnableLargeMessages option). The PIPEMAN and NIF processes use shared memory segments to send messages to each other asynchronously. The number of messages that will be in transit at any given time will depend on traffic (volume and timing of the RSC/MP data being sent and received over the network), overall load on the system, and the Piccolo logging level. The per-process PIPEMAN and NIF requirements will range from just one or two segments on an unburdened Piccolo installation to several hundred on a busy system where Piccolo is running at a LogLevel of 8 or higher. SHMMNI (maximum number of shared memory segments for one process) must be large enough to accommodate all the messages that might be in transit from PIPEMAN or a NIF process at any given time. Single-threaded RSC/MP client processes use one shared memory segment each. Multi-threaded RSC/MP client process (supported on HP-UX, Solaris, AIX and Linux) use one segment for each thread that registers using RscRegisterThread, plus one segment for the main thread. Each instance of the RSCPIPE uses one segment. SHMSEG (maximum number of shared memory segments in the system) must be large enough to accommodate the total requirements of RSC/MP clients, RSCPIPE, PIPEMAN and NIF processes, in addition to the requirements of all other software running in the system. 6-8

93 Installing RSC/MP on UNIX Workstations System V Message Queues System V Message Queues RSC/MP uses message queues with messages of exactly 4 bytes in size. MSGMAX (maximum size of a message) must be greater than or equal to 4. The PIPEMAN and NIF processes use one message queue each. MSGMNI (number of unique message queue identifiers) must be greater than the total number of PIPEMAN and NIF processes that will run concurrently, plus the requirements of all other software running on the system. One System V message is used for every PIPEMAN or NIF message that is conveyed through shared memory. The number of System V messages required will be approximately equal to the number of shared memory segments which depends on network traffic as described above in the discussion of shared memory. MSGMNB (maximum number of bytes in a message queue) must be large enough to accommodate all the messages that might be in transit to a PIPEMAN or a NIF process at any given time, counting 4 bytes per message; or a larger value if so dictated by requirements of other software running in the system. MSGTQL (number of message headers) must be large enough to accommodate all the messages that might be in transit to all PIPEMAN and NIF processes at any given time, plus the requirements of all other software running in the system. System V Semaphores Each PIPEMAN process creates a single semaphore set containing a single semaphore. SEMMNI (maximum number of system wide semaphore sets) and SEMMNS (maximum number of semaphores in the system) must both be greater than or equal to the number of PIPEMAN processes, plus the requirement from all other software running in the system. 6-9

94 Installing RSC/MP on UNIX Workstations System V Message Queues 6-1 0

95 7 NetBIOS Network Interface Configuration This section shows how to configure the NetBIOS Network Interface (NIF) by: Setting up addressing. Using the options in the PIPE.INI file. The NetBIOS network interface (NIFNB) is used to transmit RSC/MP data over a NetBIOS network. Each host and workstation must be configured with its own Pipeman process and network interface. All traffic between the two systems is transmitted on a single NetBIOS session, regardless of the number of logical connections that exist between the two systems. The NetBIOS NIF provides two methods of address resolution: Its own address resolution by the implementation of an address resolution protocol for those NetBIOS implementations that support broadcast (the default). A user-defined session name for those NetBIOS implementations that do not support broadcast. Access to these systems require using the Resolver section. See Creating the [RESOLVER] Section (optional, for workstations only) on page 5-15, for more information about the Resolver section. Prerequisites to Configuring To configure the NetBIOS NIF, you should be familiar with the NetBIOS software that is installed on your system. NIFNB NIF naming conventions follow the standard Piccolo NIF naming conventions and may be represented by any symbolic name in the PIPE.INI NifList option. Whatever name is chosen, there must be a unique section specifying the NIF configuration information. Before starting Piccolo on a NonStop NonStop system, you must at a minimum, customize the MultilanLine and MultilanGateway options. See Configuration Options Reference on page 7-2 for more information about the NetBIOS network options that are used in the NIF-nifname section in the PIPE.INI file. NetBIOS Network Interface Addressing NIFNB implements an address resolution protocol (ARP) that provides the easiest way for workstation to contact hosts by name. This ARP is a special function of the Piccolo NIFNB, and should not be confused with any other ARP (such as the ARP included in the standard TCP/IP protocol suite). When configuring RSC/MP over NetBIOS, you must decide whether to use ARP. 7-1

96 NetBIOS Network Interface Configuration Configuration Options Reference ARP uses (and requires) the NetBIOS broadcast feature. If your network configuration supports NetBIOS broadcasting, then you can use ARP. With ARP, all hosts listen on a common group name (by default, ZPIPEARP). To connect with a host, the workstation broadcasts a message containing the desired host s full system name (as defined in the host Piccolo s [Pipeman] section) the SystemName and DomainName options. All hosts receive this broadcast message, but only the target host responds by sending its own session name through which the workstation then communicates privately. When the NetBIOS NIF needs to resolve the address of a remote system, it broadcasts an ARP request message to all systems on the local network that use the same ARP name. When the destination system receives the ARP request, it responds to the source system with a message containing the session name of the destination system. The NIF then uses the session name to establish a NetBIOS session for data transfer. Note. The NonStop implementations of NBT and NBX do not support the broadcast feature. They require configuration of NBName and the use of the Resolver section. Configuration of the NBName in the Resolver section overrides the ARP, so that the NIF will not use the NetBIOS broadcast. Each NBName must be unique across the network. Systems that do not support broadcast must use the Resolver section in which the destination SystemName is matched with its assigned NBName. The NetBIOS NIF allows up to 16 NBName tags to be specified in a single extended address. The address tags are processed from left to right. The NIF will try to connect to the address specified by each tag until a connection is established or the tags are exhausted. A sample NetBIOS resolver entry is: test.corsof.com=nbname:host2,nbname:host3 Configuration Options Reference The following options are available for configuring the NetBIOS network interface process in the PIPE.INI file. The example configuration file shown later in this section uses some of these options. Network Interface Section ([NIF-nifname]) This NIF section contains options that control the operation of the NetBIOS network. These settings are read by the NIF process when it starts. The settings in this section are preceded by the section name [NIF-nifname], where nifname is the user-defined symbolic name of the NIF. 7-2

97 NetBIOS Network Interface Configuration Network Interface Section ([NIF-nifname]) AdapterNumber Option The AdapterNumber option defines the network adapter number used by the NIFNB. Although there may only be one physical adapter in your system, your NetBIOS interface may use a logical adapter number to indicate the network protocol that the NetBIOS interface should use. Make certain you are using the correct logical adapter number. See your System Administrator for the number of the logical adapter. AdapterNumber=number number A valid adapter number. Required: Default: 0 No Platforms: All Example: AdapterNumber=0 ArpRetries Option Note. Do not alter this value unless instructed to do so by HP Global Customer Support Center (GCSC). The ArpRetries option defines the number of retries for the ARP broadcast message. This option is only used with installations that use ARP. ArpRetries=number number An integer in the range from 0 through Required: No Default: 2 Platforms: All Example: ArpRetries=4 7-3

98 NetBIOS Network Interface Configuration Network Interface Section ([NIF-nifname]) ArpTimeout Option Note. Do not alter this value unless instructed to do so by HP Global Customer Support Center (GCSC). The ArpTimeout option defines the timeout of broadcast name resolution retries. This option is only used with installations that use ARP. ArpTimeout=number number A number in the range from 0 through Required: No Default: 5 Platforms: All Example: ArpTimeout=4 CPU Option The CPU option defines the number of the processor where the process is to run. CPU=number number A numeric value from 0 through 15 Required: No Default: The CPU in which Pipeman is running. Platforms: NonStop Example: CPU=3 7-4

99 NetBIOS Network Interface Configuration Network Interface Section ([NIF-nifname]) DatagramQueue Option The DatagramQueue option defines the maximum number of simultaneous NetBIOS datagram-receives that the NIF will post to the network adapter. The NIF uses datagrams to resolve remote system addresses. Increasing this value increases the use of NCB resources on the network adapter. Decreasing this value may reduce address resolution speed. This option is only used with installations that use ARP. DatagramQueue=number number A number from 1 through 8. Required: Default: 2 No Platforms: All Example: DatagramQueue=1 Domain Option The Domain option defines the suffix for the ARP name used by the network interface. The value is concatenated with the prefix ZPIPE to form the ARP name. All systems that communicate with each other must use the same ARP name. This option is only used with installations that use ARP. Note. This option is not the same as the DomainName option in the [Pipeman] section. They are not related. Domain=name name A name of 1 through 8 alphanumeric characters. Required: No Default: ARP (which forms the default ARP name ZPIPEARP) Platforms: All Example: Domain=DEV 7-5

100 NetBIOS Network Interface Configuration Network Interface Section ([NIF-nifname]) IdleDisconnect Option The IdleDisconnect option defines the number of seconds that a physical network connection will be maintained when no pipes are using the logical connection. IdleDisconnect=number number The number of seconds in the range from 5 through Required: No Default: 60 seconds Platforms: All Example: IdleDisconnect=180 IN Option The IN option defines the IN file for the NIF process. IN=filename filename A valid file name; DEFINES are not supported. Required: No Default: The IN file of the Pipeman process. Platforms: NonStop Example: IN=$CONSOLE 7-6

101 NetBIOS Network Interface Configuration Network Interface Section ([NIF-nifname]) LinkRequestRetriesMax Option The LinkRequestRetriesMax option defines the maximum number of times that Pipeman will attempt to establish a logical link through the NIF to a host before either attempting to use the next NIF in the NifList, or returning a PIPERC_PATH_FAILURE error. LinkRequestRetriesMax=number number An integer in the range from 1 through Required: Default: 3 No Platforms: All Example: LinkRequestRetriesMax=3 LinkRequestRetryInterval Option The LinkRequestRetryInterval option defines the length of time that the initiating Pipeman will wait for confirmation of establishing a logical link from the destination Pipeman before repeating its request or moving on to another NIF. A longer time interval may be necessary so a response can be received when unexpected conditions are present, such as attempting to connect using an invalid IP address in the Resolver section of the Piccolo configuration file before attempting one that is valid. LinkRequestRetryInterval=number number The number of seconds as an integer in the range from 1 through Required: No Default: 15 Platforms: All Example: LinkRequestRetryInterval=60 7-7

102 NetBIOS Network Interface Configuration Network Interface Section ([NIF-nifname]) ListenQueue Option The ListenQueue option defines the maximum number of NetBIOS LIS TEN NCBs that the network interface posts to the network adapter. Increasing this value increases the use of NCB resources on the network adapter. Decreasing this value may reduce the speed at which connections are established. ListenQueue=number number A number in the range from 1 through 8. Required: Default: 2 No Platforms: All Example: ListenQueue=1 MultilanGateway Option The MultilanGateway option defines the name of the Multilan gateway that the NIF uses. See your System Administrator for the name of the gateway. MultilanGateway=name name The name of an existing Multilan gateway. Required: Only if a Multilan gateway is to be used. Default: None Platforms: NonStop Example: MultilanGateway=#GW1 7-8

103 NetBIOS Network Interface Configuration Network Interface Section ([NIF-nifname]) MultilanLine Option The MultilanLine option defines the device name of the LAN controller that the NIF uses, or the NBT or NBX process name to be used. MultilanLine=name name The process name of the LAN communications subsystem on the local system that supports the Multilan WSPTP interface. See your Multilan documentation for more information. When running over NBT or NBX, supply the NBT or NBX process name. Required: Default: Yes None Platforms: NonStop Examples: 1. When running Multilan: MultilanLine=$LANA 2. When using NBT: MultilanLine=$NBT 3. When using NBX: MultilanLine=$NBX NBCase Option The NBCase option defines if the NBName used by the NIF should be all uppercase (U) or all lowercase (L) letters to allow for the migration of applications. This provides the capability to distinguish this name and session names posted in uppercase used by other applications that use the same session names. Systems that will be communicating with each other must use the same NBCase value. NBCase=U L Required: Default: No L Platforms: All Example: NBCase=U 7-9

104 NetBIOS Network Interface Configuration Network Interface Section ([NIF-nifname]) NBName Option This option is for installations that are NOT using ARP. The NBName option defines the NetBIOS session name used for incoming connections. An NBName can be specified in the Resolver section for outgoing connections. NBName=name name A valid NetBIOS session name. Required: Default: Platforms: All Example: NBName=rsc Yes, when not using ARP; otherwise, not required. Internally generated. NetworkBufferSize Option The NetworkBufferSize option determines the receive buffer size for each NetBIOS connection. The default value is appropriate for all applications. Notes. The ReceiveQueue setting can override this option setting. You should not alter the NetworkBufferSize option value unless instructed to do so by HP Global Customer Support Center (GCSC). NetworkBufferSize=number number A numeric value from 4096 through Required: No Default: Platforms: All Example: NetworkBufferSize=

105 NetBIOS Network Interface Configuration Network Interface Section ([NIF-nifname]) OUT Option The OUT option defines the OUT file for the NIF process. OUT=filename filename A valid file name or process name; DEFINES are not supported. Required: No Default: The OUT file of the Pipeman process. Platforms: NonStop Example: OUT=$CONSOLE PRI Option The PRI option defines the execution priority of the NIF process. PRI=priority priority An integer in the range from 1 through 199. Required: No Default: The priority of the Pipeman process. Platforms: NonStop Example: PRI=

106 NetBIOS Network Interface Configuration Network Interface Section ([NIF-nifname]) Priority Option The Priority option defines the order in which this NIF will be used (if multiple NIFs are configured) when making a connection to a remote node. In attempting to reach a host, Pipeman will first try using the NIF having the lowest priority value, if that fails, then the next higher priority NIF will be tried, and so on. Priority=number number A integer in the range from 0 through Zero is the highest priority. Required: No Default: 20 Platforms: All Example: Priority=10 ProgramFile Option The ProgramFile option defines the name of the executable file that should be run for this NIF. For NetBIOS network interfaces, this value must be NIFNB. ProgramFile=nifnb Required: Default: Yes Platforms: All Example: None ProgramFile=nifnb 7-1 2

107 NetBIOS Network Interface Configuration Network Interface Section ([NIF-nifname]) ReceiveQueue Option The ReceiveQueue option defines the maximum number of NetBIOS receive requests that are posted to the network adapter. Increasing this value increases the use of NCB resources on the network adapter. Decreasing this value may reduce connection throughput. Note that if this value is set to greater than one, the NetworkBufferSize option is automatically set to ReceiveQueue=number number An integer in the range from 1 through 8. Required: No Default: 1 Platforms: All Example: ReceiveQueue=2 Term Option The Term option defines the name of the home terminal for the NIF process. Term=terminalname terminalname A valid name for a terminal or process, which can also include a node name. Required: No Default: The home terminal of the Pipeman process. Platforms: NonStop Example: Term=$home 7-1 3

108 NetBIOS Network Interface Configuration NetBIOS Example PIPE.INI and PIPEINI Configuration Files NetBIOS Example PIPE.INI and PIPEINI Configuration Files Example 1: Using NIFNB ARP (Multilan on the NonStop host). On the host (in the PIPEINI file): [Pipeman] DomainName=mycompany.com SystemName=myhost ; workstation will reach us at this name ; using ARP mechanism... [NIF-mynif] ProgramFile=nifnb MultilanGateway=#GW1 MultilanLine=$LANA On the workstation (in the PIPE.INI file):... [NIF-mynif] ProgramFile=nifnb AdapterNumber=1 Example 2: Using NBT NIFNB (ARP is not available). On the host: [Pipeman] DomainName=mycompany.com SystemName=myhost... [NIF-mynif] ProgramFile=nifnb NBName=mytag ; name by which the workstation will reach us MultilanLine=$NBT 7-1 4

109 NetBIOS Network Interface Configuration NetBIOS Example PIPE.INI and PIPEINI Configuration Files On the workstation:... [NIF-mynif] ProgramFile=nifnb AdapterNumber=1... [Resolver] myhost.mycompany.com=nbname:mytag 7-1 5

110 NetBIOS Network Interface Configuration NetBIOS Example PIPE.INI and PIPEINI Configuration Files 7-1 6

111 8 TCP/IP Network Interface Configuration This section shows how to configure the TCP/IP Network Interface (NIF) by: Setting up addressing. Selecting the TCP/IP port. Using the options in the PIPE.INI file. The TCP/IP network interface (NIFSOCK) transmits data between two Pipeman processes on a TCP/IP network. Each system must be configured with its own Pipeman process and NIF. All traffic between the two systems is transmitted on a single TCP connection, regardless of the number of logical client connections that exist between the two systems. The simplest method of configuration is to use a fixed TCP port number in the configuration of all systems. Using this method, the same port number is set in the PIPE.INI file of all the systems that will communicate with each other The TCP/IP network interface uses either standard TCP/IP name resolution services or Piccolo Extended Addressing to map Piccolo system addresses to TCP/IP network Internet Protocol (IP) addresses. The configuration information is specified in one of the following sections of the PIPE.INI file: The NIF section used to configure the fixed port (ServicePort) used for listens and as the default for outgoing connections. The Resolver section used to configure extended addresses. See Creating the [RESOLVER] Section (optional, for workstations only) on page 5-15 for more information about the Resolver section. Prerequisites to Configuring To configure the TCP/IP network interface, you should be familiar with the TCP/IP software that is installed on your system. NIFSOCK NIF naming conventions follow the standard Piccolo NIF naming convention and may be represented by any symbolic name in the PIPE.INI NifList option. Whatever name is chosen, there must be a unique section specifying the NIF configuration information. See Configuration Options Reference on page 8-3 for more information about the TCP/IP network options that are used in the NIF-nifname section in the PIPE.INI file. 8-1

112 TCP/IP Network Interface Configuration TCP/IP Network Interface Addressing TCP/IP Network Interface Addressing You can use the Resolver section to map system addresses to network addresses. The TCP/IP network interface allows up to 16 IP address tags to be specified in a single extended address. The Resolver section recognizes the formats described in the following table. Table 8-1. Resolver Formats ip:* ip: * ip: ip: ip: ip: IPv6:* IPv6: * ipv6: fe80::cafe:babe IPv4 Uses the IPv4 address resolved through DNS and the service port of the local NIF. When ip:* is detected within an extended address, all other IP addresses in that extended address are ignored. Uses IPv4 address and the service port of the local NIF. Uses IPv4 address and service port IPv6 Uses the IPv6 or IPv4 address resolved through DNS and the service port of the local NIF. When ipv6:* is detected within an extended address, all other IP addresses in that extended address are ignored. Uses IPv6 address fe80::cafe:babe and the service port of the local NIF. Note that double quotes are required for an IPv6 address. ipv6: fe80::cafe:babe.2000 Uses IPv6 address fe80::cafe:babe and service port Note that the service port is always expressed in decimal, despite the standard hexidecimal notation of an IPv6 address. ipv6: ::ffff: ipv6: ::ffff Uses IPv6 embedded IPv4-mapped address and the service port of the local NIF. Uses IPv6 embedded IPv4-mapped address and service port See TCP/IP Example PIPE.INI Configuration File on page 8-12 for more examples. Extended Address Processing The IP portion of an extended address is processed according to specific rules. An extended address may contain both IPv4 tags (ip:) and IPv6 tags (ipv6:). These tags are evaluated by: First collecting all addresses specified with the ipv6: tag, in order from left to right. 8-2

113 TCP/IP Network Interface Configuration Selecting the TCP/IP Port Second collecting all addresses specified with the ip: tag, in order from left to right. During either the first or second collection, a wildcard (ipv6:* or ip:*) will cause IP address collection to stop and all previously collected addresses to be discarded. The wildcard thus overides any and all other IP addresses specified in the extended address. (The wildcard feature is expected to be used when an extended addresses contains both IP and non-ip information.) Once all the addresses have been collected, the NIF will try to connect to each address until either a connection is established or the tags are exhausted. Selecting the TCP/IP Port Piccolo has been assigned port number 2787 by the Internet Assigned Number Authority. This port number is in the Master Services file; however, it is not necessarily found in the Services file on every system. Because the port cannot be shared between different TCP/IP applications, it is important that the port number you select is not being used by another application. Note: Port 2787 is recommended for most RSC/MP installations. If you plan to run more than one instance of Piccolo or more than one NIFSOCK process per Pipeman process on your system, each instance of the network interface must use a different port. However, you must ensure that the port number you choose is not being used by another application. Configuration Options Reference The following options are available for configuring the TCP/IP network interface process in the PIPE.INI file. The example configuration file shown later in this section uses some of these options. Network Interface Section ([NIF-nifname]) This NIF section contains options that control the operation of the TCP/IP network. These settings are read by the NIF process when it starts. The settings in this section are preceded by the section name [NIF-nifname], where nifname is the user-defined symbolic name of the NIF. CPU Option The CPU option defines the number of the processor where the NIF process is to run. CPU=number number A valid numeric value from 0 through

114 TCP/IP Network Interface Configuration Network Interface Section ([NIF-nifname]) Required: Default: No Platforms: NonStop Example: CPU=3 The CPU on which the Pipeman process is running. EnableProtocolKeepAlives Option The EnableProtocolKeepAlives option determines whether the protocol-specific keepalive will be enabled by Piccolo. This option increases network traffic if enabled. EnableProtocolKeepAlives=enabled enabled YES to enable, NO to disable. Required: No Default: NO (disabled) Platforms: All Example: EnableProtocolKeepAlives=YES 8-4

115 TCP/IP Network Interface Configuration Network Interface Section ([NIF-nifname]) IdleDisconnect Option The IdleDisconnect option defines the number of seconds that a physical network connection will be maintained when no pipes are using the logical connection. IdleDisconnect=number number A valid number of seconds in the range 5 through Required: No Default: 60 seconds. Platforms: All Example: IdleDisconnect=180 IN Option The IN option defines the IN file for the NIF process. IN=filename filename A valid file name; DEFINES are not supported. Required: No Default: The IN file for Pipeman. Platforms: NonStop Example: IN=$CONSOLE 8-5

116 TCP/IP Network Interface Configuration Network Interface Section ([NIF-nifname]) LinkRequestRetriesMax Option The LinkRequestRetriesMax option defines the maximum number of times that Pipeman will attempt to establish a logical link through the NIF to a host before either attempting to use the next NIF in the NifList (if there is one), or returning a PIPERC_PATH_FAILURE error (if there isn t one). LinkRequestRetriesMax=number number An integer in the range of 1 through Required: Default: 3 No Platforms: All Example: LinkRequestRetriesMax=3 LinkRequestRetryInterval Option The LinkRequestRetryInterval option defines the length of time that the initiating Pipeman will wait for confirmation of establishing a logical link from the destination Pipeman before reissuing the request. A longer time interval may be necessary so a response can be received when unexpected conditions are present, such as attempting to connect using an invalid IP address in the Resolver section of the Piccolo configuration file before attempting one that is valid. LinkRequestRetryInterval=number number An integer in the range of 1 through Required: No Default: 15 Platforms: All Example: LinkRequestRetryInterval=60 8-6

117 TCP/IP Network Interface Configuration Network Interface Section ([NIF-nifname]) NetworkBufferSize Option The NetworkBufferSize option defines the size of the send and receive buffer for each network connection. This value determines how much data the TCP/IP subsystem will buffer on behalf of the network interface before suspending data transfer. The default value is appropriate for all applications. The value of this option in no way affects the maximum message size that can be sent or received using the Piccolo API. Note. You should not alter this value unless instructed to do so by HP Global Customer Support Center (GCSC). NetworkBufferSize=size size A valid numeric value from 4096 through Required: No Default: Platforms: All Example: NetworkBufferSize=10000 OUT Option The OUT option defines the OUT file for the NIF process. OUT=filename filename A valid file name or process name; DEFINES are not supported. Required: No Default: The OUT file of Pipeman. Platforms: NonStop Example: OUT=$CONSOLE 8-7

118 TCP/IP Network Interface Configuration Network Interface Section ([NIF-nifname]) PRI Option The PRI option defines the execution priority of the NIF process. PRI=priority priority A valid integer in the range 1 through 199. Required: Default: Platforms: Example: PRI=128 No The priority of the Pipeman process. NonStop Priority Option The Priority option defines the order in which this NIF will be used (if multiple NIFs are configured) when making an outbound connection to a remote node. Pipeman will first try the NIF having the lowest priority value, if that fails then the next higher priority NIF will be tried, and so on. Priority=number number A valid numeric value from 0 through Zero is the highest priority. Required: No Default: 10 Platforms: All Example: Priority=

119 TCP/IP Network Interface Configuration Network Interface Section ([NIF-nifname]) ProcessName Option The ProcessName option defines the name of the TCP/IP process to use on NonStop systems. The value must be the process name of a properly configured TCP/IP process on the NonStop system. ProcessName=name name A valid name of a running, properly configured TCP/IP process. Required: Default: No $ZTC0 Platforms: NonStop Example: ProcessName=$ZTC1 ProgramFile Option This option is required. The ProgramFile option defines the program file that should be run for this NIF. For a TCP/IP network interface, this value must be NIFSOCK. ProgramFile=nifsock Required: Default: Yes Platforms: All Example: None ProgramFile=nifsock 8-9

120 TCP/IP Network Interface Configuration Network Interface Section ([NIF-nifname]) ServiceIPAddress Option The ServiceIPAddress option defines a single IP address on which NIFSOCK will listen for incoming connections. Setting this option overrides the default behavior of accepting connections on all IP addresses. The IP address must contain a single, literal IPv4 or IPv6 address or a single hostname. When a hostname is used, the hostname must be resolvable by the getaddrinfo() TCP/IP library function to a SINGLE IP address. If the hostname cannot be resolved, the NIFSOCK will not start. If the hostname resolves to multiple addresses, connections will work intermittently. On startup, NIFSOCK attempts to access the address specified by ServiceIPAddress. If there is a problem accessing the specified address, a critical error is logged to the Piccolo log file and NIFSOCK does not start. If no problem is detected with accessing the specified address, a message indicating which address is being used for input is logged to the Piccolo log file at log level CLOG_TCP (128). In addition to a log entry, the successful activation of ServiceIPAddress can be verified using the PIPECP STATUS NIFS command. The word only is added to the IP address for each NIF that is monitoring a single incoming connection. The following sample output shows two NIFSOCK instances, one of which is constrained by ServiceIPAddress: C:\rsc\bin>pipecp status nifs NIF name Type Process Pri Links Address nifnormal TCP/IP 6c , (port 5000) nifsipopt TCP/IP 6fc only (port 5001) The same service port can be used with different ServiceIPAddress values with no interaction between the different ServiceIPAddress environments, provided the operating system and installed TCP/IP networking software allow it. ServiceIPAddress=address address A literal IPv4 or IPv6 address. A hostname that can be resolved to a single IPv4 or IPv6 address. Required: Default: No Platforms: All Example: All IP addresses ServiceIPAddress= ServiceIPAddress=fe80::cafe:babe ServiceIPAddress=RSCPM.mycompany.com 8-1 0

121 TCP/IP Network Interface Configuration Network Interface Section ([NIF-nifname]) ServiceP ort Option The ServicePort option is a numeric value that defines the TCP/IP service port on which incoming connections will be accepted (NonStop host) or the default TCP/IP service port for outgoing connections (all workstations). The default value of 2787 is recommended because this port number has been assigned to Piccolo by the Internet Assigned Number Authority. ServicePort=number number A valid integer in the range from 1 through Required: No Default: 2787 Platforms: All Example: ServicePort=2787 ;the default service port Term Option The Term option defines the name of the home terminal for the NIF process. Term=terminalname terminalname A valid name for a terminal or process (can also include a node name). Required: No Default: The home terminal of the Pipeman process. Platforms: NonStop Example: Term=$home 8-1 1

122 TCP/IP Network Interface Configuration TCP/IP Example PIPE.INI Configuration File TCP/IP Example PIPE.INI Configuration File In this example, the default service port of 2787 is used. The Resolver section shows three formats of configuring the NIFSOCK NIF. [NIF-mynifsock] ProgramFile=nifsock ;required option ServicePort=2787 ;the default service port [Resolver] ; this example shows the IP address and service ; port boston.corsof.com=ip: ; this example uses the default IP address name resolution for ; your network. accounting.corsof.com=ip:* ; this example will first try to reach the IP address ; and, if that fails, tries to reach the IP address ; and service port sysadmin.corsof.com=ip: ,ip:

123 9 Managing the RSC/MP Transport (Piccolo) This section describes the PIPECP Piccolo control program and commands that you use to manage Piccolo. These commands allow you to start and stop Piccolo; to obtain Pipeman status, NIF status, and version information; and to control Piccolo and NIF event logging. Running the PIPECP Program PIPECP is an interactive program that presents an identical command-oriented interface on all supported platforms. You invoke PIPECP according to the standards of the platform you are using: On Windows systems, select the PIPECP icon in the RSC folder. On Windows systems or UNIX platforms, at the command prompt type: PIPECP On NonStop systems, at the TACL prompt type: > run pipecp PIPECP indicates whether Piccolo is running and enters its interactive mode indicated by the command prompt pipecp>. At this prompt, enter PIPECP commands as described in PIPECP Commands on page 9-2. PIPECP continues accepting commands until you enter the QUIT or EXIT command. PIPECP also supports single-command operation from the system command prompt on all platforms. To execute a single command, include it on the command line after the PIPECP program name. For example, to start Piccolo and return to the system command prompt, type: > pipecp start 9-1

124 Managing the RSC/MP Transport (Piccolo) PIPECP Commands PIPECP Commands Within the PIPECP window, you can enter the following commands at the prompt (pipecp>): BACKUP START cpu BACKUP STOP CFGSW CHECK CONNECT system EXIT (or QUIT) HELP (or?) LOGLEVEL n LOGSWITCH LOGVIEW RESTART START START nifname STATUS STATUS CLIENTS STATUS IPC STATUS LINKS STATUS NIFS Starts the backup process. cpu must be the number of a valid installed and running CPU or a comma-separated list of valid, running CPUs. For NonStop systems only. Stops the backup process. For NonStop systems only. Directs PIPECP to use a different configuration file and communicate with a different Pipeman process. For NonStop and UNIX systems only. For more information about configuring multiple instances of Pipeman, see Configuring Multiple Instances of Piccolo (for advanced installations) on page 5-5. Indicates whether Piccolo is running. Tests connectivity with the named system. system is the name of the local or remote system that you specified in the PIPE.INI file. Exits the PIPECP program. Lists the PIPECP commands. Changes the diagnostic level. Use this command only on the recommendation of HP Global Customer Support Center (GCSC). Closes the current log file and opens a new one. See information about logging in Specifying Piccolo Logging on page Displays saved log events. Restarts the system. Use RESTART -Y to suppress the confirmation prompt. Starts Piccolo. Note that the configuration file must be closed before Piccolo can be started. Starts the Pipeman-specified network interface. Displays general status of Piccolo. Displays status of registered Piccolo clients. Displays statistics about the Piccolo IPC layer (RSC/MP Win32+TSE client only). Displays status of links to other systems. Displays status of NIFs that are currently running. 9-2

125 Managing the RSC/MP Transport (Piccolo) PIPECP Commands STATUS PIPES STOP STOP nifname VERSION filename Displays status of pipes. Stops Piccolo. Use STOP -Y to suppress the confirmation prompt. Stops the specified network interface. Displays the Piccolo version report of an executable file or library. 9-3

126 Managing the RSC/MP Transport (Piccolo) PIPECP Commands 9-4

127 10 Configuring and Managing the RSC/MP TDP Process The Transaction Delivery Process (TDP) is a persistent NonStop process pair that facilitates delivery of messages between the workstation application and host server applications. Through the TDP, a workstation can communicate with any Pathway server or a named NonStop process. RSCCOM is a host process that provides a command interface to configure and control the TDP. See Section 11, RSCCOM Command Reference for descriptions of the TDP management commands provided by RSCCOM. The following steps must be performed in order to configure the TDP process on the host: 1. Start the TDP. 2. Start the RSCCOM process. 3. Configure and start the TDP objects (PIPE and TERM) and their attributes. Optionally, you can also configure the ACS objects and attributes. You configure these objects using RSCCOM commands. Starting the RSC/MP Host Processes RSC/MP provides OBEY files to start and stop the TDP. Also provided are sample TDP and Pathway configuration files. These files will need to be changed to suit your environment. Preserving Your Changes Before you edit these files for your use, you should copy them from the RSC/MP host ISV to another location and make the changes on the new copies. The installation of an RSC/MP host software update will overwrite the files in the RSC/MP host ISV. 9> VOLUME $vol.rscwork 10> FUP DUP $system.zrschost.tdpcfg, * 11> FUP DUP $system.zrschost.startrsc, * 12> FUP DUP $system.zrschost.stoprsc, * 13> FUP DUP $system.zrschost.pwycfg, * 14> FUP DUP $system.zrschost.pipetxt, pipeini 10-1

128 Configuring and Managing the RSC/MP TDP Process Editing the STARTRSC File Editing the STARTRSC File STARTRSC is a sample TDP startup TACL macro and can be used as it is; however, you can make the following changes: If you are not going to pass the volume and subvolume names as an argument when you run the macro, change all the [RSCWORK] references in the STARTRSC file to indicate the volume and subvolume in the format $vol.subvol. If you chose a name for the Piccolo configuration file other than PIPEINI, then you must change the following line setting the PIPEINI environment variable to the actual name of your Piccolo configuration file name. PARAM PIPEINI [RSCWORK].pipeini Determine if you will need to access your host applications as Pathway serverclasses. The following lines start a Pathmon process and configure it to run the RSC/MP test echo server as a Pathway serverclass (TDDSVR). You will need to edit the Pathway configuration file, PWYCFG, adding server configurations for your applications. If you do not need your applications to run in a Pathway environment and you don t wish to run RSCTEST to TDDSVR via Pathsend, you can comment out (by preceding each line with the TACL COMMENT ==) or delete the following lines: PATHMON /NAME $pathmon-process-name, NOWAIT/ PATHCOM /IN [RSCWORK].pathway-configuration-file/ $pathmon-process-name Run the TDP. This command starts the TDP process and optionally specifies, among other things, the CPU its backup will run in, the home terminal, and the standard input and output devices. The general syntax to run the TDP process is: TDP /NAME $process-name, NOWAIT, IN in-file, OUT out-file, & TERM home-term, PRI priority, CPU cpu-num/backup-cpu The OUT and TERM parameters should refer to a permanently configured terminal with a paused TACL. If not specified, these options will default to the terminal ID of the starting TACL. If this OBEY file is run from a Telnet session or other temporary terminal, then the IN, OUT, and TERM options must be added to the command shown below. Failure to do this can cause the TDP process to fail because the assumed device is inaccessible. The CPU in which the backup process will run can either be supplied with the RUN command or via RSCCOM with the CONTROL command. The following steps assume that the TDP and RSCCOM objects are installed in $SYSTEM.SYSTEM. 10-2

129 Configuring and Managing the RSC/MP TDP Process Editing the STARTRSC File Three choices for starting the TDP are presented in the STARTRSC sample TACL macro. The simplest command is active within the file; if another choice is the desired one for starting the TDP, comment out the undesirable command and activate the desirable one. The three choices are: 1. Start the TDP on the same CPU where the current TACL is running: RUN [SYSTEM.SYSTEM.]TDP /NAME $zrsc, NOWAIT/ 2. Start the TDP on a specific CPU (0 in the example below): RUN [SYSTEM.SYSTEM.]TDP /NAME $zrsc, NOWAIT, CPU 0/ 3. Start the TDP on a specific CPU with a backup CPU (0 for the primary and 1 for the backup in the example below): RUN [SYSTEM.SYSTEM.]TDP /NAME $zrsc, NOWAIT, CPU 0/1 Configure the TDP. The DELAY command allows the TDP to initialize completely before RSCCOM attempts to configure it. The value used depends on the processing speed of the NonStop host. Practical values are from 5 to 20 seconds. The TDPCFG file refers to the sample TDP configuration file shipped with RSC/MP. Modify this to fit your environment. DELAY 10 SECONDS RUN [RSCSYS].RSCCOM /IN tdpcfg/ $zrsc Run the test echo server. This is only needed for the RSCTEST and RSCTESTW client test programs. This is not needed for a production environment. The process must be named $TDD. RUN [RSCISV].TDDSVR /NAME $TDD, NOWAIT/ INTERPROCESS 10-3

130 Configuring and Managing the RSC/MP TDP Process Running Processes at High PINs Running Processes at High PINs All RSC/MP processes are compatible with High PINS. The TDP process can accept opens and requests from TCPs, UMS requesters, and other Guardian processes that run with HIGHPIN ON, regardless of whether the TDP itself is configured to run with HIGHPIN ON. Configuring TDP Objects The TDP is composed of objects (ACS, PIPE, and TERM) that are referenced and controlled individually through RSCCOM. At a minimum, you will need: One PIPE object. If you are using dynamic TERM objects, you will need at least one TERM template. If you are using static TERM objects, you will need one object for each workstation. See Section 11, RSCCOM Command Reference, for descriptions of the RSCCOM commands. The number of TDP objects depends on the number of workstations and the type and total number of transports needed. You must configure a TERM object for each workstation (if using static TERM names) and a communications object for each communication end point (for example, PIPE object) that the TDP must support. 10-4

131 Configuring and Managing the RSC/MP TDP Process RSC/MP Configuration Limits RSC/MP Configuration Limits Table 10-1 shows the RSC/MP configuration limits. These limits are stated both as theoretical maximums (that is, the limits imposed by the architecture of the RSC/MP product) and as maximums observed during product testing. The actual limits observed at your site may vary (either larger or smaller) from the limits observed during product testing. The actual limits depend on many factors such as the model of the host system (that is, S7000, S70000 and so on), the version of the operating system, the amount of available memory on your system, available swap file space, similar workstation variables, and so on. In addition, performance requirements may dictate significantly smaller configurations per TDP process and/or per workstation. Table Configuration Limits Component Measured Maximum Observed Theoretical Limit object 6 per TDP approx concurrent connections per TDP PIPE object - assumes static TERM concurrent connections per workstation concurrent connections per TDP TERM object concurrent sessions per TDP TERM object concurrent sessions per workstation connection approx approx concurrent opens to named servers concurrent opens to ServerClass servers 9000 unknown 1. Highest value tested. Upper bound not known. 2. Workstation resource limit encountered. 3. Due to observed workstation limit. Upper bound not known. 4. Guardian error 36 encountered. 5. Guardian file system limit. 6. A TDP object is a unit of control within the TDP. The total number of objects includes those TERM, PIPE, and ACS objects configured vi a the RSCCOM ADD command, TERMs created dynamically upon each RscConnect if dynamic TERMs are configured, and the internal objects which total 5, plus 1 for each RSCCOM process which has opened the TDP. 10-5

132 Configuring and Managing the RSC/MP TDP Process TERM Object TERM Object All RSC/MP connections and sessions terminate with a TERM object. While a TERM generally corresponds to a workstation, a workstation can be configured to access multiple TERM objects. The TERM object sets defaults for the sessions associated with it. For example, a TERM object can enforce access through an ACS process regardless of how individual workstations are configured. PIPE Object The PIPE object provides the TDP interface to the Piccolo transport system. Its name is used as the listen (or passive open name) on connect requests from clients. This name, along with the host system name, is used by RSC/MP clients in the RSC.INI file as the value of HOST_PIPENAME. Files Used to Configure RSC/MP After you configure and start TDP objects, you can edit the following files to configure and maintain the TDP. Table Sample Configuration and Management Files File TDPCFG STARTRSC STOPRSC PWYCFG PIPETXT Retaining Modifications Purpose RSCCOM input configuration Starts the RSC/MP host processes Stops the RSC/MP host processes Configures a Pathway/TS for the test server (TDDSVR) Piccolo configuration To retain modifications to the TDP configuration, place the modified values in a command file (for example, TDPCFG) that is supplied to RSCCOM upon TDP start up. TDP Logging You can turn on TDP logging and view the messages by following the steps in the following subsections. Setting Up a Log File The TDP sends critical RSC/MP event messages automatically to the Distributed Systems Management (DSM) event collector, $0, and to a log file if the file has been established using the RSCCOM LOGOPEN command. These critical events include critical errors, logfile opens, and object state changes (such as start, stop, and abort). This process does not require configuration. HP Global Customer Support Center 10-6

133 Configuring and Managing the RSC/MP TDP Process Logging Using EMS Tokens (GCSC) may request additional logging to diagnose a TDP problem. To turn on optional logging, follow these steps: 1. Use the RSCCOM command LOGOPEN to start logging and to identify the log file; for example: LOGOPEN $DATA.RSC.ERRLOG The log file ($DATA.RSC.ERRLOG, in this example) must be a pre-existing, unstructured Enscribe file, spooler (for example, $5.#MYTRACE), or a terminal with a paused TACL (for example, $ASY01.#TERM2). 2. Use RSCCOM and the attribute LOGEVENTS to turn on logging of optional events for a specific TDP object (this applies to TERM and PIPE objects only); for example: ALTER TERM TERMO1 LOGEVENTS TMF This turns on logging of TMF events for the TERM object named TERM01. Notes. All critical messages are automatically logged to the event collector ($0). Set up a log file only for diagnostic purposes. Optional logging will affect the performance of RSC/MP. 3. To turn off all logging for a TDP, enter the LOGCLOSE command. 4. To turn off optional events for a specific TDP object, enter an ALTER command with no options for LOGEVENTS; for example: ALTER TERM TERMO1 LOGEVENTS This command turns off logging of TMF events for the TERM object. Logging Using EMS Tokens By default, logging of critical events is performed by using the Event Management Service (EMS). The TDP issues messages in tokenized form. These tokens are described in the Remote Server Call (RSC/MP) Messages Manual. You can use Viewpoint or EMSDIST to view the tokenized log messages. This requires that the RSC EMS tokens and advisory text templates be merged with the system templates as described in Installation from the CD on page 3-1. If you have performed this merge operation, set the RSCUSEEMS PARAM prior to starting the TDP. The following example shows the use of this PARAM: > PARAM RSCUSEEMS 1 > RUN TDP /NAME $TD01, NOWAIT/ If you do not perform this merge operation, you can still view the tokenized messages since the TDP inserts a text token (for compatibility purposes) that contains all of the information necessary for Viewpoint or EMSDIST to display the message text into the token stream. However, displaying this text token 10-7

134 Configuring and Managing the RSC/MP TDP Process Suppressing Event Types increases the size of the token stream; using the template merge operation is recommended instead. Note. If you do not merge the templates, DO NOT define the RSCUSEEMS PARAM prior to starting the TDP, otherwise messages will not be properly displayed. Suppressing Event Types To suppress object state changes (for example, stopping, starting or aborting) from being sent to the console, use the CONTROL TDP SUPPRESSEMS command. See CONTROL TDP SUPPRESSEMS Command on page 11-9 for more information about this command and the Remote Server Call (RSC/MP) Programming Manual for more information about object states. Logging Events Logging of some events can be selected using options to the LOGEVENTS attribute of the ALTER command. For example, at the RSCCOM prompt, enter this command to set the logging for a terminal: ALTER TERM TERMO1 LOGEVENTS ALL This command logs all events, including optional events, for the terminal named TERM01 to the file that you opened in Setting Up a Log File on page Note. For all TDP objects that support the LOGEVENTS attribute, you can use the RSCCOM ALTER command to change the logging options while an object is in the started state. To turn off optional logging of events for a specific object, enter a space after the LOGEVENTS attribute. The word None appears when you use the RSCCOM INFO command. Viewing Log Events Use Viewpoint (see the Viewpoint Manual for instructions) to see messages in the log file; for example: :37:42 TDP:$TDPA:TERM:TERM01:2521 [1] Interprocess session established :35:43 TDP:$TDPA:TERM:TERM01:2540 [1] Interprocess I/O started, process \TESTLAB.$TDD, request size 200, reply size 200, I/O handle -1, TMF option 3. Note. The number at the end of each message, for example, 2521 at the end of TDP:$TDPA:TERM: TERM01: 2521 is an error/event code. The following text, Interprocess session established, describes the error/event. The following tables describe the events that are specific to TDP objects. 10-8

135 Configuring and Managing the RSC/MP TDP Process Logging Events TERM Object Event Types The TERM object has these options for logging events: ACSALLOW ACSREJECT CONNECTION SESSION TMF MESSAGE MEMORY ALL DIAGNOSTIC Attempts to access a server for which the ACS object permitted the access. Attempts to access a server for which the ACS object rejected the access. Events related to establishing connections; for example, connect and disconnect. Events related to establishing sessions; for example, begin session, end session, errors, and so on. Events related to TMF transactions; for example, begin transaction, end transaction, errors, and so on. I/O errors, such as WriteReads, IoChecks, and unsolicited messages. Events related to allocating and releasing memory. Events from all categories, except MEMORY. Events for all categories, including MEMORY. PIPE Object Event Types The PIPE object has these options for logging events: CONNECT SEND RECEIVE DISCONNECT ALL Events related to establishing connections; for example, connect and disconnect. Events related to sending data packets. Events related to receiving data packets. Events related to break down of sessions. Events from all categories. 10-9

136 Configuring and Managing the RSC/MP TDP Process Logging Events 10-10

137 11 RSCCOM Command Reference This section describes the RSCCOM commands that are used to manage the RSCCOM environment, control the TDP, and manage the TDP objects. Overview of RSCCOM Commands RSCCOM is a NonStop system process which provides a command interface to the TDP. You can enter RSCCOM commands interactively at a workstation to configure and control the TDP. There are three categories of RSCCOM commands: Operational commands that manage the internal RSCCOM environment. These commands are entered on the command line at the RSCCOM prompt and are described in RSCCOM Command Descriptions on page TDP control commands that manage the TDP process directly. These commands include starting and stopping a backup, and opening and closing a log file. These commands are described in RSCCOM TDP Control Commands on page Object-related commands that are passed to the TDP for processing. These commands configure and manage the TDP objects which includes adding, altering, and deleting the objects. These commands are described in TDP Object Management using RSCCOM Commands on page Follow these guidelines when using RSCCOM: Enter the RSCCOM commands in uppercase or lowercase characters. Enter multiple commands on one command line by separating each command from the next with a semicolon (;). Press the BREAK key to put the RSCCOM process in the background and display a TACL prompt. Enter the PAUSE command at the TACL prompt to bring you back to an RSCCOM process that is running in the background. Press the BREAK key to stop the output of text and return to the RSCCOM prompt. RSCCOM Command Descriptions These are the operational RSCCOM commands associated with the control and operation of RSCCOM:! FC MAXWARNINGS [ HELP OBEY ASSUME EXIT HISTORY MAXERRORS 11-1

138 RSCCOM Command Reference! Command! Command The! command allows immediate execution of a previously executed command line. This command acts like the FC command, but executes the specified command immediately. When no arguments are indicated, the! command repeats the last command string entered.!!prefix!number prefix The leading character of the previously entered command string that you want to re-execute. number The number of the stored command to re-execute. Examples: The following example retrieves and executes the previous command entered: 5((! The following example retrieves and executes the last command entered beginning with the word SET: 6((!SET The following example retrieves and executes the command entered at command prompt 3: 7((!3 [ Comment Indicator The [ character allows you to add comments to the text in an RSCCOM OBEY file. Any text following the left bracket, up to the end of the line, is a comment. Note. This command is for OBEY files only and does not work for interactive (command line mode) operations. [ text 11-2

139 RSCCOM Command Reference ASSUME Command text The text to be commented. Example: The following example shows comments in an RSCCOM OBEY file: [ configure TERM objects ADD TERM SMITH [workstation for John Smith ADD TERM JONES [workstation for Tom Jones [START ALL TERMS START TERM * ASSUME Command The ASSUME command sets the default TDP object. When the object type is omitted from subsequent commands, RSCCOM uses the object type that you specified with the ASSUME command, until a different object type is specified. ASSUME ASSUME type type The type of TDP object. Example: The first command sets the default object type to TERM and the second command sets the TERM PWYPATHMON attribute to $PM (without redefining the object as TERM): 1(( ASSUME TERM 2(( SET PWYPATHMON $PM EXIT Command The EXIT command terminates the RSCCOM process. If RSCCOM is using a command file, this command also terminates the command file. EXIT E <CTRL-Y> 11-3

140 RSCCOM Command Reference FC Command FC Command The FC (fix command) command repeats a command line, allowing you to edit the command. This FC command behaves similar to the TACL FC command. FC FC prefix FC number prefix The leading characters of the command string to edit. number The command prompt number of the command line of the command to edit. When no arguments are entered, FC returns the previous command string entered. When this command executes, it displays the previous command line and prompts for editing input with periods (...). FC accepts three editing commands: R (replacement-string) I (insertion-string) D (deletion-character) Replaces one or more characters in the command line with replacement-string on a one-for-one basis Inserts one or more characters in the command line before the character that is above insertionstring Deletes one character that is above it in the command line; the editing command is repeated for each character to be deleted. If a string of characters is entered but no command is entered, replacement occurs. Enter editing commands and their associated strings below the display command line and terminate the command by pressing the RETURN key. Begin replacement, insertion, and deletion commands with the character positioned directly above the editing command (R, I, or D). After editing the line, press the RETURN key; RSCCOM then displays the command line for another editing command. FC terminates when it receives only a carriage return; the corrected command line is then executed. Two forward slashes end the editing command and allow another editing command on the same line. CTRL/Y exits the command. The BREAK key exits the FC command, but does not exit the process, and returns to the TACL prompt. 11-4

141 RSCCOM Command Reference HELP Command Example: The following example shows the correction of a typing error in which a V was used instead of a C in the word DYNAMIC: 4(( ALTER TERM DYNAMIV ACSERVER ACS1 ***Error 3016: TERM object DYNAMIV has not been configured. 5(( FC 5(( ALTER TERM DYNAMIV ACSERVER ACS1... RC 5(( ALTER TERM DYNAMIC ACSERVER ACS1... 6(( HELP Command The HELP command displays short descriptions of the RSCCOM commands and parameters. When no arguments are entered, RSCCOM displays the entire list of help topics. HELP HELP command HELP type ATTRIBUTES HELP type attribute command The command for which you want to display help. type The type of object; for example, TERM. attribute The named attribute of the object type. Example: The following command displays help about the TERM object s template: 1(( HELP TERM TEMPLATE 11-5

142 RSCCOM Command Reference HISTORY Command HISTORY Command The HISTORY command displays the last 20 previously entered RSCCOM commands. HISTORY H MAXERRORS Command The MAXERRORS command sets the number of errors that RSCCOM ignores when executing an IN or OBEY command file, or an IN process file. MAXERRORS number number The maximum number of errors that RSCCOM ignores. MAXERRORS can be entered in the command file that is used for the IN file option of the RSCCOM STARTUP command. The default value is 1. Example: The following command allows RSCCOM to continue executing the command file until it encounters 10 errors or the end of the file: 1(( MAXERRORS 10 MAXWARNINGS Command The MAXWARNINGS command sets the number of warnings that RSCCOM ignores when executing an IN or OBEY command file, or an IN process file. MAXWARNINGS number number The maximum number of warnings that RSCCOM ignores. MAXWARNINGS can be entered in the command file that is used for the IN file option of the RSCCOM STARTUP command. The default value is

143 RSCCOM Command Reference OBEY Command Example: The following command allows RSCCOM to continue executing the command file until it encounters 10 warnings or the end of the file: 1(( MAXWARNINGS 10 OBEY Command The OBEY command reads commands from a batch file. OBEY filename filename An edit file name from which RSCCOM reads commands. RSCCOM reads and executes commands from the named file until it encounters an EXIT command or the end of the file. All lines read from the file are echoed to the terminal. After reaching the end of the file, RSCCOM closes the OBEY file and command input reverts to the terminal. When RSCCOM detects errors or warnings while processing the commands from an OBEY file, the line where the error or warning was found is displayed. RSCCOM increments the error or warning count and compares that count to the values of the MAXERRORS and MAXWARNINGS attributes. When the count exceeds either attribute value, RSCCOM closes the OBEY file and displays a prompt on the terminal. OBEY commands can be nested, so you can have OBEY commands within an OBEY file. Example: In the following example, RSC is the subvolume and TDPCFG is the name of the file to read: 1(( OBEY RSC.TDPCFG 11-7

144 RSCCOM Command Reference RSCCOM TDP Control Commands RSCCOM TDP Control Commands There are several RSCCOM commands that can be used to control the operation of the TDP. Enter these commands at an RSCCOM prompt. CONTROL TDP BACKUPCPU LOGOPEN STATUS TDP CONTROL TDP SECURITY LOGCLOSE VERSION CONTROL TDP SUPPRESSEMS OPEN The TDP commands are not case-sensitive. Multiple commands may be entered on one command line by separating each command with a semicolon (;). A left square bracket ([) makes the rest of a line a comment. CONTROL TDP BACKUPCPU Command The CONTROL TDP BACKUPCPU command defines and changes the parameters of the backup CPU for an existing TDP process. The TDP is considered to be persistent when run with a backup process. This means that the configuration information from the primary TDP is checkpointed to the backup TDP, so the backup has the same configuration as the primary TDP. The backup CPU can also be specified on the command line when starting the TDP. If the CPU is not specified on the command line, no backup TDP process runs until a CONTROL TDP command is executed. CONTROL TDP BACKUPCPU number CONTROL TDP BACKUPCPU NONE number NONE The number of the CPU where the TDP backup process is to be created. If a backup process is already running, the TDP stops the current backup process and starts a new backup process in the specified CPU. Indicates that no TDP backup process is to run. If a backup process is running, it is stopped. Example: The following command defines CPU 1 as the backup CPU: 1(( CONTROL TDP BACKUPCPU

145 RSCCOM Command Reference CONTROL TDP SECURITY Command CONTROL TDP SECURITY Command The CONTROL TDP SECURITY command defines the security attributes for an existing TDP process. CONTROL TDP SECURITY value value The value of the security attribute: O U G C A N OWNER The owner of the TDP process on the local node only USER The owner of the TDP process, either on the local node or on a remote node GROUP Any member of the owner's group on the local node only COMMUNITY Any member of the owner's group, either on the local node or on a remote node ALL All users on the local node only NETWORK Any user on any remote node (default) - The local node superuser only Example: The following command allows access of all users on the local node: 1(( CONTROL TDP SECURITY A CONTROL TDP SUPPRESSEMS Command The CONTROL TDP SUPPRESSEMS command suppresses or enables logging of the EMS events for object state changes while the TDP is running. CONTROL TDP SUPPRESSEMS value value The value of the attribute, either Y or N. Example: The following command suppresses generation of EMS events for object state changes: 1(( CONTROL TDP SUPPRESSEMS Y 11-9

146 RSCCOM Command Reference LOGOPEN Command LOGOPEN Command The LOGOPEN command names the files that the TDP uses for reporting errors and changes in object status. The TDP generates either text or event messages for each log file. Logging is provided primarily for RSC/MP development and debugging purposes, as use of this command can cause performance problems associated with the extra I/O. There is no default log file. Note. Critical events are always logged to the console, $0. This is independent of the LOGOPEN or LOGCLOSE commands. Logging is provided primarily for RSC/MP development and debugging purposes. Use of this command can cause performance problems associated with the extra I/O. Only one log file can be open at a time. When the LOGOPEN command is issued, any currently open log file is closed. LOGOPEN filename filename The name of an existing file to receive diagnostic messages. There is no default log file. The file name could be any of the following: Examples: The name of a fully qualified (specify the volume, subvolume, and file name) existing unstructured file to receive error messages. The name of an existing NonStop terminal available for output. A spool collector. The console log file name ($0). When messages are logged to the console, they are in EMS format. The following command defines the log file as a fully qualified file: 1(( LOGOPEN $DATA.RSC.ERRLOG The following command defines the log file as an existing NonStop terminal: 2(( LOGOPEN $ASY00.#TERM1 The following command defines the spooler as the log file: 3(( LOGOPEN $S.#RSCLOG The following command defines the console as the log file: 4(( LOGOPEN $

147 RSCCOM Command Reference LOGCLOSE Command LOGCLOSE Command The LOGCLOSE command closes the current error log opened with the LOGOPEN command. LOGCLOSE OPEN Command The OPEN command specifies the name of the TDP to which RSCCOM directs subsequent commands and closes any previously opened TDP. OPEN [ \system.]$process system The name of the host system. If not supplied, the current host system name is used. process The name of the TDP process to open. Examples: The following example specifies $TDP1 on the local system as the name of the TDP process to open: 1(( OPEN $TDP1 The following example specifies $TDPA on the system BOSTON as the name of the TDP process to open: 2(( OPEN \BOSTON.$TDPA STATUS TDP Command The STATUS TDP command displays the current status of the TDP, including information about the status of the primary and backup processes. STATUS TDP This is the format of the display: STATUS for TDP process process-name: Primary process is running in CPU prim-cpu. Backup process is backup-state

148 RSCCOM Command Reference VERSION Command Current memory in use is current-mem bytes. Maximum memory use is max-mem bytes. Pathsend is pathsend-state. Log file: logfile-state. Security: ' O ' These are the parameters that are returned: process-name prim-cpu backup-state current-mem max-mem pathsendstate The name of the target TDP. The number of the primary CPU. One of the following describes the state of the TDP: Is not configured Is running in CPU number Is down Is initializing in CPU number Is unknown The current memory usage in bytes. The maximum memory usage in bytes. The string indicates whether Pathsend is installed. logfile-state The name of the currently used log file, or None. VERSION Command The VERSION command displays the version number of the currently opened TDP. VERSION Example: The following example shows the version of the TDP that RSCCOM is currently addressing: Current TDP is \HIMA.$TZRSC - T9711V60 - (15JAN2001) 11-12

149 RSCCOM Command Reference TDP Object Management using RSCCO M Commands TDP Object Management using RSCCOM Commands You use the RSCCOM commands for configuring and managing the following TDP objects: ACS PIPE TERM To avoid entering the object type for the following commands, you can set a default object type through the ASSUME command. ABORT Command The ABORT command aborts TDP objects regardless of their current state. Use this command to immediately stop an object that has outstanding sessions, including active TMF transactions. ABORT type name ABORT type * type The type of TDP object. name The name of the object to abort. * Aborts all configured objects of this type. Example: The following command aborts the TERM object named TERM01: 1(( ABORT TERM TERM01 ADD Command The ADD command adds an object to the TDP. Use this command after entering the appropriate SET command for the object

150 RSCCOM Command Reference ALTER Command ADD type name type name The type of TDP object. The name supplied for the object. The ACS and PIPE object name can be from 1 through 15 alphanumeric characters; the TERM object name can be from 1 through 8 characters. The name must start with a letter and is not case-sensitive. Example: The following command adds an ACS object ACS1 to the TDP: 1(( ADD ACS ACS1 ALTER Command The ALTER command changes the attribute values of an object that was previously added to the TDP. The ACS object must be in the STOPPED state before its attributes can be altered. ALTER type name attribute value type name The type of TDP object. The name supplied for the object. The ACS and PIPE object name can be from 1 through 15 alphanumeric characters; the TERM object name can be from 1 through 8 characters. The name must start with a letter and is not case-sensitive. attribute value The name of an attribute (see TDP Object Attributes and Configuration Notes on page 11-28). A value for the attribute

151 RSCCOM Command Reference DELETE Command Example: The following command alters the ACSERVER attribute of the TERM object TERM01 to MYACS: 1(( ALTER TERM TERM01 ACSERVER MYACS DELETE Command The DELETE command removes an object from the TDP. An object must be in the STOPPED state before it can be deleted. DELETE type name DELETE type * type The type of TDP object. name The name supplied for the object to delete. * Deletes all configured objects of this type. Example: The following command deletes the TERM object TERM01 from the TDP: 1(( DELETE TERM TERM

152 RSCCOM Command Reference INFO Command INFO Command The INFO command displays the current attribute values for an object. See TDP Object Attributes and Configuration Notes on page for a list of attributes for the ACS, PIPE, and TERM objects. INFO type name [ OBEYFORM ] INFO type * type name The type of TDP object. The name of the object for which to display information. OBEYFORM This optional parameter displays the current configuration of the specified object in a form, if captured to a file, which could be used as input in an OBEY file. * Displays the values of all configured objects of this type. Examples: The following command displays the values for the attributes of all the TERM objects described in the TDP when Pipeman is available: 1(( INFO TERM * This is an example of the information reported for a TERM object: PWYPATHMON ACSERVER LOGEVENTS TEMPLATE $PMON ACS1 None Yes The following command displays the configuration values for the TERM object TERM01 in a form that could later be used as input in an OBEY file: 2(( INFO TERM TERM01 OBEYFORM This is an example of the information reported for a TERM object: ASSUME TERM SET PWYPATHMON SET ACSERVER SET LOGEVENTS $RSCP None None 11-16

153 RSCCOM Command Reference RESET Command SET TEMPLATE ADD TERM No TERM01 To capture this data in an edit file, start RSCCOM with the INFO command from the TACL prompt, using the OUT facility: > RSCCOM /out $volume.subvol.file/$tdp; INFO TERM * OBEYFORM RESET Command The RESET command changes the values for the attributes of an object from the values that are entered with the SET command to the default values. This command does not affect the attributes of an object that has already been added to the TDP. RESET type type The type of TDP object. Example: The following command resets all attribute values for the object that was set but has not yet been added: 1(( RESET TERM 11-17

154 RSCCOM Command Reference SET Command SET Command The SET command establishes values for an object s attributes. Use the SET command before the ADD command. After adding the object, you can change attribute values by using the ALTER command. SET type attribute value type The type of TDP object. attribute value The name of an attribute (see TDP Object Attributes and Configuration Notes on page 11-28). A value for the attribute. Example: The following command causes subsequently created TERM objects to be templates: 1(( SET TERM TEMPLATE YES SHOW Command The SHOW command displays the current default attributes of the object type. These values will be supplied as the attribute values for the next (added) object of this type. SHOW type type The type of TDP object. Use the SET command to change specific attribute values. Example: The following command displays the default values for the attributes of the TERM object: 1(( SHOW TERM 11-18

155 RSCCOM Command Reference START Command This is an example of the system default attributes for a TERM object: PWYPATHMON $RSCP IDSPATHMON $RSCP IDSTCP RSC-TCP IDSTCLPROG $SYSTEM.ZRSCHOST.IDS IDSINITIAL IDS-SAMPLE PWYTIMEOUT 30 ACSERVER None LOGEVENTS None TEMPLATE No START Command The START command initiates operation of an object. START type name START type * type name The type of TDP object. The name supplied for the object. The ACS and PIPE object name can be from 1 through 15 alphanumeric characters; the TERM object name can be from 1 through 8 characters. The name must start with a letter and is not case-sensitive. * Starts all configured objects of this type. Examples: The following command starts the TERM object named TERM01: 1(( START TERM TERM01 The following command starts all of the TERM objects that have been previously added: 2(( START TERM * 11-19

156 RSCCOM Command Reference STATS Command STATS Command The STATS command shows data accumulated within the TDP of the specified object, if the object is in the started state. Note. Use of the STATS command with the ACS object displays the message STATS data is not available for an ACS object. STATS type name [ RESET ] STATS type * [ RESET ] type name The type of TDP object. The name supplied for the object. The ACS and PIPE object name can be from 1 through 15 alphanumeric characters; the TERM object name can be from 1 through 8 characters. The name must start with a letter and is not case-sensitive. RESET Resets the accumulators and restarts the collection of statistical data. If the reset occurs while a connection is being established, the Connect counter is set to 1 instead of 0. * Reports statistics for objects of this type. Example: The following command displays statistics for the TERM object named RSCQA15: 4(( STATS TERM RSCQA

157 RSCCOM Command Reference STATS Command This is an example of the output of a STATS command for a TERM object: Term Since(Started/Reset) # Connected # Disconnected RSCQA15 Wed May 15, :27: IOs ---- RECV SENT REQSIZE REPSIZE >56789 > UMS ---- RECV SENT REQSIZE REPSIZE TMF TRANSACTIONS---- STARTED COMMITTED ABORTED SERVER RESPONSE TIME (SECONDS) --- MINIMUM AVERAGE MAXIMUM This is the data in a STATS TERM report: Term Since (Started/Reset) The name of the TERM object providing the statistics. The date and time this accumulation of statistics started. This value is updated each time a STATS TERM command is issued with the RESET modifier. # Connected The number of connects that have been made to this TERM since reset-time. # Disconnected The number of disconnects that have been made to this TERM since reset-time. IOs RECV IOs SENT IOs REQSIZE IOs REPSIZE UMS RECV UMS SENT UMS REQSIZE The total number of RSC/MP messages received by this TERM object since start or reset-time. The total number of RSC/MP messages sent by this TERM object since start or reset-time. The total number of bytes that this TERM object has handled for RSC/MP requests (from workstation applications) since start or reset-time. The total number of bytes that this TERM object has handled for replies (from server processes) to RSC/MP messages from the workstation since start or reset-time. The total number of UMS requests (from the workstation) that this TERM object has received since start or reset-time. The total number of UMS requests (from the workstation) that this TERM object has sent since start or reset-time. The total number of bytes that this TERM object has handled for UMS requests (from server processes) since reset-time

158 RSCCOM Command Reference STATUS Command UMS REPSIZE TMF TRANSACTIONS STARTED TMF TRANSACTIONS COMMITTED TMF TRANSACTIONS ABORTED SERVER RESPONSE TIME - MINIMUM SERVER RESPONSE TIME - AVERAGE SERVER RESPONSE TIME - MAXIMUM The total number of bytes that this TERM object has handled for UMS replies (from workstation applications) since resettime. The total number of transactions initiated by this TERM object. The total number of transactions committed by this TERM object. The total number of transactions aborted by this TERM object. The shortest elapsed time for an RSC message received by this object since the last reset command The average elapsed time for the all RSC messages received since the last reset command The longest elapsed time for an RSC message received by this object since the last reset command Note. A greater than symbol (>) for a statistical value indicates that the value exceeded a maximum for the accumulator and that the accumulator wrapped to zero. STATUS Command The STATUS command displays the functional state of an object. STATUS type name [ DETAIL ] STATUS type * [ DETAIL ] type name The type of TDP object. The name of the object for which to display status information. DETAIL An optional attribute of the STATUS command that provides details of the functional aspects of the specified object. Detailed status reports are shown later in this section. A detailed TERM object status report is shown on page * Displays the status for all objects of this type

159 RSCCOM Command Reference STATUS Command Examples: The following command displays the status for the TERM object named TERM01: 1(( STATUS TERM TERM01 The following command displays the status for all configured TERM objects: 2(( STATUS TERM * ACS Object Status Report The following example shows the format of the ACS object status report: ACS Status Sess Req. Last Event name Outstanding ACS1 Started 0 0 ACS started. [ 7002 ] ACS2 Started 0 0 ACS started. [ 7002 ] This is the data in an ACS object status report: ACS name Status Sessions Req. Outstanding Last Event The name of the ACS object. The current status of the ACS. These are the possible values: STOPPED STARTED PIPE Object Status Report The ACS object is stopped. The ACS object is executing. The number of outstanding sessions for the ACS. The number of requests that are outstanding for the ACS. The last RSC/MP event recorded for this TDP object. The following example shows the format of the PIPE status report: PipeName Status Sessions Last Event TDPPIPE Started 1 PIPE started. [ 8802 ] 1 Pipe objects have been configured. This is the data in a PIPE object status report: PipeName Status The name of the PIPE object. The current status of the PIPE. These are the possible values: STOPPED The PIPE object is stopped. STARTED The PIPE object is executing

160 RSCCOM Command Reference STATUS Command Sessions Last Event The number of outstanding Pipe sessions (one-to-one correspondence with RSC/MP connection). The last RSC/MP event recorded for this TDP object. There are two types of events: 1. Informational events are in the format: Event [event-number] 2. Error events are in one of two formats: a) Guardian error [err-number] b) API error [err-number] PIPE Object Detailed Status The Guardian Procedure Errors and Messages Manual describes the Guardian errors and the Remote Server Call (RSC) Messages Manual describes the API errors. The following information is included in the PIPE object status report if the DETAIL attribute is set: MAX MESSAGE SIZE Maximum message size. TERMS CONNECTED TIME CONNECTED Name of the TERM connected. Date and time the TERM was connected. TERM Object Status Report The following example shows the format of the TERM object status report: Term Status Conn Sess Last Event Started 1 1 TERM started. [ 2802 ] NEWTERM Template This is the data in a TERM object status report: Term Status The name of the TERM object. The current status of TERM. These are the possible values: STOPPED STOPPING STARTED The TERM object is stopped. The TERM object received a STOP command. The TERM object is executing

161 RSCCOM Command Reference STATUS Command Conn Sess Last Event The number of physical connections. The number of TERM sessions. The last RSC/MP error event recorded for this TDP object. TERM Object Detailed Status The following information is included in the TERM object status report if the DETAIL attribute is set: CONNECTION TYPE SESSION HANDLE SESSION TYPE TRANSACTION ID PATHMON NAME SERVER REQSIZE REPSIZE SESSION ALIAS GROUP ALIAS QUEUED The communications object through which the connection was established. A specific number issued by the TDP at the time of the BeginSession call. An RSC/MP session type as established by the client (see the Remote Server Call (RSC/MP) Programming Manual for more information about sessions. The identifier shown when TMF transactions are active. Default Pathmon name used in I/Os for which the explicit Pathmon name is not defined. The node name is shown when the Pathmon name is not local. The server process name. The node name is shown for remote servers. The logical I/O request size that is specified by the client application which does not include internal RSC/MP headers. The logical I/O host reply size which does not include internal RSC/MP headers. A UMS session alias as established by a client application.* A UMS group alias as established by a client application.* The total number of UMS messages that are outstanding.* * Displayed only when UMS messages are queued

162 RSCCOM Command Reference STOP Command STOP Command The STOP command stops operation of TDP objects that have no outstanding sessions. Use the ABORT command to stop an object that has outstanding sessions. STOP type name STOP type * type name The type of TDP object. The name supplied for the object. The ACS and PIPE object name can be from 1 through 15 alphanumeric characters; the TERM object name can be from 1 through 8 characters. The name must start with a letter and is not case-sensitive. * Stops all configured objects of this type. Examples: The following command stops the TERM object TERM01: 1(( STOP TERM TERM01 The following command stops all configured TERM objects: 2(( STOP TERM * TELL Command The TELL command uses the Unsolicited Message Service (UMS) to test the sending of messages to workstation sessions. The application checks and retrieves the message. See the Remote Server Call (RSC/MP) Programming Manual for more information about the UMS. TELL term-name alias-type alias message-text term-name The terminal name of the workstation(s) to receive the unsolicited message. This name must match the name of the TERM object and the corresponding TERM_NAME option specified in the RSC.INI file on the workstation. A termname of asterisk (*) sends the message to applications using the specified alias

163 RSCCOM Command Reference TELL Command alias-type alias Defines the type of the alias that follows, either GROUP or SESSION. GROUP Sends the message to the group of workstation sessions with the GROUP_ALIAS option equal to alias. SESSION Sends the message to a workstation session with the SESSION_ALIAS option equal to alias. Defines which sessions receive the message-text. When the type is equal to GROUP, the message-text is sent to all remote sessions whose TERM_NAME matches term-name and GROUP_ALIAS option matches alias. When the type is equal to SESSION, a message is sent to all remote sessions whose TERM_NAME matches term-name and SESSION_ALIAS option matches alias. The asterisk (*) specifies all sessions or groups. message-text The message to send to the remote workstation(s). The message can be a maximum of 80 characters in length. Examples: The following example sends the message Hello out there to the sessions within workstation TERM01 whose GROUP_ALIAS value equals RSCTEST: 1(( TELL TERM01 GROUP RSCTEST Hello out there The following example sends the message Hello out there to all workstations whose GROUP_ALIAS value equals RSCTEST: 2(( TELL * GROUP RSCTEST Hello out there The following example sends the message Hello out there to the session within workstation TERM01 whose SESSION_ALIAS value equals RSCTEST: 3(( TELL TERM01 SESSION RSCTEST Hello out there The following example sends the message Hello out there to all workstations whose SESSION_ALIAS value equals RSCTEST: 4(( TELL * SESSION RSCTEST Hello out there 11-27

164 RSCCOM Command Reference TDP Object Attributes and Configuration Notes TDP Object Attributes and Configuration Notes ACS Object Attributes Table ACS Object Attributes Attribute Name ACSSERVERCLASS ACSPROCESSNAME Description The valid Pathway server class name of an ACS server that is running in a Pathway environment. If blank, then the ACS server is not running in a Pathway environment. If specified, then the Pathmon name must be set in the ACSPROCESSNAME attribute. The default is no ACS server class name. The ACS object must be in the STOPPED state before using the ALTER command with the ACSSERVERCLASS attribute. This attribute must be assigned a value, either: A valid Guardian process name for an ACS server if the ACSSERVERCLASS is blank. RECVWRITEREADS or The name of the Pathmon in which the serverclass, identified by ACSSERVERCLASS, is running. The ACS object must be in the STOPPED state before using the ALTER command with the ACSPROCESSNAME attribute An attribute that specifies whether all WriteRead requests are to be sent from the TDP to the ACS server for security validation. If the value is YES, then all WriteRead requests received by the TDP are sent to the ACS. If the value is NO, then the TDP does not send WriteReads to the ACS server. The ACS object must be in the STOPPED state before using the ALTER command with the RECVWRITEREADS attribute Example attribute settings for the ACS object: ACSSERVERCLASS ACSPROCESSNAME RECVWRITEREADS ACSSVR $RSC-PN NO 11-28

165 RSCCOM Command Reference PIPE Object Attributes PIPE Object Attributes For PIPE objects, the object name must be unique in the TDP, but does not need to be unique on the host or on the network. Piccolo distributes connections across PIPE objects of the same name in the same host. The name must match the first portion of the HOST_PIPENAME option on the workstation. Table PIPE Object Attributes Attribute Name AUTORESTART KEEPALIVE LOGEVENTS Description The number of seconds to wait before automatically restarting a PIPE object that was aborted because of an error. The default value is 30 seconds. Use the SET AUTORESTART command to automatically restart an aborted PIPE object. You can alter the AUTORESTART attribute without the PIPE object being in the STOPPED state. The number of seconds between attempts by Piccolo to verify that the connection remains active. The value may be from zero (disabled) to seconds (100 hours). Low values for KEEPALIVE may burden networks with verification messages. By default, KEEPALIVE is disabled (0). The PIPE object must be in the STOPPED state before using the ALTER command with the KEEPALIVE attribute The type of logging event. This attribute is used primarily for RSC/MP development and debugging and is subject to change. You can use the LOGEVENTS attribute without the PIPE object being in the STOPPED state

166 RSCCOM Command Reference PIPE Object Attributes The PIPE object also has two read-only attributes that are not configurable after TDP startup: Attribute Name PIPEINI LOCATION Pipeman IpcKey Description The Piccolo configuration file name and location. This value is derived at TDP startup from the PIPEINI or PATH environment variables or, if neither is provided, by finding the configuration file of the default Pipeman process, $PIPE. The process name of the Pipeman process. This value is derived at TDP startup from the IpcKey value found in the Piccolo configuration file indicated to by the PIPEINI or PATH environment variables or, if neither is provided, the default value, $PIPE, is used. Example attribute settings for the PIPE object: AUTORESTART 30 KEEPALIVE Disabled LOGEVENTS None 11-30

167 RSCCOM Command Reference TERM Object Attributes TERM Object Attributes Table TERM Object Attributes (page 1 of 2) Attribute Name ACSERVER Description The Access Control Server invoked for sessions on this TERM. The ACS that will be invoked depends on both the ACSERVER attribute of the TERM object and the HOST_ACS_NAME option specified by the client application on the workstation: If the ACSERVER attribute is not blank, its value is interpreted as the name of the ACS object to be invoked. The workstation cannot override an ACS specified this way. This configuration provides the highest level of security. If the ACSERVER attribute is blank, the workstation determines which ACS object will be invoked by setting the HOST_ACS_NAME option. If both the ACSERVER attribute and the HOST_ACS_NAME option are blank, no ACS object is invoked. See the Remote Server Call (RSC/MP) Programming Manual, Section 9, Access Control Server for more information. IDSINITIAL IDSPATHMON IDSTCP IDSTCLPROG The TERM object must be in the STOPPED state before using the ALTER command with the ACSERVER attribute. The default SCREEN COBOL PROGRAM-ID name for IDS sessions for this terminal. The value for this attribute must be a valid SCREEN COBOL PROGRAM-ID contained within the TCLPROG specified for the session. The default is IDS- SAMPLE. The default PATHMON to use for IDS sessions for this terminal. The value for this attribute must be a valid Guardian process name. The default is $RSCP. The default TCP name for IDS sessions for this terminal. This attribute must be a valid TCP name that has been configured in the Pathway specified for the IDS session. The default is RSC- TCP. The default name of the SCREEN COBOL object file to use for IDS sessions for this terminal. The value for this attribute must be a SCREEN COBOL object file name and must be fully qualified. The default is $rscvol.rscsubvol.ids

168 RSCCOM Command Reference TERM Object Attributes Table TERM Object Attributes (page 2 of 2) Attribute Name LOGEVENTS PWYPATHMON PWYTIMEOUT TEMPLATE Description Used for logging events. Logging choices are ACSALLOW, ACSREJECT, CONNECTION, DIAGNOSTIC, MEMORY, SESSION, TMF, MESSAGE, or ALL. See the TERM Object Event Types on page 10-9 for a definition of these categories. You can alter the LOGEVENTS attribute without the TERM object being in the STOPPED state. The default PATHMON to use for Pathsend sessions for this terminal. This attribute must be a valid Guardian process name. The default is $RSC. The TERM object must be in the STOPPED state before using the ALTER command with the PWYPATHMON attribute. The number of seconds to wait for the Pathway terminal supporting the IDS session to start up. The minimum value is 30 seconds and the maximum value is 120 seconds. If a value is not specified, the default value is 30 seconds. A YES or NO value which indicates whether this terminal is a terminal template. A terminal template is used for the configuration of dynamic terminals and cannot service static terminal connections.when the TDP receives a connection request from the workstation, the TDP uses a template configuration to start a dynamic terminal. You cannot use the START command to start a template from RSCCOM. The TERM object must be in the STOPPED state before using the ALTER command with the TEMPLATE attribute. Example attribute settings for a TERM object: PWYPATHMON $RSCP IDSPATHMON $RSCP IDSTCP RSC-TCP IDSTCLPROG $SYSTEM.ZRSCHOST.IDS IDSINITIAL IDS-SAMPLE PWYTIMEOUT 30 ACSERVER None TEMPLATE No 11-32

169 RSCCOM Command Reference TERM Object Attributes TERM Object Configuration Notes Each workstation must have a TERM object in the TDP. There are two types of TERM objects: static and dynamic. Static TERM objects require that you specify a TERM name for each workstation before it is connected. The name of the TERM object (TERM01 in the following example) must match in the host and workstation configurations (see Figure 11-1). The TDP uses this TERM object only for a specific workstation. A dynamic TERM object, specified by setting the TEMPLATE attribute to YES, allows the TDP to create and start a TERM object at the time a workstation is connected. Configuring Static TERM Objects On the NonStop host, follow these steps to configure a static TERM object: 1. Set the TEMPLATE attribute to NO: set term template no 2. Add a TERM object to the TDP and name it; for example, TERM01: add term term01 On the workstation, edit the RSC.INI file, setting the TERM_NAME option to a name that matches the name of the TERM object in the TDP: term_name = term01 Each workstation connected to a TDP must have a unique TERM_NAME. Figure 11-1 illustrates the configuration of a static TERM in the TDP and on the workstation. This name must match the name of the TERM object in the TDP. Figure Static Terminal Configuration Workstation (RSC.INI File) NonStop TM Host [RSC] TERM_NAME = TERM01 PATHMON_NAME = $PM SET TERM IDSPATHMON $PM SET TERM IDSINITIAL MYIDSREQ SET TERM IDSTCP MYTCP SET TERM IDSTCLPROG $VOL.SV.IDS ADD TERM TERM01 CDT

170 RSCCOM Command Reference TERM Object Attributes Configuring Dynamic TERM Objects You can configure the TDP so that TERM objects are created dynamically at the time the workstation is connected. This capability is helpful when there are a large number of workstations that do not correspond directly to one particular TDP. It is also helpful in that it allows for a single, non-unique, distributable RSC.INI file. When a workstation connects to the TDP, the TDP uses the attributes of the TERM object with the specified template name to create and start a new TERM object. This new TERM object then services requests from the workstation. Any number of workstations can specify the same TERM_TEMPLATE name. Dynamic terminals are assigned names, as needed, of the where nnnn is a sequential number. When the workstation disconnects from the TDP, the dynamic TERM object is stopped and deleted. There are two ways to configure dynamic TERM objects: Use a TERM object template named DYNAMIC. This TERM object has a special meaning to the TDP. It allows any workstation using RSC/MP to access RSC/MP on the NonStop system. Follow these steps: 1. Configure the TDP: a. Using the SET command, change the TEMPLATE attribute to YES: set term template yes b. Add a TERM object with the name DYNAMIC: add term dynamic 2. Optional, but recommended, edit the RSC.INI file, adding the TERM_NAME option with a name; for example: term_name = remote1 If the TERM object in the TDP has the name DYNAMIC, then the workstation does not need to have the TERM_TEMPLATE option set. 3. Use RSCCOM to show the status of this TERM object: 8 (( status term * Term Status Conn Sess Last Event Started 1 TERM started. [ 2802 ] 1 DYNAMIC Template 2 TERM objects have been configured. If you omit the TERM_NAME from the RSC.INI file, RSCCOM reports the name of the workstation as NoName

171 RSCCOM Command Reference TERM Object Attributes Use a TERM template with a name other than dynamic. Follow these steps: 1. Configure the TDP: a. Using the SET command, change the TEMPLATE attribute to YES: set term template yes b. Add a TERM object to the TDP and name it, for example, NEWTERM: add term newterm 2. Edit the RSC.INI file: a. Add the TERM_TEMPLATE option; for example: term_template=newterm b. Optional, but recommended: add the TERM_NAME option with a name, for example, REMOTE1: term_name = remote1 3. Use RSCCOM to show the status of this TERM object: 8 (( status term * Term Status Conn Sess Last Event Started 1 1 TERM started. [ 2802 ] NEWTERM Template 2 TERM objects have been configured. In this example, RSC/MP reads the TERM TEMPLATE setting of YES in the TDP, for the TERM object named NEWTERM. The YES setting instructs RSC/MP to add a dynamic for the terminal named REMOTE1. If you do not specify the TERM_NAME in the RSC.INI file, the STATUS command shows NoName for the terminal name: 9 (( status term * Term Status Conn Sess Last Event Started 1 1 TERM started. [ 2802 ] NEWTERM Template 2 TERM objects have been configured

172 RSCCOM Command Reference TERM Object Attributes 11-36

173 12 Configuring the RSC/MP Client This section describes how to configure the client workstations. RSC/MP Client Configuration and Verification Follow these steps to configure and test the RSC/MP client: 1. Install and configure the host component (see Section 3, Installing RSC/MP on the Host, and Section 10, Configuring and Managing the RSC/MP TDP Process). 2. Install the RSC/MP client software (see Section 4, Installing RSC/MP on Windows Workstations, or Section 6, Installing RSC/MP on UNIX Workstations). 3. Configure the RSC/MP transport (see Section 5, Configuring the RSC/MP Transport (Piccolo). 4. Configure the RSC.INI (see Basic RSC.INI Configuration on page 12-2). 5. Start the RSC/MP transport manager (see Starting the RSC/MP Transport Manager (Pipeman) on page 12-4). 6. Test the RSC/MP installation and configuration (see Testing the RSC/MP Client Configuration on page 12-8). Prerequisites to Configuring RSC/MP Before configuring RSC/MP perform the following steps: 1. Read the softdoc shipped with this release. 2. Install the RSC/MP client software on the target workstation. 3. Ensure that the network communications facility (for example, TCP/IP network) is installed, connected, configured, and working properly. 4. Gather the following information: System name of destination host system TDP TERM object name TDP PIPE object name 12-1

174 Configuring the RSC/MP Client Basic RSC.INI Configuration Basic RSC.INI Configuration RSC/MP configuration files can be created and adjusted using an ordinary text editor on all platforms. Also, the RSC/MP Configuration Wizard (RscConfig.exe file) can be used to create a basic configuration file on the Windows platform. An RSC/MP configuration file can have any name. The default name is RSC.INI, and this name is used throughout this subsection. Note. In addition to the minimal set of options shown in this subsection and the complete set of RSC/MP options given in the Remote Server Call (RSC/MP) Programming Manual, the RSC/MP configuration file can also include configuration settings for Piccolo. For information about creating a combined configuration file, see Combining Piccolo and RSC/MP Configuration Settings (workstations only) on page 5-9. Several options can be used in an RSC.INI configuration file. See the Remote Server Call (RSC/MP) Programming Manual for a complete list of these options. These options are also used in the corresponding TDP configuration which is discussed in Section 10, Configuring and Managing the RSC/MP TDP Process. A minimum RSC.INI configuration requires: 1. The TERM_NAME option. The TERM_NAME option identifies which TDP TERM object this workstation corresponds to. Whether the TERM_NAME option is required depends upon the TDP TERM object configuration. a. Static TERMs. If the TDP is configured only with static TERM objects, then the TERM_NAME option is required. It must match the name of a TDP TERM object that is not already in use (i.e. with static TERM objects, each workstation must have a unique TERM_NAME), for example: TERM_NAME = term01 b. Dynamic TERMs. If the TDP is configured with a TERM object with the TEMPLATE attribute set to YES, then use of the TERM_NAME option is optional, and the TDP will create TERM objects dynamically upon RscConnect requests. When the TERM_NAME option is supplied it becomes part of the dynamically created name and can be used by the RSCCOM STATUS TERM command to query the status of a particular workstation. The TERM object configured with the TEMPLATE attribute is called a template. If the TERM template is named DYNAMIC no further configuration is needed on the workstation. If the TERM template name is other than DYNAMIC, then the TERM_TEMPLATE option must be used in the RSC.INI file and the name supplied must match the TERM template name in the TDP. 2. The ERROR_FILE option. This option sets the path of the RSC/MP error file. The ERROR_FILE option is used to identify to RSC/MP the location of the RSC.ERR file. This file is used by the RSC/MP API library when requested by the application to translate an RSC/MP error code to the text associated with the error. If this 12-2

175 Configuring the RSC/MP Client Basic RSC.INI Configuration option is not specified, the RSC/MP error file must be in the application s current directory, C:\ (for Windows), or in the PATH (for Windows and UNIX). Example: ERROR_FILE = c:\rsc\rsc.err 3. The SUBSYSTEM_NAME option. This option supplies the RSC/MP I/O manager (RSCPIPE) process logical name. When the application issues an RscConnect call the RSC/MP API library will attempt to communicate with RSCPIPE. If it is not yet started, the process will be launched and the name identified by the SUBSYSTEM_NAME option will be used by the new process as its logical name. If this option is not specified, the RSC/MP I/O manager process name used will be RSCPIPE. SUBSYSTEM_NAME = RSCPIPE 4. The HOST_PIPENAME option. The HOST_PIPENAME option identifies the name of the TDP PIPE object and the host SystemName to which the application will connect. The presence of the HOST_PIPENAME option implies that the PIPE.INI file contains all of the communications related configuration, and therefore RSC/MP will ignore all connectivity options in RSC.INI (used by RSC 5.0 and previous versions). HOST_PIPENAME = pipename@hostname where: hostname The name of the PIPE object in the TDP. A required separator. The name of the host that must match the SystemName in the PIPEINI on the host system. The hostname may also include the DomainName of the host system. For example: HOST_PIPENAME=pipe1@sysA HOST_PIPENAME=A301@sysB.mydomain.com 12-3

176 Configuring the RSC/MP Client Starting the RSC/MP Transport Manager (Pipeman) Starting the RSC/MP Transport Manager (Pipeman) The PIPEMAN process must be running in order for RSC/MP clients to operate correctly. PIPEMAN must be started in one of the following three ways: 1. When RSC/MP is installed as a service, PIPEMAN will be started automatically when the RSC Service starts. The RSC Service can be configured to start automatically at system startup, as described in Section 4, Installing RSC/MP on Windows Workstations. 2. Piccolo can be configured for automatic startup by including an AutoStart setting in the Piccolo configuration file, as described in Section 5, Configuring the RSC/MP Transport (Piccolo). 3. Piccolo can be started by using the PIPECP utility, as outlined below. This can be done manually, or as part of a local startup sequence (for example, through an icon in the "Startup" programs group in Windows). To start the Pipeman process, enter: PIPECP START To test the transport configuration, enter: PIPECP CONNECT hostname where hostname is the SystemName in the PIPEINI file on the host system. This command will reply with either a message, Attempting connection... connection succeeded. or an error code indicating why the connect attempt failed. Configuring the RSC/MP I/O Manager Process (RSCPIPE) The RSCPIPE process includes extended functionality for diagnostic logging, window control, and migration. This extended functionality is enabled by command line parameters, that are provided during either an RSC/MP API-controlled or a usercontrolled startup of the RSCPIPE process. An RSCPIPE process is started by the RSC/MP API when an RSC/MP application issues the first RscConnect call and the RSC/MP API determines RSCPIPE is not running. When RSCPIPE is started by the RSC/MP API, command line parameters are evaluated from the SUBSYSTEM_CMDLINE option in the RSC.INI file. You can initiate an RSCPIPE process, either during system startup or from a command line prompt. Note. RSCPIPE requires PIPEMAN. When attempting a user-controlled startup of the RSCPIPE process, be sure that PIPEMAN is already running or that Piccolo is configured for automatic startup as described in Section 4, Installing RSC/MP on Windows Workstations. 12-4

177 Configuring the RSC/MP Client Configuring the RSC/MP I/O Manager Pr oc es s ( RS CP IPE ) Starting the RSCPIPE Process on Windows Systems The syntax for starting the RSCPIPE process from the RSC.INI file is: SUBSYSTEM_CMDLINE = "[-h -hh] [-dflogname] [-cn] [-ln]" The syntax for starting the RSCPIPE process from a command line prompt is: <path>\rscpipe.exe [-h -hh] [-dflogname] [-cn] [-ln] [subsystem_name] <path> The folder where rscpipe.exe is installed. -h Hides the icon for the RSCPIPE process and removes the process from the task list. This is the preferred form for hiding RSCPIPE. If RSCPIPE is invoked with the -h option from a command line prompt (that is, in an existing console window or DOS box), the RSCPIPE will not hide the existing command line prompt window but will instead report an error ( RSCPIPE: Cannot hide this console window; use START RSCPIPE -H... ) which guides the user to run RSCPIPE in a new window by using the Windows command START. -hh Hides the icon for the RSCPIPE process and removes the process from the task list. This form defeats the check for an existing command prompt and hides the RSCPIPE window unconditionally. Use this form only if some system configuration problem prevents the -h option from working correctly on your system. -d Enables diagnostic logging. This option is disabled by default because it slows down performance and may create log files that use a significant amount of disk space. flogname The fully qualified file name (the path plus the file name) of an output file where debug messages are written. The complete name is limited to 64 characters. An example of the -df parameters is: -dfc:\rsc\bin\rscpipe.log 12-5

178 Configuring the RSC/MP Client Configuring the RSC/MP I/O Manager Pr oc es s ( RS CP IPE ) -cn -ln subsystem_name Specifies the debugging class. Values range from 0 (no debugging classes) to 255 (all debugging classes). The default value is 255. This setting takes effect only when diagnostic logging has been enabled with the -d flag. The debugging classes are specified as a sum of the target class values, selected from the values below. Each entry in the log file will contain an identifier indicating which debugging class generated the log entry. 1 RSC 2 PICCOLO 4 CONN 8 API 16 HOST 32 REQ 64 NOTIFY 128 SNO For example, to enable API, HOST, and REQ logging, add to get a final class value of 56. Specifies the debugging level. Values range from 0 (the least amount of information) to 3 (the greatest amount of information). The default value is 3. This setting takes effect only when diagnostic logging has been enabled with the -d flag. The logical name of the RSCPIPE process. This name identifies a running instance of the RSCPIPE process, for example the icon name or the process name in a task list. In order for an application to identify and use this RSCPIPE instance, the name specified here must match the SUBSYSTEM_NAME option established by the application. On a Windows platform, you can configure and control the startup of the RSCPIPE process in these ways: If RSC/MP was installed as a service, supply command line parameters using the Service Control Manager. Use the STARTUP folder to launch RSCPIPE at system startup. Use the RUN command to launch RSCPIPE on demand. Use the command line to launch RSCPIPE on demand. Note. If RSC/MP is installed as a service, do not start other instances of RSCPIPE because those instances will not be accessible from an RSC/MP application. 12-6

179 Configuring the RSC/MP Client Configuring the RSC/MP I/O Manager Pr oc es s ( RS CP IPE ) Starting the RSCPIPE Process on UNIX Systems The syntax for starting the RSCPIPE process from the RSC.INI file is: SUBSYSTEM_CMDLINE = "[-d] [-cn] [-ln]" The syntax for starting the RSCPIPE process from a command line prompt is: <path>/rscpipe.exe [-d] [-cn] [-ln] [subsystem_name] <path> The folder where rscpipe.exe is installed. -d Enables diagnostic logging. This option is disabled by default because it slows down performance and may create log files that use a significant amount of disk space. -cn -ln Specifies the debugging class. Values range from 0 (no debugging classes) to 255 (all debugging classes). The default value is 255. This setting takes effect only when diagnostic logging has been enabled with the -d flag. The debugging classes are specified as a sum of the target class values, selected from the values below. Each entry in the log file will contain an identifier indicating which debugging class generated the log entry. 1 RSC 2 PICCOLO 4 CONN 8 API 16 HOST 32 REQ 64 NOTIFY 128 SNO For example, to enable API, HOST, and REQ logging, add to get a final class value of 56. Specifies the debugging level. Values range from 0 (the least amount of information) to 3 (the greatest amount of information). The default value is 3. This setting takes effect only when diagnostic logging has been enabled with the -d flag. 12-7

180 Configuring the RSC/MP Client Testing the RSC/MP Client Configuration subsystem_name The logical name of the RSCPIPE process. This name identifies a running instance of the RSCPIPE process, for example the icon name or the process name in a task list. In order for an application to identify and use this RSCPIPE instance, the name specified here must match the SUBSYSTEM_NAME option established by the application. On a UNIX platform, you can configure and control the startup of the RSCPIPE process in these ways: Add an RSCPIPE entry to the /etc/rc.local file to start RSCPIPE at system startup. Use the command line to launch RSCPIPE on demand. Testing the RSC/MP Client Configuration RSC/MP supplies the following test programs to test the RSC/MP installation and configuration: RSCPINGW.EXE RSCTESTW.EXE RSCTEST.EXE Available with RSC/MP Windows. RSCPINGW, an end-to-end connectivity test, is a Windows application which uses the configuration in the RSC.INI file and attempts to connect to the TDP. It is useful to determine whether the TDP is reachable from the RSC/MP client. Available with RSC/MP Windows. RSCTESTW, a sample RSC/MP client application, is a Windows application which uses the configuration in the RSC.INI file and attempts to connect to the TDP. It requires that the sample echo server $TDD (shipped with the TDP) be running on the host. Available with all RSC/MP client platforms. RSCTEST, a sample RSC/MP client application, runs as a command line console application which uses the configuration in the RSC.INI file and attempts to connect to the TDP. It requires that the sample echo server $TDD (shipped with the TDP) be running on the host. 12-8

181 A Migration to RSC/MP 7.3 This appendix provides the following installation and configuration information: Differences between RSC/MP 7.3 and earlier versions. Features that are no longer supported. Procedures for migrating from previous releases to RSC/MP 7.3. Information about host and workstation connectivity options. See the Remote Server Call (RSC/MP) Programming Manual for information about the programming migration issues. Differences Between RSC/MP 7.x and Earlier Versions The RSC/MP 7.x family differs from RSC/MP version 6.x and earlier in the following ways: The ACSERVER attribute of the TDP TERM object is now required to identify an ACS object. Attempting to set ACSERVER to a Guardian process name will now result in an error. The Pathway/TS terminal session type is no longer supported. Pathsend is supported using the Interprocess session type. If you send a Pathway session to the TDP, it is converted into a Pathsend session. RSC/MP uses the TDP PIPE object and the Piccolo transport. The Eicon X.25 and X25AM network interfaces are no longer supported. The IPX/SPX and Asynchronous network interfaces are no longer supported. The IMPLICIT_ACK option has been discontinued. Its setting is now silently ignored. The STAMP_MESSAGES option has been discontinued. Its setting is now silently ignored. There is no support for MS-DOS or Macintosh workstations. There is no support for Windows 95, Windows 98, Windows NT 4.0 and Windows ME workstations. There is no support for SCO UnixWare workstations. The direct communication objects ASYNCPORT, NETNAME and SPXPORT are no longer available in the RSC/MP Host. The RSC asynchronous Step-aside feature is not supported. A - 1

182 Migration to RSC/MP 7.3 Features No Longer Supported The limit of 62 I/Os per session has been removed. The limit of 64 sessions per workstation has been removed. The number of objects supported by the host has been expanded from 4000 to objects. Features No Longer Supported These features are not supported in this version: Pathway session type PATHSENDNOOVERRIDE and PATHSENDOVERRIDE commands ADSPPORT object Step-Aside feature Silent Installation on Windows Rscserv -install, rscserv -installfresh, and rscserv -remove options. Migration Tips RSC/MP utilizes Piccolo transport. The Piccolo transport and RSC/MP are packaged as a single product. Each new release of RSC/MP provides a host component that supports clients from some number of previous releases. However, previous releases of the host component are NOT guaranteed to work with newer clients. As a general rule the version of RSC/MP installed on the workstation should be no more recent than the version on the host. For example, the host component TDP version 7.3 is compatible with client versions 6.3 through 7.3; however TDP version 6.3 is not guaranteed to be compatible with a 7.3 client, and this type of configuration is strongly discouraged. The host should be migrated first. Depending on the versions of existing clients, a TDP can support connections from multiple versions of clients, allowing for clients to be migrated over a period of time. See the information below on compatibility issues with a new host and older clients A - 2

183 Migration to RSC/MP 7.3 Migrating from RSC/MP 6.x to RS C/MP 7.3 Migrating from RSC/MP 6.x to RSC/MP 7.3 This section assumes that the Piccolo component has been installed and configured from a previous version. The RSC/MP 7.3 host component supports connection requests from RSC/MP clients 6.x - 7.3, allowing for a mix of old clients and new clients communicating with the new host component as long as the clients are not using functionality that has been discontinued. To migrate from RSC/MP 6.x to RSC/MP 7.3, do the following: 1. Install the new RSC/MP host component, see Section 3, Installing RSC/MP on the Host. 2. (Optional) Verify an existing application can communicate with the new RSC/MP host component. If the application uses features that have been discontinued in the RSC/MP host, adjust the application as necessary. 3. Install the RSC/MP client. Follow the steps for installing RSC/MP that apply to your platform (shown earlier in this manual). 4. Verify that the RSC/MP Transport (Piccolo) configuration is correct and a connection can be made by using the PIPECP CONNECT command. 5. Verify the RSC/MP installation by using the RSCTEST or RSCTESTW program; see Testing the RSC/MP Client Configuration on page Verify an existing application works with the new client. A - 3

184 Migration to RSC/MP 7.3 Migrating from RSC/MP 6.x to RS C/MP 7.3 A - 4

185 B Installation Troubleshooting This appendix describes the test programs and procedures for checking the installation and configuration of RSC/MP and how to report problems to HP Global Customer Support Center (GCSC). Notes About Diagnostic Clues Many things that can go wrong in the RSC/MP system (such as misconfigurations, API programming errors, operational and network failures) can be diagnosed using the RSC/MP primary logging functions. However, certain serious error situations (such as exhaustion of certain operating-system resources) may prevent RSC/MP from using its normal logging mechanism. If your system seems to operate incorrectly (processes hang or exit unexpectedly), check for the following telltale files and report them to technical support. For Windows or UNIX: Check the bin subdirectory of the RSC/MP install for any file whose name starts with nif and ends with.bad such as nif206.bad. For NonStop: Check in the product installation subvolume for any file whose name starts with ZZBAD such as ZZBAD206. How to Test the Configuration RSC/MP includes diagnostic test programs that can help verify that the host TDP and the workstation are properly configured. Although these programs supply basic performance information, they are not appropriate for use as benchmark tools. The RSC/MP test host server program (TDDSVR) echoes a test message back to a workstation; no database I/O operation takes place. The sample TDP start up file STARTRSC shipped with the TDP includes a RUN statement to start the TDDSVR. Note. The RSC/MP test server must be named $TDD for the RSC/MP test program to work. The RSC/MP test programs are: RSCTESTW and RSCPINGW for Windows RSCTEST64 and RSCTESTW64 for Windows Vista (64-bit) clients RSCTEST for Windows and UNIX All of these programs rely on the RSC.INI file for their configuration. RSCTESTW allows setting of some options. To verify the installation and configuration, start the RSC/MP test program. This program will report the status of the connection. If the RSC/MP test program fails or returns an error message, use the information in the rest of this appendix to diagnose and correct the error condition. B - 1

186 Installation Troubleshooting How to Trace Errors How to Trace Errors This appendix provides a step-by-step process for troubleshooting an RSC/MP connection. This process includes the following assumptions: You have followed the instructions for installing RSC/MP on the host and workstation. Using this procedure, you can quickly target the most common problems and provide a resolution for most of them. While the examples in this appendix are for RSC/MP Windows, much of the information is also useful for the UNIX environment. Step 1. Determine if Your RSC/MP Software is Current and Compatible 1. On the host, enter this command at a TACL prompt: VPROC filename This example shows the version (T9617D42) and VPROC date (27 September, 2002) for the installed TDP: > vproc tdp VPROC- T9617D42 - (29 JUL 96) SYSTEM \MYTDP Date 28 MAR 2002, 14:12:56 COPYRIGHT TANDEM COMPUTERS INCORPORATED $USER.DVTDP.TDP Binder timestamp: 20MAR02 11:22:40 Version procedure: T8432D44_01JUL97_CRTLMAIN Version procedure: T9711V63_27SEP2002_630_004 Version procedure: T8432D44_01JUL97_CRTLNS Version procedure: T8680D40_01NOV95_D40_V27_BASE Version procedure: T9711V63_27SEP2002_Libpipe330 Native Mode: runnable file 2. On a workstation, enter this command: RSCVPROC.EXE filename This example shows you the version (T7985V70) and release date (27 September, 2003) of the RSC/MP file specified in filename. You can check the executable file (RSCPIPE.EXE), and library files (dll,.so, and so on) to see that they are the same version. RSCVPROC - T7985V63_27SEP2002_630_004 RSC/MP TM Version Display Utility. HP NonStop RSC/MP using technology from Cornerstone Software, Inc. Copyright (c) Cornerstone Software, Inc. All rights reserved. Scanning file "RSCPIPE.EXE" Version: T7985V70_27SEP2003_700_002 B - 2

187 Installation Troubleshooting Step 2. Determine if the Communications Tr ans por t is F unc ti onal 3. Compare the results of the commands above to the RSC/MP host and client softdocs to verify that compatible RSC/MP software is running on the NonStop host and the workstation. Step 2. Determine if the Communications Transport is Functional Use a tool provided by the communications transport provider, such as PING for TCP/IP or start a TACL session to verify that the network is working correctly. Step 3. Check the Piccolo Configuration Files The Piccolo Configuration Check program reports errors that are not detected by the Piccolo subsystem. The Piccolo subsystem searches for specific options in specific sections; the Piccolo Configuration Check program analyzes each entry to detect: Unrecognized options Options in the wrong section Options that have missing or incorrect data NIFs referenced but not configured Required elements that are not specified Use the Piccolo Configuration Check program (pcfgchk) to verify that the Piccolo configuration files on the host and workstation do not contain incorrect data. 1. On the host, enter this command at the TACL prompt: > run pcfgchk which should produce output similar to the following (line numbers and sections processed will vary depending on the data in the Piccolo Configuration file): Piccolo Configuration Check Program - T9711V70 - (28SEP2003) /001 - NonStop Copyright (c) Cornerstone Software, Inc. All rights reserved. Checking configuration file $system.zrschost.pipeini Processing section [pipeman] Processing complete for section [pipeman], (Lines 1-11). Processing section [nif-tcp] Processing complete for section [nif-tcp], (Lines 12-13). Final processsing......processing complete. B - 3

188 Installation Troubleshooting Step 4. Check the Host Configuration 2. On a Windows workstation or a UNIX workstation, enter this command: > pcfgchk which should produce output similar to the following (line numbers and sections processed vary depending on the data in the Piccolo Configuration file; VPROC and configuration file names will vary depending on the platform): Piccolo Configuration Check Program - T7981V70 - (28SEP2003) /001 - Win32 Copyright (c) Cornerstone Software, Inc. All rights reserved. Checking configuration file c:\rsc\bin\pipe.ini Processing section [pipeman] Processing complete for section [pipeman], (Lines 1-8). Processing section [nif-tcp] Processing complete for section [nif-tcp], (Lines 9-12). Final processsing......processing complete. 3. If any error or warning is reported, refer to Creating the Configuration File (for all installations) on page 5-10 to find information which may help determine the cause of the problem. Modify the Piccolo Configuration file as needed to eliminate any errors and warnings. Step 4. Check the Host Configuration 1. Verify that the appropriate TDP objects are started (for example, TERM and PIPE) by entering the following command at a TACL prompt: 1>RSCCOM $TDP; STATUS TERM * If the appropriate object is not started, verify your configuration files by entering the following command at a TACL prompt: 2>RSCCOM $TDP; INFO TERM * Verify that the appropriate object is configured and all named processes are referenced correctly. Make any corrections and start the object, as required. 2. Ensure that the TDDSVR process is running as a named process $TDD on the host. This is the process that echoes messages that the workstation test program sends to the NonStop host. Enter the following command at a TACL prompt: 3>STATUS $TDD B - 4

189 Installation Troubleshooting Step 5. Run the Workstation RSC/MP Test Program If no process is found, start the process before proceeding: 4>RUN $SYSTEM.ZRSCHOST.TDDSVR /NAME $TDD,NOWAIT/INTERPROCESS If there is more than one RSC/MP ISV on your system, be sure that you are using the correct one. Use the VOLUME command to locate to the ISV for the version of RSC/MP that you are going to use. 3. Ensure that a TDP process is running. The installation process moves the TDP object code to $SYSTEM.SYSTEM. Enter the following command at the TACL prompt: 5> STATUS *,PROG $SYSTEM.SYSTEM.TDP There must be at least one TDP process running on the NonStop system; there can be more. If the TDP process with a configuration you need is not running, start the TDP process. Step 5. Run the Workstation RSC/MP Test Program The RSC/MP test program should immediately report message traffic between the workstation and NonStop host. If the test fails, you receive an appropriate error message. Record the message number and see the Remote Server Call (RSC/MP) Messages Manual to investigate its cause and remedy. Step 6. Interpret the Workstation and Host Error Messages The RSC/MP product provides error messages on both the workstation and the NonStop host. These error messages provide the first opportunities to resolve problems with RSC/MP connectivity. The error messages that the RSC/MP test program displays can help you to determine if the problem is on the workstation or the NonStop host. If the problem is on the host, TDP error messages help to identify a solution. To interpret errors, it is necessary to understand the conditions required for establishing a successful RSC/MP environment: 1. RSC/MP can run on the workstation. In the Microsoft Windows environment, RSC/MP must communicate with any necessary DLL libraries needed to support its API calls. 2. RSC/MP can find and open the correct RSC.INI file. 3. RSC/MP can successfully use the communications subsystem on the workstation. 4. A communication channel (for example, a network) exists between the workstation and the host. 5. The communications subsystem on the NonStop host acknowledges or receives messages from the workstation. B - 5

190 Installation Troubleshooting Step 6. Interpret the Workstation and Host E rror Mes s ag es 6. Messages from the workstation can reach the target TDP process on the NonStop host. This requires that the NIF is communicating with the correct port in the NonStop communications subsystem and that the port is started. 7. The TDP process is able to open and communicate with the designated server process on the NonStop system. This requires that an RscConnect be established between the RSC/MP client and the TDP TERM object, that the TERM object is started, and that the TERM is passing messages to the host server. Proper interpretation of RSC/MP error messages should help you determine where in the previous list of conditions the error occurred. To understand an error message, you must first be able to read the message number. A typical error contains an error number and extension; these are coded in both decimal and hexadecimal; for example: Error ( Hex) To find the description of an error, first look at its hex number; for example, This is composed of a base value of 2000 plus the hex value of 385 (385 is equivalent to a decimal error number 901). The base number, 2000, indicates that this is a Pathsend error message. The error extension (in this example, -0 or -0000) may contain an extended error code reported by an underlying subsystem: Guardian File System, API, Pathway/TS, and Pathsend messages have extended error numbers. Look up the extended error codes in the appropriate documents. B - 6

191 Installation Troubleshooting Step 7. Check the Status of the TDP Objects Step 7. Check the Status of the TDP Objects Follow these steps to determine the current status and most recent errors of TDP objects: 1. Use the RSCCOM STATUS command for TERM objects, STATUS TERM *. 1 (( status term * Term Status Conn Sess Last Event (DYNAMIC:TERM01) Started 0 0 TERM started. [ 2802 (DYNAMIC:TERM02) Started 2 2 TERM started. [ 2802 (DYNAMIC:TERM03) Started 0 0 TERM started. [ 2802 (DYNAMIC:TERM04) Started 0 0 TERM started. [ 2802 (DYNAMIC:TERM05) Started 5 5 Guardian error (DYNAMIC:TERM06) Started 0 0 TERM started. [ 2802 (DYNAMIC:TERM07) Started TERM started. [ 2802 (DYNAMIC:TERM08) Started 0 0 DYNAMIC Template 9 TERM objects have been configured. 2. Use the RSCCOM STATUS command for the PIPE object you are using: 2 ((status pipe * PipeName Status Sessions Last Event TDPPIPE Started 17 PIPE started. [ 8802 ] 1 Pipe objects have been configured. The Last Event column shows the host-generated error or status message for the TERM and PIPE objects. The numbers enclosed in square brackets are either error or internal event numbers. 3. A detailed status report of a TDP object can be obtained using the STATUS DETAIL command. 3 ((status pipe PipeName, detail PipeName Status Sessions Max Message Size Last Event TDPPIPE Started PIPE started. [ 8802 ] Terms Connected Time Connected RSCQA1 Tue May 3 14:01: B - 7

192 Installation Troubleshooting Step 8. Check the Status of the Components Step 8. Check the Status of the Components Check the status of the RSC/MP Transport components: > pipecp status nif NIF name Type Process Pri Links Address nif01 TCP/IP 4c (port 2787) > pipecp status System Address: mysys.mydomain.com Version: T7981V62 - (30SEP2001) /001 - Win32 Configuration File: C:\RSC\bin\pipe.ini License Mode: Runtime License Code: None Log File Name: pipelog Log Level: 2 Clients: 0 Network Interfaces: 0 inbound, 0 outbound Links: 0 Pipes: 0 connected, 0 active open, 0 passive open Step 9. Run Your RSC/MP Application If the RSC/MP test program worked correctly, run your RSC/MP-based application. Step 10. Turn on Additional Logging If the preceding steps are not sufficient to resolve the cause of an error, you must gather additional information. RSC/MP provides several points to collect logging information. HP Global Customer Support Center (GCSC) may request these and will describe how to collect them. For more information about logging, see How to Use Logging on page B-9. B - 8

193 Installation Troubleshooting How to Use Logging How to Use Logging This subsection shows how to use logging on the RSC/MP components. Figure B-1. Log Collection Points Workstation NonStop Host RSC API logging RSC/MP application Pipeman RSCPIPE RSCPIPE logging TDP Pipeman TDP logging servers Piccolo logging nifsock nifsock Piccolo logging TCP /IP TCP/IP TCP/IP tracing CDT011 B - 9

194 Installation Troubleshooting RSC/MP API Logging RSC/MP API Logging API logging can be used to record certain details of the internal activities of the RSC/MP API library (DLL or shared library) for diagnostic purposes. When engaged, the logging function adds processing burden to the RSC/MP client application and generates potentially large log files. Logging should therefore be engaged only when required by Customer Support. To engage API logging, use the following options:. RSC.INI Option DEBUG_TYPE = 1 DEBUG_NAME = logfilename Description Engages API logging. Names the file to which logged data will be written; a fully qualified path and file name is recommended. If the file already exists, new log entries are appended to it. DEBUG_LEVEL = 3 Selects the greatest level of detail. Substitute 2 for medium detail or 1 for least detail. DEBUG_MASK_RSC = 1 DEBUG_MASK_PIPE = 1 DEBUG_MASK_API = 1 DEBUG_MASK_SNO = 1 DEBUG_MASK_CONNECT = 1 Enables logging of interactions with the RSC/MP Host. Enables logging of local interaction with the Piccolo transport. Enables logging of entry into and exit from the API functions and some parameter-validation errors. Enables logging of unexpected internal errors and internal states that Should Not Occur. Enables logging of interaction with the RSCPIPE process. Use one of the following methods to specify the API logging options: If the client application uses the default options (RSC_DEFAULT_OPTIONS), put the API logging options into the configuration file RSC.INI. If the application loads options from a file explicitly, put the API logging options in the file whose name is being passed to the RscLoadOptions function. B - 10

195 Installation Troubleshooting RSCPIPE Logging If the client does not use RSC_DEFAULT_OPTIONS and does not call RscLoadOptions, follow the steps below to force the use of options. This setup will cause the RSC/MP API to load RSC_DEFAULT_OPTIONS from the specified file at the beginning of the first RSC/MP API function that the application calls. 1. Put the API logging options into a new options file. 2. Define the environment variable RSC_FORCE_INILOAD to contain the fully qualified path name of the new file. 3. Start the client application. RSCPIPE Logging To enable RSCPIPE logging, the process must either be started manually with the -d command line switch and the platform-specific qualifiers, or the switch and qualifiers can be supplied via the RSC.INI option SUBSYSTEM_CMDLINE. Starting the RSCPIPE process is described in Configuring the RSC/MP I/O Manager Process (RSCPIPE) on page An example for the Windows platform is: RSCPIPE dfc:\rsc\rscpipe.log -c255 -l3 An example for the UNIX platform is: rscpipe.exe d -c255 -l3 >rscpipe.log B - 11

196 Installation Troubleshooting Piccolo Logging Piccolo Logging Piccolo logging is enabled by using the PIPECP LOGLEVEL command on both the RSC/MP client and the NonStop host. The following example shows the currently defined log levels. >pipecp loglevel Critical errors 1 Errors requiring user intervention 2 Errors which may require user intervention 4 Information such as startup banners 8 Main loop events 16 API events 32 System to system addressing 64 NIF main loop 128 TCP/IP NIF (NIFSOCK) 256 NETBIOS NIF (NIFNB) 4096 Main loop events for PIPECP processing 8192 API events for PIPECP processing Logging module events Miscellaneous internal housekeeping events For more information about Piccolo logging, see Specifying Piccolo Logging on page B - 12

197 Installation Troubleshooting TDP Logging TDP Logging Enabling TDP logging is a two step process: 1. A log file must be opened. 2. The PIPE and/or TERM object logging attributes must be selected. You can use the following RSCCOM commands to enable TDP logging: RSCCOM Command LOGOPEN $s.#tdplog ALTER PIPE rsc LOGEVENTS ALL ALTER TERM term01 LOGEVENTS ALL Description The log file can be a spooler file, an unstructured Enscribe file, or a terminal ID. ALL could be replaced by one or more of the individual event types listed under PIPE Object Event Types on page ALL could be replaced by one or more of the individual event types listed under TERM Object Event Types on page See TDP Logging on page 10-6, for more information about TDP logging. Section 11, RSCCOM Command Reference, describes the RSCCOM commands in further detail. B - 13

198 Installation Troubleshooting How to Report Problems How to Report Problems If you must call HP Global Customer Support Center (GCSC), be ready to supply the following information. Copy or print these pages and complete this information. RSC/MP Information RSC/MP versions (see Step 1. Determine if Your RSC/MP Software is Current and Compatible on page B-2) Workstation NonStop Host RSC/MP component that has the problem: Detailed description of the problem: Instructions to reproduce the problem: TDP log information, if any B - 14

199 Installation Troubleshooting How to Report Problems Transport Information Transport type NetBIOS TCP/IP LAN vendor (3COM, Ungermann-Bass, or other) Protocol stack and drivers used (such as NBP, or other) Workstation Information Operating environment and version Manufacturer and model Memory amount NonStop Host Information Processor type NonStop Kernel release Communications configuration B - 15

200 Installation Troubleshooting How to Report Problems HP NonStop Remote Server Call (RSC/MP) Installation and Configuration G uide B - 16

201 C RSCCOM Syntax Summary This appendix lists RSCCOM commands by functional group. See Section 11, RSCCOM Command Reference, for more detail about these commands. See Notation Conventions on page xiii at the beginning of this guide for the conventions used to express command syntax. Working with RSCCOM These commands are processed by RSCCOM only. The TDP does not need to be opened to use these commands. HELP Get help HELP command HELP type ATTRIBUTES HELP type attribute EXIT (or E or <Ctrl-Y>) HISTORY (or H) FC FC prefix FC number!!prefix!number Get help on a specific command Get a table that lists every attribute for a given object type Get the description of a given attribute for a given object type Exit from RSCCOM Display the last 20 commands Fix the previous command Fix the last command that started with a given prefix Fix a stored command by number Execute the previous command Execute the last command that started with a given prefix Execute a stored command by number C - 1

202 RSCCOM Syntax Summary Working With the TDP as a Whole OBEY filename [ text MAXERRORS number MAXWARNINGS number OPEN [\system.]$process Working With the TDP as a Whole Accept input from the given filename Remainder of line is a comment (Use this inside the OBEY file only. It is not accepted when RSCCOM is used interactively.) Set the maximum allowable number of errors Set the maximum allowable number of warnings Open a TDP process for RSCCOM to control RSCCOM passes these commands to the TDP. Before using these commands, the TDP process must be opened. STATUS TDP VERSION Get TDP status Get TDP process name and version information CONTROL TDP BACKUPCPU number CONTROL TDP BACKUPCPU NONE CONTROL TDP SECURITY value CONTROL TDP SUPPRESSEMS value Establish a backup TDP process on a CPU Discontinue a backup TDP process Set TDP security Suppresses or enables logging of the EMS events for object state changes LOGOPEN filename LOGCLOSE Start logging to the named file Stop logging C - 2

203 RSCCOM Syntax Summary Working With Objects Within the TDP Working With Objects Within the TDP The commands in the following tables work with objects of the following types: ACS PIPE TERM Saving keystrokes by setting a default object type Using the ASSUME command allows you to avoid entering the object type repeatedly. ASSUME type ASSUME Establish a default object type (with this done, you can omit typea in the commands listed in the tables below) Cancel the established ASSUME Setting attributes for objects that do not exist yet When you ADD an object, the new object takes on the attributes you set with these commands: SET typea attribute value RESET typea SHOW typea Set one attribute of the type Reset all attributes to the default values of the type Show all attributes of the type C - 3

204 RSCCOM Syntax Summary Working With Objects Within the TDP Adding, modifying, and deleting objects ADD typea name ALTER typea name attribute value DELETE typea name DELETE typea * Add a new object of the type Change one attribute of an existing object of the type Delete an object of the type Delete all objects of the type Starting and stopping objects START typea name START typea * STOP typea name STOP typea * ABORT typea name ABORT typea * Start an object of the type Start all objects of the type Stop an object of the type that has no session active Stop all objects of the type that do not have sessions active Stop an object of the type, aborting its sessions and transactions Stop all objects of the type, aborting its sessions and transactions C - 4

205 RSCCOM Syntax Summary Working With Objects Within the TDP Getting information about objects INFO typea name [OBEYFORM] INFO typea * STATS typea name [ RESET ] STATS typea * [ RESET ] STATUS typea name [ DETAIL ] STATUS typea * [ DETAIL ] Sending messages to RSC/MP applications TELL term-name alias-type alias message-text Show the attributes of one object of the type [optionally, in a format that can be used as input in an OBEY file] Show the attributes of all objects of the type Get statistics on one object [and optionally reset counters] Get statistics on all objects of the type [and optionally reset counters] Get status information on one object [and optionally get detailed status] Get status information on all objects of the type [and optionally get detailed status] Send a message using Unsolicited Message Service (UMS) C - 5

206 RSCCOM Syntax Summary Working With Objects Within the TDP C - 6

207 D Resolver Reference Tags This appendix lists the extended address tags for the NetBIOS and TCP/IP platforms. The NIF address tag applies to all platforms (listed under All NIF Reference Tags on page D-1). These tags can be referenced in the Resolver section (preceded by the section name [Resolver] in PIPE.INI file) to map (or resolve) system addresses to corresponding extended addresses. See Creating the [RESOLVER] Section (optional, for workstations only) on page 5-15 for more information about the [Resolver] section. All NIF Reference Tags NIF Type Tag Name Tag Value Format All NIFs NIF network interface name network interface name is a valid NIF name. NetBIOS Reference Tags (nifnb) Tag Name NBName Tag Value Format name[.lana] name is a valid NetBIOS name or an asterisk (*) to indicate to resolve the address using broadcast name resolution. lana is the optional LAN adapter number. If not specified, the current configuration of the NIF s LAN adapter number is used. D-1

208 Resolver Reference Tags TCP/IP Reference Tags (nifsock) TCP/IP Reference Tags (nifsock) Tag Name IP Tag Value Format ipaddress. port * ipaddress is a valid IPv4 address (example: ). port is an optional port field. If not specified, the current configuration of the NIF service port is used. * indicates the address is resolved using DNS and overrides any other IP address specified. This tag is only used in the Resolver section. Tag Name IPv6 Tag Value Format ipaddress. port * ipaddress is a valid IPv6 address (example: fe80::cafe:babe ). port is an optional port field. If not specified, the current configuration of the NIF service port is used. * indicates the address is resolved using DNS and overrides any other IP address specified. This tag is only used in the Resolver section. D-2

209 E Best Practices Guide This appendix contains information intended to help you use RSC/MP effectively, including: Three conceptual models showing a range of RSC/MP configuration styles, see Model Configuration Scenarios on page E-1. Notes about configuring home terminals for RSC/MP, see Host Home-Terminal Considerations on page E-12. Model Configuration Scenarios This subsection describes three configuration scenarios. Your own configuration will differ from these scenarios according to the requirements, goals, and available resources in your RSC/MP installation. These scenarios are provided only as a conceptual framework that might be helpful when making choices that will affect availability and throughput in RSC/MP. The following discussion is based on the use of TCP/IP as the network protocol. Within this subsection, NIF refers to the Piccolo TCP/IP network interface (NIFSOCK). Similar methods and considerations apply to RSC/MP installations that use other protocols. Within this subsection, [RESOLVER] refers to the RESOLVER section of the Piccolo configuration file. Scenario 1 In a development environment or low-volume, occasional-use production environment, redundancy and high throughput may not be requirements. In this case, a configuration similar to the following can be used (see Figure E-1): E - 1

210 Best Practices Guide Scenario 1 Figure E-1. Scenario 1 workstation (typical) workstation (typical) NonStop host HOST1 Application Application Servers S er v er s S er v er s RSCPIPE RSCPIPE TDP PIPEMAN PIPEMAN PIPEMAN NIF NIF NIF TCP/IP TCP/IP TCP/IP Network CDT012 NonStop host configuration One TDP One PIPEMAN process One NIF One network adapter Workstation configuration One PIPEMAN process One NIF One network adapter Advantages This is the simplest RSC/MP configuration and the easiest to configure. E - 2

211 Best Practices Guide Scenario 1 Disadvantages This configuration does nothing to provide fault tolerance. If the host TDP or PIPEMAN process should crash, no workstation will be usable. Loss of the host NIF process can be tolerated, since PIPEMAN will restart the NIF automatically; but if the CPU on which the NIF is running goes down, if the network adapter fails, or if the network segment goes down, the system cannot be used. The host PIPEMAN and TDP processes will become bottlenecks and limit system throughput when many workstations attempt to use RSC/MP concurrently. Possible improvements to this configuration To improve availability, consider using the active backup capability of the host TDP and PIPEMAN processes. Active backup allows persistent operation in the face of a CPU outage or an RSC/MP crash on the host. For example, if the CPU on which the PIPEMAN process is running should go down, the PIPEMAN backup process would take over on a different CPU and restart the NIF process. The TDP would then establish contact with PIPEMAN and become ready to handle new connection requests (each workstation must reconnect). To improve throughput, consider running additional instances of the entire RSC/MP host process set (TDP plus PIPEMAN plus NIF). When doing so, use PARAM PIPEINI to direct each TDP to its intended instance of PIPEMAN. The host NIFs can be configured to run on the same network adapter or on different network adapters. In either case, each workstation must be configured to reach the specific, intended NIF processes: Multiple NIFs on the same network adapter (see Figure E-2). The host NIFs must listen on different service ports. In this case you need not give each host PIPEMAN a unique SystemName, as long as you configure each workstation to use only the one desired service port when connecting to the host. The example shown in the diagram includes two groups of workstations, A and B, which both connect to HOST1 using different service ports. Within the workstation Piccolo configuration, port 5001 or port 5002 would be configured in the [NIF-name] section or within the [RESOLVER] section. E - 3

212 Best Practices Guide Scenario 1 Figure E-2. Scenario 1 improved with NIFs on the same network adapter workstation (group B ) workstation (group A ) NonStop host HOST1 Application Application Servers S er v er s S er v er s RSCPIPE RSCPIPE TDP TDP PIPEMAN PIPEMAN PIPEMAN PIPEMAN NIF TCP/IP port 5002 NIF TCP/IP port port NIF $ZTC0 NIF port Network CDT013 Multiple NIFs on different network adapters (see Figure E-3). In this case, you must give each PIPEMAN instance a unique SystemName. From the workstation s perspective, each Piccolo instance on the host appears to be a different host. Configure the DNS server to give the correct IP addresses for the network adapters being used, according to the names configured in Piccolo. The example shown in the diagram includes two groups of workstations, A and B, which connect to logical (Piccolo) HOST1A and HOST1B. The DNS server should be configured to map HOST1A and HOST1B to the proper IP addresses; or alternatively, the Piccolo [RESOLVER] section can be used on the workstations. E - 4

213 Best Practices Guide Scenario 1 Figure E-3. Scenario 1 improved with NIFs on different network adapters workstation (group B ) workstation (group A ) NonStop host HOST1 Application Application Servers S er v er s S er v er s RSCPIPE RSCPIPE TDP TDP PIPEMAN PIPEMAN PIPEMAN PIPEMAN SystemName HOST1A SystemName HOST1B NIF TCP/IP port 5002 NIF TCP/IP port 5001 NIF $ZTC0 NIF $ZTC Network CDT014 By running multiple Piccolo instances on the host, you can improve throughput by carefully assigning each workstation to a specific host Piccolo. This technique does not provide any kind of automatic load balancing. E - 5

214 Best Practices Guide Scenario 2 Scenario 2 A more typical production environment may need a moderate level of redundancy and provision for greater system throughput. In this case, a configuration similar to the following can be used (see Figure E-4). Figure E-4. Scenario 2 workstation (typical) workstation (typical) NonStop host HOST1 Application Application Servers S er v er s S er v er s RSCPIPE RSCPIPE TDP TDP TDP active backup PIPEMAN PIPEMAN PIPEMAN NIF NIF NIF NIF NIF NIF TCP/IP TCP/IP $ZTC0 $ZTC1 $ZTC2 $ZTC Network DNS serves addresses round-robi n to wor kstations calling HOST1: first caller: second c aller: third caller: etc. CDT015 NonStop host configuration Multiple TDPs, configured with identical PIPE, TERM, and ACS objects; each TDP has its backup process enabled One PIPEMAN process, with backup Multiple NIFs, each configured for a different network adapter These host processes are running in different CPUs where possible E - 6

215 Best Practices Guide Scenario 2 Workstation configuration One PIPEMAN process One NIF One network adapter DNS configuration This configuration relies on the DNS server to cause incoming connection requests to be distributed among the NIFs. For example, a round-robin DNS system can be employed. The example shown in Figure E-4 makes use of a DNS server that will give a different IP address for HOST1 on each name lookup. The first workstation that connects uses , the second uses , and so on. If a round-robin DNS system is not available, the individual workstations need to be configured to connect to specific NIFs on the host by using the [RESOLVER] section (see the text at the bottom of Figure E-5). This configuration is more complicated but does not severely reduce the throughput and availability, because the [RESOLVER] entry for a host can give multiple IP addresses for that host in order to handle the contingency that the first listed IP address cannot be used (for example due to a network-adapter failure on the host). E - 7

216 Best Practices Guide Scenario 2 Figure E-5. Scenario 2 modified to run without round-robin DNS workstation (group B ) workstation (group A ) NonStop host HOST1 Application Application Servers S er v er s S er v er s RSCPIPE RSCPIPE TDP TDP TDP active backup PIPEMAN PIPEMAN PIPEMAN NIF NIF NIF NIF NIF NIF TCP/IP TCP/IP $ZTC0 $ZTC1 $ZTC2 $ZTC Network Group B workstations have [RESOLVER] HOST1=ip: ,ip: Group A wor kstations have [RESOLVER] HOST1=ip: ,ip: CDT016 Advantages This configuration provides better throughput than does the configuration in scenario 1: The DNS system distributes connections among the participating NIFs, and the PIPEMAN process distributes the connections among the participating TDPs in a round-robin fashion. This configuration can tolerate the loss of a CPU or network adapter on the host. Disadvantages This configuration is more complex than the configuration in scenario 1. The PIPEMAN process can become a bottleneck when many workstations are connected through it and are making many RSC/MP requests. The practical saturation point of the PIPEMAN process can be as low as two or three TDPs and two or three NIFs, depending on the load. E - 8

217 Best Practices Guide Scenario 2 Possible improvements to this configuration To alleviate the heavy loading on the PIPEMAN process, consider running additional instances of PIPEMAN, each with its own set of TDPs and NIFs (see Figure E-6). Use PARAM PIPEINI to direct each TDP to its intended instance of PIPEMAN. Give each PIPEMAN instance its own SystemName setting, and configure each workstation to use one of those names. Configure DNS to resolve each host name appropriately (in the example shown in the diagram, DNS resolves each of two host names to two different IP addresses using the round-robin method). Figure E-6. Scenario 2 improved with multiple PIPEMAN instances workstation (group B ) workstation (group A ) NonStop host HOST1 Application Application Servers S er v er s S er v er s RSCPIPE RSCPIPE TDP TDP TDP T DP PIPEMAN PIPEMAN Sys temname HOST1A PIPEMAN PIPEMAN SystemName HOST1B NIF NIF NIF NIF NIF NIF TCP/IP TCP/IP $ZTC0 $ZTC1 $ZTC2 $ZTC Network Group B works tations use HOST1B Group A works tations use HOST1A DNS serves addresses round-robin: Wor kstations calling HOST1A get or Wor kstations calling HOST 1B get or CDT017 E - 9

218 Best Practices Guide Scenario 3 Scenario 3 In a critical production environment where redundancy and high performance are major requirements, two separate networks might be used (different wires, switches, hubs, routers, and so on). In this case, a configuration similar to the following can be used (see Figure E-7). Figure E-7. Scenario 3 workstation (group B ) workstation (group A ) NonStop host HOST1 Application Application Servers S er v er s S er v er s RSCPIPE RSCPIPE TDP TDP TDP T DP PIPEMAN PIPEMAN Sys temname HOST1A PIPEMAN PIPEMAN SystemName HOST1B NIF NIF NIF NIF NIF NIF X Y X Y $ZTC0 $ZTC1 $ZTC2 $ZTC B alternate A primary Network X B primary A alternate Network Y Group B workstations have [RESOLVER] HOST1=ip: ,ip: Group A workstati ons have [RESOLVER] HOST1=ip: ,ip: CDT018 E - 10