HP NonStop TS/MP Pathsend and Server Programming Manual HP Part Number: 542660-007 Published: February 2012 Edition: J06.03 and all subsequent J-series RVUs and H06.
© Copyright 2012 Hewlett-Packard Development Company, L.P. Legal Notice Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license. The information contained herein is subject to change without notice.
Contents About This Manual........................................................................................7 Product Version........................................................................................................................7 Supported Release Version Updates (RVUs)..................................................................................7 Who Should Read This Manual..................................................................................................
Designing Server Programs......................................................................................................43 Design Considerations........................................................................................................43 Server Program Structure.....................................................................................................47 Designing Applications for Batch Processing..............................................................................
Handling ACS Subsystem Failures........................................................................................74 Writing Pathway Servers That Interoperate With NonStop Tuxedo Requesters..................................74 5 Pathsend Procedure Call Reference.............................................................75 Calls From C or C++...............................................................................................................76 Calls From COBOL85..............................
7 Pathsend Errors for ACS Subsystem...........................................................120 Types of Errors Returned by the Pathsend Procedures.................................................................120 Descriptions of Pathsend Errors...............................................................................................120 A TS/MP Limits for Pathsend Requesters........................................................128 B Examples.......................................................
About This Manual 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. 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 TS/MP and the HP NonStop Pathway/iTS products.
Related Documentation This manual is one in a set of manuals for the TS/MP and Pathway/iTS products. Figure 1 (page 8), shows the manuals that are most closely related to this manual. These paragraphs describe each of the supporting manuals shown in Figure 1. • Pathway/iTS TCP and Terminal Programming Guide. This guide describes how to write requester programs using SCREEN COBOL. • Guardian Programmer’s Guide.
For information about informational, warning, and error messages, see: • Guardian Procedure Errors and Messages Manual. This manual describes the Guardian messages for NonStop systems that use the HP NonStop Kernel operating system. The manual covers various types of error codes and error lists associated with Guardian procedure calls and also the interprocess messages sent to application programs by the operating system and the command interpreter. • Operator Messages Manual.
Other Manuals of Interest Other manuals that might be of interest to readers of this manual include these: • Availability Guide for Application Design. This manual describes the features of NonStop systems that support the availability of applications. This manual includes a section about application availability in the Pathway transaction processing environment. • Guardian Programmer’s Guide.
• Added a reference to Server Timeout in: ◦ “SERVERCLASS_DIALOG_BEGIN_ Procedure” (page 81) ◦ “SERVERCLASS_DIALOG_SEND_ Procedure” (page 88) ◦ “SERVERCLASS_SEND_ Procedure” (page 94) ◦ “SERVERCLASS_SENDL_ Procedure” (page 100) • Updated the description of “Server Timeout” (page 106). • Updated “limits for server-class send operations” (page 128). Changes in the H06.14/J06.03 Manual • Supported release statements have been updated to include J-series RVUs. • Added Table 1 (page 16).
Notation Conventions General Syntax Notation The list below 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.
… Ellipsis An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times. For example: M address [ , new-value ]… [ - ] {0|1|2|3|4|5|6|7|8|9}… 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.
error := FILE_GETINFO_ ( filenum !i , [ filename:maxlen ] ) ; !o:i Notation for Messages This list summarizes the notation conventions for the presentation of displayed messages in this manual. Nonitalic Text Nonitalic letters, numbers, and punctuation indicate text that is displayed or returned exactly as shown. For example: Backup Up. lowercase italic letters Lowercase italic letters indicate variable items whose values are displayed or returned.
Document History Part Number Product Version Published 542660-002 NonStop TS/MP 2.3 May 2008 542660-003 NonStop TS/MP 2.3 and 2.4 May 2009 542660-004 NonStop TS/MP 2.3 and 2.4 July 2009 542660-005 NonStop TS/MP 2.3 and 2.4 August 2009 542660-006 NonStop TS/MP 2.0, 2.1, 2.3, and 2.4 November 2010 542660-007 NonStop TS/MP 2.0, 2.1, 2.3, and 2.4 February 2012 HP Encourages Your Comments HP encourages your comments concerning this document.
1 Introduction to Pathway Application Programming This section introduces Pathway transaction processing applications, which you write and run with the assistance of the TS/MP and the Pathway/iTS software.
Table 2 Task and Manual Correspondences If Your Application Includes… You Need… Pathsend requesters Section 2, “Designing Your Application” (page 29) Section 3, “Writing Pathsend Requesters” (page 51) To Perform this… Design an application including Pathsend requesters Write a Pathsend requester program Section 5, “Pathsend Procedure Call Reference” Look up the syntax of Pathsend procedures (page 75) Pathway servers Section 6, “Pathsend Errors” (page 109) Look up cause, effect, and recovery for error
This cost reduction occurs because: • TS/MP and related products provide the most complex components of an OLTP application. TS/MP includes the Pathway monitor (PATHMON), the command interpreter for management (PATHCOM), and the means for interprocess communication. In addition, the TMF product provides the transaction manager, and the Pathway/iTS product provides a multithreaded TCP for communication with terminals, including fault tolerance and transaction protection.
For more information about the PATHMON process, the management interfaces, and status and error reporting capabilities in the Pathway environment, refer to the NonStop TS/MP System Management Manual, the Pathway/iTS System Management Manual, the NonStop TS/MP Management Programming Manual, and the Pathway/iTS Management Programming Manual. Data Integrity If your database is corrupted by a hardware or software failure, you might need weeks to isolate and then correct the problem.
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.
in conjunction with the operating system, allows you to distribute application processes within a single system. Additionally, TS/MP and TMF, in conjunction with the Expand networking software, allow you to spread processes, data, and transactions across a network of NonStop systems.
Server Classes Server classes provide these benefits: • You can minimize use of system resources—for example, processes and file opens—because server classes are shared and highly utilized. • You can maximize performance because server classes allow multiple copies of server processes to run concurrently in multiple processors.
SCREEN COBOL Requesters SCREEN COBOL requesters, which are compiled by the SCREEN COBOL compiler and then interpreted and executed by the TCP, provide ease of programming if you need to handle large numbers of terminals or intelligent devices or if you need screenpresentation services. The TCP and the SCREEN COBOL language produce a highquality, manageable application.
As shown in the figure, only server-class control information is passed to the LINKMON process; the application data moves directly from the Pathsend requester process to the server process. Figure 2 Pathsend Interprocess Communication Although you can obtain some information about LINKMON processes through the PATHMON process (by means of PATHCOM or SPI), LINKMON processes are not managed as PATHMON-controlled objects.
to run on NonStop systems, therefore providing these applications with the fundamental advantages of NonStop systems. When using the NonStop Tuxedo system, you work in the NonStop Tuxedo programming environment; you need not use the requester and server programming interfaces described in this manual. Note, however, that you can develop applications that use a combination of modules from the NonStop Tuxedo environment and the Pathway environment.
The Pathmaker Application Generator The Pathmaker product helps you create Pathway applications consisting of requester programs written in SCREEN COBOL and server programs written in C or COBOL85.
Figure 3 Example Application Using a Pathsend Requester 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 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.
8. Executing SQL/MP statements in its program, the server process accesses the database and updates the appropriate information. 9. The server process formats a reply message, which verifies that the information has been updated, and replies to the LINKMON process or the ACS subsystem processes by using NonStop Kernel interprocess communication. 10. The LINKMON process or ACS subsystem processes receive and forwards the reply messages to the Pathsend requester. The TMF transaction ends. 11.
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.
5. Accept any special instructions, such as back-ordering out-of-stock items, required to process the order. 6. Calculate the total order cost; get the current customer balance and credit limit from the \REG database; add the total order cost to current customer balance; and ensure that the new balance does not exceed the customer’s credit limit. 7. Ask the customer to confirm the order. 8.
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.
Figure 5 Relationships Between Transaction Functions 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 pages below outline how to integrate the TMF subsystem with your business transactions.
TMF transactions act as brackets; that is, the statements are placed before and after the add record, update record, and delete record procedures in your requester program. Figure 6 (page 33) illustrates the use of the TMF subsystem by a Pathsend requester program and a Pathway server program. In the illustration, the variable called TRANSID acts as a transaction identifier.
records are locked too early, other transactions cannot access them and the application’s concurrency (its ability to process many transactions at the same time) suffers. As the Enter Sales transaction demonstrates, all the data collection and validation operations can happen before you begin the TMF transaction—although some revalidation may be done again as part of the transaction. Assembling the order header and assembling the order involve reading records in the database but not changing the records.
relationships between each of the files in the database and then normalize your database files. To normalize files is to ensure, at a minimum, that: • There are no repeating fields. • Data is dependent on the entire key (a unique element) of a field. • Data is dependent on nothing but the key. 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.
Designing Requester Programs To facilitate the accessing of Pathway server classes from different transaction sources, you can develop requester programs for a Pathway application that use any of these access approaches: • SCREEN COBOL and the TCP • SCREEN COBOL and the TCP with the intelligent device support (IDS) facility • The Pathsend procedure calls • The RSC/MP product, with or without the POET • The GDSX product In Table 3 (page 36), key technical and business considerations are mapped to e
IDS Requesters Standard SCREEN COBOL requesters are screen oriented; they send data back and forth between the Working-Storage Section of the program and a terminal’s display screen by way of screen templates defined in the Screen Section. Standard SCREEN COBOL requesters use SCREEN COBOL ACCEPT and DISPLAY statements in the Procedure Division to interact with display terminals.
The Pathsend procedures and the LINKMON process or the ACS subsystem processes, however, do not provide multithreading, fault tolerance, device configuration, or operations management for requesters. Therefore, if you need these capabilities in a Pathsend requester, you must provide the programming for them. 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.
Example 1 Sample Pathsend Requester Program Structure Declare program variables. TMFError := BEGINTRANSACTION( TransactionTag ): Begins TMF transaction. Allocate buffer for request and reply messages. PathmonName ‘:=‘ [“$PM”] Set SERVERCLASS_SEND_ parameters. PathmonNameBytes :=3; ServerClass ‘:=‘ [“ASERVER”] nl nl nl Specifies no timeout. Specifies nowait send.
IF( ReplyError ) THEN . Perform application-dependent error logic, which may include aborting transaction. . . ELSE TMFError :=ENDTRANSACTION; Clients Using RSC/MP and POET The RSC/MP product facilitates client/server computing, allowing workstation applications to access Pathway server classes and Guardian processes. The RSC/MP product supports a number of different transport protocols and workstation platforms.
USCODE consists of user exits that are called by TSCODE to handle the application specific, data communications-related functions, such as data manipulation, protocol conversion, and message routing for the I/O process. USCODE is typically written in TAL or pTAL and bound with TSCODE to produce a functional GDSX process. GDSX provides its own interface to Guardian procedures, TMF procedures, and Pathsend procedures.
Figure 7 GDSX as a Front-End Process When developing a front-end process using GDSX, consider these 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. • A GDSX front-end process is also a good choice when performance is critical. SCREEN COBOL might not be efficient enough to handle a large amount of application function.
error? The SCREEN COBOL language allows such work to be done by the requester, but it could also be done by the server. For more considerations about dividing function among modules within an application, see “Packaging Server Functions” (page 44), under “Designing Server Programs” (page 43), later in this section.
processes on demand or communicates with a remote system from another vendor) or shared access (for example, when requests are multiplexed over a single link). Context-Free Servers Versus Context-Sensitive Servers If your servers are programmed to be context-free, the relationship between an application requester program (for example, a SCREEN COBOL program) and a Pathway server process exists only for the duration of a single send operation: that is, one request message and the server’s reply to it.
• One server for similar business functions: Similar business transactions (for instance, enter orders less than $100 in value or delete orders) are handled by a single server. • One server for similar business functions and all database functions: A single server services similar business transactions and handles both business decisions and database navigation. • Update or read-only server: A single server exclusively handles either update transactions or inquiry transactions.
Aborting Transactions A request sent to the server can have one of three outcomes: • All the work for the request was completed successfully. • None of the work for the request was completed. • The work for the request was only partially completed. In the first case, the requester can commit the transaction. In the second case, the requester can commit the transaction and then retry it.
the GDSX process might run a line-handler task to handle data on the communications lines and a device-handler task for each server process. The device handlers forward data to the line handler for forwarding to the remote system. Figure 8 GDSX as a Back-End Process For further information about designing and coding GDSX processes, refer to the Extended General Device Support (GDSX) Manual.
Example 2 COBOL85 Server Program Example IDENTIFICATION DIVISION. Declares server name. PROGRAM-ID. ORDER-SERVER. ENVIRONMENTAL DIVISION. CONFIGURATION SECTION. SPECIAL NAMES. FILE “$src.srvlib.orderlib” IS COBOL-LIB. Defines source library file names. FILE “$obj.srvlib.ocmgrobj” IS COMM-MGR. INPUT-OUTPUT SECTION. FILE CONTROL. SELECT MSG-IN ASSIGN TO $RECEIVE FILE STATUS IS RCV-STAT IN WS-RCV-INFO. Selects logical names for $RECEIVE and all database files accessed by server.
DATA DIVISION. FILE SECTION. Declares record data structures for logical file names. FD MSG-IN RECORD CONTAINS 204 CHARACTERS LABEL RECORDS ARE OMITTED 01 ORDER-MSG. . . . 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.
PROCESS-REQUEST SECTION. PERFORM GET-MSG IN RCV-MGR. Contains logic that reads requests in $RECEIVE, services requests, and replies to requests. IF NOT last-requester-close PERFORM DO-REQUEST. DO-REQUEST. IF function-code OF order-check-msg = ORDER-CHECK nl PERFORM DO-ORDER-CHECK ELSE IF function-code OF order-check-msg = ORDER-COMIT PERFORM DO-ORDER-COMIT nl nl ELSE PERFORM BAD-REQUEST IN ERROR-MGR. DO-ORDER CHECK. . . . RCV-MGR SECTION. Provides $RECEIVE I/O services. DB-MGR SECTION.
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 these: • 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” (page 62).
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 or the ACS subsystem processes, which in turn opens a server process selected by the PATHMON process.
The SERVERCLASS_SEND_ procedure enables Pathsend requesters to send data to and receive replies from a specified Pathway server class. This procedure communicates with the LINKMON process or the ACS subsystem processes in the processor where the Pathsend requester is running, passing information that enables the LINKMON process or the ACS subsystem processes to choose a link to a server process.
LINKMON Limit Errors In some cases, you can recover from a LINKMON limit error by retrying the Pathsend procedure call. Whether a retry will work depends on the design and operating environment of your application, including the configuration of static and dynamic links. Static links between a LINKMON process or the ACS subsystem processes and a PATHMON process generally persist for some time, depending on the application and the system workload.
is up again, the new communication channel is established and the send2 operation is successfully completed. • The application uses only waited context-free sends. After the first send operation (send1), the ACS subsystem goes down in a processor and is not up again before the next send operation (send2). The send1 operation successfully completes without any cause. When the send2 operation is initiated, TS/MP detects a problem with the existing communication channel to the ROUT process.
This is a transient error. The send operation will be successful when the ACS subsystem automatically restarts. The application program must retry the send operation till it succeeds. • The application uses a combination of waited and nowaited sends. TS/MP differentiates between waited and nowaited sends; therefore, separate communication channels are established for each. The behavior is the same as explained in the above scenarios for each type.
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.
to the server class’s OWNER and SECURITY attributes. You set these attributes for server classes at configuration time if those server classes are to be accessed by Pathsend processes. The NonStop TS/MP System Management Manual describes how to set the SERVER OWNER and SERVER SECURITY parameters in PATHCOM. RSC/MP Client Security RSC/MP workstation clients can be allowed or disallowed to communicate with specified Pathway servers.
To participate in a dialog with a context-sensitive Pathway requester, a server must perform additional tasks besides those required of all servers. These additional tasks are described under “Writing Context-Sensitive Servers” (page 70) in Section 4. Using Context-Sensitive Requesters With Context-Free Servers Context-sensitive requesters can perform single-send dialogs with Pathway servers that are coded to be context-free.
When the one-transaction-per-dialog model is used, the current TMF transaction, if any, 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-perdialog 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.
To communicate directly with a NonStop Tuxedo server by calling the ATMI functions, a Pathsend requester must also act as a NonStop Tuxedo client, as follows: • It must be compiled as an OSS process; therefore, it must be written in an HP language that supports OSS (such as HP C for NonStop systems ). • It must link in the ATMI functions. For example, if the requester is an HP C program, it can be linked to the ATMI functions by being compiled with the buildclient command.
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 RSC/MP product or the POET product. Pathsend requesters are described in this manual. SCREEN COBOL requesters are described in the Pathway/iTS TCP and Terminal Programming Guide; the SCREEN COBOL language is described in the Pathway/iTS SCREEN COBOL Reference Manual.
The LINKMON process’s open of the server process is shared among all the Pathsend requester processes running in the same processor as that of the LINKMON process or the ACS subsystem processes. Therefore, a close does not necessarily occur when the communication with a particular requester process is finished. Server Stop Protocol A Pathway server must stop itself when the LINKMON process, the ACS subsystem processes, or the TCP closes it on behalf of the last requester that has a link to it.
requesters from other PATHMON environments that specify associative servers and from outside the Pathway environment (for example, operations applications). The default value for MAXLINKS is an unlimited number of links; therefore, to avoid this problem, MAXLINKS must be set to a value. The error returned to a Pathsend requester is error 905 (FEScNoServerLinkAvailable) or 923 (FEScTooManyServerLinks). The error returned to a SCREEN COBOL requester is error 4 (link denied).
call to SERVERCLASS_SEND_) is, in effect, a dialog consisting of a single send operation. Pathway servers that are coded to be context-free can participate in single-send dialogs with context-sensitive requesters. However, if these servers check for system messages, you must modify them so that they recognize Pathsend dialog abort system messages, as described under “Writing Context-Sensitive Servers” (page 70) later in this section.
However, if the transaction work was only partially completed, as in the third case, the server needs to ensure that the transaction is not committed so that the incomplete work can be backed out. To ensure transaction backout, the server should call the ABORTTRANSACTION procedure after reading the server’s request and before sending its reply.
subset. You can place the extracted records in a nonaudited scratch file (each server can have its own scratch file, to avoid conflict among them). If the transaction is aborted and restarted, the transaction starts writing the scratch file from the beginning and there is no need for the scratch file to be audited. Another example is logging all input messages to a server, which allows examination of them after a failure.
These examples demonstrate how you might apply these guidelines. 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.
There is no comparable mechanism to indicate that a server process coded in TAL, pTAL, or FORTRAN should not run as a process pair. If you have server processes in these languages that are coded as process pairs, you can either implement a custom PARAM or recode your server. Transaction Deadlocks An application that uses the TMF subsystem might hold more record locks and hold them longer than it would without the TMF subsystem because: • Implicit locks are held on the keys of deleted records.
TERMINATION-STATUS value of 12 (I/O error) and a TERMINATIONSUBSTATUS value of 40 (timeout error). Note also that if the server class is configured so that it can be opened more than once (that is, with MAXLINKS greater than 1), the LINKMON process, the ACS subsystem processes, or TCP can attempt to open a server process in that server class at any time. This open attempt can time out if the server process is being debugged.
Section 3, “Writing Pathsend Requesters” (page 51), and Section 5, “Pathsend Procedure Call Reference” (page 75), convey dialog information to the server, and the server conveys dialog information in its reply. NOTE: The SCREEN COBOL language does not support context sensitivity; therefore, to take advantage of context sensitivity, you must use either a Pathsend requester or a GDSX front-end process that uses the GDSX pseudo Pathsend procedures.
1. 2. 3. 4. 5. Reads a message from $RECEIVE by using the $RECEIVE reading mechanism for the programming language, such as a call to the Guardian READUPDATE or READUPDATEX procedure. Checks bits <12:13> of the dialog flags returned by the FILE_GETRECEIVEINFO_ or the CRE_Receive_Read_ procedure. If the value in these bits is 1, the message is the first in a new dialog. If the value is 2, the message is for an existing dialog.
for bit 14 is 1, the server can abort the dialog by replying to the message with an error value of FEEOF (1). When the one-transaction-per-dialog model is used (when bit 14 of the dialog flags is equal to 0), the server must end the dialog by replying FEOK to a message before the requester can commit the associated TMF transaction. To allow requesters to ask the server to end the dialog, you can program your server to recognize a user-defined “end request” command.
messages if it uses FILE_GETRECEIVEINFO_, or CLOSE system messages if it uses CRE_Receive_Read_ or the COBOL85 or FORTRAN language. The server should treat such messages as dialog aborts. Servers can monitor CPU down, remote CPU down, and loss of communication with network node system messages by calling the Guardian procedures MONITORCPUS and MONITORNET, which are described in the Guardian Programmer’s Guide.
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.
NOTE: For general information about calling these and other NonStop 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. Therefore, language restrictions on procedures that set this register do not apply to the Pathsend procedures.
actual-reply-len timeout flags scsend-op-num tag GIVING error 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, and tag are variables defined in the WORKING-STORAGE SECTION of the DATA DIVISION. The types of these variables should be the COBOL85 types that correspond to the TAL variable types specified in the Pathsend procedure-call description later in this section.
To use the Pathsend procedures in a Pascal program, you must first have named them in a SOURCE PEXTDECS compiler directive. For further information, refer to the Pascal Reference Manual.
is the dialog identifier previously returned from the SERVERCLASS_DIALOG_BEGIN_ call that began the dialog. This parameter is required. Considerations These considerations apply to the SERVERCLASS_DIALOG_ABORT_ procedure: • If the server has opened $RECEIVE for system message handling and is using the Common Run-Time Environment (CRE), aborting the dialog will cause the server to receive a system message -121, PATHSEND DIALOG ABORT.
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. dialog-id output INT:ref:EXT(32):1 returns an identifier that can be used for subsequent operations on this dialog. This parameter is required.
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. No more than maximum-reply-len bytes of the actual reply are placed into message-buffer upon successful completion of a send. It is not an error if the server replies with a byte count not equal to the maximumreply- len value specified by the requester in the call to this procedure.
the send, and there are no restrictions on ENDTRANSACTION other than those associated with calls to the WRITEREAD procedure. The default is 0. flags.<0:13> must be 0. NOTE: For information on setting flag 9 for TS/MP 2.3 and later versions, see “Bridging Pathsend API into Pathway Domain” (page 108). scsend-op-num output INT:ref:EXT:1 returns the server-class send operation number.
NOTE: Messages greater than 32 KB in size are supported only on Expand-over-Servernet.
This is a mandatory parameter. server-class-name:length input:input STRING:ref:EXT64:*, INT:value contains the name of the server class (for example, EMP-SERVER). This name must conform to the Pathway server class naming rules, must be left justified in the buffer, and can contain trailing blanks. This server class name, along with the pathmon-process-name uniquely identifies a server class. The integer value is the byte length of the server-class-name string. This value can range from 1 through 15.
For more information on timeout for waited and nowait operations, see “Timeout Considerations for Pathsend Programming” (page 106). For more information on Pathsend error 904 and file system error 40, see “Server Timeout” (page 106). flags input INT:value flags.<15> indicates that this operation is to be performed nowait with a value of 1. A value of 0 indicates that this operation is to be performed waited. The default is 0. flags.
Considerations If the SERVERCLASS_DIALOG_BEGIN64_ procedure fails but does not return a valid dialog identifier, the dialog was never created. In this case, there is no need to abort the dialog. For additional considerations, see “Usage Considerations for Pathsend Procedures” (page 103). SERVERCLASS_DIALOG_END_ Procedure The SERVERCLASS_DIALOG_END_ procedure cleans up resources for the specified dialog after the server has ended it.
This procedure is similar to the context-free SERVERCLASS_SEND_ procedure, with a few differences as described under “Considerations.
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. No more than maximum-reply-len bytes of the actual reply are placed into message-buffer upon successful completion of a send. It is not an error if the server replies with a byte count not equal to the maximumreply- len value specified by the requester in the call to this procedure.
See “Server-Class Send Operation Number” (page 105) later in this section for more information about the server-class send operation number. tag input INT(32):value 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.
Syntax The syntax of the SERVERCLASS_DIALOG_SEND64_ procedure is: error := SERVERCLASS_DIALOG_SEND64_ ( dialog-id ,message-buffer ,request-len ,[ actual-reply-len ] ,maximum-reply-len ,[ timeout ] ,[ flags ] ,[ scsend-op-num ] ,[ tag ] ); ! ! ! ! ! ! ! ! ! i i,o i o i i o i i returned value error INT returns an error containing one of these values: 0 (FEOK) indicates that the call was successful and the server has ended the dialog.
No more than maximum-reply-len bytes of the actual reply are placed into message-buffer upon successful completion of a send. It is not an error if the server replies with a byte count not equal to the maximum-reply-len value specified by the requester in the call to this procedure. If the server replies with a byte count greater than the maximum-reply-len value, the actual bytes transferred are truncated to maximum-reply-len. This is a mandatory parameter.
Considerations The SERVERCLASS_DIALOG_SEND64_ procedure is similar to the context-free SERVERCLASS_SEND64_ procedure, with the following differences: • The dialog identifier, obtained from the SERVERCLASS_DIALOG_BEGIN64_ call that started the dialog, is used to identify the dialog, which is associated with a particular server class.
23, 3 (FESCErr) indicates that an error occurred. You can call the SERVERCLASS_SEND_INFO_ procedure to get more detailed information about the error. 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). For TS/MP 2.3 and later versions, it is the pathway domain name, whose member pathmons have the server class configured under them. For more information on TS/MP 2.
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. No more than maximum-reply-len bytes of the actual reply are placed into message-buffer upon successful completion of a send. It is not an error if the server replies with a byte count not equal to the maximumreply-len value specified by the requester in the call to this procedure.
initiated nowait send. This value is returned on every subsequent nowait send that is initiated successfully. A value of -1 is returned for nowait sends that are not initiated successfully. A value of -1 is always returned for waited sends. See “Server-Class Send Operation Number” (page 105) later in this section for more information about the server-class send operation number. tag input INT(32):value is used for nowait I/O only.
0 (FEOK) indicates that the call was successful. 233 (FESCErr) indicates that an error occurred. For detailed information on the error, call SERVERCLASS_SEND_INFO64_ procedure. pathmon-process-name input STRING:ref:EXT64:* contains the external Guardian process name of the PATHMON process controlling the server class (for example, $PM or \AB.$PMN). For TS/MP 2.3 and later versions, it is the pathway domain name, whose member Pathmons have the server class configured under them.
This is a mandatory parameter. 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 to 32767 bytes. No more than maximum-reply-len bytes of the actual reply are placed into message-buffer upon successful completion of a send. It is not an error if the server replies with a byte count not equal to the maximumreply-len value specified by the requester in the call to this procedure.
successfully initiated nowait send. This value is returned on every subsequent nowait send that is initiated successfully. A value of -1 is returned for nowait sends that are not initiated successfully. A value of -1 is always returned for waited sends. For more information about the server-class send operation number, see “Server-Class Send Operation Number” (page 105). tag input INT(64):value is used for nowait I/O only.
error returned value INT returns a file-system error number indicating the outcome of the operation. 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) or the Pathway domain name, whose member PATHMONs have the server class configured under them.
INT(32):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 2097152 bytes. This parameter is required. actual-reply-len output INT(32):ref:EXT:1 returns a count of the number of bytes returned in the server process reply. This parameter is for waited I/O only and can be omitted for nowait I/O. The return value of this parameter is 0 if nowait I/O is used. For nowait I/O, the actual reply length is returned by AWAITIOXL.
Considerations See “Usage Considerations for Pathsend Procedures” (page 103). Retaining Concurrent Sends Limit The Pathsend procedures use the process file segment (PFS) of the caller to store the requests and reply messages. The maximum PFS size is 32 MB.
error returned value INT returns an error word. This error is associated with the call to SERVERCLASS_SEND_INFO_ and not with the previous Pathsend call. The error word contains one of these file-system errors: 0 (FEOK) indicates that no errors occurred in the call to SERVERCLASS_SEND_INFO_. 2 (FEInvalOp) is returned if the caller has an invalid segment in use. Error 2 is also returned if the caller has no extended data segment in use and one of the reference parameters is an extended address.
error returned value INT returns an error word. This error is associated with the call to SERVERCLASS_SEND_INFO64_ and not with the previous Pathsend call. The error word contains one of these file-system errors: 0 (FEOK) indicates that no errors occurred in the call to SERVERCLASS_SEND_INFO64_. 2 (FEInvalOp) is returned if the caller has an invalid segment in use. Error 2 is also returned if the caller has no extended data segment in use and one of the reference parameters is an extended address.
For an example of issuing a waited call to SERVERCLASS_SEND_, see the Pathsend server program example PATHSRV, Example 4 (page 182). In this COBOL85 program, paragraph 460-SEND-TO-SUBSIDIARY-SERVER performs a waited SERVERCLASS_SEND_ call. Nowait I/O These considerations apply to nowait Pathsend procedure calls: • You complete a nowait Pathsend procedure call with a call to AWAITIOX. You cannot use the AWAITIO—without the X—procedure to complete a nowait server-class send operation.
(FEScError), Pathsend error 917 (FEScServerClassTmfViolation), and file-system error 0 (FEOK). See the NonStop TS/MP System Management Manual for details about the TMF parameter of the SET SERVER command. Server-Class Send Operation Number The server-class send operation number is returned in the scsend-op-num parameter on the first successfully initiated nowait server-class send operation (through a call to SERVERCLASS_SEND_, SERVERCLASS_DIALOG_BEGIN_, or SERVERCLASS_DIALOG_SEND).
Calling CANCEL or CANCELREQ has these effects on your Pathsend program: • The program is not affected by any reply to the SERVERCLASS_SEND_, SERVERCLASS_DIALOG_BEGIN_, or SERVERCLASS_DIALOG_SEND_ call. • The program cannot determine whether the request message has been sent to a server process, and if it was sent, whether or not it was canceled before the server process finished processing the request.
call, described in these subsections, the TIMEOUT attribute does not include waiting for the server link; the TIMEOUT attribute applies only to the I/O to the server. Server timeout returns Pathsend error 904 (FEScServerLinkConnect) and file-system error 40 (FETimedOut).
(for example, WRITEREAD calls, which do not provide a timeout parameter) and you also use a timeout value on the Pathsend calls, timeouts can occur in one of the preceding two ways, depending on which timer expires first. To avoid this complex error handling, it is recommended that you use a timeout value only on 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.
900 FEScInvalidServerClassName Cause. The server-class name specified in a call to SERVERCLASS_SEND_ or SERVERCLASS_DIALOG_BEGIN_ is not syntactically correct. This is a programming error. Typical file-system error: 2 (FEInvalOp) Effect. The send initiation fails with an error. Recovery. Correct the server-class name syntax. See the NonStop TS/MP System Management Manual for a description of the correct syntax for server-class names. 901 FEScInvalidPathmonName Cause.
• Error 48 (FESecViol) indicates there was a security violation. See Section 3, “Writing Pathsend Requesters” (page 51), for information about network and server-class security. • Error 201 (FEPathDown) or error 240 through 255 indicates that a path error occurred (for example, the PATHMON process failed). Restart the PATHMON process. 903 FEScPathmonMessage Cause.
Cause. The LINKMON process had no links to the server class and was unable to get a link from the PATHMON process to satisfy this request. For example, MAXLINKS links for each server class are already allocated to other LINKMON processes and TCPs. This is a PATHMON configuration problem. 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 process. Recovery.
Cause. The buffer length in the request-len or maximum-reply-len parameter for a call to SERVERCLASS_SEND_, SERVERCLASS_DIALOG_BEGIN_, or SERVERCLASS_DIALOG_SEND_ is invalid. This is a programming error. Typical file-system error: 21 (FEBadCount) Effect. The send initiation fails with an error. Recovery. Check the buffer lengths allowed for the request-len and maximum-reply-len parameters in the syntax description for the procedure call, and specify the correct buffer lengths.
Effect. The SERVERCLASS_SEND_, SERVERCLASS_DIALOG_BEGIN_, or SERVERCLASS_DIALOG_SEND_ call is completed with an error. The message is not sent to the server class. Recovery. If the PATHMON process is shutting down, determine the reasons for the shutdown and perform appropriate recovery actions. If a server process is in debug mode and a timeout error (file-system error 40) occurred: • Use the PATHCOM STATUS PATHMON command to find the server classes that are in the LOCKED state.
919 FEScInvalidTimeoutValue Cause. The caller supplied an invalid timeout value in a call to SERVERCLASS_SEND_, SERVERCLASS_DIALOG_BEGIN_, or SERVERCLASS_DIALOG_SEND_. This is a programming error. Typical file-system error: 2 (FEInvalOp) Effect. The send initiation fails with an error. Recovery. Specify a valid timeout value. See the procedure call syntax description for details about valid timeout values. 920 FEScPFSUseError Cause. The caller’s process file segment (PFS) could not be accessed.
923 FEScTooManyServerLinks Cause. The LINKMON process already has the maximum number of concurrent links to server processes allowed for all PATHMON processes. The maximum number is 1750. 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 process. Recovery. In some cases, you can recover from this error by retrying the call.
Recovery. Use a valid dialog identifier. 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. The requester has an outstanding send operation on this dialog.
Effect. The operation fails with an error. Recovery. Use RESUMETRANSACTION to make the correct transaction identifier current, and reissue the call that failed. 931 FEScDialogEnded Cause. A call to SERVERCLASS_DIALOG_SEND_ failed because the server had already ended the dialog, either by replying with FEOK or FEEOF or by terminating while a send was still outstanding. Typical file-system error: the file-system error of the last server response.
Each subsequent SERVERCLASS_SEND_, SERVERCLASS_DIALOG_BEGIN_, or SERVERCLASS_DIALOG_SEND_ call in this processor causes the LINKMON process to reattempt initialization; after the condition is corrected, the LINKMON process can complete initialization. For information about initialization and limits for the LINKMON process, refer to “LINKMON Limit Errors” (page 44) and also to the NonStop TS/MP System Management Manual.
7 Pathsend Errors for ACS Subsystem This chapter describes the error codes that can be returned by the TS/MP 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 ACS subsystem.
901: FEScInvalidPathmonName Cause. The PATHMON process name specified in a call to SERVERCLASS_SEND_ or SERVERCLASS_DIALOG_BEGIN_ is not syntactically correct. This name must be a valid external process name. This is a programming error. Typical file-system error: 2 (FEInvalOp). Effect. The send initiation fails with an error. Recovery. Correct the PATHMON name syntax.
904: FEScServerLinkConnect Cause. An error has occurred with the link to the server. For example, an open operation has failed or there is an I/O problem. This error could occur on a call to SERVERCLASS_SEND_, SERVERCLASS_DIALOG_BEGIN_, or SERVERCLASS_DIALOG_SEND_. Typical file-system errors: 14, 40, 48, 201, or one of the path errors between 240 and 255. Effect. The call is completed with an error. The message might or might not have been sent to the server process, depending upon the file-system error.
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. The send initiation fails with an error. Recovery.
915: FEScPathmonShutDown Cause. The send operation has been denied for one of these reasons: • The PATHMON process for the server class is shutting down. • A timeout occurred on an I/O operation to a server in debug mode. Typical file-system error: 0 (FEOK). Effect. The SERVERCLASS_SEND_, SERVERCLASS_DIALOG_BEGIN_, or SERVERCLASS_DIALOG_SEND_ call is completed with an error. The message is not sent to the server class. Recovery.
919: FEScInvalidTimeoutValue Cause. The caller supplied an invalid timeout value in a call to SERVERCLASS_SEND_, SERVERCLASS_DIALOG_BEGIN_, or SERVERCLASS_DIALOG_SEND_. This is a programming error. Typical file-system error: 2 (FEInvalOp). Effect. The send initiation fails with an error. Recovery. Specify a valid timeout value. See the procedure call syntax description for details about valid timeout values. 920: FEScPFSUseError Cause. The caller’s process file segment (PFS) could not be accessed.
This error can also occur when the ACS subsystem processes in a CPU fail and the Pathsend requesters on that CPU continue running. When ACS subsystem processes fail, both TSMP 2.1 and TSMP 2.3 do not automatically terminate the Pathsend requesters in the CPU. Therefore, some of the requesters might be in an inconsistent state and may continue to receive this error for dialog-based send initiations. This can occur even after the ACS subsystem processes are restarted on the CPU.
933: FEScDialogOutstanding Cause. A call to SERVERCLASS_DIALOG_END_ was made, but the server has not ended the dialog. Typical file-system error: 0 (FEOK). Effect. The procedure initiation fails with an error. Recovery. Reply FEOK to cause the server to end the dialog or use SERVERCLASS_DIALOG_ABORT_ to abort the dialog. 934: FEScTransactionAborted Cause. The transaction associated with the dialog was aborted. Typical file-system error: 0 (FEOK). Effect. The procedure initiation fails with an error.
A TS/MP Limits for Pathsend Requesters Table 6 (page 128) lists the 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.
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. These 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).
Example 3 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.
ERROR-LOG-FILE -- Used to record error msgs. MESSAGE-LOG-FILE -- A write to this file is part of a transaction. It contains request msgs received by BREQ from DRIVER. TRACE-FILE (OPTIONAL) -- Used to log certain READs, SENDs, and TMF operations. There can also be up to 50 ASSIGNs to give logical names to PATHMONs that may be referenced in the input record. The following PARAM is passed: MAX-RETRIES -- BREQ uses this number to calculate the number of times it will try to recover from PATHSEND SEND failures.
?PAGE "STRUCTURE NEEDED TO STARTUP A PROCESS" ?SECTION STARTUP ! The following is used when starting up STRUCT .
?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 ASSIGN ! !ASSIGN msg ! ![0] -2 !PARAMS to AS
?PAGE "STRUCTURE NEEDED TO PROCESS PARAM MSGS" ?SECTION PARAM ! The following is used to process PARAM messages STRUCT CI^PARAM (*); !PARAM msg BEGIN ! INT MSG^CODE, ![0] -3 NUM^PARAMS; ![1] number of PARAMS in this msg STR PARAMETERS[0:1023]; ![2] PARAMS END; ! ?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.
! The following is the structure of the output record that BREQ ! writes to the OUT file specified in the run line. STRUCT BREQ^OUTPUT^REC^TEMPLATE (*); BEGIN STRUCT SERVER^REPLY [0:1]; BEGIN STR SYSTEM^NAME[0:7]; STR PROCESS^NAME[0:7]; STRUCT ERROR^MSG; BEGIN STR PATHSEND^ERROR[0:77]; STR FILE^SYSTEM^ERROR[0:77]; END; END; STR NON^SEND^ERROR^MSG[0:77]; END; ! BREQ output rec template ?PAGE "STRUCTURE OF A REQUEST TO PATHSRV" ?SECTION PATHSRV^REQUEST ! The following is the format of the msg to PATHSRV.
?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. At transaction completion, the cb memory is returned ! using PUTPOOL.
! The following are GLOBAL literals: LIT nil^addr = -1D;\ LIT true = -1; LIT false = 0; LIT e^eof = -1; ! end of file LIT e^security^violation= 48; ! an access denied LIT open^read^only = %2000; LIT open^write^only = %4000; LIT open^shared = %0; LIT open^nowait^disk = %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 LIT trace^read^input trace^pathsend trace^write^to^msg^log trace^begin^transaction trace^
?PAGE "T9153 PATHWAY PATHSEND SC Errors" ! ! The following is a list of all the Server ! error numbers 900 - 950 reserved. ! LITERAL FEScFirstError = 900, ! FEScInvalidServerClassName = 900, ! FEScInvalidPathmonName = 901, ! FEScPathmonConnect = 902, ! ! connection (eg. Open, ! etc.).
! requesters has been exceeded. = 947, ! Error with LINKMON connection ! (eg. Open, I/O, etc. ). FEScLastError = 950; ! Last avail. PATHSEND error. ! This is for checking ranges ! not currently returned.
PROC assign^proc (rucb, passthru, assign^msg, msg^len, match) VARIABLE; INT .rucb, .passthru, .assign^msg, msg^len, match; EXTERNAL; ?PAGE "RETURN AN ENTRY FROM THE ASSIGN TABLE" INT PROC get^assign (logical^name, len); STR .logical^name; INT len; EXTERNAL; ?PAGE "READ THE STARTUP AND ASSIGN MSGS, AND OPEN THE LOG FILE" PROC initialize; EXTERNAL; ?PAGE "START ONE I/O IN THE TRANSACTION" INT PROC initiate^IO (cb); INT .
PROC param^proc (rucb, buf, param^msg, msg^len, match) VARIABLE; INT .rucb, .buf, .param^msg (ci^param), msg^len, match; EXTERNAL; ?PAGE "READ FROM AN EDIT FILE" INT PROC read^ (fnum, buf, read^count, error); INT fnum; STR .buf; INT read^count; INT .error; EXTERNAL; ?PAGE "LOOK AT WHY SERVERCLASS_SEND_INFO_ FAILED" PROC ServerClass^Send^Info^error (error); INT error; EXTERNAL; ?PAGE "SET UP THE CONTROL BLOCKS FOR ONE TRANSACTION" DBL PROC setup^control^blocks (input^buf, record^number); INT .
PROC store^control^block^info (cb, data^buf, cb^type, record^number); INT .EXT cb (control^block^template); STR .data^buf (pathsrv^request^template); INT cb^type; INT record^number; EXTERNAL; ?PAGE "BE SURE AN INCOMING REQUEST IS VALID" INT PROC validate^breq^request (input^rec); INT .
! 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 circumstances, should ABENDing, a procedure to the home terminal. for error conditions that, under normal not happen. In these cases, before will call this procedure to write a message This proc calls ABEND. PROC abend^with^my^abend^msg; BEGIN INT .filename [0:11]; INT term^fnum; INT .buf [0:79]; STR .sbuf := @buf '<<' 1; STR .
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; CALL WRITE (error^log^fnum, buf, @sp '-' @
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.
! and 919 all return the same file system error (error 2, ! FEInvalOp).
?PAGE "CANCEL ALL OUR OUTSTANDING I/O" ! This proc is called to cancel I/O posted but not completed. We ! use the io^posted flag in the control block to get the state of ! the I/O. ! This proc is called when one I/O in a transaction failed, either ! at initiation time or completion time. PROC cancel^outstanding^io (cb^list^head); INT .EXT cb^list^head (control^block^template); ! ptr to head of cb list BEGIN INT .EXT cb (control^block^template) := @cb^list^head; WHILE @cb <> nil^addr DO BEGIN IF cb.
?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.01 sec units) LIT anyfnum = -1; ! wait on any file INT fnum; ! used in call to awaitiox STR .
! 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 we can include it in the output record glo
! 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.
?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 .
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 .
?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. Before ! returning, the new cb is zero'd. DBL PROC get^control^block (cb^list^head); INT .
! 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. INITIALIZER calls procs local to this program to read the startup msg, save the ASSIGN msgs, and save the param msg.
! Verify that the ASSIGNs for msg log file, error log file, and ! trace file are present in our ASSIGN table.
! 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.
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.
! 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.pathmon^system^and^process^name [len] = " " OR cb.
! 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^req^buf, $LEN (pathsrv^request^template), $LEN (pathsrv^reply^template), , ! actual reply len for waited I/O only ! timeout, flags, ^ScSendOpNum, @cb !tag! ); IF error = FEok !0! THEN ! successfully initiated the Pathsend send BEGIN cb.
?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.
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.
?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 .EXT cb (control^block^template) := @cb^list^head; WHILE @cb <> nil^addr DO BEGIN IF cb.
! 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.
! Store non-Pathsend error messages generated by this program out^buf.non^send^error^msg ':=' global^non^pathsend^error^msg FOR $OCCURS (out^buf.
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 one transaction.
! 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.
INT fnum; STR .buf; 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.
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.
! 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.
?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 .
?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 .
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.
?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 .
?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 DO BEGIN IF input^rec.
BEGIN logical^name ':=' input^rec.server^request[i].pathmon^assign^name FOR $OCCURS (input^rec.server^request.
?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].
! 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 ':=' "INITIATED WRITE TO MESSAGE-LOG-FILE" -> @s
?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. ! If we fail to execute the transaction and the error is retryable, ! we retry it MAX-RETRIES times, where MAX-RETRIES is a param msg ! defined at the TACL prompt. PROC breq^program MAIN; BEGIN STRUCT .
! Besides validating the input record, the validate routine ! looks up ASSIGN names for PATHMON system and process names Pathsend Requester Example 179
! 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.
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); ! end of file input file CALL CALL CALL CALL 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 Nested Server Example Example 4 (page 182), PATHSRV, is a context-free nested server coded in COB
Example 4 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.
SELECT MESSAGE-IN-FILE ASSIGN TO $RECEIVE FILE STATUS IS WS-FILE-STATUS. SELECT MESSAGE-OUT-FILE ASSIGN TO $RECEIVE FILE STATUS IS WS-FILE-STATUS. SELECT ERROR-LOG-FILE ASSIGN TO "ERRORLOG" ORGANIZATION IS SEQUENTIAL ACCESS IS SEQUENTIAL FILE STATUS IS WS-FILE-STATUS. RECEIVE-CONTROL. TABLE OCCURS 10 TIMES SYNCDEPTH 1. / DATA DIVISION. FILE SECTION. FD MESSAGE-IN-FILE DATA RECORD IS PATHSRV-REQUEST. 01 PATHSRV-REQUEST. 03 SUBSIDIARY-SERVER. 05 PATHMON-ASSIGN-NAME PIC X(31).
DATA RECORD IS ERROR-LOG-REC. 01 ERROR-LOG-REC PIC X(132). WORKING-STORAGE SECTION. 01 WS-FILE-STATUS PIC X(2) VALUE ZERO. 88 WS-CLOSE-FROM-REQUESTER VALUE "10". 01 WS-FILE-SYSTEM-ERROR-MESSAGE. 03 FILLER PIC X(25) VALUE "FILE SYSTEM ERROR. FILE: ". 03 WS-LOGICAL-FILE-NAME PIC X(31). 03 FILLER PIC X(13) VALUE "FILE STATUS: ". 03 WS-FILE-STATUS-ERROR-MESSAGE PIC 99. 01 WS-NUMERIC-DISPLAY * * * * * * YOU CAN USE THE FOLLOWING WS-ASSIGN TABLE TO STORE UP TO FIFTY ASSIGNS.
* THE FOLLOWING PARAMETERS ARE USED IN A CALL TO SERVERCLASS_SEND_. 01 WS-SERVERCLASS-SEND-PARAM. 03 WS-ERROR 03 WS-PATHMON-PROCESS-NAME 03 WS-PATHMON-PROCESS-NAME-LEN 03 WS-SERVER-CLASS-NAME 03 WS-SERVER-CLASS-NAME-LEN 03 WS-MESSAGE-BUFFER 03 WS-REQUEST-LEN 03 WS-MAXIMUM-REPLY-LEN 03 WS-ACTUAL-REPLY-LEN 03 WS-TIMEOUT * S9(4) COMP VALUE X(15). S9(4) COMP VALUE X(15). S9(4) COMP VALUE X(300). S9(4) COMP VALUE S9(4) COMP VALUE S9(4) COMP. S9(9) COMP VALUE ZERO. 15. 15. 63. 300. 12000.
* * * 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. 03 WS-PROCESS-ID-NETWORK REDEFINES WS-PROCESS-ID-GENERIC. 05 WS-BACKSLASH PIC X.
* * * * * 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 SUBSIDIARY-REQUEST. 03 SUBSIDIARY-SERVER. 05 PATHMON-ASSIGN-NAME 05 PATHMON-SYSTEM-AND-PROCESS 05 SERVER-CLASS 01 SUBSIDIARY-REPLY. 03 REPLY-CODE 03 THIS-SERVER.
* * * * 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.
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. MOVE MOVE MOVE MOVE SPACES TO PATHSRV-REPLY.
* * * * * * 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.
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.
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. 0420-GET-MOM-SYSTEM-PROCESS.
IF WS-LOCAL OF WS-MOM-PROCESS MOVE WS-PROCESS-ID OF WS-PROCESS-ID-LOCAL OF WS-MOM-PROCESS TO WS-PROCESS-NAME OF WS-MOM-PROCESS ELSE 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 " " ".
* THIS PARAGRAPH PERFORMS THE PATHSEND SEND TO THE SUBSIDIARY SERVER MOVE "N" TO WS-SERVERCLASS-SEND-OKAY. MOVE SERVER-CLASS OF PATHSRV-REQUEST TO WS-SERVER-CLASS-NAME OF WS-SERVERCLASS-SEND-PARAM. MOVE SUBSIDIARY-REQUEST TO WS-MESSAGE-BUFFER OF WS-SERVERCLASS-SEND-PARAM.
* * THIS PARAGRAPH CALLS SERVERCLASS_SEND_INFO_ TO GET THE PATHSEND ERROR NUMBER AND TO GET THE FILE SYSTEM ERROR NUMBER. ENTER TAL "SERVERCLASS_SEND_INFO_" USING WS-PATHSEND-ERROR OF WS-SERVERCLASS-SEND-INFO-PARAM WS-FILE-SYSTEM-ERROR OF WS-SERVERCLASS-SEND-INFO-PARAM GIVING WS-ERROR OF WS-SERVERCLASS-SEND-INFO-PARAM.
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 MOVE "SERVERCLASS_SEND_ TIMED OUT
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/iTS SCREEN COBOL Reference Manual. $RECEIVE A special Guardian file name through which a process receives and optionally replies to messages from other processes by using Guardian procedure calls. This file is analogous to a request queue defined for a NonStop Tuxedo server.
batch processing A method of transaction processing in which transactions are first grouped together and then processed at regular intervals. See also online transaction processing (OLTP). block mode A terminal operating mode in which data is read from the terminal and displayed on the terminal one screen at a time. See also conversational mode. cache A temporary storage buffer. cascading server A term formerly used for a nested server. See nested server.
configured TERM object A TERM object that is explicitly configured with an ADD TERM command. Such a TERM object exists until it is explicitly deleted. Names of configured TERM objects begin with a letter. See also temporary TERM object and TERM object. consistency. See database consistency. 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.
database consistency The state of a database in which items satisfy established criteria. For example, an account balance must equal credits to the balance minus debits to the balance. When the database satisfies these criteria, the database is considered to be consistent. In general, a database is consistent when it is accurate and all changes generated by transactions are complete.
Distributed Systems Management (DSM) A group of tools for managing a variety of subsystems in a distributed processing environment. 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.
external server See external process. external TCP See external process. fault tolerance The ability of a NonStop system to continue processing despite the failure of any single software or hardware component within the system. field-characteristic clause In SCREEN COBOL, an ordered set of characters that specify the characteristics of a screen field. file identifier (file ID) In the Guardian environment, the portion of a file name following the subvolume name.
HP NonStop Remote Server Call/MP (RSC/MP) An HP software product that facilitates client/server computing, allowing personal computer (PC) or workstation applications running under Microsoft Windows software or the MS-DOS or OS/2 operating system to access Pathway server classes and Guardian processes.
library A set of related files or common files that can be accessed by multiple programs or processes. linear expandability See scalability link 1. 2. An open of a server process within a server class.
modified data tag (MDT) In SCREEN COBOL, a bit that is set or reset to indicate whether data in an associated field is to be sent to the computer from the terminal. multithreaded A programming model that provides more than one thread of control within a program. Multithreading allows multiple sequential processing tasks to be executed concurrently within a process: for example, a terminal control process (TCP). See also thread and single-threaded.
OBEY command A command in a NonStop interactive interface, such as PATHCOM or the SCREEN COBOL Utility Program (SCUP), that allows users to execute the commands in a command file. See also command file. object An entity that is subject to independent reference or control by one or more subsystems. Examples of objects are devices, communications lines, processes, and files.
partially qualified file name A Guardian file name in which only the right-hand file-name parts are specified. The remaining parts of the file name assume default values. See also fully qualified file name. PATHCOM 1. 2. The interactive interface to the PATHMON process, through which users enter commands to configure and manage Pathway applications. The process that provides this interface.
Pathway environment See Pathway transaction processing environment Pathway management programming interface A set of programmatic commands that allow users to write management application programs that communicate directly with the PATHMON process for configuration and management. This interface is based on the Subsystem Programmatic Interface (SPI) within the Distributed Systems Management (DSM) software. Programmatic commands communicating with the PATHMON process use the Pathway subsystem ID.
Portable Transaction Application Language (pTAL) A machine-independent systems programming language based on TAL. The pTAL language excludes architecturespecific TAL constructs and includes new constructs that replace the architecturespecific constructs. See also Transaction Application Language (TAL). primary process The currently active process of a process pair in the Guardian environment. See also backup process and process pair. process 1. 2.
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. This header specifies the NonStop Tuxedo application service for which the message is destined, the NonStop Tuxedo buffer types of the request and reply messages as seen by the service, and options that modify the invocation of the service.
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. See also screen, base screen, and overlay screen. screen overlay area See overlay area.
static server A server process that the PATHMON process creates when a START SERVER command is issued. The PATHMON process starts the number of static servers defined by the NUMSTATIC attribute for the server class. See also dynamic server. Structured Query Language (SQL) A relational database language used to define, manipulate, and control databases.
tell message An informational message sent by PATHCOM or a management application to one or more terminals controlled by a SCREEN COBOL program, to be displayed for the terminal operators. TELL object A temporary object used in PATHCOM and SPI commands to define a tell message. temporary TERM object A TERM object created by the PATHMON process when a PATHCOM RUN PROGRAM command or an SPI START PROG command is issued.
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 RSC/MP product, that runs on a 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 A unique name that the TMF subsystem assigns to a transaction. transaction log See audit trail.
Index Symbols $RECEIVE messages allocating space, 63 determining new dialogs, 71 A Aborted dialog (error 929), 117 Aborted dialogs, detecting, 73 Aborted send operation (error 918), 114 Aborted transaction (error 934), 118 Aborting transactions, 34, 46, 143 ABORTTRANSACTION procedure, 66 Access Control Server (ACS), 58 Application generator, Pathmaker, 26 Application Transaction Monitor Interface (ATMI), 60 Applications, designing batch processing , 50 database , 34, 35 example, OLTP, 29, 34 requester prog
invoking Pathsend procedures, 76 Code, standardizing and testing, 18 Colon, in Pathsend procedure parameters, 76 Common Run-Time Environment (CRE), 63 Concurrent processing, 33, 34, 65 Condition code considerations, 103 register, 76 Context-free servers, using with context-sensitive requesters, 59, 64 Context-sensitive programming, requesters ACS restart, 60 canceling server-class sends, 60 failure recovery, 59, 60 overview, 58 resource utilization, 59 using with context-free servers, 59, 64 Context-sensiti
FEPathDown (error 201), 111 FESecViol (error 48), 111 FETimeout (error 40), 110 FETimeout (error 440), 111 Requesting process has no… (error 75), 66 timeout error (error 40), 69, 70 Event Management Service (EMS), 18 Examples nested server program, 181, 196 Pathsend requester program, 129, 181 Extended BASIC, for Pathway servers, 21 Extended General Device Support (GDSX) processes, 23, 40, 42, 46 F Failure recovery context-sensitive requesters, 59, 60 fault-tolerant programming requesters, 56, 57 servers,
cancel outstanding, example, 146 complete outstanding, example, 147 starting example, 140 IDS See Intelligent device support (IDS), 29 Industrial robots, 40 Input file structure example, 134 Inspect product , 25 Intelligent device support (IDS) , 36 description, 37 GDSX programming for, 41 overview , 21 RSC requesters , 24, 40 Intelligent mode, 36 Interoperation of Pathsend requesters with NonStop TUXEDO servers, 25 of Pathway servers with NonStop TUXEDO requesters (clients), 25 with NonStop TUXEDO requeste
fault-tolerant servers, 68 grouping transaction operations, 67, 68 limits, 128 Pathmaker software, 26 Pathsend procedure calls, 56 record locking, 67 requester example, 129, 181 retryable operations, 66 server application structure, 65, 66 server class violation (error 917), 114 server process pairs, 46 TMF OFF server parameter, 56 transaction deadlocks, 69 usage considerations, 104 writing servers to use, 65, 69 NonStop Transaction Services/MP (NonStop TS/MP) product, 7, 16, 18 NonStop TUXEDO applications,
See also Server classes; Server processes; Server programs; Applications, programming; Applications, designing, 16 Pathway to TUXEDO translation server, 25, 61 Pathway/TS product, 7, 16, 18 Performance provided by Pathsend requesters, 22 provided by Pathway applications, 20 provided by server processes, 21 Personal computer support, 40 PFS use error (error 920), 115 POET (Pathway Open Environment Toolkit) product, 18, 24, 40 Portable Transaction Application Language See pTAL, 16 POS (point-of-sale) devices,
procedure calls,list of, 75 retryable requests, 57 security issues, 57, 58 server process failures, 53 sharing servers, 62 TMF subsystem, 56 using ASSIGNs, 58 Requesting process has no… (error 75), 66 Resource utilization, 59 Response time, 20 Retry mechanism, Pathsend calls, 56 See also Fault tolerance, 16 Retryable requests, Pathsend, 57 Retryable server operations, TMF, 66 Return errors, 109 Robots, industrial, 40 RSC (Remote Server Call) role in Pathway environment, 24, 40 security issues, 58 server pro
TMF considerations, 104 waited considerations, 103, 107 SERVERCLASS_SEND_INFO_ procedure example, 144, 185, 194 overview , 53 syntax and usage, 101, 102, 103 SERVERCLASS_SENDL_ procedure retaining concurrent sends limit, 101 retaining concurrent sends limits, 101 syntax and usage, 98, 101 Servers canceling sends to server classes, 60 context-sensitive errors returned, 72 functions of, 71 context-sensitive requesters, using, 59, 64 conversational (context-sensitive), 62 creation failure (error 916), 114 debu
Too many dialogs (error 927), 117 Too many Pathmons (error 921), 115 Too many requesters (error 925), 116 Too many send requests (error 924), 116 Too many server classes (error 922), 115 Too many server links (error 923), 116 Tools, software development, 25, 26 tpinit() ATMI function, 61 Transaction Application Language See TAL, 16 Transaction identifiers and LINKMON processes, 104 Transaction Management Facility See TMF, 16 Transaction processing See OLTP, 16 Transaction processing scenario, 26, 28 Transac
