Message Control Bank - Public Support Login - Unisys

OS 2200
Message Control Bank (MCB)
Programming Reference Manual
© 2003 Unisys Corporation.
All rights reserved.
Level 8R3
Printed in USA
July 2003 7833 1568–004
UNISYS

NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information
described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to
purchase or lease equipment or to license software. The only warranties made by Unisys, if any, with respect to the
products described in this document are set forth in such agreement. Unisys cannot accept any financial or other
responsibility that may be the result of your use of the information in this document or software material, including
direct, special, or consequential damages.
You should be very careful to ensure that the use of this information and/or software material complies with the laws,
rules, and regulations of the jurisdictions with respect to which it is used.
The information contained herein is subject to change without notice. Revisions may be issued to advise of such
changes and/or additions.
Notice to U.S. Government End Users: This is commercial computer software or hardware documentation developed at
private expense. Use, reproduction, or disclosure by the Government is subject to the terms of Unisys standard
commercial license for the products, and where applicable, the restricted/limited rights provisions of the contract data
rights clauses.
Correspondence regarding this publication can be e-mailed to doc@unisys.com.
Unisys is a registered trademark of Unisys Corporation in the United States and other countries.
All other brands and products referenced in this document are acknowledged to be the trademarks or registered
trademarks of their respective holders.

OS 2200
Message Control Bank
(MCB)
Programming Reference
Manual
Level 8R3
OS 2200
Message Control
Bank (MCB)
Programming
Reference
Manual
Level 8R3
7833 1568–004 7833 1568–004
Bend here, peel upwards and apply to spine.

Contents
Section 1. Introduction
1.1. Introduction to MCB................................................................. 1–1
1.2. Notation Conventions............................................................... 1–3
Section 2. Components and Mass Storage Files
2.1. Components............................................................................. 2–1
2.1.1. Background Run .............................................................. 2–2
2.1.2. Main Common Bank........................................................ 2–3
2.1.3. Main Storage Message Common Banks ........................ 2–3
2.1.4. Position Identifier (PID) Table Common Banks ............... 2–3
2.1.5. Message Retention File (MRF) Control Common
Banks .......................................................................... 2–4
2.1.6. Site-id Table Common Banks .......................................... 2–4
2.1.7. Range Table Common Banks .......................................... 2–4
2.1.8. VINDEX Common Bank................................................... 2–4
2.1.9. Message-Recovery Bank for Short Recovery
(MSGBNK)................................................................... 2–5
2.1.10. Message-Recovery Bank for Long Recovery
(MSGLNGBNK)............................................................ 2–5
2.2. Mass Storage Files .................................................................. 2–5
2.2.1. Message Retention File (MRF)........................................ 2–5
2.2.2. MRF Control File.............................................................. 2–5
2.2.3. PID Index File (PIX).......................................................... 2–6
Section 3. Message Processing – General Concepts
3.1. Message Types........................................................................ 3–1
3.2. Message Attributes ................................................................. 3–2
3.2.1. Message Recoverability .................................................. 3–2
3.2.2. Deferred Message Queuing............................................ 3–2
3.2.3. Message Numbering....................................................... 3–3
3.2.3.1. Intelligent Input....................................................... 3–3
3.2.3.2. Intelligent Output.................................................... 3–3
3.2.3.3. Unintelligent Input .................................................. 3–4
3.2.3.4. Unintelligent Output ............................................... 3–4
3.2.4. Audit Text ........................................................................ 3–4
3.2.5. Message Recall ............................................................... 3–5
3.2.6. Low Main Storage Priority............................................... 3–5
3.2.7. Reduced Output Path Length (ROPL) ............................. 3–5
3.3. Validation Table Considerations ............................................... 3–6
7833 1568–004 iii

Contents
3.3.1. Application Group Number...............................................3–6
3.3.2. Recovery Options ............................................................3–7
3.3.2.1. Output Message Attributes.....................................3–8
3.3.2.2. Input Message Attributes........................................3–8
3.3.2.3. Program Execution Attributes .................................3–8
3.3.3. Access Mask....................................................................3–9
3.3.4. Input Queue Priority.........................................................3–9
3.3.5. Transaction Program Number..........................................3–9
3.4. Message Processing Interfaces .............................................3–10
3.4.1. Basic Mode Low-Level Interface ...................................3–12
3.4.2. Application Programming Considerations ......................3–13
3.4.2.1. Basic Mode and Extended Mode Interfaces.........3–14
3.4.2.2. Mixed-Mode Considerations .................................3–15
3.5. Optional Features ...................................................................3–15
3.5.1. Conversational Link........................................................3–16
3.5.2. Multiple Destination Output...........................................3–16
3.5.3. Rotary Output ................................................................3–16
3.5.4. Unsolicited Output .........................................................3–17
3.5.5. Delivery Notification.......................................................3–17
3.5.6. Test and Training Modes................................................3–17
3.5.6.1. Training Mode........................................................3–17
3.5.6.2. Test Mode .............................................................3–18
3.5.6.3. Test/Training Mode ...............................................3–18
3.5.6.4. Mode Establishment .............................................3–18
3.5.6.5. Mode Interpretation ..............................................3–19
3.5.7. MCB Session Control.....................................................3–19
3.5.7.1. Outbound Open Session Establishment ...............3–19
3.5.7.2. Outbound Session Close.......................................3–20
3.5.7.3. Session State Changes .........................................3–20
3.5.8. Exclusive Use of a PID...................................................3–20
3.5.9. PID Site-id Table.............................................................3–20
3.5.10. IBM Terminal to Logical UTS 400 Terminal....................3–20
3.5.11. Input Message Control...................................................3–21
3.5.12. Output Message Control ...............................................3–21
3.5.13. TIP Session Control........................................................3–22
3.5.14. Program Options (VALTAB and XQT).............................3–22
3.5.15. Common Bank Security .................................................3–22
3.5.16. TIP Message Security ....................................................3–22
3.5.17. MCB File Security ..........................................................3–23
3.5.18. User Session Reestablishment......................................3–23
3.5.19. Partitioned Applications..................................................3–23
3.5.20. Statistics Monitor Transaction .......................................3–24
3.5.21. MRF Threshold Control ..................................................3–24
3.5.22. User Message Control ...................................................3–24
3.6. TeamQuest Transaction Performance Auditing System
(TPAS).................................................................................3–24
Section 4. CMS Interface
4.1. Requirements of CMS ..............................................................4–1
4.2. Basic Mode Calling Sequence for CMS....................................4–2
iv 7833 1568–004

Contents
4.3. Extended Mode Calling Sequence for CMS............................. 4–3
4.4. CMS Interface Packet .............................................................. 4–4
4.5. Interface Functions .................................................................. 4–5
4.5.1. CMS Activity Initialization ................................................ 4–5
4.5.2. CMS Activity Termination................................................ 4–7
4.5.3. CMS Store Input Message.............................................. 4–7
4.5.4. CMS Input Message Cancel............................................ 4–9
4.5.5. CMS Receive Output Message..................................... 4–10
4.5.6. CMS Output Message Hold .......................................... 4–12
4.5.7. CMS Output Message Positive Acknowledge.............. 4–12
4.5.8. CMS Output Message Negative Acknowledge ............ 4–13
4.5.9. CMS Put Text ................................................................ 4–14
4.5.10. Read VINDEX Entry ....................................................... 4–15
4.5.11. CMS Get Text................................................................ 4–16
4.5.12. CMS Session Status Notification .................................. 4–17
4.5.13. CMS PID Configuration ................................................. 4–19
4.5.14. CMS Session Open Notify ............................................ 4–20
4.5.15. CMS Resilient Session Open Notification ..................... 4–20
4.5.16. CMS PID Information Request...................................... 4–21
4.5.17. CMS Obtain Resource Status ....................................... 4–22
4.6. Auxiliary Information Area...................................................... 4–23
Section 5. Application Program Interface
5.1. General Description.................................................................. 5–1
5.2. Basic Mode High-Level Calling Sequence................................ 5–2
5.3. Extended Mode High-Level Calling Sequence......................... 5–3
5.4. Application Program Interface Packet...................................... 5–4
5.5. Functions.................................................................................. 5–6
5.5.1. Initialize............................................................................ 5–6
5.5.2. Terminate ...................................................................... 5–11
5.5.3. Commit.......................................................................... 5–12
5.5.4. Rollback ......................................................................... 5–13
5.5.5. Read Input ..................................................................... 5–14
5.5.6. Release Input ................................................................ 5–16
5.5.7. Cancel Output ............................................................... 5–17
5.5.8. Store Output.................................................................. 5–17
5.5.9. Store Pass-Off............................................................... 5–23
5.5.10. Store Checkpoint........................................................... 5–26
5.5.11. Enqueue Message ........................................................ 5–29
5.5.12. Audit .............................................................................. 5–29
5.5.13. Discrete Receive ........................................................... 5–30
5.5.14. Open a Session ............................................................. 5–32
5.5.15. Close a Session ............................................................. 5–34
5.5.16. Request PID Status ....................................................... 5–34
5.5.17. Obtain Exclusive Use of a PID ...................................... 5–35
5.5.18. Release Exclusive Use of a PID .................................... 5–36
5.5.19. Obtain Input-Only Exclusive Use of a PID..................... 5–37
5.5.20. Obtain MCB Statistics ................................................... 5–38
5.6. Auxiliary Information Area...................................................... 5–40
5.7. Unique Identifier..................................................................... 5–40
7833 1568–004 v

Contents
5.8. Recovery Options Summary...................................................5–41
5.9. Unintelligent Message Numbering Format.............................5–44
5.9.1. Input Acknowledge Message ........................................5–44
5.9.2. Output Message Header ...............................................5–45
5.10. Delivery Notification Format ...................................................5–46
5.11. Session State Changes...........................................................5–47
5.12. Host-to-Host MCB Transactions.............................................5–47
5.12.1. Host-to-Host Restrictions...............................................5–47
5.12.2. End-to-End Message Acknowledgment ........................5–48
5.12.3. Opening a Host-to-Host PID Session.............................5–48
5.12.4. Store Output (SEND$$) Considerations.........................5–49
5.12.5. SEP and ENP Considerations.........................................5–49
5.13. HVSTAT Considerations..........................................................5–49
Section 6. TIP Primitive Interface
6.1. MCB Primitives.........................................................................6–1
6.1.1. INITAL—Transaction Program Initialization......................6–2
6.1.2. TERMN8—Transaction Program Termination..................6–2
6.1.3. CONECT—Batch/Demand Program Initialization.............6–2
6.1.4. DISCON—Batch/Demand Program Termination .............6–2
6.1.5. CSTLOG—Store a Message ............................................6–3
6.1.6. CSTOVR—Overlay or Extend a Message ........................6–3
6.1.7. CDATAC—Read a Message.............................................6–3
6.1.8. CDATCR—Read and Release a Message........................6–3
6.1.9. CRELOG—Release All Messages....................................6–3
6.1.10. RTRANO/RTRANU—Store and Queue a
Message ......................................................................6–3
6.1.11. RTOUTP/RTSCHD—Queue an Output or
Pass-off Message........................................................6–4
6.1.12. ERTERM—Program Error Termination ............................6–4
6.1.13. ROLBAK—Program Step Rollback...................................6–4
6.1.14. COMMIT—Program End of Step .....................................6–4
6.2. Message Parameter Area.........................................................6–4
6.3. User Parameter Area ................................................................6–5
6.4. Application Program Impacts and Incompatibilities..................6–5
6.4.1. Relative Addressing .........................................................6–5
6.4.2. Overlay.............................................................................6–5
6.4.3. Physical COMPOOL.........................................................6–5
6.4.4. Program Options..............................................................6–5
6.4.5. Initialization.......................................................................6–5
6.4.6. Termination Differences between COMPOOL
and MCB......................................................................6–6
6.4.7. Running COMPOOL and MCB Programs
Concurrently ................................................................6–6
Section 7. Universal Database Control Considerations
7.1. Universal Database Control Interface .......................................7–1
7.2. Universal Database Control Run-Unit Conventions ..................7–1
7.2.1. MCB Initialize ...................................................................7–2
vi 7833 1568–004

Contents
7.2.2. MCB Terminate ............................................................... 7–2
7.2.3. MCB Commit................................................................... 7–2
7.2.4. MCB Rollback.................................................................. 7–2
7.2.5. Message Release............................................................ 7–2
7.2.6. Retrieval Run-Units.......................................................... 7–3
7.2.7. LOG Command ............................................................... 7–3
Section 8. Error Processing Programs
8.1. Overview.................................................................................. 8–1
8.2. System Error Program (SEP).................................................... 8–1
8.2.1. Purpose ........................................................................... 8–2
8.2.2. System Generation Considerations................................. 8–2
8.2.3. VINDEX Considerations................................................... 8–3
8.2.4. MCB Interface ................................................................. 8–3
8.3. Error Notification Program (ENP) ............................................. 8–4
8.3.1. VINDEX Considerations................................................... 8–5
8.3.2. Message Format ............................................................. 8–5
Section 9. Message Recovery
9.1. MSGBNK.................................................................................. 9–1
9.2. MSGBNK Interface to IRU ....................................................... 9–1
9.3. MSGBNK Error Handling.......................................................... 9–2
9.4. MSGBNK Console Messages .................................................. 9–2
9.5. MSGLNGBNK........................................................................... 9–2
Appendix A. Function Codes
Appendix B. Error Codes
Appendix C. Message Recovery Options
C.1. Recovery Option Combinations ...............................................C–1
C.2. Message Numbering................................................................C–3
C.3. Program Recovery Options......................................................C–4
Appendix D. Audit Records
D.1. MCA Block ...............................................................................D–2
D.2. Overflow Block.........................................................................D–2
D.3. User Audit Record....................................................................D–3
D.4. MRF Controls ...........................................................................D–3
D.5. Periodic Statistics.....................................................................D–3
D.6. TIP$Q Error ..............................................................................D–3
7833 1568–004 vii

Contents
Appendix E. Tailoring Features
E.1. Tailored Message Analysis (TMA) ........................................... E–1
E.2. Tailored Session Analysis (TSA)............................................... E–3
Appendix F. Data Structures
F.1. Message Block Structure .........................................................F–1
F.1.1. Notation Conventions.......................................................F–1
F.1.2. MCA Block .......................................................................F–1
F.1.2.1. MCA Field Definitions..............................................F–2
F.1.2.2. TIP$Q Packet Field Definitions................................F–4
F.1.2.3. TIP$Q Packet Extension for Output
Messages ...........................................................F–5
F.1.2.4. TIP$Q Packet Extension Area for Other
Message Types...................................................F–6
F.1.3. Overflow Block.................................................................F–7
F.1.4. Main Storage Buffers.......................................................F–7
F.2. Message Retention File (MRF) Operations ..............................F–8
F.2.1. Recoverable MRFs...........................................................F–8
F.2.2. Nonrecoverable MRFs .....................................................F–9
F.2.3. MRF Control Tables .........................................................F–9
F.2.4. MRF Blocks......................................................................F–9
F.2.5. MRF Identifiers (MID) ....................................................F–10
F.2.6. Segment Allocation Mask (SAM) Area...........................F–10
F.3. Main MRF Control Table (MRF$TBL)......................................F–11
F.3.1. MRF File Table (MF$CTX) ..............................................F–11
F.3.2. MRF Control Table (MF$CTL) ........................................F–12
F.4. Buffer Pool Controls ...............................................................F–14
F.5. SLOT.......................................................................................F–15
F.5.1. AUDIT$ Packet...............................................................F–22
F.5.2. SLOT Extension Area.....................................................F–23
F.5.3. DM$IOW Packet............................................................F–25
F.5.4. TIP$XMIT Packet ...........................................................F–26
F.6. MRF Allocation Descriptor (MAD) ..........................................F–27
F.7. Position Identifier (PID) ...........................................................F–32
F.7.1. PID Entry........................................................................F–33
F.7.2. Group PID Entry .............................................................F–35
F.7.3. Group PID Table.............................................................F–36
F.8. PID Index File (PIX) .................................................................F–36
F.9. Statistics Table (ST$TBL)........................................................F–37
Appendix G. MCB Open Look
Appendix H. Related Product Information
Glossary ............................................................................................. 1
viii 7833 1568–004

Contents
Index ............................................................................................. 1
7833 1568–004 ix

Contents
x 7833 1568–004

Figures
2–1. Components and Mass Storage Files ................................................................ 2–2
3–1. Message Format .............................................................................................. 3–11
4–1. CMS Packet ....................................................................................................... 4–4
4–2. CMS Packet Overlay .......................................................................................... 4–5
4–3. Auxiliary Information Area ................................................................................ 4–23
5–1. Application Program Interface Packet................................................................ 5–5
5–2. Application Program Interface Packet Overlay .................................................. 5–6
5–3. Multiple Destination List .................................................................................. 5–20
5–4. Unique Identifier............................................................................................... 5–41
5–5. Input Recovery Options ................................................................................... 5–42
5–6. Output Recovery Options ................................................................................ 5–42
5–7. Pass-Off Recovery Options.............................................................................. 5–43
5–8. Checkpoint Recovery Options.......................................................................... 5–43
8–1. Error Notification Message ................................................................................ 8–6
D–1. Order of MCA Blocks in Audit Trail ....................................................................D–2
F–1. MCA Block Structure ......................................................................................... F–1
F–2. MCA Field Definitions ........................................................................................ F–2
F–3. TIP$Q Packet Field Definitions........................................................................... F–4
F–4. TIP$Q Packet Extension for Output Messages ................................................. F–5
F–5. TIP$Q Packet Extension Area ............................................................................ F–6
F–6. Overflow Control Field Definitions ..................................................................... F–7
F–7. Main Storage Buffer Field Definitions ................................................................ F–8
F–8. Main MRF Control Table .................................................................................. F–11
F–9. MRF File Table ................................................................................................. F–11
F–10. MRF Control Table ........................................................................................... F–12
F–11. MRF Control Table Formats ............................................................................. F–13
F–12. Buffer Pool Control........................................................................................... F–14
F–13. SLOT Header.................................................................................................... F–15
F–14. SLOT ................................................................................................................ F–17
F–15. Audit$ Packet ................................................................................................... F–22
F–16. SLOT Extension Area ....................................................................................... F–23
F–17. DM$IOW Packet.............................................................................................. F–25
F–18. TIP$XMIT Packet.............................................................................................. F–26
F–19. MRF Allocation Descriptor ............................................................................... F–27
F–20. RNG$BNK Directory......................................................................................... F–32
F–21. PID Entry .......................................................................................................... F–33
F–22. Group PID Entry ............................................................................................... F–35
F–23. Group PID Table ............................................................................................... F–36
F–24. Field Definitions (EQUF) for Statistics.............................................................. F–38
7833 1568–004 xi

Figures
G–1. Example of C Language Call to UC Function Library ......................................... G–2
G–2. Structure of an MCB Open Look Executable ZOOM ........................................ G–3
xii 7833 1568–004

Tables
3–1. Recovery Options............................................................................................... 3–7
3–2. Example Programs........................................................................................... 3–13
4–1. Relation between P$FUNC and P$QID............................................................ 4–18
4–2. Values for UTS 400 Function Keys................................................................... 4–27
4–3. Values for the Coded Character Set................................................................. 4–30
8–1. VINDEX Parameters for System Error Program................................................. 8–3
8–2. VINDEX Parameters for Error Notification Program........................................... 8–5
8–3. Error Notification Codes ..................................................................................... 8–6
A–1. Function Codes ..................................................................................................A–1
B–1. Error Codes ........................................................................................................B–1
7833 1568–004 xiii

Tables
xiv 7833 1568–004

Examples
5–1. Input Acknowledge Message .......................................................................... 5–44
5–2. Output Message Header.................................................................................. 5–45
7833 1568–004 xv

Examples
xvi 7833 1568–004

Section 1
Introduction
This manual is a reference for Message Control Bank (MCB) information used in
applications programming on OS 2200 systems (Exec) with OS 2200 system software.
This manual contains the following information:
• General information about the MCB product and message processing
• Information about MCB external interfaces
• MCB internal technical information for software maintenance
• Information about MCB programming conventions for use with database
management programs, external error processing, and message processing
programs
This manual assumes that you are familiar with OS 2200 Executive System software,
Transaction Processing (TIP), TIP utilities, and a Communications Management System
(CMS 1100 or similar program on your system), and Network Database Server (formerly
DMS 2200) software. This manual assumes that you are also familiar with the Integrated
Recovery Conceptual Overview.
This document contains all the information that was available at the time of publication.
Technical changes that were not available at that time are documented in problem list
entry (PLE) 17891294. Your Unisys representative can provide you with a copy of that
PLE.
1.1. Introduction to MCB
The Message Control Bank (MCB) is the message control component of the OS 2200
integrated recovery system. MCB is an alternative to the original communications
message-buffer pool (COMPOOL) and provides additional functions, particularly in
message recovery. MCB is used primarily in a transaction processing environment.
In combination with related software in the Communications Management System
(CMS 1100) and the OS 2200 (Exec) system, MCB supports the following message
types:
• Communications network input messages
• Communications network output messages
• Internally generated program pass-off messages
• Checkpoint messages (not communications)
7833 1568–004 1–1

Introduction
Transaction programs or programs connected with Transaction Processing (TIP) batch or
demand programs can receive input or pass-off messages, or create output or pass-off
messages. Application programs interface to the MCB through one of the following:
• A low-level, packet-driven interface
• The Display Processing System (DPS 2200)
• A TIP primitive interface compatible with COMPOOL
To MCB, a message consists of
• Control information or data represented by a packet
• Auxiliary data or data exterior to the packet
• Text made up of any kind of binary data
The MCB supports the following message processing activities:
• Message staging
Message staging holds message text in main storage buffers or in message
retention files on mass storage.
• Message auditing
Message auditing allows optional logging of message traffic on a magnetic tape or
mass storage audit trail for recovery, statistical, and accounting purposes.
• Message queuing
Message queuing give priority sequencing to control information for orderly delivery
of input and pass-off messages to application programs and delivery of output to the
network through CMS.
• Message recovery
Message recovery automatically requeues recoverable undelivered input, output, and
pass-off messages after system failure.
• Message recall
Message recall recalls successfully delivered input or output from a message
retention file.
Note: The MCB is the only supported interface for message queuing and message
recovery. However, the MCB does not perform these functions alone; they are
accomplished by joint processing of the Exec and MCB.
1–2 7833 1568–004

1.2. Notation Conventions
Introduction
This manual uses the following general command format in examples and procedural
discussions:
������� ����������������
where:
COMMAND
is the name of a command. Command names are presented in uppercase, but you
may enter them in either uppercase or lowercase.
parameter-string
is a parameter associated with the command. Parameter-string fields are presented
in lowercase or italics when they represent alphanumeric variables.
The following conventions are used to describe MCB command syntax:
{ }
Braces indicate two or more required parameters or fields from which you must
choose one.
|
[ ]
$
< >
A vertical line indicates a choice between two or more parameters, for example:
parameter | parameter
Parameters are also indicated as follows:
���������
���������
���������
Brackets indicate optional parameters or fields.
The first character of each MCB command is a dollar sign to distinguish it from a
transaction code.
Less than and greater than symbols in procedural examples indicate the default
response to a system prompt.
UPPERCASE
Commands and other characters that you must type in to activate the command are
shown in uppercase. You do not need to enter the commands or characters in
uppercase, however.
7833 1568–004 1–3

Introduction
lowercase italic
bold
Variable information (such as commands and parameters) appears in lowercase italic.
In examples showing interaction between user and the system, user entries are
bold.
Note: Braces, brackets, and vertical lines are not part of the command syntax; do not
type them in. Unless otherwise indicated, use blank spaces (one or more) to separate
fields.
Miscellaneous Notation Conventions
The following notation conventions appear in word diagrams.
Asterisk (*)
An asterisk in front of a word number denotes an overlay of a word. The following
example shows an overlay of word 02:
02 P$HDR (output header offset)
*02 P$RSTYP P$CCS
Dots
P$HDRSIZE P$LKEY
header size logical function key
In this example, the half word P$HDR can be replaced with the quarter words
P$RSTYP and P$CCS.
Two dots (..) indicate continuation of number in the word number column.
Three dots (...) indicate continuation within the word.
1–4 7833 1568–004

Section 2
Components and Mass Storage Files
2.1. Components
The main components of the MCB are
• Background run
• Main common bank
• Main storage buffer common banks
• Position identifier (PID) table common banks
• Message retention file (MRF) control table common banks
• Site-id table common banks
• Range table common banks
• Validation table index (VINDEX) common bank
• Message recovery banks
• MCB initialization
• Message release processing
• MCB dumping
• II-keyin processing (from the OS 2200 console)
• Network administrator action command processing
• Statistics gathering and reporting
The background run executes as a real-time program, continuously locking the MCB
common I-bank in main storage. Much of the infrequently used background run
functional capability resides in overlay segments that MCB loads into main storage
through an ER LOAD$ when needed.
7833 1568–004 2–1

Components and Mass Storage Files
MRF
Files
MCB
Extended Mode
Common Bank
MCB Message
Recovery Banks
Integrated
Recovery
Utility
CMS 1100
Main MCB
Common Bank
OS 1100
Executive
EM
BM
User Program
User Program
CFIGUTIL
MRF
Control File
2.1.1. Background Run
PIX
Files
MCB Main Storage
Buffer Common
Banks
MCB PID Table
Common Banks
MCB
Background Run
MCB MRF Control
Common Banks
VINDEX
Common Bank
Site-id Table
Common Banks
Range Table
Common Banks
Figure 2–1. Components and Mass Storage Files
Config
When using the MCB, the background run (a batch program) executes continuously. The
background run consists of multiple program activities and multiple program banks.
The background run performs these functions:
• MCB initialization
• Message release processing
• MCB dumping
• II-keyin processing (from the OS 2200 console)
2–2 7833 1568–004

• Network administration action command processing
• Statistics gathering and reporting
Components and Mass Storage Files
The background run executes as a real-time program, continuously locking the MCB
common I-bank in main storage. Much of the infrequently used background run
functional capability resides in overlay segments that MCB loads into main storage
through an ER LOAD$ when needed.
2.1.2. Main Common Bank
The main MCB common bank contains instructions and control information. It is based
on BDR0/ and entered with a Load Bank and Jump (LBJ) instruction from either CMS or
an application program when a function is requested. During execution, MCB common
banks are temporarily based on BDR3 by the main MCB common bank.
The installed version of the main common bank is a dummy bank. During MCB
initialization, the installed version is entered by the background run, reloaded through ER
BANK$, contracted to the proper size through an ER LCORE$, and written by the
background run. This allows a revised MCB common I-bank to be installed without
reinstalling the MCB product or rebooting the operating system.
To protect the integrity of the MCB against errant application programs, the main
common bank is configured with a guaranteed-entry point (GEP).
2.1.3. Main Storage Message Common Banks
Main storage message common banks (CORBNK) contain message staging buffers and
other temporary work buffers. Up to eight CORBNKs can be configured to hold
messages in main storage.
Also, as with the main MCB common bank, the installed version of the main storage
buffer message banks are dummy banks whose actual contents are established by the
background run.
Once MCB is initialized, the main storage message common banks cannot be based
directly by an application program. Any attempt to do so causes the application program
to terminate in error.
2.1.4. Position Identifier (PID) Table Common Banks
The PID table common banks consist of a small number of control information words for
each PID. Up to 33 PID table common banks can be configured.
The installed PID table common banks are dummy banks. The actual contents are
established at MCB initialization by the background run. The PID table common banks
cannot be based directly by an application program once the MCB is initialized. Any
attempt to do so causes the application program to terminate in error.
7833 1568–004 2–3

Components and Mass Storage Files
2.1.5. Message Retention File (MRF) Control Common Banks
The MRF control common banks contain a control table for each configured MRF file. Up
to two MRF control common banks can be configured.
The installed MRF control common banks are dummy banks. The actual contents are
established at MCB initialization by the background run.
The MRF control common banks cannot be based directly by an application program
once the MCB is initialized. Any attempt to do so causes the application program to
terminate in error.
2.1.6. Site-id Table Common Banks
The site-id table common banks contain entries that associate a site-id with a PID
number. Up to nine site-id common banks can be configured.
The installed site-id table common banks are dummy banks. The actual contents are
established at MCB initialization by the background run.
The site-id table common banks cannot be based directly by an application program once
the MCB is initialized. Any attempt to do so causes the application program to terminate
in error.
2.1.7. Range Table Common Banks
The range table common banks contain entries for groups of consecutive PID numbers.
Up to five range table common banks can be configured.
The installed range table common banks are dummy banks. The actual contents are
established at MCB initialization by the background run.
The range table common banks cannot be based directly by an application program once
the MCB has been initialized. Any attempt to do so causes the application program to
terminate in error.
2.1.8. VINDEX Common Bank
The validation table index (VINDEX) common bank contains the validation table index
(VALTAB), which identifies transaction programs by 6-character codes.
The installed version of the VINDEX common bank is also a dummy bank. The actual
contents are established by the background run.
The VINDEX bank cannot be based directly by an application program. Any attempt to do
so causes the application program to terminate in error.
If TRMXVT in the Exec configuration is set to a value greater than 8190, the MCB uses
an ER VT$RD to access the VINDEX. In this case, the VINDEX common bank is installed,
but empty.
2–4 7833 1568–004

Components and Mass Storage Files
2.1.9. Message-Recovery Bank for Short Recovery (MSGBNK)
The MSGBNK is constructed and installed by the MCB, and is used by the Integrated
Recovery Utility (IRU) during short message-recovery processing. This bank is installed as
an alternate file common bank (AFCB).
2.1.10. Message-Recovery Bank for Long Recovery
(MSGLNGBNK)
The MSGLNGBNK is constructed and installed by the MCB, and is used by the IRU
during long message-recovery processing. This bank is installed as an AFCB.
2.2. Mass Storage Files
Three types of mass storage files are associated with the MCB:
• Message retention files
• MRF control files
• PID index (PIX) files
Each of these TIP/Network Database Server files is accessed by the main MCB common
bank using an ER DM$IOW. For initialization and recovery, the background run and
message recovery common bank can also access these files.
2.2.1. Message Retention File (MRF)
One MRF is used for overflow storage of nonrecoverable message text. All messages
are staged block-by-block in main storage buffers. When main storage buffer space is
exhausted, nonrecoverable message text is moved to MRF file 0/.
One or more message retention files may be used for storage of recoverable message
text. These are known as MRFs 1 through n, where n is less than or equal to 63. The
message source or destination (PID) and the message type (input or output) determine in
which MRF the message is stored. A recoverable message is staged block-by-block in
main storage buffers. It is always written to the proper MRF, but is not necessarily
deleted from main storage. As buffer space permits, recoverable message text is
retained in main storage to avoid a subsequent mass storage read when the text is
accessed for processing.
2.2.2. MRF Control File
The MRF control file contains information about the allocation and release of MRF space.
Each MRF is composed of one or more fixed-length segments. Each segment is further
divided into one or more fixed-length message blocks. The number of segments in an
MRF can vary. Each segment in an MRF is free, active, or retired at any given time.
7833 1568–004 2–5

Components and Mass Storage Files
A free segment does not have any allocated message blocks. Any MRF may contain one
or more free segments at any time.
An active segment is the segment in which message block allocation currently occurs.
An MRF can have a maximum of two active segments at one time: an input message
allocation segment and an output message allocation segment.
A retired segment has all blocks allocated. Message blocks are individually released
during the normal course of message processing so the segment remains retired until all
blocks are released. Then the segment becomes a free segment.
The MRF control file retains a record during a system crash, or MCB abort, of the current
segment states for each of the recoverable MRFs, 1 through n. The number of MRFs, n,
is determined by MCB configuration. (See the MCB Installation Guide for more
configuration information.) When any segment state changes, the system updates the
MRF control file. The MRF control file is not updated as each message block is allocated
or released because performance would suffer. The message recovery bank restores the
allocation controls after system recovery.
The MRF control file also contains a copy of the PID table. If the MCB configuration has
the RESILIENT SGS set to YES, session-related changes to PIDs are copied into the MRF
control file. This session information is available when you recover a failed MCB. The
session information saved in this file includes exclusive use, input-only exclusive use,
outbound open, mode change, and session close notification.
2.2.3. PID Index File (PIX)
A recoverable message may be recallable; this is the choice of the application designer.
When you supply a PID (source or destination), the message type, and the message
number, the MCB can locate a recallable input or output message from its MRF after the
message is processed and released if the subject message blocks are not reallocated.
Since MRF space allocation is circular, the file wraparound time determines the
maximum recall period.
To recall a recoverable message, the MCB makes an entry in the PID index file (PIX). In
this way, the MCB retains the MRF location of the most recent input and output
messages declared recallable and recoverable. The actual number of these messages is
determined by MCB configuration. See the MCB Installation Guide for more configuration
information.
Note: A recoverable message is not automatically recallable. Message recall is an
optional message attribute due to the I/O overhead implied by a PIX file update.
One or more PIX files can be configured in the MCB. A PIX file of a PID is a function of
the MRF that retains its recoverable input and output messages.
The contents of the PIX files are not recovered or restored by the short or long message
recovery processes. After short or long message recovery, the data in the PIX files is
accurate up to the time the step control application group aborts, as long as the PIX files
are not corrupted.
2–6 7833 1568–004

Section 3
Message Processing – General
Concepts
3.1. Message Types
The Message Control Bank (MCB) recognizes four types of messages:
• Input Messages
An input message arrives through Communications Systems Management System
(CMS) from an external source identified by a logical terminal-id (PID). The PID is an
internal numeric identifier. The physical location of the originating terminal point is
not communicated to the MCB. The destination of an input message is an application
program.
• Output Messages
An output message is created by an application program and directed to an external
destination identified by a PID. The physical location of the destination terminal point
is not communicated to the MCB.
• Pass-Off Messages
A pass-off message is created by an application program and directed to another
application program.
• Checkpoint Messages
You generate and use a checkpoint message in a long-running, recoverable,
application program. The program (transaction or online batch) uses this message to
break its processing into a sequence of smaller steps. In the event of a failure, you
can restart the program at the most recent checkpoint.
Only transaction and online batch programs can use checkpoint messages.
7833 1568–004 3–1

Message Processing – General Concepts
3.2. Message Attributes
A message may have the following optional attributes:
• Recoverability
• Deferred queuing
• Numbering
• Audit text
• Recallability
• Low main storage priority (subject to early paging if storage space is needed)
• Reduced output path length (ROPL)
See 3.3.2 for a description of how these attributes are established for each VINDEX entry
when you use the VTBUTL utility program.
3.2.1. Message Recoverability
If an input or pass-off message is declared recoverable, the message remains intact
across system or program failures until it is successfully delivered to the proper
application program and processed by that program.
If an output message is declared recoverable, the message remains intact across system
failures until the message transmission is acknowledged by CMS.
A checkpoint message is recoverable by definition.
3.2.2. Deferred Message Queuing
An output message that is declared deferred is not forwarded to CMS until the
application program generating the message reaches a processing success point.
A pass-off message that is declared deferred is not queued for processing by the target
application program until the application program that is generating the message reaches
a processing success point.
A recoverable output or pass-off message must have the deferred queuing attribute by
definition, since this is how message recovery is synchronized with database updates.
You can assign the deferred queuing attribute to a nonrecoverable output or pass-off
message. Deferred queuing is preferred even for a nonrecoverable message because it
ensures that external notification of program processing completion does not occur
unless processing is complete.
A checkpoint message is deferred by definition.
3–2 7833 1568–004

3.2.3. Message Numbering
Message Processing – General Concepts
You can number recoverable input and output messages in two ways:
• Intelligent message numbering
• Unintelligent message numbering
If a recoverable input message is numbered and the associated PID is configured with
unintelligent numbering, a unique message number is displayed in a header with the
input acknowledgment message. If an output message is numbered, and the message
requests a header (see 5.9.2), the message number can be displayed. You must
configure PIDs that send or receive numbered messages with either the intelligent or the
unintelligent numbering option. See the MCB Installation Guide for more information
about numbering options.
If a numbered message is sent to a PID that is not configured for message numbering,
the numbering option is removed from the message recovery options. This applies to
single destination outputs as well as multiple destination outputs.
For intelligent numbering, an input or output message must have the message
numbering option set. The message can be either recoverable or nonrecoverable.
For unintelligent numbering, an input or output message must have both the message
numbering option and the recoverable option set.
3.2.3.1. Intelligent Input
The sending application program sends a message number with the message text. CMS
extracts this number from the message protocol and presents it to MCB along with the
text. MCB accepts the message as it is and does not check message numbers for
duplication or sequential order. You are responsible for the uniqueness of message
numbers.
If CMS does not present a message number when it stores the input, intelligent
message numbering does not occur. If CMS does present a message number, and the
message is recoverable, the Exec message number table is updated with this number for
the input PID.
3.2.3.2. Intelligent Output
The message number can be generated either by the application program or the Exec.
MCB looks for the message number in the application interface packet. If a number is in
the packet, MCB uses this number. If the packet does not contain a message number,
MCB uses the number generated by the Exec. MCB does not check the message
number supplied by the application.
MCB presents the message number to CMS along with the output message text. CMS
may send the number as part of the message protocol.
7833 1568–004 3–3

Message Processing – General Concepts
If the message number field in the interface packet is nonzero, the output message can
be either recoverable or nonrecoverable. If the message number field is zero, the output
message must be recoverable. If the message number field is zero and the message is
nonrecoverable, an error status is returned. If the message is recoverable and recallable,
it can be recalled using the associated message number.
Note: Be careful when you use intelligent message numbering to generate message
numbers. Duplicate message numbers can produce erroneous message recalls and
delivery notifications. When an application program-supplied message number is used for
an intelligently numbered output message, the Exec message number table is not
updated for the destination PID.
3.2.3.3. Unintelligent Input
MCB receives a message number generated by the Exec and associates this number
with the input message. After the message is staged, MCB sends to the originating
terminal an input acknowledge message that contains the message number. The input
acknowledge message indicates that the input message is queued to the Exec with
guaranteed processing.
3.2.3.4. Unintelligent Output
MCB receives a message number generated by the Exec and can create an output
message header as part of the output message text. The output message header
contains the message number; its position within the message text is determined by the
application program. CMS transmits the message number as message text.
In unintelligent numbering, message numbering is not apparent to CMS. MCB transmits
the input acknowledge message and the output message headers.
3.2.4. Audit Text
The audit text message attribute records the text of a message on the audit trail. This
option is allowed only for a recoverable message. The text of a recoverable message is
always written to a message retention file. If preferred, the text of a recoverable
message can also be written to the integrated recovery audit trail. The message
retention file provides for recovery across a system failure. Audit trail retention provides
for long message recovery and for accounting or statistical analysis of message traffic.
Note: If an unaudited recoverable message was written to an MRF, the message is not
rewritten during a long message recovery. If the MRF containing the message was
corrupted and rebuilt, and the message is still queued or active after the long message
recovery, the recovery will fail. If the recovery fails, you can initialize the application
group. All recoverable messages will be lost. To run long message recovery successfully,
include the audit attribute on all recoverable messages. If you do not want to run long
message recovery, do not use the audit attribute.
3–4 7833 1568–004

3.2.5. Message Recall
Message Processing – General Concepts
The optional message recall attribute allows a numbered, recoverable input or output
message to be recalled. For such a message, MCB creates a PIX file entry that serves as
an index with which the message can be recalled. To recall it, you must specify a PID,
the message number, and the message type.
When a message is recalled, the system guarantees that the recall is successful only
within the limits of MRF and PIX file space. The MRF file space can be reallocated if too
much time has elapsed since the message was created. With respect to PIX, the system
retains a record of only the N most recent recallable input and the n most recent
recallable output messages per PID. See the MCB Installation Guide for information on
configuring PIX length on the P$ID statement.
3.2.6. Low Main Storage Priority
Low main storage priority is an optional message attribute that determines whether the
message text has low priority (subject to early paging) in main storage with respect to its
main storage residence in MCB staging buffers. This attribute is allowed for both
recoverable and nonrecoverable messages. It adjusts the message buffering scheme
used by MCB and is used for messages with a relatively long life.
This attribute applies to all four message types: input, output, pass-off, and checkpoint.
3.2.7. Reduced Output Path Length (ROPL)
ROPL is an optional message attribute that determines whether a message will be sent
with the ROPL interface, significantly reducing path length and improving throughput. An
ROPL message can replace a step control message when you do not need recoverability,
unintelligent message numbering, message deferment, or Transaction Processing (TIP)
message security.
An ROPL message is queued to CMS with an ER RT$OUT instead of an ER TIP$Q. ROPL
messages do not use ERs TIP$ID, TIP$TA, TIP$TC, or TIP$XMIT. A step control message
is used instead of an ROPL message when:
• A message is sent to a PID with a closed session.
• A message is sent to a group PID (or with the multiple destination list), and any
single PID within the group has a closed session.
• An output message designated as recoverable or deferred is sent by an application
program to a PID.
• An output message is sent by an application program to a group PID (or with the
multiple destination list), and any PID in the group is open to a different CMS run.
• The program sending the message does not have the V execution option (see
3.5.14).
All destination PIDs must have a session open to the same CMS number. If any PIDs
have sessions open to different CMS numbers, the message is handled as a step control
message for all PIDs.
7833 1568–004 3–5

Message Processing – General Concepts
If CMS terminates when using ROPL output messages with an unacknowledged, paged,
ROPL output message, the MRF identifiers (MID) for the message are orphaned. The
MRF blocks that contain the message are suspended until MCB is terminated.
If a CMS session is closed with ROPL messages queued, and another session is opened
to a second application, the queued ROPL messages from the first application remain
queued and undelivered until the session is reopened to the first application.
If CMS spooling is enabled, and the APPLICATION network definition statement (NDS) or
PID NDS is configured to negatively acknowledge (NAK) queued messages when sent to
PIDs with stopped or closed sessions, any ROPL messages are negatively
acknowledged and sent to the error notification program (ENP) with the NAK reason. If
you create a print file for these messages, your error notification program (ENP) can
generate excess print files.
When CMS TIPCSU terminates normally, queued ROPL messages are not acknowledged
and are sent to the ENP with the NAK reason. Again, there may be many print files.
3.3. Validation Table Considerations
The target of an input or pass-off message is identified by a 1-character to 6-character
transaction code, and is identified internally by a corresponding entry in the VINDEX
table. The VINDEX table is constructed by executing the TIP utility program VTBUTL. The
table contains an entry for each valid transaction code. See the Transaction Processing
Administration and Operations Reference Manual.
Each VINDEX entry contains the following fields:
• Application group number
• Recovery options
• Access mask
• Input queue priority
• Transaction program number
3.3.1. Application Group Number
Within one system, transaction processing can take place simultaneously using the
communications message-buffer pool (COMPOOL) and one or more MCBs. Each
processing subdivision is called an application group. (See the Integrated Recovery
Conceptual Overview.) Since there is only one VINDEX table on an OS 2200 host
system, each VINDEX entry contains a parameter that defines the application group
number to which the VINDEX entry applies. Use the AUDIT parameter to define the
VINDEX entry when you execute the VTBUTL utility. The AUDIT parameter and the
application group number defined in the MCB application must be the same.
If the AUDIT parameter is nonzero and the APNUMBER does not match, input or
pass-off messages are rejected with the invalid transaction code error.
3–6 7833 1568–004

3.3.2. Recovery Options
Message Processing – General Concepts
To ensure that user programs associated with a recoverable application group are
recoverable, a program must specify recoverable steps. When you specify message
recovery options I through T in the validation table (VALTAB) entries associated with the
application group’s transaction programs, it implies an MCB interface. The interface
writes recoverable messages to the application group’s message retention file (MRF) and
audited messages to the audit trail.
When you execute the VTBUTL utility program, the RECOVERY parameter establishes a
recovery options field for each VINDEX entry. Table 3–1 defines attributes for the given
transaction code.
Letter
Option
Bit
Table 3–1. Recovery Options
Explanation
I 17 Low-priority output message for main storage.
J 16 Output message recall.
K 15 Output message numbering.
L 14 Audit output message text.
M 13 Output message recoverable.
N 12 Defer output message.
O 11 Low-priority input message for main storage.
P 10 Input message recall.
Q 09 Input message numbering.
R 08 Audit input message text.
S 07 Input message recoverable.
T 06 Defer input message.
U 05 Release handling for recoverable locks at commit (integrated
recovery only)
V 04 Reserved.
0 = all recoverable locks released at commit time regardless of
whether they were specifically unlocked.
1 = all recoverable locks that have been explicitly released (by RU,
UA, UN, or WR) are released at commit time. If a lock has not
been explicitly released, retain that lock.
W 03 User-specified requeue action. W option is valid only if X option is
set.
0 implies the message is requeued.
1 implies the message is queued to the system error program.
7833 1568–004 3–7

Message Processing – General Concepts
Letter
Option
Bit
X 02 Rollback default action.
Table 3–1. Recovery Options
0 implies the step is resumed.
1 implies the step is terminated.
Y 01 Commit default action.
0 implies the step is advanced.
1 implies the step is terminated.
Z 00 Recoverable program step.
Explanation
The foregoing options are defined in three 6-bit subfields:
• Output message attributes (bits 17-12)
• Input message attributes (bits 11-6)
• Program execution attributes (bits 5-0)
3.3.2.1. Output Message Attributes
Six bits define the attributes that apply to any output message generated by this
transaction during execution (unless the calling program supplies attributes to MCB on
the output message staging request). These attributes are explained in 3.2.
3.3.2.2. Input Message Attributes
Six bits define the attributes that apply to any input or pass-off message directed to the
transaction code. These attributes are explained in 3.2.
3.3.2.3. Program Execution Attributes
These bits specify the recovery-related attributes that apply to processing the
transaction:
Bit 0
This bit defines a program as recoverable because the program creates recoverable
output, pass-off, or checkpoint messages, or updates recoverable Network Database
Server database files. If the bit is set, audit trail records are created during execution
for recovery purposes. The bit must be set if the input message is recoverable (bit 7
set). The bit may or may not be set if the input message is nonrecoverable (bit 7
clear).
3–8 7833 1568–004

Bit 1
Bit 2
Message Processing – General Concepts
The program step is advanced (if this bit is not set) or terminated (if it is set) when a
commit point such as an Network Database Server FREE/DEPART is reached, unless
the program step action is specified on the commit request.
The program step is resumed (if this bit is not set) or terminated (if it is set) when
rollback occurs, unless a program step action is specified on the rollback request,
such as an Network Database Server DEPART WITH ROLLBACK. For information
about commit, rollback, and program steps, see the Integrated Recovery Conceptual
Overview.
3.3.3. Access Mask
The VTBUTL parameter MASK defines terminal classes from which this transaction code
is entered. During MCB generation, each PID is defined as a member of a terminal class.
When an input message is received from a PID, the MCB verifies that the associated
terminal class can access the transaction. If the MASK is unspecified, access control is
not imposed. See the P$ID stream generation statement (SGS) in the MCB Installation
Guide.
3.3.4. Input Queue Priority
The VTBUTL parameter QPRIORITY defines the terminating node within the input queue
tree structure where the input or pass-off message is queued for processing. If the
message is processed by a transaction program, it is dequeued by TIP scheduling based
on priority and concurrency considerations. If the message is processed by a batch or
demand program, the program issues an MCB request to dequeue the next message
from the specified terminating node. In this case, the specified terminating node or a
node above it in the tree structure should have a maximum concurrency of zero to
bypass the node with TIP scheduling. For a more complete description of the input
queue, see the Exec Installation and Configuration Guide.
3.3.5. Transaction Program Number
Each transaction code has a corresponding program number. Although CMS and user
programs use transaction code to identify a program when calling MCB, MCB finds the
program number and passes it to the Exec to identify the program to be scheduled. For
the MCB features of exclusive use, conversational link, output delivery notification, and
outbound session open, MCB saves the program number, but not the corresponding
transaction code.
Use caution if you modify the VALTAB records in an active system. If you change the
program numbers that correspond to the various transaction programs, it is possible that
wrong programs may be scheduled to process messages that are already on the input
queue at the time the VALTAB updates are made, and the programs scheduled as a
result of the MCB features mentioned might not be the programs you intend to be
scheduled.
7833 1568–004 3–9

Message Processing – General Concepts
3.4. Message Processing Interfaces
There are three interfaces to MCB:
• A CMS interface
• An application program interface
• A TIP primitive interface
Display Processing System and application programs that do not use TIP primitives use
the application program interface. The application interface adds functions beyond those
of the TIP primitives. The TIP primitive interface is a compatible replacement for the
analogous COMPOOL primitives for migration to MCB.
Each time a CMS or application program activity uses the MCB, it must first register with
MCB by executing an initialization function call. MCB returns an error status to any
program requesting data handling before the initialization request. MCB uses the
initialization to establish control tables for a calling program and to register for termination
notification with an ER TRMRG$. This allows MCB to regain control if there is an error in
the calling program when it is not executing in MCB. MCB regains control to clean up
tables and return transient facilities to the program in error.
When the calling program completes processing normally, it makes a termination call to
MCB. This allows an ER TRMRG$ to deregister and return transient facilities to the
program.
MCB also maintains control through common data bank contingencies. If an application
program executing in MCB receives an asynchronous contingency, the contingency
routine receives control before MCB returns a contingency to the program. This allows
execution to complete immediately. Then MCB queues the contingency to the user
through an ER CQUE$.
While executing on behalf of the calling program activity, MCB interfaces as needed
through Executive requests to the step control and audit control components of the
Exec.
For the CMS or application interface, MCB assumes that any input or output message
has three parts:
• Interface or control parameters
• Auxiliary information
• Text
For some message types, the auxiliary information area may not be required.
For the TIP primitive interface, MCB assumes that any input or output message contains
these parts:
• A required message parameter area (MPA)
• An optional user parameter area (UPA)
• Text
3–10 7833 1568–004

Message Processing – General Concepts
The MPA and UPA are analogous to the MCB interface parameters area and the auxiliary
information area of the CMS and application interfaces, but the packet fields have
different definitions. Figure 3–1 shows each of these parts for the three types of
interfaces.
00
07
010
CMS 1100
Packet Interface
MCB
Interface
Parameters
Auxiliary
Information
Text
Text
Text
Application Program
Primitive Interface
Message
Parameter
Area (MPA)
User
Parameter
Area (UPA)
(optional)
Text
Application Program
Packet Interface
MCB
Interface
Parameters
7833 1568–004 3–11
00
017
020
021
Figure 3–1. Message Format
Site-id
(optional)
Auxiliary
Information
In a CMS program using TIP session control, A0 points to word 0 of the interface packet.
The word immediately before word 0 is expected to contain the TIP session identifier on
all appropriate calls to MCB (see Figure 4–1).
The Load Bank and Jump (LBJ) instruction that calls the MCB common I-bank must base
MCB on BDR0. Before the LBJ, the application program must have a bank based on
BDR0. See 5.2 for more details on calling the MCB.
Text
Text
Text

Message Processing – General Concepts
In Figure 3–1, the packets for the CMS and application program interfaces correspond to
the first block shown under CMS and the application program. The MCB interface
parameters are contained in words 00 to 07 for the CMS interface, and in words 00 to
017 for the application program interface.
A special packet version exists for the application interface when a program uses site-ids.
Two extra words, 020 and 021, exist for the site-id in this case.
The auxiliary information starts at word 010, 020, or 022 of the respective packet. Its
length is defined by a parameter in the first part of the packet (P$AUX). MCB does not
alter this auxiliary information. It is passed between CMS and application programs so
the application can construct proper output and properly interpret input. The specific
content of this auxiliary information area is dependent on the device handler that sends
the message to, or receives the message from, the network. MCB also allows an
auxiliary information area to be present in a pass-off or checkpoint message. In this case,
MCB passes the auxiliary information to the receiving program.
The blocking factor for message control information and text within MCB is an internal
MCB consideration. CMS and the application program interfaces can store and retrieve
message text by specifying any number of characters per request.
3.4.1. Basic Mode Low-Level Interface
Both the CMS and basic mode application program interfaces share the following calling
sequence:
��� ��������� �������
����� ����������
��� �����������
MCB destroys the contents of the program’s registers X11, A0 to A5, A16 to A19, and
R0 to R3.
The MCB entry point is 01000. This 18-bit value is defined in the CBEP$$MCBn element
produced from the MCB build, where n is the step control application number. The
entry-point label is MCB$ENT.
The MCB BDI is defined in the CBEP$$MCBn element in the utility file from the MCBBDI
configuration SGS. Two labels are produced: MCBBNK and MCBBNK$. These labels are
not unique if more than one MCB is installed. You must resolve these two labels at
collection time. See 3.4.2.
Control returns to the instruction following the LBJ, unless the calling program specifies
some other return point in the packet (P$RTN). The P$RTN packet cell cannot be used if
the CBSECURITY configuration parameter is set to YES. On return, A0 contains zero in
H1 and the packet address in H2. A1 contains a status. Specific status codes are listed in
Appendix B.
3–12 7833 1568–004

Message Processing – General Concepts
3.4.2. Application Programming Considerations
Multiple MCB applications contain multiple MCB code banks. You must be sure to link a
transaction program and the MCB code bank correctly. For further reference, see the
examples listed in Table 3–2.
Table 3–2. Example Programs
File Name Explanation
GN.MCBDEF-UCOB Example UCOBOL definitions for the MCB packet
GN.MCBDEF-UFTN Example UFORTRAN definitions for the MCB packet
GN.EXAMPLE-UCOB Example UCOBOL program
GN.MCBDEF-MASM Example Meta-Assembler definitions for the MCB packet
GN.EXAMPLE-ENP Example error notification program
GN.EXAMPLE-SEP Example system error program
GN.EXAMPLE-FTN Example FORTRAN program
GN.MCBDEF-FTN Example FORTRAN definitions for the MCB packet
GN.MCBDEF-UMASM Example UMASM definitions for the MCB packet
GN.EXAMPLE-COB Example COBOL program
GN.MCBDEF-COB Example COBOL definitions for the MCB packet
GN.EXAMPLE-UFTN Example UFORTRAN program
GN.EXAMPLE-UC Example UC program
GN.MCBDEFCOPY/H Example UC definitions for the MCB packet
GN.UCLINK Example of link of a UC program
GN.UCMCBLIB Example library of MCB UC libraries
The following examples, in basic mode, show correct linkage for an example
application number 3. For information on using extended mode, see the C
Compiler Programming Reference Manual Volume 1, C Compiler
Programming Reference Manual Volume 2, COBOL Compiler Programming
Reference Manual Volume 1, COBOL Compiler Programming Reference
Manual Volume 2, FORTRAN Compiler Programming Reference Manual
Volume 1, FORTRAN Compiler Programming Reference Manual Volume 2,
and Application Development Solutions Programming Guide.
7833 1568–004 3–13

Message Processing – General Concepts
In basic mode, there are several methods to resolve the BDI and entry-point values of
multiple MCBs:
• In MASM programs, use the generic bank name MCBBNK or MCBBNK$:
����� ���������� �� ����� �����������
��� ����������� �� ��� �����������
You must resolve the generic label MCBBNK or MCBBNK$ with one of the following
three methods:
− The first method requires the RB element name CBEP$$MCB3. The MAP
directive is:
�� ����������
Though you do not need to know the MCB product file name, you do need to
know the application number (in this case, 3)
− The second method requires knowledge of the MCB bank’s BDI. The MAP
directive is
��� ���������������
400600 is the BDI of the MCBBNK bank for application 3.
− The third method requires knowledge of the MCB product installation file name.
The MAP directive is
��� ���������
• In ASCII FORTRAN (FTN) and COBOL (ACOB) programs that use the primitive
interface, you must use one of the MAP directives listed in the previous bullet.
3.4.2.1. Basic Mode and Extended Mode Interfaces
A few distinctions can be drawn between the basic mode interface and the extended
mode interface.
You can use an alternate return point with the basic mode interface. This 18-bit address
is kept in cell P$RTN in the interface packet. In extended mode, the RTN instruction does
not allow return to a specific address. Rather, the RTN instruction signals that
information contained in the most recent return control stack (RCS) frame, created by the
call (or LBJ/CALL), is being used.
You cannot use the alternate return mechanism in extended mode. Packet cell P$RTN
must be set to zero. Some users of this mechanism are guaranteed-entry point (GEP)
common banks, that force the MCB to return to their GEP because an in-line return is
impossible. This workaround is not necessary in extended mode, because the RTN
instruction allows execution to resume at any location within a GEP common bank.
3–14 7833 1568–004

Message Processing – General Concepts
Batch programs, demand programs, TIP application programs, mapped absolute
elements, statically linked and dynamically linked object modules (OM) are all eligible to
call the EMMCB in extended mode. The MCB product requires only that the basic mode
interface rules be followed for MCB callers, and that Universal Compiling System (UCS)
interface rules be followed for EMMCB callers.
3.4.2.2. Mixed-Mode Considerations
Programmers constructing mixed-mode absolute elements must be aware of the
method by which the entry point is resolved. The extended mode entry point
(MCB$ENT = 202662001000) is defined only in the OM element CBEP$EMMCBn, where
n is the step control application number. A program that contains both basic mode and
extended mode banks cannot force the Collector to recognize the OM element
CBEP$EMMCBn. The basic mode entry point (MCB$ENT = 01000) is defined only in the
relocatable element CBEP$$MCBn, which is recognized by the Collector. Extended mode
and basic-mode interfaces are mutually exclusive. A mixed-mode program can use either
interface, but not both.
3.5. Optional Features
An application may use the following optional message processing features:
• Conversational link
• Multiple destination output
• Rotary output
• Unsolicited output
• Delivery notification
• Test and training modes
• MCB session control
• Exclusive use of a PID
• PID site-id table
• IBM_ terminal to logical UTS 400 terminal
• Input message control
• Output message control
• TIP session control
• Program options (VALTAB and XQT)
• Recovery bank protection
• TIP message security
• MCB file security
• User session reestablishment
• Partitioned Applications
7833 1568–004 3–15

Message Processing – General Concepts
• Statistics monitor transaction
• MRF threshold control
• User message control
3.5.1. Conversational Link
The conversational link feature allows an application program to direct input from a
specific PID to a specific transaction, without requiring a transaction code. The
application establishes the link to the transaction when it issues an output to the PID that
contains conversational link setup parameters. After the link is established, the next input
message from the PID is directed to the specified transaction. After input is received
from the PID, the conversational link is cleared. The link must be reestablished to direct
any additional input from the PID to the transaction.
An established, unused link can be cleared only by another output that establishes a new
link. The system retains the most recent link established with a PID until an input
message is received from that PID. If the application requires that output messages be
inhibited until the input link is used, the exclusive use feature of the MCB should be
considered as an alternative to conversational link.
Use the conversational link feature when the application system needs direct, interactive
control of an auxiliary device at a terminal, such as a tape cassette on a UNISCOPE
display terminal. In this mode, device status conditions are directed to the application in
the form of an input message to the program, identified by the conversational link
transaction code. The auxiliary information area defines how the conversational link is
used in this manner.
In the event of component or system failure, conversational link is retained across a
recovery of CMS and MCB only if CMS is configured RESILIENT and MCB is configured
RESILIENT YES.
3.5.2. Multiple Destination Output
An output request can explicitly direct an output message to multiple destinations by
specifying a list of output PIDs.
An output request can implicitly direct an output message to multiple destinations by
specifying a group PID. The members of a given group PID are established by
MCBsystem generation.
3.5.3. Rotary Output
An output request can explicitly direct an output message to a group PID with a
specification that the message be sent to only one member of the group PID. The
system distributes messages directed in this manner among the members of the group
PID on a rotary basis. This is useful, for example, when hard copy messages need to be
continuously delivered to a physical location with more than one output device. In this
situation, it does not matter which device receives a given message, but it is better to
3–16 7833 1568–004

Message Processing – General Concepts
keep all of the devices equally busy to distribute the workload and to prevent premature
mechanical deterioration of one or more devices.
3.5.4. Unsolicited Output
An output request can explicitly direct an unsolicited output message to an interactive
terminal. The message is queued and the terminal operator is notified of possible
queued, unsolicited output, for example, through a message-waiting indicator. When the
operator selects the message to be dequeued, for example, through a message-waiting
function key, the message is transmitted. If both unsolicited output and conversational
link are specified for a message, CMS does not transmit the text of the message to the
terminal. The conversational link is used when the request for the message is received,
but the output is not sent.
3.5.5. Delivery Notification
When the system stages a given output message, the calling program may request that
the application system be notified when delivery occurs. This is useful, for example, to
pace continuous output to a printer or tape cassette. The notification occurs as an
internally created and scheduled pass-off message stating that a message to a given PID
was transmitted.
Requesting delivery notification on a message does not prevent the application from
continuing with additional output messages. For example, the application may create
continuous output messages in groups of five with delivery notification requested on the
fifth message in each set. The program does not continue with the next set of output
messages until delivery notification occurs. This prevents the system from being flooded
by output from one program.
3.5.6. Test and Training Modes
Four modes of application program execution are recognized by TIP and Universal
Database Control:
• Normal
• Training
• Test
• Test/Training
3.5.6.1. Training Mode
Training mode trains a new end user of an application system.
In training mode, you invoke and execute a normal production copy of an application
program. The application program is not notified that it is executing in training mode.
During execution, an alternate database is accessed and updated, if appropriate. This
alternate database is specifically set up for training. It is often a functional subset of the
online database, and training functions are limited accordingly.
7833 1568–004 3–17

Message Processing – General Concepts
3.5.6.2. Test Mode
Test mode is for debugging a new or revised application program before putting it into
production. In test mode, as opposed to training mode, you invoke an alternate copy,
presumably one that has not been debugged, of an application program rather than the
normal production program. Like training mode, test mode is transparent to the
application program. Therefore, you do not need to modify source code after you test
your program.
During execution in test mode, the system accesses the online database and captures
attempted database updates. The system cannot update the online database because it
interprets the application program as not debugged.
In addition to capturing database updates, the system imposes other restrictions on
execution results to minimize the impact upon the online production system.
See 4.5.10 for a description of test mode usage on systems configured for concurrent
operation of COMPOOL and MCB under CMS. Also, see the Transaction Processing
Administration and Operations Reference Manual for a description of the VALTAB status
bits J and L. The L bit defines how the test copy input is stored with MCB or COMPOOL.
3.5.6.3. Test/Training Mode
In test/training mode, you can debug a new or revised application program with fewer
restrictions, usually after running the program successfully in test mode.
As in test mode, you invoke and execute an alternate copy of the program rather than
use the production copy.
As in training mode, you access the alternate, training database. In test/training mode,
the system removes the restrictions imposed in test mode on execution results.
3.5.6.4. Mode Establishment
The system determines the mode of program execution at the start of a program step
and does not change it until step termination. The mode is established by the way the
associated step was created.
The execution mode of transaction input from a given terminal is a function of the current
mode of that terminal. MCB establishes the initial mode of each PID during MCB
configuration. During system operation, you can change the mode of a given PID when
you send output to the PID.
The execution mode of pass-off and checkpoint messages is implicit from the mode of
the program that created the pass-off or checkpoint message. However, you can
explicitly override the execution mode when you create a pass-off message.
3–18 7833 1568–004

Message Processing – General Concepts
The execution mode of a batch or demand program that creates a program step without
retrieving an input, pass-off, or checkpoint message is determined by the program @XQT
options O and Y:
O option Test mode
Y option Training mode
O and Y options Test and Training mode
The execution mode of a transaction or online batch program that creates a program step
without retrieving an input, pass-off, or checkpoint message is determined by the
VALTAB program OPTIONS field O and Y options.
3.5.6.5. Mode Interpretation
During program execution, both TIP and Universal Database Control are sensitive to the
program execution mode and condition their processing accordingly. If the MCB
configuration has the RESILIENT SGS set to YES, the mode is retained across a failure.
For a description of TIP interpretation, see the Transaction Processing Programming
Reference Manual. For a description of Universal Database Control interpretation, see
the Network Database Server for ClearPath OS 2200 Administration and Support Guide.
3.5.7. MCB Session Control
A session is a connection between CMS and an entity in the network known to CMS.
When a session exists, CMS associates the session with one of several applications
configured in CMS. See the CMS 1100 Operations Reference Manual. A session may be
established automatically by CMS through an operations command or with a command
from a program using MCB.
When a session exists between CMS and a network entity, no new requests for
sessions with the same entity are accepted. The existing session must end before a new
session can begin. A session associated with MCB can be used by all programs
simultaneously unless the PID is held in exclusive use by one program.
If the MCB configuration has the RESILIENT SGS set to YES, the sessions established by
a transaction using the MCB (outbound open) are retained across a failure. These
sessions are either kept open or are reopened by a CMS that is configured with a
RESILIENT parameter on the APPLICATION NDS. If the transaction has requested
session close notification and the session cannot be reestablished during recovery
processing, the transaction is notified that the session is closed.
MCB session control gives application programs the ability to open sessions, close
sessions, and to receive notification of aborted or externally closed sessions.
3.5.7.1. Outbound Open Session Establishment
An application program can open a session on a PID that has no session open.
7833 1568–004 3–19

Message Processing – General Concepts
3.5.7.2. Outbound Session Close
An application program can close a session previously opened by an outbound open
request.
3.5.7.3. Session State Changes
An application program can receive notification of sessions that are abnormally or
externally closed or aborted.
3.5.8. Exclusive Use of a PID
A program may request exclusive use of a PID. If the request is accepted, that program
is the target of all future input until exclusive use is revoked.
Only the owner of exclusive use is allowed to create output destined for the exclusively
held PID. This owner is a program that is currently processing a message having the
same transaction program number as the message being processed when exclusive use
was turned on.
An input-only exclusive use feature is also provided that directs the inputs to a specific
program, but no control is provided on the outputs to the specific PID.
If the MCB configuration has the RESILIENT SGS set to YES, exclusive use information
is retained across a failure. If the transaction requested session close notification and the
session cannot be reestablished during recovery processing, the transaction is notified
that the exclusive use session is closed.
3.5.9. PID Site-id Table
Instead of using a PID number in the application interface, you can use an ASCII
8-character site-id. To use this feature, you must build the PID site-id table during MCB
generation. The site-ids come from CMS system configuration statements and can be
used only on the initialize, read input, and store output functions. A site-id can be
returned on the initialize or read input function requests. A site-id is accepted with the
store output function request. Note that both building the PID site-id table and using
site-ids when the table exists are optional.
3.5.10. IBM Terminal to Logical UTS 400 Terminal
An application program may communicate with any one of several different device types.
If the physical device uses IBM hardware protocols (3270 terminals) and is connected
through the BSC 3270 program product, the program may communicate with a device in
UTS 400 mode. In the MCB, two fields in the auxiliary information area of the interface
packet describe the device type:
• P$TTYP defines the logical type.
• P$RTYP defines the actual hardware type.
3–20 7833 1568–004

Message Processing – General Concepts
P$RTYP always contains the code for the IBM 3270 when you use the BSC 3270
program product. When a session is first opened, the terminal handler operates in
emulation mode. An input message finds the code for the UTS 400 terminal in P$TTYP.
An application program can change the terminal handler mode for this session by sending
an output message that has the 3270 code in P$TTYP.
P$TTYP defines the form of the input message. Many application programs prepare
output in accordance with the input form and then have no further use for the terminal
type. A program that uses the terminal type may inspect P$RTYP. If P$RTYP defines a
3270, the program alters P$TTYP, if necessary, to establish the desired logical type (UTS
400 or 3270 in emulation mode). If you alter P$TTYP in the output auxiliary information
area, the new P$TTYP defines the form of the output message. P$TTYP is defined for all
subsequent input messages during the session, unless you alter it again.
It is possible for P$TTYP to be changed frequently. A single transaction performing the
proper P$TTYP setting, according to a unified session purpose, would be more typical.
Usually, this transaction will be an initial transaction, specified on the PID configuration
statement, which has an EU-NAME with a 3270 association.
This capability is provided only for sessions using the BSC 3270 program product.
3.5.11. Input Message Control
When a recoverable numbered input message is transmitted from a terminal (PID)
configured for input message control, further input is not allowed until the MCB input
acknowledgment (ACK) message is displayed on the terminal. When input is attempted,
MCB discards the input and a WAIT - LAST INPUT IGNORED message is displayed. MCB
will accept additional inputs only after the input ACK message is displayed on the
terminal.
3.5.12. Output Message Control
When this option is configured, output messages sent to a PID with no open session are
rejected. Output message control prevents core buffers and MRF space from being used
by undeliverable messages. If a message is undeliverable for any reason other than a
closed session, the message is not rejected.
To create multiple destination messages, there must be a session open for all PIDs or
group PIDs with output message control configured. The message is rejected if any PID
has a closed session.
If you encounter problems with tight MCB resources, check for congestion caused by
output messages to PIDs that do not have an open session. You may want to configure
those PIDs to use output message control. Use output message control if you plan to
configure spooling for CMS.
7833 1568–004 3–21

Message Processing – General Concepts
3.5.13. TIP Session Control
This level of MCB supports the TIP session control feature of OS 2200 security. No MCB
configuration or generation changes are needed to support this feature. However, proper
levels of the Exec, IRU, and CMS are required to make use of TIP session control.
See the MCB Installation Guide for information on configuring and running TIP Session
Control in a PA environment.
3.5.14. Program Options (VALTAB and XQT)
A program that uses session control or ROPL output must run with the V option set in
one of two ways:
• OPT,V set in the VALTAB for transaction programs
• @XQT,V for batch or demand programs
In session control, without the V option set, an error status is returned to the calling
program.
3.5.15. Common Bank Security
This level of MCB supports the common bank security feature of OS 2200 security. You
must have the proper levels of the Exec, COMUS, and IRU to make use of common bank
security. You need a configuration parameter to invoke common bank security
protection. (See the MCB Installation Guide for more information.) The MCB short and
long message recovery banks are installed as alternate file common banks (AFCB).
If both TIP session control and TIP file security (OS 2200 security features) are
configured, and common bank security is not configured (CBSECURITY=NO), you cannot
access the TIP files unless the attributes of the TIP file (created from the MCB
installation) match the user-id attributes of the MCB caller. To match these attributes,
either run with CBSECURITY=YES in your configuration, or manually match the TIP file
attributes to the user-id attributes of the MCB caller.
3.5.16. TIP Message Security
This level of MCB supports the TIP message security feature of OS 2200 security. You
must have the proper levels of the Exec and CMS to make use of TIP message security.
No MCB configuration or generation changes are needed to support this feature. The
MCB does not perform specific checking of message attributes, but it does enforce
security decisions made by the Exec. The MCB must create some internally generated
messages with specific attributes defined by the security complex in the Exec. These
messages include inputs to the following:
• Error notification program (see 8.3)
• Delivery notification (see 3.5.5 and 5.10)
• Session control notification (see 5.11)
3–22 7833 1568–004

3.5.17. MCB File Security
Message Processing – General Concepts
You can control the public/private access attributes of the files that MCB catalogs for
you. These include the MRF Control File, the MRFs, the PIX files, and the dump files.
Be careful to give the proper access rights to all MCB callers when you ask the MCB to
make the files private. If you do not give the proper access rights, MCB callers will not be
able to access the files.
When configuring TIP File Security in Exec, be careful to assign all MCB callers the same
clearance level regardless of the public/private attribute. Do not use TIP File Security
unless the MCB has been configured for Common Bank Security.
3.5.18. User Session Reestablishment
Sessions can be reestablished after failures of CMS or MCB if each of these products is
configured for resiliency. See the CMS 1100 Installation and Configuration Guide.
• CMS holds all sessions open and waiting during an MCB failure and subsequent
MCB recovery. CMS reestablishes any outbound open sessions reported by the
MCB on a CMPIDS$$ call after a CMS failure.
• The system notifies any transaction requesting session close notification of session
closure if the session cannot be reestablished during recovery processing.
• If you initialize the application group after an MCB failure in a resilient environment,
CMS sessions remain in an open/wait state. Sessions in the MCB are marked closed
because the MCB was not recovered. To resolve this inconsistency, after the
application group is initialized and the MCB is up, enter these commands to CMS:
���� �������� ������
�� �������� ������
This step is necessary only when CMS and MCB are configured as RESILIENT.
3.5.19. Partitioned Applications
Partitioned Applications requires MCB and CMS configured with the correct resilient
configuration and correctly configured Exec. See Partitioned Applications Planning,
Installation, and Operations Guide and the Partitioned Applications Conceptual Overview
for more information.
• The Partitioned Applications feature adds TIP scheduling on both the primary and the
backup host to the functions of Hot-Standby and User Session Reestablishment.
• The Partitioned Applications feature lets you move an application and its related
sessions from one host to another with minimal interruption of the application
environment. The IRU application recovery program (APPREC) utility, contained in the
Partitioned Application feature, restarts MCB after an MCB failure or a system failure
under these conditions:
• MCB is automatically restarted on the backup host after a primary host failure.
• MCB is automatically restarted on the primary host after an MCB failure.
7833 1568–004 3–23

Message Processing – General Concepts
• Sessions are automatically reestablished after either of these failures.
3.5.20. Statistics Monitor Transaction
When MCB is generated, an absolute element is produced that you can install as a
transaction. The transaction displays information on MCB resources and statistics. See
the MCB Installation Guide and the MCB Administration and Operations Guide for more
information.
3.5.21. MRF Threshold Control
You can use the $THRES keyin to define the threshold limits of the message retention
files (MRF). When allocated space in an MRF reaches the upper limit you set, a message
appears on the system console. The message appears once for a single MRF unless:
• The allocated space in the MRF falls below the lower limit you set.
• The $THRES command is issued again with the ON parameter.
• The MCB is terminated and restarted.
See the MCB Operations Reference Manual for more information.
3.5.22. User Message Control
This feature allows input messages to be either discarded or rejected. Messages can be
either thrown away (discarded) or thrown away with a reject message returned to the
originator (rejected). The decision to discard or reject a message is taken by site supplied
Tailored Message Analysis (TMA) code (see Appendix E).
User message control can be used to protect the system from resource depletion.
During periods of system overload or periods of application maintenance, this feature
allows you to provide priority to input messages by either selectively or globally rejecting
them. You can also use this feature to temporarily “ban” a specific transaction that is
known to be causing problems.
3.6. TeamQuest Transaction Performance Auditing
System (TPAS)
TPAS is a measurement tool that provides system performance analysis information in a
transaction processing environment. It collects data and produces a message
management report with a summary of performance statistics for calls to MCB.
MCB does not call TPAS for data gathering during extended mode calls or TIP primitive
calls. When you use these interfaces, the message management report may not be
complete.
3–24 7833 1568–004

Section 4
CMS Interface
This section explains the interface available for communications programs such as
CMS 1100, SILAS, Communications Interface for Transaction Applications, and similar
programs. In this section, the term CMS refers to any of these programs.
After MCB is initialized by the MCB background run, one or more CMS programs may
interface with MCB. Before using MCB, each CMS must perform preparatory action, as
explained in 4.1.
Multiple activities from the same CMS can interface to MCB. Successive segments of
the same message can be stored or retrieved by different activities as long as only one
activity is accessing a message at any time.
Each CMS activity that performs message processing through MCB uses the set of
functions described in this section. The first function performed by each activity must be
CMS activity initialization (CMINIT$$). In addition to the functions described in this
section, an activity initialized by the CMINIT$$ function can use some of the application
program functions described in Section 5. The only application program functions
available to a CMS activity are SEND$$, CANCEL$$, ENQUE$$, and PIDSTAT$$. For
calls with these functions, the CMS activity must use the calling sequence described in
Section 5 rather than the calling sequence explained in this section.
4.1. Requirements of CMS
Before any CMS activity can begin using MCB, CMS must perform the following
preparatory processes:
• Elevate to real-time status by performing ER RT$ with each activity that calls MCB.
• Connect to Transaction Processing (TIP) by doing the following with at least one
activity of the program:
��� ����
��� ����
��� ����
�� ������
7833 1568–004 4–1

CMS Interface
• Perform ER-CMS$REG with one activity of the program to register the program as a
CMS and establish a TIP output message queue, sometimes referred to as the
routing output queue (ROQ). Refer to the Transaction Processing Administration and
Operations Reference Manual for an explanation of ER-CMS$REG and of the ROQ
and its entries. Each activity performing ER-CMS$REG must obtain a unique CMS
number. CMS passes that CMS number to MCB on the CMINIT$$ function call (see
4.5). Several activities of the same program may use the same CMS number when
calling MCB if one of them has registered the number via ER-CMS$REG. When
performing ER-CMS$REG, specify the output queuing option.
Note: It is permissible for multiple activities of a program to perform ER CMS$REG
and obtain different CMS numbers for passing to MCB, but MCB regards the
activities as being from separate programs.
CMS identifies to the Exex which PIDs are under its control by performing ER RT$PID.
EXEC maintains a PID matrix to record the CMS-PID relationship. When an output
message is queued for a particular PID, EXEC uses the PID matrix to identify the CMS
ROQ which receives the queue entry for that output.
If CMS passes a nonzero value in packet field P$VER on the CMINIT$$ call (see 4.5),
then CMS must be prepared to process outbound session open requests which are
queued to it on the ROQ. For each outbound session open request, CMS must call MCB
with one of the Session Status Notification functions (SESSOP$$ or SESSRJ$$, see 4.5).
Failure to do so can result in application programs being hung in MCB.
A CMS activity must be allowed to deactivate for test-and-set queuing, mass storage I/O,
or audit trail writing.
4.2. Basic Mode Calling Sequence for CMS
Refer to 3.4.1 for a description of the calling sequence.
Register A0 points to word 0 of the interface packet (see 4.4). If TIP session control is
enabled, the word immediately preceding word 0 must contain the TIP session id when
CMS calls MCB with the Store Input, Receive Output Message, Output Message
Positive Acknowledge, or Output Message Negative Acknowledge (CMSTOR$$,
CMRECV$$, CMSACK$$ or CMNAK$$) functions. If TIP session control is not enabled,
that word must exist in the bank containing the packet, but MCB ignores the contents of
that word.
For all the functions explained in this section, CMS must have the following addressing
environment at the time CMS enters MCB:
• The main I-bank (BDR0) is any I-bank. MCB takes the place of this bank as MCB is
entered, and MCB rebases this bank when MCB returns to CMS.
• The main D-bank (BDR2) is any D-bank. MCB unbases this bank and rebases it
before returning to CMS. CMS cannot have either the packet or this bank when MCB
is called. The bank must not be a guaranteed entry point bank.
4–2 7833 1568–004

CMS Interface
• The utility I-bank (BDR1) holds the packet and the data buffer that CMS passes to
MCB. MCB does not unbase this bank. This bank must not be read-only, and its
address limits must not overlap the MCB common banks that MCB bases on BDR0
and BDR3. Because the upper limit for the MCB I-bank can be as high as 0127777,
set the lower limits of the CMS bank at 0130000 or higher. If the limit needs to be
below 0130000, see the MCB Installation Guide.
• The utility D-bank (BDR3) is any D-bank. MCB unbases this bank, then rebases it
before returning to CMS. As with the main D-bank, neither the packet nor the data
buffer can be in this bank, and the bank must not be a guaranteed-entry point bank.
In addition to the functions described in this section, a CMS activity (an activity initialized
by the CMINIT$$ function) can use some of the application program functions described
in Section 5. When you use those functions, the CMS activity must conform to the
addressing requirements listed in 5.2 rather those listed in this section. The only
application program functions available to a CMS activity are SEND$$, CANCEL$$,
ENQUE$$, and PIDSTAT$$.
4.3. Extended Mode Calling Sequence for CMS
A program written in UCS C (UC) may call MCB as a CMS program with
or
��������� ������������ ����������� ��������� ���������������
���������� ������������ ����������� ��������� ���������������
where n is the application number, and where each of the parameters is defined as a
pointer to void.
The entry point name can be resolved by the linking system using the CBEP$EMMCBn
element in the MCB installation file.
The parameters are as follows:
• Parameter One points to the interface packet as shown in 4.4 with the following
exceptions:
− The word containing P$SESID is not part of the packet. Parameter four is used
instead of P$SESID.
− P$BUFF must be zero. Parameter two is used instead of P$BUFF.
− P$RTN must be zero. Alternate return point cannot be used.
• Parameter Two points to a 36-bit word which MCB uses to return a status code.
Refer to Appendix B for a list of values returned.
• Parameter Three points to a text buffer. The buffer must be word-aligned.
• Parameter Four points to a 36-bit word containing the TIP session id. If TIP session
control is not enabled, provide a word containing 0.
7833 1568–004 4–3

CMS Interface
4.4. CMS Interface Packet
The CMS packet shown in Figure 4–1 is used for all CMS functions. On any given
function, only certain fields are used. The unused fields must be zeros.
The CMS packet shown in Figure 4–1 is used for all CMS functions. On any given
function, only certain fields are used. The unused fields must be zeros.
-01 0
00
01
02
03
04
05
06
07
01
0
P$FUNC
function code
P$AUX
aux data
P$LENGTH
P$OFF
data offset
request character pointer
P$START
start character pointer
P$FAC
facilities
P$PID
terminal identifier
P$TC2
transaction code
P$VER
version
P$TC1
transaction code
P$QID
queue item identifier
start of auxiliary information
Figure 4–1. CMS Packet
P$SESID
TIP session identifier
4–4 7833 1568–004
P$ID
message identifier
P$BUFF
data buffer address
P$RTN
return point
P$FLAGS
flags
P$MN
message number
P$ML
message length

CMS Interface
When you use the CMS activity initialization function, words 01 and 02 are overlaid as
shown in Figure 4–2.
01 P$FUNC
P$LENGTH
request character count
CMS feature
02 P$MCBFEAT
P$START
start character pointer
MCB feature
4.5. Interface Functions
P$ILVL
CMS Lvl
P$ILVM
MCB Lvl
Figure 4–2. CMS Packet Overlay
P$BUFF
data buffer address
P$RTN
data buffer address
The following information describes MCB functions available to application programs
through the CMS interfaces (see 4.2 and 4.3). In the packet field descriptions,
mnemonics name the function codes passed in the P$FUNC field. The actual value for
each function code is listed in Appendix A.
4.5.1. CMS Activity Initialization
The initialization function identifies an activity of CMS to the MCB. The activities switch
list (SWL) is recorded, an ER TRMRG$ is performed, and the activity is marked to use the
other CMS functions. The initializing activity must be in real-time mode.
The packet fields in Figure 4–1 and Figure 4–2 that are used for activity initialization are
described next. The packet address of word 0 must be in A0.
P$ILVL
Indicates level for CMS. At activity initialization, CMS passes a P$ILVL and MCB
returns a P$ILVM with these values:
0 = Not in use
1 = Use of P$CMSFEAT and ROPL output messages allowed
P$CMSFEAT
Used as a bit map to indicate features in CMS that can be configured, enabled, or
disabled at run time. Bits are undefined.
7833 1568–004 4–5

CMS Interface
P$ILVM
Indicates level for MCB. At CMS activity initialization, MCB passes a P$ILVM and
CMS returns a P$ILVL with these values:
0 = Not in use
1 = Use of P$MCBFEAT and ROPL output messages allowed
P$MCBFEAT
Used as a bit map to indicate features in MCB that can be configured, enabled, or
disabled at run time. Bits are undefined.
P$FUNC
P$FAC
The function code CMINIT$$ is supplied by the calling program.
The facilities status field indicates the condition of system resources at completion of
the request. MCB returns a value in the range 0 to 3. The following values are the
maximum current values of either Exec or MCB resources.
Exec values are based upon core queue items or EXPOOL. MCB values are based on
core buffers or MRF allocation descriptors (MAD). If the MCB is nonrecoverable,
MRF use is also included.
Exec MCB
0 = normal 0 = normal
1 = 50 percent in use 1 = 50 percent in use
2 = 80 percent in use 2 = 70 percent in use
3 = 90 percent in use 3 = 90 percent in use
P$RTN
This is the return point. If this field is zero, control is returned to the caller following
the LBJ that entered the MCB. If this field is not zero, control is returned to the
address specified in the bank from which the MCB was called, and P$RTN is set to
the address following the LBJ that entered the MCB.
P$ID
P$VER
This field is supplied by the calling program and must be zero.
The interface version. CMS and MCB use P$VER to communicate the level of
support for various features. The value in this field indicates the support level. Level
0 does not support the outbound open feature. Level 1 supports the outbound open
feature. Level 2 supports TIP session control. Level 3 supports MCB resilient
functionality and the outbound open feature. The MCB level is communicated in this
field to CMS on return from the INIT function.
4–6 7833 1568–004

P$QID
The CMS number that is used by CMS.
4.5.2. CMS Activity Termination
CMS Interface
The packet fields in Figure 4–1 that are used for activity termination are described next.
This function ends the association of the activity with MCB. CMS executes an ER
TRMRG$, and releases any resources held by the activity. The packet fields are
P$FUNC
The function code CMTERM$$. The calling program supplies this field.
P$RTN
This is the return point. If this field is zero, control is returned to the caller following
the LBJ that entered MCB. If the field is not zero, control is returned to the address
specified in the bank from which the MCB was called, and P$RTN is set to the
address following the LBJ that entered the MCB. This field is supplied by the calling
program.
P$ID
This field must be zero.
4.5.3. CMS Store Input Message
The packet fields (see Figure 4–1) that are used to store input messages are described
next. This function stages input message text and parameters from CMS to the MCB
and mass storage. Before control is returned to CMS, any required auditing is initiated
and any mass storage I/O is completed. Audit requests are not mandatory, and need not
be finished before control is returned to CMS. The packet fields are
P$SESID
The TIP session identifier. The calling program supplies this field.
P$FUNC
The calling program supplies the function code CMSTOR$$ field.
P$FAC
The facilities status (see 4.5.1). MCB fills in this field.
P$ID
The message-id value is passed to MCB by CMS to identify the message on which
the operation should be done. If the value is zero, a new message is started. If the
value is not zero, it is checked for accuracy. On return from the MCB to CMS, this
field is correctly set for future operations on the message. CMS is responsible for
setting the field correctly on all calls to MCB. Different activities of CMS can stage
successive message segments of a message, but only one segment can be
7833 1568–004 4–7

CMS Interface
undergoing staging at one time. A message stays associated with CMS until it is
passed on to step control. See P$FLAGS bit 0.
P$LENGTH
The length of text being passed is the number of quarter words of data to be stored
as message text. The field is supplied by the calling program.
P$BUFF
The address of the data area holding the text is supplied by the calling program.
P$START
P$PID
P$OFF
P$AUX
P$RTN
The start character pointer specifies the point in the message to begin placing the
text. The value is in characters relative to the start of the message text, where the
first character is denoted by P$START = 1. If zero is given as a value, the text is
appended to any existing text. This field is supplied by the calling program. On return
from any store function, the field is set to point at the character after the last one
stored. If a change is not made, the value can be used on subsequent store functions
to add new text at the end of the message. If nonzero, the value must be less than
or equal to the number of characters already in the message plus one. Previously
staged text may be overlaid, but holes cannot be left in a message.
The input PID field is meaningful only for the first operation on a message. It is
ignored on subsequent store operations for the message. This field is supplied by the
calling program.
The data offset value specifies the number of quarter words from the address in
P$BUFF at which the text begins in the CMS data area. Zero is Q1 of the address in
P$BUFF, and four is Q1 of the following word. This field is supplied by the calling
program.
The size in words of the auxiliary information for the message is supplied by the
calling program. This data starts at word 8 of the packet, and the field is significant
only for the first store operation on a message.
The return point. If this field is zero, control is returned to the caller following the LBJ
that entered the MCB. If the field is nonzero, then control is returned to the specified
address in the bank from which the MCB was called, and P$RTN is set to the
address following the LBJ that entered the MCB. The field is supplied by the calling
program.
4–8 7833 1568–004

P$FLAGS
P$MN
CMS Interface
Bits to indicate special processing. For this function the bits are
Bit 0
Last block indicator (LBI). If set, the message is queued to step control when
data transfer is complete and further attempts to access the message result in
error. If the bit is not set, the message remains available to CMS for processing.
Bit 13
Bit 15
Bit 16
If set, a transaction code is not supplied in P$TC1/P$TC2 because conversational
link is in effect.
If set, the MCB assumes that the first store function with this flag set presents
the first character of the transaction code as the first text character on that
function call. This bit is ignored if P$TXN in the auxiliary information area is not
zero (see 4.6).
If set, the auxiliary data area previously stored with the message is replaced with
the auxiliary data area presented on this call. When a new message is started
(P$ID = 0), the auxiliary data area is set according to the value in P$AUX.
Subsequent calls either replace the auxiliary data (if bit 16 is set) or leave it
unchanged (if bit 16 is not set). You cannot alter the size of the auxiliary data
area. The size is always determined by the value in P$AUX when a message is
started.
The message number. If CMS receives an assurance unit with a message, the
assurance unit is presented to the MCB in this field. If no assurance unit is received,
the field is zero. This field is significant only on the first store operation for a given
message.
P$TC1/P$TC2
The transaction code. These fields contain the first one to six text characters in ASCII
(terminated by a blank, or the sixth character, whichever comes first). If fewer than
six characters are presented, a blank must be the last character. The field is supplied
by the calling program. A character is a quarter word. This field is significant only on
the first store operation for a given message.
4.5.4. CMS Input Message Cancel
The packet fields in Figure 4–1 that are used to cancel input messages are described
next. This function tells the MCB that an input message being built will not be finished.
The MCB can reuse the resources used for the message. The packet fields are
P$FUNC
The function code CMCAN$$. This field is supplied by the calling program.
7833 1568–004 4–9

CMS Interface
P$FAC
P$ID
P$RTN
The facilities status (see 4.5.1). This field is filled in by the MCB.
The message-id. This must be nonzero and valid. The field is supplied by the calling
program.
The return point. If this field is zero, control is returned to the caller following the LBJ
that entered the MCB. If the field is nonzero, control is returned to the specified
address in the bank from which the MCB was called, and P$RTN is set to the
address following the LBJ that entered the MCB. The field is supplied by the calling
program.
4.5.5. CMS Receive Output Message
The packet fields in Figure 4–1 that are used to receive output messages are described
next. This function passes output message parameters and text from the MCB or mass
storage to CMS. MCB signals CMS through the output queue mechanism that pending
output messages exist. The first use of this function for a new message returns a
number of items in the request packet in addition to returning text. Later calls to the
MCB can read or reread any part of the text. The packet fields, however, are returned by
the MCB on successive calls only if P$START = 1. The packet fields are
P$SESID
The TIP session identifier. This field is supplied by the calling program.
P$FUNC
The function code CMRECV$$. This field is supplied by the calling program.
P$FAC
The facilities status (see 4.5.1). This field is filled in by the MCB.
P$ID
The message-id. This field is zero for the first operation on a message and nonzero
for subsequent operations. See P$QID that follows. This field is supplied by the
calling program.
P$LENGTH
The requested text size in quarter words. This field is supplied by the calling program
and is changed by the MCB if the last character of the text is read. In this case,
P$FLAGS bit 0 is also set.
P$BUFF
The data buffer address. This field is supplied by the calling program.
4–10 7833 1568–004

P$START
P$PID
CMS Interface
The start character pointer. This field is used in a manner analogous to the store
function (see 4.5.3). It may be used to re-read text previously read. If P$START = 0,
the reading of text resumes at the point where the previous read operation for this
message terminated. The field is supplied by the calling program.
The destination PID. CMS must present the PID to which the message is actually
sent. This need not be the PID to which the message was originally directed. The
field is meaningful only if P$ID = 0 (the first request).
P$FLAGS
Bit flags. For this function, the following meanings are defined. The field is filled in by
the MCB.
Bit 0
Last block indicator (LBI). If set, the last text character was read. P$LENGTH is
set to the number of characters actually transferred.
P$OFF
Bit 17
P$AUX
P$RTN
P$ML
Recoverable message indicator. If set, the message is recoverable.
The data offset. This value specifies the number of quarter words from the address
in P$BUFF at which the text begins in the CMS data area. Zero is Q1 of the address
in P$BUFF and four is Q1 of the following word. The field is supplied by the calling
program.
The size of the auxiliary information area. CMS presents this value to the MCB. On
return, the field contains the length of the auxiliary data actually put in the packet. If
the area presented is not large enough to hold all the data, an error exists, and an
error status is returned to CMS. This field is necessary on the first receive for a
message or any other receive function for which P$START = 1.
The return point. If the field is zero, control is returned to the caller following the LBJ
that entered the MCB. If the field is nonzero, control is returned to the specified
address in the bank from which the MCB was called, and P$RTN is set to the
address following the LBJ that entered the MCB. This field is supplied by the calling
program.
The message length. The MCB returns this value to CMS on the first receive
function for a given message or any other receive function for which P$START = 1. It
is the total length of the message text in quarter words.
7833 1568–004 4–11

CMS Interface
P$QID
P$MN
The queue item identifier. This value is presented to CMS by step control (Exec) in
the output queue entry. CMS presents it to the MCB to indicate that a new message
is about to be transmitted. If P$ID is not zero, then P$QID is ignored. If P$ID and
P$QID are both zero, an error exists.
The message number. If the MCB returns a nonzero value, CMS must send that
value as an assurance unit. If the field is zero, no assurance unit need be sent. This
field is returned to CMS on the first receive function for a given message or any
other receive function for which P$START = 1.
4.5.6. CMS Output Message Hold
The packets fields in Figure 4–1 that are used to hold output messages are described
next. This function tells the MCB that a message cannot be transmitted at the present
time. Since it may be possible to transmit the message in the future, the message is
retained in anticipation of later delivery. For this function, the MCB releases the transient
control buffers for the message but retains a copy of the message. The packet fields are
P$FUNC
The function code MHOLD$$. This field is supplied by the calling program.
P$FAC
The facilities status (see 4.5.1). This field is filled in by the MCB.
P$ID
The message-id. This field is supplied by the calling program.
P$RTN
The return point. If the field is zero, control is returned to the caller following the LBJ
that entered the MCB. If the field is nonzero, control is returned to the specified
address in the bank from which the MCB was called, and P$RTN is set to the
address following the LBJ that entered the MCB. This field is supplied by the calling
program.
4.5.7. CMS Output Message Positive Acknowledge
The packet fields in Figure 4–1 that are used to positively acknowledge output messages
are described next. This function indicates that an output message was successfully
transmitted. All system resources for the message are released. The packet fields are
P$SESID
The TIP session identifier. This field is supplied by the calling program.
P$FUN
The function code CMSACK$$. This field is supplied by the calling program.
4–12 7833 1568–004

P$FAC
P$ID
P$RTN
The facilities status (see 4.5.1). This field is filled in by the MCB.
The message-id. This field is supplied by the calling program.
CMS Interface
The return point. If the field is zero, then control is returned to the caller following the
LBJ that entered the MCB. If the field is nonzero, then control is returned to the
specified address in the bank from which the MCB was called, and P$RTN is set to
the address following the LBJ that entered the MCB. This field is supplied by the
calling program.
4.5.8. CMS Output Message Negative Acknowledge
The packet fields in Figure 4–1 that are used to negatively acknowledge output
messages are described next. This function indicates that an output message cannot be
successfully delivered or alternately routed. A system error process is invoked to dispose
of the message. The packet fields are
P$SESID
The TIP session identifier. This field is supplied by the calling program.
P$FUNC
The function code CMSNAK$$. This field is supplied by the calling program.
P$FAC
The facilities status (see 4.5.1). This field is filled in by the MCB.
P$ID
The message-id. This field is supplied by the calling program.
P$RTN
The return point. If this field is zero, control is returned to the caller following the LBJ
that entered the MCB. If the field is nonzero, control is returned to the specified
address in the bank from which the MCB was called, and P$RTN is set to the
address following the LBJ that entered the MCB. This field is supplied by the calling
program.
7833 1568–004 4–13

CMS Interface
P$SESSION
When an output message is negatively acknowledged, CMS supplies the reason for
NAK code in this call. The following are valid reasons for NAK:
NAK Definition
031 Peer negatively acknowledged the message
032 Message sent, but may have been lost
033 Too many output messages queued to the PID
034 Output message too large
035 Illegal function
036 Message deleted by keyin
037 Illegal PID
040 CMS internal error
4.5.9. CMS Put Text
041 TIP message security violation
042 MCB unable to retrieve the output message
043 Undeliverable message; the application or the PID is configured to NAK
ROPL output messages if a PID session is stopped or closed
044 MCB ROPL message queued in CMS during a normal TIPCSU termination
The packet fields (see Figure 4–1) that are used for text placement are described next.
This function stages CMS message text temporarily in the MCB and mass storage. The
text is later retrieved by the CMS get text function. The message is always
nonrecoverable. The packet fields are
P$FUNC
The function code CMSPUT$$. This field is supplied by the calling program.
P$FAC
The facilities status (see 4.5.1). This field is filled in by the MCB.
P$ID
The message-id. This is a value passed to the MCB by CMS to identify the message
on which the operation must be performed. If the value is zero, a new message is
started. If the value is nonzero, it is checked for accuracy. On return from the MCB
to CMS, this field is set for future operations on the message. CMS is responsible for
setting the field correctly on all calls to the MCB. Different activities of CMS may
stage successive segments of a given message but only one segment may undergo
staging for a given message at one time. A message is associated with CMS until it
is discarded by the input message cancel function or retrieved by the get text
function.
4–14 7833 1568–004

P$LENGT H
CMS Interface
The length of text being passed. This field is the number of quarter words of data to
be stored as message text and is supplied by the calling program.
P$BUFF
The address of the data area holding the text. This field is supplied by the calling
program.
P$START
P$RTN
P$OFF
The start character pointer. This value specifies the point in the message to begin
placing the text. The value is in characters relative to the start of the message text,
where the first character is denoted by P$START = 1. If zero is given as a value, the
text is appended to existing text, if any. he field is supplied by the calling program.
On return from any store function, the field is set to point at the character following
the last one stored. If a change is not made, the value can be used on subsequent
store functions to add new text at the end of the message. If nonzero, this value
must be less than or equal to the number of characters plus one in the message.
Previously staged text may be overlaid, but no holes can be left in a message.
The return point. If this field is zero, control is returned to the caller following the LBJ
that entered the MCB. If this field is nonzero, control is returned to the specified
address in the bank from which the MCB was called, and P$RTN is set to the
address following the LBJ that entered the MCB. The field is supplied by the calling
program.
The data offset. This value specifies the number of quarter words from the address
in P$BUFF at which the text begins in the CMS data area. (0 is Q1 of the address in
P$BUFF, 4 is Q1 of the following word.) The field is supplied by the calling program.
P$FLAGS
Bits to indicate special processing. For this function, the bit is
Bit 0 Last block indicator (LBI). If set, this causes the message to become a
read-only message that may be accessed by the CMS get text
function. If not set, the message remains available to CMS for further
put text operations.
4.5.10. Read VINDEX Entry
The packet fields in Figure 4–1 that are used to read the VINDEX entry are described
next. This function returns to CMS the VINDEX entry corresponding to a transaction code
from the MCB VINDEX bank. It retrieves only one VINDEX entry from the bank and
returns it in words 4 through 6 of the calling program’s packet.
When CMS is configured to run both MCB and COMPOOL, CMS uses the returned
7833 1568–004 4–15

CMS Interface
VINDEX entry to determine how the input should be stored. If the V bit in the recovery
options field is set, the input is stored with the MCB. If the V bit is not set, the input is
stored with COMPOOL.
The V bit in the VINDEX entry is set by the VALTAB utility program based on the VALTAB
J-status bit. If the MCB finds test mode set for the input PID, the V bit returned to CMS
is based on the VALTAB L-status bit.
If the PID supplied in the packet has exclusive use set, the transaction code supplied is
ignored and the VINDEX entry returned is the exclusive use of the target transaction
code. The V bit is set unconditionally in this case.
If the input is one of the two special MAPPER_ characters, caret (^) or right bracket ( ] ),
a check determines if either of the characters is an MCB trigger character. If either is an
MCB trigger, the V bit is returned to CMS from the VINDEX entry of the trigger’s
transaction code. If neither character is an MCB trigger, the input is stored in COMPOOL.
Test mode, through the use of the VALTAB L bit, is also allowed for the MAPPER system
transaction code.
The packet fields are
P$FUNC
The function code VNXRD$$. This field is supplied by the calling program.
P$PID
The input PID. This field is supplied by the calling program.
P$TC1/P$TC2
The transaction code corresponding to the requested VINDEX entry.
4.5.11. CMS Get Text
This function returns to CMS message text that was previously staged in the MCB using
the CMS put text function. The packet fields are
P$FUNC
The function code CMSGET$$. This field is supplied by the calling program.
P$FAC
The facilities status (see 4.5.1). This field is filled in by the MCB.
P$ID
The message-id. This field must be nonzero and must be the value previously
returned when the message text was staged in the MCB using the CMS put text
function. The field is supplied by the calling program.
4–16 7833 1568–004

P$LENGTH
CMS Interface
The requested text size in quarter words. The field is supplied by the calling program.
The field is changed by the MCB if the last character of text is read. In this case,
P$FLAGS bit 0 is also set.
P$BUFF
The address of the data area to receive the text. This field is supplied by the calling
program.
P$START
P$OFF
P$RTN
The start character pointer. This field is similar to the CMS put text function (see
4.5.9). The field may be used to re-read text. If P$START = 0, the reading of text
resumes at the point where the previous read operation terminated. This field is
supplied by the calling program.
The data offset. This value specifies the number of quarter words from the address
in P$BUFF at which text begins in the CMS data area. (0 is Q1 of the address in
P$BUFF, 4 is Q1 of the following word.) This field is supplied by the calling program.
The return point. If this field is zero, control is returned to the caller following the LBJ
that entered the MCB. If this field is nonzero, control is returned to the address in the
bank from which the MCB was called, and P$RTN is set to the address following the
LBJ that entered the MCB. The field is supplied by the calling program.
P$FLAGS
Bits to indicate special processing. For this function, the bits are
Bit 0 Last block indicator (LBI). Set by the MCB when the last text character was
read. P$LENGTH is set to the number of characters transferred.
Bit 2 If set, the message is released when the last character is read. This bit is
supplied by the calling program.
P$ML
The message length. The MCB returns this value to CMS on the first get text
function for a given message or any other get text function for which P$START = 1.
It is the total message length in quarter words.
4.5.12. CMS Session Status Notification
The packet fields in Figure 4–1 that are used for session status notification are described
next. These functions are used by CMS to notify the MCB of session state changes. The
packet fields are as follows.
P$FUNC
A function code from Table 4–1. This field is passed by CMS to MCB.
7833 1568–004 4–17

CMS Interface
P$FAC
P$PID
P$QID
The facilities status. This field is passed back to CMS by the MCB. The values are
defined in 4.5.1.
The PID for which the status is being reported. This field is passed by CMS to the
MCB.
A function code from Table 4–1. This field is passed by CMS to MCB.
Table 4–1. Relation between P$FUNC and P$QID
P$FUNC Mnemonic P$QID Meaning
062 SESSCLR$$ 024 Session close rejected because PID busy
025 Session close rejected because PID not in use
063 SESSOP$$ Ignored Session successfully opened
066 SESSRJ$$ 01 Session open rejected; device information error in
local configuration
02 Device information error in network
03 Lack of local resources
04 Lack of network resources
05 Local software error- protocol error
06 Network software error- protocol error
07 Peer failed:
• Not turned on
• Not connected
• Hardware error
• Problem with peer application
010 Peer busy-in use by other user
011 Session already open
012 PID is DOWN (CMS CSA command)
024 PID is busy-session already open with another
application
4–18 7833 1568–004

Table 4–1. Relation between P$FUNC and P$QID
P$FUNC Mnemonic P$QID Meaning
067 SESSAB$$ 050 Session aborted because Peer failed
051 Local software error
052 Network software error
053 Reduced local resources
054 Reduced network resources
055 CSA commanded session abort
056 TIP Session Control session timeout
071 SESSCP$$ Ignored Session close received from Peer CSU
072 SESSCL$$ Ignored Session closed
CMS Interface
Functions 067 and 072 never contain text. These functions create a pass-off message as
described in 5.11.
4.5.13. CMS PID Configuration
This function was used by CMS with former levels of MCB to provide a list of PIDs in the
CMS configuration. This function is no longer necessary. It is maintained for
compatibility, but it has no effect. This function is not valid with the extended mode
calling sequence. The packet fields are
P$FUNC
The function code, CMPIDI$$, is supplied by the calling program.
P$LENGTH
The CMS number, subfunction, and number of ACWs. This field is identical to H1 of
A0 for the ER RT$PID. See the Transaction Processing Administration and
Operations Reference Manual. Use subfunction values 1 and 2. Any other value
results in an error status. Subfunctions 1 and 2 operate similarly to the ER RT$PID.
However, the MCB records, for each PID, the CMS number for every copy of CMS
that has the PID configured. Thus, no error is detected when this call is made when
another CMS has a session open with the same PID.
P$BUFF
The ACW buffer address. This field points to a buffer of the same form as the ER
RT$PID.
7833 1568–004 4–19

CMS Interface
4.5.14. CMS Session Open Notify
The packet fields in (see Figure 4–1) that are used for session open notification are
described next. This function is used by CMS to notify the MCB when a session is
opened. The MCB places the CMS number in the PID entry for the PID specified in the
calling packet. The CMS number in the PID entry signifies an active session with that
PID. This function does not include outbound opens. The packet fields are
P$FUNC
The function code, CMSOPEN$$, is supplied by the calling CMS.
P$PID
The PID with which a session has been established. This is supplied by the calling
CMS.
P$RTN
P$FAC
The return point. If this field is zero, control is returned to the caller following the LBJ
that entered the MCB. If this field is nonzero, control is returned to the specified
address in the bank from which the MCB was called, and P$RTN is set to the
address following the LBJ that entered the MCB. The field is supplied by the calling
program.
The facilities status. This field is passed to CMS by the MCB. The values are defined
in 4.5.1.
4.5.15. CMS Resilient Session Open Notification
CMS uses the session open notification function to notify the MCB that the PID numbers
provided in the access control word (ACW) are PIDs that were previously inbound
opened and are to be recovered. The MCB places the CMS number in the appropriate
cell in the PID entry. MCB determines that the PID number is valid, is not a group PID, or
is not currently assigned to another CMS. The CMS number in the PID entry signifies an
active session with the PID. The packet fields (which are all shown in Figure 4–1) are as
follows:
Note: This function is not valid with the extended mode calling sequence.
P$FUNC
The function code, RESOPEN$$, is supplied by calling CMS.
P$LENGTH
The buffer length in words.
P$BUFF
The address of the buffer that contains the list of PID numbers that were previously
inbound opened and are to be recovered.
4–20 7833 1568–004

P$PID
CMS Interface
The number of PIDS (integer value) that are in the list pointed to by the address in
the cell P$BUFF. CMS passes a maximum of 1,000 PID numbers per call to MCB.
When CMS resumes control, this cell contains a value of zero if no errors were
encountered. If an error occurred in the processing of any of the PIDs to be
recovered, the number of the last PID for which any error occurred is present in this
cell.
The three possible error codes that may be returned in register A1 following the return of
control to CMS are 017, 034, and 0117. See Appendix B of this document for the
explanation of these error codes.
4.5.16. CMS PID Information Request
The packet fields used in Figure 4–1 that are used to request PID information are
described next. CMS uses this function to obtain session-related information from MCB
after a CMS, MCB, or system failure. To enable this function, the RESILIENT parameter
must be set on the APPLICATION NDS in the CMS configuration, and the RESILIENT
parameter must be set to YES in the MCB configuration. The requested information is
returned in a buffer supplied by the calling program at the address in P$BUFF.
Note: This function is not valid with the extended mode calling sequence.
The first word of the supplied buffer contains information about the buffer itself:
• H1 always contains the total number of words of usable return buffer space (space
that MCB will use).
• H2 contains the number of ACWs specifying PID ranges. The calling program
supplies the ACWs. If H2 is zero, no PID range ACWs are present, and the MCB
searches from P$PID to MAXPID.
If H2 is nonzero, it indicates the number of PID range ACWs contained in a list that
immediately follows the usable buffer area. The buffer length plus the length of the
ACW list is specified (in quarter words) in the P$LENGTH field.
For each PID range ACW in the list, H1 contains the number of PIDs in the specified
range, and H2 contains the first PID in the range.
The PID session information is returned by the MCB into the specified buffer area as
follows:
• In the first word of the buffer, H1 contains the total number of PIDs returned.
• For each following word (one word per PID), H1 indicates the type of PID:
1 = outbound open, 2 = exclusive use close notification and output message control.
H2 contains the PID number.
The packet fields are
P$FUNC
The function code CMSPIDS$$ is supplied by the calling program.
7833 1568–004 4–21

CMS Interface
P$LENGTH
The total buffer length in quarter words. This is the total of usable buffer space and
the ACW list (if any). This field is supplied by the calling program.
P$BUFF
The starting address of the buffer area. This field is supplied by the calling program.
The first buffer word contains the following information:
H1 = number of usable buffer words
H2 = number of ACWs in ACW list (may be zero)
P$RTN
The return point. This field is supplied by the calling program. A zero indicates that
control is returned to the calling program following the LBJ that entered the MCB.
P$FAC
P$PID
P$MN
The facilities status (see 4.5.2). This field is supplied by the MCB.
Contains the first PID number in the search. This field is supplied by the calling
program. The MCB updates this field to contain the last PID number read before
returning control to the calling program.
This field indicates the type of information to be returned by the MCB:
0 = both types
1 = outbound open only
2 = exclusive use close notification and output message control
This field is supplied by the calling program.
4.5.17. CMS Obtain Resource Status
The packet fields in Figure 4–1 that are used to obtain resource status are described
next. This function is used by CMS to obtain the most recent status on system
resources. The packet fields are
P$FUNC
The function code CMFAC$$, supplied by the calling program.
4–22 7833 1568–004

P$FAC
CMS Interface
The facilities status field indicates the condition of system resources at completion of
the request. MCB returns a value in the range 0 to 3. The values in the following
table are the maximum current values of either Exec or MCB resources. Exec values
are based on core queue items or EXPOOL. MCB values are based on core buffers
or MADs. If the MCB is nonrecoverable, MRF usage is also included.
Exec MCB
0 = normal 0 = normal
1 = 50 percent in use 1 = 50 percent in use
2 = 80 percent in use 2 = 70 percent in use
3 = 90 percent in use 3 = 90 percent in use
4.6. Auxiliary Information Area
The information in the auxiliary information area applies to both CMS and site-developed
application programs. The auxiliary information area of the interface packet begins at
word 8 (010) of the CMS packet or at word 16 (020) of the application program packet.
The format is shown in Figure 4–3.
The use of the auxiliary information area as described here is supported by CMS1100 and
SILAS. Other CMS programs do not necessarily use all of the fields of the auxiliary
information area in the same manner as CMS1100 and SILAS.
00 P$END
size
01 P$TTYP
device type
P$FNC
function
P$FORMAT
text format
P$DID
device index
P$ROW
cursor row
P$KEY
function key
P$COL
cursor column
P$CAT
device category
02 P$HDR (output header offset) P$HDRSIZE P$LKEY
*02 P$RSTYP P$CCS header size logical function key
03 P$TXN
txn code offset
P$PRIM
offset for MC$PRIM
P$SESSION
NAK reason code or
state change reason
04 Start of optional UPA data
Figure 4–3. Auxiliary Information Area
P$RTYP
real device type
7833 1568–004 4–23

CMS Interface
Beginning with word 4 of the auxiliary data area, an optional user parameter area (UPA)
allows the application program to communicate control information between itself and a
site-supplied device handler. The contents of the following fields may be input or output
values:
P$END
This field is the size in words of the standard data. If UPA data is present, size is the
difference between P$AUX and P$END. Currently, P$END = 4. If UPA data is not
present, P$AUX also equals 4.
P$FNC
The function code. The significance of this field is dependent on the device type (P$TTYP).
The following values are defined for interactive CRT devices.
Value Description
03 MESSAGE WAITING key input. This value is set in an input message by CMS
if MESSAGE WAITING input is received and conversational link is in effect
for the PID. If conversational link is not in effect, the MESSAGE WAITING
input is processed by CMS. The input is not passed to any program.
012 Function key input. The value in P$KEY identifies which key input was
received. All the function key values (P$FNC = 12) are set up by CMS in an
input message.
The following values are defined only for the UNISCOPE 100/200 and UTS 400 terminals:
Value Description
013 Activate the auxiliary interface. This value is set by an application program in
an output message. It activates the interface to auxiliary devices connected
to the terminal that receives the message. The P$DID field specifies the
device-id of the device to select. A DC2 character is always appended to the
text by the terminal handler.
014 THRU response. This value is set in an input message by CMS when the
auxiliary interface is ready for another message and conversational link is in
effect for the PID. If conversational link is not in effect, CMS processes the
THRU response. It is not passed to any program.
015 This function is similar to 013 except that the terminal handler does not
append a DC2 to the text. Normally, the text should contain a peripheral
initiation sequence, such as DC2, ESC DC2, or ESC H. The P$DID field
specifies the device to select.
4–24 7833 1568–004

Value Description
CMS Interface
020 If this value is specified in an output message, the terminal bell rings at the
same time the message (0 or more characters) is sent. The next MESSAGE
WAITING key input is given to the exclusive-use linked program, if any,
unless it is given to the error notification program (see 5.3). That MESSAGE
WAITING input may be used by the program to send another output or to
take some other action. The program may send a message again, using the
020 value, before receiving the MESSAGE WAITING input that reactivates
the bell. Although somewhat different, depending on application, this
functionality may be used instead of the older functionality provided by the
combination of conversational link and unsolicited output (see 3.5.1 and 3.5.4,
and 5.5.1 and 5.5.8). When this value is used in an output message, the
function and subfunction fields of P$OUTQ should be 0, and exclusive-use
should be in effect.
061 This value is set in an input message if conversational link is in effect for the
PID. It indicates that a power-on-confidence status (DLE6) was received from
the auxiliary interface. It is returned only for OFIS Link_ terminals.
067 This value is set by MCB in a pass-off message that notifies an application
program that a session is aborted.
Note: For the auxiliary interface status values 070 and 073 to 076, an input message is
created only if conversational link is in effect. If conversational link is not in effect, then
the status is processed entirely by CMS.
Value Description
070 This value is set by in an input message if conversational link is in effect for
the PID. The value indicates that a DLE8 status was received from the
auxiliary interface.
071 This value is set by MCB in a pass-off message that notifies an application
program that a session is closed by the peer. (See 5.11 for more information.)
073 This value may be set in an input message if conversational link is in effect
for the PID. The value indicates that an Error1 status was received from the
auxiliary interface.
074 This value is set in an input message if conversational link is in effect for the
PID. The value indicates that an Error2 status was received from the auxiliary
interface.
075 This value is set in an input message if conversational link is in effect for the
PID. The value indicates that a No Status code was received from the
auxiliary interface.
076 This value is set in an input message if conversational link is in effect for the
PID. The value indicates that a No Error code was received from the auxiliary
interface.
7833 1568–004 4–25

CMS Interface
P$FORMAT
This field contains a value that defines the protocol or format of the text. Currently,
the only defined value is
1 = device dependent
The values 0 to 037 are reserved for future use by CMS. The values 040 to 057 are
reserved for other Unisys software such as Display Processing System. The values
060 to 077 are available for definition by any application.
P$ROW
P$COL
This field contains one of the cursor coordinates for the text. For an input message,
this is the row on which the input text began. For an output message, this is the row
on which to begin the text. Not all devices have cursors, and not all devices with
cursors transmit coordinates. In these cases, this field and P$COL are zero.
The field contains the other cursor coordinate for the text. For an input message, this
is the column in which the input text began. For an output message, this is the
column in which to begin the text.
P$TTYP
The logical device type. This field is set up by CMS for each input message.
Currently, the possible values are
001 UNISCOPE 100 terminal
002 UNISCOPE 200 terminal
003 DCT 500
004 DCT 1000
005 UTS 400
014 TTY
015 UTS 10
016 UTS 20
017 UTS 40
020 DATASPEED 40/4
021 DATASPEED 4540
022 DATASPEED 40/4 printer
023 UTS 10B (UTS 10 in buffered mode)
024 SPERRYLINK desk station (UDSSP)
025 UTS30
026 UTS60
027 IBM 3270
4–26 7833 1568–004

CMS Interface
030 UDS40 (SPERRYLINK desk station)
031 SVT1210 (asynchronous terminal), VT100, VT101, VT102, VT131
032 SVT1220 (asynchronous terminal), VT 220
033 CMS (host-to-host)
034 Transport TTY
035 Telnet NVT
036 LT 300
037 IBM 3270 EBCDIC
0100 open OLTP terminal type (not set by CMS)
0200 HTML terminal (not set by CMS)
The values 1 to 037 and 0101 to 0277 are reserved for future use by CMS. You may
define the values 040 to 077 and 0300 to 0377. (See also P$RTYP and 3.5.10 for more
information.)
P$KEY
The physical function key value. When function key input is received, an input
message is created that may or may not have text. The value in this field identifies
the specific key that was received. The field is set by CMS in an input message
when P$FNC is 012. For the physical function key values for other terminal types,
see the appropriate terminal hardware documentation.
The values for the UTS 400 function keys are listed in Table 4–2.
Table 4–2. Values for UTS 400 Function Keys
Key Label P$KEY ASCII
Character
MSG-WAIT BEL 007
P$KEY
Octal
Value
F1 � 067 01
F2 � 107 02
F3 � 127 03
F4 � 147 04
F5 Space 040 05
F6 � 041 06
F7 � 042 07
F8 � 043 010
F9 � 044 011
P$LKEY
Octal
Value
7833 1568–004 4–27

CMS Interface
Table 4–2. Values for UTS 400 Function Keys
Key Label P$KEY ASCII
Character
P$KEY
Octal
Value
F10 � 045 012
F11 � 046 013
F12 � 047 014
F13 � 050 015
F14 � 051 016
F15 � 052 017
F16 � 053 020
F17 � 054 021
F18 � 055 022
F19 � 056 023
F20 � 057 024
F21 � 060 025
F22 � 061 026
P$LKEY
Octal
Value
P$LKEY
The logical function key index. This value is present when P$KEY is nonzero. The
value is derived by CMS from the configuration parameters. See the CMS 1100
Programming Reference Manual.
P$TXN
This field contains the text offset to the first character of the transaction, for
example, the first character of text beyond device-dependent data (contained in the
preamble). A value of 1 indicates that no preamble data is present, a value of 2
indicates one character of preamble data, a value of 3 indicates two characters. For
the applications program interface, P$TXN is filled by MCB. For the CMS interface,
P$TXN may be filled by CMS, or MCB computes this value on the first store-input
call with bit 15 of P$FLAGS set (see 4.5.1).
P$PRIM
This field contains the text offset for the beginning of a read function by a
COMPOOL compatible primitive.
P$SESSION
This field contains the reason for a session state change. Some of the values are
passed by CMS in P$QID (see 4.5.12). This field will contain the NAK reason code
returned by CMS if an output message is negatively acknowledged (see 4.5.8). You
4–28 7833 1568–004

P$CAT
CMS Interface
must specify at least four words of auxiliary data area to accept returned NAK reason
codes. If you are using CMS level 5R1 or higher, CMS returns NAK reason codes to
the MCB when output messages are negatively acknowledged. A value of 0777 is
used for notification of the $BREAK II keyin. See the MCB Operations Reference
Manual.
This field identifies the device category from which an input was received or to
which an output is being sent. The Distributed Communications Architecture (DCA)
defines the values for the field. CMS sets the field for every input message, and the
application program sets the field for every output message. A value of zero has a
special meaning (discussed with P$DID). The values for this field are
• Category 1, Presentation Devices, is for auxiliary printers connected to a CRT.
Examples are the UNISCOPE 100 COP printer, the TP 800 printer, the 0786
printer, and the DCT 1000 auxiliary printer.
P$DID
• Category 2, Acquisition Devices, is for auxiliary input devices connected to a
CRT. There are currently no examples of such devices.
• Category 3, Conversational Devices, is for devices capable of both input and
output. In the case of CRTs, it refers to the screen.
• Category 4, Storage Devices, is for auxiliary output devices such as card punches
or paper tape punches.
• Category 5, Retrieval Devices, is for auxiliary input devices not connected to a
CRT. Examples are the DCT 1000 card reader or teletypewriter paper tape
reader.
• Category 6, Storage/Retrieval Devices, is for auxiliary devices that are capable of
both input and output. An example is the TCS 610 tape cassette system.
The DID or device identifier. If P$CAT is zero, this field contains the hardware
device-id (DID) for the device that is to receive an output message or from which an
input message was received. CMS sets the field on every input; the application
program sets the field on every output.
If P$CAT and P$DID are both zero in an output message, the message is not sent to
any auxiliary device. If P$CAT is nonzero, this field specifies the logical device
number within the category that is to receive an output message or from which an
input was received. For an output message, the device number specified must exist
and be assignable by CMS. If not, the message cannot be delivered.
P$HDR
The offset into the output message for the MCB to place its header, if any. If
P$HDRSIZE is zero, P$HDR is ignored. The value in the field is in characters from the
beginning of the message. (1 is the first character, 2 is the second character.) If this
field is zero, the MCB does not create a header.
If the field is nonzero, the MCB assumes that there are P$HDRSIZE characters in the
user text that may be overlaid. MCB also assumes that any necessary control
7833 1568–004 4–29

CMS Interface
sequences (cursor positioning, for example) are present in the text and are not
included in the P$HDRSIZE characters.
The MCB inserts only alphanumeric ASCII characters in the message. If the message
length is not large enough to hold all P$HDRSIZE characters, the header is truncated.
This field must be set by Display Processing System or the calling program, when
output message numbering is needed and the destination PID is configured with the
unintelligent numbering option (see 5.9.2).
P$HDRSIZE
The size of the output header. If P$HDR is zero, the field has no meaning. If P$HDR
and P$HDRSIZE are both nonzero, any header is limited to the number of characters
specified in P$HDRSIZE. Note that this may result in truncation of the header.
P$HDRSIZE must be at least 60 to avoid truncation.
P$RTYP
The hardware device type. This field is set up by CMS for each input message. The
values can be the same as those for P$TTYP. In most cases, the actual value will be
the same as P$TTYP on any one message. The exception is when P$RTYP is equal
to 027 (the code for 3270). In this case, P$TTYP may be controlled by the transaction
program system (see 3.5.10).
P$RSTYP
P$CCS
The terminal subtype. This field is supplied by CMS for each input message. The
terminal subtype value can be defined in the terminal configuration. This is a
site-specified value that further identifies the terminal type. Unisys software is not
sensitive to terminal subtype values. This field is not used as a terminal subtype on
output, but is part of a different field (see P$HDR).
The coded character set. This field is supplied by CMS for each input message. Table
4–3 lists the currently defined values.
Table 4–3. Values for the Coded Character Set
Decimal Octal Explanation
1 01 ASCII/ISO character set. The data is expected to be in the
United States variant of ISO 646. Historically, however, this
value has also been used to indicate any quarter-word
character set (in contrast to sixth-word Fieldata).
2 02 ASCII/APL character set
3 03 Extended Binary Coded Decimal Interchange Code (EBCDIC)
4 04 Raw binary
5 05 Untyped data or application-dependent data
6 06 Column binary format character set
4–30 7833 1568–004

Table 4–3. Values for the Coded Character Set
Decimal Octal Explanation
7 07 Reserved for use by the operating system
CMS Interface
8 through 13 (octal values 010 through 015) are reserved for customer use. These character
sets are assumed to be ASCII-like.
14 016 Hangul character set
15 017 Hanzi character se
16 020 JIS 16 18-bit Kanji format character set
17 021 ISO 646 United States
18 022 646 Norway/Denmark
19 023 646 France
20 024 646 Germany
21 025 United Kingdom
22 026 Italy
23 027 Spain
24 030 Sweden
25 031 Finland
26 032 Canada
27 033 Netherlands
28 034 Portugal
29-32 035-040 Reserved for future definition of ISO character sets
33-34 041-042 Reserved for customer use
35 043 ISO 8859.1 Latin Alphabet No. 1
36 044 ISO 8859.1 Latin Alphabet No. 2
37 045 ISO 8859.1 Latin Alphabet No. 3
38 046 ISO 8859.1 Latin Alphabet No. 4
39 047 ISO 8859.5 Latin/Cyrillic
40 050 ISO 8859.6 Latin/Arabic
41 051 ISO 8859.7 Latin/Greek
42 052 ISO 8859.8 Latin/Hebrew
43 053 ISO 8859.9 Latin Alphabet No. 5
44 054 ISO 8859.10 character set (box drawing set)
45 055 French/Arabic character set
46 056 Katakana character set
7833 1568–004 4–31

CMS Interface
Table 4–3. Values for the Coded Character Set
Decimal Octal Explanation
47 057 BICS character set
48-50 060-062 Reserved for future definition of ISO character sets
51-61 063-075 Reserved for arbitrary future use Assumed to be not
ASCII-like
62-63 076-077 Reserved for future use
4–32 7833 1568–004

Section 5
Application Program Interface
5.1. General Description
This section describes a packet-driven interface that you can use in any application
program that requires the functions of Message Control Bank (MCB). The Display
Processing System can also use this interface, on behalf of application programs, to
access MCB instead of COMPOOL. This is the recommended interface for application
programs. It offers a richer set of functions and a shorter path length than the MCB TIP
primitive interface discussed in Section 6.
Any program activity that uses the MCB through this interface must use the initialize
function first. This function defines a unique program step that may or may not have an
associated input, pass-off, or checkpoint message to process. A program step may be
started without reading an associated input or passoff message. An example of such a
program is a batch program to send an unsolicited broadcast message to all terminals. A
program activity that executes as a program step with the MCB may concurrently
interface to Universal Database Control for database access and update. If so, the
program step message processing and database processing are coordinated for
recovery. See the Integrated Recovery Conceptual Overview.
The use of a multiactivity program is restricted in these ways:
• A multiactivity transaction program may have only one activity that executes as a
program step and interfaces to the MCB.
• A multiactivity batch or demand program may have two or more activities, each
executing as an independent program step interfacing to the MCB. Two user
program activities may not interface to the MCB with respect to the same message.
Any program calling the MCB must be executing in quarter-word mode at the time the
MCB is called. If the program is not in quarter-word mode, program error code 04 (see
Appendix B) is returned.
MCB provides a sample library of subroutines that you can use to call MCB. See
Appendix G for more information.
7833 1568–004 5–1

Application Program Interface
5.2. Basic Mode High-Level Calling Sequence
An application program written in Meta-Assembler (MASM) can invoke the calling
sequence explained in 3.4 or enter the MCB with
���� ��� �������������
An application program written in ASCII FORTRAN (FTN) can enter the MCB with
���� ��� ���������������
An application program written in ASCII COBOL (ACOB) can enter the MCB with
���� ������ ����� ������ �����������
The subroutine with entry points MCB and CMCB is included in the TIP library files
and is generated with the relocatables for the TIP primitives. The STATUS word
contains the program error code, if any, returned by the MCB. For a complete list of
these error codes, see Appendix B.
The calling program of the MCB should have the following addressing environment at the
time the MCB is entered:
• The main I-bank (BDR0) is the calling program’s I-bank. This bank is unbased by the
MCB when the LBJ is done, and is rebased when the MCB returns control to the
calling program.
• The main D-bank (BDR2) holds the packet and the data buffer that the application
program passes to MCB. MCB does not unbase this bank. This bank must not be
read-only, and its address limits must not overlap the MCB common banks that MCB
bases on BDR0 and BDR3. Because the upper limit for the MCB I-bank can be as
high as 0127777, set the lower limits of the application program bank at 0130000 or
higher. If the limit must be below 0130000, refer to the MCB Installation Guide.
• The utility I-bank (BDR1) can be empty or can have an I-bank based by the calling
program. This bank is unbased by the MCB and rebased before returning to the
calling program. The calling program must have neither the packet nor the data buffer
in this window when the MCB is called. The calling program’s bank must not be a
guaranteed entry-point bank.
• The utility D-bank (BDR3) can be empty or can have a D-bank based by the calling
program. This bank is unbased by the MCB and rebased before returning to the
calling program. As with the utility I-bank, neither the packet nor the data buffer can
be in this bank, and the bank must not be a guaranteed entry-point bank.
The product installation file (GN file) contains these sample basic mode templates for the
MCB packet. These templates can also be found in SYS$LIB$*PROC$ if you installed
MCB using SOLAR.
• MCBDEF-COB
• MCBDEF-FTN
• MCBDEF-MASM
5–2 7833 1568–004

Application Program Interface
The GN file also contains sample basic mode application programs that use the
templates for the MCB packet. The program names are
• EXAMPLE-COB EXAMPLE-COB uses a MASM routine GETADDR, located in the GN
file, to obtain buffer addresses for the MCB.
• EXAMPLE-FTN
5.3. Extended Mode High-Level Calling Sequence
An application program written in UCS FORTRAN (UFTN) can enter the MCB with
���� ������� �������� ������� ����� ����
An application program written in UCS COBOL (UCOB) can enter the MCB with
���� ��������� ����� ������ ������ ���� ���
An application program written in UCS C (UC) can enter the MCB with
������� ��������� �������� ������ ������
An application program written in UCS Ada (UADA) can enter the MCB with
������� �������� ������� ����� �����
See the Application Development Programming Guide for more information on writing
programs that access MCB.
Alternatively, entry-point name MCB$ENTn can be used instead of MCB$ENT, where n is
the step control application number. This method is not recommended because your
program cannot be ported to another application group without a symbolic rewrite.
The UFTN assumed noncontiguous arrays cannot be used in the argument list of a call to
the MCB.
The parameters are as follows:
• Parameter one points to the interface packet as shown in Figure 5–1 with the
following exceptions:
− P$BUFF must be zero. Parameter three is used instead of P$BUFF.
− P$RTN must be zero. Alternate return point cannot be used.
− P$MDL must be zero. Parameter four is used instead of P$MDL.
Packet words 020 and 021 exist only if packet cell P$VER contains the value 3.
An auxiliary area exists if packet cell P$AUX is nonzero. The auxiliary area
immediately follows the interface packet, at word 020 (if packet words 020 and
021 do not exist) or at word 022 (if packet words 020 and 021 exist).
• Parameter two points to a 36-bit word which MCB uses to return a status code.
Refer to Appendix B for a list of values returned.
7833 1568–004 5–3

Application Program Interface
• Parameter three points to the data buffer. This parameter is used instead of packet
cell P$BUFF. The buffer must be word-aligned. (If you want text to start at some
location in your buffer other than the first quarter of the first word, you can use the
packet cell P$OFF.) This parameter can be null for functions that do not require the
data buffer.
• Parameter four points to the multiple destination list. This parameter is used instead
of packet cell P$MDL. The destination list format is shown in section 5.5.8. This
parameter can be null when a multiple destination list is not required.
MCB requires read and write access to parameters one, two and three. MCB requires
read access to parameter four.
The product installation file (GN file) contains these sample extended mode templates for
the MCB packet. These templates can also be found in SYS$LIB$*PROC$ if you installed
MCB using the Software Library Administrator (SOLAR):
• MCBDEF-UCOB
• MCBDEF-UFTN
• MCBDEF-UMASM
• MCBDEF-UC/H
• MCBDEFCOPY/H
Note: In SYS$LIB$*PROC$, the elements MCBDEF-UC/H and MCBDEFCOPY/H are
listed as incremental elements MCBDEF-UC n/H and MCBDEFCOPYn/H, where n is the
application group number.
The GN file also contains sample extended mode application programs that use the
templates for the MCB packet. The program names are
• EXAMPLE-UCOB
• EXAMPLE-UFTN
• EXAMPLE-UC
5.4. Application Program Interface Packet
The packet shown in Figure 5–1 is used for all application program functions. On any
given function, only certain fields are used. The unused fields must be presented as
binary zero. The bit-numbering method used in this and other packets in this section is as
follows:
• The leftmost bit is the high-level bit (35).
• The rightmost bit is the low-level bit (0).
5–4 7833 1568–004

00
P$FUNC
function code
P$OFF
data offset
Application Program Interface
7833 1568–004 5–5
P$ID
message identifier
01 P$LENGTH request character count P$BUFF data buffer address
02 P$START start character point P$RTN return point
03
P$AUX
auxiliary data
P$FAC
facilities
P$VER
version
P$FLAGS
flags
04 P$PID terminal identifier P$MN message number
05 P$TC1 transaction code
06 P$TC2 transaction code P$ML message length
07 P$STEP1 step-id word 1
010 P$STEP1 step-id word 2
011 P$PROG program number P$NODE queue node
012
P$MODE
program mode
P$REQUE
requeue
P$TYPE
message type
013 P$RUNID generated run-id
014 P$OS1 originator's step-id word 1
015 P$OS1 originator's step-id word 2
P$RECOPT
recovery options
016 P$OUTQ output queue parameters P$MDL destination list
017
P$SAVE
Display Processing System screen number
P$WAIT
wait time
~020 P$SID1 site-id for the PID
~021 P$SID2
~022 start of auxiliary information
~ These words are optional.
Figure 5–1. Application Program Interface Packet
P$ERR
error code
P$LVL
When you use the application initialize or read input functions, word 016 is overlaid as
shown in Figure 5–2.
level

Application Program Interface
016 P$OUTQ output queue parameters P$MDL destination list
*016 P$TID timer-id or input timestamp
5.5. Functions
Figure 5–2. Application Program Interface Packet Overlay
The following information describes MCB functions available to application
programs through the application program interface. In the packet field
descriptions, mnemonics name the function code passed in the P$FUNC field. The
actual value for each function code is listed in Appendix A.
5.5.1. Initialize
You can use the Initialize function in one of these ways:
• Transaction program initialization with the MCB and step control. This may include
retrieval of the next input message from the wait queue for the transaction program,
or a step may be started with no input message.
• Online batch program initialization with the MCB, connection to TIP, and initialization
with step control. This may include retrieval of the next input message from the wait
queue for the batch program, or a step may be started with no input message. Batch
or demand program initialization with the MCB, connection to TIP, and initialization
with step control. This may include retrieval of a message from a specified input
queue, or a step may be started with no input message.
• For any of the cases that include message retrieval, all or part of the message may
be read by the program.
• If the message is nonrecoverable and the entire message has been read, it may be
released.
A program can use the Initialize function repetitively without using a terminate first. The
program must have no step outstanding at the time of the call to the MCB. Steps are
terminated by the Commit, Rollback, and Terminate functions, or Network Database
Server FREE, DEPART, or DEPART WITH ROLLBACK commands. A transaction program
or online batch program cannot start a step without retrieving a message on the first use
of this function. The message that causes a program to be executed must be read and
released before a step without an input can be started. The program must end the step
with commit, rollback, terminate, or Network Database Server command before starting
another step.
If a program issues the Initialize function more than once (multiple call) with message
retrieval specified, two results may occur:
• A new message is delivered to the program.
• Error code 022 is returned to the program because no message is waiting.
If a program uses the MCB packet interface to issue a multiple call while no messages
5–6 7833 1568–004

Application Program Interface
are waiting, the program remains initialized and can issue other MCB functions.
Programs that use MCB primitives are terminated from the MCB if no message exists
when the program issues a multiple INITAL call.
The Initialize function uses several Executive requests (ER):
• ER TRMRG$ is performed each time the function is used by a program.
• ER QI$NIT is performed each time the function is used by a transaction program to
retrieve a message.
• ER QI$CON is performed each time the function is used by a batch or demand, an
online batch program or by a transaction program to start a step without a message.
Step control parameters and any parameters of a retrieved message are always returned
to the MCB calling program. Message text can be returned. The Read Input function can
be used to read or reread message text after the function is completed. TIP TIMER input
may also be received using the MCB initialize function.
Note: If you terminate a program with the X keyin while the program is initialized with
the MCB, a short recovery of the application group is required.
The packet fields are used as follows:
P$FUNC
The function code TRINIT$$. This field is supplied by the calling program.
P$FAC
The facilities status field indicates the condition of system facilities at completion of
the request. MCB returns a value in the range 0 to 3. The following values are the
maximum current values of either Exec or MCB resources. Exec values are based on
core queue items or EXPOOL. MCB values are based on core buffers or MADs. If
the MCB is nonrecoverable, message retention file (MRF) usage is also included.
Exec MCB
0 = normal 0 = normal
1 = 50 percent in use 1 = 50 percent in use
2 = 80 percent in use 2 = 70 percent in use
3 = 90 percent in use 3 = 90 percent in use
P$LENGTH
This field contains the number of text characters requested for the message. If this
field is zero, no text is transferred to the calling program. If nonzero, the number of
characters or the entire message, whichever is less, is transferred to the calling
program. The message field length is in quarter words, which is supplied by the
calling program. When the last character of the message is read, the field is changed
by the MCB to show the number of characters actually transferred. This action is
described in bit 0 of P$FLAGS.
7833 1568–004 5–7

Application Program Interface
P$BUFF
The data buffer address. This data area is assumed to be in the main D-bank window
(BDR2). The field is supplied by the calling program.
P$START
P$PID
P$MN
The start character pointer. This value is the message-relative character at which to
begin reading. Message text characters are numbered sequentially from one. If this
field is zero, the value 1 (the first text character) is assumed. This field is supplied by
the calling program. If nonzero, the value must be less than or equal to the number
of characters in the message text. On return from this call, the field points to the
character following the last character read.
The input PID. This field is filled in by the MCB.
The input message number. This field is filled in by the MCB if a message is
retrieved. If the message is not numbered, zero is returned.
Note: The input PID, P$PID, and input message number, P$MN, may be applicable
to checkpoint and pass-off as well as network input if the checkpoint or pass-off is a
member of a checkpoint or pass-off sequence generated by a nonrecoverable
network input.
P$VER
P$OFF
P$AUX
The packet version number. The calling program must set this field to 3 to get the
site-id, if one exists, that is associated with the PID when an input message is to be
read. In addition, two extra words for P$SID1 and P$SID2 must be provided at the
end of the interface packet before the auxiliary data area.
The partial word in which the text is to begin in the user’s data buffer. The value 0
implies the first quarter of the word given in P$BUFF; four implies the first quarter of
the following word, and so forth. This field is supplied by the calling program.
The size in words of auxiliary data to be put in the request packet. If the value in this
field is not at least as large as the existing auxiliary data, an error condition exists,
and a status is returned to the calling program. The field is supplied by the calling
program. Upon return, this field is set by the MCB to the number of auxiliary words
of data actually present in the message. See 4.6 for a description of the auxiliary
contents.
5–8 7833 1568–004

P$FLAGS
The bits for this function are
P$WAIT
P$LVL
P$RTN
P$ML
Application Program Interface
Bit 0 Last block indicator (LBI). If set, the last character of the message was read. In this
case, P$LENGTH is set to the number of characters actually transferred. The bit is
set by the MCB.
Bit 1 When set, start a step without retrieving a message. If clear, retrieve a message or
return a status, if none is available. For a batch or demand program the waiting
time when no message is queued is determined by P$WAIT. This bit is set by the
calling program.
Bit 2 When set, release the message if it is nonrecoverable and the last character has
been read. Bits 1 and 2 cannot both be set. This bit is set by the calling program.
Bit 3 When set, retrieve the timestamp, in ER TIME$ format (milliseconds past
midnight), of when the message was put on the OS 2200 Step Control Input
Queuing Tree. The timestamp is returned in P$TID of the input packet by MCB.
Setting bit 3 also enables your application to log user HVSTAT data by setting
auxiliary area word 0 to the ASCII character string HVST (see 5.13).
Bit 13 If set, the message retrieved is a conversational link input message. This bit is set
by the MCB.
The length of time (in seconds) to wait for an input message if none exists at the
time the request is made. This field applies to batch and demand programs only.
The connect level for connecting a batch or demand, or online batch program to TIP.
Allowed level values are one, two, or three. See the Transaction Processing
Programming Reference Manual, for a definition of connect levels.
The return point. If the field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If the field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
The number of quarter words of text in the message. This field is filled in by the
MCB.
P$STEP1/P$STEP2
The unique identifier of this program step. The field is filled in by the MCB using
information returned by an ER QI$NIT or an ER QI$CON.
P$PROG
The transaction program number. This field is filled in by the MCB.
7833 1568–004 5–9

Application Program Interface
P$NODE
P$TID
The terminating node on the input queue from which the message should be
retrieved (batch or demand) or was retrieved (transaction or online batch). This field is
filled in by the MCB for transaction and online batch programs. The field is supplied
by a batch or demand program if P$FLAGS bit 1 is clear.
For TIMER input (P$TYPE = 6), this field is timer-id. For network input, checkpoint,
and pass-off messages (P$TYPE 1, 2, and 3), this is the timestamp, in milliseconds
past midnight, of when the message was put on the OS 2200 Step Control Input
Queuing Tree. This field is filled in by the MCB when P$FLAGS bit 3 is set to request
retrieval.
P$TYPE
The message type. This field is filled in by the MCB. The values are
1 = Network input
2 = Checkpoint
3 = Pass-off
4 = Output
Note: The only occurrence of P$TYPE = 4 on the Initialize function is when a
recoverable output message is forwarded to the system error program because
it is undeliverable to the network (see 8.2.4).
6 = Timer input
Note: For P$TYPE=6, see the P$OUTQ/P$MDL field for the timer-id.
7 = ROPL output (See SEND$ function in 5.5.8).
P$MODE
The program mode. This field is filled in by the MCB. The values are
0 = Normal mode
1 = Training mode
2 = Test mode
3 = Test or training mode
P$RUNID
The generated run-id of the program. This field is filled in by the MCB.
P$OS1/P$OS2
The unique identifier of the originator of the message. The field is filled in by the
MCB. This field is applicable only to output, pass-off and checkpoint messages.
5–10 7833 1568–004

P$OUTQ/P$MDL
Application Program Interface
The timer-id. This field is filled in by the MCB. It is meaningful only when the calling
program retrieves a timer input.
P$RECOPT
The recovery options. This field must be supplied if a step is started without getting a
message. If a message is retrieved, the MCB returns the step’s recovery options. In
a batch-connect program, all recovery options are meaningful (see 3.3.3).
P$TC1/P$TC2
P$ERR
The transaction code of the message. This field is filled in by the MCB and contains 1
to 6 ASCII characters terminated by a blank, if fewer than six characters. For a
checkpoint message (P$TYPE = 2), this field has the value supplied by the calling
program at store checkpoint time (see 5.5.10).
The error code. This field is filled in by the MCB from information returned by an ER
QI$NIT or an ER QI$CON. The field only applies to recoverable messages directed to
the system error program (see 8.2.4).
P$REQUE
The requeue count. The field is filled in by the MCB from information returned by ER
QI$NIT or ER QI$CON. The field denotes the number of times, if any, that this
recoverable message has been requeued for processing after a system failure or
application rollback.
P$SAVE
For a network input message, the field contains the value specified in some previous
output message. For pass-off and checkpoint messages, this field is zero.
P$SID1/P$SID2
5.5.2. Terminate
The site-id of the PID. This field is filled in by the MCB and consists of 1 to 8 ASCII
characters, left-justified and space-filled. It is supplied only when the application calls
the MCB with P$VER set to 3 and an input message is expected. Also, the PID
sending the message must have an entry and a site-id in the PID site-id table. The
site-id is returned in uppercase ASCII characters. If the site-id is not found in the
table, binary zero is returned in this field.
The Terminate function ends the association of a program with the MCB. If a step exists,
this function implies a commit with step termination. A checkpoint cannot be pending.
An ER TRMRG$ is always performed, and the calling program’s SWL is no longer
recorded by the MCB. The ER EXIT$ is never performed. Any batch, demand, or online
batch program is disconnected from TIP. In all cases, partially constructed output,
pass-off, or checkpoint messages are released. If a discrete receive has been done, that
message is also released. If auditing is turned on in the Exec, this function is not allowed
7833 1568–004 5–11

Application Program Interface
by a run-unit currently imparted to Universal Database Control (see 7.1). The packet fields
for this function are
P$FUNC
The function code TERM$$. This field is supplied by the calling program.
P$RTN
The return point. If this field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If the field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
P$ID
5.5.3. Commit
The message-id. This field must be zero.
The Commit function indicates a success point for a program. The current step can be
• Terminated
• Terminated and replaced by a checkpoint
• Advanced
If the first option is exercised, the program remains initialized with the MCB but it cannot
perform message processing. Another initialize is required to perform more message
processing and a terminate is necessary before termination. The second option is
solicited by creating a checkpoint message during the step. OS 2200 step control starts a
new step if a checkpoint message exists when a step terminates. In this case, the same
fields returned by the MCB on an initialize are returned in the packet. This function is not
allowed by a run-unit currently imparted to Universal Database Control. For such a
program, a DML FREE or DEPART command implies a commit point.
When the third option (advanced) is used, the step currently active remains active, and
another initialize is not allowed. In all cases, partially constructed output, pass-off, or
checkpoint messages are released. If a discrete receive is performed, that message is
also released.
The packet fields for this function are
P$FUNC
The function code COMMIT$$. This field is supplied by the calling program.
P$FAC
The facilities status (see 5.5.1). This field is filled in by the MCB.
P$RTN
The return point. If the field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If this field is nonzero, control is returned to
5–12 7833 1568–004

Application Program Interface
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
P$FLAGS
Bits to tell the MCB what to do. This field is supplied by the calling program. The bits
for this function are
Bit 8 If set, advance the step.
Bit 9 If set, terminate the step and release the input message. If a checkpoint
message exists, a new step is started by step control. Otherwise, the
program continues without a step.
If both bits are set, an error exists. If both bits are clear, the program recovery
options in effect for this program step determine the default.
P$STEP1/P$STEP2
P$ID
5.5.4. Rollback
The step-id. The program’s step-id is returned if an advance or terminate with
checkpoint pending was performed. Zero is returned if step terminate with no
checkpoint was performed.
The message-id. This field must be zero.
The Rollback function indicates the end of an unsuccessful step. The step may be
• Started over (resumed).
• Terminated and the input message, if any, requeued or released. If a recoverable
message exists, it is requeued. If a nonrecoverable message exists, it is released.
• Terminated and the input queued to the error program.
If the second or third option is exercised, the program remains associated with the MCB
but it cannot do message processing. Another initialize is required to perform additional
message processing, and a terminate is necessary before program termination.
If the first option is exercised, a recoverable input message held when the step started is
still available; if the input message is not recoverable and was not released previously, it
is also still available. This function is not allowed by a run-unit currently imparted to
Universal Database Control. For such a program, a DML DEPART WITH ROLLBACK
command implies a rollback. In all cases, partially constructed output, pass-off, or
checkpoint messages are released. If a discrete receive was performed, that message is
also released.
The packet fields for this function are
P$FUNC
The function code ROLBAK$$. This field is supplied by the calling program.
7833 1568–004 5–13

Application Program Interface
P$FAC
P$RTN
The facilities status (see 5.5.1). This field is filled in by the MCB.
The return point. If this field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If this field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
P$FLAGS
Bits to tell the MCB what to do. This field is supplied by the calling program. The bits
for this function are
Bit 10 If set, resume the current step with the same input message, if any. If a
nonrecoverable input has been previously released, resume with no input.
Bit 11 If set, terminate the step and requeue the input (if recoverable) or release
it (if nonrecoverable).
Bit 12 If set, terminate the step and queue the input to the system error program
(if recoverable). If the input is not recoverable, release it. If no bits are set,
the program recovery options in effect for this program step determine
the default. Only one of these bits may be set.
P$STEP1/P$STEP2
The unique identifier of the program step. The new unique identifier is returned by
the MCB. The values are
• Zero, if the step was terminated
• The current unique identifier, if the step resumed
P$ID
The message-id. This field must be zero.
5.5.5. Read Input
The Read Input function transfers message text from the MCB (or retention file) to the
calling program’s data area. An option is provided to release a nonrecoverable message if
the last character is read. Any part of a message can be read or reread, and a program
can use this function any number of times. The packet fields for this function are
P$FUNC
The function code RECV$$. This field is supplied by the calling program.
P$FAC
The facilities status (see 5.5.1). This field is filled in by the MCB.
5–14 7833 1568–004

P$ID
P$VER
Application Program Interface
The message-id. If nonzero, this field must be the value returned by the MCB on a
previous discrete receive function. If zero, the current input message is read.
The packet version number. The calling program must set this field to 3 to get the
site-id, if one exists, that is associated with the PID. In addition, two extra words for
P$SID1 and P$SID2 must be provided at the end of the interface packet before the
auxiliary data area.
P$LENGTH
The requested number of message text characters. If nonzero, the number of
characters or the remaining message text, whichever is less, is transferred to the
calling program. Refer to P$START below. This value is in quarter words, and the
field is supplied by the calling program. If P$FLAGS bit 0 is set on return, this field
contains the number of characters actually transferred.
P$BUFF
The data buffer address. This data area is assumed to be in the main D-bank window
(BDR2). The field is supplied by the calling program.
P$START
P$OFF
P$AUX
The start character pointer. This value is the message-relative character at which to
begin reading. If the field is zero, the read begins where the previous read or initialize
function left off. If P$START = 1, the auxiliary area is again returned to the calling
program (see P$AUX field).
The partial word in which the text is to begin in the user’s data buffer. The value 0
implies the first quarter of the word given in P$BUFF; the value 4 implies the first
quarter of the following word.
The size in words of auxiliary data to be put in the request packet. If the value in this
field is not at least as large as the existing data, an error condition exists, and a
status is returned to the calling program. The field is supplied by the calling program.
Upon return, this field is set by the MCB to the number of auxiliary words of data
actually present in the message. See 4.6 for a description of the auxiliary area
contents.
P$FLAGS
Bits to indicate what the MCB should do. The bits for this function are
Bit 0 Last block indicator (LBI). If set, the last character of the message was
read. In this case, P$LENGTH is set by the MCB to the number of
characters actually transferred.
7833 1568–004 5–15

Application Program Interface
Bit 2 If set, release the message if it is nonrecoverable and the last character
has been read. Bit 2 is supplied by the calling program. If not set, the
message is not released until the calling program issues a commit or
terminates.
0 When set, retrieve the timestamp, in ER TIME$ format (milliseconds past
midnight), of when the message was put on the OS 2200 Step Control
Input Queuing Tree. The timestamp is returned in P$TID of the input
packet by MCB. This bit is ignored if P$START is not equal to 1.
P$RTN
The return point. If this field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If the field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
P$SID1/P$SID2
The site-id of the PID. This field is filled in by the MCB and consists of one to eight
ASCII characters, left-justified and space-filled. It is supplied only when the
application calls the MCB with P$VER set to 3 and the PID has an entry in the PID
site-id table. The site-id returned in uppercase ASCII characters. If the site-id is not
found in the table, binary zero is returned in this field.
5.5.6. Release Input
The Release Input function releases a nonrecoverable input message or a discrete
receive message. If this function is used for a recoverable message, the MCB does
nothing. The function can be used whether or not the message was read. It is not
necessary to use this function since input messages can be released by other functions
or at the end of the step.
The packet fields for this function are
P$FUNC
The function code INPREL$$. This field is supplied by the calling program.
P$FAC
The facilities status (see 5.5.1). This field is filled in by the MCB.
P$RTN
The return point. If this field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If the field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
5–16 7833 1568–004

P$ID
Application Program Interface
The message-id. If P$ID = 0, the current input message is released. If nonzero, the
specified discrete receive message is released.
5.5.7. Cancel Output
The Cancel Output function discards a partially constructed output, pass-off, or
checkpoint message.
The packet fields for this function are
P$FUNC
The function code CANCEL$$.
P$RTN
The return point. If this field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If the field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
P$ID
P$FAC
The message-id. If this field is zero, there may be only one partially constructed
message outstanding and it is released. If the field is nonzero, it must be valid, and
the specified message is released.
The facilities status (see 5.5.1). This field is filled in by the MCB.
5.5.8. Store Output
The Store Output function constructs an output message. The calling program supplies
parameters and text for the message. The MCB retains that data and its own control
information in main storage, on mass storage, or both.
The packet fields for this function are
P$FUNC
The function code SEND$$. The field is supplied by the calling program.
P$FAC
The facilities status (see 5.5.1). This field is filled in by the MCB.
P$ID
The message-id. The field is zero when a new message is begun. The value returned
in this field is used to identify the message on future store functions if more than
one message is undergoing construction simultaneously. As long as a program has
7833 1568–004 5–17

Application Program Interface
P$VER
only one message under construction, this field may be zero on all store functions.
Bit 7 of P$FLAGS determines whether or not a new message is begun.
The packet version number. This field is supplied by the calling program with a value
of 3 to indicate that a site-id in P$SID1 and P$SID2 is being supplied instead of
P$PID. The packet should be two words longer for the site-id and the site-id should
exist for a valid PID in the PID site-id table.
P$LENGTH
The number of quarter words of text being presented with this call. The field is
supplied by the calling program.
P$BUFF
The data buffer address. This data area is assumed to be in the main D-bank window
(BDR2). The field is supplied by the calling program.
P$START
P$PID
P$OFF
P$AUX
The start character pointer. This value is the message-relative character at which to
begin storing, where the first character is denoted by P$START = 1. The value is
presented by the calling program. On return, it is set by the MCB to point to the
character following the last character stored on the call. If the field is zero, the new
text is appended to any existing text. If the field is nonzero, new text can overlay
previously staged text or be appended to any existing text.
The output PID. This field is filled in by the calling program. It may be a group
(multiple destination) PID. This field must not be used if P$MDL is nonzero. If a group
PID is specified, P$MN must be zero or the message numbering option must be
cleared; otherwise, error 053 is returned.
The partial word in which the text begins in the application program’s data buffer.
The value 0 implies the first quarter of the word given in P$BUFF; the value 4 implies
the first quarter of the following word. This field is supplied by the calling program.
The size in words of auxiliary data in the request packet. The maximum size allowed
for this data is 63 words. If the NAK reason code is to be supplied when a
recoverable message is negatively acknowledged, at least four words of auxiliary
area must be specified in this field (see 4.6). This field is supplied by the calling
program.
P$FLAGS
Bits to indicate what the MCB should do. The field is supplied by the calling program.
The bits for this function are
5–18 7833 1568–004

Application Program Interface
Bit 0 Last block indicator (LBI). If set, the message is to be queued to step
control when the data transfer is complete.
Bit 3 If set, and if P$PID identifies a group PID, the message is queued to one
member of the group as selected by the system. This is referred to as
rotary output. If not set, and if P$PID identifies a group PID, the message
goes to all the members of the group. If P$PID does not specify a group
PID, the bit is ignored. This bit is set by the calling program.
Bit 4 If set, MCB creates a delivery notification message when CMS has
successfully transmitted and acknowledged this output. The transaction
code given in P$TC1 and P$TC2 is used as the target for the delivery
notification message (see 5.10). Delivery notification is not provided for
multiple destination messages.
Note: If end-to-end acknowledgment is not used, the delivery notification
can occur before the output message has traversed the network. If you
want end-to-end acknowledgment, you can use intelligent message
numbering (see 3.2.3). Alternatively, you can configure CMS PID
statement with the GUARANTEE-DELIVERY or the AU-LABEL parameter.
See the Communications Delivery Software Configuration Guide for more
information. Any of these will cause CMS to delay acknowledging the
output message until the message has reached its destination and CMS
has received an acknowledgment. The scheduling of the delivery
notification message is not guaranteed to occur in the event of an
intervening system failure.
Bit 5 The options in P$RECOPT should be used for the message. If this bit is
not set, the output message recovery options in effect for the program
step are used by default.
Bit 6 Change the mode of the PID. If this bit is set, the value in P$MODE is
saved as the terminal mode. Once set, a mode stays in effect until
explicitly changed by an output message. The bit is ignored if P$PID is a
group PID or if P$MDL is nonzero. The bit is set by the calling program.
Bit 7 If set, this function applies to a partially staged output message. If not set,
start a new message. If the bit is not set, P$ID must be zero.
Bit 14 If set, save the value in P$SAVE to be returned with subsequent network
input messages. Every network input message contains the value (in
P$SAVE) that was last specified by an output to the PID from which the
input is received. Output messages without this bit set do not alter the
saved value (see 5.5.1).
Bit 16 If set, the auxiliary data area previously stored with the message is
replaced with the auxiliary data area presented with this call. When a new
message is started (P$ID = 0 and P$FLAGS bit 7 also = 0), the size of the
auxiliary data area for the message is determined by the value in P$AUX.
The size is unalterable after that. On subsequent calls the auxiliary data
area is left unchanged if bit 16 is not set. If bit 16 is set, the contents of
the auxiliary data area is completely replaced.
7833 1568–004 5–19

Application Program Interface
P$RTN
The return point. If the field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If the field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
P$STEP1/P$STEP2
The unique identifier of this program step. The field is filled in by the MCB from
information returned by ER TIP$ID. This is done only on the first Store function for a
given message. For reduced output path length (ROPL) messages or when a value of
7 is returned in P$TYPE, this field is unused and has no meaning.
P$TC1/P$TC2
The transaction code. This is a one- to six- ASCII character (quarter-word) field,
left-justified and space-filled. Only alphanumeric characters may be used. The field is
used in conjunction with some of the bits in P$FLAGS and for conversational link.
This field is supplied by the calling program. See also 3.3.5.
P$MDL
The destination list. This field contains the address of a list of PIDs to which the
message should be sent. None of the entries in the list may itself be a group PID. A
maximum of seven entries is allowed for a destination list. If a destination list is
specified, P$MN must be zero or the message numbering option must be cleared.
Figure 5–3 shows the destination list format.
0 number of entries first PID
01 second PID third PID
02 fourth PID fifth PID
03 sixth PID seventh PID
P$MODE
Figure 5–3. Multiple Destination List
The mode of the PID. This field is used to set the mode of the PID given in P$PID.
The field may not be used if P$PID is a group PID or if P$MDL is nonzero. Refer to
5.5.1 for a definition of P$MODE values. If the MCB configuration has ��������� ���
set to ���, the mode state is retained over a failure.
5–20 7833 1568–004

P$OUTQ
Application Program Interface
The P$OUTQ field is divided into three 6-bit subfields (function, subfunction, and
queuing priority), as shown below. These subfields become H1 of the second word
of the output queue entry which CMS receives on its output routing queue. The
effect of these subfields depends on CMS. The use of these subfields as described
here is supported by CMS 1100 and by SILAS, but not necessarily by other CMS
programs.
function subfunction queuing
priority
The function code values can be
0 Normal output
1 Unsolicited output message to an interactive terminal. The system notifies the
terminal of queued output, if feasible. he message is delivered when it is
solicited by the terminal operator.
04-05 Reserved for your site-developed application programs. Your site must supply
its own communications handlers to process these values. CMS negatively
acknowledges output that uses these values.
The subfunction code values can be
0 Nonconversational link output
1 Conversational link in effect
04-05 Reserved for your site-developed application programs. Your site must supply
its own communications handlers to process these values. CMS negatively
acknowledges output that uses these values.
The queuing priority field indicates the priority level:
Bits 2-0 Value of priority level, 0 through 7
If the function and subfunction codes are both 1, the system notifies the terminal by
actuating the bell or message-waiting light, and the next message-wait key input is
passed to the sending program.
If the subfunction is 1, a transaction code is assumed to be present in the P$TC1/P$TC2
field. The next input from the PID is directed to that transaction, regardless of the
message content. For subfunction = 1, the following conditions must be met:
• P$PID cannot specify a group PID.
• P$MDL must be zero.
• Conversational link and delivery notification cannot both be set (see Bit 4 of
P$FLAGS).
7833 1568–004 5–21

Application Program Interface
• If conversational link is being set while exclusive use is in effect, the following must
be considered: The message is processed by CMS as a conversational link output,
but the transaction code in P$TC1/P$TC2 is not used. Routing of the subsequent
input from the PID is governed by the exclusive use link. If exclusive use is cleared
before the subsequent input, the input is routed either to the program specified by
the transaction code associated with the message or to the Error Notification
Program. The preceding information also applies to input-only exclusive use, except
that any program can send conversational link output to the PID. The potential for
conflicts between application programs is greater. If one program has input-only
exclusive use of the PID, and a second program requests input through
conversational link, the second program does not receive the expected input. The
next input goes instead to the input-only exclusive use program, unless the
input-only exclusive use has been cleared.
P$RECOPT
The message recovery options. These bits determine how the message is handled.
The following bits have meaning for the function:
Bit 12 The message is deferred.
Bit 13 The message is recoverable.
Bit 14 The message text is audited.
Bit 15 The message is numbered.
Bit 16 The message is recallable.
Bit 17 The message has low main storage priority
P$ML
message length in quarter words. This field is returned by the MCB when P$FLAGS
bit 0 is set.
P$SAVE
For an output message, this field contains the value to be saved and returned with
subsequent input messages from the PID (P$ID). If P$FLAGS bit 14 is not set, the
field is ignored.
P$SID1/P$SID2
P$MN
The site-id of a PID. This field is filled in by the calling program with 1 to 8 ASCII
characters, left-justified and space-filled. P$VER must also be set to 3 and the site-id
must exist in the PID site-id table. This field is not used if P$MDL is nonzero. The
site-id can be in uppercase or lowercase ASCII characters. This field is 2 full words in
length. If the site-id is not found in the PID site-id table the function is rejected.
The message number. If this field is nonzero and the message numbering option is
set, the message is intelligently numbered. If the message is recoverable and
recallable, it can be recalled using this number. For this field to be meaningful, the
5–22 7833 1568–004

Application Program Interface
output PID in P$PID must be configured with intelligent numbering. This field is
supplied by the calling program.
P$TYPE
MCB returns a value of 7 in this field when the MCB sends a ROPL type message.
Notes:
• Only single PIDs are allowed as output PIDs in intelligent numbering. If a group PID
or a multiple destination list is specified as the destination, error 053 will be returned
(see Appendix B).
• The MCB accepts P$MN as it is. Therefore, this field must be cleared if intelligent
numbering is not required.
• If P$MN is zero, the message numbering option is set, and the destination PID is
configured with intelligent numbering, the message must be recoverable; otherwise,
an error status is returned.
5.5.9. Store Pass-Off
The Store Pass-Off function creates a message for delivery to another program. The
packet fields for this function are
P$FUNC
The function code PASOFF$$. This field is supplied by the calling program.
P$FAC
The facilities status (see 5.5.1). This field is filled in by the MCB.
P$ID
The message-id. This field is zero when a new message begins. The value returned
in the field identifies the message on future store functions if more than one
message undergoes construction simultaneously. As long as a program has only one
message under construction, the field may be zero on all store functions. Bit 7 of
P$FLAGS determines whether or not a new message is begun.
P$LENGTH
The number of quarter words of text presented with this call. The field is supplied by
the calling program.
P$BUFF
The data buffer address. This data area is assumed to be in the main D-bank window
(BDR2). The field is supplied by the calling program.
P$START
The start character pointer. This value is the message-relative character at which to
begin storing, where the first character is denoted by P$START = 1. The value is
presented by the calling program. On return, it is set by the MCB to point to the
7833 1568–004 5–23

Application Program Interface
P$OFF
P$AUX
character following the last character stored on the call. If the field is nonzero, it can
be used to overlay previously staged text or append text to any existing text. If the
field is zero, the new text is appended to any existing text.
The partial word in which the text begins in the application program’s data buffer.
The value 0 implies the first quarter of the word given in P$BUFF; the value 4 implies
the first quarter of the following word. This field is supplied by the calling program.
The size in words of the auxiliary data in the request packet. The maximum size
allowed for this data is 63 words. The field is supplied by the calling program, if
desired.
P$FLAGS
Bits to indicate what the MCB should do. The field is supplied by the calling program.
The following bits have meaning for this function:
Bit 0 Last block indicator (LBI). If set, the message is to be queuedto step
control when the data transfer is complete.
Bit 5 The options in P$RECOPT should be used for this message. If this bit is
not set, the input message recovery options for the target program are
used by default.
Bit 6 If set, the execution mode of the target program is given by P$MODE. If
clear, the execution mode of the calling program is passed along.
Bit 7 If set, this function applies to a partially staged pass-off message. If not
set, start a new message. If the bit is not set, P$ID must be zero.
Bit 16 If set, the auxiliary data area previously stored with the message is
replaced with the auxiliary data area presented with this call. When a new
message is started (P$ID = 0 and P$FLAGS bit 7 also = 0), the size of the
auxiliary data area for the message is determined by the value in P$AUX.
The size is unalterable after that. On subsequent calls, the auxiliary data
area is left unchanged if bit 16 is not set. If bit 16 is set, the contents of
the auxiliary data area is completely replaced.
P$RTN
The return point. If this field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If the field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
P$STEP1/P$STEP2
The unique identifier of this program step. The field is filled in by the MCB from
information returned by an ER TIP$ID. This is done only on the first store pass-off
function for a given message.
5–24 7833 1568–004

P$TC1/P$TC2
Application Program Interface
The transaction code. This is a one- to six- ASCII character (quarter word) field,
left-justified, and space-filled. Only alphanumeric characters can be used. The
recipient of a pass-off message is identified by this code. The transaction code is
assumed to be in the VINDEX of the MCB. The target of a pass-off can be either a
transaction program or a node of the input queue from which messages are
dequeued by batch or demand programs. The application program doing the pass-off
need not be cognizant of the difference. A transaction code must always be supplied,
except as noted for P$PROG. This field is supplied by the calling program.
P$PROG
The program number of the target program. This applies only if the transaction code
(P$TC1/P$TC2) is presented as zero. The transaction code and P$PROG must not
both be zero. This field is supplied by the calling program.
P$RECOPT
The message recovery options. These bits determine how the message is handled.
The field is optional. The bits for this function are
P$MODE
P$PID
Bit 6 The message is deferred.
Bit 7 The message is recoverable.
Bit 8 The message text is audited.
Bit 9 The message is numbered (see P$MN below).
Bit 10 The message is recallable (see P$MN below).
Bit 11 The message has low main storage priority.
The selected execution mode of the target program. This field is optional. See 5.5.1
for the definition of P$MODE values.
The value supplied in this field is returned to the program receiving the pass-off
message. If no PID is supplied, the input PID is returned to the receiving program. If
the pass-off message is recoverable, the PID from the last input message read
determines which message retention file is used. If no input message is read, the
first recoverable message retention file is used.
7833 1568–004 5–25

Application Program Interface
P$MN
P$ML
The message number. This field is filled in by MCB. If the current input message is
recoverable, numbering of the pass-off message is not performed and 0 is returned
in P$MN.
If the current input message is nonrecoverable, a recoverable pass-off message can
be numbered if specified by recovery options bit 9. In that case, message recall
(recovery options bit 10) can also be set. The message number is assigned from the
input message numbering sequence for the input PID. The input PID must have been
configured with the unintelligent message numbering option. If the input PID is
configured with the intelligent message numbering option, the message is not
numbered and no error status is returned.
Note: Only one pass-off or checkpoint message in a step can be numbered. If an
attempt is made to store a second such message, error 0131 is returned (see
Appendix B).
Total message length in quarter words. This field is returned by the MCB when
P$FLAGS bit 0 is set.
5.5.10. Store Checkpoint
The Store Checkpoint function creates a checkpoint message for a program. The packet
fields for this function are
P$FUNC
The function code CHKPT$$. This field is supplied by the calling program.
P$FAC
The facilities status (see 5.5.1). This field is filled in by the MCB.
P$ID
The message-id. This field is zero when a new message begins. The value returned
in the field is used to identify the message on future store functions if more than one
message is undergoing construction simultaneously. As long as a program has only
one message under construction, the field can be zero on all store functions. Bit 7 of
P$FLAGS determines whether or not a new message is begun.
P$LENGTH
The number of quarter words of text presented with this call. The field is supplied by
the calling program.
P$BUFF
The data buffer address. This data area is assumed to be in the main D-bank window
(BDR2). The field is supplied by the calling program.
5–26 7833 1568–004

P$START
P$OFF
P$AUX
Application Program Interface
The start character pointer. This value is the message-relative character at which to
begin storing, where the first character is denoted by P$START = 1. The value is
presented by the calling program. On return, it is set by the MCB to point to the
character following the last character stored on the call. If it is nonzero, this field can
overlay previously staged text or append text to any existing text. If the field is zero,
the new text is appended to any existing text.
The partial word in which the text begins in the application program’s data buffer.
The value 0 implies the first quarter of the word given in P$BUFF, and the value 4
implies the first quarter of the following word. This field is supplied by the calling
program.
The size in words of auxiliary data in the request packet. The maximum size allowed
for this data is 63 words. The field is supplied by the calling program.
P$FLAGS
Bits to indicate what the MCB should do. The field is supplied by the calling program.
The following bits have meaning for this function:
Bit 0 Last block indicator (LBI). If set, the message is to be queued to step
control when the data transfer is complete.
Bit 5 Use the options in P$RECOPT for this message. If the bit is not set, the
input message recovery options for the program step are used by
default.
Bit 7 If set, this function applies to a partially staged checkpoint message. If
not set, it starts a new message. If the bit is not set, P$ID must be zero.
Bit 16 If set, the auxiliary data area previously stored with the message is
replaced with the auxiliary data area presented with this call. When a
new message is started (P$ID = 0 and P$FLAGS bit 7 also = 0), the size
of the auxiliary data area for the message is determined by the value in
P$AUX. The size is unalterable after that. On subsequent calls, the
auxiliary data area is left unchanged if bit 16 is not set. If bit 16 is set, the
contents of the auxiliary data area are completely replaced.
P$RTN
The return point. If this field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If this field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
P$STEP1/P$STEP2
The unique identifier of this program step. The field is filled in by the MCB from
information returned by an ER TIP$ID. This is done only on the first store function for
a given message.
7833 1568–004 5–27

Application Program Interface
P$RECOPT
The recovery options for the message (see P$FLAGS, bit 5). These bits determine
how the message is handled. Note that a checkpoint message is presumed to be
recoverable and deferred. The bits for this function are
Bit 6 The message is deferred (always assumed to be set).
Bit 7 The message is recoverable (always assumed to be set).
Bit 8 The message text is audited.
Bit 9 The message is numbered (see P$MN).
Bit 10 The message is recallable (see P$MN).
Bit 11 The message has low main storage priority.
P$MN
The message number. This field is filled in by MCB. If the current input message is
recoverable, the checkpoint message is not numbered and 0 is returned in P$MN.
If the current input message is nonrecoverable, a recoverable checkpoint message
can be numbered if specified by recovery options bit 9. In that case, message recall
(recovery options bit 10) can also be set. The message number is assigned from the
input message numbering sequence for the input PID. The input PID must have been
configured with the unintelligent message numbering option. If the input PID is
configured with the intelligent message numbering option, the message is not
numbered and no error status is returned.
Note: Only one pass-off or checkpoint message in a step can be numbered. If an
attempt is made to store a second such message, error 0131 is returned (see
Appendix B).
P$ML
Total message length in quarter words. This field is returned by the MCB when
P$FLAGS bit 0 is set.
P$TC1/P$TC2
The transaction code. This field should contain the transaction code of the calling
program; otherwise, no transaction code is associated with the checkpoint message.
Typically, the application can save P$TC1/P$TC2 after initialization with the MCB (by
reading a network input or pass-off message), after which it restores this field in the
interface packet when it performs a store checkpoint. The MCB does not check on
this field.
5–28 7833 1568–004

5.5.11. Enqueue Message
Application Program Interface
The Enqueue Message function allows a program to queue a message to step control
without storing additional text. Some text must be stored prior to the use of the function.
A store function can also be used to enqueue the message.
The packet fields for this function are
P$FUNC
The function code ENQUE$$.
P$ID
The message-id. If P$ID = 0, at least one partially staged output, pass-off, or
checkpoint message must exist. The oldest message, that is the message that was
stored first, is enqueued. Any other partially staged messages are ignored. If no
message exists, an error status is returned.
P$RTN
P$FAC
P$ML
5.5.12. Audit
The return point. If this field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If the field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
The facilities status (see 5.5.1). This field is filled in by the MCB.
Total message length in quarter words. This field is returned by the MCB.
The Audit function puts a user data record on the audit trail. A single block of data can be
written; no scatter-gather operation is provided. The MCB appends a record header to
the data to denote it as site-supplied audit record and to identify the calling program step.
The packet fields for this function are
P$FUNC
The function code AUDIT$$.
P$FAC
The facilities status (see 5.5.1). This field is filled in by the MCB.
P$LENGTH
The length in words of the data to be audited. This value must be greater than seven
and less than the maximum allowed by audit control.
7833 1568–004 5–29

Application Program Interface
P$BUFF
P$RTN
P$ID
The data buffer address.
The return point. If this field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If the field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
The message-id. This field must be zero.
5.5.13. Discrete Receive
The Discrete Receive function allows a program to recall an input or output message,
given a PID and a message number. Not all messages are recallable. To be recalled, a
message must be marked as recoverable, numbered, and recallable at the time of
creation; for output messages, transmission must have begun. Pass-off and checkpoint
messages can also be numbered and recallable under certain conditions. See 5.5.9 and
5.5.10.
This function can be used while a normal input is associated with a program. Only one
message at a time, however, can be read using the function. This function is used for the
initial access to the message. The normal read input function is used to read more text or
to reread text. The release input function can be used to release the message.
The packet fields for this function are
P$FUNC
The function code DISREC$$. This field is supplied by the calling program.
P$FAC
The facilities status (see 5.5.1). This field is filled in by the MCB.
P$ID
The message-id. This field must be zero, and no discrete receive message can be
associated with the program. On return, the field contains a value that must be used
on subsequent read input or release input functions for the message.
P$LENGTH
The number of quarter words of text to be read. This field is supplied by the calling
program and can be zero.
P$BUFF
The data buffer address. This field is supplied by the calling program. The address is
assumed to be in the main D-bank (BDR2) window.
5–30 7833 1568–004

P$START
P$PID
P$OFF
P$AUX
Application Program Interface
The start character pointer. This value is the message-relative character at which to
begin reading where, the first character is denoted by P$START = 1. If the field is
zero, the read begins with the first text character. If nonzero, the value must be less
than or equal to the number of characters in the text. On return, the field is set to
point at the character following the last one read.
The PID. This field is filled in by the calling program and is used with the message
number to locate the message. For checkpoint and pass-off messages, the field
refers to the PID of the originator of the message.
The data offset. This field is supplied by the calling program. It specifies the partial
word in which the text should start in the user data buffer (P$BUFF). Zero implies the
first quarter of the word given in P$BUFF, and four implies the first quarter of the
following word.
The size in words of auxiliary information in the request packet. This field is supplied
by the calling program, and can be 63 words at most. If the value in the field is not at
least as large as the data that exists, an error status is returned. Upon return, this
field is set by the MCB to the number of words of auxiliary data actually present in
the message.
P$FLAGS
The following bits are defined for this function:
Bit 0 Last block indicator (LBI). If set, the last character of the message was
read. In this case, P$LENGTH is set to the number of characters actually
transferred.
Bit 2 Release the message if the last character is read on this request. The bit
is set by the calling program.
P$STEP1/P$STEP2
P$MN
P$RTN
The unique identifier of the program step. This field is filled in by the MCB using
information from the message control area (MCA).
The message number. This field is supplied by the calling program, and used along
with the PID to locate the message.
The return point. If this field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If the field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
7833 1568–004 5–31

Application Program Interface
P$TYPE
P$ML
The message type. This field identifies whether the specified message number
applies to the input message numbering sequence or the output message
numbering sequence for the specified PID. The value for input messages is one, the
value for checkpoint messages is two, the value for pass-off messages is three, and
the value for output messages is four.
The message length. This field contains the number of quarter words of text in the
message. The field is filled in by the MCB.
P$PROG
The transaction program number of the program that received the message (if the
message is an input message). For an output message, the field is zero. This field is
filled in by the MCB.
P$NODE
The terminating node on the input queue to which the message was queued (if the
message is an input message). For an output message, the field is zero. This field is
filled in by the MCB.
P$RECOPT
The recovery options that applied to the message. This field is filled in by the MCB.
P$TC1/P$TC2
If an input message, this field contains the transaction code that was presented with
the message by CMS. For an output message, the field is zero. This field is filled in
by the MCB.
5.5.14. Open a Session
This function allows an application program to request that CMS open a session between
CMS and a specified PID. The result of the attempt is reported to the calling program. If
error status 0112 is returned, the P$SESSION field of the auxiliary area contains a
detailed error status with the reason for failure to open a session. If the request is
successful, later changes in the state of the session are reported to an application
program specified in the request packet (see 5.5.11).
In a failure, if the MCB configuration has the RESILIENT SGS set to YES, the PID table in
the MRF control file (on mass storage) is updated, allowing open session information. If
the CMS configuration has the RESILIENT parameter set on the APPLICATION NDS, and
a CMS failure occurs, the PID is reopened by CMS. If an MCB failure occurs with this
configuration, CMS keeps the session open over the failure.
If a session is aborted, MCB notifies the transaction specified (in P$TC1/P$TC2) when
the session was opened by generating a pass-off message that contains the PID and an
error code. The pass-off message sent to the transaction contains 20 characters of text
and an auxiliary data area of four words (see 5.11). The PID number is in P$PID and the
5–32 7833 1568–004

Application Program Interface
error code is in P$SESSION. The error codes returned in P$SESSION are the same as
those defined for the P$QID field on the CMS session status notification function (see
4.5.12).
The packet fields for this function are
P$FUNC
The function code OPNSSN$$. This field is supplied by the calling program.
P$PID
The PID to which a session should be opened. Group PIDs are not allowed. See the
CMS REMOTE-EU network definition statement in the CMS 1100 Installation and
Configuration Guide.
P$FAC
P$RTN
The facilities status (see 5.5.1). This field is filled in by the MCB.
The return point. If this field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If the field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
P$TC1/P$TC2
P$AUX
The transaction code to which future session state changes should be reported. If
this field is blank or zero, no program will be notified of any session state changes.
This field also identifies the program allowed to close this session. If this field is zero
or blank, no program is allowed to close this session. See also 3.3.5.
The size of the auxiliary information in the request packet. The field is supplied by the
calling program and must have a value greater than or equal to 4.
Notes:
• Any program doing a session open must have the V option set (either with the
VALTAB field, OPT,V, or the XQT option, @XQT,V). This is required for the ER
RT$OUT, which is done internally.
• To satisfy an outbound session open request, MCB communicates with all initialized
CMS programs that claim to support outbound open. MCB queues the open request
to each initialized CMS program one at a time in ascending CMS number order, until
all have been tried or until one of the CMS programs reports the session is
successfully opened.
If all initialized CMS programs reject the request, the error code from the last tried
CMS is returned to the caller in P$SESSION. The exception to this rule is that if the
last tried CMS returned the “PID not configured” error code of 01 (see 4.5.12), the
calling program receives the error code from the last tried CMS that returned an error
other than 01. If all CMSs returned the 01 error code, the calling program receives
the 01 error code in P$SESSION.
7833 1568–004 5–33

Application Program Interface
5.5.15. Close a Session
This function allows an application program to direct CMS to close any session that can
exist with a PID. The only application program allowed to close the outbound open
session is a program running with the transaction code of the session state change
notification program (see 5.5.14 and 5.5.17). The result of the attempt is reported back to
the calling program (see 5.11). If error status 0112 is returned, the P$SESSION field of
the AUX area contains a more detailed error status. P$SESSION values are those listed
under P$QID in 4.5.12.
The MCB packet fields for this function are
P$FUNC
The function code CLSSN$$. This field is supplied by the calling program.
P$PID
The PID for which the action is requested.
P$FAC
The facilities status (see 5.5.1). This field is filled in by the MCB.
P$RTN
The return point. If this field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If the field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
P$AUX
The size of the auxiliary information in the request packet. The field is supplied by the
calling program and must have a value greater than or equal to 4.
Note: Any program doing a session close must have the V option set (either with the
VALTAB field, OPT,V, or the XQT option, @XQT,V). This is required for the ER RT$OUT,
which is done internally.
5.5.16. Request PID Status
This function allows an application program to retrieve the state of a PID from the MCB
PID table. It retrieves only a single PID entry from the table and returns it in words
07-015 of the calling program’s packet. This function allows an application program to
know everything about a PID that is known to the MCB. The format of the information
returned in words 07-015 is defined in F.7.1.
The packet fields for this function are
P$FUNC
The function code PIDSTAT$$. This field is supplied by the calling program.
5–34 7833 1568–004

P$PID
P$RTN
P$FAC
The PID for which the status is requested.
Application Program Interface
The return point. If this field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If the field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
The facilities status (see 5.5.1). This field is filled in by the MCB.
5.5.17. Obtain Exclusive Use of a PID
This function allows an application program to gain exclusive use of a PID. It is used by
an application program to obtain future input from a specific PID, and to exclude
intervention by other programs. Exclusive use can be established only by a program that
is processing a message. The program must have an MRF identifier in its queue item.
Once exclusive use is established, it remains in effect until the owner program ends it
with the release exclusive use function (see 5.5.18). The $BREAK II keyin can also be
used by an operator to arbitrarily release exclusive use of a PID (see the MCB Operations
Reference Manual). When a PID is assigned for exclusive use, MCB rejects output to the
PID from programs other than the owner program. This exclusive use link can exist in
addition to other sessions opened by the program.
When it requests exclusive use, the owner program supplies a transaction code (in the
P$TC1/P$TC2 packet fields) identifying the program to which all future input is directed
(this can be different from the owner’s transaction code). If the owner is not the program
identified by P$TC1/P$TC2, the transaction program specified in P$TC1/P$TC2 cannot
send output to the PID or release exclusive use of that PID. This means that if the owner
directs input to another transaction, the owner still retains exclusive use of the PID.
If the MCB configuration has the RESILIENT SGS set to YES, the PID table in the MRF
control file (on mass storage) is updated. If an MCB or CMS failure occurs, the MCB
keeps exclusive use and exclusive use close notification in effect for the PID over the
failure. If the same program requests exclusive use, the request does not generate an
error. If the exclusive use session cannot be reestablished after a failure, the requesting
transaction is notified that the session is closed.
The packet fields for this function are
P$FUNC
The function code SETXUSE$$. This field is supplied by the calling program.
P$PID
The PID over which exclusive control is needed.
7833 1568–004 5–35

Application Program Interface
P$FAC
The facilities status (see 5.5.1). This field is filled in by the MCB.
P$FLAGS
P$RTN
Bits to indicate what the MCB should do. The field is supplied by the calling program.
The bit for this function is
Bit 8 If set, notify the program pointed to by the transaction code in
P$TC1 /P$TC2 whenever any session with the terminal from
P$PID closes or aborts. See 5.11 for a description of the format
of the notification message.
Note: If P$FLAGS bit 8 is used to indicate session close or abort notification, it
overrides any previous notification that can have been set by an outbound open.
The return point. If this field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If the field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
P$TC1/P$TC2
The transaction code to which all further input is directed. A valid transaction code
must be provided. If not, the request is rejected. See also 3.3.5.
5.5.18. Release Exclusive Use of a PID
This function is used by an application program to release a PID from exclusive use. The
packet fields for this function are
P$FUNC
The function code CLRXUSE$$. This field is supplied by the calling program.
P$PID
The PID being released from exclusive use.
P$FAC
The facilities status (see 5.5.1). This field is filled in by the MCB.
P$RTN
The return point. If this field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If the field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
If session close or abort notification was included when exclusive use was set,
releasing exclusive use also clears that notification.
5–36 7833 1568–004

5.5.19. Obtain Input-Only Exclusive Use of a PID
Application Program Interface
This function allows an application program to gain only the input side of exclusive use of
a PID. All future input from the PID is directed to the application program named in
P$TC1 and P$TC2. There are no restrictions or controls on outputs to the PID. Any
program can send output to the PID having input-only exclusive use set, and any program
can release the input-only exclusive use from the PID with the release exclusive use
function (see 5.5.18). The $BREAK II keyin can also be used by an operator to arbitrarily
release exclusive use of a PID (see the MCB Operations Reference Manual).
Exclusive use and input-only exclusive use cannot be in effect simultaneously. Only one
exclusive use can be set on a PID at any time. This function can be used repeatedly to
change the transaction code to which input is directed without clearing the current
exclusive use.
If the MCB configuration has the RESILIENT SGS set to YES, MCB retains exclusive use
and close notification information for the PID over a failure of the MCB or CMS (see
5.5.17).
The packet fields for this function are
P$FUNC
The function code SETIXUSE$$. This field is supplied to the calling program.
P$PID
The PID over which input-only exclusive control is desired. This field is supplied by
the calling program.
P$FAC
The facilities status (see 5.5.1). This field is filled in by the MCB.
P$FLAGS
P$RTN
Bits to indicate what the MCB should do. The field is supplied by the calling program.
The following bit has meaning for this function:
Bit 8 If set, notify the program pointed to by the transaction code in
P$TC1/P$TC2 whenever any session with the terminal from P$PID
closes or aborts (see 5.11).
The return point. If this field is zero, control is returned to the calling program
following the LBJ that entered the MCB. If the field is nonzero, control is returned to
the specified address in the bank from which the MCB was called, and P$RTN is set
to the address following the LBJ that entered the MCB.
If session close or abort notification was included when exclusive use was set,
releasing exclusive use also clears that notification.
7833 1568–004 5–37

Application Program Interface
P$TC1/P$TC2
The transaction code to which all further input is directed. A valid transaction code
must be provided. If not, the request is rejected. See also 3.3.5.
5.5.20. Obtain MCB Statistics
The Statistics function allows an application program to retrieve MCB statistics for buffer
control, file control, and statistics table information. The information is returned in a
variable format based on the number of core banks configured in the MCB.
The packet fields are
P$FUNC
The function code STAT$$. This function is supplied by the calling program.
P$LENGTH
The number of words of text returned to the calling program. If this value is smaller
than the statistics area, only the first P$LENGTH words are returned. This field is
supplied by the calling program.
P$BUFF
The data buffer address. This data area is assumed to be in the main D-bank window
(BDR2) and is supplied by the calling program.
total number of slots lowest number of slots available
test and set cell
unused number slots available
The remainder of the P$BUFF area, for an MCB with two core banks and two
message retention files, follows. Different MCB configurations result in a different
number of replicated 6-word and 7-word controls.
03 number of core banks
04 core bank 0 MAD controls (6 words)
012 core bank 1 MAD controls (6 words)
020 core bank 0 free MRL controls (6 words)
026 core bank 1 free MRL controls (6 words)
034 core bank 0 active MRL controls (6 words)
042 core bank 1 active MRL controls (6 words)
050 core bank 0 free core buffer controls (6 words)
056 core bank 1 free core buffer controls (6 words)
064 core bank 0 active core buffer controls (6 words)
5–38 7833 1568–004

070 core bank 1 active core buffer controls (6 words)
076 core bank 0 PRP controls (6 words)
0104 core bank 1 PRP controls (6 words
Application Program Interface
0112 number of PIX files number of MRF files
0113 MRF 1 information (7 words)
0122 MRF 0 information (7 words)
0131 statistics information
See Appendix F for the format of MAD, MRL, core buffer, and PRP controls. The
format of the MRF controls for recoverable messages is
Word 0,,W Relative MRF number for this entry.
Word 1,,H1 Segment currently allocated for input (SC$AI).
Word 1,,H2 Segment currently allocated for output (SC$AO).
Word 2,,H1 Sector address of the MRF in MRF$CNTRL (SC$SEC).
Word 2,,H2 Number of segments in this MRF.
Word 3,,H1 TIP/ Network Database Server file number assigned to this MRF.
Word 3,,H2 TIP/ Network Database Server file number of associated PIX file.
Word 4,,W Number of free segments.
Word 5,,T1 Number of blocks in the active input segment that have been
freed.
Word 5,,S3 Segment cycle number for the active input segment.
Word 5,,H2 Segment number, block number of the most recently assigned
block in the active input segment.
Word 6,,T1 Number of blocks in the active output segment that have been
freed.
Word 6,,S3 Segment cycle number for the active output segment.
Word 6,,H2 Segment number, block number of the most recently assigned
block in the active output segment.
The format of the MRF controls for MRF-0 differs from the format for all other MRFs. For
MRF-0 the format is
Word 0,,W Relative MRF file number for this entry (zero).
Word 1,,H1 Latest MRF identifier (MID) allocated (SC$LMID).
Word 1,,H2 Number of active blocks of MIDs (SC$NABLK).
Word2,,H1 Reserved (SC$SEC).
Word2,,H2 Number of segments configured for this MRF (SC$NSG).
7833 1568–004 5–39

Application Program Interface
P$ML
Word 3,,H1 TIP/ Network Database Server file number assigned to this MRF file
(SC$MFN).
Word 3,,H2 Number of MID bit map words in the MF$CTL (SC$BMW).
Word 4 Total number of blocks configured for this MRF, calculated from
SC$NSG and NB$MRFBK.
Words 5 and 6 Reserved
The number of words transferred to P$BUFF. This field is returned by MCB. The user
of this function is responsible for dealing with internal changes to the MCB when
those changes can change data, or change the format in which the data is returned
by this function.
Set P$OFF and P$START to binary zero. These fields are not used by the statistics
function. See the value of the label STATS$$LEN in the element MC$TABLE (from
the MCB build) for the actual statistics area length for your MCB.
5.6. Auxiliary Information Area
The auxiliary information area for input and output messages begins at word 16 (020) of
the interface packet unless the packet version, P$VER, is 3. Then it begins at word 18
(022). The format is defined in 4.6.
The auxiliary information area for pass-off and checkpoint messages is transparent to the
MCB.
5.7. Unique Identifier
Every message (except a ROPL message) has a unique, two-word internal identifier. This
is true of both recoverable and nonrecoverable messages, and of externally and internally
numbered messages in the communications network.
Every program step also has a unique, two-word internal identifier. This is true whether
or not a program step has been initialized to process a message. If a program step has
been initialized to process a message, the program step identifier is the message
identifier of the processed message.
The MCB, Universal Database Control, Exec, and IRU use the unique identifier internally
to identify, control, and record interrelated processing activity. For example, the unique
identifier of a program step is used on the audit trail as the originator of an Network
Database Server database after-look record.
5–40 7833 1568–004

Application Program Interface
The unique identifier is available on certain MCB functions as packet fields
P$STEP1/P$STEP2 and P$0S1/P$0S2. Figure 5–4 shows the format.
data and time
sequence number step number
The packet fields are defined as follows:
date and time
Figure 5–4. Unique Identifier
Bits 35-30 Year, relative to 1964. For example, 24 is 1988.
29-24 Month, 1 to 12.
23-18 Day, 1 to 31
17-0 Time in seconds since midnight.
sequence number
Bits 35-12 A sequence number increased by one each time a new unique identifier
is formed. This number gives uniqueness to two or more unique
identifiers created within the same second. The number is also used to
formulate a generated run-id for the transaction program that processes
the transaction message identified by this unique identifier.
step number
Bits 11-0 Step advance number. This begins at zero and is increased by one each
time the program step performs a step advance.
5.8. Recovery Options Summary
The 18-bit recovery options for a message are derived from three information sources:
• P$RECOPT in the packet of the calling program
• Target VINDEX entry
• Default options in effect for the calling program step as recorded by the MCB in its
table of information (SLOT) for the initialized program activity
P$RECOPT is available as an override to automatic determination from the other two
sources when the calling program specifies P$FLAGS bit 5 on an output, pass-off, or
checkpoint function.
The target VINDEX entry is applicable to input and pass-off messages.
The default options in effect for an active program step are derived from:
• The recovery options field of the input, pass-off or checkpoint message retrieved by
the program activity on its initialize function.
• The P$RECOPT field in the Initialize function as supplied by the program when a
program step is created without retrieving a message
7833 1568–004 5–41

Application Program Interface
Figure 5–5 through Figure 5–8 summarize derivation of the recovery options for each of
the four message types: input, output, pass-off, and checkpoint. Note that the resulting
18-bit recovery options field has three 6-bit subfields for output, input, and program
options, respectively (see 3.3.3).
Target VINDEX
Out In Prog
Out In Prog
Figure 5–5. Input Recovery Options
Caller's SLOT
Out In Prog
Caller's Packet
Out In Prog
Out 0 0
Figure 5–6. Output Recovery Options
5–42 7833 1568–004

Caller's SLOT
Out In Prog
Caller's Packet
Out In Prog
Out In Prog
Figure 5–7. Pass-Off Recovery Options
Caller's SLOT
Out In Prog
Application Program Interface
Caller's Packet
Target VINDEX
Out In Prog
Out In Prog
Figure 5–8. Checkpoint Recovery Options
Out In Prog
7833 1568–004 5–43

Application Program Interface
5.9. Unintelligent Message Numbering Format
The numbering format for input acknowledge messages and output message headers
used with unintelligent PIDs is described next.
5.9.1. Input Acknowledge Message
An input acknowledge message is created by the MCB and returned to a terminal after
staging a numbered, recoverable input message received from an unintelligent PID (see
3.2.3.3). Example 5–1 shows the format of this message.
������������� ��� �������� �������� ������� ������ ���
��� ������� ���� ���� �������� ��� ��
����� ������ ������
��������
����
������������� � � ����������
Example 5–1. Input Acknowledge Message
The fields in this message are defined as follows:
PID
Numeric PID of the originating terminal.
Message number
Input message number.
R
If present, indicates that this message is recallable.
Date
Unique identifier of the input message (see 5.7).
Time
Unique identifier of the input message (see 5.7).
Sequence number
Unique identifier of the input message (see 5.7).
Run ID
Generated run-id of the transaction program that processes the message. This field
is not applicable if the transaction message is processed by a batch or demand
program.
5–44 7833 1568–004

Mode
Execution mode of this transaction:
Blank = Normal
TR = Training
TS = Test
TT = Test/Training
5.9.2. Output Message Header
Application Program Interface
An output message header is appended by the MCB to a numbered, recoverable output
message directed to an unintelligent PID (see 3.2.3.3). Example 5–2 shows the header
format.
���������������������� ��� � �������� �������� ������� ������ ���
�
�������� ��� ������� ���� ���� �������� ��� �� �� ���� ��
��� ������ ������ ����������
�����������
� � ��������� ��������� �����������
� � ���������� �������
� � ����������������� ����������������
Example 5–2. Output Message Header
These header fields are defined as follows.
Original PID
If present, the message was originally destined for the terminal identified by this
numeric PID, but the message is now being alternately routed.
PID
Numeric PID of the receiving terminal.
Message number
*
R
M
Output message number.
If present, indicates that the message can be a duplicate.
If present, indicates that this message is recallable.
If present, indicates that this message was sent to multiple destinations.
7833 1568–004 5–45

Application Program Interface
Date, Time, Sequence number
Unique identifier of the output message (see 5.7). Date and time values will be zero
for multiple destination list and group PID messages.
Run-id of originator
Generated run-id of the program that created this message.
Mode of originator
Execution mode of the program that created this message:
Blank = Normal
TR = Training
TS = Test
TT = Test/Training
The application program is responsible for leaving space within the text of the output
message for the header (if a header is desired). Refer to 4.6 for a discussion of P$HDR,
P$HDRSIZE, and P$END.
5.10. Delivery Notification Format
You can request delivery notification on an output request by setting P$FLAGS option
bit 4 (see 3.5.5 and 5.5.8).
The delivery notification message is a nonrecoverable pass-off message with no auxiliary
information area. The text of the delivery notification message is identical in format to
that for the error notification program described in 8.3. The error type and error code
information in word 0 of the text is zero if the message is successfully delivered. If the
message is not delivered, the error notification program is scheduled instead of the
delivery notification program.
If the MCB is running within an application group configured to use TIP message
security, input to the delivery notification program is created at the system-high level.
See the Exec Installation and Configuration Guide for information about configuration
parameters that control TIP message security. See the Security Administration for
ClearPath OS 2200 Help for a description of system-high attributes. Delivery notification
input is created at system-high because user text is included in the message.
The application program, and the TIP or demand session under which it runs, must be
able to accept messages at the system-high level. A batch-connect type of program is
recommended for reading delivery notification inputs. The session used by the program
can be given the proper security privileges through the user-id. If the delivery notification
program is not privileged to read a message at system-high, access is denied and the
input message is discarded.
5–46 7833 1568–004

5.11. Session State Changes
Application Program Interface
Session state changes for sessions opened with the OPNSSN$$ function create a
pass-off message to the program specified when the session was opened. Notification
of session close or session abort is also provided for PIDs in exclusive use if specified
when exclusive use is established. (See 5.5.14 and 5.5.17 for more information). These
messages use P$PID to identify the session. The P$FNC field in the auxiliary data area
has a value equal to the CMS value in P$FUNC. The auxiliary data area field called
P$SESSION contains the value passed by CMS in P$QID.
Twenty characters of text represent the first five words of the MCB packet used that
creates the notification message.
If the MCB is running within an application group configured to use TIP message
security, input to the session notification program is created at the system-low level. See
the Exec Installation and Configuration Guide for information about configuration
parameters that control TIP message security. See the Security Administration for
ClearPath OS 2200 Help for a description of system low attributes. Session state change
input is created at system low because no user text is included in the message.
System-low inputs can be read by any program, regardless of session attributes.
5.12. Host-to-Host MCB Transactions
The host-to-host feature sends an output from an MCB transaction program on one
OS 2200 system (host 1) and schedules it as a transaction input on another OS 2200
system (host 2). Communication is handled between two copies of CMS, one on each
host. Each CMS must have at least one PID configured as a host-to-host PID. See the
CMS 1100 Installation and Configuration Guide for information on the PID network
definition statement (NDS) used in host-to-host feature configuration.
The host-to-host feature also returns negative acknowledgment (NAK) reason codes from
either host to the system error program (SEP) or the error notification program (ENP).
5.12.1. Host-to-Host Restrictions
The following restrictions apply to the host-to-host feature:
• MCB action command output cannot be sent to a host-to-host PID.
• For output messages, the auxiliary area of the MCB application interface packet is
used only to return NAK reason codes.
• For input messages, the auxiliary area of the MCB application interface packet is
used only to specify the host-to-host type with the type fields P$TTYP and P$RTYP.
The type fields identify the message source as a PID on another host.
• The host-to-host feature supports only the MCB packet interface.
• A session cannot be opened to or from a CMS application configured with the
RESILIENT parameter on the APPLICATION NDS, or through a CMS application that
is using the TIP session control feature.
• Conversational link is not supported on host-to-host PIDs.
7833 1568–004 5–47

Application Program Interface
5.12.2. End-to-End Message Acknowledgment
The host-to-host feature supports two variations of end-to-end message
acknowledgment between hosts:
• If an output message is sent to a PID that is not configured for intelligent message
numbering, MCB receives message acknowledgment from CMS when the output is
transmitted to the communications peer. An application program can receive this
message acknowledgment if the program specifies delivery notification when it
issues the store output (SEND$$) function call to MCB.
• If the receiving PID is configured for intelligent message numbering, or if the
AU-LABEL parameter is specified in the CMS configuration for that PID, MCB
receives message acknowledgment (CMSACK$$) from CMS after CMS receives an
AU-CONFIRM from the communications peer. MCB receives negative
acknowledgment (CMSNAK$$) if CMS receives an AU-FAIL from the
communications peer. An application program can receive this message
acknowledgment if the program specifies delivery notification when it issues the
store output (SEND$$) function call to MCB.
5.12.3. Opening a Host-to-Host PID Session
An application program opens a session between itself and a host-to-host PID through
the MCB outbound open procedure. The outbound open to a host-to-host PID is identical
to an outbound open to any other PID.
When an outbound open to an host-to-host PID is performed, an MCB inbound open is
performed on the receiving host to establish a session between the host-to-host PID and
CMS. The host-to-host PID is identified to the receiving host in its CMS configuration (by
the FROM-USER parameter of the REMOTE-EU NDS). See the CMS 1100 Installation
and Configuration Guide for information on the REMOTE-EU and PID NDSs.
For example, in a host-to-host session between a sending transaction on host 1 and a
receiving transaction on host 2:
• The host-to-host PID used for the session is logically treated by CMS on each host as
a PID configured as a REMOTE-EU. Each CMS establishes a host-to-host session
only through the host-to-host PIDs defined in its own configuration.
• A Session Open function initiated by the transaction program on host 1 to host 2 is
treated by the host 1 CMS application as an MCB outbound open to the host-to-host
PID.
• This communication is treated by the host 2 CMS application as an MCB inbound
open from the PID.
• Two-way communication can be established through a single host-to-host PID
configured in CMS on both hosts. Alternatively, a different host-to-host PID can be
configured on each host to handle one-way communication only.
5–48 7833 1568–004

5.12.4. Store Output (SEND$$) Considerations
Application Program Interface
When the application program issues a store output (SEND$$) to send output to a
transaction on another host, the following requirements must be met:
• The value of the P$PID field must be a host-to-host PID defined in the CMS
configuration of the sending host.
• The first six characters of output message text must be a valid transaction code
configured in the VALTABs of the receiving host. An invalid transaction code causes
a TIP scheduling error on the receiving host and the error notification program is
scheduled on the receiving host.
• The fields P$TC1 and P$TC2 are used only if delivery notification is specified (bit 4 is
set in the P$FLAGS field). MCB ignores the P$TC1 and P$TC2 fields for any other
condition. The conversational link feature cannot be used with the host-to-host
feature.
• The application program must specify at least four words of auxiliary area when it
issues a SEND$$ function for a recoverable message. If this condition is not met, the
auxiliary area will not be large enough to pass NAK reason codes to the system error
program.
5.12.5. SEP and ENP Considerations
The following modifications should be made to the SEP and ENP programs to support
the return of NAK reason codes in host-to-host transactions:
• When the SEP or ENP is initialized, a value of at least four must be placed in the
P$AUX and P$END fields of the application interface packet. This defines an auxiliary
area large enough to pass the NAK reason codes.
• The SEP or ENP should be modified to include the NAK reason code (located in the
P$SESSION field) in error information that is printed or displayed.
• The SEP or ENP should be modified so that error messages destined for PIDs (not
print devices) cannot be sent to host-to-host PIDs. If this modification is not
performed, extra and unwanted traffic occurs between host systems.
5.13. HVSTAT Considerations
The OS 2200 TIP system contains a transaction performance monitoring capability called
HVSTAT. (See the Transaction Processing Administration and Operations Reference
Manual for more information.) HVSTAT provides the capability for a user transaction to
log 4 words of transaction-unique information in the standard HVSTAT record. The
transaction passes this data to the operating system by setting specific registers before
doing an ER EXIT$ at the end of a transaction. (See the Transaction Processing
Administration and Operations Reference Manual for more information.)
Transactions that perform multiple TRINIT$$ functions to process multiple messages do
not execute an ER EXIT$ after each message. As a result, this information cannot be
logged by that method.
7833 1568–004 5–49

Application Program Interface
Transactions that perform multiple TRINIT$$ functions can log HVSTAT user buffers.
These transactions must pass the 4-word buffer to the MCB when performing a
subsequent TRINIT$$ call to retrieve another message. During the TRINIT$$ call, the
MCB establishes the appropriate registers for the operating system to log the HVSTAT
user data. To use this facility, you must add the following information on the TRINIT$$
call:
• Set bit 3 of P$FLAGS.
• Set P$AUX greater than or equal to 5.
• Put the ASCII character string HVST in word 0 of the auxiliary area.
• Put the 4 words to pass to HVSTAT in words 1 through 4 of the auxiliary area.
MCB supports HVSTAT user data only through the packet interface. MCB does not
support the use of HVSTAT user data when you are using the COMPOOL-compatible
primitive interface.
5–50 7833 1568–004

Section 6
TIP Primitive Interface
This section describes the Message Control Bank Transaction Processing (MCB TIP)
primitive interface, which is a migration aid to convert TIP primitives from
communications message-buffer pool (COMPOOL) to MCB use. You can migrate
without modifying your application programs by remapping with the alternate set of MCB
primitives presented here. The MCB primitives invoke and express a functional subset of
the application interface defined in Section 5. The primitives offer a compatible
replacement for the functions available under COMPOOL. The TIP primitive interface is
not supported for extended mode application programs.
An application program must be executing in quarter-word mode (D17 set) when it calls
MCB, or the MCB returns an error. Programs using the TIP primitive interface require the
same addressing environment used with the applications program (packet) interface (see
5.2).
The MCB primitives are available in the TIP library files. See the Transaction Processing
Administration and Operations Reference Manual for more information.
6.1. MCB Primitives
The primitives from the set of TIP ASCII primitives described in 6.1.1 through 6.1.14 are
modified to use the MCB. Not all primitives perform message handling, but all primitives
call the MCB. The interface to each of the primitives is described in the Transaction
Processing Programming Reference Manual. These interfaces remain unchanged. Your
existing application programs run correctly without changes except for conditions
described in 6.4. The MCB and primitives assume the volatile register set (X11, A0 to A5,
R1 to R3) is available for use and need not be saved or restored.
In cases where an error return to the primitive occurs or when the transaction must be
given a contingency, the primitive receives a code, a type, and a contingency from the
MCB. The primitive then issues an ER CQUE$ to pass the contingency to the application
program.
7833 1568–004 6–1

TIP Primitive Interface
6.1.1. INITAL—Transaction Program Initialization
This primitive enters the MCB for MCB activity initialization to do an ER QI$NIT and to
transfer part of the message to an application program data area. Activity initialization
includes an ER TRMRG$ to register activity termination processing for the MCB. If
INITAL or CONECT has not been used first, use of any of the other primitives listed here
results in an error. INITAL can be called more than once to allow processing of more than
one input message by a single transaction program. INITAL can also be used to receive
TIMER inputs.
To call this primitive more than once, you must use the COMMIT primitive or the FREE,
DEPART, or DEPART WITH ROLLBACK DML command between each pair of successive
uses of INITAL. Further, the recovery options in the VALTAB entry must specify step
termination as the default for COMMIT (the Y option must be set). If on a multiple-INITAL
call, a COMMIT was not first issued, the MCB issues a COMMIT with step terminate
before trying to obtain the next input.
6.1.2. TERMN8—Transaction Program Termination
This primitive enters the MCB to deregister the activity from the MCB. The primitive then
does an ER EXIT$. The MCB processing includes ER TRMRG$ to deregister termination
processing, release all partially staged messages, and release main storage resources for
any remaining input messages.
6.1.3. CONECT—Batch/Demand Program Initialization
This primitive enters the MCB to do MCB initialization and to do an ER QI$CON. As with
INITAL, ER TRMRG$ registers activity termination processing. An online batch program
can read some or all of its input messages. An attempt by an offline batch program to
read an input message results in a contingency for the program. One of the parameters
passed to the CONECT primitive is the set of recovery options for the program. This field
includes the options that determine the actions to be taken with the use of COMMIT or
ROLBAK primitives.
6.1.4. DISCON—Batch/Demand Program Termination
This primitive enters the MCB to deregister the activity from the MCB and to do an ER
QI$DIS. An ER TRMRG$ is also done to deregister termination processing. The input
message and partially staged output, pass-off, and checkpoint messages are released.
6–2 7833 1568–004

6.1.5. CSTLOG—Store a Message
TIP Primitive Interface
This primitive enters the MCB to create a new message. As with COMPOOL, an existing
incomplete output or pass-off message is released. The specified data is stored as a new
message. Certain message parameters that affect future processing for the message
must be specified in the message parameter area (MPA)” (see 6.2 on this request).
These parameters are the indicator character, the PID, and the transaction code. As with
COMPOOL, if the message is a pass-off with indicator character 3, and if the Exec
parameter TPSNUM is nonzero, the caller can supply a program number instead of a
transaction code.
6.1.6. CSTOVR—Overlay or Extend a Message
This primitive enters the MCB to replace part of a message or to add to a message. It
does not change an input message into an output or pass-off message. CSTOVR can
change only message text, not the MPA or user parameter area (UPA). Do not use the
characters 003 in the last word of the overlaying segment. These characters are read as
an end-of-text (ETX) character and are stripped off.
6.1.7. CDATAC—Read a Message
This primitive enters the MCB to read part or all of a message. Message release is not
done under any circumstances; further access is prohibited. Part or all of a message can
be read as many times as necessary.
6.1.8. CDATCR—Read and Release a Message
This primitive enters the MCB to read part or all of a message as for CDATAC. If the last
word of the message is read and the message is not recoverable the message is
released and is no longer accessible by the program. If the message is recoverable, it is
not released until the end of the step.
6.1.9. CRELOG—Release All Messages
This primitive enters the MCB to release a partially staged output or pass-off message.
This primitive releases the input message if the message is not recoverable. If the input
message is recoverable, it is not released until the end of the step.
6.1.10. RTRANO/RTRANU—Store and Queue a Message
This primitive enters the MCB to store a message, as does the CSTLOG primitive. In
addition, the MCB queues the message for output or pass-off, according to the indicator
character. As with the COMPOOL version of RTRANO/RTRANU, if the word count is
zero, the primitive assumes a message already exists and does the queuing operation
only. Once a message has been queued, the program is denied further access to it. As
with COMPOOL, if the message is a pass-off with indicator character 3, and if the Exec
parameter TPSNUM is nonzero, the caller can supply a program number instead of a
transaction code.
7833 1568–004 6–3

TIP Primitive Interface
6.1.11. RTOUTP/RTSCHD—Queue an Output or Pass-off
Message
This primitive enters the MCB to queue a message. The message must have been
stored with the CSTLOG primitive. Parameters passed on the RTOUTP or RTSCHD call
are ignored; parameters previously passed in the MPA are used instead.
6.1.12. ERTERM—Program Error Termination
This primitive enters the MCB to do an ER TRMRG$ and to remove the switch list (SWL)
address from the activity. The primitive then does an ER ERR$. The MCB processing is
identical to the process invoked by TERMN8 or DISCON.
6.1.13. ROLBAK—Program Step Rollback
This primitive enters the MCB to do message cleanup and perform an ER RL$BAK. The
caller has the option to retain the step’s input message, or to release and requeue the
input message. Any partially staged messages are released. The choice of action is
determined by the recovery options specified in the program’s VINDEX or the options
passed to the CONECT primitive.
6.1.14. COMMIT—Program End of Step
This primitive enters the MCB to release any partially staged messages and to do ER
CO$MIT. Following the ER, the MCB either clears the step-id (if the step terminated) or
updates the activities step-id (if the step advanced). The choice of action is determined
by the recovery options specified in the program’s VINDEX or passed to the CONECT
primitive.
6.2. Message Parameter Area
The message parameter area (MPA) is described in detail in the Transaction Processing
Programming Reference Manual. For MCB, the following changes to that format are
necessary:
• Any fields marked zero, not used, or reserved system usage are disregarded. These
fields are neither used by the MCB nor carried along with the message.
• Word 4,T1; word 4,T2; and word 9,H1 are disregarded.
• For output messages, the input PID (word 2,H1) is disregarded.
Although the MPA is the vehicle for passing parameters between transaction programs
and the MCB, the CMS interface does not use the MPA. The relevant fields are
contained in the CMS MCB packet instead.
6–4 7833 1568–004

6.3. User Parameter Area
TIP Primitive Interface
In the primitive interface, a user parameter area (UPA) can be appended to the MPA
immediately preceding the message text. Within the MCB, the UPA is passed as part of
the auxiliary information area. A program using the MCB primitive interface has the same
access to the UPA as it does when using COMPOOL. The CSTOVR primitive is an
exception; it cannot be used to rewrite the UPA. The UPA can not exceed 59 words.
6.4. Application Program Impacts and
Incompatibilities
The following subsections explain application program impacts and incompatibilities.
6.4.1. Relative Addressing
The data passed to or from the MCB in a primitive request must reside in the main
D-bank window. Furthermore, the relative addressing range of the main D-bank must not
overlap the MCB main I-bank and utility D-banks. See 5.2 for a more complete
description of the required addressing conventions.
6.4.2. Overlay
CSTOVR cannot be used to alter MPA or UPA data after the original CSTLOG primitive
request. CSTOVR cannot transform an input message into an output or pass-off
message. Do not use the characters 003 in the last word of the overlaying segment.
These characters are read as an end-of-text (ETX) character and are stripped off.
6.4.3. Physical COMPOOL
The physical COMPOOL primitives, CASGBL, CSTPHS, CRDPHS, and CRELBL are not
supported by the MCB. You cannot use these primitives.
6.4.4. Program Options
The R and V execution options are disregarded by the MCB.
6.4.5. Initialization
For the primitive interface, the INITAL or CONECT primitive must be the first primitive
used by an application program. In current systems, COMPOOL primitives can be used
without using INITAL or CONECT first. The MCB introduces the requirement to initialize
(impart) with the MCB before other functions can be used.
7833 1568–004 6–5

TIP Primitive Interface
6.4.6. Termination Differences between COMPOOL and MCB
A transaction program must use the TERMN8 primitive to terminate normally. This is not
a requirement under COMPOOL.
A batch/demand or online batch program must use the DISCON primitive to terminate its
connection with the MCB prior to normal program termination. This is not a requirement
under COMPOOL.
An online batch program releases its input message upon execution of DISCON. This
does not occur under COMPOOL.
6.4.7. Running COMPOOL and MCB Programs Concurrently
Messages stored with the MCB cannot be read or accessed by programs that use
COMPOOL primitives. The converse is also true. For example, a program using the MCB
primitives cannot use an RTRANO/RTRANU to perform a pass-off to a program that uses
COMPOOL primitives. The converse is also true.
Therefore, when migrating to MCB, or when COMPOOL and MCB programs are running
in the same environment, keep the programs separate.
6–6 7833 1568–004

Section 7
Universal Database Control
Considerations
7.1. Universal Database Control Interface
Note: If auditing is not turned on in the Exec, there is no interface between Universal
Database Control and MCB. Hence, this section only applies if auditing is on.
Universal Database Control (formerly UDS ) notifies the Message Control Bank (MCB)
whenever an end-of-step is reached. This informs the MCB of the correct step-id for
each initialized program to release messages at the proper time.
Universal Database Control enters the MCB by
����� ������� ���
��� ������� ����� �����
where:
A0 = Function code
R1 = Application group name
R3 = BDI and entry point for return to Universal Database Control
A4,A5 = Step-id returned by an ER DMES$ or ER DMRB$
The MCB returns to the specified bank and entry point with
A1 = 6
X1 - X10 preserved
X11, A0, A2 through A5 and R1 through R3 destroyed
All other registers unchanged
7.2. Universal Database Control Run-Unit
Conventions
A program that interfaces with the MCB for message processing and concurrently
interfaces to Universal Database Control as a run-unit for database processing must
observe the rules and conventions described in 7.2.1 through 7.2.7.
7833 1568–004 7–1

Universal Database Control Considerations
7.2.1. MCB Initialize
The MCB Initialize function (or INITAL primitive) may precede the IMPART command.
The MCB Initialize function (or INITAL primitive) can be executed after the IMPART
command only if it is issued before the first data manipulation language (DML) command
after the IMPART or FREE commands, except for the OPEN command. Any such DML
command identifies the start of a program step to Universal Database Control. For a
discussion of multiple INITAL commands within an IMPART/DEPART sequence, see the
Integrated Recovery Conceptual Overview.
7.2.2. MCB Terminate
You cannot use the MCB Terminate function (or TERMN8 primitive) before the DEPART
or DEPART WITH ROLLBACK commands.
7.2.3. MCB Commit
You cannot use the MCB Commit function (or COMMIT primitive). A FREE or DEPART
command signifies an end-of-step.
7.2.4. MCB Rollback
You cannot use the MCB Rollback function (or ROLBAK primitive). A DEPART WITH
ROLLBACK command signifies rollback.
7.2.5. Message Release
You can use optional DML syntax on the FREE, DEPART, and DEPART WITH ROLLBACK
commands to specify disposition of the input message retrieved on the MCB initialize
request (or INITAL primitive).
On the FREE and DEPART commands, the options are
• Retain the message (step advance).
• Release the message (step terminate).
On the DEPART WITH ROLLBACK command, the options are
• Retain the message and resume the program step.
• Requeue the message, if recoverable, or release the message, if nonrecoverable.
• Queue the message to the system error program, if recoverable, or release the
message, if nonrecoverable.
The latter two options imply that the program step terminates.
If you do not use the optional DML syntax, input message processing defaults to that
specified in the program recovery options for the calling program step.
7–2 7833 1568–004

Universal Database Control Considerations
Fully staged and deferred output, pass-off, or checkpoint messages are handled in one of
these ways:
• Delivered as part of FREE or DEPART processing.
• Discarded as part of DEPART with ROLLBACK processing.
• Discarded, if partially staged, as part of a FREE or DEPART command.
7.2.6. Retrieval Run-Units
If a run-unit opens a recoverable database area for an update, the program must have
specified the recoverable step option (see 3.3.3). If a run-unit wishes to open database
areas for retrieval only, the program may or may not have specified the recoverable step
option depending on its MCB and message processing related attributes. Even for a
retrieval only run-unit, the FREE, DEPART, and DEPART WITH ROLLBACK commands
denote end-of-step or rollback.
7.2.7. LOG Command
You can use the DML LOG command to write records from your application program to
the audit trail. As an alternative, you can also use the MCB Audit function. If you use the
DML LOG command, the audit record is tagged with the unique identifier of the program
step only if the MCB Initialize function (or INITAL primitive) has already occurred.
Note: Not all database products use the DML syntax, IMPART, DEPART, and FREE, for
a step creation and step termination.
7833 1568–004 7–3

Universal Database Control Considerations
7–4 7833 1568–004

Section 8
Error Processing Programs
8.1. Overview
Any installation that uses the MCB must supply these two error processing programs:
• System error program (SEP)
• Error notification program (ENP)
The two programs would normally be transaction programs. As an alternative, the
messages directed to these two processing points could be dequeued and processed by
a batch or demand program. In either case, the corresponding VINDEX entries must be
configured with the VTBUTL utility (see 3.3).
The purpose of the two programs is to allow application-dependent error processing to
be solicited in certain conditions in which it is not desirable for automatic, standard
system action to occur. These programs represent an extension to such concepts as a
contingency routine or ROLBAK paragraph.
If the MCB is running in an application that has TIP message security configured, inputs
to the ENP and the system error program SEP are created at many different security
levels, ranging from system low to system high. See the Exec Installation and
Configuration Guide for information about configuration parameters that control TIP
message security. Refer to the Security Administration for ClearPath OS 2200 Help for
information about the attributes of system-low and system-high security.
The ENP and the SEP must be able to read input messages at system high. Use a
batch-connect type of program to read these inputs. The sessions used by the ENP and
SEP can then be given the proper security privileges through the user-id. If the ENP or
SEP programs do not have the privilege to read a message at system high, access is
denied and the input message is discarded.
Examples of the ENP and SEP programs are in the GN file. The file names are
�������������� and ��������������. The packet definitions are in file ��������������.
8.2. System Error Program (SEP)
The SEP is intended to be the repository of any recoverable input, pass-off, or checkpoint
message that cannot be processed and any recoverable output message that cannot be
delivered.
7833 1568–004 8–1

Error Processing Programs
8.2.1. Purpose
A recoverable input, pass-off, or checkpoint message is queued to the system error
program in the following situations:
• TIP scheduling error.
• Rollback and requeuing has occurred the maximum number of times allowed by the
Exec.
• Rollback occurred due to program contingency errors, and recovery option W is set.
• System configured requeuing will not occur. The system error program is scheduled
with all information necessary to optionally schedule the program that erred.
• Queuing to the system error program has been explicitly requested with an MCB
rollback function or Network Database Server DEPART WITH ROLLBACK command.
A recoverable output message is queued to the system error program in the following
situation:
• CMS output message negative acknowledge function has been issued because the
output message cannot be delivered.
8.2.2. System Generation Considerations
The following stream generation statement (SGS) statement must be included in the
system generation of the Exec:
����������� � ����� ������� �� � �������� �� �
where:
n
x
p
Application group number.
Transaction program VALTAB number of the system error program.
Queue priority in the input queue tree structure for enqueuing messages to the
system error program.
See the Exec Installation and Configuration Guide. Reserve the specified queue priority
exclusively for messages queued to the system error program. If error conditions arise
regarding the scheduling or execution of the system error program itself, the Exec
discontinues scheduling of the system error program by setting the maximum
concurrency to zero on the associated queue priority.
8–2 7833 1568–004

8.2.3. VINDEX Considerations
Error Processing Programs
Table 8–1 lists the parameters for the associated VINDEX entry for the system error
program that must be included with the VTBUTL utility program.
Table 8–1. VINDEX Parameters for System Error Program
VINDEX Parameter Specification
Applications group number Same as n in 8.2.2. Must match the APNUMBER n parameter in
the MCB configuration.
Transaction program number Same as x in 8.2.2.
Input queue priority Same as p in 8.2.2.
Access mask Zero. Irrelevant.
Recovery options Zero. Any message that is redirected to the system error
program already has its recovery options established.
Transaction code Any desired transaction code can be used. If the terminal user
explicitly enters this transaction code or if an application program
issues a pass-off to this transaction code, then meaningful values
should be supplied for the access mask and recovery options.
8.2.4. MCB Interface
The system error program should use the application program interface described in
Section 5. On the MCB initialize function, give special attention to these message
parameters:
P$ERR
This field identifies the reason for directing the message to the system error
program. The value 070 indicates that a program with the W recovery option erred.
(See P$OUTQ.) The value 073 indicates CMS negatively acknowledged an output
message. (See P$SESSION.) Other values are possible. See the list of type 035
errors in the Transaction Processing Programming Reference Manual.
Note: P$ERR has a value of 070 only when a program contingency occurs that
causes scheduling of the system error program, and recovery option W is set.
P$TYPE
This field identifies the message type. The system error program represents the only
instance in which an output message can be retrieved by an application program on
the initialize function.
P$SESSION
This field identifies the NAK reason code (see 4.5.8). At least four words of auxiliary
area must have been specified with the output message to receive the NAK reason
code (see 4.6). When MCB is operated with CMS level 5R1 or higher, CMS returns
NAK reason codes to the MCB when output messages are negatively acknowledged.
7833 1568–004 8–3

Error Processing Programs
P$TC1/P$TC2
P$MN
This field contains the transaction code of the erring program, if it starts a step by
reading an input, pass-off, or checkpoint message. If the erring program starts a step
without reading a message, P$TC1/P$TC2 will contain ASCII space (040) characters.
This field contains the message number associated with the input, pass-off, or
checkpoint message retrieved by the erring program.
P$RECOPT
This field contains the recovery options of the erring program.
P$MODE
P$PID
This field contains the execution mode of the erring program.
This field contains the originating terminal-id, if the erring program is scheduled by a
network input.
P$OUTQ
If P$ERR has a value of 070, this field contains the contingency information for the
erring program: error type, error code, and contingency type. See the ER
Programming Reference Manual.
The system error program can interrogate the message parameters, read the message
text, and take the appropriate action in the context of the user application. All MCB
interface functions are available to the system error program. If the input, pass-off, or
checkpoint message is queued to the SEP due to a contingency error, and the W option
is set, the SEP can reschedule the erring program using all of the message parameters
just listed.
8.3. Error Notification Program (ENP)
The ENP allows the MCB to notify the application system of these situations:
• A nonrecoverable input or pass-off message has been discarded because of a TIP
scheduling error or because the target transaction program terminated without
retrieving the message with an MCB Initialize (or INITAL) request.
• A nonrecoverable output message was discarded because it was undeliverable by
CMS.
• An input message was ejected and discarded by the MCB during the CMS input
message staging for reasons such as an invalid transaction code.
• A transaction program has terminated in error.
• An attempt to queue a recoverable or nonrecoverable input message was rejected by
step control. The program terminated without detaching from MCB with the TERM$$
call or the TERMN8 primitive.
8–4 7833 1568–004

Error Processing Programs
• The ENP can close any session, using the CLSSN$$ function, that was opened with
MCB. In addition, the ENP can send output messages to the PIDs in exclusive use,
as well as override exclusive use.
• The VALTAB for the ENP is required for Automatic Recovery of Components (ARC)
to function for MCB. The specific product that heartbeats with MCB is APPREC, and
APPREC requires the ENP transaction code to be registered.
8.3.1. VINDEX Considerations
You must include the parameters listed in Table 8–2 for the associated VINDEX entry for
the error notification program with the VTBUTL utility program.
Table 8–2. VINDEX Parameters for Error Notification Program
VINDEX Parameter Specification
Applications group number Must match the APNUMBER n in the system
Transaction program number As needed.
Input queue priority As needed.
Access mask Zero, irrelevant. As needed.
Program recovery options As needed.
Output recovery options As needed.
generation of the MCB.
Input recovery options Zero. The message that is passed to the error
notification program is a nonrecoverable pass-off,
internally generated within the MCB.
Transaction code Must match the ENP$TXN name in the system
configuration of the MCB.
8.3.2. Message Format
The error notification program is scheduled for execution with a pass-off message
generated within the MCB. The text of this message contains these categories of
information:
• Identification of the error condition
• Parameters relevant to the discarded message
• Auxiliary information area of the discarded message
• The first n characters of text of the discarded message
The message is a nonrecoverable pass-off with a total length P$ML that is no greater
than 448 quarter words. The message has no auxiliary information area; P$AUX = 0.
Figure 8–1 shows the format.
7833 1568–004 8–5

Error Processing Programs
In the case of error type 4, this message provides information about the program that
terminated, rather than information about the input message held by the terminated
program. The program may have been holding a recoverable or nonrecoverable input
message (or none at all) at the time of error termination.
0 error status information
1-16
message parameters
17 auxiliary information
17+i
Word 0
8–6 7833 1568–004
text
Figure 8–1. Error Notification Message
One word of error status information in the following format (the error type and code
are defined in Table 8–3):
0
Error
Types
Error
Code
reserved error type error code
Table 8–3. Error Notification Codes
Explanation
0 X Nonrecoverable input or pass-off discarded by TIP. The error code X
identifies the reason and is defined in the Transaction Processing
Programming Reference Manual as the error code applicable to type
035 TIP errors.
1 X Nonrecoverable output message discarded by CMS. The NAK
reason code is returned in the error code field. See 4.5.8 for
possible reasons for the NAK.
2 X An input message has been rejected for a reason such as invalid
transaction code. The error code X identifies the reason and is
defined in Appendix B.
3 X An input message has been rejected for a reason defined by tailored
message analysis (TMA). The error code x is defined by the user.

Error
Types
Error
Code
Table 8–3. Error Notification Codes
Error Processing Programs
Explanation
4 X A transaction program has terminated in error. The contingency
word from TL$END in the SLOP table is passed in the 17th word,
and the program name passed in the 18th and 19th word in the
packet. The abort mask from the PCT (EN field in the PCT) is also
passed in the second half of the 19th word.
When TRMXVT is set greater than 8190, the TIP FLAGBOX
SCHEDULE bit must be ON when the MCB background run is
started. This enables MCB to schedule the ENP for error type 4.
6 X An attempt to schedule a transaction with ER TIP$Q failed and the
resulting error code x was returned. See the Exec Administration
Reference Manual for a description of ER TIP$Q error codes.
Words 1 through 16
These 16 words contain message parameters in the format of the Application
Program Interface packet defined in 5.2 and Figure 5–1. The parameters apply to the
discarded message. For error type 4, these words make up the packet used
internally by MCB to generate the pass-off message to the error notification program
(ENP).
Words 17 through 17 + i - 1
These i words contain the auxiliary information area (if any) that applied to the
discarded message. The value of i is given by the field P$AUX in the parameters
within words 1 to 16.
For error type 4 only, the following words (17, 18, 19) are returned in the auxiliary
information area:
17 + i
For error types other than 4, the text of the discarded message begins at word
17 + i. That text is truncated, if necessary, to allow the error notification message to
reside within one MRF buffer. The length of the discarded message is given by field
P$ML in the parameters within words 1 through 16.
7833 1568–004 8–7

Error Processing Programs
8–8 7833 1568–004

Section 9
Message Recovery
The MCB plays an important role in performing both long and short message recovery
with the Integrated Recovery Utility (IRU). MCB common banks MSGBNK and
MSGLNGBNK act as an interface between IRU and MCB. During execution, an IRU
activity executes the MCB portion of message recovery from these two common banks.
9.1. MSGBNK
The IRU can call MSGBNK during short or long message recovery. The main function of
MSGBNK is to ensure that no inconsistencies exist between the Exec and MCB.
MSGBNK reads all queue items from the Exec and checks whether the MRF identifier
(MID) in each queue item exists in an MCB message retention file (MRF).
If a queue item contains a MID that MSGBNK cannot find, a message noting the
inconsistency is displayed on the Exec system console. MSGBNK also creates SNAPs of
the error-related information to send to a breakpoint print file (BPFILE) for later
examination. Upon completion of the comparison process, MSGBNK updates the
MRFCNTRL file to match the MIDs in use.
9.2. MSGBNK Interface to IRU
MSGBNK is called by the IRU activity. Register X11 contains the return address to the
IRU. The IRU activity passes a recovery parameter in register A0 when it enters
MSGBNK, and MSGBNK returns a completion status to the IRU in register A0.
When MSGBNK is entered with register A0, indicating that the application is initialized,
(A0I = 1), MSGBNK updates the MRFCNTRL file copy of the MCB directory with an
initialize status. When MSGBNK is entered with A0, indicating a recovery (A0I = 2),
MSGBNK goes through the recovery process. MSGBNK returns to IRU with A0 set to
indicate either a success (1) or a failure (2).
MSGBNK is installed by COMUS as an alternate file common bank (AFCB). The IRU uses
the file SYS$*MCB as a directory to find the BDI definitions. See the MCB Installation
Guide for more information about MSGBNK installation.
7833 1568–004 9–1

Message Recovery
9.3. MSGBNK Error Handling
When MSGBNK detects a problem, a dump and other related information are placed in
the breakpointed print file ����������������, which is generated during a recovery. You
should print the contents of this file and include it with any User Communication Forms
(UCF) you send to the development center.
9.4. MSGBNK Console Messages
See the MCB Operations Reference Manual for messages displayed on the system
console during an IRU execution.
9.5. MSGLNGBNK
The IRU calls MSGLNGBNK during a long message recovery to rebuild the message
retention files (MRF) and the MRFCNTRL file after a system failure.
MSGLNGBNK is called by the IRU activity. Register X11 contains the return address to
the IRU. The IRU activity passes a function and an audit record address to MSGLNGBNK
in register A0. If the IRU requests the status function (012), MSGLNGBNK calls MCBBNK
and returns either a down or an up status. If the function is a write request (010),
MSGLNGBNK looks at the audit record to determine what I/O to accomplish. Any other
function is treated as an error. MSGLNGBNK returns a status to IRU in register A1 as
follows:
• Write request
ER DM$IOW status codes returned. See the Transaction Processing Programming
Reference Manual for descriptions of these codes.
• Status request
05 = MCB is up.
06 = MCB is down.
• Other
014 = Either bad function code or bad audit header (word 0).
MSGLNGBNK is installed by COMUS as an AFCB. The IRU uses the file SYS$*MCB as a
directory to find the bank descriptor index (BDI) definitions. If your Exec has the
Multi-Host File Sharing (MHFS) feature installed, the IRU uses the file SYS$h*MCB
instead of SYS$*MCB. h is the host identifier converted to one letter a through z. See
the MCB Installation Guide for more information about MSGBNK installation.
9–2 7833 1568–004

Appendix A
Function Codes
Table A–1 lists the function codes for the CMS and application program packet interfaces
to the MCB.
Table A–1. Function Codes
Mnemonic Code Explanation
TRINIT$$ 02 Initialize
CMINIT$$ 03 CMS Activity Initialization
CMTERM$$ 04 CMS Activity Termination
CMSTOR$$ 05 CMS Store Input Message
CMCAN$$ 06 CMS Input Message Cancel
CMRECV$$ 07 CMS Receive Output Message
CMSACK$$ 010 CMS Output Message Positive Acknowledge
MHOLD$$ 011 CMS Output Message Hold
TERM$$ 012 Terminate
COMMIT$$ 013 Commit
ROLBAK$$ 014 Rollback
RECV$$ 015 Read Input
INPREL$$ 016 Release Input
CANCEL$$ 017 Cancel Output
SEND$$ 020 Store Output
PASOFF$$ 021 Store Pass-off
CHKPT$$ 022 Store Checkpoint
ENQUE$$ 023 Enqueue Message
AUDIT$$ 024 Audit
DISREC$$ 025 Discrete Receive
STAT$$ 030 Statistics Retrieval
CMSPUT$$ 031 CMS Put Text
CMSGET$$ 032 CMS Get Text
7833 1568–004 A–1

Function Codes
Table A–1. Function Codes
Mnemonic Code Explanation
CMSNAK$$ 033 CMS Output Message Negative Acknowledge
CMFAC$$ 036 CMS Obtain Resource Status
VNXRD$$ 037 Read VINDEX Entry
SETIXUSE$$ 040 Set Input-Only PID Exclusive Use
SETXUSE$$ 041 Set PID Exclusive Use
CLRXUSE$$ 042 Clear PID Exclusive Use
CLSSN$$ 043 Session Close
CMPIDI$$ 044 CMS PID Configuration
OPNSSN$$ 045 Session Open
PIDSTAT$$ 046 Request PID Status
CMSOPEN$$ 047 CMS Session Open Notify
RESOPEN$$ 050 CMS Resilient Session Open Notify
CMSPIDS$$ 051 CMS PID Information Request
SESSCLR$$ 062 CMS Session Close Reject
SESSOP$$ 063 CMS Open Confirm
SESSRJ$$ 066 CMS Open\ Reject
SESSAB$$ 067 CMS Session Abort
SESSCP$$ 071 CMS Session Close
SESSCL$$ 072 CMS Close Confirm
A–2 7833 1568–004

Appendix B
Error Codes
Table B–1 lists the status codes that are returned by the MCB to the calling activity in
the CMS and application program packet interfaces. MCB returns this information in the
status parameter specified on the MCB call. Bit 35 is set with all error codes, which
makes the status word negative. For basic mode assembler-language programs, this
information is in register A1.
Note: For codes 6, 7, 014, and 0137, Q3 of the status word contains the error code
returned by step control and Q4 contains the error code given in this table. The codes
returned in Q3 are defined in the Exec Administration Reference Manual. For codes 060
to 064, 070 to 074, and 0100 to 0104, Q3 contains the Exec I/O error code (if it exists).
Q4 contains the MCB error code.
Table B–1. Error Codes
Code Meaning
01 MCB is not up.
02 User packet overlaps MCB D-banks.
03 User packet address not in range, or attempt to use primitives with primitives
disabled in the configuration.
04 Calling program is not in quarter-word mode.
05 Invalid queue-item id (P$QID).
06 ER TIP$Q rejected (see note).
07 User audit rejected (see note).
010 Maximum number of CMS programs already initialized with MCB.
011 Maximum number of program activities already initialized with MCB.
012 Calling activity not initialized with MCB.
013 Calling activity already initialized with MCB.
014 ER QI$NIT/QI$CON/QI$DIS/CO$MIT/ROL$BAK rejected (see note).
015 CMS may not terminate with messages active.
016 Attempt to read a partially staged message or write a completely staged
message.
017 ACW length too small.
7833 1568–004 B–1

Error Codes
Table B–1. Error Codes
Code Meaning
020 Privileged function. Normally indicates that an application program is
attempting to use a CMS function.
021 PID selected for use has exclusive use set by another program.
022 No input message is currently assigned to the calling activity but input
message access was attempted.
023 Exclusive use or conversational link is already set for the PID.
024 No partially staged message exists.
025 Attempt to do ROLLBACK, but no step exists.
026 Attempt to store a message larger than the size configured with the
MSGMAXCHARS characters parameter.
027 Output rejected. Session not open to this PID.
030 Invalid function code.
031 Invalid message identifier (P$ID).
032 Invalid queue-item identifier (P$QID).
033 Buffer address out of range.
034 Invalid PID.
035 Invalid transaction code. FLAGBOX SCHEDULE bit may be OFF.
036 Character pointer (P$START) is past the current end of message.
037 Character pointer (P$START) is past end of message.
040 Conversational link not in effect but requested by CMS.
041 Access mask violation. Indicates a transaction code entered from unauthorized
terminal.
042 Invalid mode (P$MODE).
043 Conversational link and delivery notification may not both be specified.
044 No PRP buffer is available.
045-050 Reserved.
051 Invalid PID for conversational link.
052 Transaction is not numbered or recoverable, but an assurance unit was
presented by CMS.
053 MCB detected step-id mismatch during commit or rollback. Probable causes: a
step was previously advanced by a program performing its own ER-CO$MIT,
or a step was previously advanced by Universal Database Control and
Universal Database Control is not configured with the correct BDI for notifying
MCB of step changes.
054 No more MRF space exists.
B–2 7833 1568–004

Table B–1. Error Codes
Code Meaning
056 No more main storage buffers exist for message staging.
Error Codes
056 No more work buffers (MAD) exist for active message processing or auditing.
057 MCB idle point in progress.
060 MRF I/O error (see note).
061 MRF control file I/O error (see note).
062 Message text audit request rejected (see note).
063 Segment controls audit request rejected (see note).
064 PIX file I/O error (see note).
065 Reserved.
066 Reserved.
067 Set up error such as PCT expansion needed but not possible.
070 MRF file not cataloged or assigned to TIP, or attempt to store a recoverable
message with no associated recoverable MRF file configured (see note).
071 MRF control file not configured (see note).
072 Reserved.
073 Reserved.
074 PIX not configured (see note).
075-077 Reserved.
0100 MRF improperly configured (see note).
0101 MRF control file improperly configured (see note).
0104 PIX improperly configured (see note).
0105 Invalid CMS level number.
0106 Invalid CMS number.
0107 Function not allowed with the MCB or CMS level in use.
0110 Invalid subfunction on CMPIDI$$.
0111 V option not set for session open or close.
0112 Session request in error.
0113 Session close attempt by program that did not open the session.
0114 No program queued for session status function.
0115 CMS termination with sessions open.
0116 Close request but no session open.
0117 Attempt to open or close a session for a group PID.
7833 1568–004 B–3

Error Codes
Table B–1. Error Codes
Code Meaning
0120 No CMS registered on outbound open or outbound close.
0121 No auxiliary area for a session request.
0122 PID in use with another CMS number.
0123 RT$OUT ERROR - no EXPOOL left (session control).
0124 Attempt to use empty PID site-id table.
0125 PID number not in PID site-id table.
0126 Site-id not in PID site-id table.
0127 Site-id interface packet end address not within application program bank.
0130 Wrong function for site-id packet version.
0131 Multiple numbered pass-off error.
0132 Discrete receive parameter error.
0133 Message not recallable.
0134 Packet cell required to be zero (P$BUFF, P$RTN, P$MDL) was not zero.
0135 Invalid function, subfunction, or queue priority specified in P$OUTQ field.
0136 Invalid TIP session identifier.
0137 ER TIP$XMIT rejected (see note).
0140 Step advance and terminate both specified on commit.
0141 MAD in use by another activity; access not allowed. Only activities initialized
with CMINIT$$ (P$FUNC = 3) receive this error code.
0142 Standard calling sequence error on an extended mode call to MCB. This
indicates that a parameter failed the validation check. If the status parameter
failed, or if the call descriptor is invalid, MCB cannot return a status code.
MCB gives the calling program a contingency through ER CQUE$ (error type
04, error code 00, contingency type 021). MCB also provides diagnostic
information; register A12 contains the number of the invalid parameter (1 for
first, 2 for second, and so on), and A13 contains the auxiliary information as
defined for contingency type 021, error type 04.
0143 Auxiliary data area outside the user D-bank or main storage buffer size less
than the AUX area.
0144 Multidestination list address out of range or too many entries requested.
0145 Auxiliary area (P$AUX) not large enough.
0146 More than one option set for rollback in P$FLAGS.
0147 Group PID or multidestination list is not allowed when P$MN is nonzero and
message numbering option is set.
0150 File wrapped on recall.
B–4 7833 1568–004

Table B–1. Error Codes
Code Meaning
0151 Extended mode program attempted to interface with MCB when
EXTENDEDMODE NO was configured.
Error Codes
7833 1568–004 B–5

Error Codes
B–6 7833 1568–004

Appendix C
Message Recovery Options
C.1. Recovery Option Combinations
You can specify any of these options for a message:
• Low Main Storage Priority (LCP)
• Message Recall (MR)
• Message Numbering (MN)
• Text Auditing (ADT)
• Defer the Message (DEF)
• Recoverable Message (REC)
The following rules control the Message Control Bank (MCB) response to each
combination of options:
1. Low main storage priority (LCP) is independent of any other options. It may be set or
clear for any message. If the LCP option is set, the message may be overlaid by
messages that do not have this option set.
2. Text Auditing (ADT) requires the recoverable message (REC) option. If REC is set,
ADT is honored (auditing is performed only if the ADT option is set). If REC is not set,
ADT is ignored. ADT may be set for any message, but it has no meaning if REC is not
also set.
3. If REC is not set, the defer the message (DEF) option may be either set or clear, and
the option will be honored. Thus, if the DEF option is set, the message is not
forwarded by step control until the step ends. If the DEF option is not set, the
message is forwarded to either CMS (output message) or the input queue (pass-off
message) immediately when ER TIP$Q is performed.
4. If REC is set, then DEF must also be set. If DEF is not set when REC is set, the
application program gets an error when the message is queued. A Store function
without the last block indicator (LBI) will be successful. The error is detected only
when the message is passed to step control, because step control is the module
concerned with deferring messages.
5. The following rules apply to the message numbering (MN) option in conjunction with
other options:
a. REC+MN, but not DEF. This case is treated as in rule 4. Since the message is
recoverable but not deferred, step control returns an error status when an ER
7833 1568–004 C–1

Message Recovery Options
TIP$Q is performed. The error is passed to the MCB’s caller. MCB does not
return an error to its caller before performing an ER TIP$Q (an MCB call with LBI
set).
b. DEF+MN, but not REC. In this case, there are three possibilities:
• MCB always sets the REC and DEF options for a checkpoint message. For a
pass-off message, MCB removes the MN option before performing an ER
TIP$Q because step control does not accept the MN option without the REC
option.
• These events occur for an input message:
1) If the originating PID is unintelligent, no error is returned to the caller.
MCB removes the MN option before performing ER TIP$Q.
2) If the originating PID is intelligent:
If P$MN is nonzero, the message number provided in P$MN is passed to
the target transaction program.
If P$MN is zero, there is no intelligent numbering. MCB removes the MN
option.
• These actions are taken for an output message:
1) If the destination PID is unintelligent, an error status is returned to the
caller.
If P$MN is nonzero, the message number provided in P$MN is used. If
P$MN is zero, an error status is returned to the caller as in the case of an
unintelligent PID.
MN alone. This is similar to case b, but the message is immediate
because the DEF option is not set.
2) If the destination PID is intelligent:
If P$MN is nonzero, the message number provided in P$MN is used. If
P$MN is zero, an error status is returned to the caller as in the case of an
unintelligent PID.
MN alone. This is similar to case b, but the message is immediate
because the DEF option is not set.
• MR requires REC, DEF, and MN. Again, there are several cases to consider:
MR alone, MR+MN, and DEF+MR+MN. These cases are all the same. Since
the REC option is not set, neither the MN nor MR options are ever checked.
DEF is checked independently, so the last combination results in a deferred
message while the first two combinations result in immediate messages. In
this case, the MCB removes the MN option to avoid errors from an ER
TIP$Q. This is the same as the first case under rule 5. If the destination PID
is unintelligent, an error status is returned to the calller. REC+DEF+MR, but
not MN. The MR option is never checked since a recallable message must
be numbered. Without the MN, the MCB does not care whether or not MR
is set. This combination of options results, therefore, in a recoverable,
deferred message without numbering, recall, or auditing. REC+MN+MR, but
not DEF. This is treated as in rule 4. Thus, the MCB processes the message,
C–2 7833 1568–004

Message Recovery Options
including numbering and recall, up to the point of doing an ER TIP$Q. An
error is returned by step control and is passed back to the caller of the MCB.
The message is not passed to its destination. The number that the MCB had
assigned to the message is reused later.
• REC may be set or clear for any message. This is the controlling option for
ADT, MN, and MR. If REC is not set, then ADT, MN, and MR are not
checked and may or may not be set. If REC is set, then DEF is required, and
the ADT, MN, and MR options are honored subject to the conditions given
earlier.
C.2. Message Numbering
For message numbering, it is important to note that the recovery options are not the only
factors in determining whether or not a number is assigned to a message. For input
messages, the transaction code entry in the VINDEX must specify numbering (the MN
option just discussed), and the PID must specify numbering. For an output message, the
MN, DEF, and REC option must all be set, and the PID must specify numbering. For a
pass-off message, the REC, DEF, and MN options must all be set, the input message for
the step generating the pass-off must be nonrecoverable, and the input PID for the step
must specify unintelligent numbering. For a checkpoint message, the conditions for a
pass-off message must be met.
Note that assignment of a number to a message does not imply the presence of
message headers. Headers are optional. They are contingent on the PID configuration
and the auxiliary data area fields P$HDR, P$HDRSIZE, and P$END.
7833 1568–004 C–3

Message Recovery Options
C.3. Program Recovery Options
For any program, there are three sets of recovery options:
• One set for input, pass-off, and checkpoint messages directed to the program
• One set for output messages generated by the program
• One set for operations on behalf of the program while it is executing.
One of the options in the third set, the Z option, declares if the program is recoverable (Z
option set) or nonrecoverable (Z option not set). Step control requires that the Z option be
set when any recoverable message processing is done. If the program step is
nonrecoverable, an attempt to create a recoverable message of any type results in an
error returned to the caller.
The recovery options in effect for any program at any time are determined by the queue
item associated with the program. A queue item is created together with a message or
by a request to start a step without a message. When a program is processing a
message, its options are those defined when the message was created, not the options
that may have been declared by the program with an ER QI$CON. The options declared
by the program take effect only if the program starts a step without receiving a message.
There is one exception to this rule. If an Network Database Server run unit opens a
recoverable database area for update without having the � option set, Universal Database
Control does an ER DMSS$ and step control sets the � option in the queue item. Thus,
the MCB and Network Database Server may have recorded different sets of options for
the same step.
C–4 7833 1568–004

Appendix D
Audit Records
All audit records created by the Message Control Bank (MCB) have the following format:
0 type subtype length of
audit header
1-2 unique-id
3-7 reserved
8
through data depending on the record type
n-1
The following table explains the format of an audit record:
record length n
Word Field Value Explanation
0 type (S1) 021 This distinguishes MCB records on the audit
trail from those records created by other
software components, such as the OS 2200
Exec or Network Database Server.
0 subtype
(S2)
01 MCA message block
02 Overflow message block
03 MRF control file header after an idle point
04 MRF controls
05 Periodic statistics
06 MRF controls after an idle point
07 Error record for ER TIIP$Q
010 PID audit record
7833 1568–004 D–1

Audit Records
Word Field Value Explanation
0 record
length
(H2)
The number of words in this audit record,
including the 8-word header.
1 through 2 unique-id For subtypes 1, 2, and 7: unique-id of the
message
3 through 7 Reserved.
For subtypes 3, 4, 5, and 6: value = 0
The unique-id contains the step-id of the
calling program.
8 through n-1 The record length is eight words plus the
number of words presented by the application
Site-developed audits through the MCB function AUDIT$$ are given a type 023 and a
subtype of 02.
MCB idle point records produced by the II keyin IDLPT are given a type 024 and a
subtype of 02. The record length is four words. The time and date stamp appears in
word 1 and the number of message retention files (MRF) in word 2.
D.1. MCA Block
When a recoverable message is audited, each message block is written as a separate
audit record. The first block, the message control area (MCA) block, is actually audited
last. The order, therefore, in which the blocks of a given message appear on the audit
trail is
2 3 N 1
Figure D–1. Order of MCA Blocks in Audit Trail
The text of the audit record of an MCA block is that format shown in F.1.4.
D.2. Overflow Block
The text of the audit record of an overflow message block is in the format shown in
F.1.4.
D–2 7833 1568–004

D.3. User Audit Record
Audit Records
The text of a user audit record is that data supplied by the calling program on an MCB
Audit function in the buffer P$BUFF with length P$LENGTH (see 5.5.12).
D.4. MRF Controls
For a recoverable MRF file, whenever a segment changes state from free to active,
active to retired or retired to free, the MRF controls for that MRF file are written to the
audit trail. The text of the audit record is in the format shown as MF$CTL in F.3.2.
D.5. Periodic Statistics
If periodic statistics have been invoked with the $STADT command, on each periodic
interval, an audit record is created whose text consists of the statistics table ST$TBL
(see F.9.
D.6. TIP$Q Error
If the MCB request to pass the message to step control fails, no queue item (QITEM)
audit record will appear on the audit trail for this step. This audit record takes the place
of the missing QITEM record, which allows the IRU to recover the message properly.
7833 1568–004 D–3

Audit Records
D–4 7833 1568–004

Appendix E
Tailoring Features
If you choose to tailor MCB code for special purposes at your site, you must be aware
that your specially written code interacts with the activities of your application programs
and the activities of CMS. You are responsible for controlling the performance factors of
your code. The two programs described in this section affect the performance of both
the MCB and the Exec.
E.1. Tailored Message Analysis (TMA)
Tailored Message Analysis (TMA) lets you write your own code for additional or alternate
processing for each message type. The entry and exit requirements are the same for
each message type.
TMA code resides in the element MC$TMA of the base symbolic files. Use temporary
corrections to insert the TMA code after the entry points listed in the following table:
Entry Usage
TMAINP Network input message
TMACHK Checkpoint message
TMAPAS Pass-off message
TMAOP Output message
Each entry point is externalized and reached with an LMJ from the initial message
analysis (IMA) routine for each message type. For pass-off, checkpoint, and output
messages, initial message analysis (IMA) is invoked prior to any processing. For a
network input message, IMA is invoked when the MCB fills the first MRF block of the
message or when CMS indicates the end of the message, whichever comes first.
7833 1568–004 E–1

Tailoring Features
The following table lists values passed to TMA.
Register Value
X8 Address of the main storage buffer containing the message control area
(MCA) block of the message
X9 Address of the MAD
X10 Address of the SLOT
X11 Return address
The tailored code may return to the main line IMA code (J 0,X11) or to the message
retention and control dispatcher (J MRFRET) when the TMA process is complete. The
correct values on return are listed in the following table:
Register Value
X9 Address of the MAD
X10 Address of the SLOT
X8 Address of the main storage buffer containing the MCA block of the
message. This is only true if returning to IMA main line code.
All other registers in the minor register set are available for use by TMA.
Your code can reference internal MCB tables and invoke internal MCB subroutines. You
should recognize, however, that when you write your own code, you are responsible for
contending with internal changes to the MCB as a result of software fixes or feature
enhancements.
You must write input messages so that both the auxiliary data area and transaction code
fit in a single main storage buffer. If the TMA code you write references text following
the transaction code, then those characters must also fit in the first main storage buffer.
Your code can change the recovery options that apply to network input messages.
Changing the recovery options is of benefit within a recoverable application where most
messages for a transaction do not need to be recoverable. TMA code can add the
desired recovery option bits in the MAD and core buffers for the selected message.
Adding the desired recovery option bits requires that you set the recoverable program
step option (REC,Z) for any transaction that can receive a recoverable input.
TMA code can make use of the user message control feature of MCB. This feature
allows TMA code to either discard or reject input messages. In the case of message
discard, the original input message is thrown away. In the case of message reject, the
originator is sent a rejection message. To discard an input message, you must set the
MA$UMCREJ flag in the MAD. To send a reject message, you must set the
MA$UMCRSP flag in the TMA code. In this case, you must also set up the text of the
reject message in the message portion of the current input core buffer and place the
length of the text of the message in CA$LEN.
E–2 7833 1568–004

Tailoring Features
If you include the SLT$USIZE SGS in your MCB generation (see the MCB Installation
Guide), your TMA code can store its own data within the SLOT table associated with the
executing activity. The user storage area begins at S$UAREA,X10. Your TMA code must
check the value of SLT$USIZE to verify that the user area exists and is large enough
before storing any data in the user area.
E.2. Tailored Session Analysis (TSA)
TSA lets you write your own code for additional processing of an open, close, or
abnormal termination of a session. The TSA code resides in the element MC$TSA of the
base symbolic files. Use temporary corrections to insert the TSA code after the entry
points listed in the following table:
Entry point Usage
TSAOPN Open session
TSACLS Close session and abnormal termination
Each entry point is externalized and reached with an LMJ from MC$DISP after all
processing for each PID is complete, depending on the session type. The values are
listed in the following table:
Register Value
A1 PID
X10 SLOT address
X11 Return address
Your code returns to the main code with an LMJ (J 0,X11) when the TSA process is
complete. Your code must save and restore all registers except A1.
If you include the SLT$USIZE SGS in your MCB generation (see the MCB Installation
Guide), your TMA code can store its own data within the SLOT table associated with the
executing activity. The user storage area begins at S$UAREA,X10. Your TMA code must
check the value of SLT$USIZE to verify that the user area exists and is large enough
before storing any data in the user area.
7833 1568–004 E–3

Tailoring Features
E–4 7833 1568–004

Appendix F
Data Structures
F.1. Message Block Structure
MCB stores each message in one or more blocks. The size of a block is defined by the
configuration parameter BUF$SIZE. The first block for a message is called the MCA
block. If the message text is too long to fit in the MCA block, one or more overflow
blocks are used.
F.1.1. Notation Conventions
Data Structure Diagrams
An asterisk in front of a word number (for example, *02) indicates an overlay of the
previous word.
Two dots (..) indicates continuation of number in the word number column.
Three dots (...) indicate continuation within the word.
Tables
Numbers within parentheses indicate value; for example, CA$MCA (040) means that
CA$MCA has a value of 040.
F.1.2. MCA Block
MCB creates a message control area (MCA) for each unique message it processes. MCB
uses the MCA internally to retain pertinent information during message processing, until
the message is released from MCB control. The MCA is located in the first block of each
message (called the MCA block). Figure F–1 shows the MCA block structure.
MCA
auxiliary information area (optional)
multidestination list (optional)
message text
Figure F–1. MCA Block Structure
7833 1568–004 F–1

Data Structures
The configuration value for BUF$SIZE must be greater than the sum of the sizes of the
MCA, the auxiliary information area, and the MDL, so that the message text begins in the
first block.
F.1.2.1. MCA Field Definitions
The fields located in the MCA area in Figure F–1 are shown in Figure F–2.
CA$FLG CA$MCYC CA$BCYC CA$DCT CA$TDC
CA$LNK
CA$PRG CA$LEN
CA$SAM1
CA$SAM2
CA$SAM3
CA$SAM4
CA$TC1
CA$TC2 CA$CVL
CA$DPS 0 CA$AUXL CA$FLAGS
TQ$PKT
TIP$Q packet begins here (see F.1.2.2)
Figure F–2. MCA Field Definitions
If the MCA is associated with a nonrecoverable message, words 03 through 06 have a
different format from the one shown in Figure F–2.
03 CA$MID2 CA$MID3
04 CA$MID4 CA$MID5
05 CA$MID6 CA$MID7
06 CA$MID8 CA$MIDOVF
F–2 7833 1568–004

Word Field Name Explanation
00 S1 CA$FLG: MCA flags:
CA$MCA (040)
• MCA block if set
CA$SCRN (020)
• TQ$DPS value is in MCA
CA$DUP (010)
• Possible duplicate message
CA$PST (004)
• Post-processing transaction in CA$CVL
CA$MODE (002)
• User requested mode change on output
CA$GPID (001)
• Group PID output
00 S2 CA$MCYC Message MRF cycle
S3 CA$BCYC Message MRF block cycle
Q3 CA$DCT Destination count for this message
Q4 CA$TDC Original destination count for this message
01 W CA$LNK Link to overflow block of message (MID)
02 H1 CA$PRK Program number of originator if Group PID output
H2 CA$LEN Logical message size in characters
03 W CA$SAM1 SAMs for this recoverable message
04 W CA$SAM2
05 W CA$SAM3
06 W CA$SAM4 Zero or link to next block of this message
03 H1 CA$MID2 MIDs for this nonrecoverable message
H2 CA$MID3
04 H1 CA$MID4
H2 CA$MID5
05 H1 CA$MID6
H2 CA$MID7
06 H1 CA$MID8
H2 CA$MIDOVF Zero or link to overflow chain of blocks.
07 W CA$TC1 ASCII transaction code (Part 1)
Data Structures
7833 1568–004 F–3

Data Structures
Word Field Name Explanation
010 H1 CA$TC2 ASCII transaction code (Part 1)
H2 CA$CVL VINDEX index of conversational link or post
011 H1 CA$DPS Display Processing System screen number save area
S5 CA$AUXL Length of auxiliary area
S6 CA$FLGS More MCA flags:
CA$ACK (040)
• MCB input ACK (release input lockout)
CA$WAIT (020)
• MCB wait message
CA$CVLINP (010)
• Conversational link input message Word
012 W TQ$PKT Start of the TIP$Q packet
F.1.2.2. TIP$Q Packet Field Definitions
The TIP$Q packet is included in the MCA for all message types. MCB uses this
information internally for ER TIP$Q processing. The TIP$Q packet extension areas shown
in Figure F–4 and Figure F–5 contain information pertinent to specific message types.
The fields in the TIP$Q packet are shown in Figure F–3.
0 TQ$STID
01
02 TQ$PID TQ$MN
03 TQ$CBN TQ$FN
.. TQ$MID
04 TIP$ packet extension (Words 04 through 010)
Figure F–3. TIP$Q Packet Field Definitions
Word Field Name Explanation
00 W TQ$STID Program’s step identifier (part 1)
01 W Program’s step identifier (part 2)
02 H1 TQ$PID Input or destination PID
H2 TQ$MN Input message number (0 for output messages)
F–4 7833 1568–004

Word Field Name Explanation
03 W TQ$MID MRF identifier (MID) of the MCA block of this message
S2 TQ$CBN Core bank number for the message being processed
S3 TQ$FN Relative MRF file number containing this message
F.1.2.3. TIP$Q Packet Extension for Output Messages
Data Structures
04 TQ$OUTQ 0 TQ$TYPE 0
05 0 TQ$ORCC 0
06 0 TQ$SEC 0
07 TQ$OSN
010 0 TQ$BDI
011 TQ$ORUNID
Figure F–4. TIP$Q Packet Extension for Output Messages
Word Field Name Explanation
04 H1 TQ$OUTQ Output queuing information (includes the output function,
indicator and queuing priority)
S5 TQ$TYPE Message type:
MT$OP (04)
• Output
05 S4 TQ$ORCC Output recovery options
06 S3 TQ$SEC Security options:
TQ$HIGH (1)
• System high
TQ$LOW (2)
• System low
07 W TQ$OSN Save area for originator’s sequence number
010 H2 TQ$BDI Common bank BDI for the group PID table of a requested
group PID number
011 W TQ$ORUNID Run-id of the program originating the message
7833 1568–004 F–5

Data Structures
F.1.2.4. TIP$Q Packet Extension Area for Other Message Types
04 TQ$PGN TQ$IPRI TQ$TYPE TQ$MODE
05 0 TQ$RCC
06 0 TQ$PGNX TQ$ORCC TQ$IRCC
07 0 TQ$SEC TQ$SESID
Figure F–5. TIP$Q Packet Extension Area
Word Field Name Explanation
04 T1 TQ$PGN Program number (least significant 12 bits)
T2 TQ$IPRI Queuing priority
S5 TQ$TYPE Message type:
MT$NET (01)
• Network input
MT$CHK (02)
• Checkpoint
MT$PAS (03)
• Pass-off
MT$PUT (05)
• Text stored by CMS put text function
MT$TMR (06)
• Timer input
S6 TQ$MODE Message mode
05 H2 TQ$RCC Recovery options
S3 TQ$PGNX Program number extension (most significant 6 bits)
S4 TQ$ORCC Output recovery options
S5 TQ$IRCC Input recovery options
06 S3 TQ$SEC Security options. See F.1.2.3.
H2 TQ$SESID TIP session control identifier
F–6 7833 1568–004

F.1.3. Overflow Block
Data Structures
In addition to an MCA block, a message may consist of one or more overflow blocks.
Figure F–6 shows the overflow block structure.
0 0 CA$MCYC CA$BCYC 0
01 CA$LNK
02
message text
Figure F–6. Overflow Control Field Definitions
Word Field Name Explanation
00 S2 CA$MCYC Message cycle
S3 CA$BCYC Block cycle
01 W CA$LNK MRF identifier (MID) of next block if one exists, or 0
F.1.4. Main Storage Buffers
The MCB main storage buffers provide a high-speed staging area for message retention.
The number of main storage buffers is specified in the MCB configuration. At least one
main storage buffer should be configured for each activity in the system (the number of
SLOTs).
Buffers are organized on free and active chains. In the initial state, all the main storage
buffers are located on the free chain, with no buffers on the active chain. A buffer on the
free chain contains a zero MRF identifier.
The free chain consists of unallocated buffers or buffers returned by a release of all
facilities associated with a message. The resource release could occur because of
message cancellation or message completion.
The active chain consists of partial message blocks, nonrecoverable blocks, or complete
blocks.
Main storage buffers are allocated in the following way. First, the MCB attempts to
allocate a main storage buffer from the free chain. If no buffer is found there, the first
buffer is selected from the active chain. Since this buffer contains valid data, it may have
to be written to an MRF file. This buffer is written to its associated MRF file if the buffer
is partially filled or is a block of a nonrecoverable message not previously written
(CB$PAR =1). Since a full block (full buffer) of a recoverable message is written to an
MRF when created, there is no need to write it to mass storage when it is reallocated.
Figure F–7 shows the field definitions for the main storage buffer and the main storage
buffer structure.
7833 1568–004 F–7

Data Structures
0 CB$FL CB$BL
01 CB$CMS CB$USE CB$STAT
02 CB$MID
03 CB$MID1
message block
(See F.1.2 or F.1.3)
Figure F–7. Main Storage Buffer Field Definitions
Word Field Name Explanation
00 H1 CB$FL Link to next main storage buffer on chain. If currently
dechained, content is zero.
H2 CB$BL Link to prior main storage buffer on chain. If currently
dechained, content is zero.
01 S1 CB$CMS CMS number for ROPL
S2 CB$USE Flag to indicate the buffer is in use.
S3 CB$STAT Main storage buffer status:
(000)
• Complete main storage buffer (I/O done).
CB$PAR (040)
• Partial main storage buffer (will be marked partial until an
I/O is done).
02 W CB$MID MRF identifier of this block. Content is zero if on the free main
storage buffer chain.
03 W CB$MID1 MRF identifier of the MCA block. Content is zero if on the free
main storage buffer chain.
F.2. Message Retention File (MRF) Operations
MCB uses several data structures to support MRF operations: the MRF itself, MRF
segments and blocks, the MRF control table, the segment allocation mask (SAM) area,
and the MRF identifiers.
F.2.1. Recoverable MRFs
Up to 63 recoverable MRFs may be configured in your system. A recoverable MRF is
composed of segments. The segments are composed of message blocks (Figure F–1),
which are the actual units of storage.
F–8 7833 1568–004

Data Structures
A recoverable MRF is organized into segments. Any segment is in one of three states:
free, active, or retired. A free segment is one with all blocks available for allocation. An
active segment is one designated for allocation of blocks. After all blocks of a segment
have been allocated, the segment is designated retired, and a new segment is allocated
as an active segment. A retired segment becomes a free segment when all blocks of
that segment have been returned. An MRF may have at most one active-input and one
active-output segment at one time. Segments are allocated sequentially on a first-in,
first-out stack; the oldest free segment is allocated next.
F.2.2. Nonrecoverable MRFs
A nonrecoverable MRF is a message retention file that holds nonrecoverable messages.
The blocks of the MRF 0 file are used as a paging area for message blocks in the main
storage buffer banks (CORBNK). Allocation of MRF blocks is controlled by a bit map kept
in the MRF control bank (CTL$BNK1). Each bit in the bit map corresponds to a single
block.
F.2.3. MRF Control Tables
Each MRF is controlled by a table. Since each MRF may be a different size, a common
control table (MF$CTX) organizes the independent control tables (MF$CTL). At system
generation time, the user specifies the size of each MRF, along with the proper MRF for
recoverable input or output messages from each PID. The MRF file specified for
recoverable input messages is also used for recoverable pass-off and checkpoint
messages. MRF 0 is used for all nonrecoverable messages.
The control table for each MRF contains information to control the allocation and release
of segments and blocks. For recovery processing purposes, whenever a segment of a
recoverable file is allocated, a copy of the MRF control table is saved on mass storage
and optionally written to the audit trail. This information, along with information
accumulated in step control, enables the controls to be recovered in the event of
component or system failure.
F.2.4. MRF Blocks
A message is composed of one or more blocks linked together by MRF identifiers (MID).
These blocks can reside in main storage buffers and in blocks of an MRF. The latest copy
of a complete recoverable block always resides in an MRF. Nonrecoverable and partial
blocks are only written to an MRF in an overflow condition. The blocks of a message can
reside in several segments of a single MRF, but they cannot reside in more than one
MRF.
Since a segment allocation starts an I/O operation, carefully consider the number of
blocks configured per segment. If small segments are configured (containing few
blocks), more I/O operations will occur. If large segments are configured (containing
many blocks), it is more probable that all segments will be retired. As long as one block
of a segment is still allocated, it cannot be placed on the free segment list.
7833 1568–004 F–9

Data Structures
F.2.5. MRF Identifiers (MID)
MRF blocks are allocated sequentially in a segment. Each block of an MRF file is
identified with a MID. This identifier is composed of a file number, segment number, and
block number as shown in the following formats. MCB uses this unique MID to locate a
block on the active main storage buffer chain, or perform an I/O to retrieve a block
written to an MRF file.
MID format:
0
(12 bits)
File #
(6 bits)
Segment #
(10 bits)
OS 2200 Queue Item MID format when using Multiple Corbnks:
0
(6 bits)
Corbnk
(6 bits)
File #
(6 bits)
Segment #
(10 bits)
F.2.6. Segment Allocation Mask (SAM) Area
Block #
(8 bits)
Block #
(8 bits)
As MRF blocks are returned to a segment, a count is kept to detect when a segment is
free. A count of the number of MRF blocks assigned to a message is kept in a segment
allocation mask (SAM). The SAMs can be found in the MRF allocation descriptor (MAD)
when the message is being accessed, and in the message control area (MCA) while
waiting to be accessed. A SAM is composed of a file number, segment number, and a
block count of this message from the specified segment as shown below. Since the
MRF blocks are allocated sequentially, this information is all that is needed to return
blocks to a segment. It is not necessary to know which blocks in the segment are
allocated.
SAM format:
0
(12 bits)
File #
(6 bits)
Segment #
(10 bits)
Block count
minus 1
(8 bits)
F–10 7833 1568–004

F.3. Main MRF Control Table (MRF$TBL)
Data Structures
The MCB directory points to the main MRF control table as shown in Figure F–8.
00 MF$CTXL MF$CTX
01 MRF$LEN MRF$NPX
02 MRF$PIX MRF$PBK
… …
MRF$PIX MRF$PBK
Figure F–8. Main MRF Control Table
Beginning with word 02, there is one word per PIX file.
Word Field Name Explanation
00 H1 MF$CTXL Length of MF$CTX table
H2 MF$CTX Offset to the MF$CTX table
01 H1 MRF$LEN Number of MRFs
H2 MRF$NPX Number of PIX files
02 H1 MRF$PIX TIP/Network Database Server file number of PIX file
H2 MRF$PBK Number of PIX blocks in PIX file
F.3.1. MRF File Table (MF$CTX)
The MRF file table, shown in Figure F–9, contains one two-word entry for each
configured MRF.
00 MR$FCL (0) MR$FCA (0)
01 MR$FCI (0) MR$FCC (0)
02 MR$FCL (1) MR$FCA (1)
03 MR$FCI (1) MR$FCC (1)
…
2N MR$FCL (N) MR$FCA (N)
7833 1568–004 F–11
…
MR$FCI (N) MR$FC (N)
N=63
Figure F–9. MRF File Table

Data Structures
Word Field Name Explanation
00 H1 MR$FCL Length of MRF control table
H2 MR$FCA Offset to the MRF control table
01 H1 MR$FCI Index into MC$DIR for this MRF
H2 MR$FCC Common bank BDI, which contains this MRF control
F.3.2. MRF Control Table (MF$CTL)
Each MRF has a control table MF$CTL. For the first MRF (MRF-0), the format of the
control table is shown in Figure F–10.
00 SC$TS
01 SC$LMID SC$NABLK
02 SC$SEC SC$NSEG
03 SC$MFN SC$NBMW
04 MID bit map words
where:
X is 0 for an allocated MID.
X is 1 for an available MID.
(8192 words maximum, 32 bits per word are used)
format:
0XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX000
Figure F–10. MRF Control Table
In the first word, the leftmost X corresponds to MID 0, and is permanently allocated.
Each MID bit map word contains a leftmost zero, 32 Xs, and three rightmost zeros.
Word Field Name Explanation
00 W SC$TS Test-and-set
01 H1 SC$LMID Latest MID allocated
H2 SC$NABLK Number of active blocks
02 H1 SC$SEC Sector address of information in MRF$CNTRL
H2 SC$NSG Number of configured elements
F–12 7833 1568–004

Word Field Name Explanation
03 H1 SC$MFN MRF Network Database Server file number
H2 SC$NBMW Number of bit map words
04 W Bit map words
The control table formats for MRF-1 through MRF-63 are shown in Figure F–11.
00 SC$TS
01 SC$AI SC$A0
02 SC$SEC SC$NSG
03 SC$MFN SC$PFN
04 SC$CF SC$CSC SC$CSB
.. word 4 repeated once per segment
SC$CF SC$CSC SC$CSB
4+N SC$FSN
5+N SF$SOLD SC$FSNEW
SC$FS ... ... ...
.. ... ... ...
N number of segments
Figure F–11. MRF Control Table Formats
Data Structures
Within this table, beginning at word 4, one control word exists per segment. Following
this set of words are two words of control information for the free segment list, followed
by the free segment list itself.
Word Field Name Explanation
00 W SC$TS Test-and-set cell used when altering this MRF control table
01 H1 SC$AI Segment currently being allocated for input messages
H2 SC$AO Segment currently being allocated for output messages
02 H1 SC$SEC Sector address of this MRF in MRF$CNTRL
H2 SC$NSG Number of segments in this MRF Word
03 H1 SC$MFN TIP/Network Database Server file number assigned to this
MRF
H2 SC$PFN TIP/Network Database Server file number of associated PIX
file (may be 0)
7833 1568–004 F–13

Data Structures
Word Field Name Explanation
04 T1 SC$CF Number of blocks freed in this segment (This field only
applies to retired segments.)
S3 SC$CSC Segment cycle number
H2 SC$CSB Segment number, block number of next block to be assigned
4+N W SC$FSN Number of free segments
5+N H1 SC$FSOLD Offset to oldest free segment
H2 SC$FSNEW Offset to newest free segment in the free segment list
SC$FS Start of free segment list
F.4. Buffer Pool Controls
Each word in the free segment list is broken into thirds with
each third containing a free segment number. The offsets
SC$FSOLD and SC$FSNEW provide access to this list for
segment allocation and release respectively.
The data in these fields, shown in Figure F–12, controls the MRF allocation descriptor
(MAD), main storage buffer, and message release resources of the MCB.
Q$FL Q$BL
Q$TS
Q$RET Q$CUR
Q$MAXN Q$MIN
Q$PS Q$PE
Q$SIZ unused
Figure F–12. Buffer Pool Control
Word Field Name Explanation
00 H1 Q$FL Address of buffer on the head of the chain
H2 Q$BL Address of buffer on the tail of the chain
01 W Q$TS T/S queuing cell for locking during chain manipulation
02 H1 Q$RET Return save cell
H2 Q$CUR Current number of buffers chained
03 H1 Q$MAXN Maximum number of buffers chained
H2 Q$MIN Minimum number of buffers chained
F–14 7833 1568–004

F.5. SLOT
Word Field Name Explanation
04 H1 Q$PS Starting address of this pool
H2 Q$PE Address of the last buffer in the pool
05 H1 Q$SIZ Size of the buffers in this pool
H2 Unused
Data Structures
All MCB message processing requires an activity control table called a SLOT. The SLOT
is created when an activity makes an initialization function call to the MCB, and it remains
attached to the activity until it terminates with the MCB, at which point the SLOT is
released.
The SLOTs reside in MCBBNK unless you are using the multiple SLOT bank feature. In
the latter case, the SLOTs reside in the SLOT banks and MCBBNK contains a 2-word
SLOT header (SLOTH) corresponding to each SLOT. Figure F–13 shows the SLOT
header. (Five SLOTs reserved for the MCB background run reside in MCBBNK in either
case. The background run SLOTs are not counted in SLT$NUM.)
00 SH$STAT SH$BNKNUM SH$SLOT
01 SH$PIDX SH$SWL
Figure F–13. SLOT Header
Word Field Name Explanation
00 S1 Not used.
S2 SH$STAT Status bits for S$SLOTH and SLOT:
SH$CMS (02)
• SLOTH belongs to a CMS caller (duplicates S$CMS).
SH$ATC (04)
• Type 017 contingency has occurred (replaces S$ATC).
SH$BDR2 (010)
• Current call bases SLOT on BDR2.
S3 SH$BNKNUM Logical bank number of SLOT
H2 SH$SLOT Address of SLOT
01 H1 SH$PIDX Replaces S$PIDX
H2 SH$SWL Duplicates S$SWL
The MCB bank descriptor index (BDI) is used as the activity identifier for TRMRG$
registration and the SLOT pointer is passed as user information. The SLOT contains the
7833 1568–004 F–15

Data Structures
activity's switch list (SWL) address. This provides the activity SLOT-TRMRG$
associations for all MCB processing. The SLOT is shown in Figure F–14.
00 Q$FL Q$BL
01 Q$TS
02 Q$RET Q$SCUR
03 Q$MAXN Q$MIN
04 0 S$PMODE S$COB S$SWL
05 S$PID S$OMN
*05 S$PMN
06 S$TD
*06 S$STID
07 S$SEQ S$STEP
010 S$ST
*010 S$A0
011 S$LIJRET
012 S$DRET S$START
013 S$OFF S$VERS S$FLAGS
014 S$LEN S$BUFF
*014 S$ACW
015 S$BDI2 S$BDI1
*015 S$BDI
016 S$BITS
017 S$STAT S$LMFC S$CMERR S$PRCC
*017 S$BANKSAV S$PORCC S$PIRCC
020 S$TRACE (word 1)
021 S$TRACE (word 2)
022 S$PRIM
023 S$X8
024 S$X9
025 S$X10
026 S$SKIP S$STAT2 S$USECBN reserved S$CMSN
F–16 7833 1568–004

027 S$PROG S$PIDX
*027 S$SLOTH
030 S$RUNID
031
…
036
031
…
037
035
…
046
042
…
052
053
051
…
053
054
…
057
61
61
…
0101
SLOT extension area (see F.5.2)
AUDIT$ packet (see F.5.1)
(partially overlays SLOT extension area)
QI$CON/QI$NIT pcket
(partially overlays AUDIT$ packet)
TIP$XMIT (see F.5.4) or DM$IOW packet (see F.5.3)
(partially overlays QI$CON/QI$NIT packet)
Network Database Server EOS code save area
VINDEX table item save
(partially overlays TIP$XMIT or DM$IOW packet)
S$REGSAV register save area
S$UAREA User definable save area.
Data Structures
The size of this area is defined by the optional SLT$USIZE SGS.
This area is present only if SLT$USIZE is specified.
Copy of EM caller’s interface packet (see Figure F–1) present
only if EXTENDEDMODE = YES in configuration
Figure F–14. SLOT
7833 1568–004 F–17

Data Structures
Word Field Name Explanation
00 H1 Q$FL Forward link.
H2 Q$BL Backward link.
If free, a SLOT points to itself. If in use, a SLOT either points
to itself or the first MAD in the chain.
If free, a SLOT points to itself. If in use, a SLOT either points
to itself or the last MAD in the chain.
01 W Q$TS T/S cell for chaining MADs to or removing MADs from SLOT
(zero indicates SLOT not in use.)
02 H1 Q$RET Return link for chaining to a SLOT.
H2 Q$CUR Current number of MADs chained off a SLOT.
03 H1 Q$MAXN Maximum number of MADs chained off a SLOT.
H2 Q$MIN Lowest number of MADs chained off a SLOT.
04 S2 S$PMODE Originator’s program mode.
S3 S$COB COBOL flag (primitive interface only).
H2 S$SWL Originator’s switch list (SWL), which provides a unique identity
for each user of the MCB.
05 W S$PMN Originator’s PID/MSG number.
H1 S$PID Originator’s PID.
H2 S$OMN Originator’s message number.
06 W S$STID Originator’s step identifier.
W S$TD Originator’s time and date.
07 H1 S$SEQ Originator’s sequence number.
H2 S$STEP Originator’s step number.
010 W S$A0 Caller’s A0 (request packet address).
H1 S$ST Caller’s request status.
011 W S$LIJRET Return address to external MCB caller.
012 H1 S$DRET Return address to internal caller.
H2 S$START Caller’s requested position to start data manipulation within
the message.
013 Q1 S$OFF Number of quarters from S$BUFF to start data manipulation.
Q2 S$VERS Packet version in use by this activity.
F–18 7833 1568–004

Word Field Name Explanation
013 H2 S$FLAGS Flags from the request packet (P$FLAG):
S$LBI (01)
• Last block indicator.
S$SOS (02)
• Start a step with no message.
Data Structures
S$RLSE (04)
• Release if a nonrecoverable message and at end of
message.
S$MLH (010)
• Only queue to one member of a group.
S$PST (020)
• Create post-processing message when this message is
acknowledged by CMS (see S$TC1 and S$TC2 in the
extension, Figure F–16).
S$RECOPT (040)
• Use the user-defined recovery options.
S$MODE (0100)
• Change the mode of this transaction or PID.
S$CMAD (0200)
• Apply operation to current message.
S$ADV (0400)
• Step advance on commit.
S$TRM (01000)
• Step terminate on commit.
S$RSM (02000)
• Step resume on rollback.
S$RQUE (04000)
• Step requeue on rollback.
S$RECV (0400000)
• Recoverable message output indicator for CMS.
S$ERRQ (010000)
• Rollback queue to error program.
S$CVL (020000)
• Input PID in conversational mode.
S$SCRN (040000)
• P$SAVE value in packet.
S$TXN (0100000)
• Transaction code presented as first character in text.
S$AUXR (0200000)
• Replace auxiliary data area.
7833 1568–004 F–19

Data Structures
Word Field Name Explanation
014 W S$ACW Access control word for LMR and LMW.
H1 S$LEN Logical amount of data to transfer.
H2 S$BUFF Destination or source of data.
015 W S$BDI User’s BDIs.
H1 S$BDI2 BDI of bank from utility D-bank window (BDR 3).
H2 S$BDI1 BDI of bank from UI or MD window (BDR 1 or 2).
016 W S$BITS Processing bits.
017 S1 S$STAT Status of this caller:
S$NPF (040)
• Numbered pass-off.
S$DISR (020)
• Discrete receive function.
S$LBW (010)
• Last block write.
S$ATC (004)
• Abnormal termination.
(Replaced by SH$ATC, see SH$STAT, for multiple SLOT
banks .)
S$CMS (002)
• CMS activity.
(See also SH$CMS, in SH$STAT.)
S$DIS (001)
• Disconnect at termination.
F–20 7833 1568–004

Word Field Name Explanation
017 S2 S$LMFC Logical message handler function code:
NOSCH (01)
• Normal LMW entry with a core buffer.
CLMW (02)
• Recursive call on LMW.
Data Structures
FBU (03)
• MCA requires updating before scheduling but is in current
main storage buffer.
IBWENT (04)
• Finish simple message (one call, one block).
AUXRW (05)
• Rewrite auxiliary data.
LMWFNC (06)
• Last LMW function.
PMOR (06)
• Recursive LMR call.
MUPD (07)
• MAD requires updating. Return here after obtaining first
block in MR.
SHRTCL (010)
• Short calculation.
017 S3 S$CMERR Code for error notification.
017 S3 S$BANKSAV Save CORBNK number over some primitive calls.
017 H2 S$PRCC Default recovery options.
017 S4 S$PORCC Output recovery options (original).
017 S5 S$PIRCC Input recovery options (original).
020 W S$TRACE Trace, word 1.
021 W S$TRACE Trace, word 2.
022 W S$PRIM Working storage (primitive use only).
023 W S$X8 Save area (X8) (primitive use only).
024 W S$X9 Save area (X9) (primitive use only).
025 W S$X10 Save area (X10) (primitive use only).
7833 1568–004 F–21

Data Structures
Word Field Name Explanation
026 Q1 S$SKIP Offset to transaction code in input message (primitive use
only) .
026 Q2 S$STAT2 Additional status bits for this caller:
S$BG (0400)
• Background run activity.
S$EM (0200)
• Extended mode caller.
S$LOW (0100)
• System low.
S$HIGH (040)
• System high.
S$USEPRIM (020)
• Primitive caller.
S$BNKSEL (010)
• Core bank selected.
026 S4 S$USECBN Location of the core bank number of the message being
processed that is associated with the SLOT activity.
026 S6 S$CMSN CMS number.
027 H1 S$PROG Program number, if any, from the input message.
H2 S$PIDX PID index for outbound open sessions.
(Replaced by SH$PIDX for multiple SLOT banks.)
H2 S$SLOTH Address of corresponding SLOT header.
030 W S$RUNID Program run-id.
F.5.1. AUDIT$ Packet
The AUDIT$ packet, shown in Figure F–15, contains audit trail information. It overlays the
SLOT extension area.
00 reserved A$PTID reserved
01 reserved
02 reserved
03 A$PSTS A$PFN reserved
04 A$ACWLST
06 A$ACW1
07 A$ACW2
Figure F–15. Audit$ Packet
F–22 7833 1568–004

Word Field Name Explanation
00 S3 A$PTID Audit number (application number)
03 S1 A$PSTS Audit status
S2 A$PFN Audit function (GW$)
04 W A$ACWLST ACW list (points at S$APKT+5)
Data Structures
05 W A$ACW1 AUDIT header ACW (points at the AUDIT header in the MAD
for message AUDITs—(MA$AHDR))
06 W A$ACW2 ACW pointing to the text to AUDIT
F.5.2. SLOT Extension Area
The SLOT extension area, shown in Figure F–16, contains information about messages.
It may be overlaid by the AUDIT$ packet.
00 S$INTRTN A$PTID S$CBCTL
*00 S$SESSTAT S$CMSREJ
01 S$MIDSAV
02 S$UPID unused S$AUXO S$AUXL
03 S$MIDCB S$FN
*03 S$TC1
*03 S$QID
*03 S$MID
04 S$TC2 S$MDL
05 S$MN
*05 S$OUTQ S$UREC S$UMODE S$TYPE
*05 S$OUTFN S$OUTSUB S$OUTPI
Figure F–16. SLOT Extension Area
Word Field Name Explanation
00 H1 S$INTRTN Internal return address saved across recursive MCB calls
Q1 S$SESSTAT Session status function returned by CMS
Q2 S$CMSREJ Last CMS number tried on session open
H2 S$CBCTL Buffer control address saved by DQMIC
01 W S$MIDSAV Save area for MID on auxiliary rewrite
7833 1568–004 F–23

Data Structures
Word Field Name Explanation
02 H1 S$UPID User specified PID (for store output or store pass-off
functions)
S5 S$AUXO Offset in words from the beginning of the request packet to
the auxiliary information area
S6 S$AUXL Length of the auxiliary information area in words
03 S2 S$MIDCBN Location of the core bank number of the message being
processed
S3 S$FN MRF file number
W S$TC1 ASCII transaction code (Part 1)
W S$QID Queue item identifier (CMS receive output message)
W S$MID MRF identifier of the message
04 H1 S$TC2 ASCII transaction code (Part 2)
H2 S$MDL Address of the multidestination list
05 H1 S$MN Input message number
H1 S$OUTQ Output message queuing information
S1 S$OUTFN Output queue function
S2 S$OUTSUB Output message queuing subfunction
S3 S$OUTPI Output queue priority
S4 S$UREC User-specified recovery options
S5 S$UMODE User-specified mode
S6 S$TYPE Message type (see MA$TYPE for values)
F–24 7833 1568–004

F.5.3. DM$IOW Packet
Data Structures
The DM$IOW packet, shown in Figure F–17, contains information for Network Database
Server. It partially overlays the QI$CON and QI$NIT packets.
00 DM$FNR
01 unused
02 unused
03 DM$STA DM$FUN
04 DM$WDC DM$BUF
*04 DM$ACW
05 DM$SAD
*05 DM$WRD
06 unused
07 unused
10 DM$RTN/DM$PIX/DM$LNK
*010 DM$LK1
Figure F–17. DM$IOW Packet
Word Field Name Explanation
00 W DM$FNR Network Database Server file number
03 S1 DM$STA Error status
S2 DM$FUN Network Database Server function code
04 W DM$ACW Network Database Server I/O access word
H1 DM$WDC Word count
H2 DM$BUF Buffer address
05 W DM$SAD Sector address in file
S1 DM$WRD Word read indicator
010 W DM$RTN Save return for MRF$00 I/O
W DM$PIX PIX word read up
W DM$LNK Read up overflow on mass storage
H2 DM$LK1 Link word area
7833 1568–004 F–25

Data Structures
F.5.4. TIP$XMIT Packet
The TIP$XMIT packet, shown in Figure F–18, contains TIP security information. It partially
overlays the QI$CON/QI$NIT packet.
00 TXM$STATUS TXM$AKSTAT TXM$FUNC TXM$APNBR 0 TXM$PKTVER
01 TXM$DESTPID TXM$SESID
02 TXM$APNAM1
03 TXM$APNAM2 0
04 TXM$OMSGNBR TXM$OPID
05 TXM$MRFID
06 TXM$QID TXM$MSGNUM
07 TXM$STID (word 1)
010 TXM$STID (word 2)
Figure F–18. TIP$XMIT Packet
Word Field Name Explanation
00 S1 TXM$STATUS Status
S2 TXM$AKSTAT ACK Status
S3 TXM$FUNC Function code
S4 TXM$APNBR Application number
S6 TXM$PKTVER Packet version
01 H1 TXM$DESTPID Destination PID
H2 TXM$SESID Session-id
02 W TXM$APNAM1 Application name (first 4 characters)
03 H1 TXM$APNAM2 Application name (last 2 characters)
04 H1 TXM$OMSGNBR Original message number
H2 TXM$OPID PID of origin
05 W TXM$MRFID MRF-id
06 H1 TXM$QID Queue item address
H2 TXM$MSGNUM Message number 07
07 W TXM$STID Step-id, word 1
010 W TXM$STID Step-id, word 2
F–26 7833 1568–004

F.6. MRF Allocation Descriptor (MAD)
Data Structures
A MAD, shown in Figure F–19, exists for each message built or read by the MCB. The
MAD tables are linked off the SLOT of the activity that is building or reading the
message. MADs exist only for the period of time a particular message is accessed by the
MCB. Each MAD contains control information for handling its associated message, such
as the current logical address within the message.
00 MA$FL MA$BL
01 MA$CBP MA$NDX MA$MCMS MA$ERR
02 MA$SM1
03 MA$SM2
04 MA$SM3
05 MA$SM4
06 MA$PID MA$MN
07 MA$ATYP MA$ASTYP MA$AHL MA$QID or MA$ARECSIZ
*07 MA$AHDR
010 MA$STID (word 1)
011 MA$STID (word 2)
012 MA$SLOT MA$RCC MA$AUDNO MA$TYPE
013 MA$CMID
014 MA$MID1
015 MA$CURPOS MA$CUMCNT
*015 MA$DATA
016 MA$FLAG MA$FN MA$CYC MA$CBC
017 MA$TXN
*017 MA$HDR
020 MA$CAHDR reserved MA$AU
021 MA$TS
Figure F–19. MRF Allocation Descriptor
7833 1568–004 F–27

Data Structures
If the MAD is associated with a nonrecoverable message, words 02 through 05 have a
different format:
MA$MID2 MA$MID3
MA$MID4 MA$MID5
MA$MID6 MA$MID7
MA$MID8 MA$MIDOVF
Word Field Name Explanation
00 H1 MA$FL Forward link to next free MAD, if available, or link to next
MAD chained off of this SLOT
H2 MA$BL Backward link to prior free MAD, if available, or link to prior
MAD chained off of this SLOT
01 H1 MA$CBP Pointer to main storage buffer presently or removes, on
writes, previously chained to this MAD
S4 MA$NDX SAM index to next available segment allocation mask (SAM)
entry
S5 MA$MCMS The CMS number destination of a ROPL output message
S6 MA$ERR Error code for error notification program
02 W MA$SM1 SAMs for this recoverable message
03 W MA$SM2
04 W MA$SM3
05 W MA$SM4 Link to overflow block if nonzero
02 H1 MA$MID2 MIDs for this nonrecoverable message
02 H2 MA$MID3
03 H1 MA$MID4
03 H2 MA$MID5
04 H1 MA$MID6
04 H2 MA$MID7
05 H1 MA$MID8
05 H2 MA$MIDOVF Zero or link to overflow chain of blocks
06 H1 MA$PID PID for this message
H2 MA$MN Message number for this message
F–28 7833 1568–004

Word Field Name Explanation
07 W MA$AHDR AUDIT header for this message
S1 MA$ATYP AUDIT record type (021)
S2 MA$ASTYP AUDIT record subtype:
AT$MCA (01)
• Message control area (MCA) block
AT$OVFLO (02)
• Overflow block
Data Structures
AT$HDR (03)
• Message retention files (MRF) control file header audit
subtype
AT$SEG (04)
• Segment control audit
AT$SEGIPT (06)
• MRF controls after idle point
AT$TQERR (07)
• TIP$Q error audit record subtype
S3 MA$AHL Audit header length
H2 MA$QID Queue item-id (output message only)
H2 MA$ARECSI
Z
Audit record size
010 W MA$STID Step identifier (2 words)
012 H1 MA$SLOT Address of SLOT to which this MAD is attached
S4 Address of
SLOT to
which this
MAD is
attached
Recovery options for this message:
MA$LCP (040)
• Low core priority
MA$RET (020)
• Retrievable message
MA$NUM (010)
• Message to be numbered
MA$AUD (004)
• Audit the message text
MA$RECV (002)
• Recoverable message
MA$DEF (001)
• Deferred message
7833 1568–004 F–29

Data Structures
Word Field Name Explanation
S5 MA$AUDNO AUDIT application number
S6 MA$TYPE Message type:
MT$NET (01)
• Input message
MT$CHK (02)
• Checkpoint message
MT$PAS (03)
• Pass-off message
MT$OP (04)
• Output message
MT$PUT (05)
• Text stored by CMS Put Text function
013 W MA$CMID MRF identifier of the current main storage buffer (Buffer
pointed to by MA$CBP should contain this MID.)
014 W MA$MID1 MRF identifier of block 1 of this message
015 W MA$DATA Count data for this message
H1 MA$CURPOS Current position pointer
H2 MA$CUMCNT Cumulative data count for this message
016 H1 MA$FLG Flags associated with this MAD:
MA$SDM (0400000)
• Single destination message
MA$NCF (0200000)
• Network control function
MA$ACK (0100000)
• Acknowledge message requested
MA$REC (0040000)
• Receive-only flag
MA$RDL (0020000)
• Redelivered message flag
MA$OH (0010000)
• Output header required for this message
MA$ALT (0004000)
• Alternate delivery flag for output header
MA$MLH (0002000)
• Rotary output
MA$RCL (0000400)
• Input PID PIX flag
F–30 7833 1568–004

Word Field Name Explanation
MA$CMS (0000200)
• Flag for IMA
MA$AUDFLG (0000100)
• First audit flag for long recovery
MA$TMA (0000040)
• TMA error flag
MA$CB (0000020)
• First CB acquired
MA$MCACK (0000010)
• Check the MCA block
MA$MS (0000004)
• Mass storage read indicator
MA$CBRD (0000002)
• Read MCA on CMSACK
MA$MULTI (0000001)
• Multiactivity MAD
Data Structures
S4 MA$FN Relative MRF file number for MA$CMID and MA$MID1
016 S5 MA$CYC MCA block cycle number
S6 MA$CBC Cycle of current block
017 Q1 MA$TXN Transaction code offset
W MA$HDR Save area for output header routines
020 Q1 MA$CAHDR Size in words of area occupied by the auxiliary information
area, the multidestination list, or both
H2 MA$AU Assurance unit for input messages
021 W MA$TS MAD test-and-set cell for multiactivity message locking
7833 1568–004 F–31

Data Structures
F.7. Position Identifier (PID)
The MCB information about PIDs is contained in tables in the PID$BNKn common banks.
The following sections describe the table entries for PIDs and group PIDs. The location of
the entry for a PID is found in the directory located in the RNG$BNKn common banks.
The directory has the format shown in Figure F–20:
00 reserved MR$CRNG
01 MF$RBDI MF$RADR
02 MF$BHIGH MF$BLOW
03 MF$HIGH MF$LOW
04 MF$BDI MF$ADR
Words 3 and 4 repeated according to the number of PID ranges in configuration.
Figure F–20. RNG$BNK Directory
Word Field Name Explanation
00 H2 MF$CRNG The number of range table entries in the current range table
common bank
01 H1 MF$RBDI The BDI for the next range table common bank
H2 MF$RADR The address of the range table common bank
02 H1 MF$BHIGH The highest PID number in the current range table common
bank
H2 MF$BLOW The lowest PID number in the current range table common
bank
03 H1 MF$HIGH The highest PID number in this range table entry
H2 MF$LOW The lowest PID number in this range table entry
04 H1 MF$BDI The BDI for the PID table comon bank that contains the PID
entries for this range table entry
H2 MF$ADR The address of the first PID entry for this PID range
F–32 7833 1568–004

F.7.1. PID Entry
Figure F–21 describes the table entries for a PID.
00 MF$TS
*00 MF$TSFLAG
Data Structures
01 MF$FLG MF$IMR MF$CMS MF$TCC
02 MF$FLG MF$OMR reserved
03 MF$CVL MF$XCVL
04 MF$TXN MF$PROG
05 MF$IMW MF$OMW
06 MF$IFO MF$OFO
Figure F–21. PID Entry
Word Field Name Explanation
00 W MF$TS Test-and-set (TS) cell
S3 MF$TSFLAG User area of TS cell
01 H1 MF$FLG PID flags:
MF$RPID (01)
• This is a real PID entry as opposed to a group
PID entry
MF$GPID (02)
• This is a group PID entry
MF$SACK (04)
• Unintelligent input numbering
MF$PIX (010)
• PIX file I/O desired
MF$NUM (020)
• Message numbering desired
MF$OH (040)
• Unintelligent output numbering
MF$INTEL (0100)
• Intelligent message numbering
MF$EXCL (0200)
• Exclusive use
MF$IMC (0400)
• Input message control
7833 1568–004 F–33

Data Structures
Word Field Name Explanation
MF$TRAIN (01000)
• Training mode
MF$TEST (02000)
• Test mode
MF$PSTPRC (04000)
• Delivery notification requested
MF$XNOT (010000)
• Exclusive use notification
MF$OUTOPN (020000)
• Outbound open
MF$OMC (040000)
• Output message control
MF$IPEXCL (0200000)
• Input only exclusive use
MF$ILK (0400000)
• Input locked out
01 S4 MF$IMR Relative MRF file number for input, pass-off, and checkpoint
messages
S5 MF$CMS CMS number with which a session is opened
S6 MF$TCC Terminal class
02 H1 MF$SCRN Value for P$SAVE
S4 MF$OMR Relative MRF file number for output messages
03 H1 MF$CVL Program number for conversational link
H2 MF$XCVL Program number for exclusive use
04 H1 MF$TXN Program number of session owner
H2 MF$PROG Program number of exclusive use owner
05 H1 MF$IMW Input PIX message wrap size
H2 MF$OMW Output PIX message wrap siz
06 H1 MF$IFO Input offset into PIX for this PID
H2 MF$OFO Output offset into PIX for this PID
Note: If no PIX files are configured, words 5 and 6 do not exist.
F–34 7833 1568–004

F.7.2. Group PID Entry
Figure F–22 describes the table entries for a group PID.
00 MF$TS
*00 MF$TSFLAG
01 MT$FLG MF$PNT
Data Structures
02 MF$NXT MF$OMR reserved
03 MF$GPBDI reserved
04 reserved
05 reserved
06 reserved
Figure F–22. Group PID Entry
Word Field Name Explanation
00 W MF$TS Test-and-set (TS) cell
S3 MF$TSFLAG User area of TS cell
01 H1 MF$FLG MF$GPID is the only valid PID flag value (see F.7.1)
H2 MF$PNT Address of the entry in MF$GPD defining the members of this
group PID (see F.7.3)
02 H1 MF$NXT Next PID for rotary output
S4 MF$OMR See F.7.1
03 H1 MF$GPBDI The BDI of the common bank where this group PIDs list of
real PID numbers can be found
Note: If no PIX files are configured, words 5 and 6 do not exist.
7833 1568–004 F–35

Data Structures
F.7.3. Group PID Table
The group PID table, shown in Figure F–23, contains a variable length entry for each
group PID.
00 number of real PIDs PID
01 PID PID
02 PID 0/
(If even number of PIDS in group)
03 number of real PIDs PID
04 PID PID
05
..
..
F.8. PID Index File (PIX)
Figure F–23. Group PID Table
PIX files provide message recall. Since an entire message is linked together, it can be
retrieved by locating only the first block. The first block is located using the MRF
identifier (MID). To recall a message, the originating and destination PID must be
associated with an MRF that has an associated PIX file.
These associations are created at system generation time, using the P$ID and M$FILE
statements. Therefore, an area is dedicated in the PIX file for each PID, based on the
configuration. The size of the area set aside is also based on the configuration. It should
be noted that each PID can recall a different maximum number of messages. This is
called the message wrap size. This mechanism is controlled in the MCB by the PID entry
table. One entry per PID contains both a message wrap size and the file offset into the
PIX file for input and output. The associated MRF file numbers for input and output also
exist there (see F.7.1). The PID and the message number are the only information
necessary to recall the desired message. The requested message number is divided by
the wrap size and the resulting remainder is the relative offset into the area set aside for
this PID. Using this calculated offset, plus the file offset, the 1-word MID entry is read. If
the MID does not identify the proper MCA block, the MRF file has wrapped and the
message is no longer retrievable.
F–36 7833 1568–004
...
...

F.9. Statistics Table (ST$TBL)
Data Structures
The statistics table, shown in Figure F–24, collects information about MCB operations.
00 STMCBID
01 STATSON STTBSZ
02 STMBDI STMBSZ
03 STDIR STUDBASE
04 STCMSN reserved
05
STGENID
010 reserved
011 reserved
012 reserved
013 reserved
014 reserved
015 STCBPLF STCBPLA
016 STSLTS STMADS
017 STMSGI
020 STMSGO
021 STMSGC
022 STMSGP
023 STROPLO
024 STCBAS
025 STCBRL
026 STOHPB 0
027 STCBNR
030 STADTW
031 STSEGW
032 STUSER
033 STNOMSG
034 STCMAI
035 STCMCN
7833 1568–004 F–37

Data Structures
036 STCMRQ
037 STCMAK
040 STCMNA
041 STBRMR
042 STTXIN
043 STCMST
044 STTSEN
045 STTPAS
046 STTCHK
047 STTENQ
050 STTREC
051 STMISC
052 STMRFR
053 STMRFW
054 STSAM4
055 STMRF (1)
..
055+N STMRF (N)
Figure F–24. Field Definitions (EQUF) for Statistics
F–38 7833 1568–004
...

Name Word/Field Description
STMCBID 0,,W MCB internal identifier.
STATSON 1,,H1 Value 1 = MCB statistics ON
Value 0 = MCB statistics OFF
STTBSZ 1,,H2 Fixed table size in words
Data Structures
When value = 0, words 0 through 016 only are used
STMBDI 2,,H1 Main MCB bank BDI (MCBBNK)
STMBSZ 2,,H2 Main MCB bank size in words
STDIR 3,,H1 Directory address
STUDBASE 3,,H2 Configured UDBASE
STCMSN 4,,H1 CMS number used by the MCB (MCBNUM)
reserved 4,,H2
STGENID 5,,W - 7,,W COMUS generation identifier
reserved 010,,W - 014,,W
STCBPLF 015,,H1 Free core buffer control address
STCBPLA 015,,H2 Active control buffer address
STSLTS 016,,H1 SLOT control address
STMADS 016,,H2 MAD control address
STMSGI 017,,W Number of CMS input messages
STMSGO 020,,W Number of output messages
STMSGC 021,,W Number of checkpoint messages
STMSGP 022,,W Number of pass-off messages
STROPLO 023,,W Number of ROPL output messages
STCBAS 024,,W Number of main storage buffer assignments
STCBRL 025,,W Number of main storage buffer releases
STOHPB 026,,H1 Active chain overhead I/O for nonrecoverable full buffers
and all partial buffers
STCBNR 027,,W Number of messages found in main storage buffers
rather than MRF
STADTW 030,,W Number of audit trail requests
STSEGW 031,,W Number of MRF control writes
STUSER 032,,W Number of user errors detected
STNOMSG 033,,W Number of no input message errors
STCMAI 034,,W Number of CMS initializations
STCMCN 035,,W Number of CMS input message cancels
STCMRQ 036,,W Number of CMS output message requeue
7833 1568–004 F–39

Data Structures
Name Word/Field Description
STCMAK 037,,W Number of CMS acknowledgments
STCMNA 040,,W Number of CMS negative acknowledgments
STBRMR 041,,W Number of MRF space releases
STTXIN 042,,W Number of transaction initializations
STCMST 043,,W Number of CMS message store functions
STTSEN 044,,W Number of send output message functions
STTPAS 045,,W Number of pass-off input message functions
STTCHK 046,,W Number of send checkpoint message functions
STTENQ 047,,W Number of enqueue message functions
STTREC 050,,W Number of message receive functions
STMISC 051,,W All other functions
STMRFR 052,,W Number of message block reads
STMRFW 053,,W Number of recoverable MRF writes
STSAM4 054,,W Number of times fourth SAM is used
STMRF 055,,W Start of write counters for each (N) MRF file
F–40 7833 1568–004

Appendix G
MCB Open Look
MCB Open Look applies the software engineering concepts of reusability, modularity,
information hiding, and data abstraction. Open Look allows you to write MCB application
programs in a particular UCS language without having to tailor that language to a specific
MCB application environment. A program can call an MCB library of functions in a native
language, thereby simplifying the writing of the program. This function library, which can
be edited, contains functions tailored for the specific application environment in which
the program runs.
Unisys provides the function library in the MCB installation file with element name
UCMCBLIB. You can edit this file in this library to suit your site needs. An example of
linking commands is provided in element UCLINK.
Figure G–1 illustrates the relation between a program written in C and its calls to
functions in the UC function library.
7833 1568–004 G–1

MCB Open Look
C language
program call
(includes files
copied from
the release
tape)
Function
called in UC
function
library
#include /* MCB packet definition */
#include
#include
#include
#include
main()
{
status = 0;
number_of_chars = 5000;
/* */
status = read_message(&number_of_chars, &chars_read, text_area, &pid);
if (status != 0)
{
printf("Bad MCB status on message read: %o\n",status);
}
.
.
.
/* */
/************************************************************************/
/* READ MESSAGE */
/************************************************************************/
/* */
int read_message (int *bytes_to_read, int *bytes_read,
char *message_buffer, int *message_address)
{
_mcb_packet_type mcbpkt;
int mcb_status;
/* */
zero (20,&mcbpkt);
/* */
mcbpkt.mcb_std_pkt.p_length = *bytes_to_read;
mcbpkt.mcb_std_pkt.p_func = TRINIT$$;
mcbpkt.mcb_std_pkt.p_aux = 63;
mcbpkt.mcb_std_pkt.p_flags = 4;
/* */
mcb_ent (&mcbpkt, &mcb_status, message_buffer);
/* */
*message_address = mcbpkt.mcb_std_pkt.p_pid;
*bytes_read = mcbpkt.mcb_std_pkt.p_ml;
*bytes_to_read = mcbpkt.mcb_std_pkt.p_length;
/* */
return mcb_status;
}
/* */
Figure G–1. Example of C Language Call to UC Function Library
To run the program in a particular application environment, an executable zoom needs to
be created by statically linking these files:
• The file of the compiled program to the file of the compiled function library
• The file of the compiled function library to the MCB application group.
Figure G–2 shows the files linked as an executable zoom.
The program you are compiling from must contain the files required to run as an Open
Look program. Before compiling and linking a program as an executable ZOOM, you
G–2 7833 1568–004

MCB Open Look
must copy these files from either the utility file on the release tape or the installed MCB
files. The C language call in Figure G–1 shows the required files copied into the program.
Program
(EXAMPLE-UC)
Static Link
MCB Function
Library
(UCMCBLIB)
Static Link
Executable ZOOM
Figure G–2. Structure of an MCB Open Look Executable ZOOM
MCB application
group linked to
library search chain
(sys$lib$*app$N)
7833 1568–004 G–3

MCB Open Look
G–4 7833 1568–004

Appendix H
Related Product Information
Application Development Solutions Application Development Programming Guide
(7831 4077). Unisys Corporation.
Application Development Solutions C Compiler Programming Reference Manual Volume
1: C Language and Library (7831 0422). Unisys Corporation.
Application Development Solutions C Compiler Programming Reference Manual Volume
2: Compiler and System Interface (7831 0430). Unisys Corporation.
Application Development Solutions COBOL Compiler Programming Reference Manual
Volume 2: Compiler and System Interface (7831 0455). Unisys Corporation.
Application Development Solutions FORTRAN Compiler Programming Reference Manual
Volume 1: FORTRAN Statements (7831 0489). Unisys Corporation.
Application Development Solutions FORTRAN Compiler Programming Reference Manual
Volume 2: Compiler and System Interface (7830 7477). Unisys Corporation.
ClearPath Enterprise Servers Security Administration for ClearPath OS 2200 Help
(7862 1760). Unisys Corporation.
Enterprise Network Database Server for ClearPath OS 2200 Administration and Support
Guide (7830 7568). Unisys Corporation.
OS 2200 Communications Management System (CMS 1100) Operations Reference
Manual (7831 5694). Unisys Corporation.
OS 2200 Communications Management System (CMS 1100) Programming Reference
Manual (7831 5827). Unisys Corporation.
OS 2200 Exec System Software Administration Reference Manual (7831 0323). Unisys
Corporation.
OS 2200 Exec System Software Executive Requests Programming Reference Manual
(7830 7899). Unisys Corporation.
OS 2200 Exec System Software Installation and Configuration Guide (7830 7915). Unisys
Corporation.
OS 2200 Integrated Recovery System Conceptual Overview (7830 8186). Unisys
Corporation.
7833 1568–004 H–1

Related Product Information
OS 2200 Message Control Bank (MCB) Administration and Operations Guide
(7833 1550). Unisys Corporation.
Previously titled and numbered OS 2200 Message Control Bank (MCB) Installation Guide
(7430 0476) and OS 2200 Message Control Bank (MCB) Operations Reference Guide
(7833 1550).
OS 2200 Meta-Assembler (MASM) Programming Reference Manual (7830 8269). Unisys
Corporation.
OS 2200 Partitioned Applications Conceptual Overview (7831 0927). Unisys Corporation.
OS 2200 Partitioned Applications Planning, Installation, and Operations Guide
(7831 0935). Unisys Corporation.
OS 2200 Transaction Processing Administration and Operations Reference Manual
(7830 7881). Unisys Corporation.
OS 2200 Transaction Processing Programming Reference Manual (7830 7402). Unisys
Corporation.
OS 2200 Universal Compiling System (UCS) COBOL Programming Reference Manual
Volume 1, COBOL Statements (7831 0448). Unisys Corporation.
H–2 7833 1568–004

Glossary
A
access control word (AWC)
An ACW describes the location and length of data.
acknowledgment (ACK)
A system response, expressed as ACK, that indicates to the sender of a message that
the message was received. Compare with negative acknowledgment.
action code
See transaction code.
activity
ACW
AFCB
The basic entity in a multiprogramming environment, as implemented on OS 2200 hosts
(see SWL).
See access control word.
See alternate file common bank.
alternate file common bank (AFCB)
A non-Exec component of Partitioned Applications that lets components such as
Message Control Bank (MCB) and UDS register, send heartbeats to the monitor run, and
deregister with the Partitioned Applications system through the application interface bank
request packet. The AIB, along with the monitor run, forms the Automatic Recovery of
Components (ARC) feature. In other contexts, AFCB is a bank you can install or update
after system generation and library boot and that several programs can share
simultaneously.
application group
An integrated recovery entity that consists of a database, an audit trail, a data dictionary
(optional), and message retention files (optional). Integrated recovery is provided only for
users of an application group. Multiple application groups can be configured on one host.
7833 1568–004 Glossary–1

Glossary
B
backup host
A host that is not actively connected to a shared application group until a system failure
occurs on the production host. When this happens, the Partitioned Applications software
installed on the backup host attaches the backup host to the application group and also
recovers the failing host. The backup host takes over for the failed host as soon as the
application group is successfully attached. The backup host can process non-shared
batch and demand programs while the production host of a Partitioned Applications
system is running.
bank descriptor index (BDI)
An index into the bank descriptor table (a data structure defined by the Exec). Practically,
BDIs are the equivalent of symbolic bank names. Program BDIs are assigned by the
Collector, whereas configured common bank BDIs are managed by the Exec, COMUS,
and the systems analyst.
bank descriptor register (BDR)
One of four registers that specify the upper and lower relative address limits and the
base address of the bank.
BATCH-CONECT
A TIP program type. Programs of this type are scheduled by way of the normal Exec
@XQT command. They gain access to TIP facilities by ”connecting” to the online system
by way of the CONECT primitive.
BDI
BDR
buffer
C
CAT
CCB
See bank descriptor index.
See bank descriptor register.
A storage area in random access memory where a computer temporarily places data until
the data can be transferred to a peripheral device or the next phase of operations. By
removing data from the immediate processing environment, buffers free the computer to
continue processing other data.
Communications Management System (CMS 1100) activity table. An MCB data structure
used as a cross-reference to coordinate message processing by different CMS 1100
activities.
See configured common bank.
CMS 1100
See Communications Management System.
Glossary–2 7833 1568–004

Glossary
Collector
A Unisys system processor that joins relocatable elements into an absolute element.
COMMIT
An action to end a recoverable step; that is, update the database, write updates to the
audit, and forward deferred messages.
Communications Management System (CMS 1100)
The real-time program that interfaces the communications network with the MCB.
CMS 1100 resides on a network host and handles all communications processing
associated with that host.
COMPOOL
Communications Message Pool; an OS 2200 message-handling component developed
before MCB. COMPOOL does not support integrated recovery of message processing
and data processing.
COMUS
CONECT
An interactive software installation and maintenance program sites used to install
OS 2200 products and Exec features.
The primitive entry point (and element name) used to provide batch programs an access
to TIP facilities.
configured common bank (CCB)
A common bank whose template resides on the operating system boot tape.
D
DAP
Abbreviation for Dump Analysis Procedures.
Data Manipulation Language (DML)
A standardized programming language used with data management software such as
Network Database Server.
DCA
DID
See Distributed Communications Architecture.
A device identifier, or device index.
Display Processing System (DPS 2200)
A software product for OS 2200 systems that provides terminal presentation control for
application programs.
Distributed Communications Architecture (DCA)
The logical communications network structure supported by CMS 1100 software on
2200 Series systems and OS 2200 systems.
7833 1568–004 Glossary–3

Glossary
DML
DPS
E
ER
F
FIFO
See Data Manipulation Language.
See Display Processing System.
Abbreviation for Executive request (ER).
Acronym for first in, first out.
FILESETUP
An absolute element that catalogs and registers MCB files.
G
GN file
H
host
A utility file that contains elements of released software, to control system generation,
and other elements for site-configuration stream generation statements (SGS).
A medium to large central processor attached to a network. Also referred to as an end
system. The host is generally dedicated to data processing functions, such as executing
application or system programs, rather than data communications functions.
Architecturally, there is no distinction between a DCA host and a DCA terminal, since
both contain a termination system, although of vastly differing powers. In SNA, a host is
defined as an SNA node that contains a PU Type 5. See also backup host, Partitioned
Application host.
host mass storage (HOSTMS)
A process that provides access to mass storage on the OS 2200 host to other network
nodes. Each node can have one or more sessions (logical connections) to the host mass
storage process. One or more files can be in use by each session.
I
initialization
The process of reading a tape containing a database and storing it on disk. This is similar
to loading, except that initialization is done on a newly-installed system.
Glossary–4 7833 1568–004

Glossary
integrated recovery application group
An entity configured by a CMS 1100 APPLICATION network definition statement with an
application number from 1 to 9. This entity is also configured with the Exec and MCB. It
is a TIP-oriented application consisting of an MCB, a set of transaction programs that use
MCB interfaces and step control logic, and a set of VALTABs that specify the
transactions.
integrated recovery system
The combination of OS 2200 features that protects users against the effects of hardware
and software failures. Integrated recovery encompasses the database recovery needs of
the Exec, TIP file control, and Universal Database Control. It also encompasses the
message recovery needs of MCB and CMS 1100. The Exec components of integrated
recovery are step control, audit control, and TIP file control. Integrated recovery
components that are not part of the Exec are IRU, Universal Database Control, and MCB.
IMA
Abbreviation for initial message analysis.
Integrated Recovery Utility (IRU)
A command-driven utility used after a system or application group failure to maintain the
integrity and availability of files, databases, and transaction messages.
IRU
L
See Integrated Recovery Utility.
last block indicator (LBI)
An interface packet flag, located in the P$FLAGS field, that indicates MCB read the last
block of a message.
LBI
LBJ
See last block indicator.
See load bank and jump.
load bank and jump (LBJ)
A hardware instruction that specifies a BDI, a BDR, and an address. LBJ causes a new
bank to be based and program execution to begin at a new memory address.
long recovery
A last-resort Integrated Recovery Utility (IRU) procedure that rebuilds the database from
the after-looks on the audit trail, starting with reloading the most recent database dump
for all steps that were completed before the failure occurred. Long recovery of messages
involves rebuilding the MCB message retention files from the audit trail.
7833 1568–004 Glossary–5

Glossary
M
MAD
MASM
See MRF allocation descriptor. An MCB internal data structure that exists only while a
message is being read or built by MCB. The MAD contains MCB processing information
such as message type, recovery options, SAMs, MID, and audit information for the
current message.
Acronym for Meta-Assembler. The OS 2200 assembly language.
master file directory (MFD)
A directory that resides on local (nonshared) mess storage and contains cataloged files
that can be assigned and accessed only by a particular host. See also SHARED master
file directory.
MCA
MCB
See message control area.
See Message Control Bank.
MCB command
An MCB operations command. Most action commands can be entered either from the
OS 2200 system console or from a privileged network terminal. Some action commands
are restricted to the OS 2200 console only.
message control area (MCA)
An internal data structure built by MCB to retain control information pertinent to a
message during MCB processing. A unique MCA exists for each message until MCB
completes processing of that message.
Message Control Bank (MCB)
A common bank, provided as a separately packaged feature, that works with the Exec to
provide queuing and recovery of input messages to CMS 1100 from user terminals,
pass-off messages between transaction programs, and output messages from the
programs. CMS 1100, TIP file control, and Exec step control use MCB for message
recovery and transaction scheduling. MCB maintains its own message storage area.
message existence time
The time a message resides in the MCB. For an input, this is measured from the time
CMS 1100 starts to store the input to the time the application program releases the
message. For an output, this is measured from the time the application program starts to
store the message to the time CMS 1100 acknowledges successful delivery.
message parameter area (MPA)
The 16-word header of a logical COMPOOL record. It contains information required by
CMS 1100 and TIP to route and process the message.
Glossary–6 7833 1568–004

Glossary
message rate
The number of messages processed divided by some time interval (usually seconds). For
example, if you process 6000 messages over a 60-second period, your message rate is
100 per second.
message recovery
The process of recovering input and output messages from the communications
network. See also long recovery.
message retention file (MRF)
A mass storage file defined by MCB configuration. MCB uses MRFs to store in-process
recoverable messages for recovery in the event of a system failure. MCB can access
multiple MRFs, one of which (MRF 0/ ) can be used as an overflow area for
nonrecoverable messages.
MID
MPA
MRF
See MRF identifier.
See message parameter area.
See message retention file.
MRF allocation descriptor (MAD)
An MCB internal data structure that exists only while a message is being read or built by
MCB. The MAD contains MCB processing information such as message type, recovery
options, SAMs, MID, and audit information for the current message. See also PID index
file (PIX).
MRF identifier (MID)
A one-word unique identifier for each block of a message retention file (MRF). MCB uses
the MID to locate blocks associated with a message.
Multi-Host File Sharing (MHFS)
An Exec feature that allows file sharing between multiple OS 2200 hosts. It associates
the files with a local or shared directory and handles the communications needed for file
sharing across multiple host systems. MHFS is required for interhost recovery in a
Partitioned Applications configuration.
N
negative acknowledgment (NAK)
A system response, expressed as NAK, that indicates to the sender of a message that
the message was not properly received or could not be received. Compare with
acknowledgment (ACK).
NCCB
See nonconfigured common bank.
7833 1568–004 Glossary–7

Glossary
network
A group of hardware and software components that are physically and logically linked,
and that interact according to established protocols. Network functions are determined
by the types of cooperating application systems within the network.
Network Database Server
A software product for OS 2200 systems that provides database control and that may
use the TIP file control component of OS 2200.
nonconfigured common bank (NCCB)
A common bank whose template resides in a user-defined file. The file name is known to
the operating system at system boot time.
O
output transmission time
Output transmission time is the time between the program sending an output message
and CMS 1100’s acknowledgment of delivery.
P
Partitioned Applications
A grouping of software features that extends the availability of 1100 and 2200 Series
hardware and software. Each host functions both as a production host and a backup host
for switchable application groups. Each host has its own set of switchable application
groups running at the same time. If a switchable application group fails, the system
automatically recovers it onto the backup host without interrupting the end user. If a
critical component fails but the host remains up, the system automatically recovers the
component on the same host and processing continues. Partitioned Applications also
allows the operator to switch an application group from the backup host to the host on
which it was originally running without bringing down the host or other application
groups. The Partitioned Applications software features are PAEXEC, ARC, MHFS, and
Unit Duplexing. Beginning with SB4R2, Partitioned Applications replaces Hot-Standby.
Partitioned Applications host
A backup host or a production host in the Partitioned Applications system. Partitioned
Applications is a dual-host system (for example two 1100/92 systems) in which one host
is the production host and the other is a backup host. The backup host can process batch
and demand calls while the production host is running TIP, batch, and demand runs. Each
host has its own operating system, mass storage, and shared mass storage.
PBR
PCF
PCT
See product build routine.
See permanent correction file.
See program control table.
Glossary–8 7833 1568–004

Glossary
permanent correction file (PCF)
A file containing code that is applied to a software component during generation to
permanently correct or upgrade the software.
PID
See position identifier (logical terminal-id).
PID index file (PIX)
A file containing information that MCB uses to recall messages associated with specific
PIDs. The PIX is defined by MCB configuration. See also MRF allocation descriptor.
PIX
PMD
See PID index file.
See postmortem dump.
position identifier (PID)
A numeric identifier that provides the location of terminals in a network. PIDs are known
to both APPs and CMS 1100. Through the use of PIDs, APPs identifies a terminal to
CMS 1100 and vice versa.
postmortem dump
A diagnostic dump created by the operating system when a program aborts or is
otherwise terminated.
primitive
A TIP primitive is an assembler language subroutine written to provide an interface to the
TIP/Exec ERs.
private file
An unowned private file is private by project-id or account number. It may have read/write
keys, or read-only/write-only attributes. An owned private file is private by user-id. The
user-id of the person who cataloged the file (or started a batch run) is required for access
to an owned private file.
product build routine (PBR)
A routine that creates software product generation runstreams.
program control table (PCT)
The PCT is a bank whose data structure is defined, created, and maintained by the
operating system. The PCT contains information about the run.
public file
A public file may be accessed by anyone.
Q
QID
See queue item identifier.
7833 1568–004 Glossary–9

Glossary
queue item identifier (QID)
A unique one-word identifier placed in the CMS 1100 output message queue by Exec
step control to identify a pending output message.
R
recovery
There are several different references to recovery in this manual:
• Database recovery provides auditing and rollback features.
• Recoverable steps are an execution entity to accomplish database recovery.
• Recoverable files are those files that are to be audited and whose updates can be
rolled back.
• System recovery is the recovery of the Exec system.
• Message recovery, supported only by MCB.
See also long recovery.
recovery bank protection
A feature that enables only the Integrated Recovery Utility (IRU) to access the long and
short recovery banks. Recovery bank protection discriminates between various MCB
callers while accessing these banks. This feature is enabled only when common bank
protection is configured (CBSECURITY=YES).
Remote Symbiont Interface (RSI)
The interface employed by communications terminal handler programs whereby input
and output images are exchanged with the operating system to support remote
application programs.
resilient
RL
RSI
S
SAM
Resilient refers to the ability of a software component to recover from a failure within the
system. For example, if the MCB is in a resilient system, PID session information is
saved on mass storage. The information can then be used after a system or component
failure to restore PID sessions and continue network message processing at the point
before the failure.
An Exec system console keyin for reloading a common bank.
See Remote Symbiont Interface.
See segment allocation mask.
Glossary–10 7833 1568–004

Glossary
segment allocation mask (SAM)
An MCB internal data structure that records the block count for each segment used by a
message in a message retention file (MRF).
SEXEM
SGS
The name of the TIP contingency-handling function that produces a program dump.
See stream generation statement.
shared application group
A feature that enables multiple hosts to access an application group to satisfy availability
and capacity requirements. It also enables multiple hosts to process a single application
group simultaneously, thereby increasing the potential system power available to an
application group.
shared file
A file in a Partitioned Applications environment that resides on shared mass storage so
multiple hosts can access it. Each shared file is cataloged in the SHARED master file
directory with a directory-id of SHARED# and a file name syntax of
SHARED*qualifier-filename.
shared mass storage
The mass storage files in a Resilient System configuration that are cataloged in the
shared master file directory so multiple hosts can concurrently access them. Each host
has an independent physical connection to shared mass storage.
SHARED master file directory
An alternative to the STD (standard) master file directory (MFD). The SHARED MFD
resides on shared mass storage and contains only cataloged files common to all hosts in
the Multi-Host File Sharing (MHFS) environment. All hosts in an MHFS system can
assign and access the files cataloged in the SHARED MFD.
shared resource
A resource (in Multi-Host Transaction Processing terms) that is accessible simultaneously
by all hosts in a loosely-coupled system. Examples of shared resources are the database
files of the shared directory.
short recovery
The Integrated Recovery Utility (IRU) process that recovers Exec components, Universal
Database Control, and MCB after a system or component failure. The IRU coordinates
with automatic Exec recovery processes (step control and TIP file control recovery) to
restore all recoverable data and message processing associated with a single application
group to its state before the failure. The short recovery process is started by executing
the IRU SHORT command.
site-developed code
All code written and controlled by users. This includes applications programs and
site-developed code in any of the communications network processors. Formerly called
user-own-code
7833 1568–004 Glossary–11

Glossary
site identifier (SID)
An optional one-character to eight- character terminal identifier (can be a mnemonic) used
in addition to the position identifier (PID), a numeric identifier required in network
configurations. Also referred to as site identifier.
step
A recoverable program entity that is accessing recoverable files to accomplish auditing
and rollback features.
step control
An Exec component of the integrated recovery system that records and updates the
current state of all steps accessing the database within an application group. Step control
provides central control information for the other integrated recovery components (audit
control end TIP file control). Step control includes Exec recovery, an option that initializes
the application group.
step recovery
The recovery of a unit of work in the Integrated Recovery environment.
stream generation statement (SGS)
The instructions entered during installation and used by the symbolic stream generator
(SSG) and the OS 2200 Exec to generate a system. SGSs are used to configure and
generate the MCB product.
SSG
See Symbolic Stream Generator.
switch list
A data structure defined and maintained by the operating system. The SWL address
uniquely identifies an activity within a single host.
SWL
See switch list.
Symbolic Stream Generator (SSG)
A general-purpose OS 2200 language processor that creates and manipulates symbolic
streams. By using the SSG, temporary correction files (TCF) and permanent correction
files (PCF) can be updated, merged with another set of corrections, printed in the
symbolic output stream, or reinserted in the original input file for use in future
programming. The SSG creates a runstream that, when executed, generates software on
an OS 2200 system. The SSG processor is an integral component of the MCB product
generation procedure.
system generation log (SGL)
A document created by COMUS during product generation. SGLs contain data related to
the product generation.
system installation log (SIL)
A document created by COMUS during product installation. SILs contain data related to
product installation, verification of installation, and product deinstallation.
Glossary–12 7833 1568–004

Glossary
system registration log (SRL)
A document created by COMUS when you enter the REGISTER command. SRLs contain
data related to a product release master tape or a separately packaged feature tape.
T
tailored message analysis (TMA)
A method of adding site-supplied message processing code to MCB.
TCF
See temporary correction file.
temporary correction file (TCF)
A file containing code that is applied to a software component to temporarily correct or
upgrade the software.
test mode
A state in which TIP transactions or CONECT programs may execute. Test mode is a
method of testing transaction programs in an online environment. While in test mode,
only FCSS and KONS read functions are performed. Writes, lock requests, and counter
updates are not done, but a normal return is simulated. Test mode allows modifications
or updates to be made on a working program without interfering with network usage of a
production copy of that program. Test and training modes also apply to Network
Database Server.
TIP
See Transaction Processing.
TIP session control (TSC)
A function supported by MCB and CMS 1100 that manages the OS 2200 Exec integrated
recovery sessions.
TIP terminal
A terminal that is logically-connected to the TIP portion of the Exec through the MCB or
COMPOOL interface, and is interactive with a transaction program.
TMA
TPAS
See tailored message analysis.
Acronym for Transaction Performance Auditing System.
7833 1568–004 Glossary–13

Glossary
training mode
A state in which a TIP transaction (or connected program) may operate. Training mode
can be used for training terminal users in the use of operational (debugged) transactions
on a real but controlled database, or for tracking down ”logic” bugs in transactions by
accessing selective (controlled) records. While in training mode, file accesses are made
to an alternate (specified) set of file control superstructure (FCSS) files. The full repertoire
of FCSS operations is permitted, thus allowing live access to files while ensuring the
integrity of the database. The contents of the alternate database can be and are restored
independently of the prime (live) database. Test and training modes also apply to
Network Database Server.
transaction code
That part of the screen (or terminal) input message that identifies which transaction is to
be scheduled. Normally, the transaction code is the first six characters of the message. It
is the job of CMS 1100, or whichever program is making the scheduling request, to
extract the transaction code from the message and place it into the MCB request packet.
Same as action code.
Transaction Processing (TIP)
A Unisys product that executes transaction processing programs. TIP enables a remote
terminal operator to initiate execution of a previously registered program at the central
computer site. Once in execution, the transaction program has access to all functions of
the OS 2200, as well as the specialized TIP functions and services.
TSC
U
UPA
See TIP session control.
See user parameter area.
user parameter area (UPA)
The UPA immediately follows the MPA in the COMPOOL record. It is a configurable
number of words long and contains whatever information a system designer specifies. It
could be used in conjunction with site-developed code in CMS 1100.
V
VALTAB
VINDEX
The transaction program validation table. VALTAB records contain information for
transaction scheduling and various execution parameters.
The VALTAB index. The VINDEX identifies transaction programs by unique six-character
transaction codes and unique program numbers. The VINDEX resides in the VALTAB file
and is used for quick reference by the Exec and MCB.
Glossary–14 7833 1568–004

Index
A
access mask, transaction code, 3-9
active segment (MRF), 2-5
activity
control table (slot), F-15
initialization packet fields, 4-5
termination packet fields, 4-7
activity initialization CMS function
(CMINIT$$), 4-5
activity termination CMS function
(CMTERM$$), 4-7
address limits
main D-bank, 5-2
utility I-bank, 4-3
addressing environment, application
program, 5-2
AFCB, See common banks
alternate return point
with basic mode interface, 3-14
with extended mode interface, 3-14
APNUMBER, 3-6
application interface functions
audit (AUDIT$$), 5-29
cancel output (CANCEL$$), 5-17
close session (CLSSN$$), 5-34
commit (COMMIT$$), 5-12
discrete receive (DISREC$$), 5-30
enqueue message (ENQUE$$), 5-29
initialize (TRINIT$$), 5-6
input-only exclusive use
(SETIXUSE$$), 5-37
obtain exclusive use (SETXUSE$$), 5-35
obtain statistics (STAT$$), 5-38
open session (OPNSSN$$), 5-32
read input (RECV$$), 5-14
release exclusive use (CLRXUSE$$), 5-36
release input (INPREL$$), 5-16
request PID status (PIDSTAT$$), 5-34
rollback (ROLBAK$$), 5-13
store checkpoint (CHKPT$$), 5-26
store output (SEND$$), 5-17
store pass-off (PASOFF$$), 5-23
terminate (TERM$$), 5-11
application program
basic mode addressing environment, 5-2
basic mode high-level calling sequence, 5-2
checkpoint messaging, 3-1
error termination, 2-3
extended mode high-level calling
sequence, 5-3
function codes, A-1
input message, 3-1
interface packet (figure), 5-4
interface packet description, 5-6
interface, message parts, 3-10
output message, 3-1
pass-off message, 3-1
application program considerations, alternate
return point, 3-14
application program interface
auxiliary information area, 5-40
description, 5-1
functions, 5-6
packet description, 5-6
program activity initialization, 5-1
application-unique label, 3-12
APPREC, See IRU application recovery
program
asynchronous contingency
execution completion, 3-10
queue with ER CQUE$, 3-10
attributes, message, 3-2
audit
control, Exec component, 3-10
DML LOG command, 7-3
MCA block, D-2
MRF controls, D-3
overflow block, D-2
periodic statistics, D-3
QITME record, D-3
records, D-1
text, integrated recovery audit trail, 3-4
trail retention, 3-4
user audit record, D-3
audit function (AUDIT$$), 5-29
AUDIT$ packet, F-22
AUDIT$$, 5-29
7833 1568–004 Index–1

Index
automatic restart (MCB)
MCB failure, 3-23
primary host failure, 3-23
auxiliary information area
conversational link, 3-16
device type, 3-20
field definitions, 4-24
for application program packet, 4-23
for CMS, 4-23
input and output messages, 5-40
interactive CRT function codes, 4-24
pass-off and checkpoint messages, 5-40
session state changes, 4-28
start in packet, 3-12
UNISCOPE 100/200, UTS 400 function
codes, 4-24
user parameter area (UPA), 4-24
auxiliary information, word size, 4-8
B
background run
locking common I-bank, 2-1
real-time program, 2-1
TIP/database files, 2-5
use of ER LOAD$, 2-1
basic mode
alternate return point, 3-14
ASCII COBOL (ACOB) program, 5-2
ASCII FORTRAN (FTN) program, 5-2
MASM program, 5-2
basic mode interface
calling sequence, 3-12
MCB entry point (MCB$ENT), 3-12
MCBBDIn, 3-12
batch/demand program
initialization, 5-6
initialization, CONECT, 6-2
termination, DISCON, 6-2
BPFILE, 9-2
BUF$SIZE, F-1
buffer pool controls, F-14
C
calling activity initialization, 3-10
calling sequence, basic mode interface, 3-12
cancel output function (CANCEL$$), 5-17
CANCEL$$, 5-17
CBEP$$MCB BUILD element, 3-12
labels
MCB$ENT, 3-12
MCBBNK, 3-12
MCBBNK$, 3-12
CDATAC, 6-3
CDATCR, 6-3
checkpoint
message, 3-1, 3-2, 5-30
recovery options, 5-42
CHKPT$$, 5-26
close session function (CLSSN$$), 5-34
CLRXUSE$$, 5-36
CLSSN$$, 5-34
CMCAN$$, 4-9
CMFAC$$, 4-22
CMINIT$$, 4-6
CMPIDI$$, 4-19
CMRECV$$, 4-10
CMS
activity initialization (CMINIT$$), 4-5
activity switch list, 4-5
activity termination (CMTERM$$), 4-7
addressing environment, 4-2
application program messages, 3-2
auxiliary information area, 4-23
spooling, 3-21
termination with ROPL output
messages, 3-6
CMS interface
auxiliary information area, 4-23
packet, 4-4
CMS interface functions
activity initialization (CMINIT$$), 4-5
activity termination (CMTERM$$), 4-7
get text (CMSGET$$), 4-16
input message cancel (CMCAN$$), 4-9
obtain resource status (CMFAC$$), 4-22
output message hold (MHOLD$$), 4-12
output message negative acknowledge
(CMSNAK$$), 4-13
output message positive acknowledge
(CMSACK$$), 4-12
PID configuration (CMPIDI$$), 4-19
PID information request
(CMSPIDS$$), 4-21
put text (CMSPUT$$), 4-14
read VINDEX entry (VNXRD$$), 4-15
receive output message
(CMRECV$$), 4-10
Index–2 7833 1568–004

esilient session open notify
(RESOPEN$$), 4-20
session open notify (CMSOPEN$$), 4-20
session status notification, 4-17
store input message (CMSTORE$$), 4-7
CMSACK$$, 4-12
CMSGET$$, 4-16
CMSNAK$$, 4-13
CMSOPEN$$, 4-20
CMSPIDS$$, 4-21
CMSPUT$$, 4-14
CMSTOR$$, 4-7
CMTERM$$, 4-7
COMMIT, 6-4
commit function (COMMIT$$)
description, 5-12
step termination, 5-6
COMMIT$$, 5-12
common bank security, 3-22
common banks
alternate file common bank (AFCB), 9-1
main
components, 2-1
guaranteed-entry point (GEP), 2-3
installed version, 2-3
main storage message (CORBNK), 2-3
MSGBNK, 9-1
MSGLNGBNK, 9-1
use of ER LCORE$, 2-3
Communications Management System, See
CMS
Compiler, rules, 3-15
COMPOOL
communications message-buffer pool, 1-1,
6-1
concurrent operation with MCB, 3-6, 6-6
migrating primitives to MCB, 3-10
termination differences, 6-6
concurrent operation, COMPOOL and
MCB, 3-6, 6-6
CONECT, 6-2
configure resilient parameter, 4-21
conversational link
auxiliary information area, 3-16
purpose, 3-16
CRELOG, 6-3
CRT function codes, 4-24
CSTLOG, 6-3
CSTOVR, 6-3
Index
7833 1568–004 Index–3
D
data buffer address (P$BUFF), 5-8
Data Management System (DMS), See
Network Database Server
data manipulation language (DML)
DEPART command, 5-12
FREE command, 5-12
syntax, 7-2
data structures
buffer pool controls, F-14
message block structure, F-1
MRF allocation descriptor (MAD), F-27
MRF operations, F-8
PID, F-32
PID index file (PIX), F-36
SLOT, F-15
statistics table, F-37
D-bank, main
address limits, 5-2
deferred queuing, 3-2
delivery notification format, 5-46
DEPART
database command, 5-6, 7-2
DEPART WITH ROLLBACK
database command, 5-6, 5-13, 7-2
device category (P$CAT), 4-29
device identifier (P$DID), 4-29
device type
hardware (P$RTYPE), 4-30
logical (P$TTYP), 3-20, 4-26
real (P$RTYPE), 3-20
DID (device identifier), 4-29
discarding input messages, E-2
DISCON, 6-2
discrete receive function (DISREC$$), 5-30
Display Processing System
application interface to MCB, 5-1
application program interface, 3-10
ASCII characters, 4-30
text format, 4-26
DISREC$$, 5-30
Distributed Communications Architecture
(DCA)
field value definitions, 4-29
DM$IOW packet, F-25
DML, See data manipulation language
DMS 2200, See Network Database Server
duplicate message numbers, 3-4

Index
E
ENQUE$$, 5-29
enqueue message function (ENQUE$$), 5-29
entry point
basic mode, 3-12
ER CQUE$
contingency queue, 3-10
ER DM$IOW
in mass storage, 2-5
MSGLNGBNK status, 9-2
ER QI$CON
start a step without a message, 5-7
ER QI$NIT
transaction program initialization, 5-7
ER RT$OUT
queuing ROPL messages, 3-5
ER TRMRG$
program initialization, 5-7
termination notification, 3-10
error code (P$ERR), 5-11
error codes
program, B-1
error conditions, system error program, 8-3
error notification message, 8-5
error notification program (ENP)
description, 8-4
ROPL messages, 3-6
error processing programs
error notification program (ENP), 8-1
system error program (SEP), 8-1
ERTERM, 6-4
example application number 3, 3-13
example programs, 3-13
excess print files
with ROPL, 3-6
exclusive use of PID, 3-20
exclusive use of PID function
(SETXUSE$$), 5-35
Exec message number table, 3-3
Exec system generation, required stream
generation statement, 8-2
Exec usage of unique identifier, 5-40
extend a message, CSTOVR, 6-3
extended mode
alternate return point, 3-14
calling EMMCB, 3-15
enter MCB
UCS Ada (UADA), 5-3
UCS C (UC), 5-3
UCS COBOL (UCOB), 5-3
UCS FORTRAN (UFTN), 5-3
high-level calling sequence, 5-3
RTN instruction, 3-14
Index–4 7833 1568–004
F
facilities status (P$FAC), 4-7, 4-23, 5-7
file security, 3-23
requirement for TIP, 3-23
FREE command, 5-6, 7-2
free segment, 2-6
free segment (MRF), 2-5
function codes
CRT, 4-24
for CMS, A-1
for packet interfaces, A-1
UNISCOPE 100/200, UTS 400
terminals, 4-24
function key index, 4-27
functions
activity initialization (CMINIT$$), 4-5
activity termination (CMTERM$$), 4-7
audit (AUDIT$$), 5-29
cancel output (CANCEL$$), 5-17
close session (CLSSN$$), 5-34
commit (COMMIT$$), 5-12
discrete receive (DISREC$$), 5-30
enqueue message (ENQUE$$), 5-29
get text (CMSGET$$), 4-16
initialize (TRINIT$$), 5-6
input message cancel (CMCAN$$), 4-9
obtain exclusive use (SETXUSE$$), 5-35
obtain input-only exclusive use
(SETIXUSE$$), 5-37
obtain resource status (CMFAC$$), 4-22
obtain statistics (STAT$$), 5-38
open a session (OPNSSN$$), 5-32
output message hold (MHOLD$$), 4-12
output message negative acknowledge
(CMSNAK$$), 4-13
output message positive acknowledge
(CMSACK$$), 4-12
PID configuration (CMPIDI$$), 4-19
PID information request
(CMSPIDS$$), 4-21
put text (CMSPUT$$), 4-14
read input (RECV$$), 5-14
read VINDEX entry (VNXRD$$), 4-15
receive output message
(CMRECV$$), 4-10
release exclusive use (CLRXUSE$$), 5-36
release input (INPREL$$), 5-16

G
request PID status (PIDSTAT$$), 5-34
resilient session open notify
(RESOPEN$$), 4-20
rollback (ROLBAK$$), 5-13
session open notify (CMSOPEN$$), 4-20
session status notification, 4-17
store checkpoint (CHKPT$$), 5-26
store input message (CMSTORE$$), 4-7
store output (SEND$$), 5-17
store pass-off (PASOFF$$), 5-23
terminate (TERM$$), 5-11
get text CMS function (CMSGET$$), 4-16
group PID, 3-16
guaranteed-entry point (GEP), 2-3, 3-14
H
host-to-host transactions, 5-47
I
I-bank, utility
address limits, 4-3
IBM 3270 protocol, 3-20
IMPART command, 7-2
INITAL, 6-2
INITAL primitive, 7-2
INITAL, with database, 7-2
initialization
online batch program, 5-6
transaction program, 5-6
initialize function (TRINIT$$), 5-6
initializing activity
real-time mode, 4-5
INPREL$$, 5-16
input
acknowledge message, 5-44
queue priority, 3-9
input message
acknowledge format, 5-44
attributes, 3-8
cancel function (CMCAN$$), 4-9
control, 3-21
number (P$MN), 5-8
source of, 3-1
Index
input message cancel CMS function
(CMCAN$$), 4-9
input-only exclusive use function
(SETIXUSE$$), 5-37
integrated recovery system
message control component, 1-1
Integrated Recovery Utility, 5-40
Integrated Recovery Utility (IRU), 2-5, 9-1.
See also IRU application recovery
program (APPREC)
intelligent message numbering
input, 3-3
option, 3-3
output, 3-3
setting, requirements, 3-3
interface
application program functions, 5-6
application program packet, 5-4
CMS packet, 4-4
database, 7-1
message processing, 3-10
packet formats, 3-11
TIP primitive, 6-1
IRU, See Integrated Recovery Utility
IRU application recovery program
(APPREC), 3-23
7833 1568–004 Index–5
L
LBJ instruction, 3-11
link, conversational, See conversational link
long message recovery
audit attribute, 3-4
low main storage priority attribute, 3-5
M
MAD, See data structures
main storage
buffers, F-7
buffers, field definitions, F-8
message common banks (CORBNK), 2-3
MAP directives
basic mode, 3-14
MCB
automatic restart, 3-23
component of integrated recovery
system, 1-1
components
action command processing, 2-1

Index
background run, 2-1, 2-2
dumping, 2-1
initialization, 2-1
keyin processing, II, 2-1
long recovery common bank, 2-5
main common bank, 2-1, 2-3
main storage buffer common
banks, 2-1, 2-3
message recovery banks, 2-1, 2-5
message release processing, 2-1
MRF control common banks, 2-1, 2-4
PID table common banks, 2-1, 2-3
range table common banks, 2-1, 2-4
short recovery common bank, 2-5
site-id table common banks, 2-1, 2-4
statistics gathering and reporting, 2-1
validation table index (VINDEX) common
bank, 2-1, 2-4, 6-4
concurrent operation with COMPOOL, 3-6,
6-6
entry point label, MCB$ENT, 3-12
file security, 3-23
file types, 2-5
host-to-host transactions, 5-47
interface types, 1-2
message elements, 1-2
message processing activities, 1-2
message processing concepts, 3-1
message retention files (MRF), 2-5
message types, 3-1
MRF control file, 2-5
PID index file (PIX), 2-6
primitives
CDATAC, 6-3
CDATCR, 6-3
COMMIT, 6-4
CONECT, 6-2
CRELOG, 6-3
CSTLOG, 6-3
CSTOVR, 6-3
DISCON, 6-2
ERTERM, 6-4
INITAL, 6-2
ROLBAK, 6-4
RTOUTP, 6-4
RTRANO, 6-3
RTRANU, 6-3
RTSCHD, 6-4
TERMN8, 6-2
TIP library files, 6-1
volatile register set, 6-1
unique identifier, 5-40
Universal Database Control interface, 5-1
MCB$ENT, 3-12
MCBBDI
where defined, 3-12
MCBBNK, 3-12
MCBBNK$, 3-12
message
attributes, 3-2
audit text, 3-4
block allocation, 2-6
checkpoint, 3-1
deferred queuing, 3-2
extend (CSTOVR), 6-3
format, 3-11
header, offset, 4-29
input, 3-1
low main storage priority, 3-5
numbering
configuration, 3-3
intelligent, 3-3, 3-4
removal, 3-3
unintelligent, 3-3, 3-4
output, 3-1
overlay (CSTOVR), 6-3
parameter area (MPA), 6-4
pass-off, 3-1
processing
common bank security, 3-22
contingencies, 3-10
conversational link, 3-16
delivery notification, 3-17
exclusive use of PID, 3-20
IBM terminal to logical UTS400
terminal, 3-20
initialization, 3-10
input message control, 3-21
interfaces, 3-10
MCB file security, 3-23
MRF threshold control, 3-24
multiple destination output, 3-16
optional features, 3-15
output message control, 3-21
Partitioned Applications, 3-23
PID site-id table, 3-20
PID, exclusive use request, 3-20
ROPL output, options, 3-22
rotary output, 3-16
security
common bank, 3-22
MCB file, 3-23
TIP, 3-22
session control, 3-19
session control, options, 3-22
session control, TIP, 3-22
Index–6 7833 1568–004

statistics monitor transaction, 3-24
termination, 3-10
test and training modes, 3-17
TIP message security, 3-22
TIP session control, 3-22
unsolicited output, 3-17
user message control, 3-24
queue output (RTOUTP), 6-4
queue output (RTSCHD), 6-4
queue pass-off (RTOUTP), 6-4
queue pass-off (RTSCHD), 6-4
read (CDATAC), 6-3
read and release (CDATCR), 6-3
recall, 3-5
recall period, 2-6
recoverability, 3-2
recovery
error handling, 9-2
interface to IRU, 9-1
long, 9-1, 9-2
message numbering options, C-3
option combinations, C-1
program recovery options, C-4
recall option, 5-26, 5-28
short, 9-1
TIP/database files, access, 2-5
recovery bank
MSGBNK, 2-5, 9-1
MSGLNGBNK, 2-5, 9-2
reduced output path length (ROPL), 3-5
release all (CRELOG), 6-3
ROPL, 3-5
step control replacement, 3-5
store (CSTLOG), 6-3
store and queue (RTRANO), 6-3
store and queue (RTRANU), 6-3
traffic, statistical analysis, 3-4
types, 3-1
user session reestablishment, 3-23
message control area (MCA) block, F-1
message numbering option, 3-3
message retention file
active segment, 2-5, F-9
allocation descriptor (MAD), F-27
blocks, F-8, F-9
common banks, 2-4
common control table, F-9
control file, 2-5
control table (MF$CTL), F-12
control table, main (MRF$TBL), F-11
error termination, 2-4
file table (MF$CTX), F-11
files, F-8
Index
free segment, 2-5, F-9
identifier (MID), 9-1, F-10
main control table (MRF$TBL), F-11
message blocks, 2-6
MRF file number, 2-5
MRF$TBL, F-11
MRF/PIX relationship, F-36
nonrecoverable message text, 2-5
queue item, 9-1
recoverable message text, 2-5
retired segment, 2-5, F-9
segment, F-8
segment allocation mask (SAM), F-10
segments, 2-5
staging, 2-5
threshold control, 3-24
MHOLD$$, 4-12
MID, See message retention file (MRF)
identifier
mixed-mode, 3-15
MPA, See message parameter area
MRF, See message retention file
MRFCNTL file, updating by MSGBNK, 9-1
MSGBNK
interface to IRU, 9-1
status codes, 9-1
updating MRFCNTL, 9-1
MSGLNGBNK
interface to IRU, 9-2
status codes, 9-2
multiactivity program, restrictions, 5-1
Multi-Host File Sharing (MHFS) feature, IRU
file used, 9-2
multiple destination
list format, 5-20
output, 3-16
multiple SLOT banks, F-15, F-20, F-22
7833 1568–004 Index–7
N
Network Database Server
commit point, 3-9
recovery, 3-8
run unit conventions, 7-1
Universal Database Control interface, 7-1
network input messages
changing recovery options, E-2
nonrecoverable message text, overflow
storage, 2-5
nonrecoverable MRF, F-9

Index
O
object modules (OM), linked, 3-15
obtain exclusive use function
(SETXUSE$$), 5-35
obtain input-only exclusive use function
(SETIXUSE$$), 5-37
obtain resource status CMS function
(CMFAC$$), 4-22
obtain statistics function (STAT$$), 5-38
online batch program initialization, 5-6
open a session function (OPNSSN$$), 5-32
OPNSSN$$, 5-33
output message
attributes, 3-8
header, 5-45
source of, 3-1
output message hold CMS function
(MHOLD$$), 4-12
output message negative acknowledge CMS
function (CMSNAK$$), 4-13
output message positive acknowledge CMS
function (CMSACK$$), 4-12
overflow storage, of nonrecoverable message
text, 2-5
overlay a message, CSTOVR, 6-3
P
packet fields
activity initialization CMS function
(CMINIT$$), 4-5
activity termination CMS function
(CMTERM$$), 4-7
audit function (AUDIT$$), 5-29
cancel output function (CANCEL$$), 5-17
close session function (CLSSN$$), 5-34
commit function (COMMIT$$), 5-12
discrete receive function (DISREC$$), 5-30
enqueue message function
(ENQUE$$), 5-29
get text CMS function (CMSGET$$), 4-16
initialize function (TRINIT$$), 5-7
input message cancel CMS function
(CMCAN$$), 4-9
obtain exclusive use function
(SETXUSE$$), 5-35
obtain input-only exclusive use function
(SETIXUSE$$), 5-37
obtain resource status CMS function
(CMFAC$$), 4-22
obtain statistics function (STAT$$), 5-38
open a session function (OPNSSN$$), 5-33
output message hold CMS function
(MHOLD$$), 4-12
output message negative acknowledge
CMS function (CMSNAK$$), 4-13
output message positive acknowledge
CMS function (CMSACK$$), 4-12
PID configuration CMS function
(CMPIDI$$), 4-19
PID information request CMS function
(CMSPIDS$$), 4-21
put text CMS function (CMSPUT$$), 4-14
read input function (RECV$$), 5-14
read VINDEX entry CMS function
(VNXRD$$), 4-16
receive output message CMS function
(CMRECV$$), 4-10
release exclusive use function
(CLRXUSE$$), 5-36
release input function (INPREL$$), 5-16
request PID status function
(PIDSTAT$$), 5-34
resilient session open notify CMS function
(RESOPEN$$), 4-20
rollback function (ROLBAK$$), 5-13
session open notify CMS function
(CMSOPEN$$), 4-20
session status notification CMS
function, 4-17
store checkpoint function (CHKPT$$), 5-26
store input message CMS function
(CMSTORE$$), 4-7
store output function (SEND$$), 5-17
store pass-off function (PASOFF$$), 5-23
terminate function (TERM$$), 5-12
PASOFF$$, 5-23
pass-off message, source of, 3-1
PID configuration CMS function
(CMPIDI$$), 4-19
PID index file, MRF/PIX relationship, F-36
PID information request CMS function
(CMSPIDS$$), 4-21
PIDSTAT$$, 5-34
PIX, See PID index file
program failure
message recoverability, 3-2
put text CMS function (CMSPUT$$), 4-14
Index–8 7833 1568–004

Q
queue a pass-off message (RTOUTP), 6-4
queue a pass-off message (RTSCHD), 6-4
queue an output message (RTOUTP), 6-4
queue an output message (RTSCHD), 6-4
queuing ROPL messages
ER RT$OUT, 3-5
R
range table common banks, 2-4
read a message (CDATAC), 6-3
read and release message (CDATCR), 6-3
read input function (RECV$$), 5-14
read VINDEX entry CMS function
(VNXRD$$), 4-15
real-time mode
initializing activity, 4-5
recall period, 2-6
receive output message CMS function
(CMRECV$$), 4-10
recoverable messages, 3-2
recoverable MRF, F-8
recovery
messages, 2-5
MRF segment states, 2-6
MSGBNK, 2-5
MSGLNGBNK, 2-5
options
default, 5-41
ensuring recovery, 3-7
for VINDEX entries, 3-7
input message attributes, 3-8
message numbering, 3-3
output message attributes, 3-8
P$RECOPT override, 5-41
Discrete Receive, 5-32
Initialize, 5-11
Store Checkpoint, 5-28
Store Output, 5-22
Store Pass-Off, 5-25
program execution attributes, 3-8
ROPL, 3-6
specified in VALTAB, 3-7
summary, 5-41
target VINDEX entry, 5-41
PIX file, 2-6
processing notification, 3-19
RECV$$, 5-14
reduced output path length, 3-5
Index
reduced output path length messages,
undelivered, 3-6
release all messages (CRELOG), 6-3
release exclusive use function
(CLRXUSE$$), 5-36
release input function (INPREL$$), 5-16
request PID status function
(PIDSTAT$$), 5-34
resiliency
conversational link, 3-16
copying session-related changes, 2-6
exclusive use information, retention, 3-20
exclusive use retention, 5-35, 5-37
MCB, 4-6
mode interpretation, 3-19
mode state retention, 5-20
Partitioned Applications, 3-23
restrictions, 5-47
session retention, 3-19, 5-32
user session reestablishment, 3-23
resilient parameter, configure, 4-21
resilient session open notify CMS function
(RESOPEN$$), 4-20
RESILIENT SGS
MCB session control, 3-19
mode interpretation, 3-19
MRF control file, 2-6
Open a Session, 5-32
PID, exclusive use of, 3-20
PID, obtain exclusive use of, 5-35
PID, Obtain Input-Only Exclusive Use
of, 5-37
Store Output, 5-20
RESOPEN$$, 4-20
restrictions
database run units, 7-1
host-to-host, 5-47
multiactivity programs, 5-1
Partitioned Applications, 3-23
TIP primitive interface
CSTOVR, 6-5
message parameter area, 6-4
user parameter area, 6-5
retired segment (MRF), 2-5
return point (P$RTN)
activity initialization, 4-6
activity termination, 4-7
audit, 5-30
cancel output, 5-17
close a session, 5-34
commit, 5-12
discrete receive, 5-31
enqueue message, 5-29
7833 1568–004 Index–9

Index
extended mode, 5-3
get text, 4-17
initialize, 5-9
input message cancel, 4-10
obtain exclusive use of PID, 5-36
obtain input-only exclusive use of PID, 5-37
open a session, 5-33
output message hold, 4-12
output message negative
acknowledgement, 4-13
output message positive
acknowledgement, 4-13
PID information request, 4-22
put text, 4-15
read input, 5-16
receive output message, 4-11
release exclusive use of PID, 5-36
release input, 5-16
request PID status, 5-35
rollback, 5-14
session open notify, 4-20
store checkpoint, 5-27
store input message, 4-8
store output, 5-20
store pass-off, 5-24
terminate, 5-12
ROLBAK, 6-4
ROLBAK primitive, 7-2
ROLBAK$$, 5-13
rollback function (ROLBAK$$), 5-13
ROPL, See reduced output path length
rotary output, 3-16
RTOUTP, 6-4
RTRANO, 6-3
RTRANU, 6-3
RTSCHD, 6-4
S
SAM, See segment allocation mask
segment allocation mask (SAM), F-10
segment states (MRF), 2-5
SEND$$, 5-17
SEP, See System Error Program
session
control, MCB, 3-19
control, RESILIENT parameter, 3-19
control, TIP, 3-22
recovery, 3-19
state change notification, 3-20, 5-47
session open notify CMS function
(CMSOPEN$$), 4-20
session status notification CMS function, 4-17
SETIXUSE$$, 5-37
SETXUSE$$, 5-35
site-id table common banks, 2-4
SLOT, extension area, F-23
spooling, changes for CMS
configuration, 3-21
staging
input message, 3-4, 4-7
output message, 3-17
STAT$$, 5-38
statistics
message traffic, analysis, 3-4
monitor transaction, 3-24
obtaining (STAT$), 5-38
table, F-37
step control
basic mode, 3-12
Exec component, 3-10
message, 3-5
mixed mode, 3-15
store a message (CSTLOG), 6-3
store and queue a message (RTRANO), 6-3
store and queue a message (RTRANU), 6-3
store checkpoint function (CHKPT$$), 5-26
store input message CMS function
(CMSTORE$$), 4-7
store output function (SEND$$), 5-17
store pass-off function (PASOFF$$), 5-23
success point
processing, 3-2
system error program, 8-3
system error program (SEP), 8-1
system error program, MCB interface, 8-3
system failure
message recoverability, 3-2
system generation, Exec, required stream
generation statement, 8-2
Index–10 7833 1568–004
T
Tailored Message Analysis (TMA)
code location, E-1
initial message analysis (IMA), use of, E-1,
E-2
main storage buffer requirement, E-2
register use, E-2

Tailored Session Analysis (TSA)
code for additional processing, E-3
code location, E-3
register use, E-3
TERM$$, 5-12
terminal class, 3-9
terminate function (TERM$$), 5-11
termination
application program, 2-3
batch program, DISCON, 6-6
COMPOOL, 6-6
notification, ER TRMRG$, 3-10
transaction program, TERMN8, 6-2, 6-6
TERMN8, 6-2
test mode, 3-18
TIP, See transaction processing
TIP$XMIT packet, F-26
TMA, See Tailored Message Analysis
TPAS, See Transaction Performance Auditing
System
training mode, 3-17
transaction code
access mask, 3-9
fields, 4-9
input queue priority, 3-9
P$TC1/P$TC2
Discrete Receive, 5-32
Initialize, 5-11
Obtain Exclusive Use of a PID, 5-36
Obtain Input-Only Exclusive Use of a
PID, 5-38
Open a Session, 5-33
Store Checkpoint, 5-28
Store Output, 5-20
Store Pass-Off, 5-25
recovery options, 3-7
target, 3-6
transaction program number, 3-9
Transaction Performance Auditing System
(TPAS), 3-24
transaction processing
file security, 3-23
message dequeuing, 3-9
message security, 3-22
modes of execution, 3-17
primitive interface
application programming
considerations, 6-5
batch program initialization, 6-2
batch program termination, 6-2
calling sequence, basic mode, 5-2
CDATAC, 6-3
CDATCR, 6-3
Index
COMMIT, 6-4
concurrency, restrictions, 6-6
CONECT, 6-2
CRELOG, 6-3
CSTLOG, 6-3
CSTOVER, 6-3
CSTOVR, 6-5
demand program initialization, 6-2
demand program termination, 6-2
DISCON, 6-2
ERTERM, 6-4
extend a message, 6-3
INITAL, 6-2
initialization
batch program, 6-2
demand program, 6-2
restrictions, 6-5
transaction program, 6-2
MCB primitives, 6-1
message contents, assumed, 3-10
message parameter area (MPA), 6-4
overlay a message, 6-3, 6-5
physical COMPOOL primitives, 6-5
program end of step, 6-4
program error termination, 6-4
program options, 6-5
program step rollback, 6-4
queue a pass-off message, 6-4
queue an output message, 6-4
read a message, 6-3
read and release a message, 6-3
relative addressing, 6-5
release all messages, 6-3
restrictions, 6-4, 6-5
ROLBAK, 6-4
RTOUTP, 6-4
RTRANO, 6-3
RTRANU, 6-3
RTSCHD, 6-4
store a message, 6-3
store and queue a message, 6-3
termination
batch program, 6-2
demand program, 6-2
program error, 6-4
transaction program, 6-2
TERMN8, 6-2
transaction program initialization, 6-2
transaction program termination, 6-2
user parameter area (UPA), 6-5
program number, 3-9
session control, 3-22
7833 1568–004 Index–11

Index
transaction program
initialization, 5-6
initialization, INITAL, 6-2
number (P$PROG), 5-9
termination, TERMN8, 6-2
TRINIT$$, 5-7
TSA, See Tailored Session Analysis
U
UCF, See User Communication Forms
unintelligent message numbering
format
input acknowledge message, 5-44
output message header, 5-45
input, 3-4
option, 3-3
output, 3-4
setting, requirements, 3-3
unique identifier
discrete receive, 5-31
Exec usage, 5-40
format, 5-41
initialize, 5-9, 5-10
Integrated Recovery Utility usage, 5-40
MCB usage, 5-40
message originator (P$OS1/P$OS2), 5-40
program step (P$STEP1/P$STEP2), 5-40
rollback, 5-14
store checkpoint, 5-27
store output, 5-20
store pass-off, 5-24
Universal Database Control usage, 5-40
UNISCOPE 100/200, function codes, 4-24
Universal Database Control
MCB interface, 5-1, 7-1
modes of execution, 3-17
unique identifier usage, 5-40
unsolicited output, 3-17
UPA, See user parameter area
User Communication Forms (UCF), MSGBNK
error handling, 9-2
user message control
using with TMA, E-2
user parameter area (UPA)
program access, 6-5
purpose, 4-24
user session reestablishment, 3-23
UTS 400
emulation mode, 3-20
function codes, 4-24
function key index, 4-27
Index–12 7833 1568–004
V
validation table index (VALTAB)
mode establishment, 3-19
modification caution, 3-9
relationship to VINDEX, 2-4
system error program (SEP)
considerations, 8-2
transaction program options, 3-7, 3-22
validation table index (VINDEX) common bank
COMMIT recovery options, 6-4
construction, 3-6
description, 2-4
error notification program (ENP)
considerations, 8-5
fields of entries, 3-6
ROLBAK recovery options, 6-4
system error program (SEP)
considerations, 8-3
VALTAB, See validation table index
VINDEX, See validation table index common
bank
VNXRD$$, 4-16
volatile register set, 6-1
VTBUTL
AUDIT parameter, 3-6
MASK parameter, 3-9
purpose, 3-6
QPRIORITY parameter, 3-9
RECOVERY parameter, 3-7

*78331568-004*
78331568– 004