HP NonStop Remote Server Call (RSC/MP) Programming Manual Abstract This manual provides an overview of RSC/MP. It describes functions and options in the RSC/MP application program interface (API) and discusses how to develop RSC/MP applications on client workstations. This manual also discusses how to develop access control server (ACS) applications on the HP NonStop™ host. Product Version RSC/MP R7.2 Supported Release Version Updates (RVUs) This publication supports G06.
Document History Part Number Product Version Published 425711-001 RSC/MP R6.1 March 2000 520229-001 RSC/MP R6.2 June 2001 522360-001 RSC/MP R6.3 September 2002 522360-002 RSC/MP R7.0 September 2003 522360-003 RSC/MP R7.1 September 2004 522360-004 RSC/MP R7.
HP NonStop Remote Server Call (RSC/MP) Programming Manual Glossary Index Examples What’s New in This Manual ix Manual Information ix New and Changed Information Figures ix About This Manual xi Manual Contents and Organization Audience Requirements xii Related Manuals xii Notation Conventions xii xi 1.
3. API Functions and Options Contents 3.
6. Application Development Contents Application Persistence 5-5 Using Multiple Applications and Connections on a Workstation Data Conversion 5-6 5-5 6. Application Development Development Considerations 6-1 Visual Basic Applications Considerations 6-1 Visual Basic .
8. Unsolicited Message Service Contents Recovering the TDP After a Failure 7-7 Error Handling Code Example 7-8 8. Unsolicited Message Service Unsolicited Messages 8-1 Design Guidelines 8-2 Aliases and UMS 8-3 Sending Messages From the Host 8-4 Receiving Messages on Workstations 8-5 Asynchronous UMS Notification 8-6 Responding to Messages 8-6 Sending Messages Using RSCCOM 8-7 UMS Header Description 8-7 UMS Host Code Example 8-8 UMS Workstation Application Example 8-8 9.
A. Migration to RSC/MP 7.
C. RSC/MP Constants Contents C. RSC/MP Constants D. API Option Definitions Options Listed Alphabetically D-1 Options Listed by Data Type D-6 RscBeginSession Function Options D-6 RscConnect Function Options D-7 RscWrite and RscWriteRead Function Options D-9 E. Function Cross-Reference F. Sample Code Overview C Sample F-1 C w/GUI Sample F-2 Echo Server Sample F-2 IDS Router Sample F-3 Java Sample F-3 Visual Basic Sample F-4 Visual Basic .NET Sample F-4 Index Examples Figures Figure 1-1. Figure 3-1.
Contents Table C-2. Table D-1. Table D-2. Table D-3. Table D-4.
Contents HP NonStop Remote Server Call (RSC/MP) Programming Manual—522360-004 viii
What’s New in This Manual Manual Information HP NonStop Remote Server Call (RSC/MP) Programming Manual Abstract This manual provides an overview of RSC/MP. It describes functions and options in the RSC/MP application program interface (API) and discusses how to develop RSC/MP applications on client workstations. This manual also discusses how to develop access control server (ACS) applications on the HP NonStop™ host. Product Version RSC/MP R7.
What’s New in This Manual • • New and Changed Information The description of the IDS session type has been updated to indicate the API function RscWrite is not supported for IDS sessions; see Interprocess and IDS Session Comparison on page 4-5. The sample program section has been updated with information on the IDS sample and the Echo Server. These samples have been delivered in previous versions of RSC/MP, but this manual did not have a description of them.
About This Manual The HP NonStop Remote Server Call (RSC/MP) product 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 manual describes the concepts and tools involved in developing RSC/MP applications on client workstations. RSC/MP provides an application program interface (API) and function calls for RSC/MP applications.
About This Manual • • • • • Audience Requirements Appendix A, Migration to RSC/MP 7.2, provides information about migrating older versions of RSC/MP to Version 6.3 and lists the deprecated and discontinued functions, constraints and options. Appendix B, Language Conversion for RSC/MP Function Calls, shows the syntax for API function calls in C, COBOL, Pascal, and Visual Basic. Appendix C, RSC/MP Constants, lists the RSC/MP constants and their values.
About This Manual General Syntax Notation Lowercase italic letters. Lowercase italic letters indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name [ ] 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.
About This Manual Notation for Messages 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.
About This Manual Change Bar Notation { } 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. } % Percent Sign.
About This Manual Change Bar Notation 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.
1 Introduction to Remote Server Call (RSC/MP) This section provides an overview of Remote Server Call (RSC/MP), including its features, components, and operation. Overview of Features RSC/MP allows workstations to access Pathway servers and other Guardian processes on a NonStop system. With RSC/MP, you can implement powerful client/server applications—the workstation is the client; the NonStop system, with its Pathway/TS online transaction processing (OLTP) software, is the server.
Introduction to Remote Server Call (RSC/MP) Workstations 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. Figure 1-1.
Introduction to Remote Server Call (RSC/MP) Application Program Interface RSC/MP provides an API and a communications transport on client workstations that support communication between the workstation and the host system. The following subsections describe the RSC/MP components on the client workstation. Application Program Interface The RSC/MP application program interface (API) provides workstation applications with a standard interface for communicating with the NonStop system.
Introduction to Remote Server Call (RSC/MP) Workstation Components Workstation Components The workstation components are: • • • • RSC/MP I/O Manager (RSCPIPE) — Matches I/O replies with requests, notifies applications of I/O completion, maps shared connections to a single host connection, and so on. RSC/MP Transport Pipe Manager (Pipeman) — Maintains the transport connections (using Piccolo), freeing the RSC/MP layers for other functions. You configure Pipeman using the PIPE.INI file.
Introduction to Remote Server Call (RSC/MP) Host Components Host Components The host components are: • • • • • • Transaction Delivery Process (TDP) — A persistent, NonStop process pair running on the NonStop host (see Figure 1-1). The TDP is capable of handling simultaneous access from multiple workstations. The TDP can send messages directly to a Guardian named process, or it can send messages to a Pathsend LINKMON process.
Introduction to Remote Server Call (RSC/MP) TDP TERM Object The TDP consists of these configurable objects: • • • The TERM object corresponds to a workstation. The ACS object defines a user-written access control server that provides security for processes on the NonStop system. The PIPE object provides an interface to a Pipeman process. TDP TERM Object All RSC/MP connections and sessions terminate with a TERM object.
Introduction to Remote Server Call (RSC/MP) Unsolicited Message Service If a TDP process that fails is running in persistent mode, a backup process takes over. After re-establishing communications with a TDP, workstation applications can reconnect and repeat the transaction. See Monitoring Transaction Calls on page 6-6 for more information about using RSC/MP with TMF. For information about TMF on the NonStop system, see the TM/MP Introduction.
Introduction to Remote Server Call (RSC/MP) HP NonStop Remote Server Call (RSC/MP) Programming Manual—522360-004 1 -8 ACS Security
2 Programming Environment This section describes the format of RSC/MP function calls and constants, and the RSC/MP programming environment. Programming Languages You can write RSC/MP applications in these languages: • • For RSC/MP Win-32, any language that can support calling a standard Windows DLL and provide necessary data types. For RSC/MP SCO UnixWare, Solaris, HP-UX, AIX, and Linux systems, any language using the native C compiler.
Programming Environment Naming Conventions Naming Conventions All parameters and variables in this manual conform to the following naming conventions, which define how names indicate both the purpose and data type of an item. All parameter and field names consist of up to three elements: a prefix, a base type, and a qualifier. For example, the pcOptionsSelector parameter has these elements: • • • p, pointer, is the prefix.
Programming Environment RSC.H Header File RSC.H Header File The RSC.H header file is placed by the RSC/MP installation programs in the directory that you specify. This file is shipped with both the workstation RSC/MP component and with the RSC/MP host component. Due to naming convention differences on different platforms, this file has the following names: • • RSC.H on the workstation is used in compiling RSC/MP workstation programs written in the C language.
Programming Environment Contents of the Header File HP NonStop Remote Server Call (RSC/MP) Programming Manual—522360-004 2 -4
3 API Functions and Options This section presents an overview of all functions of the RSC/MP application program interface (API) and the options used to customize the run-time environment of an RSC/MP application. Application Program Interface Functions Figure 3-1 lists the API functions according to functional groups, lists each function’s name in the other languages (shown in parenthesis) that RSC/MP supports, and describes how each function is used. Table 3-1.
API Functions and Options API Options Table 3-1. Functions Listed by Group (page 2 of 2) Functional Group C Language Function Name [Name in Other Languages] Error Processing RscErrorInfo [RSCERI] Obtains the description of an error returned from an RSC/MP function. Unsolicited Messages RscNotifySem [RSCSEM] Receives and replies to unsolicited messages sent to an RSC/MP application.
API Functions and Options Using Option Definition Files There are two ways to manipulate options structures, using the following functions: Method 1 Method 2 RscConnect (RSC_DEFAULT_OPTIONS, ...) RscCreateOptions (ulOptionsHandle) RscBeginSession (RSC_DEFAULT_OPTIONS, ...) RscLoadOptions (ulOptionsHandle, "MYRSCAPP.INI", "MYSECTION") RscConnect (ulOptionsHandle, ...) RscSetOption (ulOptionsHandle, "PATHMON_NAME", "$RSCP", NULL ) RscBeginSession (ulOptionsHandle) ... ...
API Functions and Options Loading Options An application can load different sections of the same INI file by using the RscLoadOptions function (see Loading Options on page 3-4) to change its operation. For example, one section might be appropriate for deposit transactions and another for withdrawals. If options have no preceding section name, they make up the NULL section. When default options are used, RSC/MP first attempts to load the RSC section.
API Functions and Options Using API Functions to Manage Options Using API Functions to Manage Options You might want to read some options from a disk file and set other options programmatically. The following code fragment shows how to combine the two methods of setting options. The options file, RSC.INI, is used to store configuration-type options such as the name of the host server and the group alias used for receiving UMS messages.
API Functions and Options Connecting to the TDP Connecting to the TDP An RSC/MP connection opens a communications channel between your application and the TDP. Establishing a connection ensures that a physical path exists between the workstation and the host system. All application instances that use RSC/MP must issue a call to the RscConnect function. The RscConnect function returns a connection handle for use with other RSC/MP functions.
API Functions and Options Example: Waited I/O Example: Waited I/O This example shows how to use waited API function calls: CHAR acServerName; USHORT uReturn; USHORT uReplySize; USHORT uRequestSize; SHORT nIoHandle = RSC_IO_WAITED; ...
API Functions and Options Example: Nowaited I/O Example: Nowaited I/O This example shows how to use nowaited API function calls: CHAR acServerName; USHORT uReturn; USHORT uReplySize USHORT uRequestSize; SHORT nIoHandle = 1; ...
API Functions and Options Asynchronous Notification Asynchronous Notification RSC/MP provides API functions you can use to request asynchronous notification of I/O completion and UMS receipt. These calls have some platform dependencies. See Section 10, API Function Descriptions, for more information. Processing Errors Use the RscErrorInfo function to obtain text for an error returned for an RSC/MP function.
API Functions and Options Basic API Functions and Options Figure 3-1.
API Functions and Options Basic API Functions and Options Figure 3-2.
API Functions and Options Basic API Functions and Options HP NonStop Remote Server Call (RSC/MP) Programming Manual—522360-004 3- 12
4 RSC/MP Sessions This section describes RSC/MP sessions and describes how to begin and end them. Session Overview An RSC/MP session provides a context for the use of servers, transactions, and the Unsolicited Message Service (UMS). Use a session to perform these tasks: • • • • • Communicate with Guardian named processes. Communicate with Pathway servers through the Pathsend product. Communicate with Pathway servers through a user-written Intelligent Device Support (IDS) requester.
RSC/MP Sessions Session Types Session Types RSC/MP supports two session types: Interprocess and IDS. This section lists the features of each session type, describes options that need to be set and other setup requirements for each session type. The Interprocess Session Type An Interprocess session provides the following features: • • • • • Communicates with Guardian named processes Communicates with Pathway servers Allows client applications to control TMF transactions.
RSC/MP Sessions The IDS Session Type Select the Pathsend delivery mechanism by calling RscWrite or RscWriteRead with a Servername whose first character is NOT a dollar sign ($) or backslash (\). TMF Transactions Each RSC/MP Interprocess session provides the context to support a TMF transaction. Applications can use this feature when the effects of several server I/O operations must be committed all together or not at all.
RSC/MP Sessions The IDS Session Type requester controls transactions. To use TMF with a user-supplied IDS requester, that requester should do the following: • • Use the TMF software to manage the message passed to the Pathway server. Utilize the Guardian BEGINTRANSACTION, ABORTTRANSACTION, and ENDTRANSACTION procedure calls (SCREEN COBOL), as indicated by the TMF information in the application message. The RSC/MP installation on the NonStop system includes sample IDS code.
RSC/MP Sessions Interprocess and IDS Session Comparison Interprocess and IDS Session Comparison This table summarizes the features of the Interprocess and IDS session types.
RSC/MP Sessions Validating a Session HP NonStop Remote Server Call (RSC/MP) Programming Manual—522360-004 4 -6
5 Application Design This section shows you how to design an RSC/MP application. This section also shows how to write an application in persistent mode and how to establish physical and virtual connections between a workstation and a NonStop host. Design Considerations When designing RSC/MP applications, consider these factors: • • • • • • • • • The operating system environment (UNIX, Windows). Note that on some Windows versions, you can run RSC as a Service.
Application Design Resource Sharing Between Threads not provide this mutual exclusion scheme might appear to function correctly, but will be prone to unexpected results that are difficult to diagnose. Resource Sharing Between Threads Connection, session, and I/O handles can be shared between registered threads. In general, the application program must ensure that the use of shared resources is coordinated properly.
Application Design Restrictions Restrictions Some elements of the RSC/MP library are not safe to use in a multithreaded application: • • The default options (selected by using RSC_DEFAULT_OPTIONS as an options handle) are shared between all threads, regardless of thread registration. Any thread using these options is affected by any change made from any other thread. To avoid this condition, have each thread create and load its own options.
Application Design Asynchronous I/O Completion Notification To allow the server to respond in any order to multiple, outstanding, nowaited RscWriteRead function calls, add the SETMODE_30 option (with a nonzero value) to the RSC.INI file, or use RscSetOption in the application program to set this option. When the TDP opens a server using the RSC_ST_INTERPROCESS session type, it sends a SETMODE 30 call to the server, with the param1 value set to 1.
Application Design UNIX Signal Handling UNIX Signal Handling The RSC/MP UNIX library does not process UNIX signals. Therefore, all signals will cause the application’s signal handler to be entered. The user program must protect against reentry into the RSC/MP library as a part of signal processing. Also, if a fatal signal is received, the application should initiate a cleanup of the RSC/MP resources it has in use.
Application Design Data Conversion (either through the RSC.INI file, or an RscSetOption function call), a subsequent call to RscConnect starts another RSCPIPE process under the new name. Data Conversion When designing an application, you must consider converting data. The byte order of INTEGER types on some workstations differs from the byte order on a NonStop system.
6 Application Development This section provides information for developing RSC/MP applications, transaction monitoring for RSC/MP, and application persistence. Development Considerations When developing RSC/MP applications, consider these factors: • • • • • • • If the application is to be written in Microsoft Visual Basic or Microsoft Visual Basic .NET, the programming considerations that are specific to Visual Basic.
Application Development Visual Basic .NET Applications Considerations Visual Basic .NET Applications Considerations When developing Visual Basic .NET (VB.NET) application programs, consider these factors: • • • RSC/MP provides a declaration file for VB.NET developers, RSC.VB. VB.NET does not permit asynchronous notification; therefore, you cannot use the RscNotifyWin, RscNotifySem or RscNotifyThread functions. A VB.NET executable requires the .NET Framework in order to run.
Application Development Formatting and Converting Data Formatting and Converting Data The integer byte order for data on NonStop systems does not always match the byte order of data on workstations. Figure 6-1 shows the byte order of the integers on the NonStop host and on PC workstations. Figure 6-1.
Application Development Upgrading NonStop Applications Written in SCREEN COBOL Upgrading NonStop Applications Written in SCREEN COBOL To upgrade an existing NonStop application to an RSC/MP application, you must convert screens written in SCREEN COBOL to PC COBOL or to Windows screens. With RSC/MP, the user interface on PC workstations can communicate directly with Pathway servers (the Pathway server does not need any changes) or servers other than Pathway.
Application Development Linking Windows 32-Bit RSC/MP Applications Linking Windows 32-Bit RSC/MP Applications RSC/MP applications for Windows should use the RSC/MP API library RSCW32.DLL. The corresponding import library is RSCW32.LIB. These libraries support the STDCALL calling convention, which is the standard used by the Windows API DLLs. Note. Earlier versions of the RSC/MP API library used the CDECL calling convention. For compatibility with existing applications, RSC/MP provides the RSCNT.
Application Development Monitoring Transaction Calls directories named by standard environment variables as listed in the Remote Server Call (RSC/MP) Installation and Configuration Guide (Section 5, Installing RSC/MP on UNIX Workstations). Monitoring Transaction Calls The Transaction Management Facility (TMF) subsystem, the major functional component of the NonStop Transaction Manager/MP product, provides transaction protection, database consistency, and database recovery.
Application Development Generating Transactions Explicitly Generating Transactions Explicitly To generate a TMF transaction explicitly, follow these steps: 1. Issue an RscBeginTransaction function call to begin the transaction. 2. Issue one or more RscWrite or RscWriteRead calls to alter the content of one or more rows or records in the database. After each call, examine the return code.
Application Development Generating Transactions Automatically (Implicitly) Generating Transactions Automatically (Implicitly) Automatic transactions can have these advantages: • • • Reduction of the message traffic between the TDP and the workstation Reduction of CPU use Improvement of response time Instead of issuing RscBeginTransaction and RscEndTransaction function calls, you set the workstation options TMF_OPTION, SUCCESS_HI, and SUCCESS_LO to the desired values and then issue RscWriteRead calls to
Application Development Generating Transactions Automatically (Implicitly) Table 6-1. Definition of TMF_OPTION Values TMF Option Result 0 No automatic TMF operations. 1 RSC_BEGIN_TRANS Begins a TMF transaction before the TDP sends the transaction request to the target server. 2 RSC_END_TRANS Ends the transaction upon completion of the TDP receiving the transaction reply from the target server, if the server reply code is between the SUCCESS_LO and SUCCESS_HI options.
Application Development Generating Transactions Automatically (Implicitly) Server Reply Codes in TMF The RSC/MP server reply code implicitly ends transactions. When used properly, this feature can reduce network traffic by reducing or eliminating calls to RscEndTransaction and RscAbortTransaction. The server reply code that is specified in the SUCCESS_HI and SUCCESS_LO options is an arbitrary value that is stored in the first two bytes of a message.
Application Development Detecting Failed Transactions 6. Set the SUCCESS_LO and SUCCESS_HI options to the desired values. These values establish the range of server reply codes that indicates successful completion. 7. Issue an RscWriteRead call to send the final message in the transaction to the host. 8. Examine the return code from the RscWriteRead call.
Application Development TMF Code Example the client must reconnect and communicate with its server to determine if the transaction was committed. Alternatively, the client application can inform the user that this situation has occurred. The user can then restart the application and determine if the transaction was committed. TMF protection exists only on the host. The actual boundary of a TMF transaction stops at the TDP.
Application Development TMF Code Example #include "rsc.
Application Development TMF Code Example /**************************************************************************** Automatic TMF transaction control with a single-request transaction ****************************************************************************/ /* Create options structure, set for automatic transaction BEGIN and END */ RscCreateOptions ( &ulOptions ); RscSetOption ( ulOptions, "TMF_OPTION", NULL, RSC_BEGIN_END_TRANS ); RscSetOption ( ulOptions, "SUCCESS_LO", NULL, 0 ); RscSetOption ( u
Application Development Persistent Applications /* Send third request to a server.
Application Development • • • Consequences of a Primary TDP Failure Determine, by analyzing the application database, whether or not the transaction that was just committed by using TMF was actually committed to the database. This capability is required to guard against the possibility of a system failure at the time of a transaction commit request. Save the configuration (options and parameters) when the RscConnect and RscBeginSession functions complete successfully.
Application Development Using a Backup TDP 2. Attempt to reconnect to the TDP. Reconnection attempts should occur at reasonable intervals for a reasonable period of time; for example, the application should make a connection attempt every 5 seconds for 60 seconds, or longer. If the connection cannot be established, notify the user that the application has failed and that operator intervention is required. 3. After the connection has been re-established, begin a new session. 4.
Application Development Using a Backup TDP HP NonStop Remote Server Call (RSC/MP) Programming Manual—522360-004 6- 18
7 Message Handling This section describes how to manage error messages that the TDP generates. It also describes how to use the RscErrorInfo function to return API errors and describes types and severities of API errors. Log Events The TDP sends RSC/MP error messages to one of these locations: • • System error and critical error messages are sent, by default, to the Distributed Systems Management (DSM) event collector ($0) or to a log file that you create.
Message Handling Searching for Tokenized Messages Searching for Tokenized Messages You can use the Event Management Service (EMS) to search for tokenized messages. Before running the TDP, follow the steps below to invoke EMS tokenization: 1. At the TACL prompt enter the PARAM command to identify which parameters are in effect. If RSCUSEEMS is defined, EMS templates are used, and “text” tokens are not inserted in error messages. 2.
Message Handling Suppressing Event Types After the TDP Has Been Started Suppressing Event Types After the TDP Has Been Started You can suppress EMS events generated by TDP object state changes after the TDP has been started by entering the following RSCCOM command: CONTROL TDP RSCSUPPRESSEMS Y To allow generation of EMS events for TDP object state changes, enter the following RSCCOM command: CONTROL TDP RSCSUPPRESSEMS N See the Remote Server Call (RSC/MP) Installation and Configuration Guide for more info
Message Handling Error Types and Severity Error Types and Severity The RSC.ERR file is searched each time the RscErrorInfo function is called. Applications can use the return value from this function to recommend corrective actions. The return value (defined in the RSC.H file) is the result of the bitwise OR operation between the error type and the error severity. If the result is zero, the operation terminates successfully. If the result is nonzero, an error code appears.
Message Handling Combined Errors Combined Errors The five error types and three error severity types are combined to produce these return code errors: Error Type Error Severity Combined Return Code Error RSC_CONNECT_ERROR RSC_ERROR_CONFIG RSC_CONNECT_CONFIG RSC_ERROR_FATAL RSC_CONNECT_FATAL RSC_ERROR_RETRY RSC_CONNECT_RETRY RSC_ERROR_CONFIG RSC_IO_CONFIG RSC_ERROR_FATAL RSC_IO_FATAL RSC_ERROR_RETRY RSC_IO_RETRY RSC_PROGRAM_ERROR No error severity associated with this error type.
Message Handling Recovering From Data Communications Failures Table 7-1. Subsystem Error Codes Error Code Base Value Error Type Description RSC_API_BASE 0x0000 API errors. See the Remote Server Call (RSC/MP) Messages Manual RSC_PATHSEND_BASE 0x2000 Pathsend interface errors. See the Pathway Application Programming Guide and the Remote Server Call (RSC/MP) Messages Manual. RSC_FILE_SYSTEM_BASE 0x3000 HP NonStop or Guardian system errors. See the Guardian Procedure Errors and Messages Manual.
Message Handling Recovering the TDP After a Failure and the primary destination. After receipt of a connection failure error, set the HOST_PIPENAME option to the alternate destination and reissue an RscConnect. To reduce the possibility of connection failure errors, multiple NIFs can be configured on the client workstation. The alternate NIF(s) could be configured to use alternate LAN segments or serial communications lines.
Message Handling Error Handling Code Example Error Handling Code Example This code example uses RSC/MP error handling function calls and options. USHORT uReturn, uSubsystem, uError, uExtendedError, uErrorTextSize; char szErrorText[256]; ... uReturn = RscWriteRead (ulOptionsHandle, ... ... if ( uReturn != RSC_SUCCESS ) { uErrorTextSize = sizeof (szErrorText); uReturn = RscErrorInfo( uReturn, &uSubsystem, &uError, &uExtendedError, szErrorText, &uErrorTextSize); if (uReturn & RSC_CONNECT_ERROR) ...
8 Unsolicited Message Service This section describes how to use the Unsolicited Message Service (UMS). Included are examples of code that show how to send and receive messages. Unsolicited Messages The UMS lets host applications send messages to workstation-based applications. An unsolicited message, originated by a host program, is routed by the TDP to the proper workstation session. The TDP uses the terminal name, an alias name, and an alias type to identify the recipient of an unsolicited message.
Unsolicited Message Service Design Guidelines Figure 8-1. Unsolicited Message Service, Flow of Information Client Application NonStop System RscUmsCheck Function 2 1 User-Written Program $TDP.#RSCUMS RscUmsReply Function 4 3 Legend 1 and 2 1 2 WRITE Procedure 3 and 4 WRITEREAD Procedure CDT009 RSC/MP functions on the workstation allow the application to receive and reply to unsolicited messages.
Unsolicited Message Service Aliases and UMS Aliases and UMS Aliases identify recipients of unsolicited messages. Alias types are defined in the RSC.H header file on the workstation and in the RSCH file on the host system. There are two types of aliases: • • SESSION_ALIAS sends messages to specific sessions. GROUP_ALIAS sends messages to many sessions across applications and terminals. The workstation uses the RscSetOption function to register terminal and alias names with the TDP.
Unsolicited Message Service Sending Messages From the Host Table 8-1 lists the possible combinations of terminal names, alias names, and alias types, and which workstation applications receive messages. An asterisk (*) indicates all terminals or all aliases. Table 8-1.
Unsolicited Message Service Receiving Messages on Workstations The UMS header information is in the RSCH file on the host system and in the RSC.H file on the workstation. The header must be included at the beginning of the unsolicited message. The message consists of a header followed by the data the host is sending. The host application initializes the header. The workstation application receives the message data without the header.
Unsolicited Message Service Asynchronous UMS Notification Asynchronous UMS Notification RSC/MP offers platform-specific asynchronous notification of UMS message receipt on all platforms. Use of this feature eliminates the need for polling to determine whether an unsolicited message has been received. RSC/MP offers these methods of requesting notification of UMS receipt: • • • Semaphores — Notification offered on UNIX and Windows with the RscNotifySem function.
Unsolicited Message Service Sending Messages Using RSCCOM Sending Messages Using RSCCOM The RSCCOM TELL command can send informational messages to sessions on remote workstations. The following example sends the message “HELLO” to workstation TERM01 whose group alias is TEST: (( TELL TERM01 GROUP TEST HELLO See the Remote Server Call (RSC/MP) Installation and Configuration Guide for more information about the RSCCOM commands. UMS Header Description When using the UMS header that is included in the RSC.
Unsolicited Message Service UMS Host Code Example acAlias The GROUP_ALIAS or SESSION_ALIAS name, depending on the uAliasType parameter, or an asterisk (*) for all. The name must be terminated with NULL characters or filled to the end with blank characters. Alias names are defined in the RSC.H file. uAliasType The type of alias, either RSC_GROUP_ALIAS or RSC_SESSION_ALIAS.
9 Access Control Server RSC/MP supports application-level security through its access control server (ACS) mechanism. This section describes the ACS mechanism and how to use it. Using ACS Use of ACS is optional. When ACS is not used, the TDP routes RSC/MP client I/O requests to any server, as directed by the RSC/MP application. When ACS is used, the RSC/MP application must supply a user ID and password to create a session with RscBeginSession.
Access Control Server How ACS Works Mapping of RSC/MP sessions to ACS objects can be done in either of two ways: • • In the TDP (recommended) by setting the TERM object’s ACSERVER attribute to the name of the ACS object. This approach provides stronger security because it does not rely on the RSC/MP application to supply the name of a properly configured ACS object. In the RSC/MP application by setting the HOST_ACS_NAME option to the name of the ACS object that should control access.
Access Control Server Security Design Guidelines Security Design Guidelines When designing security for an application: • • • • • • Do not run the TDP under the super ID. Create an ACS. Secure RSCCOM processes by allowing only a particular group of users to have execution access. Secure the TDP by using the RSCCOM command CONTROL TDP SECURITY to set security to an appropriate value. See the Remote Server Call (RSC/MP) Installation and Configuration Guide for information about this command.
Access Control Server Configuring a Workstation for an ACS Configuring a Workstation for an ACS Use the RscSetOption function call to set these options: ACS_BINARY_AREA Used in place of the ACS_MESSAGE_AREA option (shown on page 9-4) to set the contents of the message to be passed to (or retrieve the message received from) the ACS process on the host to a binary string up to 128 bytes long.
Access Control Server A Sample ACS for the NonStop Host HOST_ACS_NAME Use this option to supply the name of the ACS object in the TDP. However, this option is ignored if the TERM object in the TDP is configured to use an ACS object. PASSWORD Each session can have a unique password specified by the client application in an RscSetOption function call. USER_ID This option is case sensitive. Each session can have a unique USER_ID specified by the client application in an RscSetOption function call.
Access Control Server n2 A Sample ACS for the NonStop Host One of these decimal values defining the access to this server process: 1 – Allow access to this server. The client workstation has access only to servers that are explicitly specified as n2=1. 2 – Refuse access to this server. Use this option only to deny access to a specific server class under a PATHMON process; for example, “21 $RSCP” allows access to all server classes under the PATHMON process $RSCP.
Access Control Server A Sample ACS for the NonStop Host 5. Configure the ACS by using one of the following methods: Note. Start the ACS server before configuring the ACS object or the ACSERVER attribute of the TERM object. • Set the TERM attribute ACSERVER to the name of an ACS object.: set term termname ACSERVER acs_object_name acs_object_name must be a valid ACS object name.
Access Control Server Developing an ACS 6. Test the ACS by starting the RSC/MP test application for the client workstation. Ensure that the RSC.INI file for this application is configured for ACS (see Configuring a Workstation for an ACS on page 9-4). If the RSC/MP test application runs without an error, the ACS is working correctly. If the ACS is not configured correctly, the NonStop host or the RSC/MP workstation reports an error.
Access Control Server Authorized List Header uVersion The version of the TDP that the ACS compares to the version of RSC/MP that an application is using to ensure version compatibility with an application. The RSC/MP version is taken from the RSC_VERSION value defined in the RSC.H file. uSessionType The session type (RSC_ST_IDS or RSC_ST_INTERPROCESS) value set by the TDP. acUserId The user ID set by the TDP (from the options area) to be authenticated.
Access Control Server sAcsHeader The ACS header that is included in the RSC.H file (see ACS Header on page 9-8). acAuthorizedList An array of structures of type RSC_ACS_LIST_ENTRY that are returned by the ACS to an ACS object in the TDP. This list is used to validate WRITEREAD requests.
10 API Function Descriptions This section lists all of the RSC/MP API functions in alphabetic order. The following information is provided for each function: • • • • • Statement Description Format Parameter Definitions Return Value Each function is presented with its C language function name. The name of the function in other languages is shown in brackets. The function format includes ‘in’ or ‘out’ to indicate an input or an output parameter.
API Function Descriptions RscAbortTransaction [RSCABT] RscAbortTransaction [RSCABT] The RscAbortTransaction function aborts a transaction that is outstanding for the session indicated by the ulSessionHandle parameter. USHORT RscAbortTransaction (ULONG ulConnectionHandle ,ULONG ulSessionHandle ); /* in */ /* in */ ulConnectionHandle The handle of an existing connection created through the RscConnect function call.
API Function Descriptions RscBeginSession [RSCBGS] RscBeginSession [RSCBGS] The RscBeginSession function begins a session with the TDP after a connection has been established. This call creates the context within RSC/MP for matching I/O replies with requests, for transaction control, and for UMS message routing. Use RscBeginSession before issuing I/O requests or using the transaction management facility.
API Function Descriptions RscBeginSession [RSCBGS] Return Value The return value is zero if the function is successful; otherwise, the function returns one of these result values: RSC_ACCESS_SERVER_IO 1 RSC_INI_FILE_NOT_FOUND 5 RSC_INVALID_CONNECTION_HANDLE 6 RSC_INVALID_OPTIONS_HANDLE 10 RSC_INVALID_SESSION_TYPE 16 RSC_PC_HEAP_EXHAUSTED 22 RSC_INVALID_WAIT_OPTION 31 RSC_OPTIONS_AREA_CORRUPTED 34 RSC_SESSION_LIMIT_EXCEEDED 41 RSC_SESSION_REJECTED_BY_ACS 45 RSC_DUPLICATE_SESSION_ALIAS
API Function Descriptions RscBeginTransaction [RSCBGN] RscBeginTransaction [RSCBGN] The RscBeginTransaction function begins a transaction for the session indicated by ulSessionHandle. The application must call RscConnect and RscBeginSession before using transactions. USHORT RscBeginTransaction (ULONG ulConnectionHandle ,ULONG ulSessionHandle ); /* in */ /* in */ ulConnectionHandle The handle of an existing connection created through the RscConnect function call.
API Function Descriptions RscClearOption [RSCOCL] RscClearOption [RSCOCL] The RscClearOption function resets a selected option in an options structure identified by the ulOptionsHandle parameter to its default value. See Appendix D, API Option Definitions, for a list of options and their meanings. USHORT RscClearOption (ULONG ulOptionsHandle ,CHAR *pcOptionSelector ); /* in */ /* in */ ulOptionsHandle The handle of an existing options structure created through the RscCreateOptions function call.
API Function Descriptions RscConnect [RSCCON] RscConnect [RSCCON] The RscConnect function establishes the connection between the workstation and the TDP. If the function is successful, it places a connection handle in the variable pointed to by the pulConnectionHandle parameter. This handle is used to reference the connection in all subsequent requests destined for the TDP.
API Function Descriptions RscCreateOptions [RSCOC] RscCreateOptions [RSCOC] The RscCreateOptions function creates an options structure to hold options set or retrieved through the RscSetOption and RscGetOption function calls. The options structure is used in many of the RSC/MP API function calls and is referred to by the pulOptionsHandle parameter. See Appendix D, API Option Definitions, for a list of options and their meanings.
API Function Descriptions RscDestroyOptions [RSCOD] RscDestroyOptions [RSCOD] The RscDestroyOptions function deletes an options structure by releasing the space allocated to it. Note. Further use of the options handle causes severe problems. USHORT RscDestroyOptions (ULONG ulOptionsHandle ); /* in */ ulOptionsHandle An existing options handle created by the RscCreateOptions function.
API Function Descriptions RscDisconnect [RSCDIS] RscDisconnect [RSCDIS] The RscDisconnect function terminates the connection between the workstation application and the TDP. This function should be called prior to terminating the workstation application. Any sessions still outstanding on the connection are terminated by the TDP, and transactions outstanding on those sessions are aborted. Note.
API Function Descriptions RscEndSession [RSCEND] RscEndSession [RSCEND] The RscEndSession function terminates the session indicated by the ulSessionHandle parameter. Any transactions still outstanding on the session are aborted, and I/O operations that have not completed are discarded. USHORT RscEndSession (ULONG ulConnectionHandle ,ULONG ulSessionHandle ); /* in */ /* in */ ulConnectionHandle The handle of the connection relevant to the transaction.
API Function Descriptions RscEndTransaction [RSCENT] RscEndTransaction [RSCENT] The RscEndTransaction function ends a transaction that is outstanding on the session indicated by ulSessionHandle. If no transaction is outstanding, an error is returned. USHORT RscEndTransaction (ULONG ulConnectionHandle ,ULONG ulSessionHandle ); /* in */ /* in */ ulConnectionHandle The handle of the connection relevant to the transaction. The connection handle is created by the RscConnect function.
API Function Descriptions RscErrorInfo [RSCERI] RscErrorInfo [RSCERI] The RscErrorInfo function provides detailed information about error codes returned by other RSC/MP API functions. Specifying NULL for a parameter to this function means that the application does not receive the corresponding information. Applications can use the RscErrorInfo return value to determine what corrective action to take.
API Function Descriptions RscErrorInfo [RSCERI] puTextLength If not NULL, on input this field points to the maximum number of characters the function should copy to the location specified by pcErrorText. On output, this field points to the actual number of characters copied. puTextLength must not be NULL if pcErrorText is not NULL. RSC/MP errors have a maximum length of the RSC_MAX_ERR_LENGTH constant.
API Function Descriptions RscErrorInfo [RSCERI] These are the error severities and corrective actions: Error Severity Corrective Action RSC_ERROR_CONFIG A serious error occurred and was caused by an RSC/MP configuration problem. Modify the appropriate configuration parameter. RSC_ERROR_FATAL A connection or session terminated abnormally. Reconnect or begin a new session. RSC_ERROR_RETRY An error occurred that might not occur again if the operation is retried. Retry the operation.
API Function Descriptions RscGetOption [RSCOG] RscGetOption [RSCOG] The RscGetOption function retrieves a value from an options structure. The user of this function selects the option by placing the desired option selector in the buffer pointed to by the pvOptionSelector parameter. See Appendix D, API Option Definitions, for a list of options and their meanings.
API Function Descriptions RscIoCheck [RSCCHK] RscIoCheck [RSCCHK] The RscIoCheck function looks for the completion of an outstanding nowaited I/O issued on the session identified by ulSessionHandle and retrieves the reply if the operation is complete. Upon successful completion of the function, the field referenced by puReplySize contains the actual number of characters stored in the buffer referenced by pvReplyBuffer.
API Function Descriptions RscIoCheck [RSCCHK] Return Value The return value is 0 if the function is successful. If the I/O has not completed, the function returns RSC_IO_PENDING [17].
API Function Descriptions RscLoadOptions [RSCOL] RscLoadOptions [RSCOL] RscLoadOptionsEx The RscLoadOptions and RscLoadOptionsEx functions set options in an options structure with the values contained in an options definition file (such as RSC.INI). See Appendix D, API Option Definitions for a list of options and their meanings.
API Function Descriptions RscLoadOptionsEx Return Value The return value is zero if the function is successful; otherwise, the function returns one of these result values: RSC_INI_FILE_NOT_FOUND 5 RSC_INVALID_OPTIONS_HANDLE 10 RSC_PC_HEAP_EXHAUSTED 22 RSC_SECTION_NOT_FOUND 52 HP NonStop Remote Server Call (RSC/MP) Programming Manual—522360-004 10 -20
API Function Descriptions RscNotifySem [RSCSEM] RscNotifySem [RSCSEM] The RscNotifySem function allows the application to request asynchronous notification of RSC/MP I/O operation completion by specifying a semaphore to be signaled when an RSC/MP I/O operation completes. This operation could be either a reply to a nowaited RscWriteRead or receipt of a UMS message.
API Function Descriptions RscNotifySem [RSCSEM] Remarks Before calling RscNotifySem: • • • Create a connection handle by calling the RscConnect function. Create a session handle by calling the RscBeginSession function. Create a semaphore by using facilities provided by the operating system (see your operating system programming environment documentation for information about semaphore creation, use, and management).
API Function Descriptions RscNotifyThread [RSCNOTH] RscNotifyThread [RSCNOTH] The RscNotifyThread function allows the application to request asynchronous notification of RSC/MP I/O operation completion by specifying a Windows message that will be posted to the specified thread queue when an RSC/MP I/O operation completes. This operation could be either a reply to a nowaited RscWriteRead or receipt of a UMS message.
API Function Descriptions RscNotifyThread [RSCNOTH] Remarks This function is supported on the Windows platform only. It is not for use in installations where RSC/MP runs as a service or for application that run under Terminal Services. Before calling RscNotifyThread: • • • • Create a connection handle by calling the RscConnect function. Create a session handle by calling the RscBeginSession function. Identify a thread through which your application will receive notifications.
API Function Descriptions RscNotifyThread [RSCNOTH] If your application uses multiple concurrent RSC/MP sessions, then you can exploit this behavior and use a single thread to receive nowaited I/O completion notifications for many sessions, supplying the ulConnectionHandle and ulSessionHandle from each notification message in your corresponding call to RscIoCheck. The same holds true for UMS notifications. Note.
API Function Descriptions RscNotifyWin [RSCNOT] RscNotifyWin [RSCNOT] The RscNotifyWin function allows the RSC/MP application to request asynchronous notification of RSC/MP I/O operation completion by specifying a Windows message to be posted to the message queue for a window owned by the application when an RSC/MP I/O operation completes. This operation could be either a reply to a nowaited RscWriteRead or receipt of a UMS message.
API Function Descriptions RscNotifyWin [RSCNOT] Return Value The return value is zero if the function is successful; otherwise, the function returns one of these result values: RSC_PC_HEAP_EXHAUSTED 22 RSC_INTERNAL_ERROR 102 RSC_NOT_IMPLEMENTED 103 RSC_RESOURCE_FAILURE 104 RSC_PARAMETER_ERROR 105 Remarks This function is supported on Windows platforms only. It is not for use in installations where RSC/MP runs as a service or for applications that run under Terminal Services.
API Function Descriptions RscNotifyWin [RSCNOT] If your application uses multiple concurrent RSC/MP sessions, then you must plan window notifications carefully. Because a window notification message does not identify the connection or session handle against which an I/O operation completes, your application should use a unique window handle or unique message number for each session that enables I/O notifications. The same guideline applies for UMS notifications.
API Function Descriptions RscRegisterThread [RSCRTHD] RscRegisterThread [RSCRTHD] The RscRegisterThread function allows multiple threads to call the RSC/MP API library simultaneously. Call this function before any thread (except the main thread) calls an RSC/MP function. Calling this function allows the RSC/MP library to create the necessary context to keep this thread’s operations within the library discrete from other threads.
API Function Descriptions RscRegisterThread [RSCRTHD] When a shared memory limitation is reached, any additional thread that attempts to use the RscRegisterThread function receives error code RSC_PICCOLO_FAILURE. In this case, consult your system administrator who can make the changes necessary to allow a greater number of shared memory segments.
API Function Descriptions RscSetOption [RSCOS] RscSetOption [RSCOS] The RscSetOption function sets a selected option identified by pcOptionSelector in the options structure identified by ulOptionsHandle to the value in ulOptionValue (if the option type is an integer) or referenced by pcOptionString (if the option type is a string). See Appendix D, API Option Definitions, for a list of options and their meanings.
API Function Descriptions RscSwapLong [RSCSL] RscSwapLong [RSCSL] The RscSwapLong function exchanges the positions of bytes in a long integer. Use this function on workstations that are little-endian to convert to/from big-endian host values. If the workstation operating system is big-endian, this function does not modify the long integer.
API Function Descriptions RscSwapShort [RSCSI] RscSwapShort [RSCSI] The RscSwapShort function exchanges the positions of bytes in a integer. Use this function on workstations that are little-endian to convert to/from big-endian host values. If the workstation operating system is big-endian, this function does not modify the integer. RscSwapShort replaces the RscSwapInt function, which is still supported for older applications.
API Function Descriptions RscTime [RSCTIM] RscTime [RSCTIM] The RscTime function retrieves the current time recorded on the host and places it in the structure referenced by psTimeStruct. The integers in the structure are corrected to match the internal representation of integers for the specific platform; therefore, COBOL programs must declare these fields as COMP-5.
API Function Descriptions RscUmsCheck [RSCUCHK] RscUmsCheck [RSCUCHK] The RscUmsCheck function checks for unsolicited messages received for the session identified by the ulSessionHandle parameter and retrieves the unsolicited message if there is any. Upon successful completion of the function, the field referenced by puBufferSize contains the actual number of characters stored in the buffer referenced by pvBuffer.
API Function Descriptions RscUmsCheck [RSCUCHK] puBufferSize On input, this field points to the size of pvBuffer. On output, this field points to the field that receives the size of the unsolicited message. The size corresponds to the write count of the sender’s Guardian WRITEREAD call. puIoType A pointer to the type of call issued to send the unsolicited message. RSC_UMS_WRITE identifies an unsolicited message issued through a WRITE call.
API Function Descriptions RscUmsReply [RSCUREP] RscUmsReply [RSCUREP] The RscUmsReply function sends a UMS reply to the sender of the unsolicited message issued through a WRITEREAD call. Unsolicited messages issued through a WRITEREAD call are identified by the RSC_UMS_WRITEREAD value referenced by the puIoType parameter after a successful RscUmsCheck function call.
API Function Descriptions RscUmsReply [RSCUREP] Return Value The return value is zero if the function is successful; otherwise, the function returns one of these result values: RSC_INVALID_CONNECTION_HANDLE 6 RSC_INVALID_IO_HANDLE 7 RSC_INVALID_MSG_SIZE 8 RSC_INVALID_REPLY_SIZE 14 RSC_INVALID_SESSION_HANDLE 15 RSC_PC_HEAP_EXHAUSTED 22 RSC_UNKNOWN_IO_HANDLE 29 HP NonStop Remote Server Call (RSC/MP) Programming Manual—522360-004 10 -38
API Function Descriptions RscUnregisterThread [RSCUTHD] RscUnregisterThread [RSCUTHD] The RscUnregisterThread function signals to the RSC/MP API library that a thread no longer needs RSC/MP services. Call this function when a thread has finished using the RSC/MP library and prior to exiting the thread. Calling this function allows the RSC/MP library to clean up any information associated with this thread.
API Function Descriptions RscWrite [RSCW] RscWrite [RSCW] The RscWrite function issues a WRITE I/O request to a server process on the NonStop host. This function is intended specifically for interprocess sessions to a Guardian process that does not issue replies; it is unsupported for the IDS session type. The request is issued on the session identified by ulSessionHandle and can be issued as a waited or nowaited I/O request.
API Function Descriptions RscWrite [RSCW] pcServerName A pointer to a NULL-terminated string or blank-padded string containing the name of the receiving server to which the WRITE procedure should be issued. This parameter should point to a character string no longer than the constant RSC_FILENAME_SIZE (including the terminator) in the RSC.H header file. The name can be a stand-alone process name (for example, $TDD) or a Pathway server class (for example, TDDSVR).
API Function Descriptions RscWrite [RSCW] Return Value The return value is zero if the function is successful; otherwise, the function returns one of these result values: RSC_DUPLICATE_IO_HANDLE (nowaited only) 4 RSC_INI_FILE_NOT_FOUND 5 RSC_INVALID_CONNECTION_HANDLE 6 RSC_INVALID_IO_HANDLE (nowaited only) 7 RSC_INVALID_MSG_SIZE 8 RSC_INVALID_OPERATION 9 RSC_INVALID_OPTIONS_HANDLE 10 RSC_INVALID_REQUEST_SIZE 13 RSC_INVALID_SESSION_HANDLE 15 RSC_PC_HEAP_EXHAUSTED 22 RSC_INVALID_SERVER_N
API Function Descriptions RscWriteRead [RSCWR] RscWriteRead [RSCWR] The RscWriteRead function issues a WRITEREAD I/O request to a server process on the NonStop host. The request is issued on the session identified by ulSessionHandle and can be issued as a waited or nowaited I/O request. Use the supplied nIoHandle to complete the I/O request using the RscIoCheck function. The data referenced by pvWriteBuffer is written to the receiving server indicated by pcServerName.
API Function Descriptions RscWriteRead [RSCWR] pcServerName A pointer to a NULL-terminated string or blank-padded string containing the name of the server to which the WRITEREAD I/O request should be issued. This parameter should point to a character string no longer than the constant RSC_FILENAME_SIZE (including the terminator) in the RSC.H header file. The name can be a stand-alone process name (for example, $TDD) or a Pathway server class (for example, TDDSVR).
API Function Descriptions RscWriteRead [RSCWR] Return Value The return value is zero if the function is successful; otherwise, the function returns one of these result values: RSC_DUPLICATE_IO_HANDLE (nowaited only) 4 RSC_INI_FILE_NOT_FOUND 5 RSC_INVALID_CONNECTION_HANDLE 6 RSC_INVALID_IO_HANDLE (nowaited only) 7 RSC_INVALID_MSG_SIZE 8 RSC_INVALID_OPTIONS_HANDLE 10 RSC_INVALID_REPLY_PARAMETERS 12 RSC_INVALID_REQUEST_SIZE 13 RSC_INVALID_REPLY_SIZE 14 RSC_INVALID_SESSION_HANDLE 15 RSC_PC
API Function Descriptions RscWriteRead [RSCWR] HP NonStop Remote Server Call (RSC/MP) Programming Manual—522360-004 10 -46
A Migration to RSC/MP 7.2 RSC/MP 7.2 is designed to provide a high degree of compatibility with applications that were developed using earlier versions of RSC, RSC over Piccolo, or RSC/MP. Many of these older applications can run without change on RSC/MP 7.2. However, applications that use certain RSC/MP functions and features might need to be adjusted to work with the current version. This appendix describes changes to the RSC product series that affect migration of existing applications to RSC/MP 7.2.
Migration to RSC/MP 7.2 Deprecated RSC API Functions Applications that use the following will require changes when rebuilding: • RSCNT.DLL / RSCNT.LIB (Windows only) The RSCNT.DLL run-time library offers the RSC API for Windows in the CDECL calling convention. Applications linked with the RSCNT.LIB import library prior to RSC/MP V6.0 will execute with the RSCNT.DLL shipped with this version. Note that compatibility issues due to discontinued functions or options can occur. The RSCNT.
Migration to RSC/MP 7.2 Discontinued RSC API Function Parameter Values Discontinued RSC API Function Parameter Values This function has discontinued parameter values. Value Function Parameter RscBeginSession uSessionType RSC_ST_PATHWAY Discontinued RSC Constants These constants had been supplied in the RSC.H file, but are no longer used. They have been removed from the RSC.H file.
Migration to RSC/MP 7.
Migration to RSC/MP 7.
Migration to RSC/MP 7.
B Language Conversion for RSC/MP Function Calls All the function calls documented in this manual use the C language syntax. This appendix shows how to translate these function calls into other languages. Data Type Equivalents Table B-1 lists the COBOL, Pascal, and Visual Basic equivalents for the C data types. Table B-1. Data Types in Other Languages C COBOL Pascal Visual Basic2 Description CHAR PIC X ( X ) CHAR STRING Character data.
Language Conversion for RSC/MP Function Calls Parameter Syntax Parameter Syntax Table B-2 lists the C and COBOL parameter passing syntax. Table B-2. C and COBOL Parameter Passing Syntax C Parameter Passing Syntax COBOL Parameter Passing Syntax Description *name USING name BY REFERENCE The address of (or pointer to) the variable. VOID *name USING name BY REFERENCE A pointer to a nonspecific data type.
Language Conversion for RSC/MP Function Calls C Function Format C Function Format C function definition: ULONG ulOptionsHandle; ULONG ulConnectionHandle; ULONG ulSessionHandle; SHORT nIoHandle; USHORT uRetcode; USHORT uWriteSize; USHORT *puReadSize; CHAR acServerName [32]; VOID *pvReadBuffer; VOID *pvWriteBuffer; C function syntax: uRetcode = RscWriteRead (ulOptionsHandle ,ulConnectionHandle ,ulSessionHandle ,pcServerName ,nIoHandle ,pvWriteBuffer ,uWriteSize ,pvReadBuffer ,puReadSize ); HP NonStop Remot
Language Conversion for RSC/MP Function Calls COBOL Function Format COBOL Function Format COBOL function definition: WORKING-STORAGE SECTION. 01 OPTION-HANDLE 01 CONNECTION-HANDLE 01 SESSION-HANDLE 01 SERVER-NAME. 01 IO-HANDLE 01 REQ-READ. 02 MESSAGE-HEADER. 03 MSG-NUMBER 03 MSG-TYPE 02 CUSTOMER. 03 CUSTOMER-ID 03 CUSTOMER-NAME 03 CUSTOMER-STREET 03 CUSTOMER-CITY 03 CUSTOMER-ZIP 01 REQ-READ-SIZE PIC PIC PIC PIC PIC 9(8) 9(8) 9(8) X(12) S9(4) COMP-5 VALUE 0 COMP-5. COMP-5.
Language Conversion for RSC/MP Function Calls Pascal Function Format Pascal Function Format Pascal function definition: TYPE Cif_ReqReply = Record Msg_Number:integer; Msg_Type:integer; Customer_Id:packed array [1..18] of char; Customer_Name:packed array [1..20] of char; Customer_Street:packed array [1..20] of char; Customer_Country:packed array [1..16] of char; Customer_Zip:packed array [1..
Language Conversion for RSC/MP Function Calls Visual Basic Function Format Visual Basic Function Format Visual Basic function definition: Global ulConnectionHandle& Global ulSessionHandle& Global ulOptionsHandle& Global acRscErrorString As String * 256 Global acServername As String * 32 Global nIoHandle% Global uWriteSize% Global puReadSize% Global Const SZ_CUSTID% = 18 Global Const SZ_CUSTOMER% = 20 Global Const SZ_ADDRESS% = 30 Global Const SZ_CITY% = 20 Global Const SZ_STATE% = 16 Global Const SZ_ZIP%
Language Conversion for RSC/MP Function Calls Visual Basic Function Format Visual Basic function syntax: Declare Function RscWriteRead% Lib "RSCW32.
Language Conversion for RSC/MP Function Calls Visual Basic Function Format HP NonStop Remote Server Call (RSC/MP) Programming Manual—522360-004 B- 8
C RSC/MP Constants Table C-1 lists the RSC/MP constants and their values. You can use either the constant name or the actual value in your code; however, the constant name is more descriptive to someone not familiar with your code and can be more easily changed. The constants are listed in the workstation header file (RSC.H). If you are using constants in your program, include the RSC.H header file at the top of your code. Users of other languages must convert these constants.
RSC/MP Constants Table C-1. RSC/MP Constants, Values, and Usage (page 2 of 2) Constant Name Value Usage RSC_LARGE_INTERPROCESS_MAX_ MSGSIZE 56000 Maximum message size used in RscWrite and RscWriteRead function calls when communicating with a named server, where both the TDP and the server are running on a NonStop platform using a version of Guardian of at least Rev D48. RSC_IO_CHECK_ALL -2 Value of IoHandle parameter for RscIoCheck API call.
RSC/MP Constants Table C-2. RSC/MP Size Constants, Values, and Usage Constant Name Value Usage RSC_INITIAL_SIZE 30 Maximum size for INITIAL_NAME option used for IDS sessions. RSC_PASSWORD_SIZE 20 Maximum size of the PASSWORD option used in the ACS header. RSC_TERMNAME_SIZE 10 Maximum size of TERM_NAME option in UMS header. RSC_USERID_SIZE 20 Maximum size of the USER_ID option in the ACS header.
RSC/MP Constants HP NonStop Remote Server Call (RSC/MP) Programming Manual—522360-004 C- 4
D API Option Definitions Table D-1 lists and defines each of the RSC/MP options that are used with API function calls. See Section 3, API Functions and Options, for a list of API functions and how to use these options. Table D-2, Table D-3, and Table D-4 list the options you can use with these functions and their corresponding data types: • • • RscBeginSession RscConnect RscWrite and RscWriteRead Options Listed Alphabetically Table D-1 lists the API options in alphabetic order. Table D-1.
API Option Definitions Options Listed Alphabetically Table D-1. Option Definitions (page 2 of 5) Option Definition HOST_PROCESS_NAME The name of the TDP process associated with a connection. The application must issue the RscGetOption call on the options structure used in a successful RscConnect call. The process name is returned as a NULL-terminated string in this format: \system .$process HOST_TERM_NAME The name of the TERM object associated with a connection.
API Option Definitions Options Listed Alphabetically Table D-1. Option Definitions (page 3 of 5) Option Definition PATHMON_NAME For Interprocess sessions, the default PATHMON to use for PATHSEND access on this workstation. When this value is not supplied, the default value $RSCP is used. For IDS sessions, the default PATHMON to use on this workstation. When used, the value overrides the IDSPATHMON attribute value for the TERM object.
API Option Definitions Options Listed Alphabetically Table D-1. Option Definitions (page 4 of 5) Option Definition SUCCESS_HI Determines the high value of a successful transaction in a reply. If the value of the first word in a reply message from a server is greater than the SUCCESS_HI value, the transaction state is not closed automatically. For example, if this value is specified as 5 and the reply from the host contains a 6 in the first word of the reply, the transaction is not committed.
API Option Definitions Options Listed Alphabetically Table D-1. Option Definitions (page 5 of 5) Option Definition TERM_NAME A name that uniquely identifies a terminal. For static terminals, the value of TERM_NAME must match the name of the TERM object. For dynamic terminals, this name is optional. TERM_TEMPLATE Identifies the dynamic TERM object in the TDP. The name supplied for this option must be the name of the TERM object in the TDP.
API Option Definitions Options Listed by Data Type Options Listed by Data Type Table D-2, Table D-3, and Table D-4 list the options, data types, acceptable values, and corresponding notes for the following functions: • • • RscBeginSession RscConnect RscWrite and RscWriteRead Options of the CHAR data type are set through the uOptionValue parameter. Options of the SHORT or USHORT data types are set through the pcOptionValue parameter. You can set options before making calls to the corresponding function.
API Option Definitions RscConnect Function Options Table D-2. Options for the RscBeginSession Function (page 2 of 2) Acceptable Values Option Selector Type Notes PASSWORD CHAR * 1 to 18 characters Used if ACS is implemented. PATHMON_NAME CHAR * 1 to 30 characters Used with RSC_ST_IDS and RSC_ST_INTERPROCESS sessions. SESSION_ALIAS CHAR * 1 to 30 characters Used with unsolicited messages. TCLPROG_NAME CHAR * 1 to 36 characters Used with RSC_ST_IDS sessions.
API Option Definitions RscConnect Function Options Table D-3. Options for the RscConnect Function (page 2 of 2) PICCOLO_ KEEPALIVE NUMERIC 0 to 3600 Number of seconds between attempts by Piccolo to verify that a connection remains active. The value can be from 0 (disabled) to 3600 seconds (1 hour). Low values for PICCOLO_KEEPALIVE can burden networks with verification messages. The default is 3600 (1 hour).
API Option Definitions RscWrite and RscWriteRead Function Options RscWrite and RscWriteRead Function Options This table shows the options for RscWrite and RscWriteRead functions. Table D-4. Options for the RscWrite and RscWriteRead Functions (page 1 of 2) Acceptable Values Option Selector Type Notes ACS_BINARY_AREA CHAR * 1 to 128 byte binary string Used to exchange binary data with the ACS server when ACS is implemented and RECVWRITEREADS is set to YES.
API Option Definitions RscWrite and RscWriteRead Function Options Table D-4. Options for the RscWrite and RscWriteRead Functions (page 2 of 2) Acceptable Values Option Selector Type Notes WRITEREAD_ PATHMON CHAR * 1 to 6 characters with leading “$” See description in Table D-1. WRITEREAD_SYSTEM CHAR * 1 to 8 characters with leading “\” See description in Table D-1.
E Function Cross-Reference This table provides a convenient cross-reference between the C language API function names and the corresponding names used in the other languages that RSC/MP supports. Using different names is necessary because many languages require function names to be less than eight characters.
Function Cross-Reference HP NonStop Remote Server Call (RSC/MP) Programming Manual—522360-004 E- 2
F Sample Code Overview This appendix provides a list of source code samples that are included with RSC/MP and describes the samples that are not described elsewhere in this manual. Sample Demonstrates...
Sample Code Overview C w/GUI Sample operation, and others. RSCTEST displays a few statistics about performance, but these are informational only and not suitable for benchmarking purposes. RSCTEST is delivered as source code and the corresponding pre-built executable. It is included with every RSC/MP client. On Windows clients, the source code is installed to the source directory and the executable is installed to the bin directory.
Sample Code Overview IDS Router Sample The echo server is called TDDSVR. It simply echoes whatever data it receives. Ordinarily, TDDSVR keeps a reference count of its openers in order to exit correctly when running under PATHWAY control. This behavior can be suspended in order to run TDDSVR as a standalone server by including any token on the invoking command line.
Sample Code Overview Visual Basic Sample The sample application and sample servlet are loosely based on RSCTEST and both allow series of RscWriteRead operations to be run against the echo server. The Java sample code is delivered as source code and pre-built executable and class files. It is included with all Windows clients and with certain UNIX clients as indicated in the “Files Included” table in the UNIX installation section of the Remote Server Call (RSC/MP) Installation and Configuration Guide.
Sample Code Overview Visual Basic .NET Sample identifying areas of change when migrating an existing RSC/MP VB6 application to VB.NET. The RSC/MP VB.NET sample application is called RscTestVBnet. It is functionally equivalent to the VB6 sample RscTestVB. RscTestVBnet is delivered as source code only; executable files are not delivered. RscTestVBnet is included with Windows clients only. To examine or build RscTestVBnet, use the VB.NET development environment. Note that the VB.
Sample Code Overview Visual Basic .
Content Feedback First Name: __________________ Phone: _____________________ Company: ___________________ Last Name: _________________ e-mail address: ______________ (All contact information fields are required.) If you’re reporting an error or omission, is your issue: Minor: I can continue to work, but eventual resolution is requested. Major: I can continue to work, but prompt resolution is requested. Critical: I cannot continue to work without immediate response.
Index A Access Control Server (ACS) authorized list header 9-9, 9-10 mechanism 9-2 message header 9-8 programming in COBOL 9-8 sample for NonStop 9-5 testing 9-8 workstation configuration 9-4 ACS See Access Control Server ACS_BINARY_AREA option 9-4, D-1 ACS_MESSAGE_AREA option 9-4, D-1 Application options clearing 3-4, 10-6 creating 3-3, 10-8 customizing 3-2 definitions of D-1 destroying 3-4, 10-9 listed alphabetically D-1 listed by data type D-6 organizing into sections 3-4 reading from definition file 3-3
Index E conversion 5-6, B-1 Default options 3-4 Definition files 3-3 DSM event collector 7-1 E Error file (RSC.
Index N N NetBIOS protocol 7-7 Network failure 7-7 opening logical connection 5-5 Nowaited I/O 4-5 issuing requests 10-3 processing call 3-8 NULL termination 5-6, B-2 O OPEN_COUNT option D-2 Operating systems 1-2 OptionsHandle parameter 3-2 P Parameters, input and output 10-1 Pascal programming language functions B-1, B-5 PASSWORD option 9-3, 9-5, D-2 PATHMON_NAME option D-3 PATHTERM_NAME option D-3 Persistent applications 6-15 Persistent mode 6-15, 7-7 PICCOLO_KEEPALIVE option D-3 PIPE object name D-1,
Index S RscWrite function customizing options 3-2 issuing I/O requests 10-40 list of options D-9 processing I/O 3-6 RscWriteRead function customizing options 3-2 list of options D-9 processing I/O 3-6 RSC.ERR file, return values 7-4 RSC.H file See also Header file 2-3 RSC.
Index U TMF_OPTION values 6-8 Transaction Delivery Process (TDP) configuration file (TDPCFG) 1-7 configuring 1-4, 1-5 connecting to 3-6 effects of a failure on 6-16 issuing request to 10-3 list of objects 1-5 multiple processes 1-5 persistent applications 6-15 recovering from failure 6-16, 7-7 using a backup process with 6-17 using in persistent mode 7-7 Transaction Management Facility (TMF) beginning and ending transactions 3-6 code example 6-12 controlling transactions 6-6 design considerations 5-3 Tran
Index W HP NonStop Remote Server Call (RSC/MP) Programming Manual—522360-004 Index-6
