NonStop TS/MP Pathsend and Server Programming Manual Abstract This manual describes how to write two types of programs as part of a Pathway application: requester programs that use the Pathsend application program interface (API) and server programs that service requests from all types of Pathway requesters. Product Version NonStop TS/MP D44 Supported Releases This manual supports D44.00 and all subsequent D4x releases and G03.
Document History Part Number Product Version Published 110074 NonStop TS/MP D31 July 1995 123813 NonStop TS/MP D31 December 1995 132500 NonStop TS/MP D44 July 1997 New editions incorporate any updates issued since the previous edition. A plus sign (+) after a release ID indicates that this manual describes function added to the base release, either by an interim product modification (IPM) or by a new product version on a .99 site update tape (SUT).
New and Changed Information This is the third edition of the NonStop TS/MP Pathsend and Server Programming Manual. Writers of Pathsend requesters and all Pathway servers should read this manual. Writers of SCREEN COBOL requesters should read the Pathway/TS TCP and Terminal Programming Guide. This third edition includes changes to reflect product changes, and also additional enhancements.
New and Changed Information Enhancements to the Manual Enhancements to the Manual The following enhancements have been made to the material in this manual: • • • • A new subsection, Consideration for Servers Used With Remote Server Call (RSC) Clients on page 4-4, has been added to mention the optional server reply code for servers used with Remote Server Call (RSC) clients. For details, refer to the Remote Server Call (RSC) Programming Manual.
Contents New and Changed Information iii About This Manual xi Notation Conventions xvii 1.
2. Designing Your Application (continued) Contents 2. Designing Your Application (continued) Designing Requester Programs 2-11 SCREEN COBOL Requesters 2-12 IDS Requesters 2-12 Pathsend Requesters 2-13 Clients Using RSC and POET 2-15 Requesters Using GDSX 2-16 Dividing Function Between Requester and Server 2-19 Designing Server Programs 2-19 Design Considerations 2-20 Server Program Structure 2-25 Designing Applications for Batch Processing 2-27 3.
4. Writing Pathway Servers (continued) Contents 4.
5. Pathsend Procedure Call Reference (continued) Contents 5.
Examples Contents Examples Example 2-1. Example 2-2. Example B-1. Example B-2. Sample Pathsend Requester Program Structure 2-15 COBOL85 Server Program Example 2-25 Context-Free Pathsend Requester Program B-2 Context-Free Server Program B-53 Figures Figure i. Figure 1-1. Figure 1-2. Figure 2-1. Figure 2-2. Figure 2-3. Figure 2-4. Figure 2-5.
Contents NonStop TS/MP Pathsend and Server Programming Manual– 132500 x
About This Manual This section describes the purpose and the contents of this manual and of other manuals closely related to this manual. This manual is one of a set of manuals that describe the NonStop Transaction Services/MP (NonStop TS/MP) and Pathway/Transaction Services (Pathway/TS) products. The contents of these products are as follows: • • NonStop TS/MP: This product consists of the PATHMON process, the LINKMON process, the PATHCOM process and interface, and the Pathsend procedure calls.
What Is in This Manual About This Manual What Is in This Manual This manual contains application design and programming information for writers of Pathsend requesters and Pathway servers. This information includes syntax, usage, and error-handling information for the Pathsend procedure calls.
Related Documentation About This Manual Figure i.
About This Manual • Related Documentation Operator Messages Manual. This manual describes system messages. For each message the manual provides an explanation of the cause, a discussion of the effect on the system, and suggestions for corrective action. The “PATHWAY Messages” section describes the operator messages generated by the PATHMON environment.
Other Manuals in the Manual Set About This Manual Other Manuals in the Manual Set In addition to the NonStop TS/MP and Pathway/TS manuals shown in Figure i, the manual set for these products includes the following manuals: • Pathway/TS System Management Manual. This manual describes how to start, configure, and manage Pathway/TS objects (TCPs, terminal objects, SCREEN COBOL programs, and tell messages) in a PATHMON environment.
About This Manual Your Comments Invited NonStop TS/MP Pathsend and Server Programming Manual– 132500 xvi
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: file-name [ ] Brackets.
General Syntax Notation Notation Conventions 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 ( file-name ) ; LISTOPENS SU $process-name.
Notation for Messages Notation Conventions !o:i. In procedure calls, the !o:i notation follows an output buffer parameter that has a corresponding input parameter specifying the maximum length of the output buffer in bytes. For example: error := FILE_GETINFO_ ( filenum , [ filename:maxlen ] ) ; !i !o:i Notation for Messages The following list summarizes the notation conventions for the presentation of displayed messages in this manual. Nonitalic text.
Notation Conventions Change Bar Notation % 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: %005400 P=%p-register E=%e-register Change Bar Notation Change bars are used to indicate substantive differences between this edition of the manual and the preceding edition.
1 Introduction to Pathway Application Programming This section introduces Pathway transaction processing applications, which you write and run with the assistance of the NonStop Transaction Services/MP (NonStop TS/MP) and Pathway/Transaction Services (Pathway/TS) software.
Introduction to Pathway Application Programming Which Sections Do You Need? to read all sections of this manual. Table 1-1 is a descriptive map listing which sections are relevant to particular programming tasks. Table 1-1.
Introduction to Pathway Application Programming Advantages of the Pathway Environment Advantages of the Pathway Environment NonStop TS/MP provides ease of development, manageability, and the fundamental strengths and benefits of Tandem NonStop systems. The strengths and benefits of Tandem systems include data integrity, fault tolerance, high performance and low cost, system security, scalability, and distributed processing.
Introduction to Pathway Application Programming • • Manageability The Pathway environment allows you to isolate and test your requester and server programs before adding them to a running application. This capability is important because coding errors are difficult, time-consuming, and expensive to find after an application is put into production. OLTP products that are compatible with the Pathway environment are available from third-party vendors through the Tandem Alliance program.
Introduction to Pathway Application Programming Fault Tolerance commonly known as a transaction log. You can use the audit trail to rebuild the database in the event of a hardware or software failure. The design of Pathway servers supports the integrity of individual transactions and therefore transaction processing protection as a whole.
Introduction to Pathway Application Programming Other Tandem Fundamentals Besides process pairs and server classes, fault tolerance in a Pathway application is ensured by the PATHMON process, the TCP, and the TMF subsystem. Using information stored in the PATHMON configuration file, the PATHMON process automatically restarts processes at their initialization level after a failure, allowing these processes to resume work immediately.
Introduction to Pathway Application Programming Pathway Applications Scalability Your organization must be able to expand its transaction processing system as its operations evolve and its technical requirements change.
Introduction to Pathway Application Programming Servers and Server Classes Servers and Server Classes You can write Pathway server programs in C, C++, COBOL85, Pascal, the Transaction Application Language (TAL), the Portable Transaction Application Language (pTAL), FORTRAN, or Extended BASIC in the Guardian environment.
Introduction to Pathway Application Programming • • Requesters By temporarily freezing and stopping the server class and changing configuration parameters, the system manager or operator can adjust the number of servers that are active at any one time to suit response-time requirements.
Introduction to Pathway Application Programming The Pathsend Environment SCREEN COBOL Requesters SCREEN COBOL requesters, which are compiled by the SCREEN COBOL compiler and then interpreted and executed by the terminal control process (TCP), provide ease of programming if you need to handle large numbers of terminals or intelligent devices or if you need screen-presentation services. The TCP and the SCREEN COBOL language produce a high-quality, manageable application.
LINKMON Processes Introduction to Pathway Application Programming LINKMON Processes LINKMON processes, together with the PATHMON process, perform link-management functions for Pathsend processes. (A link is a connection to a server process.) A LINKMON process executes in each processor, or CPU, of a system. As a link manager, a LINKMON process is responsible for managing links on behalf of all the Pathsend processes executing in its processor.
Introduction to Pathway Application Programming Client/Server Capabilities Client/Server Capabilities The Remote Server Call (RSC) product and the Pathway Open Environment Toolkit (POET) bring client/server capabilities to the Pathway environment by allowing you to move requester functions to a workstation.
Introduction to Pathway Application Programming Other Transaction Processing Environments Other Transaction Processing Environments The NonStop TS/MP product serves as the foundation for open transaction processing on Tandem NonStop systems. In addition to the Pathway environment, NonStop TS/MP supports the NonStop TUXEDO transaction processing system.
Introduction to Pathway Application Programming Development Tools and Utilities Development Tools and Utilities When you are writing requester and server programs for your Pathway application, a variety of program development tools and utilities are available to you. These tools and utilities allow you to shorten the amount of time it takes to code, debug, and test your programs.
Introduction to Pathway Application Programming • • • • Client/Server Development Tools Automatically generating TMF statements in your requester programs when you indicate that you want your programs to have TMF protection Providing a central location for most application information Creating error-handling code for the most commonly encountered errors Letting you simulate application screens and navigate from one application screen to another before you write a single line of code Applications develop
Transaction Processing Scenario Introduction to Pathway Application Programming Figure 1-2.
Introduction to Pathway Application Programming Transaction Processing Scenario In this scenario, clerks at an order entry office enter their transactions into terminals attached to an IBM system. Processing of the transactions, however, requires access to a database that is linked to a Tandem NonStop system. 1. The clerks enter transactions into their terminals and initiate processing by pressing function keys. Any preliminary checking or editing is performed by the application on the IBM system. 2.
Introduction to Pathway Application Programming Transaction Processing Scenario NonStop TS/MP Pathsend and Server Programming Manual– 132500 1- 18
2 Designing Your Application To develop a functioning Pathway application, you must identify the individual transactions in your business operations, design and build the application database, and design and code requester programs and server programs. This section describes the design of transactions and databases for Pathway applications and the design of requester and server programs.
Designing Your Application Analyzing Data Flow Analyzing Data Flow Analyzing the flow of data involves identifying what information is required for a business task, determining the order in which that information is required, and specifying how the information is to be handled. To automate the order-processing tasks of the previously described distributorship, for example, you could analyze the flow of information as follows: 1.
Analyzing Data Flow Designing Your Application Figure 2-1. Data Flow for a Business Task 1. Accept: 2. \REG — Check customer ID. — Get customer's name and address. — Get order ID. — Customer ID — Requested shipping date — Shipping instructions 3. Accept: 4. \WHS —Check quantity available for delivery of each ordered item. — List of ordered items — Quantity of each item 5. Accept: Inventory Data 6. — Calculate order cost. — Get customer balance and credit limit.
Designing Your Application Identifying Transaction Components Identifying Transaction Components After you have identified the Enter Sales transaction for the order-processing application, you list the functions performed by the transaction and group them either into data collection and validation operations or into database update operations.
Identifying Transaction Components Designing Your Application Figure 2-2.
Designing Your Application Protecting Transactions Protecting Transactions After listing and grouping the components of the Enter Sales transaction, you protect the integrity of each transaction, and ultimately the consistency of the database, with the TMF subsystem. The following pages outline how to integrate the TMF subsystem with your business transactions.
Protecting Transactions Designing Your Application Figure 2-3. Pathway Application Programming for the TMF Subsystem COBOL85, C, C++, Pascal, or TAL BEGINTRANSACTION • TRANSID • • Request database services • • Perform checkpointing as needed • • Abort and restart transaction if necessary • • ABORTTRANSACTION or ENDTRANSACTION Requester COBOL85, C, C++, Pascal, TAL, ...
Designing Your Application Protecting Transactions To illustrate this assertion, consider a situation where a transaction fails after it changes the customer’s balance, records the order information, and records the order invoice, but before it records the shipping information. In this scenario, the customer is going to be billed for an order never received.
Designing Your Application Designing the Database Designing the Database The next step in developing a Pathway application is to design the database that will be accessed and updated by the application. Designing the database, which is a highly specialized activity typically performed by experienced database administrators, involves: • Precisely identifying the meaning and use of the data as it exists in your business and specifying the database files and records that will store this data.
Physical Design Designing Your Application Physical Design You undertake the physical design of your database by selecting the appropriate file types and record keys for each of the files in the database. Whether you are using the NonStop SQL/MP software or the Enscribe software as your database management system (DBMS), these file types can be classified as key-sequenced, relative, entrysequenced, or unstructured: Key-sequenced Each record in the file has a primary key and up to 255 alternate keys.
Remote Duplicate Database Facility (RDF) Designing Your Application Remote Duplicate Database Facility (RDF) If disaster recovery of your database is important, the Remote Duplicate Database Facility (RDF) is available to maintain a copy of the database on a remote system. The RDF product monitors database updates audited by the TMF subsystem and applies those updates to the remote copy of the database.
Designing Your Application SCREEN COBOL Requesters SCREEN COBOL Requesters Screen programs for Pathway terminals perform a variety of front-end functions for your Pathway application and are typically written as single-threaded programs in the SCREEN COBOL language. This language offers a simple programming environment and screen-management system to drive Tandem terminals and IBM 3270 terminals.
Designing Your Application • • • Pathsend Requesters Fault tolerance through process pairs Multithreading and multitasking Expanded I/O editing support for data streams from intelligent devices For information about designing and coding IDS requesters, refer to the Pathway/TS TCP and Terminal Programming Guide. Pathsend Requesters As an alternative to writing SCREEN COBOL requesters, you can write Pathsend requesters in C, C++, COBOL85, Pascal, TAL, or pTAL.
Designing Your Application Pathsend Requesters In addition, Pathsend procedure calls that send messages to server classes must be protected by the TMF subsystem to ensure data integrity in your Pathway application. The Pathsend procedures and the LINKMON process do not support the checkpointing of Guardian interprocess message synchronization IDs. This lack of checkpointing support is an important consideration when writing fault-tolerant requester programs that do not use the TMF subsystem.
Clients Using RSC and POET Designing Your Application Example 2-1. Sample Pathsend Requester Program Structure Declare program variables. TMFError := BEGINTRANSACTION( TransactionTag ): Begins TMF transaction. Allocate buffer for request and reply messages. PathmonName ‘:=‘ PathmonNameBytes ServerClass ‘:=‘ ServerClassBytes Timeout := -1D; Flags := 1; Set SERVERCLASS_SEND_ parameters. [“$PM”] :=3; [“ASERVER”] =7; Specifies no timeout. Specifies nowait send.
Designing Your Application Requesters Using GDSX classes by using either the Pathsend API and the LINKMON process or the terminal control process (TCP) provided in the Pathway/TS product. If the TCP is used, it can route a request message to a Pathway server by using either the intelligent device support (IDS) requester supplied as part of RSC or an IDS requester that you develop yourself. The TDP can also send request messages from a workstation to a Guardian process.
Designing Your Application Requesters Using GDSX character inserted before the procedure name. For example, SERVERCLASS_SEND_ becomes ^SERVERCLASS_SEND_. The GDSX interface supports both context-free and context-sensitive Pathsend procedures.
Requesters Using GDSX Designing Your Application Figure 2-4. GDSX as a Front-End Process Tandem NonStop System PATHMON Server Class GDSX LINKMON Server General Device NonStop TM/MP NonStop SQL/MP Database CDT126 When developing a front-end process using GDSX, consider the following points: • • • • A GDSX front-end process is a good choice when a specified data communications protocol is not supported by the Pathway TCP but is supported by GDSX.
Designing Your Application Dividing Function Between Requester and Server Dividing Function Between Requester and Server In designing a Pathway application, you must decide how to divide function between requester and server. In making this decision, you should consider the type of requester or client you are writing (SCREEN COBOL, Pathsend, RSC, or GDSX), and you should also consider performance, maintainability, and other factors.
Designing Your Application Design Considerations After you code and compile your server program, the server object code and library code are shared among all processes of the same server class. Design Considerations Before structuring and coding a server program, you should consider some design issues that can affect server performance and efficiency. First, you must decide whether to program single-threaded or multithreaded servers.
Designing Your Application Design Considerations program or in the database. When you program a server to be context-free, you code the server to be independent of its previous request. In essence, every request must be treated as if it were the first request received by the server. SCREEN COBOL and the TCP support only context-free servers. However, if you use Pathsend requesters, you can use either context-free or context-sensitive servers. In most cases, it is preferable to use context-free servers.
Designing Your Application • Design Considerations Update or read-only server: A single server exclusively handles either update transactions or inquiry transactions. One approach to packaging server functions is to first group server functions based on management considerations (for example, all servers within a server class must freeze and stop as a unit) and security considerations (for example, the server class must execute under one user ID).
Designing Your Application • • Design Considerations Single-threaded servers that send to other server classes can cause low server utilization in the same way that any single-threaded process that calls another process can: the server process sending the request is idle until it receives a reply from the server to which it sent the request.
Design Considerations Designing Your Application increases its potential queue by one request. A single-threaded server queue can result in poorer performance for the application system. Audited and Nonaudited Servers If your Pathway application uses a database that is a combination of TMF audited files and nonaudited files, write separate servers to process the two types of files.
Server Program Structure Designing Your Application Server Program Structure Example 2-2 illustrates the structure of a single-function server program written in COBOL85. The program in the following example handles data entry for the orderprocessing application introduced at the beginning of this section. Note. The program in Example 2-2 illustrates program structure only; it is not a complete program. For an example of a complete, running Pathway server program, refer to Appendix B, Examples.
Server Program Structure Designing Your Application Example 2-2. COBOL85 Server Program Example (page 2 of 3) FD MSG-OUT RECORD CONTAINS 36 TO 204 CHARACTERS LABEL RECORDS ARE OMITTED 01 ORDER-REPLY. . . . 01 ERROR-STATUS-REPLY. . . . FD LAST-ID RECORD CONTAINS 12 CHARACTERS LABEL RECORDS ARE OMITTED 01 LAST-ID-RECORD. 02 LAST-ID . . . PIC 9(12). WORKING STORAGE SECTION. Declares data structures of variables used by server. PROCEDURE DIVISION. DECLARATIVES.
Designing Your Application Designing Applications for Batch Processing Example 2-2. COBOL85 Server Program Example (page 3 of 3) PROCESS-REQUEST SECTION. PERFORM GET-MSG IN RCV-MGR. IF NOT last-requester-close PERFORM DO-REQUEST. Contains logic that reads requests in $RECEIVE, services requests, and replies to requests. DO-REQUEST.
Designing Your Application Designing Applications for Batch Processing NonStop TS/MP Pathsend and Server Programming Manual– 132500 2- 28
3 Writing Pathsend Requesters This section explains how to write programs that use Pathsend procedure calls to make requests to Pathway servers. These programs can be either one of the following: • • Standard requesters—programs that initiate application requests Nested servers—servers that act as requesters by making requests to servers in other server classes Nested servers are described further in Section 4, Writing Pathway Servers.
Writing Pathsend Requesters Interprocess Communication in the Pathsend Environment Interprocess Communication in the Pathsend Environment Communication between requesters and servers in the Pathsend environment differs from communication between Guardian requesters and servers. Rather than directly opening a particular server process, the requester opens the LINKMON process, which in turn opens a server process selected by the PATHMON process.
Writing Pathsend Requesters Basic Pathsend Programming Basic Pathsend Programming The simplest type of Pathsend program is a context-free program. This subsection provides the information you need to write a context-free Pathsend program. It also provides information common to both context-free and context-sensitive programming. The next subsection provides information about the additional tasks required of a context-sensitive Pathsend program.
Writing Pathsend Requesters Programming for Failure Recovery requests more smoothly. However, because the TMF subsystem guarantees only the consistency of the database and not fault tolerance for other operations (such as messages sent over data communications lines), your application might need to use process pairs along with TMF level recovery. TMF programming is described in the NonStop TM/MP Application Programmer’s Guide. The Guardian Programmer's Guide discusses process pairs and checkpointing.
Writing Pathsend Requesters Programming for Failure Recovery Pathsend Programming and the TMF Subsystem The Pathsend procedure calls support TMF transactions. Calling a Pathsend procedure to start a server-class send operation propagates the current transaction identifier, if any, to the server process. If the Pathsend procedure call fails, use of the TMF subsystem allows your application to abort the transaction and retry the call.
Writing Pathsend Requesters Security Issues For Pathsend calls not protected by the TMF subsystem, the proper recovery depends on the nature of the request: • Retryable requests that are not protected by the TMF subsystem can be repeated many times without adverse effect. An example of this kind of request is a request to read a bank account balance. Requests to retrieve data from a database are retryable requests. For these requests, on backup takeover, the backup can simply reissue the request.
Writing Pathsend Requesters Avoiding Coded PATHMON Names This level of security is required because the LINKMON process must be able to open the PATHMON process (to make link requests); the LINKMON process must be able to open the server processes (to send user requests); and the PATHMON process must be able to open the server processes (to send startup messages). All of these opens are performed with the PATHMON user ID. Note.
Writing Pathsend Requesters Context-Sensitive Pathsend Programming Context-Sensitive Pathsend Programming If you are writing a context-sensitive Pathsend program, you must follow the guidelines in the previous subsection, Basic Pathsend Programming, and also perform additional programming tasks. This subsection describes these additional tasks and other considerations for context-sensitive programming.
Writing Pathsend Requesters Programming for Failure Recovery Programming for Failure Recovery The SERVERCLASS_DIALOG_BEGIN_ procedure allows two types of TMF protection for dialogs: • • The one-transaction-per-dialog model The any-transaction-per-dialog model You use bit 14 of the flags parameter in the SERVERCLASS_DIALOG_BEGIN_ procedure call to select which model will be used. A value of 0 for bit 14 of flags (the default) selects the one-transaction-per-dialog model.
Writing Pathsend Requesters Cancellation of Server-Class Send Operations abort occurs. In either case, the requester should abort the transaction when it receives an error reply.
Writing Pathsend Requesters Writing Requesters That Interoperate With NonStop TUXEDO Servers Writing Requesters That Interoperate With NonStop TUXEDO Servers Pathsend requesters can call on the services of NonStop TUXEDO servers in either of two ways: • • Directly, by making calls to the NonStop TUXEDO Application Transaction Monitor Interface (ATMI) functions Indirectly, by using the Pathway to TUXEDO (PWY2TUX) translation server To communicate directly with a NonStop TUXEDO server by calling the ATMI
Writing Pathsend Requesters Writing Requesters That Interoperate With NonStop TUXEDO Servers NonStop TS/MP Pathsend and Server Programming Manual– 132500 3- 12
4 Writing Pathway Servers This section explains how to write server programs that service requests from Pathway requesters. Such requesters can be Pathsend requesters, SCREEN COBOL requesters, or clients that use the Remote Server Call (RSC) product or the Pathway Open Environment Toolkit (POET) product. Pathsend requesters are described in this manual.
Writing Pathway Servers Guardian Servers and Pathway Servers Guardian Servers and Pathway Servers Like a Guardian server, a Pathway server receives messages by reading the Guardian $RECEIVE file. However, unlike a Guardian server, it does not receive its messages directly from a requester program, but instead receives them from an intermediate process: either a LINKMON process or a terminal control process (TCP).
Writing Pathway Servers LINKMON Process Failures When a requester fails, all transactions initiated by that requester but not yet completed at the time of the failure are automatically aborted. LINKMON Process Failures If a halt occurs in the processor where a LINKMON process is running, all the Pathsend requesters in that processor fail. (See the previous subsection for details about requester failures.) The links that the LINKMON process established with the server processes are relinquished.
Writing Pathway Servers Consideration for Servers Used With Remote Server Call (RSC) Clients For more information about the checkpointing strategy used by the TCP, refer to the Pathway/TS TCP and Terminal Programming Guide. Consideration for Servers Used With Remote Server Call (RSC) Clients Some Remote Server Call (RSC) clients are written to check for an integer reply-code value in the first two bytes of the server’s reply message.
Writing Pathway Servers Considerations for Servers That Use the TMF Subsystem Considerations for Servers That Use the TMF Subsystem If you are writing a Pathway server that uses the TMF subsystem for transaction management, a number of additional programming considerations apply, related to the following topics: • • • • • Recommended application structure Writing a server to use the TMF subsystem if your application does not follow the recommended structure Using audited and nonaudited files Record lock
Writing Pathway Servers Writing a Server to Use the TMF Subsystem information about use of the Enscribe locking facilities, refer to the Enscribe Programmer’s Guide. Servers do not reply to request messages until all work for the request has been completed. The contents of the reply message indicate the outcome of the request, which is one of the following: • • • All the work for the request was completed successfully. None of the work for the request was completed.
Writing Pathway Servers Using Audited and Nonaudited Files proceed because they are each waiting for the other to release a lock.) One way to cope with deadlock is to use timeout. In addition, your requester program must use the necessary transaction-control procedure calls or statements to begin and end the transaction and to abort or restart the transaction if necessary. Note.
Writing Pathway Servers Locking Records Locking Records If your application uses the TMF subsystem, your servers must follow the TMF locking rules. Locking gives the TMF subsystem the control required to ensure that transactions are presented with a consistent view of the database. With respect to the locking of records, you must consider the following aspects of your application: • • • • Repeatable reads.
Writing Pathway Servers Grouping Transaction Operations Example 1 Some logical transactions do not have to be identified as TMF transactions. For example, a logical transaction locates a single record and displays the record contents. Because this transaction changes nothing in the database, it does not affect consistency and does not have to be a TMF transaction. Example 2 A data-entry transaction with a group of accesses that insert new data into the database should be a TMF transaction.
Writing Pathway Servers Servers as Process Pairs Servers as Process Pairs When you are using the TMF subsystem, you should not write your server processes as fault-tolerant process pairs. The additional programming and functional overhead required to do so is unnecessary. If your servers are already coded as process pairs, however, it is not usually necessary to change them back to ordinary servers.
Writing Pathway Servers Considerations for Debugging Pathway Servers Considerations for Debugging Pathway Servers When you are running a Pathway server in debug mode (that is, with the server class configured with DEBUG ON) or when the server falls into debug mode because of an error, some situations might cause errors to be returned to the requester communicating with that server, and in some cases also might cause errors to be returned to other requesters.
Writing Pathway Servers PATHMON Process Timeouts When Pathsend error 915 or a SEND error with TERMINATION-STATUS 12 occurs with a timeout error during server debugging, use the PATHCOM STATUS PATHMON command to find the server classes that are in the LOCKED state. Identify the server program file for each locked server class, and issue the TACL command STATUS *, PROG object-file-name to list all running processes. Stop these processes by using the TACL STOP command.
Writing Pathway Servers Writing Context-Sensitive Servers Writing Context-Sensitive Servers If you are writing a context-sensitive Pathway server, you must follow the guidelines in Basic Pathway Server Programming earlier in this section and also perform additional programming tasks. This subsection describes these additional tasks and other considerations for programming context-sensitive servers. When you use context-sensitive Pathway servers, the requester and server must be designed to work together.
Writing Pathway Servers Detecting a Newly Established Dialog For the syntax of the FILE_GETRECEIVEINFO_ procedure, refer to the Guardian Procedure Calls Reference Manual. For the syntax of the CRE_Receive_Read_ procedure, refer to the Common Run-Time Environment (CRE) Programmer’s Guide. Note. CRE_Receive_Read_ and the other CRE routines are callable only from TAL, pTAL, FORTRAN, and COBOL85 programs and are used when you are writing mixed-language programs.
Receiving, Servicing, and Replying to Messages in a Dialog Writing Pathway Servers Table 4-1. Meaning of Error Codes Returned by Context-Sensitive Server in Reply Error Returned by Server Meaning 70 (FEContinue) Allow the dialog to continue. 0 (FEOK) End the dialog. After the server replies with this code, the associated TMF transaction (if any) will be allowed to commit, and the server will receive no further sends associated with this dialog. 1 (FEEOF) Abort the dialog.
Writing Pathway Servers Correlating Messages With a Dialog When the one-transaction-per-dialog model is used, the transaction is automatically aborted when the server returns an error value (FEEOF, or any other value besides FEOK or FEContinue) in the reply. When the any-transaction-per-dialog model is used (when bit 14 of the dialog flags is equal to 1), no automatic transaction abort occurs. In either case, the requester should abort the transaction when it receives an error reply.
Writing Pathway Servers Writing Pathway Servers That Interoperate With TUXEDO Requesters either FEOK (0) or FEEOF (1); these values direct the LINKMON process to release the link for re-use. If a processor or network failure occurs, it is possible to have a dialog abort but not receive a Pathsend dialog abort message.
Writing Pathway Servers Writing Pathway Servers That Interoperate With TUXEDO Requesters NonStop TS/MP Pathsend and Server Programming Manual– 132500 4- 18
5 Pathsend Procedure Call Reference Pathsend programs use six procedures that are part of the Guardian procedure library. This section provides the syntax and semantics of these procedure calls, preceded by information about how to call the procedures from each of the languages supported by Pathsend. The descriptions are in alphabetic order by procedure name.
Pathsend Procedure Call Reference Calls From C or C++ COBOL85, Pascal, pTAL, or TAL. The topics that follow explain how to call the Pathsend procedures from each of the supported programming languages. Note. For general information about calling these and other Tandem system procedures from programs written in various programming languages, refer to the information about accessing Guardian procedures in the Guardian Programmer’s Guide. None of the Pathsend procedures set the condition-code register.
Pathsend Procedure Call Reference Calls From COBOL85 For further information, refer to the C/C++ Programmer’s Guide.
Pathsend Procedure Call Reference Calls From Pascal Calls From Pascal To invoke any of the procedures from within a Pascal program, you execute a statement of the following form: error := SERVERCLASS_SEND_ ( pathmon-process-name ,pathmon-process-name-len ,server-class-name ,server-class-name-len ,message-buffer ,request-len ,maximum-reply-len ,actual-reply-len ,timeout ,flags ,scsend-op-num ,tag ) error is a variable of type IO_Error_Number defined earlier in your data declarations.
Pathsend Procedure Call Reference Calls From TAL or pTAL Calls From TAL or pTAL To invoke any of the procedures from within a TAL or pTAL program, you execute a statement of the following form: error := SERVERCLASS_SEND_ ( pathmon-process-name ,pathmon-process-name-len ,server-class-name ,server-class-name-len ,message-buffer ,request-len ,maximum-reply-len ,actual-reply-len ,timeout ,flags ,scsend-op-num ,tag ); error is an integer variable defined earlier in your data declarations.
Pathsend Procedure Call Reference SERVERCLASS_DIALOG_ABORT_ Procedure SERVERCLASS_DIALOG_ABORT_ Procedure The SERVERCLASS_DIALOG_ABORT_ procedure aborts the specified dialog. A call to SERVERCLASS_DIALOG_BEGIN_ to begin a dialog must be matched by a call to SERVERCLASS_DIALOG_ABORT_ or SERVERCLASS_DIALOG_END_ at the end of the dialog.
Pathsend Procedure Call Reference SERVERCLASS_DIALOG_BEGIN_ Procedure SERVERCLASS_DIALOG_BEGIN_ Procedure The SERVERCLASS_DIALOG_BEGIN_ procedure initiates a dialog with a server process in a server class and sends the first message in the dialog. The procedure identifies the server class to the system and returns a dialog identifier for subsequent dialog operations. A SERVERCLASS_DIALOG_BEGIN_ call must be matched by a SERVERCLASS_DIALOG_ABORT_ or SERVERCLASS_DIALOG_END_ call at the end of the dialog.
Syntax Pathsend Procedure Call Reference returns an error word containing one of the following values: 0 (FEOK) indicates that the call was successful and the server has ended the dialog. 70 (FEContinue) indicates that the call was successful and the server is ready for the next message in the dialog. 233 (FESCErr) indicates that an error occurred. You can call the SERVERCLASS_SEND_INFO_ procedure to get more detailed information about the error.
Syntax Pathsend Procedure Call Reference This parameter is required. request-len input INT:value is the byte length of the data contained in message-buffer. The range of acceptable values is 0 through 32767 bytes. This parameter is required. maximum-reply-len input INT:value is the maximum number of bytes that the reply message from the server class can contain. The range of acceptable values is 0 through 32767 bytes.
Syntax Pathsend Procedure Call Reference flags.<15> with a value of 1 indicates that this operation is to be performed nowait. A value of 0 indicates that this operation is to be performed waited. The default is 0. flags.<14> if set to 0, selects the one-transaction-per-dialog model. In this model, the dialog records the transaction identifier that is current at the time of the SERVERCLASS_DIALOG_BEGIN_ call.
Pathsend Procedure Call Reference Considerations is used for nowait I/O only. The tag is stored by the system and then passed back to the application by the AWAITIOX procedure when the nowait operation is completed. You can use the tag parameter to identify multiple nowait I/O operations. For waited I/O, this parameter is not used and can be omitted. The default is 0D.
Pathsend Procedure Call Reference SERVERCLASS_DIALOG_END_ Procedure SERVERCLASS_DIALOG_END_ Procedure The SERVERCLASS_DIALOG_END_ procedure cleans up resources for the specified dialog after the server has ended it. A call to SERVERCLASS_DIALOG_BEGIN_ must be matched by a call to SERVERCLASS_DIALOG_ABORT_ or SERVERCLASS_DIALOG_END_ at the end of the dialog.
Pathsend Procedure Call Reference SERVERCLASS_DIALOG_SEND_ Procedure SERVERCLASS_DIALOG_SEND_ Procedure The SERVERCLASS_DIALOG_SEND_ procedure initiates a send within the specified dialog.
Syntax Pathsend Procedure Call Reference dialog-id input INT(32):value is an identifier, previously returned from SERVERCLASS_DIALOG_BEGIN_, that specifies the dialog for this send operation. This parameter is required. message-buffer input, output STRING:ref:EXT:* contains the message to send to the server class. On successful completion of the send operation, message-buffer contains the reply from the server class. This parameter is required.
Syntax Pathsend Procedure Call Reference timeout input INT(32):value specifies the maximum amount of time, in hundredths of a second, that the LINKMON process waits for the completion of this send. This value must be either -1D or a value greater than 0D. The default is -1D (wait indefinitely). If there is an outstanding I/O operation to a server process when the SERVERCLASS_DIALOG_SEND_ operation times out, the I/O operation is canceled.
Pathsend Procedure Call Reference Considerations Considerations The SERVERCLASS_DIALOG_SEND_ procedure is similar to the context-free SERVERCLASS_SEND_ procedure, with the following differences: • • • The dialog identifier, obtained from the SERVERCLASS_DIALOG_BEGIN_ call that started the dialog, is used to identify the dialog, which is associated with a particular server class.
SERVERCLASS_SEND_ Procedure Pathsend Procedure Call Reference SERVERCLASS_SEND_ Procedure The SERVERCLASS_SEND_ procedure initiates a context-free send operation to a server process in the specified server class.
Syntax Pathsend Procedure Call Reference pathmon-process-name input STRING:ref:EXT:* contains the external Guardian process name of the PATHMON process controlling the server class (for example, $PM or \AB.$PMN). The process name portion can have up to five characters after the dollar sign ($) if it is a local process name and up to four characters after the dollar sign if it is a process on a remote system.
Syntax Pathsend Procedure Call Reference request-len input INT:value is the byte length of the data contained in message-buffer. The range of acceptable values is 0 through 32767 bytes. This parameter is required. maximum-reply-len input INT:value is the maximum number of bytes that the reply message from the server class can contain. The range of acceptable values is 0 through 32767 bytes.
Considerations Pathsend Procedure Call Reference flags input INT:value flags.<15> with a value of 1 indicates that this operation is to be performed nowait. A value of 0 indicates that this operation is to be performed waited. The default is 0. flags.<0:14> must be 0. scsend-op-num output INT:ref:EXT:1 returns the server-class send operation number.
Pathsend Procedure Call Reference SERVERCLASS_SEND_INFO_ Procedure SERVERCLASS_SEND_INFO_ Procedure The SERVERCLASS_SEND_INFO_ procedure retrieves error information about the last SERVERCLASS_SEND_, SERVERCLASS_DIALOG_BEGIN_, SERVERCLASS_DIALOG_SEND_, SERVERCLASS_DIALOG_END_, or SERVERCLASS_DIALOG_ABORT_ operation that was initiated or completed with return error 233 (FEScError) or 0 (FEOK).
Pathsend Procedure Call Reference Considerations Considerations The following considerations apply to the SERVERCLASS_SEND_INFO_ procedure: • • The condition code setting has no meaning following a call to SERVERCLASS_SEND_INFO_. A call to SERVERCLASS_SEND_INFO_ before a call is ever made to SERVERCLASS_SEND_ or SERVERCLASS_DIALOG_BEGIN_ results in return error 0 (FEOK), Pathsend error 906 (FEScNoSendEverCalled), and file-system error 0 (FEOK).
Pathsend Procedure Call Reference Usage Considerations for Pathsend Procedures Usage Considerations for Pathsend Procedures The following subsections discuss usage considerations that apply to several of the Pathsend procedure calls. Condition Code The condition-code setting has no meaning following a Pathsend procedure call. Waited I/O The following considerations apply to waited Pathsend procedure calls: • • The tag parameter has no meaning and can be omitted.
Pathsend Procedure Call Reference • Calls Within a TMF Transaction SERVERCLASS_SEND_, SERVERCLASS_DIALOG_BEGIN_, and SERVERCLASS_DIALOG_SEND_ return the server-class send operation number in the scsend-op-num parameter. See Server-Class Send Operation Number later in this section for more information about the server-class send operation number. For an example of issuing a nowait call to SERVERCLASS_SEND_, see the Pathsend program example BREQ, Example B-1 on page B-2.
Pathsend Procedure Call Reference Server-Class Send Operation Number A value of -1 is returned for nowait send operations that are not initiated successfully. A value of -1 is always returned for waited send operations. Note. Passing the server-class send operation number as a filenum parameter to Guardian procedures other than AWAITIOX, CANCEL, CANCELREQ, and FILEINFO results in filesystem error 2 (FEInvalOp).
Pathsend Procedure Call Reference • • Server-Class Send Operation Number If the canceled call was to SERVERCLASS_DIALOG_BEGIN_ or SERVERCLASS_DIALOG_SEND_, the dialog is aborted and the server receives a Pathsend dialog abort system message, even if the server has already replied to the server-class send operation. If the SERVERCLASS_SEND_, SERVERCLASS_DIALOG_BEGIN_, or SERVERCLASS_DIALOG_SEND_ operation was performed within a TMF transaction, the transaction is automatically aborted.
Pathsend Procedure Call Reference Timeout Considerations for Pathsend Programming Timeout Considerations for Pathsend Programming When you design a Pathsend application, you can decide which of two timeout methods that you want the LINKMON process to use: • • A server TIMEOUT attribute that applies only to the server process I/O A SERVERCLASS_SEND_, SERVERCLASS_DIALOG_BEGIN_, or SERVERCLASS_DIALOG_SEND_ parameter value that applies to the entire processing of the send request Because the errors for eac
Pathsend Procedure Call Reference Timeout Considerations for Pathsend Programming Nowait server-class send operations are completed with a call to AWAITIOX. The timeout considerations for nowait operations are more complex, because a time-limit parameter can also be set in the AWAITIOX call.
6 Pathsend Errors This section describes the error codes that can be returned by the Pathsend procedure calls. These errors can be returned by processes that call the Pathsend procedures directly and also by software that uses these procedures internally, such as the NonStop TUXEDO system.
Descriptions of Pathsend Errors Pathsend Errors • How to recover from the error These errors can be returned to Pathsend requesters. They can also be returned to NonStop TUXEDO clients that invoke NonStop TUXEDO request/response services or conversational services.
Descriptions of Pathsend Errors Pathsend Errors 902 FEScPathmonConnect Cause. An error has occurred in the requester’s communication with the PATHMON process. For example, an open operation has failed, an I/O error has occurred, or the PATHMON process has failed. Typical file-system errors: 12, 14, 40, 48, 201, or one of the path errors between 240 and 255. Effect. The SERVERCLASS_SEND_ or SERVERCLASS_DIALOG_BEGIN_ call is completed with an error. The message is not sent to the server process. Recovery.
Descriptions of Pathsend Errors Pathsend Errors 903 FEScPathmonMessage Cause. The LINKMON process received an unrecognizable message from the PATHMON process while processing a SERVERCLASS_SEND_ or SERVERCLASS_DIALOG_BEGIN_ request. You might be using incompatible versions of the LINKMON and PATHMON processes, or this could be a LINKMON or PATHMON process internal error. Typical file-system error: 0 (FEOK) Effect. The SERVERCLASS_SEND_ or SERVERCLASS_DIALOG_BEGIN_ call is completed with an error.
Descriptions of Pathsend Errors Pathsend Errors • Error 201 (FEPathDown) or error 240 through 255 indicates that a path error occurred (for example, the processor where the server process was running has failed). If this error is returned from SERVERCLASS_DIALOG_BEGIN_ or SERVERCLASS_DIALOG_SEND_, use SERVERCLASS_DIALOG_END_ or SERVERCLASS_DIALOG_ABORT_ to terminate the requester’s portion of the dialog. 905 FEScNoServerLinkAvailable Cause.
Descriptions of Pathsend Errors Pathsend Errors 909 FEScInvalidFlagsValue Cause. The caller set bits in the flags parameter that are reserved and must be 0. This is a programming error. Typical file-system error: 2 (FEInvalOp) Effect. The send initiation fails with an error. Recovery. Set the reserved bits in the flags parameter to 0. 910 FEScMissingParameter Cause. A required parameter was not supplied. This is a programming error. Typical file-system error: 29 (FEMissParam) Effect.
Descriptions of Pathsend Errors Pathsend Errors 913 FEScServerClassFrozen Cause. The server class the process tried to send to is frozen. Typical file-system error: 0 (FEOK) Effect. The SERVERCLASS_SEND_ or SERVERCLASS_DIALOG_BEGIN_ call is completed with an error. The message is not sent to the server class. Recovery. Resend after the system manager or operator has thawed the server class. 914 FEScUnknownServerClass Cause. The server class is not configured through the specified PATHMON process.
Descriptions of Pathsend Errors Pathsend Errors If a server process is in debug mode and a timeout error (file-system error 40) occurred, do the following: • • • • Use the PATHCOM STATUS PATHMON command to find the server classes that are in the LOCKED state. Identify the server program file for each locked server class. Issue the TACL command STATUS *, PROG object-file-name to list all running processes. Stop these processes by using the TACL STOP command.
Descriptions of Pathsend Errors Pathsend Errors 918 FEScSendOperationAborted Cause. The send operation has been terminated at an indeterminate point. Typical file-system error: 40 (FETimedOut) Effect. The send fails. A message might or might not have been sent to the server process, depending on when the send was aborted. Recovery. The recovery action depends on which file-system error has occurred. With error 40 (FETimedOut), you might want to try a larger timeout value.
Descriptions of Pathsend Errors Pathsend Errors Effect. The call is completed with an error. The message is not sent to the server process. Recovery. In some cases, you can recover from this error by retrying the call. Whether a retry will work depends on the design and operating environment of your application. If the PATHMON processes in your application are frequently created and stopped, retry the call.
Descriptions of Pathsend Errors Pathsend Errors 924 FEScTooManySendRequests Cause. The maximum number of concurrent server-class send operations allowed has been exceeded. The maximum number is 255 per requester and 512 for all requesters running in a processor. This error can occur on a call to SERVERCLASS_SEND_, SERVERCLASS_DIALOG_BEGIN_, or SERVERCLASS_DIALOG_SEND_. Typical file-system error: 0 (FEOK) Effect. The call is completed with an error. The message is not sent to the server process. Recovery.
Descriptions of Pathsend Errors Pathsend Errors 927 FEScTooManyDialogs Cause. The requester cannot start a new dialog, because it already has the maximum number of dialogs open. The maximum number of dialogs per requester is 256. This error can occur on a call to SERVERCLASS_DIALOG_BEGIN_. Typical file-system error: 0 (FEOK) Effect. The send initiation fails with an error. Recovery. Reduce the number of dialogs. 928 FEScOutstandingSend Cause.
Descriptions of Pathsend Errors Pathsend Errors 930 FEScChangedTransid Cause. A call to SERVERCLASS_DIALOG_SEND_, SERVERCLASS_DIALOG_END_, or SERVERCLASS_DIALOG_ABORT_ was done under a different transaction identifier than the previous call to SERVERCLASS_DIALOG_BEGIN_ (which had specified flags.<14> = 0). This is a programming error. Typical file-system error: 0 (FEOK) Effect. The operation fails with an error. Recovery.
Descriptions of Pathsend Errors Pathsend Errors 934 FEScTransactionAborted Cause. The transaction associated with the dialog has been aborted. Typical file-system error: 0 (FEOK) Effect. The procedure initiation fails with an error. The dialog is now aborted. Recovery. Use SERVERCLASS_DIALOG_END_ or SERVERCLASS_DIALOG_ABORT_ to terminate the requester’s portion of the dialog. 947 FEScLinkmonConnect Cause. There is a problem communicating with the LINKMON process in this processor.
A NonStop TS/MP Limits for Pathsend Requesters Table A-1 lists the NonStop TS/MP product limits that apply to the Pathsend programming environment. For limits related to the configuration of a PATHMON environment, refer to the NonStop TS/MP System Management Manual. Table A-1.
NonStop TS/MP Limits for Pathsend Requesters NonStop TS/MP Pathsend and Server Programming Manual– 132500 A- 2
B Examples This appendix shows the source code for two example programs designed to help you understand how to write Pathsend programs and Pathway servers. The following examples are included: • • A context-free Pathsend requester coded in TAL A context-free Pathsend nested server example coded in COBOL85 Edit files containing the source code for these examples are provided on the site update tape (SUT).
Pathsend Requester Example Examples Example B-1. Context-Free Pathsend Requester Program ?PAGE "BROADCAST REQUESTER (BREQ) OVERVIEW" ! @@@ START COPYRIGHT @@@ ! Tandem Confidential: Need to Know only ! Copyright (c) 1980-1985, 1987-1995, Tandem Computers Incorporated ! Protected as an unpublished work. ! All Rights Reserved.
Pathsend Requester Example Examples The following files are used by BREQ and must exist before running the program: INFILE OUTFILE -- each record is one transaction -- the outcome of the transaction ERROR LOG -- Entry sequenced; record length 132; not audited. The physical file name is read from the ASSIGN 'ERROR-LOG-FILE'. MESSAGE LOG -- Entry sequenced; record length 132; audited. The physical file name is read from the ASSIGN 'MESSAGE-LOG-FILE'.
Pathsend Requester Example Examples ?PAGE "VERSION PROCEDURE DECLARATION" ?SOURCE VersProc( PS^EXAMPLE^MODULE ) ?PAGE "GLOBAL DECLARATIONS FOR BREQ" ! The following are GLOBAL defines DEFINE def DEF lit = DEFINE#; = LITERAL#; DEF str DEF dbl = STRING#; = INT(32)#; ?PAGE "STRUCTS BREQ" ! ! These are the STRUCTS used when compiling the BREQ program. Comments appears to the right of the code.
Pathsend Requester Example Examples ?PAGE "STRUCTURE NEEDED TO PROCESS ASSIGN MSGS" ?SECTION ASSIGN ! The following is used to process ASSIGN msgs: STRUCT CI^ASSIGN (*); BEGIN INT MSG^CODE; STRUCT LOGICALUNIT; BEGIN STRING PROGNAMELEN, PROGNAME[0:30], FILENAMELEN, FILENAME[0:30]; END; INT(32) FIELDMASK; STRUCT TANDEMFILENAME; BEGIN INT VOLUME[0:3], SUBVOL[0:3], DFILE [0:3]; END; !CREATESPEC INT PRIMARYEXTENT, SECONDARYEXTENT, FILECODE, EXCLUSIONSPEC, ACCESSSPEC, RECORDSIZE, BLOCKSIZE; END; ! ci ASSIG
Pathsend Requester Example Examples ?PAGE "STRUCTURE NEEDED TO PROCESS PARAM MSGS" ?SECTION PARAM ! The following is used to process PARAM messages STRUCT CI^PARAM (*); BEGIN INT MSG^CODE, NUM^PARAMS; STR PARAMETERS[0:1023]; END; !PARAM msg ! ![0] -3 ![1] number of PARAMS in this msg ![2] PARAMS ! ?PAGE "STRUCTURE OF THE INPUT FILE" ?SECTION BREQ^INPUT ! ! ! The following is the record format of the edit file, which is the input to the BREQ program.
Pathsend Requester Example Examples ?PAGE "STRUCTURE OF A REQUEST TO PATHSRV" ?SECTION PATHSRV^REQUEST ! ! The following is the format of the msg to PATHSRV. used in BREQ. It is STRUCT PATHSRV^REQUEST^TEMPLATE (*); BEGIN STR PATHMON^ASSIGN^NAME[0:30]; STR PATHMON^SYSTEM^AND^PROCESS^NAME[0:14]; STR SERVER^CLASS[0:14]; END; ?PAGE "STRUCTURE OF A REPLY FROM PATHSRV" ?SECTION PATHSRV^REPLY ! ! The following is the format of the reply from PATHSRV. used in BREQ.
Pathsend Requester Example Examples ?PAGE "STRUCTURE OF THE CONTROL BLOCK" ?SECTION CONTROL^BLOCK ! ! ! This structure is used to keep data about a Pathsend send or message log write. Control blocks (cb's) are allocated from the upper 32K using GETPOOL. ! ! ! ! ! For each transaction, which is driven by data from one record in the input file, 3 cb's are allocated (one each for the Pathsend sends, and one for the message log write) and linked together in a linked list.
Pathsend Requester Example Examples ?PAGE "GLOBAL DECLARATIONS FOR BREQ" ! The following are GLOBAL literals: LIT nil^addr = -1D; LIT true LIT false = -1; = 0; LIT e^eof = LIT e^security^violation= -1; ! end of file 48; ! an access denied LIT open^read^only LIT open^write^only = %2000; = %4000; LIT open^shared LIT open^nowait^disk = %0; = %1; LIT retry^path^failures = 1; ! sync depth param in the open ! The following are TRACE file literals: LIT LIT LIT LIT LIT LIT LIT LIT LIT LIT LIT LIT
Pathsend Requester Example Examples ?PAGE "T9153 PATHWAY PATHSEND SC Errors" ! ! The following is a list of all the Server Class Errors. PATHSEND has ! error numbers 900 - 950 reserved.
Pathsend Requester Example Examples FEScLinkMonConnect = 947, FEScLastError = 950; ! Miscellaneous file system errors LIT LIT LIT LIT LIT FEok FEInvalidOp FEBoundsErr FEMissparam FESCError ! Various file numbers used globally INT INT INT INT INT INT = = = = = ! ! ! ! ! ! requesters has been exceeded. Error with LINKMON connection (eg. Open, I/O, etc. ). Last avail. PATHSEND error. This is for checking ranges not currently returned.
Pathsend Requester Example Examples INT .my^processid[0:3]; ! used to preface error msgs with my pid ! ! ! Define a global array to hold error msgs that aren't PATHSEND send errors. For example, reference parameter errors, AWAITIOX timeout errors, and validation errors. STR .global^non^pathsend^error^msg [0:77] := [78 * [" "]]; LIT max^assigns = 56; STRUCT .
Pathsend Requester Example Examples ?PAGE "START ONE I/O IN THE TRANSACTION" INT PROC initiate^IO (cb); INT .EXT cb (control^block^template); EXTERNAL; ?PAGE "START A WRITE OF THE INPUT REQUEST RECORD TO THE MSG LOG" INT PROC initiate^write^to^message^log (cb); INT .EXT cb (control^block^template); EXTERNAL; ?PAGE "REPORT AN IO ERROR" PROC IO^error (fnum); INT fnum; EXTERNAL; ?PAGE "SEARCH THE CONTROL BLOCKS FOR OUTSTANDING I/O" INT PROC io^outstanding (cb); INT .
Pathsend Requester Example Examples ?PAGE "PROCESS THE STARTUP MSG" PROC startup^proc (rucb, buf, msg, msg^len, match) VARIABLE; INT .rucb, .buf, .msg (ci^startup), msg^len, match; EXTERNAL; ?PAGE "STORE DATA IN THE CONTROL BLOCK" PROC store^control^block^info (cb, data^buf, cb^type, record^number); INT .EXT cb (control^block^template); STR .
Pathsend Requester Example Examples ! The following dummy procedure is for example program version control PS^EXAMPLE^VERSION^PROC; ?PAGE "PRINT A MESSAGE TO THE TERMINAL AND ABEND" ! ! ! ! Many procedures check for error conditions that, under normal circumstances, should not happen. In these cases, before ABENDing, a procedure will call this procedure to write a message to the home terminal. This proc calls ABEND. PROC abend^with^my^abend^msg; BEGIN INT .filename [0:11]; INT term^fnum; INT .
Pathsend Requester Example Examples IF (tmf^error := ABORTTRANSACTION) THEN ! failed to abort, file sys error in tmf^error BEGIN sbuf ':=' "ERROR WITH ABORTTRANSACTION: " -> @sp; CALL NUMOUT (sp, tmf^error, 10, 3); @sp := @sp[3]; CALL WRITE (error^log^fnum, buf, @sp '-' @sbuf); IF < THEN ! print an error msg and abend CALL IO^error (error^log^fnum); CALL ABEND; END; ! Successfully aborted the transaction CALL write^trace^file (trace^abort^transaction); sbuf ':=' "TRANSACTION ABORTED NORMALLY" -> @sp; CA
Pathsend Requester Example Examples IF (error := SERVERCLASS_SEND_INFO_ (pathsend^error, filesystem^error)) THEN ! problem making the call to SERVERCLASS_SEND_INFO_ BEGIN CALL serverclass^send^info^error (error); RETURN; END; ! Save off the errors and error msg text cb.pathsend^error := pathsend^error; cb.file^system^error := filesystem^error; ! ! ! ! This application treats Pathsend errors 916, 918, and 924 as retryable. Other errors may be retryable, depending on your application.
Pathsend Requester Example Examples IF pathsend^error = OR pathsend^error OR pathsend^error OR pathsend^error OR pathsend^error OR pathsend^error OR pathsend^error FEScInvalidSegmentId = FEScNoSegmentInUse = FEScInvalidFlagsValue = FEScMissingParameter = FEScInvalidBufferLength = FEScParameterBoundsError = FEScInvalidTimeoutValue !907! !908! !909! !910! !911! !912! !919! THEN ! the error returned from serverclass_send_ was a param error sp ':=' "(BAD PARAMETER PASSED TO SERVERCLASS_SEND_)" -> @sp; ! I
Pathsend Requester Example Examples IF assign^count >= max^assigns THEN ! will exceed the size of our assign table BEGIN sbuf ':=' "NUMBER OF ASSIGNS EXCEEDS MAX^ASSIGNS" -> @sp; CALL WRITE (term^fnum, buf, @sp '-' @sbuf); IF < THEN ! print an error msg and abend CALL IO^error (term^fnum); CALL ABEND; END; assign^table [assign^count] ':=' assign^msg FOR (msg^len + 1) / 2; assign^count := assign^count + 1; END; ! PROC assign^proc ?PAGE "CANCEL ALL OUR OUTSTANDING I/O" ! ! ! This proc is called to cancel I
Pathsend Requester Example Examples ?PAGE "COMPLETE THE OUTSTANDING I/O" ! ! ! ! This PROC waits for I/O to complete and returns the address of the control block associated with the completion. It returns nil^addr if I/O completed with an error, or nil^addr if there was no completion (in the case of a timeout, error 40). DBL PROC complete^io; BEGIN INT .EXT cb (control^block^template); DBL tag := -1D; DBL timelimit := 300D; ! wait 3 seconds (0.
Pathsend Requester Example Examples ! An error or warning occurred CALL FILEINFO (fnum, error); IF <> THEN ! couldn't access the ACB CALL abend^with^my^abend^msg; ! Check for a timeout error IF error = 40 THEN ! AWAITIO timed out and no completion has occurred BEGIN sbuf ':=' "AWAITIO TIMED OUT (ERROR 40)" -> @st; CALL WRITE (error^log^fnum, buf, @st '-' @sbuf); IF < THEN ! print an error msg and abend CALL IO^error (error^log^fnum); CALL write^trace^file (trace^io^timed^out); ! Save the error msg so
Pathsend Requester Example Examples ! Check for errors on the disk operation CASE cb.type OF BEGIN cb^type^msg^log -> BEGIN ! I/O to the message log file failed cb.file^system^error := error; cb.
Pathsend Requester Example Examples ?PAGE "CREATE THE CONTROL BLOCK MEMORY POOL" ! ! ! This procedure uses the standard memory management routines to declare a memory pool starting at the upper 32K, with a size of 32K bytes. ! ! Control blocks (cb's) are managed as a linked list, and new cb's are allocated in get^control^block. PROC create^the^memory^pool; BEGIN INT status; INT .buf [0:79]; STR .sbuf := @buf '<<' 1; STR .
Pathsend Requester Example Examples sbuf ':=' "TRANSACTION ENDED NORMALLY" -> @sp; CALL WRITE (error^log^fnum, buf, @sp '-' @sbuf); IF < THEN ! print an error msg and abend CALL IO^error (msg^log^fnum); END; ! PROC end^the^tmf^transaction ?PAGE "RETURN AN ENTRY FROM THE ASSIGN TABLE" ! ! ! This procedure is passed a logical ASSIGN name and searchs the ASSIGN table for the ASSIGN name. If found it returns the address of the table entry, otherwise false. INT PROC get^assign (logical^name, len); STR .
Pathsend Requester Example Examples ?PAGE "ALLOCATE A NEW CONTROL BLOCK FROM THE MEMORY POOL" ! ! ! This proc gets memory from the pool for a new control block (cb). The caller passes in the head of a list of control blocks, and it links the new cb to the end of that list. ! ! If the list head has a nil address, then the new cb becomes the first element of the list. ! ! This proc returns the address of the new control block. returning, the new cb is zero'd.
Pathsend Requester Example Examples ! Clean the new control block, and set the link to nil address cb ':=' 0 & cb FOR (($LEN (cb) + 1) / 2) - 1; @cb.next^cb := nil^addr; RETURN @cb; END; ! DBL PROC get^control^block ?PAGE "READ THE STARTUP AND ASSIGN MSGS, AND OPEN VARIOUS LOG FILES" ! ! ! ! This procedure calls the GUARDIAN 90 PROC INITIALIZER, which opens $RECEIVE and handles the protocol with our ancestor, TACL.
Pathsend Requester Example Examples ! ! Verify that the ASSIGNs for msg log file, error log file, and trace file are present in our ASSIGN table.
Pathsend Requester Example Examples ! ! The trace file contains a log of specific events that occurred in BREQ, e.g., a PATHSEND send or ENDTRANSACTION. logical^name ':=' "TRACE-FILE "; IF (@assign^ := get^assign (logical^name, 10)) THEN ! optional assign, use if included BEGIN CALL FNAMECOLLAPSE (assign^.tandemfilename.volume, trace^file); CALL FNAMEEXPAND (trace^file, trace^file, startup^msg.
Pathsend Requester Example Examples CALL DEVICEINFO (error^log^file, devtype, phys^reclen); IF devtype.<4:9> = 6 !type term! THEN ! Do a setmode so we can write to an un-paused TERM.
Pathsend Requester Example Examples ! ! ! Start the Pathsend send to the server class. Fill the send buf with blanks so there's not a cascading Pathsend send from server to server class. cb.io^buf ':=' " ! ! ! " & cb.io^buf FOR $OCCURS (cb.io^buf) - 1; Set up the ServerClass_Send_ parameters: get the PATHMON name and server class name lengths, and set the values for and . len := $OCCURS (cb.pathsend^req^buf.pathmon^system^and^process^name) - 1; WHILE cb.
Pathsend Requester Example Examples ! ! Also note that the param is an optional reference param that has a return value of 0 for nowaited I/O. error := SERVERCLASS_SEND_ (cb.pathmon^system^and^process^name, pathmon^process^name^len, cb.serverclass^name, serverclass^name^len, cb.
Pathsend Requester Example Examples ?PAGE "START A WRITE OF THE INPUT REQUEST RECORD TO THE MSG LOG" ! ! ! This proc is called from initiate^IO, and starts the I/O to the message log file. The WRITE is tagged so we can identify this I/O when completing it with AWAITIOX, or cancelling it with CANCELREQ. ! If the WRITE fails, we will not return. INT PROC initiate^write^to^message^log (cb); INT .EXT cb (control^block^template); BEGIN INT error := 0; CALL WRITEX (msg^log^fnum, cb.input^data^buf, $LEN(cb.
Pathsend Requester Example Examples CALL abend^with^my^abend^msg; sbuf ':=' "FILE SYSTEM ERROR " -> @sp; CALL NUMOUT (sp, error, 10, 3); @sp := @sp[3]; ! ! ! If the error is on a file already opened, include the file name in the error msg. If the error occurred while trying to open a file, we can't include the file name.
Pathsend Requester Example Examples ?PAGE "SEARCH THE CONTROL BLOCKS FOR I/O POSTED BUT NOT COMPLETED" ! ! ! ! I/O's were initiated out of control blocks. Here we step through the list of cb's and check for I/O that was initiated but not completed. If there are any outstanding I/O's, return true, otherwise return false. INT PROC io^outstanding (cb^list^head); INT .EXT cb^list^head (control^block^template); ! first element in cb list BEGIN INT .
Pathsend Requester Example Examples ! Store the server's reply: system name and process name out^buf.server^reply[i].system^name ':=' cb.pathsend^reply^buf.this^server.system^name FOR $OCCURS (cb.pathsend^reply^buf.this^server.system^name); out^buf.server^reply[i].process^name ':=' cb.pathsend^reply^buf.this^server.process^name FOR $OCCURS (cb.pathsend^reply^buf.this^server.process^name); ! ! Store Pathsend error msg text and file system error msg text generated by this program.
Pathsend Requester Example Examples ! Store non-Pathsend error messages generated by this program out^buf.non^send^error^msg ':=' global^non^pathsend^error^msg FOR $OCCURS (out^buf.
Pathsend Requester Example Examples IF NOT found AND NOT early^exit THEN ! look at the next param @sp := @sp[sp + sp[sp + 1] + 2]; END; ! while i < num params and not found IF NOT found THEN ! missing or bad param BEGIN sbuf ':=' "MISSING OR ILLEGAL PARAM 'MAX-RETRIES' " -> @sp; CALL WRITE (term^fnum, buf, @sp '-' @sbuf); IF < THEN ! print an error msg and abend CALL IO^error (error^log^fnum); CALL ABEND; END; ! if not found END; ! PROC param^proc ?PAGE "PROCESS ONE TRANSACTION" ! ! ! This PROC executes
Pathsend Requester Example Examples ! ! Step through the list of control blocks (cb's), initiating the I/O associated with each cb (a send or a write). WHILE @cb <> nil^addr DO BEGIN IF NOT initiate^IO (cb) THEN ! failed to start the operation, treat error as non-retryable BEGIN CALL cancel^outstanding^io (cb^list^head); CALL abort^tmf^transaction; RETURN false; END; ! Successfully started the I/O for this cb, goto next cb @cb := @cb.
Pathsend Requester Example Examples INT read^count; INT .error; BEGIN INT status; DBL LineNum; ! ! ! If status >= 0, the read was successful and status contains the count of chars in the text line. Actual bytes transferred <= read^count. If status < 0, an unrecoverable error occurred.
Pathsend Requester Example Examples WHILE @cb <> nil^addr DO BEGIN IF cb.type = cb^type^pathsend AND cb.pathsend^error THEN ! an error occurred on this Pathsend send BEGIN IF NOT cb.error^is^retryable THEN ! the transaction isn't retryable RETURN false; transaction^is^retryable := true; END; @cb := @cb.
Pathsend Requester Example Examples ! ! ! The following procedure is called from PROC analyze^send^error^233 when SERVERCLASS_SEND_INFO_ fails. All these errors are non-retryable, and all are programming errors.
Pathsend Requester Example Examples ?PAGE "SET UP THE CONTROL BLOCKS FOR ONE TRANSACTION" ! ! ! ! Here we get memory for each control transaction, and we store data from The data we store is data necessary transaction, a Pathsend send or msg block (cb) used in the the input record into the cb. to execute that part of the log WRITE. ! ! This proc returns the address of the first element in the list of control blocks. DBL PROC setup^control^blocks (input^buf, record^number); INT .
Pathsend Requester Example Examples ?PAGE "START THE TMF TRANSACTION" ! ! The following procedure is called by the MAIN proc to start the TMF transaction. PROC start^the^tmf^transaction; BEGIN DBL trans^tag; INT tmf^error; INT .buf [0:79]; STR .sbuf := @buf '<<' 1; STR .
Pathsend Requester Example Examples CALL IO^error (term^fnum); CALL IO^error (in^fnum); END; ! The IN file must be an EDIT file, so verify that now CALL FILEINFO (in^fnum,,,,,,,,, FileCode); IF FileCode <> 101 THEN ! illegal file type BEGIN sbuf ':=' "INFILE MUST BE TYPE EDIT (101)" -> @sp; CALL WRITE (term^fnum, buf, @sp '-' @sbuf); IF < THEN ! print an error msg and abend CALL IO^error (term^fnum); CALL ABEND; END; ! ! Setup the edit control block (a GLOBAL array) for calls to EDITREAD.
Pathsend Requester Example Examples ?PAGE "STORE DATA IN THE CONTROL BLOCK" ! ! ! This proc stores data to make one Pathsend send or one write to the message log file. The data is from one input record, and is stored in the control block that's passed into this procedure. PROC store^control^block^info (cb, data^buf, cb^type, record^number); INT .EXT cb (control^block^template); STR .
Pathsend Requester Example Examples ?PAGE "SUBPROC TO WRITE A VALIDATION ERROR MSG" ! ! If a record is invalid, write an error msg to the error log file ! SUBPROC output^msg; BEGIN CALL WRITE (error^log^fnum, buf, @sp '-' @sbuf); IF < THEN ! print an error msg and abend CALL IO^error (error^log^fnum); ! Save the error msg so we can include it in the output record global^non^pathsend^error^msg ':=' sbuf FOR @sp '-' @sbuf; END; ! SUBPROC output^msg ?PAGE "BEGIN BODY OF VALIDATE BREQ INPUT" FOR i := 0 to 1
Pathsend Requester Example Examples FOR $OCCURS (input^rec.server^request.pathmon^assign^name); RSCAN logical^name[30] WHILE " " -> @sp; IF NOT (@assign^ := get^assign (logical^name, @sp[1] '-' @logical^name)) THEN ! the ASSIGN isn't in our ASSIGN table BEGIN sbuf ':=' "ASSIGN '" -> @sp; sp ':=' logical^name FOR 31 -> @sp; RSCAN sp[-1] WHILE " " -> @sp; sp[1] ':=' "' NOT FOUND" -> @sp; CALL output^msg; RETURN false; END; ! Found the ASSIGN, save the PATHMON name CALL FNAMECOLLAPSE (assign^.
Pathsend Requester Example Examples ?PAGE "GET MY NAME OR PROCESS ID" ! ! The following procedure gets my name or process id so that ! error msg text can be preceded by my process name or cpu,pin. ! PROC who^am^i; BEGIN STR .spid := @my^processid '<<' 1; ! ! ! ! ! MYPID returns my cpu,pin and is input to GETCRTPID, which returns my^processid in this form: [0:2] = process name or creation timestamp [3].<4:7> = cpu [3].
Pathsend Requester Example Examples ! Let the user know who this msg is from swrite^buf ':=' spid FOR 6 BYTES -> @sp; RSCAN sp[-1] WHILE " " -> @sp; @sp := @sp[1]; sp ':=' ": " -> @sp; ! Include the record number IF $PARAM (record^number) THEN ! include it in the msg BEGIN sp ':=' "RECORD #" -> @sp; CALL NUMOUT (sp, record^number, 10, 3); @sp := @sp[4]; END; CASE function OF BEGIN !0! sp ':=' "READ ONE REQUEST MSG FROM INPUT FILE" -> @sp; !1! sp ':=' "INITIATED ONE PATHSEND SEND" -> @sp; !2! sp ':=' "
Pathsend Requester Example Examples ?PAGE "THE BREQ PROGRAM'S MAIN PROCEDURE" ! ! This procedure calls the initialize routine to start up, sets up a memory pool, and loops reading the IN file. ! ! ! Input records are validated, control blocks are allocated, the transaction is initiated and then completed, and control blocks are de-allocated.
Pathsend Requester Example Examples ! ! ! specified in the input record, and puts the process name associated with the ASSIGN into the PATHMON system and process name field of the input record. IF validate^breq^input (input^buf) THEN ! input record is valid BEGIN ! ! ! ! A valid request record is in the format of breq^input^rec^template, and contains data needed to make 2 Pathsend sends. The data is a PATHMON name (either explicit or an ASSIGN) and a server class name.
Pathsend Requester Example Examples CALL return^control^block^memory (cb^list^head); @cb^list^head := nil^addr; END; ! if read^ END; ! while not error IF error <> e^eof THEN ! print an error msg and abend CALL IO^error (in^fnum); ! CALL CALL CALL CALL end of file input file CLOSE CLOSE CLOSE CLOSE (in^fnum); (out^fnum); (msg^log^fnum); (error^log^fnum); IF trace^fnum > 0 THEN CALL CLOSE (trace^fnum); CALL STOP; END; ! PROC breq^program ?NOMAP NonStop TS/MP Pathsend and Server Programming Manual– 13250
Nested Server Example Examples Nested Server Example Example B-2, PATHSRV, is a context-free nested server coded in COBOL85. PATHSRV uses Pathsend calls within a server to access another server. Example B-2. Context-Free Server Program * @@@ START COPYRIGHT @@@ * Tandem Confidential: Need to Know only * Copyright (c) 1980-1985, 1987-1995, Tandem Computers Incorporated * Protected as an unpublished work. * All Rights Reserved.
Nested Server Example Examples * * * * ANY ERRORS THAT CAN NOT BE REPORTED BY PATHSRV BACK TO ITS REQUESTER ARE WRITTEN TO AN ERROR LOG FILE. THIS ENTRY SEQUENCED FILE WITH 132 BYTES RECORDS MUST EXIST PRIOR TO THE EXECUTION OF PATHSRV. ITS ASSIGN NAME IS ERROR-LOG-FILE. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. TANDEM. OBJECT-COMPUTER. TANDEM. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT MESSAGE-IN-FILE ASSIGN TO $RECEIVE FILE STATUS IS WS-FILE-STATUS.
Nested Server Example Examples DATA RECORD IS ERROR-LOG-REC. 01 ERROR-LOG-REC PIC X(132). WORKING-STORAGE SECTION. 01 WS-FILE-STATUS 88 WS-CLOSE-FROM-REQUESTER 01 WS-FILE-SYSTEM-ERROR-MESSAGE. 03 FILLER VALUE "FILE SYSTEM ERROR. FILE: ". 03 WS-LOGICAL-FILE-NAME 03 FILLER VALUE "FILE STATUS: ". 03 WS-FILE-STATUS-ERROR-MESSAGE 01 PIC X(2) VALUE ZERO. VALUE "10". PIC X(25) PIC X(31). PIC X(13) PIC 99. WS-NUMERIC-DISPLAY PIC S9(9).
Nested Server Example Examples * * * PROCESSINFO IS CALLED TO SEE IF THE MOM OF THE SERVER PROCESS IS A PATHMON. (THIS IDENTIFIES WHETHER THE SERVER IS ASSOCIATIVE.) AN ERROR NUMBER (WS-ERROR) MY BE RETURNED FOR A CALL TO PROCESSINFO. 01 * * * WS-PROCESSINFO-PARAM. 03 WS-ERROR PIC S9(4) COMP. THE FOLLOWING PARAMETERS ARE USED IN A CALL TO LOOKUPPROCESSNAME, WHICH LOCATES THE MOM OF THE CURRENT SERVER PROCESS (TO SEE IF IT'S A PATHMON). 01 * WS-LOOKUPPROCESSNAME-PARAM.
Nested Server Example Examples * * * THE FOLLOWING PARAMETERS ARE USED IN CALLS TO PROCESSINFO AND MYSYSTEMNUMBER, WHICH ARE USED TO IDENTIFY THE MOM OF THE SERVER PROCESS. 01 * * * * * WS-MOM-PROCESS. 03 WS-PROCESS-ID-GENERIC. 05 WS-BYTE-1 PIC X. 88 WS-LOCAL VALUE "$". 88 WS-NETWORK VALUE "\". 05 FILLER PIC X(5). 05 WS-CPU-PIN PIC S9(4) COMP. 03 WS-PROCESS-ID-LOCAL REDEFINES WS-PROCESS-ID-GENERIC. 05 WS-PROCESS-ID PIC X(6). 05 WS-CPU-PIN PIC S9(4) COMP.
Nested Server Example Examples * * * * * IF PATHSRV-REQUEST SPECIFIES A SERVER CLASS, THEN A PATHSEND REQUEST IS MADE TO A SUBSIDIARY SERVER. THE FOLLOWING GROUP DATA ITEMS ARE THE REQUEST AND REPLY MESSAGE LAYOUTS. THE REQUEST IS ALWAYS SPACE FILLED BECAUSE THE SUBSIDIARY SERVER IS NEVER ASKED TO MAKE A REQUEST OF ANOTHER SERVER. 01 01 * * SUBSIDIARY-REQUEST. 03 SUBSIDIARY-SERVER. 05 PATHMON-ASSIGN-NAME 05 PATHMON-SYSTEM-AND-PROCESS 05 SERVER-CLASS SUBSIDIARY-REPLY. 03 REPLY-CODE 03 THIS-SERVER.
Nested Server Example Examples * * * * REQUESTER ON $RECEIVE. IF AN ERROR IS FOUND WHILE READING $RECEIVE, A MESSAGE IS WRITTEN TO THE ERROR-LOG-FILE AND THE PROGRAM STOPS. PERFORM 0100-INITIALIZE.
Nested Server Example Examples 0200-PROCESS-TRANSACTION. * * * * * * * * THIS PARAGRAPH PROCESSES ONE MESSAGE FROM $RECEIVE. THE FORMAT OF THE MESSAGE IS PATHSRV-REQUEST. FIRST THE PATHSRV-REPLY MESSAGE IS INITIALIZED. THE SYSTEM AND PROCESS NAME OF THE CURRENT SERVER PROCESS ARE ALWAYS RETURNED TO THE REQUESTER IN THE PATHSRV-REPLY MESSAGE. IF THE SUBSIDIARY SERVER CLASS IS SPECIFIED IN THE REQUEST, THEN A PATHSEND SEND IS DONE TO THAT SUBSIDIARY SERVER CLASS.
Nested Server Example Examples * * * * * * IF THE PROGRAM LOGIC ARRIVES HERE, THEN NEITHER AN ASSIGN NOR AN EXPLICIT SYSTEM AND PROCESS NAME ARE USED TO IDENTIFY THE PATHMON TO WHICH THE PATHSEND SEND SHOULD BE DONE. IF THE MOM OF THE CURRENT SERVER PROCESS IS A PATHMON (I.E. WS-SERVER-IS-ASSOCIATIVE = "N") THEN ITS SYSTEM AND PROCESS NAME IS USED FOR THE PATHSEND SEND.
Nested Server Example Examples 0400-BUILD-ASSIGN-TABLE. * * * * * * * * * THIS PARAGRAPH LOADS WS-ASSIGN-TABLE FROM THE STARTUP ASSIGN MESSAGES. WS-ASSIGN-TABLE IS USED TO STORE UP TO FIFTY ASSIGN's. THESE ASSIGN's ARE FOR PATHMON SYSTEM AND PROCESS NAMES OF SUBSIDIARY SERVERS. IF PATHMON-ASSIGN-NAME IS USED IN THE REQUEST MESSAGE (PATHSRV-REQUEST) THEN THE ASSOCIATED PATHMON SHOULD BE IN THIS TABLE. THIS IS ONE WAY OF AVOIDING HARD-CODING PATHMON SYSTEM AND PROCESS NAMES.
Nested Server Example Examples 0410-GET-MY-SYSTEM-PROCESS. * * THIS PARAGRAPH GETS THE PROCESS-ID FOR THE CURRENT SERVER PROCESS. THIS PROCESS-ID IS RETURNED TO THE REQUESTER IN PATHSRV-REPLY. ENTER TAL "MYPID" GIVING WS-CPU-PIN OF WS-MY-PROCESS. ENTER TAL "GETCRTPID" USING WS-CPU-PIN OF WS-MY-PROCESS WS-PROCESS-ID OF WS-MY-PROCESS. ENTER TAL "MYSYSTEMNUMBER" GIVING WS-SYSTEM-NUMBER OF WS-MY-PROCESS. ENTER TAL "GETSYSTEMNAME" USING WS-SYSTEM-NUMBER OF WS-MY-PROCESS WS-SYSTEM-NAME OF WS-MY-PROCESS.
Examples Nested Server Example STRING "$" WS-PROCESS-ID OF WS-PROCESS-ID-NETWORK OF WS-MOM-PROCESS DELIMITED BY " " INTO WS-PROCESS-NAME OF WS-MOM-PROCESS END-IF ENTER TAL "GETSYSTEMNAME" USING WS-SYSTEM-NUMBER OF WS-MOM-PROCESS WS-SYSTEM-NAME OF WS-MOM-PROCESS STRING WS-SYSTEM-NAME OF WS-MOM-PROCESS DELIMITED BY " " "." DELIMITED BY SIZE WS-PROCESS-NAME OF WS-MOM-PROCESS DELIMITED BY " " INTO WS-SYSTEM-AND-PROCESS OF WS-MOM-PROCESS END-IF. 0440-VALIDATE-PATHSRV-REQUEST.
Nested Server Example Examples 0450-LOOKUP-PATHMON-ASSIGN. * * * * * THIS PARAGRAPH LOOKS UP AN ASSIGN FROM THE REQUEST MESSAGE TO SEE WHETHER A CORRESPONDING PATHMON SYSTEM AND PROCESS NAME CAN BE FOUND IN THE TABLE OF ASSIGNS BUILT WHEN THE SERVER PROCESS STARTED. THE RESULTING PATHMON SYSTEM AND PROCESS NAME IS PUT INTO THE PARAMETER VARIABLE THAT IS USED IN THE PATHSEND SEND.
Nested Server Example Examples * * * * * * THE SERVER CLASS OPERATION NUMBER PARAMETER IS OMITTED BECAUSE THE SEND IS BEING DONE IN WAIT MODE. IN NOWAIT MODE THE IS USED IN CALLS TO AWAITIOX. THE AND PARAMETER ARE OMITTED BECAUSE THE SEND IS BEING DONE IN WAIT MODE. THEY ARE ONLY NEEDED IN NOWAIT MODE.
Nested Server Example Examples INTO PATHSEND-ERROR OF PATHSRV-REPLY ELSE MOVE WS-PATHSEND-ERROR OF WS-SERVERCLASS-SEND-INFO-PARAM TO WS-NUMERIC-DISPLAY STRING "SERVERCLASS_SEND_ PATHSEND ERROR NUMBER : " WS-NUMERIC-DISPLAY DELIMITED BY SIZE INTO PATHSEND-ERROR OF PATHSRV-REPLY END-IF IF WS-FILE-SYSTEM-ERROR OF WS-SERVERCLASS-SEND-INFO-PARAM = 48 MOVE "SERVERCLASS_SEND_ SECURITY VIOLATION (ERROR 48)" TO FILE-SYSTEM-ERROR OF PATHSRV-REPLY ELSE IF WS-FILE-SYSTEM-ERROR OF WS-SERVERCLASS-SEND-INFO-PARAM = 40 M
Examples Nested Server Example NonStop TS/MP Pathsend and Server Programming Manual– 132500 B -68
Glossary Note. This glossary does not include terms for elements of the SCREEN COBOL language that are also found in standard COBOL. For definitions of such terms, refer to standard COBOL texts or to the text of the Pathway/TS SCREEN COBOL Reference Manual. absolute pathname. An OSS pathname that begins with a slash (/) character and is resolved beginning with the root directory. See also OSS pathname, relative pathname, and root directory. accept operation.
audited file Glossary audited file. A database file that is flagged for auditing by the TMF subsystem; auditing is the monitoring of transactions in preparation for recovery efforts. audit trail. A record of database changes that can be used by the TMF subsystem to rebuild a database in the event of a hardware or software failure. An audit trail is also known in the industry as a transaction log. availability.
client/transaction server model Glossary personal computers to a host computer system by means of supported communications protocols. See also requester/server model. client/transaction server model. A model for client/server applications. The client/transaction server model is the model of choice for high-volume OLTP applications in which transaction volume is great and the processing requirements change infrequently.
context Glossary context. Information required by a server to process the current request in an exchange of multiple request and reply messages: for example, identification of the last item processed. See also context-free server and terminal context. context-free server. A server that does not retain any information about the processing of previous requests.
cool start Glossary cool start. The operation that restarts a PATHMON environment, using the information in an existing PATHMON configuration file (PATHCTL file). The PATHMON environment must have been previously started with a cold start operation. See also cold start. Crossref cross-reference generator. A Tandem software tool that produces a crossreferenced listing of selected identifiers—such as data variables, statement labels, or subprograms—in an application program. current working directory.
DEFINE Glossary DEFINE. A named set of attributes and associated values. In a DEFINE (as with an ASSIGN command), users can specify information to be communicated to processes they start. definition files. A set of files containing data declarations for items related to SPI messages and their processing. The core definitions required to use SPI are provided in a DDL file and in several language-specific definition files, one for each programming language that supports SPI.
distributed transaction processing (DTP) Glossary distributed transaction processing (DTP). The coordination of transactions among application servers residing within an Expand network and possibly accessing different database management systems (NonStop SQL/MP and Enscribe). DTP allows the coordination of multiple, autonomous actions as a single logical unit of work. double-byte character. A character represented in two bytes. See also double-byte character set. double-byte character set (DBCS).
expandability Glossary expandability. See scalability. Expand networking software. Tandem software that can connect up to 255 Tandem NonStop systems into a single network. Extended General Device Support (GDSX). A Tandem product that facilitates communication between general I/O devices and a PATHMON environment by acting as a front-end or a back-end process. extensible structured token.
File Utility Program (FUP) Glossary attributes. A file system provides the namespace for the file serial numbers that uniquely identify its files. File Utility Program (FUP). A Tandem product that allows users to create, copy, purge, and otherwise manipulate disk files interactively. fixed-function terminal. A nonintelligent device (that is, a device without processing ability) capable of sending and receiving information over communications lines.
Inspect command terminal Glossary Inspect command terminal. The terminal on which programmers enter commands to Inspect when debugging a SCREEN COBOL program or a Pathway server. intelligent device.
link access Glossary blocks from one or more object files to produce a target object file. On Tandem NonStop systems, linking for TNS/R native object files is performed by the nld utility. link access. The actual transfer of data from a requester to a server process. In the Pathway environment, link access is provided by TCPs and LINKMON processes. See also link granting. link granting.
Glossary message-oriented requester message-oriented requester. A SCREEN COBOL requester that sends data from working storage to a device (or to a front-end process that controls a device) and receives data from the device or process into working storage by way of Message Section templates. SCREEN COBOL requesters that use the intelligent device support (IDS) facility are message-oriented.
noninteractive mode Glossary noninteractive mode. An operating mode in which commands are entered through a command file. NonStop Kernel. See Tandem NonStop Kernel. NonStop processing. On Tandem NonStop systems, processing characterized by continued operation even when a component fails, when equipment is being repaired or replaced, or while new processors or peripheral devices are being added to the system.
NonStop TUXEDO transaction processing environment Glossary applications. The NonStop TUXEDO system runs in the OSS operating environment on Tandem NonStop systems. See also OSS environment. NonStop TUXEDO transaction processing environment. An environment that provides the API and transaction monitor functions of the BEA Systems, Inc.
online transaction processing (OLTP) application Glossary used for many different kinds of business tasks such as order processing, inventory control, accounting functions, and banking operations. See also batch processing. online transaction processing (OLTP) application. A set of programs that perform online transaction processing (OLTP) tasks on behalf of the user. With an OLTP application, many terminal users can update data simultaneously, recording the changes in the database as they are entered.
PATHCOM command terminal Glossary PATHCOM command terminal. See command terminal. PATHCTL. See PATHMON configuration file. Pathmaker product. A menu-driven application generator, provided by Tandem, that increases the productivity of programmers developing Pathway applications. The Pathmaker software generates requester programs in SCREEN COBOL and server programs in C or COBOL85. PATHMON configuration file.
PATHTCP2 Glossary PATHTCP2. The TCP object file, usually identified by the file name $SYSTEM.SYSTEM.PATHTCP2. PATHTCPL. The TCP user library object file. Pathway application. A set of programs that perform online transaction processing tasks in the Guardian environment, using interfaces defined by Tandem. A Pathway application can include SCREEN COBOL requesters, Pathsend requesters, and Pathway servers running on Tandem NonStop systems.
Pathway subsystem Glossary Pathway subsystem. The PATHMON environment components to which SPI commands are sent under the Pathway subsystem ID and which generate EMS event messages with the Pathway subsystem ID. All SPI commands for the Pathway subsystem are sent to the PATHMON process, but the processsing for the command might involve other processes, such as a TCP.
primary process Glossary primary process. The currently active process of a process pair in the Guardian environment. See also backup process and process pair. process. (1) A unique execution of a program in the Guardian environment. (2) An entity in the OSS environment consisting of an address space, a single thread of control that executes within that address space, and the system resources required by that thread of control. See also process type. process identification number (PIN).
Glossary Remote Duplicate Database Facility (RDF) Remote Duplicate Database Facility (RDF). The Tandem software product that assists in disaster recovery for OLTP production databases, monitors database updates audited by the TMF subsystem on a primary system, and applies those updates to a copy of the database on a remote system. Remote Server Call (RSC).
request translation header Glossary executed until completion, it does not have any dialog with the requester, and it sends back a return value to the requester. A request/response server is analogous to a contextfree Pathway server. request translation header. A group of header fields that must be included at the beginning of each request message a SCREEN COBOL or Pathsend requester sends to the Pathway translation server for the NonStop TUXEDO system.
SCREEN COBOL Utility Program (SCUP) Glossary processes that manage application databases. SCREEN COBOL programs are compiled into pseudocode form by the SCREEN COBOL compiler and then interpreted by the TCP. See also terminal control process (TCP). SCREEN COBOL Utility Program (SCUP). A utility that provides control and manipulation of SCREEN COBOL object files. screen description entry. A declaration of a base screen, and, optionally, an overlay screen, in the Screen Section of a SCREEN COBOL program.
SERVER object Glossary SERVERCLASS_DIALOG_BEGIN_, and SERVERCLASS_DIALOG_SEND_ procedures perform server-class send operations. See also SEND operation. SERVER object. A definition of a server class within the configuration of a PATHMON process. service. A function performed by a server process or program on behalf of a requester or client. A server can perform one or several services.
subtype 30 process Glossary subsystem processes, such as the PATHMON process, for configuration and control of objects and for event management. subtype 30 process. A nonprivileged process that simulates terminals and communications devices. subvolume. A related set of files, as defined by the user, within the Guardian environment. The name of a subvolume is the third of the four parts of a file name. swap file.
Tandem NonStop Series/RISC (TNS/R) Glossary TNS processors implement the TNS instruction set. See also complex instruction-set computing (CISC) and Tandem NonStop Series/RISC (TNS/R). Tandem NonStop Series/RISC (TNS/R). Tandem computers that support the Tandem NonStop Kernel and that are based on reduced instruction-set computing (RISC) technology. TNS/R processors implement the RISC instruction set and are upwardly compatible with the TNS system-level architecture.
terminal data area (TDA) Glossary terminal data area (TDA). In SCREEN COBOL, the area that the TCP allocates for terminal context data. The MAXTERMDATA parameter of the PATHCOM SET TCP command defines the upper limit for this data area. TERM object. A definition of a task that uses a SCREEN COBOL program to control an input/output device such as a terminal or workstation, or an input/output process such as a front-end process.
transaction backout Glossary transaction backout. A TMF subsystem activity in which the effects of a partially completed transaction are canceled. Transaction Delivery Process (TDP). A multithreaded gateway process, part of the Remote Server Call (RSC) product, that runs on a Tandem NonStop system. The TDP can be replicated and can manage many connections and workstations at one time, as well as multiple sessions from each workstation. transaction identifier.
Glossary unsolicited-message processing (UMP) format defined by the program. The message is sent first to the TCP. It contains a header with information that is used by the TCP and a body with information that the TCP delivers to the SCREEN COBOL program. unsolicited-message processing (UMP). The feature that allows terminals running SCREEN COBOL requesters to accept and reply to unsolicited messages sent to them by Guardian processes outside of the PATHMON environment. USCODE.
Index A Aborted dialog (error 929) 6-12 Aborted dialogs, detecting 4-16/4-17 Aborted send operation (error 918) 6-9 Aborted transaction (error 934) 6-14 Aborting transactions 2-8, 2-23, B-15 ABORTTRANSACTION procedure 4-6 Access Control Server (ACS) 3-7 Application development tools 1-3 Application generator, Pathmaker 1-14 Application Transaction Monitor Interface (ATMI) 3-11 Applications, designing batch processing 2-27 database 2-9/2-10 example, OLTP 2-1/2-8 requester programs 2-11/2-19 server programs 2
B Index AWAITIOX procedure 5-7, 5-13, 5-17, 5-25, 5-28 B Back-end process 2-16, 2-24 BASIC, Extended, for Pathway servers 1-8 Batch processing 1-7, 2-13, 2-27 Bounds error (error 912) 6-6 Buffer length invalid (error 911) 6-6 Buffer limits A-1 C C and C++ languages for Pathsend requesters 1-10 for Pathway servers 1-8 invoking Pathsend procedures 5-2 Calls See Procedure calls, Pathsend, individual procedures CANCEL procedure 5-25/5-26 Canceling server-class send calls 5-25/5-26 CANCELREQ procedure 5-25/5
D Index CRE (Common Run-Time Environment) 4-3 Creation failure, servers (error 916) 6-8 Creator default for PATHMON names 3-7 CRE_Receive_Read_ procedure 4-14 Crossref product 1-14 D Data analyzing flow of 2-2/2-3 classes of 2-9 integrity 1-4 Database concurrency 2-7/2-8 consistency 1-4, 2-7/2-8 consistency and concurrency 4-5 fields in 2-9 files in, normalizing 2-9 integrity 1-8 logical design 2-9 management systems 2-10 physical design 2-10 records in 2-9 relational 2-10, 4-5 DBMS (database management
E Index E Extended General Device Support (GDSX) processes 1-10, 2-16/2-18, 2-24 Early replies 2-23 Enscribe product 2-10, 4-5 Entry-sequenced files 2-10 Errors See also Errors, file-system; Failure recovery; individual errors dialog abort system message (message -121) 4-16 FESCErr (error 233) 5-6, 5-7, 5-12, 5-13, 5-17 handling Pathsend 6-1/6-14 Pathsend server TIMEOUT 5-27 returned by servers in replies 4-14 server process 3-4 Errors, file-system associated with Pathsend errors 6-1/6-14 FEBoundsErr (e
G Index FESCErr (error 233) 5-6, 5-7, 5-12, 5-13, 5-17 FEScError (error 233) 3-9 FEScInvalidBufferLength (error 911) 6-6 FEScInvalidFlagsValue (error 909) 6-6 FEScInvalidPathmonName (error 901) 6-2 FEScInvalidSegmentId (error 907) 6-5 FEScInvalidServerClassName (error 900) 6-2 FEScInvalidTimeoutValue (error 919) 6-9 FEScLinkmonConnect (error 947) 6-14 FEScMissingParameter (error 910) 6-6 FEScNoSegmentInUse (error 908) 6-5 FEScNoSendEverCalled (error 906) 6-5 FEScNoServerLinkAvailable (error 905) 4-3, 6-5
I Index I L IDS See Intelligent device support (IDS) Industrial robots 2-16 Input file structure example B-6 Inspect product 1-14 Intelligent device support (IDS) description 2-12 GDSX programming for 2-17 overview 1-7 RSC requesters 1-12, 2-15 Intelligent mode 2-12 Interoperation of Pathsend requesters with NonStop TUXEDO servers 1-13 of Pathway servers with NonStop TUXEDO requesters (clients) 1-13 with NonStop TUXEDO requesters (clients) 4-17 with NonStop TUXEDO servers 3-11 Interprocess communication
N Index Messages dialog abort system message (message -121) 4-16 error, checking for 2-14 example print to terminal and abend B-15 for checkpointing 1-5 handling in a dialog 4-14/4-15 processing example B-60 receiving by servers 4-2 reply size, specifying maximum 5-9, 5-14, 5-19 unrecognizable (error 903) 6-4 Missing parameter (error 910) 6-6 Modes, terminal 2-12 Modularity 1-8 Multiprocessing 1-6 Multithreading GDSX feature 2-16 in server design 2-20 Pathsend requesters 1-9 N Native System /T clients, N
O Index Nowait send operations errors for 6-1 limit on number of A-1 procedure calls for 5-7, 5-13, 5-17 specifying 5-9, 5-15, 5-20 usage considerations 5-23/5-24, 5-28 No-early-reply rule 2-23 O OLTP application design example 2-1/2-8 development considerations 1-3/1-4 expanding systems for 1-7 importance of fault tolerance for 1-5 manageability 1-4 Pathway environment 1-3/1-7 support for NonStop TUXEDO environment 1-13 transaction processing scenario 1-15/1-17 Online transaction processing (OLTP) See O
P Index Pathsend application program interface (API) (continued) transaction processing scenario 1-15/1-17 Pathsend procedure calls See also individual procedures errors returned 6-1/6-14 invoking from C and C++ programs 5-2 invoking from COBOL85 programs 5-3 invoking from Pascal programs 5-4 invoking from TAL and pTAL programs 5-5 overview 5-1 return errors 6-1 usage considerations 5-23/5-28 use by NonStop TUXEDO requesters 4-17 Pathsend requesters checkpointing limitations 2-14 description 1-9 design co
Q Index pTAL for Pathsend requesters 1-10 for Pathway servers 1-8 invoking Pathsend procedures 5-5 PWY2TUX translation server 1-13, 3-11 Q Queuing of incomplete transactions 2-23 R RDBMS (relational database management system) See Database management systems RDF See Remote Duplicate Database Facility (RDF) Read operations, repeatable 4-8 RECEIVE messages allocating space 4-3 determining new dialogs 4-13 Record locking 4-8, 4-10 Records, database 2-9 Recovery context-sensitive requesters 3-9/3-10 fault-t
S Index Requesters, writing Pathsend (continued) NonStop TUXEDO, interoperating with 3-11 overview 3-3 procedure calls,list of 3-1 retryable requests 3-6 security issues 3-6/3-7 server process failures 3-4 sharing servers 4-1 TMF subsystem 3-5 using ASSIGNs 3-7 Requesting process has no… (error 75) 4-6 Request/response servers 4-1 Resource utilization 3-8 Response time 1-6 Retry mechanism, Pathsend calls 3-5 See also Fault tolerance Retryable requests, Pathsend 3-6 Retryable server operations, TMF 4-7 Ret
S Index Server programs (continued) dividing functions with requesters 2-19 example nested server B-53/B-67 GDSX back-end process, using 2-24 languages for 1-8 nested 2-13 nested servers 2-22/2-23 no-early-reply rule 2-23 packaging individual functions 2-21/2-22 Pathmaker, using to develop 1-14 single-threaded and multithreaded 2-20 structure of 2-25/2-27 TMF subsystem and fault tolerance 2-23 utilization of 2-20 Server reply code for RSC clients 4-4 for SCREEN COBOL requesters 4-3 SERVERCLASS_DIALOG_ABOR
T Index Servers, writing context-free with context-sensitive requesters 4-4 context-sensitive programming 4-13/4-17 debugging 4-11/4-12 Guardian 4-2, 4-3 linkage space considerations 4-3 nested servers 4-4 overview 4-1 Pathway 4-2 reply formats 4-1 RSC requester considerations 4-4 SCREEN COBOL requester considerations 4-3 sharing by different requesters 4-1 TMF subsystem application structure 4-5/4-6 audited files 4-7 fault-tolerant programming 4-10 grouping transaction operations 4-8/4-9 overview 4-5 rec
U Index timelimit parameter, AWAITIOX procedure 5-28 TIMEOUT attribute 5-27 Timeout error (error 40) 4-11/4-12 Timeout errors 4-11/4-12 Timeouts invalid value (error 919) 6-9 Pathsend usage considerations 2-14, 5-27/5-28 send completion, specifying maximum 5-9, 5-15, 5-19 servers, specifying 5-27 server-classes, specifying 5-27 TMF OFF server parameter 3-5, 5-24 TMF (Transaction Management Facility) audit-trail files 2-8 defining transactions 2-6 description 1-4 fault-tolerance role 1-6 Too many dialogs (
W Index W Waited send operations errors for 6-1 procedure calls for 5-7, 5-13, 5-17 specifying 5-9, 5-15, 5-20 usage considerations 5-23, 5-27 Workstation clients, NonStop TUXEDO, interoperating with 4-17 Special Character $RECEIVE messages allocating space 4-3 determining new dialogs 4-13 NonStop TS/MP Pathsend and Server Programming Manual– 132500 Index -15
Special Character Index NonStop TS/MP Pathsend and Server Programming Manual– 132500 Index -16
