HP NonStop TS/MP 2.5 Pathsend and Server Programming Manual HP Part Number: 679666-002 Published: May 2012 Edition: J06.11 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......................................................................................................42 Design Considerations........................................................................................................42 Server Program Structure.....................................................................................................46 Designing Applications for Batch Processing..............................................................................
Handling ACS Subsystem Failures........................................................................................73 Writing Pathway Servers That Interoperate With NonStop Tuxedo Requestors..................................73 5 Pathsend Procedure Call Reference.............................................................74 Calls From C or C++...............................................................................................................75 Calls From COBOL85..............................
Server-Class Send Operation Number................................................................................110 Timeout Considerations for Pathsend Programming...............................................................111 Bridging Pathsend API into Pathway Domain........................................................................113 Retaining Concurrent Sends Limit........................................................................................114 6 Pathsend Errors.....................
About This Manual This manual describes how to write two types of programs as part of a Pathway application: requestor programs that use the Pathsend Application Program Interface (API) and server programs that service requests from all types of Pathway requestors. This chapter 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.
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 requestor programs using SCREEN COBOL. • Guardian Programmer’s Guide. This guide provides information about programming in the Guardian environment, including use of the Guardian procedure calls.
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. This manual describes system messages. For each message, the manual provides an explanation of the cause, a discussion of the effect on the system, and suggestions for corrective action.
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 chapter about application availability in the Pathway transaction processing environment. • Guardian Programmer’s Guide.
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 := FILENAME_COMPARE_ (filename1:length !i:i , filename2:length ) ; !i:i !o:i In procedure calls, the !o:i notation follows an output buffer parameter that has a corresponding input parameter specifying the maximum length of the output buffer in bytes. For example: error := FILE_GETINFO_ ( !i filenum , [ filename:maxlen ] ) ; !o:i Notation for Messages This list summarizes the notation conventions for the presentation of displayed messages in this manual.
% Percent Sign A percent sign precedes a number that is not in decimal notation. The % notation precedes an octal number. The %B notation precedes a binary number. The %B notation precedes a binary number. The %H notation precedes a hexadecimal number. For example: %005400 %B101111 %H2F P=%p-register E=%e-register Document History Part Number Product Version Published 679666-001 NonStop TS/MP 2.5 February 2012 679666-002 NonStop TS/MP 2.
1 Introduction to Pathway Application Programming This chapter 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 Application types References Tasks Includes Pathsend requestors chapter 2, “Designing Your Application” (page 28) Design an application including Pathsend requestors chapter 3, “Writing Pathsend Requestors” (page 50) Write a Pathsend requestor program chapter 5, “Pathsend Procedure Call Reference” Look up the syntax of Pathsend procedures (page 74) Includes Pathway servers chapter 6, “Pathsend Errors” (page 115) Look up cause, effect, and recovery for error
transaction protection. (On NonStop system models earlier than the Himalaya systems, Pathway/iTS is packaged as part of the Pathway transaction processing system.) Used with or without TMF and Pathway/iTS, TS/MP provides a run-time Pathway environment to simplify your development efforts for scalable OLTP applications on a massively parallel processor architecture. • HP makes valuable application development tools and utilities available for the Pathway environment.
Data Integrity If your database is corrupted by a hardware or software failure, you might need weeks to isolate and then correct the problem. Because an inaccessible or inconsistent database can have a dramatic, adverse effect on business operations, HP developed the TMF subsystem, to ensure database consistency.
Other NonStop Fundamentals Besides data integrity and fault tolerance, the Pathway environment also provides the high performance and low cost, system security, scalability, and distributed processing of NonStop systems. High Performance and Low Cost The more transactions your system can process (preferably without degrading response time), the lower the cost of each transaction.
possibly accessing different resource managers (HP NonStop SQL/MP and Enscribe) is known as distributed transaction processing (DTP). Pathway Applications Pathway applications consist of two types of programs: requestor programs and server programs. This design allows application logic to be distributed near the resources it manages. For example, presentation services are located near terminal devices or workstations; database logic resides in server programs near that database.
• Based on configuration settings determined by the system manager or operator, the PATHMON process can dynamically create additional server processes within the server-class to maintain acceptable throughput as the workload increases. • By temporarily freezing and stopping the server-class, and changing configuration parameters, the system manager or operator can adjust the number of servers that are active at a time to suit response-time requirements.
You can use a GDSX as a front-end process to the TCP and SCREEN COBOL requestors to communicate with devices not directly supported by the TCP. Use of the GDSX product is described in the Extended General Device Support (GDSX) Manual. The Pathsend Environment The Pathsend environment includes Pathsend processes and ACS subsystem processes: • Pathsend processes, written as a part of your application, use Pathsend procedure calls to make requests to server-classes.
Figure 2 Pathsend Interprocess Communication Although you can obtain some information about ACS Subsystem processes through the PATHMON process (by means of PATHCOM or SPI), ACS Subsystem processes are not managed as PATHMON-controlled objects. For details about management of ACS Subsystem processes, see the NonStop TS/MP 2.5 Release Supplement Manual.
When using the NonStop Tuxedo system, you work in the NonStop Tuxedo programming environment; you need not use the requestor 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.
At your command, the Pathmaker product uses the information from the catalog and the TEDIT file to generate SCREEN COBOL requestor code, C or COBOL85 server code, and command files to configure and start the finished Pathway environment for testing. The Pathmaker product simplifies the creation of Pathway applications by: • Generating application code in an uniform structure for all requestors and servers, to help simplify maintenance and modification.
Figure 3 Example Application Using a Pathsend Requestor 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 ACS subsystem ROUT process by using NonStop Kernel interprocess communication. 10. The ACS subsystem ROUT process receives and forwards the reply messages to the Pathsend requestor and 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 requestor programs and server programs. This chapter describes the design of transactions and databases for Pathway applications and the design of requestor 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 requestor program. Figure 6 (page 32) illustrates the use of the TMF subsystem by a Pathsend requestor 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 might 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.
• The Pathsend procedure calls • The RSC/MP product, with or without the POET • The GDSX product In Table 3 (page 35), key technical and business considerations are mapped to each way of accessing Pathway servers. More information about each approach is provided after the table.
SCREEN COBOL requestors that employ the IDS facility within the TCP send data back and forth between the Working-Storage Section and an intelligent device (or a front-end process that controls the device) by way of message templates defined in the Message Section. IDS requestors use SCREEN COBOL SEND MESSAGE statements and their associated REPLY clauses in the Procedure Division to interact with the intelligent devices or front-end processes.
The Pathsend procedures and the ACS subsystem processes do not support the checkpointing of Guardian interprocess message synchronization IDs. This lack of checkpointing support is an important consideration when writing fault-tolerant requestor programs that do not use the TMF subsystem. chapter 3, “Writing Pathsend Requestors” (page 50), provides more information about writing fault-tolerant Pathsend programs.
Example 1 Sample Pathsend Requestor 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 might 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 requestor, 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 43), under “Designing Server Programs” (page 42), later in this chapter.
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 requestor 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 requestor can commit the transaction. In the second case, the requestor can commit the transaction and then retry it.
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, see the Extended General Device Support (GDSX) Manual. Server Program Structure Example 2 (page 47) illustrates the structure of a single-function server program written in COBOL85.
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-requestor-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 Requestors This chapter explains how to write programs that use Pathsend procedure calls to make requests to Pathway servers. These programs can be either one of the following: • Standard requestors—programs that initiate application requests • Nested servers—servers which act as requestors by making requests to servers in other server-classes Nested servers are described further in chapter 4, “Writing Pathway Servers” (page 61).
Later parts of this chapter describe how to use these procedures in context-free and context-sensitive Pathsend programs. chapter 5, “Pathsend Procedure Call Reference” (page 74), gives detailed syntax and usage considerations for the procedures. Interprocess Communication in the Pathsend Environment Communication between requestors and servers in the Pathsend environment differs from the communication between Guardian requestors and servers.
The SERVERCLASS_SEND_ procedure enables Pathsend requestors to send data to and receive replies from a specified Pathway server-class. This procedure communicates with the ACS subsystem ROUT process in the processor where the Pathsend requestor is running, passing information that enables the ACS subsystem processes to choose a link to a server process. After a link to the server has been obtained, the requestor’s data is sent directly from the requestor’s data space to the server.
ACS Subsystem Limit Errors In some cases, you can recover from an ACS Subsystem 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 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.
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 2.5 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. You can set up security validation by creating an access control server (ACS).
To participate in a dialog with a context-sensitive Pathway requestor, a server must perform additional tasks besides those required of all servers. These additional tasks are described under “Writing Context-Sensitive Servers” (page 69) in chapter 4. Using Context-Sensitive Requestors With Context-Free Servers Context-sensitive requestors 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 requestor must abort the transaction when it receives an error reply.
To communicate directly with a NonStop Tuxedo server by calling the ATMI functions, a Pathsend requestor 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 requestor 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 chapter explains how to write server programs that service requests from Pathway requestors. Such requestors can be Pathsend requestors, SCREEN COBOL requestors, or clients that use the RSC/MP product or the POET product. Pathsend requestors are described in this manual. SCREEN COBOL requestors 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 ACS Subsystem ROUT processes open of the server process is shared among all the Pathsend requestor processes running in the same processor as that of the ACS subsystem ROUT process. Therefore, a close does not necessarily occur when the communication with a particular requestor process is finished. Server Stop Protocol A Pathway server must stop itself when the ACS subsystem ROUT process or the TCP closes it on behalf of the last requestor that has a link to it.
The default value for MAXLINKS is an unlimited number of links. To avoid this problem, MAXLINKS must be set to a value. The error returned to a Pathsend requestor is error 905 (FEScNoServerLinkAvailable) or 923 (FEScTooManyServerLinks). The error returned to a SCREEN COBOL requestor is error 4 (link denied). Considerations for Servers Used With SCREEN COBOL Requestors SCREEN COBOL requestors require that the first two bytes of a server reply message contain an integer reply-code value.
requestors. 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 69) later in this chapter.
out. To ensure transaction backout, the server must call the ABORTTRANSACTION procedure after reading the server request and before sending a reply. A call to ABORTTRANSACTION by the server does not end the transaction—only the requestor can end it—but such a call imposes the requirement that the requestor also call ABORTTRANSACTION, rather than ENDTRANSACTION, after the reply of the requestor.
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. It is self-defeating to designate the log file as an audited file; the message that caused the failure would be backed out.
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 must be a TMF transaction.
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. • Implicit locks are held for inserted records. • Locks are held until the transaction is either committed or aborted and backed out. The increased locking could cause new possibilities for transaction deadlock.
When Pathsend error 915 or a SEND error with TERMINATION-STATUS 12 occurs with a timeout error during server debugging, use the PATHCOM STATUS PATHMON command to find the server-classes that are in the LOCKED state. Identify the server program file for each locked server-class, and issue the TACL command STATUS *, PROG object-file-name to list all running processes. Stop these processes by using the TACL STOP command.
Functions of a Context-Sensitive Server In addition to the functions performed by all Pathway servers, a context-sensitive server must: • Detect a newly established dialog • Receive, service, and reply to messages associated with a dialog • Correlate messages with a dialog • Continue a dialog • Terminate a dialog • Abort a dialog • Detect an aborted dialog It is simpler to code a context-sensitive server if you allow only one dialog at a time.
3. 4. 5. Checks the value of bit 14 of the dialog flags if the TMF subsystem is being used, the server is enforcing transaction commit protection during the dialog, and the value of bits <12:13> of the dialog flags is 1 (first message in a new dialog). If the value of bit 14 is 1, aborts the dialog by replying with FEEOF (1). Processes the message and performs the requested services. Issues a reply by using the $RECEIVE writing mechanism of the language, such as a call to the REPLY or REPLYX procedure.
When the one-transaction-per-dialog model is used, the transaction is automatically aborted when the server returns an error value (FEEOF, or any other value besides FEOK or FEContinue) in the reply. When the any-transaction-per-dialog model is used (when bit 14 of the dialog flags is equal to 1), no automatic transaction abort occurs. In either case, the requestor aborts the transaction when it receives an error reply.
It is also possible to get Pathsend dialog abort messages that do not represent actual aborted dialogs. A server can receive such a message if the requestor calls SERVERCLASS_DIALOG_BEGIN_ and then cancels the message. In that case, the ACS subsystem ROUT process sends the Pathsend dialog abort message even though the server might not have received the first message in the dialog.
5 Pathsend Procedure Call Reference Pathsend programs use six procedures that are part of the Guardian procedure library. This chapter 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.
servers. The SERVERCLASS_SEND_INFO_ procedure is used to obtain information about both context-free and context-sensitive requests. The method for accessing these procedures from a Pathsend program depends on the programming language you use. You can write Pathsend programs in C, C++, COBOL85, Pascal, pTAL, or TAL. The topics that follow explain how to call the Pathsend procedures from each of the supported programming languages.
Calls From COBOL85 To invoke any of the procedures from within a COBOL85 program, you must execute a statement of this form: ENTER "SERVERCLASS_SEND_" USING pathmon-process-name pathmon-process-name-len server-class-name server-class-name-len message-buffer request-len maximum-reply-len actual-reply-len timeout flags scsend-op-num tag 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, time
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 earlier in your data declarations. The types of these variables must be the Pascal types that correspond to the TAL variable types specified in the Pathsend procedure-call description later in this chapter.
error returned value INT returns an error word containing one of these values: 0 (FEOK) indicates that the call was successful. 23 (FESCErr) indicates that an error occurred. You can call the SERVERCLASS_SEND_INFO_ procedure to get detailed 3 information about the error. nl dialog-id input INT(32):value is the dialog identifier previously returned from the SERVERCLASS_DIALOG_BEGIN_ call that began the dialog. This is a mandatory parameter.
,[ scsend-op-num ] ,[ tag ] ); error ! o ! i returned value INT returns an error word containing one of these values: 0 (FEOK) indicates that the call was successful and the server has ended the dialog. 70 (FEContinue) indicates that the call was successful and the server is ready for the next message in the dialog. 233 (FESCErr) indicates that an error occurred. You can call the SERVERCLASS_SEND_INFO_ procedure to get detailed information about the error.
This is a mandatory parameter. request-len input INT:value is the byte length of the data contained in message-buffer. The range of acceptable values is 0 through 32767 bytes. This 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 through 32767 bytes.
When this bit is set to 0, the TMF subsystem treats a dialog like an I/O operation: the ENDTRANSACTION operation fails until the dialog has finished. The same restriction applies to a nested server (a server that receives a request and then becomes a requestor to other servers): if a server receives a message in a dialog and then initiates a dialog with another server, it must complete the entire initiated dialog before replying to the message from the received dialog.
The completion of this processing that is, getting the final outcome (success or failure) and, if successful, the reply data occurs in one of the two ways, depending on whether the send operation is initiated as waited or nowait: • For waited send operations, initiation and completion are both performed by the SERVERCLASS_DIALOG_BEGINL_ procedure.
The process name portion can have up to five characters after the dollar sign ($) if it is a local process name, and up to four characters after the $ sign if it is a process on a remote system. The name cannot include an optional first or second name qualifier. Name must be left justified in the buffer, and can contain trailing blanks. The domain name portion can have a maximum of eight and minimum of two characters. It must begin with a ‘%’ sign and can contain alphanumeric characters.
If there is an outstanding I/O operation to a server process when a SERVERCLASS_DIALOG_BEGINL_ operation times out, the I/O operation is canceled. For details about timeout for waited and nowait operations, see “Timeout Considerations for Pathsend Programming” (page 111) later in this chapter. For more information about Pathsend error 904 and file-system error 40, see “Server Timeout” (page 111). flags input INT:value flags.<15> flags.
Considerations • HP recommends that no-waited IOs initiated by SERVERCLASS_DIALOG_BEGINL_ must be completed by a call to AWAITIOXL. If the message size is less than or equal to 32KB, AWAITIOX can also be used. • If both the read-write buffers used in the call are 2 MB in size, you might be able to do only 7 concurrent no-waited calls, instead of 255.
The completion of this processing that is, getting the final outcome (success or failure) and, if successful, the reply data occurs in one of the two ways, depending on whether the send operation is initiated as waited or nowait: • For waited send operations, initiation and completion are both performed by the SERVERCLASS_DIALOG_SEND_ procedure. • For nowait send operations, initiation is performed by the SERVERCLASS_DIALOG_SEND_ procedure, and completion is performed by the AWAITIOX procedure.
This is a mandatory parameter. request-len input INT:value is the byte length of the data contained in message-buffer. The range of acceptable values is 0 through 32767 bytes. This 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 through 32767 bytes.
nowait sends, and in calls to FILEINFO for waited and nowait sends, to indicate that the calls refer to server-class send operations. The value of scsend-op-num is determined on the first 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.
Syntax The syntax of the SERVERCLASS_DIALOG_SENDL_ procedure is: error := SERVERCLASS_DIALOG_SENDL:_ ( dialog-id ,message-buffer, [reply-buffer] ,request-len ,maximum-reply-len ,[ actual-reply-len ] ,[ timeout ] ,[ flags ] ,[ scsend-op-num ] ,[ tag ] ); ! ! ! ! ! ! ! ! ! ! i i,o o i i o i i o i returned value error INT returns an error word containing one of these values: 0 (FEOK) indicates that the call was successful and the server has ended the dialog.
This is a mandatory parameter. maximum-reply-len input 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. This is a mandatory parameter. 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. The return value of this parameter is 0 if nowait I/O is used.
parameter to identify multiple nowait I/O operations. For waited I/O, this parameter is not used and can be omitted. The default is 0F. Considerations • HP recommends that no-waited IOs initiated by SERVERCLASS_DIALOG_SENDL_ must be completed by a call to AWAITIOXL. If the message size is less than or equal to 32KB, AWAITIOX can also be used. • If both the read-write buffers used in the call are 2MB in size, you might be able to do only 7 concurrent no-waited calls, instead of 255.
233 (FESCErr) indicates that an error occurred. You can call the SERVERCLASS_SEND_INFO_ procedure to get 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). OR is the pathway domain name, whose member PATHMON processes have the server-class configured under them (for example, %DOM, %DOM1).
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 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 requestor in the call to this procedure.
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 110) later in this chapter. 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.
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 is the pathway domain name, whose member PATHMON processes have the server-class configured under them (for example, %DOM, %DOM1).
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. This is a mandatory parameter. 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 108). If both the read-write buffers used in the call are 2MB in size, you might be able to do only 7 concurrent no-waited calls, instead of 255.
SERVERCLASS_SENDL64_ Procedure The SERVERCLASS_SENDL64_ procedure initiates a context-free send operation to a server process in the specified server-class. The completion of this processing receives the final outcome (success or failure). If successful, the reply data occurs in one of the following ways, depending on whether the send operation is initiated as waited or nowait: • SERVERCLASS_SENDL64_ procedure performs initiation and completion for waited send operations.
name cannot include an optional first or second name qualifier. The name must be left justified in the buffer, and can contain trailing blanks. The domain name portion can have minimum two and a maximum of eight characters. It must begin with a ‘%’ sign and can contain alphanumeric characters. Also, special characters, ‘-‘ and ‘_’ are allowed. Since Pathway domain is a logical entity, it cannot be qualified by the node name. This is a mandatory parameter.
returns a count of the number of bytes returned by the server process reply. This parameter is for waited I/O only and can be excluded 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 FILE_AWAITIO64_. timeout input INT(32):value specifies the maximum amount of time, in hundredths of a second, the ACS subsystem ROUT process waits for completion of this send. This value must be either -1D or a value greater than 0D.
The procedure identifies the server-class for the system and returns a dialog identifier for subsequent dialog operations. A SERVERCLASS_DIALOG_BEGINL64_ call must be matched by a SERVERCLASS_DIALOG_ABORT_ or SERVERCLASS_DIALOG_END_ call at the end of the dialog.
contains the external Guardian process name of the PATHMON process controlling the server-class (for example, $PM or \AB.$PMN). OR is the pathway domain name, whose member PATHMON processes have the server-class configured under them (for example, %DOM, %DOM1). The process name portion can have up to five characters after the dollar sign ($), if it is a local process name, and up to four characters after the $ sign if it is a process on a remote system.
This is a mandatory parameter. actual-reply-len output INT(32).EXT64 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 excluded 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 FILE_AWAITIO64_.
returns the server-class send operation number. You can use the server-class send operation number in place of the file-number parameter in calls to CANCEL, CANCELREQ, FILEINFO, and FILE_AWAITIO64_ for nowait sends, and in calls to FILEINFO for waited sends, to indicate that the calls refer to server-class send operations. The value of scsend-op-num is determined on the first successfully initiated nowait send. This value is returned on every subsequent nowait send that is initiated successfully.
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. 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_INFO64_ procedure to get detailed information about the error.
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 excluded 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 FILE_AWAITIO64_. timeout input INT(32):value specifies the maximum amount of time, in hundredths of a second, that the ACS subsystem ROUT process waits for the completion of this send.
this feature has been overridden by setting the flags.<14> bit to 1 in the call to SERVERCLASS_DIALOG_BEGINL64_. • The send fails if there is already an outstanding send in the dialog from a previous nowait call to this procedure. For additional considerations, see “Usage Considerations for Pathsend Procedures” (page 108).
22 (FEBoundsErr) is returned if a reference parameter is out of bounds. 29 (FEMissParam) is returned if a required parameter is missing. These errors are programming errors. pathsend-error output INT:ref:1 returns the Pathsend error. For more details on Pathsend errors, see chapter 6 “Pathsend Errors” (page 115). file-system-error output INT:EXT64:ref:1 returns the file system error. For more details on file system errors, see the Guardian Procedure Errors and Messages Manual.
Waited I/O These considerations apply to waited Pathsend procedure calls: • The tag parameter has no meaning and can be omitted. • On a successful completion of a waited Pathsend procedure call, the actual-reply-len parameter indicates the number of bytes in the reply. For an example of issuing a waited call to SERVERCLASS_SEND_, see the Pathsend server program example PATHSRV, Example 4 (page 188).
See the NonStop TS/MP 2.5 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). The same value is returned on every subsequent nowait send that is initiated successfully.
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 subchapters, 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.
NOTE: • If a PATHMON is configured under multiple Pathway domains, then the Pathsends issued with that PATHMON name in the Pathsend API are treated as a domain send for the Pathway domain, which is configured last in the ACSCTL file having that PATHMON as a member. If you want the Pathsend request to be served by a particular Pathway domain, then you must use the Pathway domain name in the Pathsend APIs. • For more information about TS/MP 2.5 and later versions, see the TS/MP 2.
6 Pathsend Errors This chapter 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 2.5 System Management Manual for a description of the correct syntax for server-class names. 901 FEScInvalidPathmonName Cause.
• Error 48 (FESecViol) indicates there is a security violation. For information about network and server-class security, see chapter 3, “Writing Pathsend Requestors” (page 50),. • 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 ACS Subsystem processes has no links to the server-class and is 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 ACS Subsystem 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. For more information, see the procedure call syntax description. 920 FEScPFSUseError Cause. The caller process file segment (PFS) cannot be accessed.
923 FEScTooManyServerLinks Cause. The ACS Subsystem ROUT process already has the maximum number of concurrent links to server processes allowed for all PATHMON processes. The maximum number is 8191. 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 requestor cannot start a new dialog, because it already has the maximum number of dialogs open. The maximum number of dialogs per requestor 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 requestor 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 has 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.
For information about limits for the ACS Subsystem processes , see “ACS Subsystem Limit Errors” (page 53) and also NonStop TS/MP 2.5 System Management Manual. 964 FEScAPINotSupported Cause. The Pathsend API is not supported on this RVU. Typical file-system error will be 0 (FEOK). Any other file-system error indicates that the API failed to determine the RVU. Effect. The send initiation fails with an error. Recovery. Verify that the RVU supports the invoked API.
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. For more information, see the TS/MP Pathsend and Server Programming Manual. 902: FEScPathmonConnect Cause.
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 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 is 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 is denied for one of the following 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 process file segment (PFS) cannot be accessed.
This error can also occur when the ACS subsystem processes in a CPU fail and the Pathsend requestors on that CPU continue running. When ACS subsystem processes fail, the Pathsend requestors in the CPU does not terminate automatically. Therefore, some of the requestors might be in an inconsistent state and might continue to receive this error for dialog-based send initiations. This can occur even after the ACS subsystem processes are restarted on the CPU. Typical file-system error: 0 (FEOK). Effect.
933: FEScDialogOutstanding Cause. A call to SERVERCLASS_DIALOG_END_ is 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 is aborted. Typical file-system error: 0 (FEOK). Effect. The procedure initiation fails with an error.
A TS/MP Limits for Pathsend Requestors Table 6 (page 134) lists the TS/MP product limits that apply to the Pathsend programming environment. For limits related to the configuration of a PATHMON environment, see the NonStop TS/MP 2.5 System Management Manual.
B Examples This appendix illustrates 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 requestor coded in TAL • A context-free Pathsend nested server example coded in COBOL85 Edit files which contain the source code for these examples are provided on the site update tape (SUT).
Example 3 Context-Free Pathsend Requestor Program ?PAGE "BROADCAST Requestor (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 might be referenced in the input record.
?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-class Errors. PATHSEND has ! error numbers 900 - 950 reserved. ! LITERAL FEScFirstError = 900, ! First avail. PATHSEND Error. FEScInvalidServerClassName = 900, ! Invalid server-class name. FEScInvalidPathmonName = 901, ! Invalid Pathmon process name. FEScPathmonConnect = 902, ! Error with Pathmon ! connection (eg. Open, I/O, ! etc.). FEScPathmonMessage = 903, ! Unknown message received from ! PATHMON.
! requestors 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 for error circumstances, must not happen. ABENDing, a procedure will call to the home terminal. This proc conditions that, under normal In these cases, before this procedure to write a message 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 might 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 Requestor Example 185
! 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 188), 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-Requestor 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.
* * * * Requestor 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 Requestor 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 MUST 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 MUST 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 Requestor 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, see 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.
Application-Transaction Monitor Interface (ATMI) The application programming interface to the System/T transaction monitor in a NonStop Tuxedo system. This interface includes transaction routines, message handling routines, service interface routines, and buffer-management routines. assignment The use of an ASSIGN command to make logical file assignments for programs in the Guardian environment.
client and handle database input and output functions. Interprocess communication (IPC) messages transfer data between client and server. COBOL85 The HP compiler and run-time support for the American National Standards Institute (ANSI) programming language COBOL, X.3.23-1985. Pathway server processes are often written in this language. cold start The operation that starts a PATHMON environment for the first time.
monitor until the application dialog is completed. Multiple messages can be exchanged between the client and server participating in the communication. See also conversational server. conversational model A model for requestor-server communication that enables an ongoing dialog between a client (or requestor) and a server. Multiple messages can be exchanged between the client and server process before control is returned to the transaction monitor. See also request/response model and conversational server.
definition files A set of files containing data declarations for items related to SPI messages and their processing. The core definitions required to use SPI are provided in a DDL file and in several language-specific definition files, one for each programming language that supports SPI. The HP DDL compiler generates the language-specific files from the DDL file. Subsystems that support SPI provide additional definition files containing subsystem-specific definitions.
Enable product A tool provided by HP that allows users to develop simple data management applications without using a conventional programming language. The Enable product can generate SCREEN COBOL programs for use with Enscribe databases. Enscribe database record manager HP database management software that provides a record-at-a-time interface between servers and a distributed database. See also NonStop SQL/MP.
file-name expansion The expansion of a partially qualified Guardian file name for a disk file to include the associated node, volume, and subvolume names. fixed-function terminal A nonintelligent device (that is, a device without processing ability) capable of sending and receiving information over communications lines. Fixed-function terminals are often referred to as dumb terminals. freeze condition A condition in which communication between a terminal and a server-class is prohibited.
HP Tandem Advanced Command Language (TACL) The user interface to the NonStop Kernel in the Guardian environment. The TACL product is both a command interpreter and a command language. I/O process In the Guardian environment, a system process to manage input/output devices. Applications use the Guardian file system to send requests to I/O processes. See also file system. IDS See intelligent device support (IDS) facility.
link manager A process that requests links to server processes and provides link access after the link is granted. TCPs and ACS Subsystem processes are the link managers in the Pathway environment. See also link access and link granting. lock A mechanism that coordinates access to the same data; locks are either shared or exclusive. log file See PATHMON log file and event log file. low PIN A process identification number (PIN) in the range 0 through 255.
nondedicated device A term formerly used for a terminal or other input/output device on which a Pathway application could be started from PATHCOM with a RUN PROGRAM command. The RUN PROGRAM command results in the creation of a temporary TERM object to control the terminal. (No new term replaces this term; instead, the manual text now refers to such devices as those associated with temporary TERM objects.) See also dedicated device and temporary TERM object.
PATHMON, PATHWAY, ACS Subsystem, SERVER, TCP, TERM, PROGRAM, and TELL. The SPI interface to the Pathway subsystem uses different names for some of these object types and defines additional object types; for example, PM, LM, PROGTERM, and TCPTERM are object types in the SPI interface. OLTP See online transaction processing (OLTP). OLTP application See online transaction processing (OLTP) application.
PATHMON log file A file used by a PATHMON process for reporting errors and changes in status. PATHMON object An object of type PATHMON; that is, a PATHMON process. See also PATHMON process and PATHMON-controlled object. PATHMON process The central controlling process in the Pathway environment.
Pathway server A server process or program in the Pathway transaction processing environment. See also NonStop Tuxedo server. Pathway subsystem The PATHMON environment components to which SPI commands are sent under the Pathway subsystem ID and which generate EMS event messages with the Pathway subsystem ID. All SPI commands for the Pathway subsystem are sent to the PATHMON process, but the processsing for the command might involve other processes, such as a TCP.
primary process fails, the backup process is notified that it is now the primary, and it resumes the application work from the last valid checkpoint message. process type An attribute of a server-class indicating whether the server processes in that server-class are Guardian processes or OSS processes. See also process. program file An executable object file. See also object file. PROGRAM object A template for creating and starting temporary TERM objects. See also temporary TERM object.
requestor/server model A model for application design that divides the tasks of data input, data manipulation, and data output between two basic types of process: requestors and servers. A requestor sends a request to a server. The server takes the requested action and then replies to the requestor. The requestor and server might reside on the same processor or on different processors. This model is used for interprocess communication in the Guardian environment. See also requestor and server.
server 1. 2. A process or program that provides services to a client or a requestor. Servers are designed to receive request messages from clients or requestors; perform the desired operations, such as database inquiries or updates, security verifications, numerical calculations, or data routing to other computer systems; and return reply messages to the clients or requestors. A server process is a running instance of a server program.
sync ID A value used in the Guardian environment to determine whether an I/O operation has finished. In active backup programming, a file’s sync ID is used to prevent the backup process from repeating I/O operations that have already been completed by the primary process. syncdepth A parameter to Guardian procedure calls that sets the maximum number of operations or messages that a process is allowed to queue before action must be taken or a reply must be performed. system name 1. 2. 3.
of the PATHMON process, establishes links between screen programs and server processes. See also requestor and SCREEN COBOL. terminal data area (TDA) In SCREEN COBOL, the area that the TCP allocates for terminal context data. The MAXTERMDATA parameter of the PATHCOM SET TCP command defines the upper limit for this data area. thaw condition A condition in which prohibition of communication between a terminal and a server-class is lifted. See also freeze condition.
TSCODE The object code for the part of a GDSX process that is supplied by HP. TSCODE includes generic routines and services that support the development of a multithreaded, fault-tolerant front-end process. See also USCODE and Extended General Device Support (GDSX). tuning The process by which a system manager allocates and balances resources for optimum system performance. UMP See unsolicited-message processing (UMP).
Index Symbols $RECEIVE messages allocating space, 62 determining new dialogs, 70 A Aborted dialog (error 929), 123 Aborted dialogs, detecting, 72 Aborted send operation (error 918), 120 Aborted transaction (error 934), 124 Aborting transactions, 33, 45, 149 ABORTTRANSACTION procedure, 64 Access Control Server (ACS), 57 Application generator, Pathmaker, 24 Application Transaction Monitor Interface (ATMI), 59 Applications, designing batch processing , 49 database , 33, 34 example, OLTP, 28, 33 requestor prog
invoking Pathsend procedures, 76 Code, standardizing and testing, 17 Colon, in Pathsend procedure parameters, 75 Common Run-Time Environment (CRE), 62 Concurrent processing, 32, 33, 64 Condition code considerations, 108 register, 75 Context-free servers, using with context-sensitive requestors, 58, 63 Context-sensitive programming, requestors ACS restart, 59 canceling server-class sends, 59 failure recovery, 58, 59 overview, 57 resource utilization, 58 using with context-free servers, 58, 63 Context-sensiti
FEOK (error 0), 71 FEPathDown (error 201), 117 FESecViol (error 48), 117 FETimeout (error 40), 116 FETimeout (error 440), 117 Requesting process has no… (error 75), 65 timeout error (error 40), 68, 69 Event Management Service (EMS), 17 Examples nested server program, 187, 202 Pathsend requestor program, 135, 187 Extended BASIC, for Pathway servers, 20 Extended General Device Support (GDSX) processes, 22, 39, 41, 45 F Failure recovery context-sensitive requestors, 58, 59 fault-tolerant programming requestor
I M I/O cancel outstanding, example, 152 complete outstanding, example, 153 starting example, 146 IDS See Intelligent device support (IDS), 28 Industrial robots, 39 Input file structure example, 140 Inspect product , 24 Intelligent device support (IDS) , 35 description, 35 GDSX programming for, 40 overview , 20 RSC requestors , 23, 39 Intelligent mode, 35 Interoperation of Pathsend requestors with NonStop TUXEDO servers, 24 of Pathway servers with NonStop TUXEDO requestors (clients), 24 with NonStop TUXED
context-free Pathsend, 55 context-sensitive requestors, 58, 59 dialogs, using with, 71 fault-tolerant servers, 67 grouping transaction operations, 66, 67 limits, 134 Pathmaker software, 25 Pathsend procedure calls, 55 record locking, 66 requestor example, 135, 187 retryable operations, 65 server application structure, 64 server process pairs, 45 server-class violation (error 917), 120 TMF OFF server parameter, 55 transaction deadlocks, 68 usage considerations, 109 writing servers to use, 64, 68 NonStop Tran
description, 20 See also server-classes; Server processes; Server programs; Applications, programming; Applications, designing, 15 Pathway to TUXEDO translation server, 24, 60 Pathway/TS product, 7, 15, 16 Performance provided by Pathsend requestors, 21 provided by Pathway applications, 19 provided by server processes, 20 Personal computer support, 39 PFS use error (error 920), 121 POET (Pathway Open Environment Toolkit) product, 17, 23, 39 Portable Transaction Application Language See pTAL, 15 POS (point-o
NonStop TUXEDO, interoperating with, 59 overview, 51 procedure calls,list of, 74 retryable requests, 56 security issues, 56, 57 server process failures, 52 sharing servers, 61 TMF subsystem, 55 using ASSIGNs, 57 Resource utilization, 58 Response time, 19 Retry mechanism, Pathsend calls, 55 See also Fault tolerance, 15 Retryable requests, Pathsend, 56 Retryable server operations, TMF, 65 Return errors, 115 Robots, industrial, 39 RSC (Remote Server Call) role in Pathway environment, 23, 39 security issues, 57
nowait considerations, 109, 112 overview, 52 syntax and usage, 91, 94 TMF considerations, 109 waited considerations, 109, 112 SERVERCLASS_SEND_INFO64_ procedure syntax and usage, 107 SERVERCLASS_SEND_INFO_ procedure example, 150, 191, 200 overview , 52 syntax and usage, 97, 108 SERVERCLASS_SENDL_ procedure syntax and usage, 94 Servers canceling sends to server-classes, 59 context-sensitive errors returned, 71 functions of, 70 context-sensitive requestors, using, 58, 63 conversational (context-sensitive), 61
fault-tolerance role, 18 TMF OFF server parameter, 55, 109 Too many dialogs (error 927), 123 Too many Pathmons (error 921), 121 Too many requestors (error 925), 122 Too many send requests (error 924), 122 Too many server links (error 923), 122 Too many server-classes (error 922), 121 Tools, software development, 24, 25 tpinit() ATMI function, 60 Transaction Application Language See TAL, 15 Transaction identifiers and LINKMON processes, 109 Transaction Management Facility See TMF, 15 Transaction processing S
