Data Management Library Queue Manager Manual Abstract Part Number This manual provides information for programming, installing, and managing Queue Manager. Queue Manager holds a communication between processes in a queue, allowing the processes to carry on other activities while Queue Manager handles the communication.
Document History Edition Part Number Product Version Operating System Version Date First Edition 46517 Transfer C30 Guardian C20 July 1991 New editions incorporate any updates issued since the previous edition. Copyright All rights reserved. No part of this document may be reproduced in any form, including photocopying or translation to another language, without the prior written consent of Tandem Computers Incorporated. Copyright 1991 Tandem Computers Incorporated.
Contents About This Manual vii Notation Conventions Section 1 ix Introduction to Queue Management Queue Manager Components and Functions Queue Manager in PATHWAY 1-2 Queue Manager Functions 1-2 Dequeue (DEQ) Function 1-3 Enqueue (ENQ) Function 1-3 Read (READQ) Function 1-3 Wait (WAITQ) Function 1-4 1-2 Using Queue Manager 1-4 UOW Sequences 1-6 Queue Manager Application Example Section 2 1-8 Queue Manager Server Interface UOWs and UOW Formats 2-1 Server Program Files 2-1 IPC Request and Reply Headers
Contents Section 3 Developing Queue Manager Applications Application Development Steps 3-1 Deciding Whether to Use Queue Manager 3-1 Specifying the Functional Aspects 3-2 Designing Input Screens 3-2 Dividing Application Tasks 3-3 Defining the UOW Content 3-3 Planning High-Level Transactions with TMF 3-3 Planning Low-Level Implementation 3-4 Coding and Testing the Software 3-5 Example 3-6 Section 4 Installation and Management Overview 4-1 Installation Steps Configure TMF Run INSTALL 4-1 4-2 4-2 Edit
Contents Moving the Queue File 4-21 Examples of Configuring Queue Manager 4-22 PATHWAY Configuration File 4-22 Server Definitions 4-24 Queue Manager Cold Start 4-25 Queue Manager Cool Start 4-25 Run Queue Manager 4-26 Queue Manager Shutdown 4-26 Executing Queue Manager from TACL 4-26 Appendix A System Messages Appendix B Example: COBOL Application Glossary Glossary–1 Index Figures Index–1 Figure 1-1. Process Interaction without Queue Manager Figure 1-2.
Contents vi 46517 Tandem Computers Incorporated
About This Manual Queue Manager holds a communication between two processes in a queue so that the processes can carry on other activities while Queue Manager handles the communication. This queuing function can be used in any application that separates an activity into multiple stages. The Queue Manager Manual provides programming, installation, and management information for Queue Manager, including some design guidelines.
About This Manual Related Manuals The following manuals contain detailed information for programs that are written in a language other than SCREEN COBOL or that interface with programs written in other languages: C Reference Manual COBOL85 Reference Manual FORTRAN Reference Manual Pascal Reference Manual Transaction Application Language (TAL) Reference Manual The GUARDIAN 90 Operating System Programmer's Guide and the GUARDIAN 90 Operating System User's Guide, which provide information about programs that
Notation Conventions The following list summarizes the conventions for syntax presentation in this manual. Notation Meaning UPPERCASE LETTERS Uppercase letters represent keywords and reserved words; enter these items exactly as shown. Lowercase italic letters represent variable items that you supply. Brackets enclose optional syntax items. A group of vertically aligned items enclosed in brackets represents a list of selections from which you can choose one or none. Braces enclose required syntax items.
1 Introduction to Queue Management Queue Manager provides capabilities for holding communications between processes in a queue so that the processes can carry on other activities while Queue Manager handles the interaction. This queuing function can be used with any application that needs to separate an activity into multiple stages. Figure 1-1 illustrates how two processes might interact without the presence of Queue Manager.
Queue Management Queue Manager Components and Functions In the second scenario, Queue Manager allows A and B to operate in a loosely coupled mode. Process A can continue with other activities after it has submitted its request. Queue Manager frees A from having to wait while B obtains the resources required for a response. B, on the other hand, need not wait for requests to come from A. It can perform other tasks such as transactions with other requesters.
Queue Management Queue Manager Components and Functions Queue Manager Functions Queue Manager provides four functions for a queue: Dequeue (remove) an entry from the queue (DEQ) Enqueue (insert) an entry on the queue (ENQ) Read an entry on the queue (READQ) Wait for an entry on the queue (WAITQ) Note DEQ, ENQ, and READQ requests are sent to an Entry Manager. WAITQ requests are sent to the Wait Manager.
Queue Management Using Queue Manager Wait (WAITQ) Function A wait function is handled by a WAITQ request from a requester process. You should not issue a WAITQ request within a TMF transaction, because the wait might be extensive and it is best to avoid long transactions. When a WAITQ request is received for a particular queue, the Wait Manager performs a read to ensure there is no entry on that queue. If an entry is on the queue, the Wait Manager issues a response to the consumer.
Queue Management Using Queue Manager Figure 1-3. Queue Management Interaction Process ProcessAA READQ UOW Queue Manager ENQ UOW RSP RSP Entry Manager DEQ UOW Queue File RSP Process B RSP WAITQ UOW Wait Manager 003 Unbroken arrows represent IPC’s containing UOWs and responses. The direction of the arrow shows the direction of the communication. Dashed arrows indicate the direction of internal Queue Manager communications. A process requests services of the Entry Manager.
Queue Management Using Queue Manager UOW Sequences UOWs are typically used in the following sequence: 1. Process B issues the following WAITQ request to the Wait Manager, specifying that the Wait Manager be ready for a specific type of entry to be placed on the queue. This request is issued outside the transaction mode, because Process B might wait a long time before it receives a reply from the Wait Manager. SEND a WAITQ UOW to the Wait Manager. 2.
Queue Management Using Queue Manager 3. When an entry of the type specified by Process B in its WAITQ request appears on the queue, Wait Manager sends a reply to Process B indicating which queue entry to process. Process B then retrieves the entry by issuing a DEQ UOW to the Entry Manager in the transaction mode. The TMF transaction is under the control of Process B, which issues an END TRANSACTION when its processing is completed. BEGIN-TRANSACTION. SEND a DEQ UOW to the Entry Manager.
Queue Management Queue Manager Application Example The example in Step 3 assumes that there would typically not be an entry in the queue for Process B. If the application expects an entry to be waiting in the queue for Process B, it should issue the DEQ request before issuing the WAITQ request, as shown in the following example. BEGIN-TRANSACTION SEND a DEQ UOW to the Entry Manager. If the queue contains an entry of the desired type, process the queue entry and END-TRANSACTION and look for more entries.
Queue Management Queue Manager Application Example This configuration will encounter severe difficulties without Queue Manager support. The sales order process—possibly terminal-based and operated by a clerk who must serve other customers—has to wait to enter another transaction until the inventory control process confirms receipt of the sale. The inventory control process must wait until purchasing accepts the PO, and so on. Figure 1-4.
Queue Management Queue Manager Application Example Figure 1-5.
2 Queue Manager Server Interface UOWs and UOW Formats Processes interface with the Wait Manager and the Entry Manager servers through units-of-work (UOWs) issued within requests. A process written in SCREEN COBOL issues SEND statements to the Queue Manager servers. The same SCREEN COBOL program can communicate with other server classes also.
Queue Manager Server Interface UOWs and UOW Formats The servers allow access to Queue data only if the requesting process has read and write access to the Queue file. Both servers check security when they receive an OPEN request from the requester. If the requester does not have access privilege, the servers deny access and issue a security violation. IPC Request and Reply Headers The format for request and reply headers is the same for all requests and replies.
Queue Manager Server Interface UOWs and UOW Formats IPC Header Format The format of the IPC header is shown by the following DDL definition: DEF ipc-hdr. 02 request-code 88 stop-on-warning 88 stop-on-err 88 do-all-uows 02 pw-reply-code 88 all-uows-ok 88 uows-with-warning 88 uows-with-err 88 rqst-err 02 filler 02 version-code.
Queue Manager Server Interface UOWs and UOW Formats Individual fields in the IPC header can contain the following information: REQUEST-CODE In a Request to the Server. Your application sets this field to indicate request processing conditions. In the request, this field always contains a value less than zero, as follows: STOP-ON-WARNING (-1) stops the processing if a UOW warning indication is encountered. Warnings imply successful completion of the UOW in which they occur.
Queue Manager Server Interface UOWs and UOW Formats Caution If your application receives a value of 2 or 3 in the PW-REPLY-CODE field, the transaction should be aborted, which will cause a transaction backout. If the transaction is not backed out, consistency in the Queue file cannot be guaranteed. VERSION-CODE In both requests and replies, this field designates the version of the message formats used.
Queue Manager Server Interface UOWs and UOW Formats some component of the system or network. IPC-RETN-CODE-DETAIL contains the GUARDIAN 90 file error code. E-ERR-QUEUE-FILE (4924) indicates that an error occurred on the Queue file. Check the IPC-RETN-CODE-DETAIL. E-IO-TIMEOUT (4990) indicates a timeout occurred on file I/O. This usually indicates a deadlock with another process. IPC-RETN-CODE-DETAIL contains the file code of the file on which the error occurred.
Queue Manager Server Interface Queue Manager UOW Descriptions Queue Manager UOW Descriptions This subsection describes the UOWs serviced by the Entry Manager and Wait Manager servers. The description of each UOW includes the following elements: The DDL format and syntax of the request UOW and its corresponding response UOW. The letters rsp at the beginning of each response UOW stand for response. The content, function, and constraints of the individual fields transmitted within, or returned by, the UOW.
Queue Manager Server Interface Queue Manager UOW Descriptions information produced by DDL when generating COBOL. The primary additions are prefixes for all field names and many level 88 declarations for fields. GPQDDL contains DDL code that is used to create definitions for use when programming in a language other than SCREEN COBOL or COBOL. GPQDDL code does not exactly match the DDL syntax shown in this manual, but it should be immediately obvious how to interpret any differences.
Queue Manager Server Interface Queue Manager UOW Descriptions management facility provides no standard handling. Refer to error code definitions in documentation for other systems your application uses, for example, in the GUARDIAN 90 Operating System Event Management Programming Manual, the TRANSFER Reference Manual, or the PATHWAY Screen COBOL Reference Manual. Note UOW Definitions All request and response UOWs must be aligned on word boundaries. Four UOWs are available for use with Queue Manager.
Queue Manager Server Interface DEQ (UOW Code 501) DEQ (UOW Code 501) DEQ dequeues an entry from a queue. The operation requires a TMF transaction. Following is the DDL definition: DEF deq-uow. 02 hdr. 03 self-ident 03 uow-code 02 flags. 03 specific-deq 03 reserved-1 03 reserved-2 03 reserved-3 03 reserved-4 03 reserved-5 03 reserved-6 03 reserved-7 02 queue-name 02 priority 02 time-of-enq 02 cpu-pin 02 max-data-size 02 pad-char 02 filler END. DEF deq-rsp. 02 hdr.
Queue Manager Server Interface DEQ (UOW Code 501) DEQ FIELDS The following fields are defined in this UOW. HDR This is the UOW header. The UOW-CODE value is 501. FLAGS FLAGS lets you qualify the search for a queue entry. Fields within FLAGS are as follows: SPECIFIC-DEQ specifies whether the PRIORITY, TIME-OF-ENQ, and CPU-PIN fields are to be included in the search for the queue entry. Y Include the PRIORITY, TIME-OF-ENQ, and CPU-PIN fields.
Queue Manager Server Interface DEQ (UOW Code 501) In the response, TIME-OF-ENQ is the timestamp generated by the Entry Manager that made the entry on the queue. CPU-PIN This in the request is ignored if SPECIFIC-DEQ is set to N. In the request, CPU-PIN is the CPU PIN value to be used in the search. In the response, CPU-PIN is the CPU PIN of the Entry Manager that made the entry. MAX-DATA-SIZE This is the maximum number of bytes to be returned.
Queue Manager Server Interface DEQ (UOW Code 501) DEQ Operation Note DEQ retrieves, thereby removing, an entry from the named queue and returns either an entry from the queue or an error. The error could be a warning that there was nothing on the queue. If the queue does not contain an expected entry, the application can follow the DEQ operation with a WAITQ request. The WAITQ request operates as a delay until the queue has an entry.
Queue Manager Server Interface ENQ (UOW Code 502) ENQ (UOW Code 502) ENQ enqueues an entry on a named queue, making the entry available for dequeuing by another process. The operation requires a TMF transaction. Following is the DDL definition: DEF enq-uow. 02 hdr. 03 self-ident 03 uow-code 02 flags. 03 notify-wait-manager 03 reserved-1 03 reserved-2 03 reserved-3 03 reserved-4 03 reserved-5 03 reserved-6 03 reserved-7 02 queue-name 02 priority 02 data-byte-count PIC AA VALUE “UW”.
Queue Manager Server Interface ENQ (UOW Code 502) N Do not notify the Wait Manager. The option not to notify the Wait Manager exists only to allow reduced overhead for applications that do not need the Wait Manager. These applications must have some other mechanism for deciding when to issue a DEQ request. This field should always be set to Y unless the Wait Manager is not being used. RESERVED-1 through RESERVED-7 are reserved for future use; these fields must be set to N.
Queue Manager Server Interface ENQ (UOW Code 502) CPU-PIN This is the CPU PIN of the Entry Manager that makes the queue entry. This value is used to ensure that entries on the queue are unique. ENQ Operation ENQ adds an entry to the named queue. The application making the entry should end its transaction as soon as possible after adding the entry. This minimizes conflict when available queue entries exist in the file but are inaccessible because they are locked by TMF.
Queue Manager Server Interface READQ (UOW Code 504) READQ (UOW Code 504) READQ reads an entry on a named queue without removing it from the queue. This operation does not require a TMF transaction. Following is the DDL definition: DEF readq-uow. 02 hdr. 03 self-ident 03 uow-code 02 flags. 03 any-queue-name 03 any-priority 03 any-time-of-enq 03 any-cpu-pin 03 skip-exact 03 reposition 03 reserved-6 03 reserved-7 02 queue-name 02 priority 02 time-of-enq 02 cpu-pin 02 max-data-size 02 pad-char 02 filler END.
Queue Manager Server Interface READQ (UOW Code 504) READQ Fields The following fields are defined in this UOW: HDR This is the UOW header. The UOW-CODE value is 504. FLAGS This lets you qualify the read operation. Fields within FLAGS are as follows: ANY-QUEUE-NAME specifies whether the read is restricted to a specific queue. Y The read is not restricted to a specific queue. A Y value in this field causes ANY-PRIORITY, ANY-TIME-OF-ENQ, and ANY-CPU-PIN to be set to Y automatically.
Queue Manager Server Interface READQ (UOW Code 504) REPOSITION is used for sequential reading of a specific queue or the entire Queue file. Setting this flag to Y after the initial read informs the Entry Manager that the values in the four fields QUEUE-NAME, PRIORITY, TIME-OF-ENQ, and CPUPIN are being supplied based on the result of a previous READQ request. To read sequentially from the beginning of a specified queue or from the beginning of the Queue file: 1. Set SKIP-EXACT and REPOSITION to N. 2.
Queue Manager Server Interface READQ (UOW Code 504) PAD-CHAR This is the character to be used for padding the reply buffer when the actual data length is less than MAX-DATA-SIZE. RETN-CODE This is the return code. The server returns a code in this field to indicate one of the following entries.
Queue Manager Server Interface WAITQ (UOW Code 505) WAITQ (UOW Code WAITQ instructs Wait Manager to wait for an entry on a queue. When a queue entry 505) is made, Wait Manager notifies the server process. This operation does not require a TMF transaction. Following is the DDL definition: DEF waitq-uow. 02 hdr. 03 self-ident 03 uow-code 02 flags.
Queue Manager Server Interface WAITQ (UOW Code 505) QUEUE-NAME This identifies the specific queue for the wait request. WAIT-PRIORITY This determines which waiting process is responded to first. The field can contain an unsigned value ranging from 0 (lowest priority) through 199 (highest priority). Higher numbers are processed before lower numbers. WAIT-TIMEOUT This sets an upper limit, in seconds, on the amount of time the requesting application can wait for an entry. A value of -1 is an unlimited wait.
Queue Manager Server Interface WAITQ (UOW Code 505) The Wait Manager has no way of knowing whether a process has canceled its wait request. To ensure that an available waiting process is notified of a new arrival on a queue, the Wait Manager replies to all processes waiting on the newly added queue entry. When a response to a WAITQ request audited by TMF contains error 4990 E-IO-TIMEOUT, the TMF transaction should be aborted.
3 Developing Queue Manager Applications An application can be designed and developed in many different ways. As a general guideline, Tandem suggests the following combination of steps as one possible way to proceed: Decide whether your application should use Queue Manager. Specify the functional aspects of the application. Identify the users or programs involved and what they do, what kind of information they exchange, how they use that information, and whether they acknowledge receipt.
Developing Queue Manager Applications Application Development Steps Step 2: Specifying the Functional Aspects Identify the entities that will request work of each other or of other processes. Consider whether these entities are people, processes, devices, or other entities; your application must interface with each of these types differently. Consider how many entities your application will involve and how they will interact. Determine which users or processes will be requesters and which will be servers.
Developing Queue Manager Applications Application Development Steps After the user logs on, the application produces a menu screen from which the user can select groups of functions, such as those making up a purchase order. After a group of functions is selected, the application allows the user to execute the function. Part of the execution could consist of enqueuing the purchase order on a Queue file. Later, another process in the application will retrieve the order from Queue Manager and process it.
Developing Queue Manager Applications Application Development Steps If the transaction is aborted during a DEQ operation, consider having the server process that just dequeued the entry enqueue it back on the Queue. A TMF transaction should never span a read operation from a terminal. If you allow a TMF transaction to span a terminal read, the record locks involved in the transaction might be held for a very long time, delaying access by other users.
Developing Queue Manager Applications Application Development Steps SCREEN COBOL program that makes the request. An example of such an error is an incorrect request length (more or fewer UOWs than the request indicated). Errors encountered while processing specific UOWs are reported in the response UOWs by Queue Manager. An example of such an error is W-QUEUE-EMPTY, returned by DEQ when there are no entries on the Queue file for a specified queue name.
Developing Queue Manager Applications Application Development Steps When your application is running, you should validate its fault-tolerant operation and reliance upon TMF. This might entail a recovery drill where operators use TMF to recover from various kinds of failures. Example Following is an example of how UOWs might flow in a Queue Manager application. The example represents part of a retail application similar to the one illustrated in Figure 1-7 in Section 1, “Introduction to Queue Manager.
Developing Queue Manager Applications Application Development Steps Table 3-1. Queue Manager UOW Flow Example Application Code Queue Manager Action Inventory Control issues 2 WAITQs to Wait Mgr: “Alert me when a sales order arrives from Sales” “Alert me when a purchase order # arrives from Purchasing” Wait Manager performs a read to ensure no entry on Queue, then waits for sales order and for purchase order #.
4 Installation and Management Overview The Queue Manager comprises two servers and a file, which can be installed, redefined, or moved using procedures described in this section. The servers are the Entry Manager and the Wait Manager. The record file is the Queue file. Queue Manager requires that TMF also be installed on the system. Queue Manager and TMF can be installed on any Tandem hardware that has both GUARDIAN 90 and TACL.
Installation and Management Step 1: Configure TMF 7. Start the system by executing the appropriate commands in your PATHWAY system. See the examples at the end of this section for a cool or cold start of Queue Manager. 8. Stop Queue Manager by executing the appropriate commands in your PATHWAY system. See the example at the end of this section for a Queue Manager shutdown. Once Queue Manager is installed, you can customize it by editing the GPQCNFG file to change server parameters.
Installation and Management Step 3: Edit PQDEFLTS Defaults File Consider the space on the volume to which you create the user-DSVs. If your volume $SYSTEM is almost full, you can put the user-DSVs on another volume. After creating your user-DSV, use the FUP GIVE command to give the ownership of the files in the user-DSV to the GUARDIAN 90 user ID under which Queue Manager will run. The files should have a security of AOAO, or Queue Manager users will receive security violation messages.
Installation and Management Step 3: Edit PQDEFLTS Defaults File Figure 4-1. Parameter-Name Format PQ EntryServNames0 Terminating number Parameter description Component ID 006 Editing the Default File When editing define files, you can change default parameter values to values you want, delete inapplicable optional parameters, and add optional parameters. The only part of a keyword parameter name you can change is a terminating number. Parameter values take different forms according to type.
Installation and Management Step 3: Edit PQDEFLTS Defaults File Only one keyword parameter and its value can appear on a line. You can insert comments. Any text following the double hyphens (- -) is considered a comment. PATHWAY Process Naming Conventions PATHWAY process names must be unique in your system and must adhere to certain PATHWAY process naming rules. A set of process names that adhere to these rules are included in the PQDEFLTS file.
Installation and Management Step 3: Edit PQDEFLTS Defaults File Process Priority Assignment The PQDEFLTS file contains minimum and maximum process priority values for the Wait Manager and the Entry Manager. The definition programs use these priority values in assigning the process priorities. The following rules apply: The maximum process priority (MAX) must be at least 9 greater than the minimum process priority (MIN).
Installation and Management Step 3: Edit PQDEFLTS Defaults File ------------------- PQDEFLTS File This file contains the default values for the keyword parameters used to define the Queue Manager. Before you install the Queue Manager, copy this file to the configuration subvolume creating the DEFINEPQ file. The keyword parameters are either initialization or reconfigurable parameters.
Installation and Management Step 3: Edit PQDEFLTS Defaults File -- The Wait Manager is a single process server -- class. Only one cpu pair and process name is -- accepted. PQWaitServName $ZTWM -- Specifies the process name for the Wait Manager. -- can change the default name to any valid -- PATHWAY process name. Required, reconfigurable -- parameter. You -- **************************************************** -- Delete the following cpu specification on a 1-cpu -- system.
Installation and Management Step 3: Edit PQDEFLTS Defaults File --N can be any number from 0 to 9; increment -N by 1 for every parameter you insert. --$ZTE0:9 must be a valid name specification -that generates unique process names within -your system. (See Process Name Generation.) ---The number of process names that can be -- generated from the PQEntryServNamesN -- specifications must not be less than the number -- of Entry Manager processes. (PQEntryServs -- parameter).
Installation and Management Step 4: Define Queue Manager -------------- INITIALIZATION PARAMETERS ---------------------- These parameters are nonreconfigurable, initialization parameters that are fixed after INITIALIZATION has successfully completed. The QUEUE file is used during both initialization and redefinition. If the file is moved to another subvolume, you must alter the File parameter value before redefining the Queue Manager or the redefinition will not work. PQInitOut $S.#QUEUE.
Installation and Management Step 4: Define Queue Manager Rules for Running the Definition Program The following rules apply for running the definition program, which is described in the following subsection. You must have TACL running. If you change a parameter after running a definition program, rerun the program. Definition procedures can be affected by parameter values specified in a prior GUARDIAN 90 command interpreter PARAM command.
Installation and Management Step 4: Define Queue Manager REDEFINE provides for changing reconfigurable parameters for the Queue Manager for an existing Queue Manager configuration. REDEFINE is optional and is assumed if you specify neither REDEFINE nor INITIAL. Here is an example of a run command: 1> RUN CDPQDEF /OUT $S.#pqout , NOWAIT/ trancnfg INITIAL This command specifies processing for the initial installation of the Queue Manager and specifies that DEFINE file DEFINEPQ resides on subvolume TRANCNFG.
Installation and Management Step 6: Configuration Do not directly edit the files that CDPQDEF generates, which are secured “O-OO” to discourage editing. If you wish to change configuration information, either customize the Queue Manager by adding information to customizing files as described later in this section or change information in the Queue Manager DEFINE file and rerun CDPQDEF.
Installation and Management Step 6: Configuration Step 7: Starting Queue Manager If you are configuring Queue Manager as part of a TRANSFER system, the appropriate PATHWAY functions will be performed when the XCOOL program is executed to start TRANSFER. If you are configuring Queue Manager as part of a PATHWAY system without TRANSFER, use the procedure you have set up to cold or cool start your PATHWAY system. Refer to the examples for Queue Manager cold or cool starts at the end of this section.
Installation and Management Installation Summary Installation Summary This summary is a check list of steps for the initial installation of Queue Manager. 1. Configure TMF if it is not already configured. 2. Prepare the user-DSV as instructed in this section. 3. Log on with the user ID under which Queue Manager will run. Copy the defaults (PQDEFLTS) file from the user-DSV to the configuration subvolume.
Installation and Management Customizing Queue Manager 8. To shut down the Queue Manager PATHWAY system, enter the appropriate stop commands. If Queue Manager is part of TRANSFER, Queue Manager will stop when you execute the XSTOP command to stop TRANSFER. If Queue Manager is configured without TRANSFER, shut Queue Manager down by executing your PATHWAY shutdown procedure.
Installation and Management Customizing Queue Manager Table 4-2. Server Parameters (Page 1 of 2) Parameter and (Default) Value Description DEBUGLOGFORMAT (FALSE) FALSE The debug log contains binary characters suitable for writing to an entry-sequenced disk file. TRUE The debug log is formatted in ASCII characters suitable for writing to a terminal or printer.
Installation and Management Customizing Queue Manager Table 4-2. Server Parameters (Page 2 of 2) Parameter and (Default) Value Description MAXREPLY (2048) nn where nn is the largest reply (in bytes) a server can generate. This value might affect the maximum number of simultaneous openers, due to memory limitations. MAXREQUEST (2048) nn where nn is the largest request (in bytes) a server can accept. This value might affect the maximum number of simultaneous openers due to memory limitations.
Installation and Management Starting Up Queue Manager Manually Starting Up Queue You have the option to install, configure, and start Queue Manager without using Manager Manually procedures supplied by Tandem. A nonautomated installation approach can be used to install Queue Manager in a PATHWAY application or as part of another application. When you incorporate Queue Manager in a PATHWAY application, be sure to edit all parameters necessary to tailor the system for use at your site.
Installation and Management Starting Up Queue Manager Manually Table 4-3. Logical File Assignments Parameter Description DEBUGLOG (None) Specifies the file to which a debugging log is written. The log contains a copy of some or all of the IPCs received and replied to by the servers. Control over log entries is provided by the parameters listed in Table 4-2 and by a field in the IPC header. If you omit this parameter, no debugging log is written.
Installation and Management Moving the Queue File Redefining Queue Redefining Queue Manager allows you to modify the definitions of existing Queue Manager Manager objects. You redefine the configuration to: Change parameters in the PQDEFLTS file Reconfigure for a new release of software Use the same files and programs you used to define a system to redefine it. The procedure descriptions that follow apply for both definition and redefinition, but redefinition has additional considerations.
Installation and Management Examples of Configuring Queue Manager Examples of The following examples include: Configuring Queue A PATHWAY configuration file that includes a Queue Manager application, Manager where Queue Manager is installed independent of TRANSFER Commands for cold starting Queue Manager when it is not part of TRANSFER Commands for cool starting Queue Manager when it is not part of TRANSFER The command to run a Queue Manager application in a PATHWAY system Commands for starting Queue Mana
Installation and Management Examples of Configuring Queue Manager TCP Descriptions RESET TCP SET TCP SET TCP SET TCP SET TCP SET TCP SET TCP SET TCP SET TCP SET TCP SET TCP SET TCP SET TCP SET TCP SET TCP SET TCP SET TCP ADD TCP CHECK-DIRECTORY ON CODEAREALEN 200000 CPUS 1:3 GUARDIAN-LIB $SYSTEM.SYSTEM.PATHTCPL INSPECT ON MAXREPLY 4096 MAXTERMDATA 15000 MAXTERMS 10 NONSTOP 1 PRI 140 PROGRAM $SYSTEM.SYSTEM.PATHTCP2 STATS ON SWAP $VOL TCLPROG $VOLX.QMCFIG.
Installation and Management Examples of Configuring Queue Manager Server Definitions RESET SERVER SET SERVER SET SERVER SET SERVER SET SERVER SET SERVER SET SERVER SET SERVER SET SERVER SET SERVER SET SERVER SET SERVER SET SERVER SET SERVER SET SERVER SET SERVER SET SERVER SET SERVER SET SERVER SET SERVER (ASSIGN DEBUGLOG,$S.#WMSERV.DEBUGLOG) (ASSIGN QUEUEFILE,$VOLX.QMCFIG.
Installation and Management Examples of Configuring Queue Manager ADD SERVER EMSERV RESET PROGRAM SET PROGRAM ERROR-ABORT ON SET PROGRAM PRINTER $S.#TITAN SET PROGRAM SECURITY “U” SET PROGRAM TCP TCP1 SET PROGRAM TMF ON SET PROGRAM TYPE T16-6520 (INITIAL WORKOUT, TCLPROG $VOLX.QMCFIG.POBJ) ADD PROGRAM PROG1 START TCP * START SERVER * Queue Manager Cold Start In the following example: $XXPM is the PATHMON name $VOLX.
Installation and Management Examples of Configuring Queue Manager Run Queue Manager The following shows a command example for running Queue Manager within a PATHWAY system, where $XXPM is the PATHMON name. PATHCOM $XXPM; RUN PROG1 Queue Manager Shutdown The following is an example of shutting down Queue Manager in a PATHWAY system, where: $XXE0 and $XXE1 are Entry Managers $XXWM is the Wait Manager $XXPM is the PATHMON name.
Installation and Management Examples of Configuring Queue Manager Running an Entry Manager from TACL In the following example: $s.#emserv.debuglog is the debuglog $volx.qmcfig.dsqueue is the Queue File $xxwm is the Wait Manager process name $voly.qmmudsv.emserv is the Entry Manager $xxem is the Entry Manager process name >clear all >assign debuglog, $s.#emserv.debuglog >assign queuefile, $volx.qmcfig.
Appendix A Overview Initialization Messages System Messages This appendix contains explanations for system messages you may encounter at system startup and during Queue Manager operation. Following are error messages that can be issued during initialization. Bad version number on file Meaning. The version number in the control record of the specified file was invalid for the running version of the server. The file must be converted to the current, compatible version.
System Messages Initialization Messages File mode incorrect for file Meaning. The file code for the specified file is incorrect. The file must be recreated with the correct file code. File must be audited Meaning. The specified file is not a file audited by TMF. The file must be specified as audited. Insufficient memory for required Wait Manager tables Meaning. The Wait Manager could not obtain sufficient memory for its tables.
System Messages Operational Error Codes MAXWAITERS value is too large Meaning. The MAXWAITERS parameter has a value that is greater than the defined maximum. The value must be reduced and the server started again. READ error on file Meaning. The specified file system error occurred when a READ was attempted on the specified file. The value is the file system error number to see for additional information. Unable to reserve lcb's Meaning.
System Messages Operational Error Codes The following paragraphs describe fields that contain error codes. PW-REPLY-CODE Errors A value of zero in the PW-REPLY-CODE field of the IPC header indicates that all UOWs in the request were processed successfully. A value other than zero denotes an error. Caution A value of 2 or greater in the PW-REPLY-CODE field requires a transaction abort and full transaction backout by TMF.
System Messages Operational Error Codes Table A-2 shows error ranges and the processes that generate errors within each range. Table A-2. RETN-CODE Errors Range Meaning 4900 through 4999 6000 through 6099 The error or warning was returned by the GUARDIAN 90 file system. The error or warning was returned by the Queue Manager.
System Messages Operational Error Codes Summary of Error Codes The rest of this section lists errors reported by Queue Manager in ascending numeric order, including: The error number associated with each error and the field in which the error is reported The mnemonic text that describes the error and the specific meaning of the error Error code text begins with an E. Warning code text begins with a W. The minus signs that precede the numeric codes for warnings are omitted. 1 UOWS-WITH-WARNING Field.
System Messages Operational Error Codes 3 RQST-ERR Field. PW-REPLY-CODE Meaning. A request error occurred. This type of error indicates that something was wrong in the data in the IPC header and that the error probably does not apply to any particular UOW. In certain cases, however, it might involve an individual UOW; for example, one with an invalid UOW header. When this error occurs, the number of response UOWs might be less than the number of UOWs in the request.
System Messages Operational Error Codes 6 REPLY-TOO-LONG Field. IPC-RETN-CODE Meaning. The reply from the server was too long to fit into the allocated reply buffer. 7 RQST-TOO-SHORT Field. IPC-RETN-CODE Meaning. The request was too short; it contained fewer UOWs than the number specified in the UOWS-TO-PROCESS field. 8 INVALID-REQUEST-CODE Field. IPC-RETN-CODE Meaning. The RQST-CODE field contained an invalid entry. 4001 W-EOF Field. RETN-CODE Meaning.
System Messages Operational Error Codes 4052 E-RESERVED-MUST-BE-N Field. RETN-CODE Meaning. Your process tried to set a flag that is reserved for future use by Queue Manager. Such flags are initialized to N and must remain at this setting. 4078 E-INVALID-PRIORITY Field. RETN-CODE Meaning. Your process specified a delivery priority for a request that was outside the range of 0-199. 4085 E-DATA-TOO-LONG Field. RETN-CODE Meaning.
System Messages Operational Error Codes 4990 E-IO-TIMEOUT Field. IPC-RETN-CODE, RETN-CODE Meaning. Queue Manager could not access portions of the Queue file needed to complete the requested operation because the file was being modified by another requestor. The RETN-CODE-DETAIL field contains the file code of the file that was unavailable. If you receive this error and the request was issued under a TMF transaction, you must abort the TMF transaction.
System Messages Operational Error Codes 6004 E-INVALID-WAITTIMEOUT Field. RETN-CODE Meaning. This error is returned by WAITQ. The value for WAIT-TIMEOUT is not in the range -1 through +9999. 6005 W-WAIT-TIMEOUT 6005 W-WAIT-TIMEOUT Field. RETN-CODE Meaning. This error is returned by WAITQ. The WAITQ UOW has been responded to because of elapsed time, not because of a new entry on the Queue file. 6006 E-WAITMANAGER-UNAVAIL Field. IPC-RETN-CODE, RETN-CODE Meaning. This error is returned by ENQ.
Appendix B Example: COBOL Application IDENTIFICATION DIVISION. PROGRAM-ID. WORKOUT. INSTALLATION. DATE-COMPILED. / ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. T16. OBJECT-COMPUTER. T16, TERMINAL IS T16-6520. SPECIAL-NAMES.
Example: COBOL Application markfield IS (NORMAL, NOREVERSE, UNPROTECTED, NOUNDERLINE, NOTHIDDEN) outfield IS inoutfield IS (NORMAL, NOREVERSE, PROTECTED, NOUNDERLINE, NOTHIDDEN) (DIM, REVERSE, UNPROTECTED, NOUNDERLINE, NOTHIDDEN) corriofield IS (NORMAL, NOREVERSE, UNPROTECTED, UNDERLINE, NOTHIDDEN) bannerfield IS (DIM, REVERSE, PROTECTED, NOUNDERLINE, NOTHIDDEN) advisefield IS (NORMAL, NOREVERSE, PROTECTED, NOUNDERLINE, NOTHIDDEN) paramfield IS (DIM, REVERSE, UNPROTECTED, NOUNDERLINE, NOTHIDDEN) * * Ov
Example: COBOL Application * 01 wa-error-msg PIC X(80) VALUE SPACES. 01 wa-call-error REDEFINES wa-error-msg. 02 wa-error-text PIC X(64). 02 wa-term-status PIC S9(5). 02 FILLER 02 wa-term-substatus PIC X(2). PIC S9(5). * * A control variable for the loop of ACCEPT-AND-DISPATCH. * 01 wa-prog-mode PIC 9(1) exit-program VALUE 0. 88 wa-continue * 88 VALUE 1. VALUE 1. / * * WC -- Fields used in controlling the work done in this module. * 01 wc.
Example: COBOL Application 01 wd. wd-enq-data-field. 10 wd-enq-number PIC 9(4). 05 wd-deq-data-field. 10 wd-deq-data-array PIC X OCCURS 0 TO 66 TIMES DEPENDING ON wc-max-data-size . 05 / 01 ipc-hdr-buf. COPY ih-ipc-hdr OF "GPQCOB". / 01 enqUow-buf. COPY uow-enq-enq-uow OF "GPQCOB". 01 enqRsp-buf. COPY rsp-enq-enq-rsp OF "GPQCOB". / 01 deqUow-buf. COPY uow-deq-deq-uow OF "GPQCOB". 01 deqRsp-buf. COPY rsp-deq-deq-rsp OF "GPQCOB". / 01 waitqUow-buf. COPY uow-wtq-waitq-uow OF "GPQCOB".
Example: COBOL Application background, VALUE "QueueName:" . 05 WORKOUT-QUEUENAME AT 5, 17 inoutfield, PIC X(32), USING wc-queue-name . 05 FILLER AT 5, 52 background, VALUE "Priority:" . 05 WORKOUT-PRIORITY AT 5, 63 inoutfield, PIC ZZZ, USING wc-priority . 05 FILLER AT 7, 1 background, VALUE "NotifyWaitManager:" . 05 WORKOUT-NOTIFYWAITMANAGER AT 7, 21 inoutfield, PIC X(1), USING uow-enq-notify-wait-manager . 05 FILLER AT 7, 51 background, VALUE "SpecificDeq:" .
Example: COBOL Application PIC X, USING uow-etq-rel-effective-time . B–6 05 FILLER AT 9, 51 background, VALUE "PadChar:" . 05 WORKOUT-PADCHAR AT 9, 61 inoutfield, PIC X, USING uow-deq-pad-char . 05 FILLER AT 11, 1 background, VALUE "DateTime:" . 05 FILLER AT 11, 25 background, VALUE "DeltaTime:" . 05 FILLER AT 11, 51 background, VALUE "MaxDataSize:" . 05 WORKOUT-MAXDATASIZE AT 11, 65 inoutfield, PIC ZZ, USING wc-max-data-size . 05 FILLER AT 12, 3 background, VALUE "Year:" .
Example: COBOL Application background, VALUE "DataLen:" . 05 WORKOUT-DATALEN AT 12, 65 inoutfield, PIC ZZ, USING rsp-deq-data-len . 05 FILLER AT 13, 51 background, VALUE "Repetition Count: " . 05 WORKOUT-REP-COUNT AT *, * + 2 inoutfield, PIC ZZZZ USING wc-rep-count . 05 FILLER AT 13, 3 background, VALUE "Month:" . 05 WORKOUT-MONTH AT 13, 12 inoutfield, PIC ZZ, USING month OF wc-date-time . 05 FILLER AT 13, 27 background, VALUE "Units:" .
Example: COBOL Application inoutfield, PIC ZZ, USING hour OF wc-date-time . 05 FILLER AT 16, 3 background, VALUE "Minute:" . 05 WORKOUT-MINUTE AT 16, 12 inoutfield, PIC ZZ, USING minute OF wc-date-time . 05 FILLER AT 17, 3 background, VALUE "Second:" . 05 WORKOUT-SECOND AT 17, 12 inoutfield, PIC ZZ, USING second OF wc-date-time . 05 FILLER AT 18, 51 background, VALUE "AnyQueueName: " . 05 WORKOUT-ANYQUEUENAME AT *, * + 2 inoutfield, PIC X, USING uow-wtq-any-queue-name .
Example: COBOL Application 05 FILLER AT 20, 1 background, VALUE "Ending Number:" . 05 WORKOUT-ENDING-NUMBER AT 20, 19 inoutfield, PIC ZZZZ, USING wc-ending-number . 05 FILLER AT 22, 1 background, VALUE "DataField:" . 05 WORKOUT-DATAFIELD AT 22, 13 outfield, PIC X(66), FROM wd-deq-data-field . 05 workout-menu AT 23, 10 background, VALUE "F1 = Enq, F9 = Deq, F10 = Waitq, F16 = Exit" . 05 advice-line AT 24, 2 advisefield, PIC X(77) ADVISORY FROM wa-error-msg . / PROCEDURE DIVISION.
Example: COBOL Application * Wait for the user to press a function key. The order of the UNTIL clause * will define the order of values assigned in TERMINATION-STATUS. * IF wc-error-status NOT = 0 MOVE wc-error-status TO wa-term-status MOVE wc-error-substatus TO wa-term-substatus MOVE LOW-VALUES TO wc-error ELSE MOVE SPACES TO wa-error-text MOVE ZEROS TO wa-term-status, wa-term-substatus. PERFORM display-screen. ACCEPT workout-scrn UNTIL enq-key, deq-key, waitq-key, (return-key, exit-key).
Example: COBOL Application MOVE LOW-VALUES TO uow-deq-time-of-enq, uow-deq-cpu-pin. MOVE wc-max-data-size TO uow-deq-max-data-size. ACCEPT wc-time-started FROM TIME. PERFORM send-deq VARYING wc-current-number FROM 1 BY 1 UNTIL wc-current-number > wc-rep-count OR wc-error-status NOT = 0. ACCEPT wc-time-finished FROM TIME. SUBTRACT wc-time-started FROM wc-time-finished GIVING wc-elapsedtime. DO-ENQ SECTION. * * User entered the ENQ key. requests * on the queue.
Example: COBOL Application MOVE LOW-VALUES TO ih-session-id. MOVE 1 TO ih-uows-to-process. MOVE SPACES TO wd-deq-data-field. IF uow-deq-specific-deq = "Y" MOVE uow-enq-queue-name TO uow-deq-queue-name MOVE uow-enq-priority TO uow-deq-priority MOVE rsp-enq-time-of-enq TO uow-deq-time-of-enq MOVE rsp-enq-cpu-pin TO uow-deq-cpu-pin. BEGIN-TRANSACTION.
Example: COBOL Application CODE 3 YIELDS ih-ipc-hdr ON ERROR MOVE TERMINATION-STATUS TO wc-error-status MOVE TERMINATION-SUBSTATUS TO wc-error-substatus. IF ih-pw-reply-code > 2 MOVE ih-ipc-retn-code TO wc-error-status MOVE ih-ipc-retn-code-detail TO wc-error-substatus ELSE IF ih-pw-reply-code > 0 MOVE rsp-enq-retn-code TO wc-error-status MOVE rsp-enq-retn-code-detail TO wc-error-substatus. IF wc-error-status = 0 END-TRANSACTION ELSE ABORT-TRANSACTION. SEND-WAITQ SECTION.
Glossary Audited file. A data file that is flagged for auditing by the Transaction Monitoring Facility (TMF). Auditing is the monitoring of transactions in preparation for recovery efforts. Configuration subvolume. A subvolume that contains define files you provide to describe and control the Queue Manager system. DDL. The Data Definition Language that is used to describe the records and files that make up a database and the formats of interprocess messages. Defaults file.
Glossary Process. A running program. Queue. A list of queue entries. Functions are provided to enqueue (add) entries, dequeue (retrieve and delete) entries, read entries, and wait for entries to appear. Queue entry. Application data that must fit in a single record. Queue file. An audited key-sequenced file in which multiple queues are stored. Queue management. An operating environment in which a set of queues are managed for two or more programs. Queue Manager.
Glossary Wait Manager (WMSERV). A server that waits for new queue entries; an application can have only one Wait Manager per Queue file. WMSERV. See Wait Manager.
Index A ALL-UOWS-OK, IPC reply code 2-4 Application development and TMF 3-3, 3-5 balancing requester-server processes 3-3 data security and integrity 3-2 defining UOWs 3-3 error-handling strategies 3-5 identifying application entities 3-2 input screens 3-2 testing 3-5 Applications, appropriate Queue Manager 3-1 Array limits, modify in standard DDL definitions 2-7 ASSIGN command 4-19 C C language and Queue Manager UOWs 2-1 as prerequisite for programming Queue Manager vii developing Queue Manager application
Index D DDL format filler fields 2-7 DEQ UOW code for 2-9 DDL definition 2-10 defined 1-3 operation 1-3, 1-7, 2-13 TMF transaction required for 2-2 DO-ALL-UOWS, IPC request code 2-4 E E-BAD-TRANSACTION, IPC return code 2-5 E-ERR-QUEUE-FILE, IPC return code 2-6 E-IO-TIMEOUT error in DEQ from Wait Manager 2-23 in IPC return code 2-6 E-IO-TIMEOUT error, in DEQ from Wait Manager 2-22 E-WAITMANAGER-UNAVAIL, IPC return code 2-6 ENQ UOW and Entry Manager 2-16 and Wait Manager 2-16 code for 2-9 defined 1-3 operati
Index G GPQCOB source code file 2-7 GPQDDL source code file 2-7 GPQFUP file 4-12, 4-13 GPQINIT file 4-12, 4-13 GPQLINK source code file 2-7 GPQLOAD file 4-12, 4-13 GUARDIAN 90 vii GUARDIAN 90 Operating System Programmer's Guide viii GUARDIAN 90 Operating System User's Guide viii I I/O timeout, not appropriate with WAITQ 2-22 Installation cold start example 4-25 configuration example 4-22 configuring TMF 4-2 cool start example 4-25 editing the source file for the Queue Manager definition file 4-3, 4-4 files
Index INVALID-REQUEST-CODE, IPC return code 2-5 INVALID-SESSION-ID, IPC return code 2-5 INVALID-UOW-HDR, IPC return code 2-5 INVALID-VERSION-CODE, IPC return code 2-5 IPC-OK, IPC return code 2-5 IPC-RETURN-CODE-DETAIL in an IPC 2-6 L LOG-THIS-IPC, in an IPC 2-6 Logical file assignment 4-19 P Parameters customizing server 4-16 sample name 4-3 used in controlling Queue Manager 4-3 value types 4-4 Pascal and Queue Manager UOWs 2-1 as prerequisite for programming Queue Manager vii developing Queue Manager appl
Index Q Queue entries 1-2 logical 1-2 Queue file add an entry to 1-3 and UOWs 1-3 function of 1-2 if typically empty 1-4 in PATHWAY 1-2 initialization 4-13 initialization files 4-12 partitioning the 1-2 procedure for moving the 4-21 read an entry on 1-3 wait for an entry on 1-3, 1-4 Queue Manager access security 2-2 and process interaction 1-1, 3-3 and the Queue file 1-2 application examples 1-8, 3-6, B-1 capabilities of 1-1 configuring manually 4-19 customizing 4-16 deciding whether to use 3-1 hardware an
Index source code for 2-7 starting 4-14 starting from TACL 4-19 stopping 4-14 two servers in 1-2 UOWs used in 1-3 Queuing function adding entry to queue 1-3 defined 1-1 inserting an entry on the queue 1-3 R READQ UOW code for 2-9 defined 1-3 operation 1-3, 2-20 REPLY-TOO-LONG, IPC return code 2-5 RQST-ERR, IPC reply code 2-4 RQST-TOO-LONG, IPC return code 2-5 RQST-TOO-SHORT, IPC return code 2-5 Run command 4-26 S SCREEN COBOL and Queue Manager UOWs 1-3, 2-1 as prerequisite for programming Queue Manager vii
Index STOP-ON-ERR, IPC request code 2-4 STOP-ON-WARNING, IPC request code 2-4 T Transaction Application Language (TAL) and Queue Manager UOWs 2-1 as prerequisite for programming Queue Manager vii developing Queue Manager application in 3-4, 3-5 Transaction Application Language (TAL) Reference Manual viii Transaction Monitoring Facility (TMF) vii and application development 3-3, 3-5 and data security 3-2 required for Queue Manager 4-1 starting up 4-2 TMF transactions and DEQ UOW 1-7 TMF transactions and ENQ
Index UOWS-RETURNED, in an IPC 2-6 UOWS-TO-PROCESS, in an IPC 2-6 UOWS-WITH-ERR, IPC reply code 2-4 UOWS-WITH-WARNING, IPC reply code 2-4 User-DSV subvolume 4-1 V Version code, in UOWs 2-5 W Wait Manager function of 1-2, 1-4 minimum and maximum process priority values 4-6 operation example 1-6, 1-7 PATHWAY configuration for 4-12 rules for using 2-1 server name WMSERV 2-1, 4-19 UOWs received 1-3 WAITQ UOW application logic for 1-4 code for 2-9 DDL definition 2-21 defined 1-3, 1-4 in an IPC request 2-2 opera
