unisys

ClearPath OS 2200 Transaction Processing Programming Reference Manual ClearPath OS 2200 Release 15.0 February 2014

7830 7402–014

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.

Unisys and ClearPath are registered trademarks 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.

Contents Section 1.

Introduction 1.1. 1.1.1. 1.1.2. 1.2. 1.3. 1.4. 1.5. 1.6. 1.7. 1.8. 1.9. 1.10. 1.11. 1.11.1. 1.11.2. 1.11.3. 1.12. 1.13.

Section 2.

Basic Program Structure 2.1. 2.1.1. 2.1.2. 2.2. 2.2.1. 2.2.2. 2.2.3. 2.2.4. 2.3. 2.3.1. 2.3.2. 2.3.3. 2.3.4. 2.3.5. 2.3.6.

7830 7402–014

About This Manual ..............................................................................1–1 Documentation Updates .........................................................1–1 Notation Conventions ............................................................. 1–2 TIP File Control and Scheduling ...................................................... 1–2 Programming Languages ................................................................. 1–3 Message Handling ............................................................................. 1–3 Database Types .................................................................................. 1–3 Frequently Accessed Data Files ..................................................... 1–4 Recovery .............................................................................................. 1–4 Security ................................................................................................. 1–4 Multiple Hosts ..................................................................................... 1–4 TIP Programs ....................................................................................... 1–5 Basic Transaction Program Design................................................ 1–5 Scope of a Transaction Program .......................................... 1–5 Site Control of Program Types ............................................. 1–6 Skeleton Transaction Program ............................................. 1–6 TIP System Parameters .................................................................... 1–7 Transaction Program Parameters .................................................. 1–7

Initializing and Terminating a Program .......................................... 2–1 Batch-Connected and Online-Batch Programs ................. 2–1 TIP Programs .............................................................................2–6 Using Message-Handling Primitives ............................................. 2–7 Reading an Input Message .................................................... 2–7 Handling an Output Message ...............................................2–9 Scheduling Another Program: User-to-User Pass-Off ............................................................................... 2–11 Sending the Output to the User’s Terminal .................... 2–13 Using TIMER Primitives to Schedule a Program ...................... 2–15 TIMER Scheduling .................................................................. 2–15 Initiating Relative Scheduling—TIMREL Primitive ............................................................................... 2–16 Initiating Absolute Scheduling—TIMABS Primitive ............................................................................... 2–17 Updating Relative Scheduling—TIMUPR Primitive ............................................................................... 2–18 Updating Absolute Scheduling—TIMUPA Primitive ............................................................................... 2–19 Deleting a TIMER Entry—TIMDEL Primitive .................... 2–19

iii

Contents

2.4. 2.4.1. 2.4.2. Section 3.

TIP File Access 3.1. 3.1.1. 3.1.2. 3.2. 3.2.1. 3.2.2. 3.2.3. 3.2.4. 3.3. 3.3.1. 3.3.2. 3.4. 3.4.1. 3.4.2. 3.4.3. 3.4.4. 3.4.5. 3.4.6. 3.5. 3.5.1. 3.5.2. 3.5.3. 3.5.4. 3.5.5. 3.5.6. 3.5.7. 3.5.8. 3.5.9. 3.5.10. 3.5.11. 3.5.12. 3.5.13. 3.5.14. 3.5.15. 3.5.16. 3.5.17. 3.5.18.

iv

Abnormal Termination of Program Execution ......................... 2–20 Handling Abnormal Termination—ERTERM Primitive .............................................................................. 2–20 Regaining Control after Abnormal Termination ............. 2–21

TIP User Files ....................................................................................... 3–1 TIP User File Types .................................................................. 3–1 Temporary and Scratch Files for Transaction Programs ...............................................................................3–2 TIP File Control ....................................................................................3–2 UDS, Freespace, and FCSS ....................................................3–2 Record Locks ............................................................................ 3–3 Access to FCSS Files .............................................................. 3–4 Duplex TIP Files ....................................................................... 3–4 Using Freespace Files .......................................................................3–5 Organization of a Freespace File ..........................................3–5 Access to Freespace Files .................................................... 3–6 TIP Files and XTC ................................................................................3–7 Extended Transaction Capacity System ............................3–7 TIP FCSS File Directories ........................................................3–7 Extended Processing Complex ........................................... 3–8 Application Groups ................................................................. 3–8 Integrated Recovery for the XTC System ........................ 3–9 Operating with a Shared TIP Database.............................. 3–9 Using FCSS Primitives for FCSS and Freespace Files ............. 3–10 Parameters for FCSS Requests .......................................... 3–10 Write Records to Audit Trail—AD Function ....................3–14 Allocate and Lock Freespace Records—AL Function ...............................................................................3–14 Allocate, Write, and Unlock Freespace Records—AN Function .................................................... 3–15 Allocate a Specific Freespace Record—AP Function ............................................................................... 3–15 Assign an Area for Temporary or Scratch Files—AS Function ............................................................ 3–16 Allocate, Write, and Lock Freespace Record— AW Function ....................................................................... 3–19 Check for Completion of Request—CK Function .......... 3–19 Volatile TCDBF Checkpoint—CP Function ...................... 3–20 Lock a Permanent File—FL Function ................................ 3–20 Lock a File Against Write Access—FR Function ............ 3–21 List Characteristics of a File—LF Function ...................... 3–21 Lock Records—LK Function ............................................... 3–26 Read Records—RD Function ............................................. 3–26 Read and Lock Records—RL Function ............................ 3–27 ASCII COBOL Read Records—RR Function ................... 3–27 Release and Unlock Freespace Records—RU Function .............................................................................. 3–28 Save File Updates—SF Function ....................................... 3–28

7830 7402–014

Contents

3.5.19. 3.5.20. 3.5.21. 3.5.22. 3.5.23. 3.6. 3.6.1. 3.6.2. Section 4.

Program Steps and Integrated Recovery 4.1. 4.2. 4.2.1. 4.2.2. 4.2.3. 4.2.4. 4.3. 4.4. 4.5. 4.6. 4.6.1. 4.6.2. 4.6.3. 4.7.

Section 5.

Release All Record/File Locks—UA Function ................ 3–28 Release Record or File Locks—UN Function ................. 3–29 Write Records and Keep Locked—WL Function .......... 3–29 Write and Release Lock—WR Function .......................... 3–30 Write Records Without Checking for Lock— WW Function...................................................................... 3–31 Using TIP Common Data Bank Files ........................................... 3–32 Accessing a TCDBF............................................................... 3–32 TCDIO Primitive ..................................................................... 3–32

Integrated Recovery .......................................................................... 4–1 Commit Points and Rollback .......................................................... 4–2 COMMIT .................................................................................... 4–2 TERMN8 ..................................................................................... 4–3 DISCON ...................................................................................... 4–3 ROLLBACK ................................................................................ 4–3 Apply Updates to the Database—COMMIT Primitive ............. 4–3 Roll Database Updates Back—ROLLBACK Primitive............... 4–4 Step Control Summary .................................................................... 4–4 Recoverable Updates ....................................................................... 4–5 TIP File Directory ..................................................................... 4–5 Audit Trail/Application Group Number............................... 4–5 Recoverable Program Steps and Primitive Requests .............................................................................. 4–6 Controlling Commit Processing ..................................................... 4–7

Using KONS 5.1. 5.2. 5.2.1. 5.2.2. 5.2.3. 5.2.4. 5.2.5. 5.2.6.

KONS Function Requests .................................................................5–2 KONS Function Descriptions .......................................................... 5–6 Update KONS Counter—CUPDAT Function (6) ................5–7 Fill-Write KONS Words—FILLWR Function (-2) ................5–7 Read and Lock a U3 Block—KRDLK Function (7) .............5–7 Read KONS Records—KREAD Function (1) ...................... 5–8 Write KONS Records—KWRITE Function (2) .................. 5–8 Write to U3 Block and Keep Locked—KWRKP Function (9) ........................................................................... 5–8 5.2.7. Write and Unlock U3 Block—KWRUN Function (8) ............................................................................................ 5–9 5.2.8. Update Counter in U3 Block—LUPDAT Function (11) ........................................................................................... 5–9 5.2.9. Mask Search and Read KONS Records— MSREAD Function (3) ........................................................ 5–9 5.2.10. Scatter-Read KONS Records—SCATRD Function (-1) ......................................................................... 5–10 5.2.11. Sequentially Search and Read KONS Records— SEQSRD Function (5) ........................................................ 5–11 5.2.12. Vertically Search and Read KONS Records— SERCHR Function (4) ........................................................ 5–11 7830 7402–014

v

Contents

5.2.13. 5.2.14. 5.2.15. 5.2.16. Section 6.

Using Performance Improvement Techniques 6.1. 6.2. 6.3. 6.3.1. 6.3.2. 6.3.3. 6.4. 6.5. 6.6.

Section 7.

Next Message Request ....................................................................6–2 Multiple Initialization—Multiple INITAL ........................................6–2 Resident Online Programs—RTPS Feature ................................ 6–3 Resident Online Program Logic ........................................... 6–4 Initialize Resident Online Program—RTPSI Primitive ................................................................................ 6–5 Delete Resident Online Program—RTPSD Primitive ................................................................................ 6–6 Block Transfer Loading .....................................................................6–7 Program Restart .................................................................................6–7 Program Sticking and Reactivation ............................................... 6–8

HVTIP Programs 7.1. 7.1.1. 7.1.2. 7.1.3. 7.1.4. 7.2. 7.2.1. 7.2.2. 7.2.3. 7.2.4. 7.2.5. 7.2.6. 7.3. 7.3.1. 7.3.2. 7.3.3. 7.3.4. 7.4. 7.4.1. 7.4.2. 7.4.3. 7.5. 7.5.1. 7.5.2. 7.5.3. 7.5.4. 7.6.

vi

Security Read of a U3 Block—SREAD Function (12) ......................................................................................... 5–12 Update Security Counter—SUPDAT Function (14) ......................................................................................... 5–12 Security Write to a U3 Block—SWRITE Function (13) ........................................................................ 5–13 Unlock a U3 Block—UNLOCK Function (10) .................... 5–13

HVTIP Program Structure ................................................................. 7–2 Common Banks ........................................................................7–3 Extended Mode HVTIP ............................................................7–3 HVTIP Program Libraries ....................................................... 7–4 HVTIP Program Banks ............................................................ 7–4 Passing Control by Call, Transfer, and Return ............................7–5 Calling an External Subroutine ..............................................7–5 Call Interface ..............................................................................7–6 Transferring Control to Another Bank ................................ 7–7 Transfer Interface.....................................................................7–8 Returning Control After a Call ...............................................7–8 Cancel Return Stack ................................................................7–9 Extended Mode Call, Transfer, and Return ............................... 7–10 Call Subprogram ..................................................................... 7–10 Transfer Subprogram ............................................................ 7–10 Cancel Return Stack .............................................................. 7–10 Transfer and Cancel Return Stack ..................................... 7–10 Initial Control Program .................................................................... 7–11 Constructing an Initial Control Program ........................... 7–11 VALTAB Entries for an Initial Control Program ............... 7–11 Initial Register State .............................................................. 7–11 HVTIP Information ............................................................................ 7–13 MASM Programs .................................................................... 7–13 ASCII FORTRAN Programs................................................... 7–13 ASCII COBOL Programs ........................................................ 7–14 Alternate ASCII Primitives to Use with HVTIP ................ 7–14 Collector Considerations for HVTIP Program Banks ............... 7–15 7830 7402–014

Contents

7.6.1. 7.6.2. 7.6.3. 7.7. 7.7.1. 7.7.2. 7.7.3. 7.7.4. Section 8.

I-Bank ......................................................................................... 7–15 D-Bank ....................................................................................... 7–16 Control Bank ............................................................................ 7–16 Program D-Bank Initialization ........................................................ 7–16 Initialization Segments .......................................................... 7–17 Using SEG ................................................................................. 7–17 Using RSEG .............................................................................. 7–18 Loading Initialization Segment (RSEGLOAD) ................... 7–18

Programming Requirements 8.1. 8.1.1. 8.1.2. 8.1.3. 8.1.4. 8.1.5. 8.1.6. 8.1.7. 8.1.8. 8.1.9.

Design-Dependent Requirements ................................................. 8–1 TIP Definition Parameters ...................................................... 8–1 COBOL Definition Procedures ..............................................8–2 FORTRAN Definition Procedures .........................................8–2 MASM Definition Procedures .............................................. 8–3 Collecting Your Program ....................................................... 8–3 Self-Initializing Transaction Programs ................................ 8–4 Reentrant Transaction Programs ........................................ 8–4 Mapping Reentrant Programs ............................................. 8–4 Mapping Self-Initializing and Self-Destructive Programs .............................................................................. 8–6 8.1.10. Compiling and Linking in Extended Mode ........................ 8–6 8.1.11. Standard-Load and Fast-Load ZOOMs ................................8–7 8.2. Language-Dependent Requirements ........................................... 8–8 8.2.1. FORTRAN Considerations ..................................................... 8–8 8.2.2. COBOL Considerations .......................................................... 8–9 Partial Word Fields ................................................................. 8–11 8.2.3. 8.2.4. Calling Sequences .................................................................. 8–12 8.2.5. MASM Considerations .......................................................... 8–13 8.2.6. Register Use ............................................................................8–14 8.2.7. Illegal Executive Requests ...................................................8–14 8.2.8. CSF$ @START for TIP Transactions .................................. 8–15 8.2.9. Quarter-Word Mode.............................................................. 8–15 8.3. Security-Dependent Requirements.............................................8–16 8.3.1. TIP Program Type ...................................................................8–16 8.3.2. Multiple-Input Transactions ................................................. 8–17 8.3.3. HVTIP ........................................................................................ 8–20 8.3.4. Special Security Option 3 Environment Considerations .................................................................. 8–20 8.4. Requirements for Execution-Time Features ............................. 8–21 8.4.1. TPLOG Primitive ..................................................................... 8–22 8.4.2. Flagbox and Logbox Settings............................................. 8–23 8.4.3. Execution Option Indicator Primitives ............................. 8–25 Section 9.

Testing Programs and Using Diagnostic Information 9.1. 9.1.1. 9.1.2. 9.1.3.

7830 7402–014

Testing and Training Modes ............................................................ 9–1 Setting Up Alternate Program Modes ................................ 9–1 Setting Up a Terminal for Alternate Modes ......................9–2 Executing Programs in Alternate Modes ...........................9–2 vii

Contents

9.1.4. 9.1.5. 9.2. 9.2.1. 9.2.2. 9.2.3. 9.2.4. 9.2.5. 9.2.6. 9.2.7.

Using KONS Functions and Files ......................................... 9–5 Other Considerations ............................................................. 9–6 Diagnostic Information .....................................................................9–7 Diagnostic Files .........................................................................9–7 Security Attributes .................................................................. 9–9 Preparing Transaction and Online-Batch Programs for Diagnostic Files ......................................... 9–9 Preparing Batch- and Demand-Connect Programs for Diagnostic Files ......................................... 9–9 Making Diagnostic Files Available for Transaction and Online-Batch Programs..................... 9–10 Results of Abnormal Program Termination..................... 9–10 Using PADS to Examine Diagnostic Files......................... 9–12

Appendix A. TIP Scheduling and Contingency Error Codes Appendix B. Additional TIP File Control Information B.1. B.2. B.3. B.3.1. B.3.2. B.3.3.

General FCSS User Buffer ................................................................B–1 FCREG Primitive Instead of a TIP Utility ...................................... B–4 Using FCSS Primitive Functions Instead of a TIP Utility................................................................................................ B–5 FCSS RV Function .................................................................... B–6 FCSS RE Function .................................................................... B–9 FCSS CG Function .................................................................. B–10

Appendix C. Additional Programming Information C.1. C.2. C.2.1. C.2.2. C.2.3. C.3. C.3.1. C.3.2. C.3.3. C.4. C.4.1. C.4.2. C.4.3. C.4.4. C.4.5. C.4.6. C.5. C.5.1. C.5.2. C.6. C.6.1.

viii

Format of the Message Parameter Area ..................................... C–1 Special Subroutines .......................................................................... C–8 FIELD Subroutine ..................................................................... C–8 LOCATE Subroutine ................................................................ C–9 COBOL Interfaces to KONS .................................................. C–9 Bank Expansion and Contraction ................................................ C–10 Requesting Bank Expansion with MCORE$ ER .............. C–11 Requesting Bank Contraction with LCORE$ ER ............. C–11 Requesting Bank Expansion or Contraction with TCORE$ ER ..........................................................................C–12 UDS/TIP Interface Executive Requests ......................................C–12 DM$IOW Request ................................................................. C–13 DM$IO Request ......................................................................C–17 DM$WT Request....................................................................C–17 DM$FAC Request...................................................................C–17 EMODE Conditions................................................................ C–19 DM$IOW/DM$IO I/O Status Codes .................................. C–19 Format of a SLOP Table ..................................................................C–21 SLOP Table Format and Field Descriptions .....................C–21 SLOP Control Word in the PCT .......................................... C–27 Format of an Extended Mode Diagnostic File ......................... C–27 Diagnostic File Header ......................................................... C–28

7830 7402–014

Contents

C.6.2. C.6.3. C.6.4.

Program Header .................................................................... C–28 Activity Entry .......................................................................... C–37 Bank Entry ............................................................................... C–42

Appendix D. Quick Reference for the FCSS Primitive Index

7830 7402–014

..................................................................................................... 1

ix

Contents

x

7830 7402–014

Figures 1–1.

Skeleton Transaction ....................................................................................................... 1–6

3–1. 3–2. 3–3.

FCSS AS Buffer Format (Device Index Definition) ................................................ 3–16 FCSS AS Buffer Format (Assign Temporary or Scratch File) .............................. 3–18 FCSS LF User Buffer Format ...................................................................................... 3–22

7–1.

HVTIP Execution ............................................................................................................... 7–2

8–1.

FORTRAN Parameter List .............................................................................................. 8–9

B–1. B–2. B–3.

FCSS RV User Buffer Format ....................................................................................... B–6 FCSS RE Buffer Format .................................................................................................. B–9 FCSS CG Buffer Format ................................................................................................ B–11

C–1. C–2. C–3. C–4. C–5. C–6.

Message Parameter Area (MPA) ................................................................................ C–2 DM$IOW Packet Format ............................................................................................. C–13 DM$FAC Packet Format ...............................................................................................C–17 Format of the SLOP Table ............................................................................................C–21 Format of the SLOP Control Word ........................................................................... C–27 TIP SUBQ Information Packet .................................................................................... C–31

7830 7402–014

xi

Tables 1–1.

VALTAB Parameter Fields and Keywords ................................................................. 1–8

2–1. 2–2. 2–3. 2–4. 2–5. 2–6. 2–7. 2–8. 2–9. 2–10. 2–11. 2–12. 2–13. 2–14. 2–15. 2–16. 2–17. 2–18. 2–19.

CONECT Request Formats ............................................................................................ 2–2 Recovery Options Parameters ..................................................................................... 2–2 Execution Options ........................................................................................................... 2–4 DISCON Call Formats.......................................................................................................2–5 INITAL Request Formats ................................................................................................2–6 TERMN8 Request Formats ............................................................................................ 2–7 CSTLOG Request Formats .............................................................................................2–9 CSTOVR Request Format ............................................................................................. 2–10 CRELOG Request Formats ........................................................................................... 2–10 RTSCHD Request Formats........................................................................................... 2–11 RTRANU Request Formats .......................................................................................... 2–12 RTOUTP Request Formats ........................................................................................... 2–13 RTRANO Request Formats .......................................................................................... 2–14 TIMER Primitives ............................................................................................................ 2–16 TIMREL Request Formats ............................................................................................ 2–16 TIMABS Request Formats ........................................................................................... 2–17 TIMUPR Request Formats ........................................................................................... 2–18 TIMUPA Request Formats ........................................................................................... 2–19 TIMDEL Request Formats ............................................................................................ 2–19

3–1. 3–2. 3–3.

Return Types ................................................................................................................... 3–11 FCSS Primitive Request Formats ...............................................................................3–14 TCDIO Request Formats ............................................................................................. 3–33

4–1. 4–2. 4–3.

COMMIT Request Formats........................................................................................... 4–3 ROLLBACK Request Formats ...................................................................................... 4–4 Step Control System Action ......................................................................................... 4–4

5–1. 5–2. 5–3.

KONS Function Requests ...............................................................................................5–2 KONS Area Addressing Scheme ..................................................................................5–5 KONS Functions and Areas Accessed....................................................................... 5–6

8–1. 8–2. 8–3. 8–4. 8–5. 8–6. 8–7. 8–8.

TIP Features That Support Multiple-Input Transactions ...................................... 8–17 TPLOG Request Formats............................................................................................. 8–22 FOXER Request Formats ............................................................................................. 8–23 Specific FOXER Formats .............................................................................................. 8–23 Flagbox Bits .................................................................................................................... 8–24 FLBOX Request Formats ............................................................................................. 8–25 UOPGET Request Formats ......................................................................................... 8–26 UOPAND Request Formats ........................................................................................ 8–26

7830 7402–014

xiii

Tables

xiv

8–9.

UOPTOR Request Formats ......................................................................................... 8–27

9–1. 9–2. 9–3.

Interpretation of Modes ................................................................................................ 9–4 Interpretation of KONS Functions for Test Mode .................................................. 9–5 Diagnostic Files .................................................................................................................9–7

A–1.

TIP Errors ........................................................................................................................... A–2

C–1.

Executive Requests for Memory Bank Expansion/Contraction ....................... C–10

D-1.

FCSS Primitive Function................................................................................................. D–2

7830 7402–014

Examples

8–4. 8–5.

Mapping a Reentrant Program .................................................................................... 8–4 Mapping a Reentrant COBOL Program ..................................................................... 8–5 Collecting an ASCII COBOL Self-Initializing or Self-Destructive Program ........................................................................................................................ 8–6 ASCII COBOL UDS/TIP program ................................................................................. 8–11 Partial Word Fields ......................................................................................................... 8–11

9–1. 9–2. 9–3. 9–4.

Calling PADS .................................................................................................................... 9–12 Using the PADS TIPLOG$ Procedure ........................................................................ 9–12 Using the PADS DISPLAY Command ........................................................................ 9–13 Using the PADS TDIAG$ Procedure .......................................................................... 9–13

7830 7402–014

xv

8–1. 8–2. 8–3.

Examples

xvi

7830 7402–014

Section 1 Introduction ClearPath OS 2200 Transaction Processing, also known as TIP, is a modular extension of the OS 2200 operating system. TIP is the basis for a high-performance system in which an input message from a user at a remote terminal causes the execution of an application program. The program accesses the application database and returns a response to the user. See the Transaction Processing Conceptual Overview for a complete introduction to the TIP environment. This section is a summary of the information that may be required for your application program environment. It presents general TIP concepts and directs you to the information in this manual or in other documents in the library. The usefulness of this manual depends on the message handler, data handler, and programming language used for your applications. A sample application is used to illustrate the features of TIP application programs. See the UCS Application Development Programming Guide for further information and examples of extended mode programming with the Universal Compiling System (UCS).

1.1. About This Manual This document is for applications programmers who work in an OS 2200 TIP environment and contains the following:

1.1.1.

•

A description of the TIP application programming environment

•

Information about using TIP primitives and functions for file access and message handling

•

Specific information for program types and programming languages

•

Instructions for testing applications programs

Documentation Updates This document contains all the information that was available at the time of publication. Changes identified after release of this document are included in problem list entry (PLE) 18978504. To obtain a copy of the PLE, contact your Unisys representative or access the current PLE from the Unisys Product Support Web site: http://www.support.unisys.com/all/ple/18978504

Note: If you are not logged into the Product Support site, you will be asked to do so.

7830 7402–014

1–1

Introduction

1.1.2.

Notation Conventions This manual follows certain conventions throughout, in format descriptions: •

If text appears in uppercase in a format statement, you must enter it exactly as it is spelled there: CALL DISCON

•

If text appears in italics, you supply the appropriate values when you use the format: CALL CONECT (parameters)

In text, tables, and figures, a leading zero (0) indicates that a number is octal, as in 020 (16 in decimal); otherwise, the number is decimal.

1.2. TIP File Control and Scheduling The main features of the TIP system are a subset of Exec file control, referred to as TIP File Control, and TIP scheduling. The TIP system administrator uses a utility to define and manage TIP files in cataloged Exec files. These files are assigned to the TIP system so that it is not necessary for the user to assign files. The administrator designates other TIP files as TIP program libraries and copies executable programs in these libraries. The attributes of these programs are defined by the administrator in the system’s validation table (VALTAB). The user must enter the transaction code contained in the VALTAB record to request execution of the program. The TIP program is loaded from the library and scheduled for execution in response to this request from the user’s terminal. If TIP File Control is the data handler for your TIP files, your programs can read and write to these files using TIP File Control primitives. These primitives are subroutines that format calls with Executive requests (ER) and eliminate the need for direct requests to the system for file control functions. TIP File Control functions are described in detail in Section 3. Batch and demand programs not defined as TIP programs in the VALTAB can connect to TIP for execution in a transaction environment. See Section 2.1.1 for additional information on these TIP primitives. The TIMER TIP primitives allow one program to schedule execution of another program. See Section 2.3 for more information on these primitives.

1–2

7830 7402–014

Introduction

1.3. Programming Languages The following programming languages are supported in a TIP environment: •

UCS FORTRAN and ASCII FORTRAN

•

UCS C

•

UCS Ada

•

UCS COBOL and ASCII COBOL

•

MASM

This manual provides some information on writing and compiling TIP application programs in various languages in Section 8. You should, however, consult the manual for the language you are using for detailed information. See the UCS Application Development Programming Guide for information about writing, compiling, and linking extended mode TIP programs.

1.4. Message Handling Messages in a TIP environment are input, output, or pass-off (between programs). There are two types of message handlers: the Message Control Bank (MCB) and COMPOOL. MCB provides message recovery as well as basic services for input, output, and pass-off messages. COMPOOL message buffers exist in and are managed by the System Interface for Legacy Application Systems (SILAS). The TIP message-handling primitives described in Section 2 use COMPOOL for message handling. If your site uses MCB, your programs can use an MCB primitive interface that emulates COMPOOL. The MCB primitive interface is intended only to facilitate migration from COMPOOL to MCB; new applications should use the MCB packet instead of the TIP primitives. If you use the Display Processing System (DPS 2200) as the screen interface for your programs, DPS 2200 can format the MCB packet. COMPOOL can be used only with basic mode programs. MCB is the required message handler for all programs that use extended mode processing, which includes all programs written in UCS languages. See the MCB documents for your UCS language.

1.5. Database Types TIP File Control handles a TIP database that may contain file control superstructure (FCSS) or Freespace files. FCSS files are direct-access files with a fixed record length. A program accesses FCSS files by referencing records. A Freespace file is a modified FCSS file in which record space is allocated as needed and released when it is no longer required. Programs access a Freespace file using a record key. TIP File Control primitives are used to access either type of TIP file. FCSS is the principal TIP File Control primitive. FCSS has 21 separate functions. These are described in Section 3.5. See the Transaction Processing Administration and Operations Reference Manual for additional information on FCSS and Freespace TIP files.

7830 7402–014

1–3

Introduction

The Universal Data System (UDS) provides a single database architecture that supports three database managers: the Relational Data Management System (RDMS 2200), Data Management System (DMS 2200), and Shared File System (SFS 2200). A UDS/TIP interface allows a UDS database manager to handle TIP files in place of TIP File Control. Appendix C contains descriptions of the UDS/TIP ERs. These descriptions are informational only; you do not make calls to TIP primitives in UDS application programs. See the documents for the UDS database managers for information on access to a UDS/TIP database.

1.6. Frequently Accessed Data Files A TIP common data bank file (TCDBF) can be used for high-speed access to relatively static data. A TCDBF is a specially formatted TIP FCSS file that exists both on disk and in memory. Any application program can access the data copy in main storage. Programs can use the FCSS primitive to read or write to a TCDBF in either basic or extended mode. See the Transaction Processing Administration and Operations Reference Manual for a detailed description of TCDBFs. A TCBDF might be used instead of, or in addition to, KONS. KONS is a fixed-format system and user area that permanently resides in main storage. See Section 5 for descriptions of KONS primitives.

1.7. Recovery Integrated Recovery is an OS 2200 system feature that protects your application programs and the integrity of your database. An application is defined by system configuration parameters as a recoverable application group consisting of database files, programs, and some system files. See Section 4 for information about making your programs recoverable and a description of TIP primitives that may be included in your programs to aid in the recovery process. See the Integrated Recovery Conceptual Overview for a detailed introduction to Integrated Recovery.

1.8. Security TIP security features can be included with any of the available security options. If your site uses Security Option 3 or if TIP File Security is configured, see Section 8 for a description of coding requirements for your programs. See the Security Administration for ClearPath OS 2200 Help for a general description of security features and options.

1.9. Multiple Hosts The Extended Transaction Processing Architecture (XTPA) features permit execution of transaction processing applications on multiple hosts. Although XTPA has little effect on application programming, you cannot use several FCSS primitives in an Extended Transaction Capacity (XTC) system because of lock handling (see 3.5). If your site has an XTPA system, consult the documents relating to the feature grouping for general information on system setup and maintenance.

1–4

7830 7402–014

Introduction

1.10. TIP Programs How you use this manual depends on whether you write applications in extended or basic mode. Extended mode programs are written in a UCS language and compiled by a UCS compiler. Basic mode programs are written in an ASCII language and compiled by an ASCII compiler. The Collector produces an executable absolute element from the relocatable compiled program. Parameters that affect application programs are set in the system configuration. Other parameters are set by the TIP administrator in the VALTAB for each program. There are two basic types of TIP programs: standard TIP programs and High-Volume TIP (HVTIP) programs. Standard TIP programs are loaded from library files maintained by the SUPUR utility. These programs are self-destructive, self-initializing, reentrant, or online batch. Non-TIP programs that connect to TIP for execution are loaded from Exec files, not TIP program library files. HVTIP programs are loaded from program libraries maintained using the TPUR utility. These reentrant programs have a unique modular structure with a single initial control program and a number of subprograms. For information on HVTIP programs, see Sections 7 and 8. See Section 6 for information on enhancing program performance. See Section 8 for special programming requirements and additional TIP primitives. See Section 9 for details on testing programs and using diagnostic information.

1.11. Basic Transaction Program Design A typical transaction program follows these steps: 1.

Reads its input message

2.

Processes the information obtained from the input message. This step can include

3.

•

Getting information from the database

•

Changing information kept in the database

Produces an output message and sends it back to the terminal. The output message usually contains database information to confirm that the program has done its job.

1.11.1. Scope of a Transaction Program In designing TIP application programs, it is important to keep the programs as simple (and small) as possible. The philosophy of TIP software is to schedule a unique execution of the program to handle each message. As a rule, a transaction program handles a single data item or “transaction” rather than a stream (batch) of input items. You certainly could design a transaction program that would be able to handle a variety of input, analyze the message to determine what it is to do, and then give control to the particular routine in the program to perform the required activity. It might be convenient for you to have all the code for a particular application in the same program. This, however, defeats the purpose of scheduling a specific program to handle a specific transaction. Main storage would contain much unused code. 7830 7402–014

1–5

Introduction

The most efficient way to use the system is to create small programs that handle each different input type. For example, if different messages access different database files, you would probably want to consider handling them in different programs. Other things to consider in your design are whether to read or search the TIP main storage file and whether to schedule other transaction programs through yours.

1.11.2. Site Control of Program Types The type of transaction programs you can use on your system is usually determined by the site administrator. Depending on the level of TIP security your site uses, you may not be allowed to use transaction programs with multi-input features, such as multiple INITAL. Also, some types of programs (such as HVTIP) are compatible only with lower levels of TIP security. See Section 3 for more information on writing transaction programs for operation with the TIP security features configured. If you are designing programs for use on an XTC system, see Section 3 on some of the aspects of operating with shared TIP database files.

1.11.3. Skeleton Transaction Program The flowchart in Figure 1–1 describes the design of a skeleton transaction program from initialization to termination. See Section 7 for a description of HVTIP modular program design.

Figure 1–1. Skeleton Transaction

1–6

7830 7402–014

Introduction

1.12. TIP System Parameters During configuration and generation of your site’s Exec system, the following TIP configuration values are set for your TIP system: •

How many permanent TIP files can be set up by the site administrator for your TIP system

•

Whether transaction programs can set up temporary and scratch TIP files

•

How many transaction programs the site administrator can register with your TIP system

•

Whether transaction programs use these features: −

HVTIP

−

Freespace

−

TIMER

−

KONS

−

Program-to-program pass-off

If you would like a detailed description of these parameters, see the parameter table in the Exec Installation and Configuration Guide.

1.13. Transaction Program Parameters The site administrator sets parameter values for individual transaction programs through the VALTAB when registering the programs with TIP. These parameter values are program attributes that indicate which system features a program uses and how it executes. Three parameter values must be set in a VALTAB entry for a transaction program: •

The program name

•

The unique transaction code, by which the user program can call the program

•

The unique program number, which the VALTAB index (VINDEX) uses to locate the VALTAB entry

Other VALTAB parameters are optional and usually have default values. This programming guide indicates which program attributes affect the design and development of your programs. All of the VALTAB parameter fields are described in the Transaction Processing Administration and Operations Reference Manual.

7830 7402–014

1–7

Introduction

Table 1–1 identifies the parameter fields and the keywords associated with them. Table 1–1. VALTAB Parameter Fields and Keywords Keyword

1–8

Parameter

none

Program number

ACT[ION]

Transaction code

AUD[IT]

Audit trail number

[BML]OWER

Lower address limit of basic mode D-bank.

[BMU]PPER

Upper address limit of basic mode D-bank.

COP[IES]

Concurrency

DAS[IZL]

Number of word blocks per additional large activity-level D-bank

DBK[SIZ]

Size of primary HVTIP D-bank

DBK[SIZ]

Size of HVTIP D-bank

DBM[AX]

Maximum size of program’s main D-bank

DEL[ETE]

Delete transaction code

DLA[CTCNT]

Number of additional large activity-level D-banks

DLP[RGCNT]

Number of additional large program-level D-banks

DPS[IZL]

Number of word blocks per additional large program-level D-bank

DSA[CTCNT]

Number of additional small activity-level D-banks

DSL[OWER]

Lower address limit for additional small program-level and activity-level D-banks

DSP[RGCNT]

Number of additional small program-level D-banks

DSU[PPER]

Upper address limit for additional small program-level and activity-level D-banks

IND[ICATORS]

VALTAB indicators

LEV[EL]

Switching level

MAS[K]

Terminal class

NAM[E]

Program name

OPT[IONS]

Execution options

PCT[BLOCKS]

PCT size

PRG[TYP]

Program type

PRI[ORITY]

Execution priority

PRT[DEVICE]

Printer

QPR[IORITY]

Queuing priority

REC[OVERY]

Recovery options

7830 7402–014

Introduction

Table 1–1. VALTAB Parameter Fields and Keywords Keyword

Parameter

RUN[TIME]

Run time

STA[TUS]

Program status

STF[ILE]

Standard file selector

TCA[SIZ]

TCA bank size

TIM[E]

Maximum wall clock time

TPM[ON]

TIP Performance Monitor

WAI[TQ]

Wait queue length

The setting of program status options (STATUS) in a VALTAB entry indicates whether the program uses COMPOOL or the MCB for execution. If your site uses both COMPOOL and the MCB, either alternately or concurrently, you need to know only if transaction messages generated during program execution are to be recoverable; the request formats of the communications primitive (Section 2) are the same for either the MCB or COMPOOL, because of the MCB primitive interface for TIP. But if you are writing programs for an environment without COMPOOL, you should use the MCB packet interface described in the MCB Programming Reference Manual for communications requests.

7830 7402–014

1–9

Introduction

1–10

7830 7402–014

Section 2 Basic Program Structure Any TIP application program must use the following types of commands: •

An initializing command to start execution

•

Message handler commands to retrieve input and send output

•

A terminating command to terminate execution

A transaction program must begin with an initialization request to establish an interface with TIP as soon as program execution begins. Once this link is established, the program can retrieve the input message sent by the TIP user who entered the program’s transaction code. The user’s terminal has a position identifier (PID) number, a unique identifier in your TIP system. An Extended Transaction Capacity (XTC) system has files that are shared between the hosts. However, each host has its own local Message Control Bank (MCB) and COMPOOL, and these provide message handling only within their local host. See 3.4 for more information on the XTC system.

2.1. Initializing and Terminating a Program This subsection describes the primitives used to initialize and terminate TIP programs.

2.1.1.

Batch-Connected and Online-Batch Programs Batch-connected and online-batch programs use the CONECT and DISCON primitives or the MCB initialization and termination functions to initialize and terminate execution. Each CONECT in a program must have a matching DISCON. A program can have any number of CONECT-DISCON pairs. Both CONECT and DISCON are supported in extended mode.

Accessing TIP Facilities—CONECT Primitive The CONECT primitive lets an online- or offline-batch program gain access to the facilities of the online system. On returning from this call, the program’s access to the online system is determined by its program options, which are further restricted by the connect level. Begin the program with a CONECT call if it is a batch-connected program.

7830 7402–014

2–1

Basic Program Structure

Table 2–1 shows the CONECT request formats. Table 2–1. CONECT Request Formats Language

Request Format

ASCII or UCS FORTRAN

CALL CONECT (parameters)

UCS C

CONECT (parameters);

UCS Ada

CALL C_ONECT (parameters);

ASCII COBOL

CALL ’CCONET’ USING parameters.

UCS COBOL

CALL ’CONECT’ USING parameters.

MASM

CALL CONECT parameters.

A CONECT primitive request contains either three or four parameters, as follows: 1.

The first parameter is the address of an input buffer area in the program’s D-bank. In extended mode, the contents of this parameter may have any value.

2.

The second parameter is the address of a 1-word field containing the buffer size in words. If no input is expected, enter zero for the buffer size. In extended mode, the contents of this parameter can have any value.

3.

The third parameter is the address of a 1-word field formatted into two halves. The leftmost half (H1) contains the recovery options if the program is to be established as recoverable under Integrated Recovery. The rightmost half (H2) contains the connect level for the program. Recoverability Options •

If you do not want the program to be recoverable, H1 should be zero.

•

If you want the program to be recoverable, you must set bit 17 in H1. Once the program has been identified as recoverable, you can set the other recovery option bits in H1. Table 2–2 identifies each bit and the results of setting it or leaving it clear. Table 2–2. Recovery Options Parameters

Bit

Function

If Clear

If Set

Relates to This VALTAB REC Option

12

Recoverable lock release action on commit (applies only to recoverable files).

Release only those locks that have been explicitly released (via RU, UN, UA, or WR). If a lock has not been explicitly released, retain the lock.

Release all locks at commit whether or not a specific release action has been submitted for those locks.

U

13

None

N/A

N/A

N/A

2–2

7830 7402–014

Basic Program Structure

Table 2–2. Recovery Options Parameters

Bit

Function

If Clear

If Set

Relates to This VALTAB REC Option

14

None

N/A

N/A

N/A

15

Rollback request handling.

Step resume.

Step terminate.

X

16

Commit request handling.

Step advance.

Step terminate

Y

17

Program recoverability.

Program is not connected as Program connected as a recoverable. recoverable program step.

Z

Connect Level In H2, use the connect level numbers 1, 2, or 3. Level 1, system open, usually allows complete execution option capabilities; execution options I through Z are listed in Table 2–2. Level 2 usually allows fewer capabilities than level 1. Level 3 allows the smallest number of capabilities. These capabilities are configured with system configuration statements OPTMSK1, OPTMSK2, and OPTMSK3, which are described in the Exec Installation and Configuration Guide. 4. The fourth parameter is the address of a 1-word field containing the integrated recovery application group number. Use the following information to determine whether you need to specify this optional parameter: •

A recoverable program (that is, recovery option bit 17 is set in H1 of parameter 3) that uses the COMPOOL interface automatically connects to application group 1 unless you specify a different application group number for this parameter.

•

A recoverable program that uses the MCB is automatically connected to the application group associated with the TIP library that you specify when you collect or link the program. (Each application group has its own TIP$*TIPLIB$ file and its own MCB.) You can omit this parameter because any value that you specify here is ignored.

•

You cannot connect a recoverable program to application group 0; if you specify 0 for this parameter, 1 is assumed.

•

A nonrecoverable program (that is, H1 of parameter 3 is zero) is automatically connected to application group 0; you can omit this parameter because any value that you specify here is ignored.

If your program issues a CONECT request when it is already online, the call changes only the connect level. Its recovery options and application group number are obtained from its VALTAB entry.

7830 7402–014

2–3

Basic Program Structure

A batch-connected program is activated by an @XQT statement in a runstream. The program is mapped and executed in standard OS 2200 Exec system format. You select from XQT options I through Z, which are listed in Table 2–3; these options are the same as the execution options that can be specified in the OPT field of a TIP program’s validation table (VALTAB) entry. If you select an XQT option that is not in the connect level specified for the program in H2 of parameter 3, that option is turned off when your program connects. Table 2–3. Execution Options Option

2–4

Description

I

Let the program use the file control superstructure (FCSS) CG function to change the characteristics of a permanent TIP file; see B.3.

J

If the buffer address supplied on an FCSS UN (unlock) function does not match that of any FCSS locks held by the activity, leave all locks intact and return a 0 status. (Without the J option, all locks are released.) This allows a user program to move records among buffers and issue a UN function from any buffer without losing all of its outstanding locks.

K

Ignore common banks when creating a program dump upon abnormal termination. If not set, common banks based at the time of termination are included in the dump.

L

Permit TIP tape logging and accounting or TIP system logging for this program; see the Transaction Processing Administration and Operations Reference Manual for detailed information.

M

Let the maximum number of print pages be exceeded.

N

The program must schedule another program or send an output response before terminating.

O

The program executes in test mode; see Section 9.1.

P

Let the program change the setting of these options during its execution, by using the UOPTOR and UOPAND primitives. Also, let the program manipulate flagbox and logbox bits with the FOXER primitive; see 8.4.

Q

Let the program manipulate the KONS security directory; see Section 5.

R

Let the program release logical COMPOOL blocks through a CRELOG primitive call; see Section 2.2.2.

S

Let the program write to the protected KONS area; the program can read this area with or without this option. See Section 5.

T

Program produces a TIPDIAG$ file upon abnormal program termination when the flagbox bit TIPTRACE is set. If the program is a zero overhead object module (ZOOM), an entry is also produced in the TIP error history file. See Section 9.2.

U

Let the program use the FCSS RE function (B.3) to release TIP files from an Exec file and the FCREG primitive (B.2) to register an Exec file with TIP or to deregister it.

7830 7402–014

Basic Program Structure

Table 2–3. Execution Options Option

Description

V

Allow physical COMPOOL requests, which are described in the Transaction Processing Administration and Operations Reference Manual.

X

Let the program access protected system files or TIP files belonging to another application group. Allow use of FCSS maintenance functions, which are described in the Transaction Processing Administration and Operations Reference Manual.

Y

Program executes in training mode; see Section 9.1.

Z

Program produces a SEXEM dump upon abnormal termination if the program is an absolute. If the program is a ZOOM, this option is equivalent to the T option. See Section 9.2.

Disconnecting the Program from TIP Facilities—DISCON Primitive The DISCON primitive lets an online batch or offline batch or demand program that has made a previous CONECT call inform the online system that the program’s requirements have been met. The online system discards all knowledge of the program, including the release of any outstanding locked records. Do not place arguments on this call. Table 2–4 shows the DISCON request format for each programming language. Table 2–4. DISCON Call Formats Language

Request Format

ASCII or UCS FORTRAN

CALL DISCON

UCS C

DISCON();

UCS Ada

CALL D_ISCON;

ASCII COBOL

CALL ’CDISCN’.

UCS COBOL

CALL ’DISCON’.

MASM

CALL DISCON.

For every CONECT primitive, a DISCON must eventually follow. A program should be disconnected to lower its priority and when TIP facilities are not immediately necessary. If you use the DISCON primitive and your program has already been disconnected from the online system, the request is treated as a request for “no operation.” The batch program can connect and disconnect as often as desired, provided a DISCON primitive follows each CONECT primitive.

7830 7402–014

2–5

Basic Program Structure

2.1.2. TIP Programs This subsection describes the INITAL and TERMN8 primitives.

Initializing the Program and Retrieving the Input Message—INITAL Primitive A transaction program must begin with an initialization request. Programs using the COMPOOL primitives would use the INITAL primitive. Programs directly accessing the MCB would use the TRINIT$$ function. Your transaction program first initializes TIP using the INITAL primitive and retrieves its input data, normally a screen image. The internal primitive requests made in the INITAL primitive are for a read (CDATAC) or a read and release (CDATCR) function, with implied start address 1. Your program can call this primitive successively during a single execution to allow the processing of additional input messages queued for the program. You can choose not to acquire the input at INITAL time by setting the length to 0, in which case the program may subsequently make a read (CDATAC) or read and release (CDATCR) function request (see Section 2.2.1). If the input message is not released at this time, it must be specifically released before termination, or the transaction terminates in error. For the input to be released at this time, the number of words specified in the call must be at least as great as the word size indicated in the message parameter area. The INITAL request sets the "program active" status indicators for your online program, establishes the execution ID, initiates system occupancy time, and delivers an input message to the program’s D-bank. Table 2–5 shows the INITAL request format for each programming language. Table 2–5. INITAL Request Formats Language

Request Format

ASCII FORTRAN

CALL INITAL (parameter1,parameter2)

ASCII COBOL

CALL ’CINIT’ USING parameter1, parameter2.

MASM

CALL INITAL parameter1,parameter2.

The INITAL request requires two parameters: •

Address of an area in the program’s D-bank

•

In H1, the escape address; in H2, the size of the buffer area in words

If no input is available when INITAL is called, control returns to the escape address specified in H1 of the second parameter word, or, if H1 contains 0, the program terminates.

2–6

7830 7402–014

Basic Program Structure

If the length of the logical COMPOOL record assigned to the transaction exceeds the word count specified, the program must use other calls to retrieve the balance of the record and to release the COMPOOL blocks. If the word count specified in the call is equal to or greater than the length of the logical COMPOOL record assigned to the transaction, the COMPOOL record is transferred into the program’s D-bank and released. The lower half (H2) of the first word contains the number of words transferred (the length of the logical COMPOOL record).

Terminating the Program—TERMN8 Primitive The transaction program must end with a TERMN8 primitive request. The TERMN8 primitive stops program execution. Place this primitive as the last executable statement in the program. As shown in Table 2–6, the exact request format depends on the programming language you are using. Programs directly accessing the MCB would use the TERM$$ function. Table 2–6. TERMN8 Request Formats Language

Request Format

ASCII FORTRAN

CALL TERMN8

ASCII COBOL

CALL ’CTRMN8’.

MASM

CALL TERMN8.

If there is outstanding I/O, it is completed. If KONS or TIP File Control locks are held, they are released. If your program must respond to a terminal and has not done so, a message is transmitted, and your program terminates in error.

2.2. Using Message-Handling Primitives This subsection describes the primitives used for handling input and output messages.

2.2.1. Reading an Input Message To read an input message, use a CDATAC or CDATCR primitive request. Programs directly accessing the MCB use the RECV$$ and INPREL$$ functions.

Reading the Message—CDATAC Primitive The COMPOOL record is not released by the CDATAC request. The program must use another request to release the record before termination; otherwise the record is released when the program terminates. The CDATAC request requires the following parameters: •

CMPBUF, the address of a buffer area in the program’s D-bank where the record is transferred.

7830 7402–014

2–7

Basic Program Structure

•

COUNT, which contains two fields of information. The address to receive control if an I/O error occurs is in H1 (except for ASCII COBOL programs), and the length of the record to be read is in H2. For ASCII COBOL programs, H1 is an error flag that is set to -1 on return if an I/O error occurs. For programs in other languages, the H1 field is optional; if it is not provided, the program receives a type 12 contingency error if an I/O error occurs.

•

START, the relative position in the logical record where the transfer begins.

CMPBUF is at least 1 word long if COUNT is 0; otherwise, CMPBUF is COUNT words long. If COUNT is 0 or input COMPOOL is not assigned to the program, the first word of CMPBUF is set to 0. If COUNT is equal to or greater than the length of the record, the transfer terminates with the transfer of the last word of the record.

Reading and Releasing the Message—CDATCR Primitive If the last word of the record is transferred, the record is released. If the last word is not transferred, the program must make a request to release the record before terminating, or the record is released when the program terminates and the program is marked as terminating in error. The CDATCR request requires the following parameters: •

CMPBUF, the address of a buffer area in the program’s D-bank to which the record is transferred.

•

COUNT, which contains two fields of information. The address to receive control if an I/O error occurs is in H1 (except for ASCII COBOL programs), and the length of the record to be read is in H2. For ASCII COBOL programs, H1 is an error flag that is set to -1 on return if an I/O error occurs. For programs in other languages, the H1 field is optional; if it is not provided, the program receives a type 12 contingency error if an I/O error occurs.

•

START, the relative position in the logical record at which the transfer is to begin.

CMPBUF must be at least 1 word long if COUNT is 0; otherwise, it must be COUNT words long. If COUNT is 0 or input COMPOOL is not assigned to the program, the first word of CMPBUF is 0. If a transaction program registers a routine to handle abort contingencies, the record is released if that routine is entered. See the Executive Requests Programming Reference Manual. Any attempt to read a COMPOOL record causes the first word of the buffer to be set to 0. If COUNT is equal to or greater than the length of the record, the transfer terminates with the transfer of the last word of the record. If START is equal to 1, the record length is found in H2 of the first word of CMPBUF.

2–8

7830 7402–014

Basic Program Structure

2.2.2. Handling an Output Message You might need to use these message handler primitives that affect your program’s output record before it is transmitted to the terminal user: CSTLOG, CSTOVR, and CRELOG.

Storing a New Output Message—CSTLOG Primitive The CSTLOG primitive creates a new message, which is stored as the output message. Any existing incomplete output or pass-off message is released. Table 2–7 shows the CSTLOG request format for each programming language. Programs directly accessing the MCB would use the SEND$$ and CANCEL$$ functions. Table 2–7. CSTLOG Request Formats Request Format

Language

ASCII FORTRAN

CALL CSTLOG (parameter1,parameter2)

ASCII COBOL

CALL ’CCSTLG’ USING parameter1,parameter2.

MASM

CALL CSTLOG parameter1,parameter2.

The CSTLOG request requires the following two parameters: •

In H1, the code specifying the output storage type; in H2, the location in your program’s D-bank of the new data The output storage type is one of the following values:

•

1

Core COMPOOL

2

Mass storage COMPOOL (primary)

3

Mass storage COMPOOL (secondary)

In H1, the address to receive control if an I/O error occurs; in H2, the length of the record to be stored

The first word of the record must contain the indicator character in S3 and the length of the record in H2. If your program is in ASCII COBOL, -1 is returned to your program in H1 of the second argument if an I/O error occurs. If you do not provide the field, a type 12 contingency error message is returned.

7830 7402–014

2–9

Basic Program Structure

Overlaying or Extending an Output Message—CSTOVR Primitive The CSTOVR primitive replaces part of a message or adds message text that is not part of the message parameter area (MPA). It overlays or extends the existing output message. Table 2–8 shows the CSTOVR request format for each programming language. Table 2–8. CSTOVR Request Format Request Format

Language

ASCII FORTRAN

CALL CSTOVR (parameter1,parameter2,parameter3)

ASCII COBOL

CALL ’CCSTOV’ USING parameter1, parameter2, parameter3.

MASM

CALL CSTOVR parameter1,parameter2,parameter3.

The CSTOVR request requires the following three parameters: •

The location in your program’s D-bank from which the data is to be transferred

•

In H1, the next statement, where control is passed if an I/O error occurs; in H2, the length of the record to be overlaid

•

The relative address in the output record where the first word of data is transferred

If your program is in ASCII COBOL, -1 is returned in the next statement field if an I/O error occurs. For programs in other languages, this field is optional. If you do not provide the field, a type 12 contingency error code is returned in the event of an I/O error. If an output record has not been assigned to your program, the CSTOVR call overlays the input record, which then becomes the output record. This feature allows program pass-off by permitting the MPA to be updated without requiring your program to read and store the entire output record.

Releasing a Partially Staged Message—CRELOG Primitive The CRELOG primitive releases a partially staged output or pass-off message. It releases the input message if the message is not recoverable; otherwise, the message is not released until the end of the step. Parameters are not required with this primitive. Table 2–9 shows the CRELOG request format for each programming language. Table 2–9. CRELOG Request Formats Language

2–10

Request Format

ASCII FORTRAN

CALL CRELOG

ASCII COBOL

CALL ’CRELOG’.

MASM

CALL CRELOG.

7830 7402–014

Basic Program Structure

2.2.3. Scheduling Another Program: User-to-User Pass-Off Use one of these primitives to schedule another transaction program: •

RTSCHD, which does not require the system to read the MPA to find out which program to schedule

•

RTRANU, which does require a read of the MPA

A program using the COMPOOL interface can pass off a record only to another program that is also using COMPOOL, not to a program that is using MCB. Likewise, a program using MCB can pass off a record only to another program that is also using MCB.

Scheduling by Transaction Code or by Number In word 1 of the MPA, you must provide the transaction code of the program you want yours to schedule. As in other routing requests, the message can be stored by a specific request, or implicitly in the pass-off request. If the configuration parameter TPSNUM is turned on, you can schedule another program by program number. In this case, include the program number in word 4 of the MPA rather than the transaction code in word 16.

Pass-Off Without an MPA Read—RTSCHD Primitive The RTSCHD primitive requests the scheduling of another transaction program. Your program supplies the transaction code and other parameters necessary to queue the request. This scheduling interface is efficient because the system does not have to read the MPA of the output message to schedule the program. The output record passed from your program becomes the input message of the scheduled program. To call the RTSCHD primitive, use the format that is appropriate for your programming language (see Table 2–10). Table 2–10. RTSCHD Request Formats Language

Request Format

ASCII FORTRAN

CALL RTSCHD (parameter1,parameter2,parameter3)

ASCII COBOL

CALL ’CRTSCH’ USING parameter1,parameter2,parameter3.

MASM

CALL RTSCHD parameter1,parameter2,parameter3

7830 7402–014

2–11

Basic Program Structure

The RTSCHD request requires three parameters: •

0 (required)

•

The transaction code or the program number

•

The program’s status bits (see word 1, S1, of the MPA) in H1 and the input terminal-id (PID) in H2

If the program is to be scheduled by transaction code, enter its transaction code in Fieldata in parameter field 2, left-justified and space-filled. If your system is configured for scheduling by program number, you can enter the program number (from the program’s VALTAB entry) instead, but it must be in the range 0 to 4095. The output message-id is taken from the SLOP table (see C.5). Your program must have previously stored the output message. If the schedule packet cannot be allocated due to lack of resources, your program terminates in error with the error type 035.

Pass-Off with an MPA Read—RTRANU Primitive The RTRANU primitive is similar to RTSCHD. It passes a message to another transaction program. The message may have been stored previously, or it may be stored in conjunction with this request. Necessary parameters are stored in the MPA of the message. This interface may require more system overhead than RTSCHD, because the system must read the MPA if the output message is not being stored with this request. To call RTRANU, use the format that is appropriate for your programming language (see Table 2–11). Table 2–11. RTRANU Request Formats Request Format

Language

ASCII FORTRAN

CALL RTRANU (parameter1,parameter2)

ASCII COBOL

CALL ’CRTRNU’ USING parameter1,parameter2.

MASM

CALL RTRANU parameter1,parameter2.

The two parameters in the RTRANU request, which is coded the same for MCB as it is for COMPOOL, are the following: •

The code of the type of COMPOOL record requested (H1) and the location of the record in the program’s D-bank (H2) The COMPOOL type is one of the following values:

2–12

1

Core COMPOOL

2

Mass storage COMPOOL (primary)

3

Mass storage COMPOOL (secondary)

7830 7402–014

Basic Program Structure

•

The number of words to be transferred to COMPOOL (H2), which must match word 1, H2 of the MPA

If parameter 1 is nonzero, and if the program has COMPOOL assigned to it, the assigned COMPOOL is released and a new COMPOOL record assigned to the program. If parameter 1 is 0, the output COMPOOL message must have been previously stored. The transaction code in Fieldata (left-justified, space-filled) must be located in word 016. The indicator character in the first word of the MPA must be set to 3 to indicate a pass-off of the message. To schedule by program number rather than transaction code, set the VALTAB program number in T3 of word 4 of the MPA. Only programs having program numbers between 1 and 4095 can be scheduled by number. (Scheduling by program number is configured by setting TPSNUM to a nonzero value.) If you want to schedule by transaction code, set the program number to 0 in word 4, T3. The transaction code, if used, must always be in word 16. If the schedule packet cannot be allocated due to a lack of resources, your program terminates in error with error type 035 returned.

2.2.4. Sending the Output to the User’s Terminal Generally, the last action a transaction program performs before terminating is to send out a reply to the terminal that initiated it. Any transaction scheduled from a terminal should respond to the terminal unless it terminates in error, in which case an error message is sent to the terminal indicating that the transaction erred. After the response to the terminal has been prepared in an output buffer, it is routed to the terminal through the ROUTNG output queue.

Scheduling Output Without an MPA Read—RTOUTP Primitive The RTOUTP primitive is used by a transaction program to place an output message on the SILAS output queue for subsequent delivery to a terminal. The program supplies the necessary parameters to create a new entry on the SILAS output queue. The program must previously have stored an output record. Table 2–12 shows the RTOUTP request format for each programming language. Table 2–12. RTOUTP Request Formats Language

Request Format

ASCII FORTRAN

CALL RTOUTP (parameter1,parameter2)

ASCII COBOL

CALL ’CRTOTP’ USING parameter1,parameter2.

MASM

CALL RTOUTP parameter1,parameter2.

7830 7402–014

2–13

Basic Program Structure

The RTOUTP request requires two parameters: •

Zero if the program does not have the V program option (allow physical COMPOOL requests) set in its VALTAB entry, or CID if the program’s V option is set.

•

Function control in S1, an indicator character in S2, queuing priority in S3, and the PID in H2. To indicate output, the indicator should be greater than or equal to 04 and less than 040.

Note: Step Control queue-item spooling under MCB hinders the effectiveness of any output queuing priority your program supplies for output messages.

Scheduling Output with an MPA Read—RTRANO Primitive The RTRANO primitive passes a COMPOOL record to SILAS as an output message. This call must be accompanied by an output COMPOOL record, stored previously, or by this call. The record contains the output message in proper format for SILAS to translate and transmit to the terminal. The indicator character in the MPA must be set to a value in the range 04 to 037 to indicate output. The system is required to read the MPA to build the SILAS output queue entry if the output record is not being stored in conjunction with this call (that is, if the value in H2 of parameter 2 is 0). RTRANO is supported only in basic mode. Table 2–13 shows the RTRANO request format for each programming language. Table 2–13. RTRANO Request Formats Request Format

Language

ASCII FORTRAN

CALL RTRANO (parameter1,parameter2)

ASCII COBOL

CALL ’CRTRNO’ USING parameter1,parameter2.

MASM

CALL RTRANO parameter1,parameter2.

The RTRANO request, which is coded the same for MCB as for COMPOOL, requires two parameters: •

The code of the type of COMPOOL requested in H1 and the location of the record in the calling program’s D-bank in H2 The COMPOOL type is one of the following values:

•

1

Core COMPOOL

2

Mass storage COMPOOL (primary)

3

Mass storage COMPOOL (secondary)

The number of words to be transferred to the COMPOOL record in H2

If the value of parameter 2 is nonzero and output COMPOOL is assigned to the program, the assigned COMPOOL is released and a new COMPOOL record obtained. If not zero, the value of parameter 2 must match H2 of the first word of the MPA.

2–14

7830 7402–014

Basic Program Structure

2.3. Using TIMER Primitives to Schedule a Program TIMER primitives allow your program to schedule a specified transaction program for execution at a future time, if that program’s VALTAB program number is 4095 or less. The calling program and the program called can use either COMPOOL or the MCB. On an XTC system, TIMER is supported only in the local mode of operation. The use of TIMER scheduling may not be desirable if your site operates with the TIP Message Security feature configured, because this TIP security feature does not control TIMER scheduling. All timing is based on local system time in minutes. The current local time is maintained in a KONS write-protected area in location TIPMIN, at the beginning of user KONS. Its value ranges from 0 to 1439 minutes throughout the day, where 0 represents 12:00 local midnight and 1439 represents 11:59 p.m. Since TIMER scheduling is based on local time, scheduling is unpredictable in the hour before or after a dynamic local time shift. You use a primitive that indicates to TIMER whether the execution is to occur at an absolute future time (a certain number of minutes past local midnight on the day of the request) or at a relative future time (a certain number of minutes past the time of the request).

2.3.1. TIMER Scheduling When calling a TIMER primitive, your program supplies an expiration-id containing the VALTAB program number of the transaction program to be called when the TIMER entry expires. The calling program constructs the 1-word expiration-id as follows: S1 07, to identify the word as a TIMER parameter word rather than as an MCB address. S2 through S4 Data for the called program to receive on an INITAL call. T3 Program number of the transaction to be scheduled. An entry for the TIMER request is added to the TIMER queue when the calling program is executed. When the TIMER queue entry expires, TIP locates the program from the expiration-id and schedules the program for execution. When the online calling program requests a TIMER primitive to make an entry on the TIMER queue, the primitive returns a “release reference” message to the program, which is the same as the second word of the TIMER queue entry. The release reference contains three fields of information:

7830 7402–014

2–15

Basic Program Structure

S1 and S2 Minute-id, which ranges from 0 to 1439, an integer for each of the 1440 minutes in a day. This is based on local time. S3 The day queue-id, which ranges from 1 to TIMDAYS, which is the number of day queues configured in the system. (TIMDAYS cannot exceed 127 or 0177.) The day queue-id for the current day might not be 1. H2 A sequential number, unique to each day queue, assigned by the TIMER primitive when the queue entry is created. Your calling program must save the release reference if the TIMER queue entry is updated or deleted before expiration time. Table 2–14 shows the five TIMER primitives your program can call. Table 2–14. TIMER Primitives Primitive

Description

TIMREL

Schedule a transaction program to run at a specified number of minutes after the time of the request.

TIMABS

Schedule a transaction program to run at a specified number of minutes past midnight on the day of the request.

TIMUPR

Modify the current time of an existing TIMER entry. The modifier is a positive number specifying the number of minutes to be added to the current time.

TIMUPA

Replace the expiration time in an existing TIMER entry with a new expiration time specified in the number of minutes since midnight on the day of the request.

TIMDEL

Remove a TIMER entry that has not yet expired.

2.3.2. Initiating Relative Scheduling—TIMREL Primitive The TIMREL primitive lets you specify the expiration time of the TIMER request as the number of minutes since the current time. The only time unit allowed is minutes. Table 2–15 shows the request formats for the TIMREL primitive. Table 2–15. TIMREL Request Formats Language

2–16

Request Format

ASCII or UCS FORTRAN

CALL TIMREL (parameters)

UCS C

TIMREL (parameters);

UCS Ada

CALL T_IMREL (parameters);

7830 7402–014

Basic Program Structure

Table 2–15. TIMREL Request Formats Language

Request Format

ASCII COBOL

CALL ’CTMREL’ USING parameters.

UCS COBOL

CALL ’TIMREL’ USING parameters.

MASM

CALL TIMREL parameters.

The TIMREL primitive request requires these parameters: •

The number of minutes until expiration time; this value must be nonzero.

•

The location in the program’s D-bank where TIMREL stores the release reference.

•

The expiration-id.

Internally, TIMREL converts the relative time to an absolute expiration time and places the entry on the proper day queue. The expiration of a relative timing request occurs up to 1 minute later than specified, but never earlier. An entry cannot be made whose day queue-id exceeds the number of day queues configured in the system. If an entry is attempted, the program terminates in error.

2.3.3. Initiating Absolute Scheduling—TIMABS Primitive The TIMABS primitive lets you express the expiration time of the TIMER request. Table 2–16 shows the request formats for the TIMABS primitive. Table 2–16. TIMABS Request Formats Language

Request Format

ASCII or UCS FORTRAN

CALL TIMABS (parameters)

UCS C

TIMABS (parameters);

UCS Ada

CALL T_IMABS (parameters);

ASCII COBOL

CALL ’CTMABS’ USING parameters.

UCS COBOL

CALL ’TIMABS’ USING parameters.

MASM

CALL TIMABS parameters.

7830 7402–014

2–17

Basic Program Structure

The TIMABS primitive requires these parameters: •

The expiration time, expressed as the number of minutes past midnight on the day of the request. For example, 720 represents noon today and 2160 represents noon tomorrow.

•

The location in the online program’s D-bank where the primitive stores the release reference.

•

The expiration-id.

Internally, TIMABS converts the time to a day and minute and stores the request in the proper day queue. Expiration occurs after the specified minute. An entry cannot be made whose day queue-id is greater than the number of day queues configured or less than or equal to the current time (as maintained in KONS location TIPMIN). If such an entry is attempted, the program terminates in error.

2.3.4. Updating Relative Scheduling—TIMUPR Primitive The TIMUPR primitive updates by a relative amount any TIMER request that has not yet expired. The original request is absolute or relative. The new timing queue entry results in a later expiration time than the original request. If the original entry cannot be found, the new release reference is zero. Table 2–17 shows the request formats for the TIMUPR primitive. Table 2–17. TIMUPR Request Formats Language

Request Format

ASCII or UCS FORTRAN

CALL TIMUPR (parameters)

UCS C

TIMUPR (parameters);

UCS Ada

CALL T_IMUPR (parameters);

ASCII COBOL

CALL ’CTMUPR’ USING parameters.

UCS COBOL

CALL ’TIMUPR’ USING parameters.

MASM

CALL TIMUPR parameters.

The TIMUPR primitive request requires these parameters: •

The positive number of minutes to be added to the current time

•

The release reference of the timing queue entry to be updated

•

The location in the online program’s D-bank where TIMUPR stores the release reference of the updated entry

The number of minutes added cannot make the expiration time exceed the number of day queues configured, nor be less than or equal to the current time (as maintained in KONS location TIPMIN). If it does, the program terminates in error.

2–18

7830 7402–014

Basic Program Structure

2.3.5. Updating Absolute Scheduling—TIMUPA Primitive The TIMUPA primitive updates to an absolute time any TIMER request that has not yet expired. The original request is absolute or relative. The new timing queue entry results in an earlier or a later expiration time than the original request. If the original entry cannot be found, the new release reference is zero. Table 2–18 shows the request formats for the TIMUPA primitive. Table 2–18. TIMUPA Request Formats Language

Request Format

ASCII or UCS FORTRAN

CALL TIMUPA (parameters)

UCS C

TIMUPA (parameters);

UCS Ada

CALL T_IMUPA (parameters);

ASCII COBOL

CALL ’CTMUPA’ USING parameters.

UCS COBOL

CALL ’TIMUPA’ USING parameters.

MASM

CALL TIMUPA parameters.

The TIMUPA primitive request requires these parameters: •

The new time, in system minutes, when the entry is removed from the queue

•

The release reference of the TIMER queue entry to be updated

•

The location in the online program’s D-bank where TIMUPA stores the release reference of the updated entry

Expiration occurs as soon as possible after the specified minute. The expiration time cannot exceed the number of day queues configured, nor be less than or equal to the current time (as maintained in KONS location TIPMIN). If it does, the program terminates in error.

2.3.6. Deleting a TIMER Entry—TIMDEL Primitive The TIMDEL primitive deletes a TIMER entry that has not yet expired. The original request is absolute or relative. TIMER deletes the request from its queue and returns the expiration-id to the online program requesting the deletion. See Table 2–19 for request formats. Table 2–19. TIMDEL Request Formats Language

Request Format

ASCII or UCS FORTRAN

CALL TIMDEL (parameters)

UCS C

TIMDEL (parameters);

7830 7402–014

2–19

Basic Program Structure

Table 2–19. TIMDEL Request Formats Language

Request Format

UCS Ada

CALL T_IMDEL (parameters);

ASCII COBOL

CALL ’CTMDEL’ USING parameters.

UCS COBOL

CALL ’TIMDEL’ USING parameters.

MASM

CALL TIMDEL parameters.

The TIMDEL primitive request requires these parameters: •

The release reference exactly as returned by the timing primitive when the entry was placed on the queue

•

The expiration-id of the entry being deleted

2.4. Abnormal Termination of Program Execution This subsection explains what might happen during abnormal program termination and tells how to use the ERTERM primitive to handle abnormal termination.

2.4.1. Handling Abnormal Termination—ERTERM Primitive If the TIPTRACE option is set in the flagbox, the error termination primitive (ERTERM) lets your program release control at any point during its execution and obtain a dump of its PCT. This dump includes the status list of the operating program (SLOP) table, main storage queue, switch list, registers, I-bank, and D-bank. To set TIPTRACE, the site administrator uses the BOXER utility, the operator uses the FB keyin, or your program issues a FOXER primitive request (see 8.4). The ERTERM primitive facilitates debugging in an online environment. It can be used at any point where you want to get a dump and stop program execution. At the same time, it lets the rest of the system continue. When an error termination is executed, control is not returned to your program. If there is any outstanding I/O, it is completed; if KONS or TIP File Control locks are held, they are released; if the program must respond to the terminal but has not, a message is transmitted; or, if a COMPOOL record is still assigned to the program, it is released before final termination is allowed. Locks and pending database updates for distributed transaction programs that terminate while in the ready state are retained by the system. The locks and updates are kept until they are explicitly committed or rolled back by another program. Use ERTERM whenever your online program must generate an abnormal termination. ERTERM generates the same dump that is obtained when a program is forcibly terminated by TIP. If your program is to send a special reply to the remote device, it should do so before calling ERTERM. In case ERTERM is repeatedly called by the same program, you can disable the dump it generates by changing that program’s TIPTRACE bit.

2–20

7830 7402–014

Basic Program Structure

2.4.2. Regaining Control after Abnormal Termination When a program terminates abnormally, there are four points at which it can regain control: •

Contingency routine (non-ABORT$/EABT$)

•

Activity TRMRG$ (common bank)

•

ABORT$/EABT$ contingency routine

•

Program TRMRG$ (common bank)

Refer to the Executive Requests Programming Reference Manual for problems that can arise when common banks are registered for contingencies or the TRMRG$ function is loaded.

Contingency Routine (Non-ABORT$/EABT$) If the program regains control through a contingency routine other than ABORT$/EABT$, no automatic rollback occurs. The program can request rollback or resume execution. If no contingency routine exists, an automatic rollback occurs.

Activity TRMRG$ (Common Bank) Next, activity TRMRG$ is honored for each registered common bank (if any). This lets the common bank clean up the departing activity. After any activity TRMRG$ processing, step termination processing occurs for the recoverable step.

ABORT$/EABT$ Contingency Routine If the program was a multiactivity program, all activities must terminate before proceeding with the next stage of termination processing. Upon proceeding, if the program was a batch/demand run connected to TIP, an automatic disconnect occurs and the recoverable identity of the program ceases. If the program was a transaction program, a new recoverable step exists. Control is then given to the ABORT$/EABT$ contingency routine, if appropriate, and the program can resume execution.

Program TRMRG$ (Common Bank) If control is not given to an ABORT$/EABT$ contingency routine, program TRMRG$ is honored for each registered common bank (if any). After any program TRMRG$ processing, program execution is terminated.

7830 7402–014

2–21

Basic Program Structure

2–22

7830 7402–014

Section 3 TIP File Access This section describes the following: •

Basic types of TIP user files and how they are created (3.1)

•

TIP File Control (3.2)

•

Organization of Freespace files and how to access them (3.3)

•

Extended Transaction Capacity (XTC) systems (3.4)

•

FCSS functions for FCSS and Freespace files (3.5)

•

TIP common data bank files (TCDBF) (3.6)

3.1. TIP User Files This subsection describes the basic types of TIP user files and explains how they are created on your system.

3.1.1.

TIP User File Types TIP user files are permanent, temporary, or scratch: •

Permanent TIP user files A permanent TIP file is created in an Exec file that is assigned permanently to TIP; any transaction program can access the TIP file quickly, without having to assign it or release it. Permanent TIP files are created as either simplex or duplex. A simplex file exists as a single copy. A duplex file exists as two copies or legs located in separate Exec files. Although your program references the duplex file as a single TIP file, all writes to the file automatically update both legs.

•

Temporary TIP files A temporary TIP file exists across program executions. Your program can pass it to another program or access it by file number if it is passed by another program.

•

Scratch TIP files A scratch TIP file exists only while your program is being executed. If your program does not release the file, the TIP system releases it after execution.

7830 7402–014

3–1

TIP File Access

If your site uses the Universal Data System (UDS), you can have TIP permanent files that are created as UDS/TIP files, not as regular TIP files. Instead of using the TIP File Control primitives described in this reference manual, see the programming manual for the appropriate UDS logical data manager (DMS 2200, RDMS 2200, or SFS 2200). UDS uses the interface described in Appendix C for UDS/TIP files, but you do not deal directly with this interface in your application programs.

3.1.2. Temporary and Scratch Files for Transaction Programs You can set up temporary and scratch files inside a TIP file through your transaction program. Your program requests file space in a certain type of storage and (usually) releases the file when it is no longer needed. In an XTC system, shared TIP files cannot be used for temporary or scratch files (see Figure 7–1). The site administrator sets up permanent TIP files inside Exec files for the application database. In an XTC system, permanent TIP files can be defined by the site administrator in either the local or the shared TIP directory (see Figure 7–1).

3.2. TIP File Control TIP File Control gives your program access to the permanent files created for your application and to the temporary and scratch files created by your program. TIP also lets you control simultaneous access to your files by other programs.

3.2.1. UDS, Freespace, and FCSS Your program uses FCSS, UDS, or Freespace interfaces to TIP files. TIP primitives, TIP File Control Superstructure (FCSS), and calls to the extended mode FCSS gate give you access to FCSS and Freespace files in both extended and basic mode environments. FCSS files have a fixed record structure, which your program references directly through fixed record numbers. Freespace files have a variable-sized record. Your program references Freespace files indirectly using a record key.

UDS/TIP Interface Through the UDS/TIP interface, UDS prepares the UDS/TIP files for you. If you want to use the UDS/TIP interface, see the UDS operations and programming reference manual for your programming language.

Fixed FCSS Files With an FCSS access file, you have complete file control. You set up the file structure yourself and have your program manipulate the data structures in the file, such as records, pointers, and even empty file space. Your program and others access records in the file through record numbers.

Freespace Files You can gain indirect access and considerable flexibility with a Freespace file. An existing FCSS file is used to establish a Freespace file. The FCSS file may be empty, or it may contain data.

3–2

7830 7402–014

TIP File Access

With a Freespace file, you do not have to handle the allocation and release of file space yourself. The Freespace system manages space in your Freespace file automatically. It gives the file a standard structure and divides the file according to use. You have the system allocate record blocks according to the amount of space you need. The system returns to your program a record key that enables you to locate the record block again. The records are released after they have been used, and the Exec can reallocate the space when it is needed for other records.

3.2.2. Record Locks TIP File Control lets you control access by other programs to the permanent files your program is working with, so that the database cannot be changed until you are through with it. Records stored in temporary and scratch files cannot be locked. TIP File Control and UDS/TIP do not handle file and record locks in the same way. Your program can lock records only in permanent files. Another program cannot update a record or file on which your program holds a lock, but may read a locked record or file. If the file is defined to permit a write without a lock, the other program can also write to the file without checking for a lock. Your program can also release the locks that it holds on records, or terminate without releasing locks. When the program terminates, the system releases any locks that have not yet been released. No locks are retained beyond the life of a program. To prevent multiple updates to the same data at the same time, your program can set record locks (or data locks) in permanent files. When your program requests a lock or a read with locking to a record that is not locked, the TIP system registers a lock for that record. In most cases, if part of the record already has a lock registered by another program, the execution of your program is suspended until the existing lock is released and a new lock can be registered. If satisfying your program’s lock request results in a deadly embrace of locks, the system returns error status information to your program to let it back out of the embrace. But if a read-and-lock function is requested with immediate locking for a record locked by another program, an FCSS error code of 031 is sent to the program, and the program regains control immediately without locking or reading the record. The FCMXLK parameter limits the number of TIP locks that an individual program can hold. There are 21818 total locks possible in any system. The FCMXLK parameter is enforced differently depending on lock usage and scarcity of available locks on the system. For enforcement purposes there are 2 types of locks, 'active' and 'hold until commit.' The active locks have not yet been released. The hold until commit locks have been logically released by the program (via UN or UA), but are still held by OS 2200 on behalf of the program and continue locking a portion of a recoverable file with a deferred update staged to it. Once the deferred update has been applied (at commit), the lock is released to general system availability. If lock usage is less that 90% (more than 10% of locks are available) then individual programs are limited to FCMXLK active locks.

7830 7402–014

3–3

TIP File Access

If lock usage is 90% or above (less than 10% of locks are available) then individual programs are limited to FCMXLK*2 total locks, including both active locks and hold until commit locks. Since locks on recoverable files are retained on the program’s behalf until commit, it is recommended that long running batch-connect or transaction programs should periodically commit with step advance (when logically possible) to apply deferred updates and releases so that the locks are periodically released.

Note: A deadly embrace between FCSS and UDS locks is not detected. Avoid mixing UDS and FCSS locking.

3.2.3. Access to FCSS Files In general, your program accesses an FCSS file through the following: •

The TIP file number

•

The identifier of the starting record

•

The number of words to lock, read from, or write to the file

Temporary and Scratch Files Your program can read from or write to any temporary or scratch file. It is not necessary for your program to check for locks, because locking of records in these files is not permitted. Your program can, however, check to determine whether the processing of file control requests from other programs is complete.

Permanent Files With a permanent file, your program has basic read and write access plus the capability of creating and releasing record locks. Your program can also check for the completion of previously issued read and write requests. If your site uses any of the TIP security features (see 8.3), access to the TIP files can be controlled.

3.2.4. Duplex TIP Files The file control functions performed on a duplex TIP file are automatically performed on both legs (copies) of the file. A fastpath I/O feature reduces the path length for the most common TIP File Control functions. The shorter path is used under the following conditions:

3–4

•

The FCSS function is read (RD), read and lock (RL), or write (WR).

•

The return type is 1 (control is to be returned after the completion of this request) or 3 (control is to be returned after the completion of all outstanding FCSS requests).

•

Test, Training, or Test/Training mode is not set.

7830 7402–014

TIP File Access

•

The word count is the default or, for a Freespace request, equal to the size of the record type.

•

The TIP file is not a UDS/TIP file or a TIP or Freespace system file.

•

The TIP File Security feature (Security Option 1 or higher) is not used.

3.3. Using Freespace Files To write transaction programs using Freespace files, you need to know how the Freespace system sets up and handles Freespace files. You use normal FCSS read and write functions with slight modifications to access Freespace files.

3.3.1. Organization of a Freespace File A Freespace file is an FCSS file that is organized by cells. The basic record size is established when the FCSS file is reserved using FREIPS. Each cell contains the same number of basic records, and each basic record contains the same number of words. A separate bit map defines and controls each cell, where a single basic record is equivalent to 1 bit. One cell is distinguished from another only by the amount of space indicated as free (that is, not allocated) on its bit map. Within a cell, space is allocated proportionately according to a predefined record type. The site administrator defines each record type by the number of basic records that it can contain. Consequently, a cell can be divided into record blocks of various sizes.

Defining Freespace File Parameters The administrator uses the following guidelines in defining the Freespace file: •

Basic record size from 6 to 4,095 words

•

Cell size from 1,024 to 131,072 basic records; must be a multiple of 1,024

•

Record types from 1 to 72 records for each type, up to 8 record types (each larger than the preceding one) for the file

Freespace Record Keys Freespace records are characterized by type and starting (basic) record number. Each Freespace record has a record key. The following figure shows the format for a record key. The record number is the number of the first record in the block, relative to the start of the file. Record type 0

7830 7402–014

Record number 11

12

35

3–5

TIP File Access

Control Blocks In converting an FCSS file to a Freespace file, the FREIPS CREATE command generates bit maps and control blocks for the file. This process is the same whether the file is empty or already contains data. The following types of control blocks are created: •

File header

•

Density map (DMAP) The main control block defines the number of bit maps, the cell size, and other parameters. It keeps a count of the number of free record blocks—the free block count (FBC)—in each bit map; and it keeps track of bit maps that are unavailable for space allocation.

•

Index table The index table contains the record keys for each bit map.

•

Program control packet

•

File statistics packet

3.3.2. Access to Freespace Files During or after the creation of a Freespace file, the site administrator registers the file with FS$SYS, the Freespace system file. Registration copies the control blocks and bit maps from the Freespace file to the FS$SYS system file for all Freespace files in the application group. To request that record space be allocated in a Freespace file, you must specify the minimum amount of space in words you need. During execution of your program, Freespace looks for the bit map with the highest number of records (Free Block Count). This bit map indicates that its cell is most likely to have space available for a record block equal in size to or slightly larger than the space that your program is requesting. When the block is allocated, its record key is returned to your program, and the bit map is updated to indicate that the block is no longer free. When the records are no longer needed, they are released. If you want some function (such as reading, rewriting, or locking) performed on existing Freespace records, your program references them by record key. Once the block of records identified by the record key has been allocated, you do not need to know its size to refer to it again. You can just indicate 0 as the number of words to be affected by the function; the number of words defaults to the number of words in the block.

3–6

7830 7402–014

TIP File Access

3.4. TIP Files and XTC Some transaction processing applications require a throughput that exceeds the capacity of a single host. Several hosts sharing TIP files between them can provide greater capacity than a single-host transaction processing system.

3.4.1. Extended Transaction Capacity System The Extended Transaction Capacity (XTC) system uses shared TIP database files to enhance transaction processing system throughput. A host in an XTC system is defined as having the following components: •

Its own operating system

•

Its own main storage

•

Both local and shared mass storage

•

Hardware record locking for UDS and TIP files across hosts

The features that enable an XTC system to provide concurrent TIP file sharing between hosts include the following: •

The Multi-Host File Sharing (MHFS) feature in the Exec allows independent hosts to use a shared Exec file directory and to have shared access to Exec database files in shared mass storage.

•

The Extended Processing Complex–Locking (XPC–L) provides lock synchronization between XTC hosts concurrently accessing the UDS or TIP database in shared mass storage.

•

The Integrated Recovery Utility (IRU) is used after a system or application group failure to maintain file, database, and transaction message integrity and availability.

3.4.2. TIP FCSS File Directories An XTC system has two types of TIP FCSS directories: •

The local TIP FCSS directory, which contains TIP file definitions local to a specific host. TIP files defined in a local TIP FCSS directory can be assigned only on the host that owns that local directory. These files cannot be accessed (shared) by other hosts in the XTC system. The files in a local TIP FCSS directory can reside in local mass storage or in shared mass storage.

•

The shared TIP FCSS directory, which contains TIP file definitions common to all the hosts in the XTC system. This shared directory resides in shared mass storage, and any changes to definitions by one host are broadcast to the other active hosts in the XTC system. TIP files defined in the shared TIP FCSS directory can be assigned and accessed (shared) by all hosts in the system. The files in the shared TIP FCSS directory reside in shared mass storage.

7830 7402–014

3–7

TIP File Access

3.4.3. Extended Processing Complex An XTC system has one XPC–L, which communicates with each host in the system through block multiplexer channels and acts as an extension of the UDS and TIP record-locking software. The XPC–L uses database lock information that it receives from TIP locking software in the hosts to control access to TIP database files in the shared TIP FCSS directory and, in some cases, TIP database files in the local TIP FCSS directory. XPC–L locking protects the TIP data files from corruption by queuing conflicting lock requests from the hosts. The XPC–L also detects deadlock conditions and notifies the requestors involved. If a TCDBF in the shared TIP FCSS directory has been updated, the XPC–L broadcasts an interhost “TIP invalidate” message instructing other hosts to update their copy of main storage data.

3.4.4. Application Groups Up to 16 application groups can be used on a system, and multiple application groups can be configured on one host. TIP programs associated with a specific application group are denied read, write, and lock access to TIP files associated with any other application groups. In addition to the physical database files associated with each of the numbered application groups, there are files that are not associated with any application group. In general, these files are used by the system for processing that is not specific to a particular application group. The local and shared TIP FCSS directory files, validation table (VALTAB) file, SUPUR program files, and HVTIP library files are examples of such files. These files belong to application group 0 and are accessible by any program in any of the application groups.

Types of Application Groups Two types of application groups can be used in the XTC system: •

Local application group, which is defined and active on only one host

•

Concurrent application group, which is defined and active on more than one host at a time. AG/host refers to the portion of a concurrent application group on a specific host.

Local application groups use local TIP FCSS directory files of the host. These application group files cannot be used by other hosts in the system. Concurrent application groups use files in the shared TIP FCSS directory. These files are under control of RLP hardware locking. This type of application group can have programs active on more than one host at a time.

3–8

7830 7402–014

TIP File Access

Hardware and Software File Locking Hardware locking of TIP files by the XPC–L is external to the hosts, and software locking of TIP files is internal to each host. TIP software locking is the default method for locking files assigned to local application groups and application group 0. XPC–L hardware locking must be used for files assigned to concurrent application groups.

Deadly Interlocks You must be very careful about allowing TIP programs to request access to files reserved under different locking methods (hardware versus software). Undetectable deadly interlocks may result from programs owning locks for files that are not all locked by the same method. Such file interlocks can cause the programs or other site maintenance utilities to hang.

3.4.5. Integrated Recovery for the XTC System Program rollback, short recovery, and long recovery are provided in the XTC system for TIP files assigned to local application groups. For TIP database files assigned to concurrent application groups, Integrated Recovery provides one or more of the following modes of recovery: •

Program rollback

•

Intrahost short recovery for AG/hosts

•

Intrahost and interhost deferred update (medium) recovery for AG/hosts. This database recovery technique can be used if short recovery fails.

•

Host-global long recovery for concurrent application groups. This recovery uses a merged audit trail that is produced using the audit trails from each AG/host assigned to the concurrent application group.

3.4.6. Operating with a Shared TIP Database In an XTC system, each host manages many of its resources independently of the other hosts. But cooperative lock control of shared TIP files and updating of host-local copies of shared data is required for operating multiple hosts from a shared TIP database. Some aspects of operating the XTC system follow: •

Structures for sharing TIP files, TCDBFs, Freespace, and TIP transaction processing are coordinated among all hosts to support concurrent transaction processing.

•

Host-local main storage copies of shared files, such as TCDBFs and the TIP VALTAB file, are updated on all hosts to match corresponding files in shared mass storage.

•

TIP file number usage is coordinated among the hosts.

•

Temporary files and scratch files can be set up only in a local TIP FCSS file directory.

•

Business Information Server files can be used only in the local host mode of operation.

7830 7402–014

3–9

TIP File Access

•

High-Volume Transaction Processing (HVTIP) libraries must be maintained in shared mass storage.

•

The Message Control Bank (MCB) and Integrated Recovery provide message recovery control, within a local host, for concurrent application groups. COMPOOL is also available for message handling, within a local host. There is no provision for message recovery for messages handled by COMPOOL.

•

Resident Transaction Program System (RTPS) programs and TIMER scheduling are supported only for local host operation.

•

The TIP VALTAB files must be maintained in shared mass storage.

•

User KONS and system KONS are supported only on a local host basis.

•

Each host in an XTC system simultaneously functions in the local host mode as well as the multihost file-sharing mode. For local host operation TIP files are assigned to a local application, and a local KONS, TCDBF, and TIP FCSS directory are used.

3.5. Using FCSS Primitives for FCSS and Freespace Files This subsection documents the TIP File Control Superstructure (FCSS) primitives used to access TIP and Freespace files.

3.5.1. Parameters for FCSS Requests The general FCSS primitive call looks like this: CALL FCSS(p1, p2, p3, p4, p5, p6, p7) Where: p1 = function p2 = return type p3 = user buffer address p4 = TIP file number p5 = word count p6 = record number or Freespace record key p7 = buffer size All requests must specify p1 through p3. Use of p4 through p7 is function dependent and is described in detail in the subsections that follow. (For a short summary of each FCSS function’s parameter requirements, see Appendix D.) The user buffer (from p3) must always contain at least a 3-word status area (see B.1 for a description of that status area). Some functions require that the status buffer be followed by an additional input or output area.

3–10

7830 7402–014

TIP File Access

Further detail on each parameter follows: p1 = Function Is the FCSS function to be performed. The FCSS functions are described in the subsections that follow. p2 = Return type Specifies when you want control returned to your program after it issues the FCSS request. You can use either the numeric or the mnemonic value for one of these six return types shown in Table 3-1: Table 3–1. Return Types 1

FCDONE

Control returns after the completion of this request.

2

FCIMED

Control returns immediately; your program must check for the completion of this request.

3

FCALLD

Control returns after the completion of all outstanding FCSS requests.

4

FCDNIL

Synchronous read of record after immediate locking.

5

FCIMIL

Asynchronous read of record after immediate locking.

6

FCALIL

Completes all outstanding FCSS requests after immediate locking.

Return types 4, 5, and 6 (immediate locking) can be used only with the FCSS Read and Lock (RL) function, the Lock (LK) function, and the Maintenance Lock (ML) function. These return types are useful because they allow your program to regain control immediately if another user has the lock. In this case, error status 031 is returned. Return types 1, 2, and 3 cause the program to be queued on the lock. You cannot use return type 2 (immediate return) if the program buffer area you specify in the next parameter resides in a common bank. Specify an immediate return only with functions involving a data transfer. For the FCSS functions Lock (LK), Unlock (UN), File Lock (FL), and File Write Lock (FR), you can specify an immediate return type (type 2) without receiving an FCSS error. This immediate return type defaults to type 1, and the request is handled as if type 1 had been the original return type. p3 = User buffer address Identifies the address in your program’s data area where records are to be read or written. This is the address of control word 0; the user data begins at word 3. You can use the same buffer repeatedly for successive requests, but not for multiple requests that are outstanding at the same time. See B.1 for a description of the status portion of the user buffer.

7830 7402–014

3–11

TIP File Access

p4 = TIP file number Is the number of the TIP file to which your request applies. The TIP file directory indicates to the system whether it is an FCSS fixed file (that is, a regular TIP file) or a Freespace file. p5 = Word count Specifies the number of words of I/O data you want transferred or, in the case of a Freespace file, allocated. If the file is located on a sector-addressable device, you should use an integral multiple of the physical sector size (normally 28, 56, 112, or 448) to reduce system overhead. For functions involving record locking in FCSS fixed files, use an integral multiple of the record length (that is, one or more complete records). For other functions, use a multiple of the record length for sector-addressable files. If the count is not a multiple of 28, the remainder of the last sector is unpredictable. For functions involving record locking in Freespace files, the number of words locked is the same as the record length (from 01 to 010 words) defined in the record key. With some functions (such as Read Records), if you indicate 0 as the number of words, the number defaults to the record length. p6 = Record number or record key Identifies the first (or only) record where the request applies. Regardless of the type of file, the number of the first record in it is always 1. For an FCSS fixed file, enter the number of the first or only record that the request references. If the number of words exceeds the length of this record, the request applies to successive records as well. For a Freespace file, this parameter is a record key that uniquely identifies the first Freespace record referenced by the request. The record key contains the record type (1 to 8) and an FCSS record number relative to the start of the Freespace file. When you request the allocation of record space, this is a dummy parameter field; the system ignores your input value, allocates the record space you request, and returns the record key for the allocated space in control word 2 (the BTMASK field) of the buffer. Use this record key in any FCSS requests that reference the allocated space. p7 = Buffer size Specifies the length in words of the user buffer. Formerly, it was required to be at least n+3, where n was the number of words of data to be transferred, and the extra three words were for the control information at the head of the buffer. But, because it is impossible to protect users from corrupting their own data, the Exec no longer checks this specification.

3–12

7830 7402–014

TIP File Access

Therefore, the argument has become a dummy parameter. It should still be present on the call, but its value does not matter. (But you might want to use it as a self-check to make sure you reserve enough space for the control words.) Except for the record number or key parameter, formulate an FCSS function request in the same way for either an FCSS fixed file (that is, a regular TIP file) or a Freespace file. You need to know only whether the file is recognized by the system as an FCSS fixed file or whether it has been registered as a Freespace file. Here is a typical FCSS function request in ASCII FORTRAN, with a brief description of each parameter field: CALL FCSS (RD,1,BUF1,48,28,1,31) You use FCSS as the name of the primitive in an ASCII FORTRAN request. The values in the seven parameter fields of the request are as follows: 1.

RD The FCSS function, Read Records. Always place the function name in the first parameter field, regardless of the syntax of the request.

2.

1 Return type 1 (FCDONE); control returns to your program after completion of this request.

3.

BUF1 The address of the area in your program buffer where the records are read.

4. 48 The TIP file number. 5.

28 The number of words of data to be read to the buffer area.

6. 1 The number of the first record to be read; for a Freespace file, the record key would go in this field instead of the starting record number. 7.

31 The size in words of the area in the program buffer.

You will find descriptions of all the FCSS functions in the following subsections.

7830 7402–014

3–13

TIP File Access

Table 3–2 shows the basic formats for an FCSS primitive request. Table 3–2. FCSS Primitive Request Formats Language

Request Format

ASCII or UCS FORTRAN

CALL FCSS (parameters)

UCS C

FCSS (parameters);

ASCII COBOL

CALL 'CFCSS' USING parameters.

UCS COBOL

CALL 'FCSS' USING parameters.

MASM

CALL FCSS parameters

3.5.2. Write Records to Audit Trail—AD Function Write a record to the audit trail. The file must be recoverable, and program execution must begin in a recoverable program step. Use the following parameters: 1.

AD, the function

2.

Return type 1 or 3

3.

Buffer address

4. Audit-trail number; optional 5.

Word count

6. Not used; leave blank 7.

Buffer size

If you do not specify an audit-trail number (1 through 16) that is the same as the application number, the default application number (1) is used. The request status is returned in word 0 (whole word).

3.5.3. Allocate and Lock Freespace Records—AL Function Allocate a Freespace record. The record is locked before control is returned to your program. Use the following parameters: 1.

AL, the function

2.

Return type 1, 2, or 3

3.

Buffer address

4. TIP file number 5.

Word count; minimum size of record block

6. Any value; the function returns the record key in control word 2 of the user buffer 7.

3–14

Buffer size

7830 7402–014

TIP File Access

If your program performs a rollback or terminates in error during the program step, the allocated record is released by the system if the file is recoverable.

Note: A Freespace record that is allocated and not written to is not recoverable, and it might be reallocated to another program by the system even though it was previously allocated. For this reason, Unisys recommends that you use only the AW function. If, however, you do use AL, write to the record before unlocking it.

3.5.4. Allocate, Write, and Unlock Freespace Records—AN Function Allocate a Freespace record, lock it, write data to it, and then release the lock. Use the following parameters: 1.

AN, the function

2.

Return type 1, 2, or 3

3.

Buffer address

4. TIP file number 5.

Word count; minimum size of record block

6. Any value; the function returns the record key in control word 2 of the user buffer 7.

Buffer size

If your program performs a rollback or terminates in error during the program step, the allocated record is released by the system if the file is recoverable.

3.5.5. Allocate a Specific Freespace Record—AP Function Allocate a specific Freespace record by its record key. If the record has not already been allocated and if the corresponding bit map is available, the record is allocated and then locked. Since obtaining and updating the needed bit map might require several file accesses, limit your use of this function. Use the following parameters: 1.

AP, the function

2.

Return type

3.

Buffer address

4. TIP file number 5.

Word count

6. Record key 7.

Buffer size

If your program performs a rollback or terminates in error during the program step, the allocated record is released by the system if the file is recoverable.

7830 7402–014

3–15

TIP File Access

3.5.6. Assign an Area for Temporary or Scratch Files—AS Function Use the AS function to perform these tasks: •

Associate a device index with an Exec file that contains the temporary or scratch file.

•

Create the temporary or scratch file.

Define Device Index for Temporary or Scratch File Use the function to identify an Exec file for temporary or scratch file assignment. You can define up to six files for temporary file space and up to six files for scratch file space. The calling program supplies a device index and the name of the Exec file. The function uniquely associates the device index with the Exec file. When a temporary or scratch file must be assigned, the device index is supplied to identify the Exec file. Figure 3–1 shows the buffer format for device index definition using the AS function. Use the following parameters: 1.

AS, the function

2.

Return type 1; the other types are not allowed

3.

Buffer address; reserve 31 words of buffer space (00 to 036 octal)

The device index, TIP file type, and storage type are described later in this subsection. 00

Status

01 02 03 . 05 06

Device index

TIP file type

Storage type

07 . . 012 TIP/Exec Filename

015 . 036

Figure 3–1. FCSS AS Buffer Format (Device Index Definition)

3–16

7830 7402–014

TIP File Access

Assign a Temporary or Scratch File Use the AS function to assign a temporary or scratch FCSS file in an Exec file container. You must have already used the AS function to associate a device index with the Exec file. Your program can then store and retrieve data in the file through the RD and WW (or WR) functions. Figure 3–2 shows the buffer format for the AS function. Use the following parameters: 1.

AS, the function

2.

Return type 1; the other types are not allowed

3.

Buffer address; reserve 31 words of buffer space (00 to 036 octal)

This function returns the TIP file number in word 3, the status in word 0, and the device index in word 6. The input fields shown in Figure 3-2 are as follows: TIP file name Optional; a maximum of 12 Fieldata characters, left-justified. Storage type For the AS function, the value in this field must always be 01, which indicates that the file is to be simplex (that is, to have only a single leg or copy, on the device indicated by device index); only permanent files can be duplex (02). TIP file type The type of TIP (FCSS) file to be assigned: 010

Scratch

020

Temporary

Device index A number indicating the storage device that contains the Exec file in which the temporary or scratch file is to be assigned. The valid device index entries are as follows: 001

Device 1

002

Device 2

004

Device 3

010

Device 4

020

Device 5

040

Device 6

7830 7402–014

3–17

TIP File Access

If the specified device index is for an undefined device, a search is performed to locate the next higher device index. The search continues up to the maximum device index, and then begins searching again at device index 001 up to the device index specified on the input buffer. The valid device index is returned in S1 of word 06. For example, if the specified device index is 002 and that device index is undefined, a search is performed starting at index 002, continuing through indexes 004, 010, 020, and 040. Then, the search starts over at device 001 (at which point it stops, since device index 002 was the specified device index for the input buffer). Record length Number of words per record Number of records Number of records to be allocated Temporary or scratch TIP files that you set up with the FCSS AS function during a program execution can be accessed only through the RD, WR, or WW functions; locking functions cannot be used. 00

Status

01 02 03

TIP file number

04

TIP file name

05 06 07

Device index

TIP file type

Storage type

Record length

010 011

Number of records

012 . 036

Figure 3–2. FCSS AS Buffer Format (Assign Temporary or Scratch File)

3–18

7830 7402–014

TIP File Access

3.5.7. Allocate, Write, and Lock Freespace Record—AW Function Allocate a Freespace record, lock it, and write data to it without releasing the lock. Use the following parameters: 1.

AW, the function

2.

Return type 1, 2, or 3

3.

Buffer address

4. TIP file number 5.

Word count; minimum size of record block

6. Any value; the function returns the record key in control word 2 of the user buffer 7.

Buffer size

Depending on the file specifications, the record key of the allocated record is placed in the first data word of the program buffer and the date and time in the second word; the function then writes to the record. If you specify 0 as the word count, a record of record type 1 is allocated, but only the first two words of the data buffer are written to the record.

3.5.8. Check for Completion of Request—CK Function Check for the completion of any requests your program issued with an immediate return type (parameter 2). This function causes your program to wait until the requests are complete. Use the following parameters: 1.

CK, the function

2.

Return type 1 or 3; if type 2 is given, it defaults to type 1

3.

Buffer address

Use return type 1 if you want your program to wait only for the completion of the request specified with the given buffer. If you want your program to wait for the completion of all outstanding requests, use type 3. The buffer address parameter is always necessary, even if you choose to have the program wait for all requests to be completed. The status of each outstanding request is returned in the status word of its buffer area. The CK function itself does not return any status code. For a multiactivity program, CK refers only to requests issued by the calling activity. The CK function waits only for the completion of outstanding FCSS I/O. If the program is also performing non-FCSS I/O, it must issue an Executive request (ER) to WALL$ to ensure that the non-FCSS I/O is completed. For information on the ER to WALL$, see the ER Programming Reference Manual. If your program performs a rollback or terminates in error during the program step, the allocated record is released by the system if the file is recoverable.

7830 7402–014

3–19

TIP File Access

3.5.9. Volatile TCDBF Checkpoint—CP Function Allow a user program to manually force a checkpoint to occur for any volatile or checkpoint TCDBF. Use the following parameters: 1.

CP, the function

2.

Return type 1 or 3

3.

Buffer address

4. TIP file number If the file parameter specifies a checkpoint TCDBF, a new timestamp is acquired and placed in the header record. If the file parameter is a recoverable checkpoint TCDBF, the second timestamp (earliest active, ready, or commit-in-progress step with checkpoint TCDBF updates) is acquired and placed in the header record. The function has no effect on the currently running checkpoint interval timers when issued for checkpoint TCDBFs. On XTC systems, the CP function is allowed for shared checkpoint TCDBFs only if the TCDBF is registered on the host where the CP function is called.

3.5.10. Lock a Permanent File—FL Function Lock a permanent file from all accesses by other programs. Your program accesses the file through the RD and WW functions. If a file lock is placed on a UDS/TIP file, your program can access the file, but no access is allowed through the UDS interface. Use the following parameters: 1.

FL, the function

2.

Return type 1 or 3; if type 2 is given, it defaults to type 1

3.

Buffer address

4. TIP file number If there are any outstanding record locks, this request for a file lock is suspended until those locks are released. However, a continuous stream of individual record locks does not cause this file lock request to be queued indefinitely. The FL function is not allowed on an XPC–L and should not be used for shared files or files specifying RLPLCK=P.

3–20

7830 7402–014

TIP File Access

3.5.11. Lock a File Against Write Access—FR Function Lock a permanent file from all but RD accesses by other programs. Your program accesses the file through both the RD and the WW functions. Use the following parameters: 1.

FR, the function

2.

Return type 1 or 3; if type 2 is given, it defaults to type 1

3.

Buffer address

4. TIP file number If there are any outstanding record locks, this request for a file lock is suspended until those locks are released. However, a continuous stream of individual record locks does not cause this file lock request to be queued indefinitely. The FR function is not allowed on an XPC–L and should not be used for shared files or files specifying RLPLCK=P.

3.5.12. List Characteristics of a File—LF Function List the characteristics of a permanent, temporary, or scratch file. Figure 3–3 shows the LF user buffer format. Use the following parameters: 1.

LF, the function

2.

Return type 1; the other types are not allowed

3.

Buffer address; reserve 31 words of buffer space (00 to 036 octal)

4. TIP file number An Extended Transaction Capacity (XTC) system has a local TIP directory and a shared TIP directory—so there are two pairs of TIP system files 0 and 1. To list the characteristics of shared TIP system file 1, include an @QUAL SHARED# statement (specifying the shared directory-id) before the FCSS LF call; otherwise, local TIP system file 1 will be referenced. You cannot use the LF function to list the characteristics of TIP system file 0 in either the local or the shared TIP directory. 00

Status

01 02 03

Related TIP file number

04

Permanent TIP file number TIP file name

05 06

Device index

7830 7402–014

TIP file type

Storage type

Fallback indicators

3–21

TIP File Access

07

Record length

010

HV flags

Lock type

Audit trail number

File status, leg 1

Fallback extension

TCDBF flag or RPF AG

RPF Host

File status, leg 2

011

Number of records

012

Exec file relative address, start of leg 1

013

Exec file name, leg 1

014 015

Exec file relative address, start of leg 2

016

Exec file name, leg 2

017 020

TCDBF BDI

HVTIP library number

021 . 035 036

Exec file number, leg 1

Exec file number, leg 2

Figure 3–3. FCSS LF User Buffer Format The output fields shown in Figure 3–3 for the LF function are as follows: Related TIP file number The number of the live TIP file, if the requested file is a training file Permanent TIP file number The number of the requested TIP file TIP file name Optional; a maximum of 12 Fieldata characters, left-justified Device index A number indicating the storage device that contains the Exec file and, inside it, the TIP file:

3–22

001

Device 1

002

Device 2

004

Device 3

010

Device 4

020

Device 5

040

Device 6

7830 7402–014

TIP File Access

TIP file type The type of TIP file. Following are bit settings for this field: 1

Permanent

2

Freespace

4

UDS/TIP

010

Scratch

020

Temporary

030

Temporary or Scratch

Bits are combined to produce values. For example, a permanent UDS/TIP file has a value of 5. Storage type Status bits indicating various mass storage attributes for the TIP file: 01

Simplex TIP file

02

Duplex TIP file

05

Shared simplex TIP file

06

Shared duplex TIP file

(Local TIP files can be on either local or shared mass storage, but shared TIP files must be on shared mass storage.) Fallback indicators The TIP file status indicators: 01000

After-looks are to be taken for this file on the audit trail.

00400

The file is recoverable.

00200

The WW (write without checking for locks) function is allowed with this file, if it is permanent.

00010

Console messages are autoanswered.

00004

The file is a TIP common data bank file (TCDBF).

00100

The file is a training file.

Record length Number of words per record

7830 7402–014

3–23

TIP File Access

HV flags If the fallback extension indicates that this TIP file is an HVTIP library (bit 0 is set), this field contains flags for the HVTIP library contained in the TIP file. Bit 1 set (000010)

Indicates the library is online

Bit 0 set (000001)

Indicates that the library is compatible with HVTIP-II, phase 2

Lock type The type of locking required or specified for the TIP file on an XTC system: 00

Software (TIP) locking

01

Hardware (RLP) locking

Audit trail number Number of the audit trail for the application or application group File status, leg 1 Status of the main, or only, copy (leg) of the file: 00

Available

04

Maintenance read inhibit

010

Maintenance write inhibit

020

Write protect

040

Read only

060

Unavailable

Fallback extension These flags are an extension of the fallback indicators. Bit 3 set (001000)

Indicates that the TPM data collection is requested for the file

Bit 2 set (000100)

Indicates the file is a UDS controlled file

Bit 1 set (000010)

Indicates the file is a rollback page file (RPF)

Bit 0 set (000001)

Indicates the file is an HVTIP library file

TCDBF flags If the file is a TCDBF, then the attributes of the TCDBF are indicated by flags in this field.

3–24

7830 7402–014

TIP File Access

Bit 3 set (001000)

Indicates the listed file is a checkpoint TCDBF

Bit 2 set (000100)

Indicates the TCDBF has a dynamic BDI

Bit 1 set (000010)

Indicates that the recorded TCDBF BDI is in L,BDI format

Bit 0 set (000001)

Indicates that the file is a volatile TCDBF

RPF AG If this fallback extension indicates that this file is a rollback page file (bit 1 is set) this field contains the rollback page file application number from the ROLLBACK configuration SGSs. RPF Host If this file is a rollback page file (RPF), this field contains the Host-id if the file is contained in a concurrent application. File status, leg 2 Status of the second copy (leg) of the file, if it is duplex; should be the same as file status, leg 1 Number of records Total number of records to be allocated Exec file relative address, start of leg 1 Starting address in the Exec file of the main (or only) copy of the TIP file Exec file name, leg 1 The name of the Exec file that contains the main (or only) leg of the TIP file Exec file relative address, start of leg 2 Starting address in another Exec file of the second copy (leg) of the TIP file, if it is duplex Exec file name, leg 2 The name of the Exec file that contains the second copy (leg) of the duplex TIP file TCDBF BDI If this TIP file contains a TIP common data bank file, this field contains the BDI of the TCDBF.

7830 7402–014

3–25

TIP File Access

HVTIP library number If this TIP file contains an HVTIP library, this field contains the HVTIP library number. Exec file number, leg 1 The number of the Exec file that contains the main (or only) leg of the TIP file Exec file number, leg 2 The number of the Exec file that contains the second copy (leg) of the TIP file, if it is duplex

3.5.13. Lock Records—LK Function Create a data lock on the referenced records. Use the following parameters: 1.

LK, the function

2.

Return type 1, 2, 3, 4, 5, or 6

3.

Buffer address

4. TIP file number; the file must be permanent 5.

Word count; one or more complete records for an FCSS fixed file, or one complete or partial record for a Freespace file

6. Record number or (for a Freespace file) record key 7.

Buffer size

With return types 1, 2, and 3, if the referenced records are already locked by another program, your program is suspended until the lock request can be granted. With return types 4, 5, and 6, if the referenced records are already locked by another program, an FCSS 031 error is returned to your program and your program can proceed.

3.5.14. Read Records—RD Function Read one or more records. No record locking is performed or checked on the referenced records. Use the following parameters: 1.

RD, the function

2.

Return type 1, 2, or 3

3.

Buffer address

4. TIP file number 5.

Word count; in an FCSS fixed file, transfer of a partial record is allowed

6. Record number or (for a Freespace file) record key 7.

3–26

Buffer size

7830 7402–014

TIP File Access

Since RD is a reserved word in ASCII COBOL, specify RR instead of RD for the function if you are writing your program in that language. Staged write data for recoverable files is ignored by the RD function. Records are read directly from the database.

3.5.15. Read and Lock Records—RL Function Create a data lock on the referenced records and read them into the program buffer. Use the following parameters: 1.

RL, the function

2.

Return type 1, 2, 3, 4, 5, or 6

3.

Buffer address

4. TIP file number; the file must be permanent 5.

Word count; one or more complete records for an FCSS fixed file, or one complete or partial record for a Freespace file

6. Record number or (for a Freespace file) record key 7.

Buffer size

With return types 1, 2, and 3, if the referenced records are already locked by another program, your program is suspended until the lock request is granted. With return types 4, 5, and 6, if the referenced records are already locked by another program, control immediately returns to your program without the record being read, and FCSS 031 error is returned to your program. For a Freespace file, if you specify 0 as the number of words, the number defaults to the record length indicated in the record key. If the data transferred is less than the number of words requested, a partial word count is returned in word 1, H1 of the program buffer. If a recoverable, deferred update is currently staged on the records by your program, the read occurs from the staged image rather than from the actual database image. Use the RL function to read the current data. The RL function first locks the record and then attempts to read it. If the attempt to read the record fails, the lock is not released.

3.5.16. ASCII COBOL Read Records—RR Function For programs in ASCII COBOL, use RR instead of RD. See the description of the RD function in 3.5.15.

7830 7402–014

3–27

TIP File Access

3.5.17. Release and Unlock Freespace Records—RU Function Unlock a Freespace record and return it to the system as a free record. To make certain that another program is not using this record, you must lock it before executing this instruction. Use the following parameters: 1.

RU, the function

2.

Return type 1 or 3; immediate return type 2 is impossible

3.

Buffer address

4. TIP file number 5.

Word count

6. Record key 7.

Buffer size

If the buffer address matches the address on any outstanding record locks, those locks are released. If the buffer address does not match the address on any outstanding record locks, the action taken depends on the setting of the execution options for the program (VALTAB OPT field for transactions or XQT options for batch connect programs). •

If the J option is clear, then all outstanding locks (both recoverable and nonrecoverable) held by the program are released.

•

If the J option is set, then all outstanding locks are left as is.

3.5.18. Save File Updates—SF Function Save on disk any TIP file updates. These updates must be staged in the cache/disk hardware system cache storage for the Exec file that contains the TIP files. Use the following parameters: 1.

SF, the function

2.

Return type 1

3.

Buffer address

4. TIP file number

3.5.19. Release All Record/File Locks—UA Function Release all recoverable record and file locks at commit time. This function is for the Integrated Recovery environment only; therefore, nonrecoverable file and record locks are not affected by this function.

3–28

7830 7402–014

TIP File Access

3.5.20. Release Record or File Locks—UN Function Unlock a record lock or an FCSS file lock or all locks held by your program. Use the following parameters: 1.

UN, the function

2.

Return type 1 or 3; if type 2 is given, it defaults to type 1

3.

Buffer address

If the buffer address matches the address on any outstanding record locks, those locks are released. If the buffer address does not match the address on any outstanding record locks, the action taken depends on the setting of the execution options for the program (VALTAB OPT field for transactions or XQT options for batch connect programs). •

If the J option is clear, then all outstanding locks (both recoverable and nonrecoverable) held by the program are released.

•

If the J option is set, then all outstanding locks are left as is. If the lock is for a recoverable file, and there is a deferred update staged under that lock, the UN request marks the lock as to-be-released, but delays the actual release until a commit point.

If the file is recoverable, the UN request is ignored if a deferred update is staged under any lock to be released.

3.5.21. Write Records and Keep Locked—WL Function Write a record and keep the record or file lock already held by your program. Use the following parameters: 1.

WL, the function

2.

Return type 1, 2, or 3

3.

Buffer address, which does not have to be identical to the one specified in the request that created the lock

4. TIP file number; the file must be permanent 5.

Word count

6. Record number or (for a Freespace file) key 7.

Buffer size

For an FCSS fixed file, the lock is not released after output. If program execution produces a recoverable, deferred update, the update is staged, but it is not written to the file until the program step terminates. If a deferred update has already been staged on the same records by the program, this request overrides the previous deferred update. If after-looks are to be taken, an after-look of the deferred update is written to the audit trail.

7830 7402–014

3–29

TIP File Access

The number of words requested on the WL function might be less than or equal to the number of words previously locked by an LK or RL request. If the number of words requested is less than the number of words previously locked, then only the words specified on the WL are written to, but the lock also remains on all the words previously locked. Record expansion occurs if the number of words you specify for this function is at least one word larger than the record length indicated in the record key. If the requested number of words on the write is larger than the Freespace record, a new record is allocated that is large enough to hold the words indicated on the write. The data is written to the new record and the old record is released. The record key of the new record is returned to your program in the third word of the status area of the buffer passed by the user. Freespace expansion is always enabled. Anytime you write more words to a Freespace record than will fit in the record, the old record is released and a new record is allocated. Anytime you use the WL function, you should check the returned record key in the third word of the status area of the user buffer. Be sure any programs reading the original record are redirected to the new record. Even if the request received an error status, the record key may have changed and must be checked. If the file is recoverable (REC) and the step is rolled back or the program error terminates upon encountering the error, the original record will still be allocated. However, if the file is nonrecoverable (NREC) or the step is committed, and record re-allocation occurred, the old record is released and the new record is left allocated. Record contraction, if allowed for the Freespace file, occurs if the number of words you specify for this function is small enough to fit into a smaller Freespace record type defined for the file. If the record is to be contracted to the new length, a new record of that size is allocated, the data is written to it, and the old record is released. The record key of the new record is returned to your program in the third word of the status area of the buffer passed by the user. Freespace file contraction can be turned off by setting CON=I for the Freespace file. Since record contraction changes the key by which you reference a record in a call, decide first whether to use this capability in a Freespace file. Always check the returned record key when using the WL function and make certain that any programs reading the original record are redirected to the new record.

3.5.22. Write and Release Lock—WR Function Write a record or records and release lock or locks. The records must have been previously locked by your program. Use the following parameters: 1.

WR, the function

2.

Return type 1, 2, or 3

3.

Buffer address, which does not have to be identical to the one specified in the request that created the block

4. TIP file number

3–30

7830 7402–014

TIP File Access

5.

Word count; transfer of a partial record is allowed for an FCSS fixed file. (If, however, the count is not a multiple of the record length, the content of the remainder of the last sector is unpredictable.)

6. Record number or (for a Freespace file) key 7.

Buffer size

At the end of data transfer, the lock is released if the file is nonrecoverable. If the file is recoverable, the WR function has the same effect as the WL function. For a temporary or scratch file, the WR function has the same effect as the WW function. If an Exec I/O error occurs during data transfer (write), the lock is still released upon completion of the WR request, and the Exec I/O error status is returned to the requestor. In a Freespace file, if you indicate 0 for the number of words, the number defaults to the length of the record type specified in the record key. The number of words specified in the record key is placed in the first word of the program buffer, and the date and time (in yymmdd hh:mm:ss format) in the second word. The record is then written. If program execution produces a recoverable, deferred update, the update is staged but is not written to the file until the program step terminates. If a deferred update has already been staged on the same records by the program, this request overrides the previous deferred update. If after-looks are taken, an after-look of the deferred update is written to the audit trail. For record expansion or contraction in a Freespace file, see the description of the WL function in Section 3.5.22.

3.5.23. Write Records Without Checking for Lock—WW Function Write a record without checking for a record lock. Use the following parameters: 1.

WW, the function

2.

Return type 1, 2, or 3

3.

Buffer address

4. TIP file number 5.

Word count; with an FCSS fixed file, transfer of a partial record is allowed

6. Record number or (for a Freespace file) key 7.

Buffer size

With a permanent file, use this function only if the “WW allowed” option has been set in the TIP file directory.

7830 7402–014

3–31

TIP File Access

3.6. Using TIP Common Data Bank Files A TIP common data bank file (TCDBF) is a specially formatted TIP FCSS file. A TCDBF exists as both an FCSS file on disk and as an application-level common data bank in memory. Data in the TCDBF is available to any program that has the bank based. A TCDBF is useful when high-speed access to fairly static data is required, or when improvement in performance is desirable. There are two types of TCDBFs: standard TCDBFs and volatile TCDBFs. You use the FREIPS TCDCREATE command to create a TCDBF. You can also create a TCDBF using an application program. The FREIPS CHA command is used to register the TCDBF after you create it. See the Transaction Processing Administration and Operations Reference Manual for detailed information about creating TCDBFs.

3.6.1. Accessing a TCDBF Full read and write access to TCDBFs is now allowed through normal FCSS primitives in both basic and extended mode. In extended mode, access to standard and volatile TCDBFs is allowed through all read functions and the Write, Write and Keep Lock, and Maintenance Write functions. Direct access is available through the extended mode call (TIP$FILE$FUN), or the extended mode FCSS primitive. You can use the TCDIO primitive to write to standard TCDBFs in basic mode only. The need for the TCDIO primitive has been eliminated by the ability to access TCDBFs through FCSS primitives. Support for the TCDIO primitive is maintained only to ensure compatibility with previous releases.

3.6.2. TCDIO Primitive Note: Full read and write access to TCDBFs is now allowed through normal FCSS primitives, as described in 3.6.1. You can use the TCDIO primitive to write to data tables in a TCDBF in basic mode only. This primitive performs the FCSS functions WL and WR for TCDBFs. TCDIO also performs the maintenance function MW in the Integrated Recovery environment. (See the Transaction Processing Administration and Operations Reference Manual for information on the MW function.) Table 3–3 shows the specific format for calling TCDIO with your programming language.

3–32

7830 7402–014

TIP File Access

Table 3–3. TCDIO Request Formats Language

Request Format

ASCII FORTRAN

CALL TCDIO (parameter 1,parameter2,...parameter9)

ASCII COBOL

CALL ’CTCDIO’ USING parameter1,parameter2,...parameter9.

MASM

CALL TCDIO parameter1,parameter2,...parameter9.

Parameters for TCDIO Requests The user buffer format for TCDIO requests is the same as for the FCSS requests; see B.1 for a description. When you call the TCDIO primitive, the particular function you want TCDIO to perform is always the first parameter, which you indicate by a two-letter mnemonic. Enter the parameter values in the following order: 1.

Function

2.

Return type

3.

Buffer address

4. TIP file number 5.

Word count

6. Record number 7.

Buffer size

8. Bank descriptor index (BDI) of the TCDBF 9. Relative bank address within the common bank The parameters are the same as those described in 3.2.1 for FCSS requests, except for the following parameters: Function is either WL (write records and keep locked) or WR (write records) Return type Number or mnemonic specifying when you want control returned to the program after it issues the TCDIO request: 1

FCDONE

2

FCIMED

3

FCALLD

You cannot use return type 2 (immediate return) if the program buffer area you specify in the next parameter resides in a common bank. Specify an immediate return only with functions involving a data transfer.

7830 7402–014

3–33

TIP File Access

Common bank BDI The BDI for the common bank. The common bank must be based. Bank address A relative address in the bank. The relative address includes the bank’s lower limit (in the TCDBF record header), so that the parameter for a write to word 0700 in a bank with a lower limit of 0300000 would be 0300700. Every application program using a TCDBF must base the bank at the same relative address. The program must verify that the common bank address corresponds with the FCSS file address.

Write Records and Keep Locked—WL Function Write a record and keep the record or file lock already held by your program. Use the following parameters: 1.

WL, the function

2.

Return type 1, 2, or 3

3.

Buffer address, which does not have to be identical to the one specified in the request that created the block

4. TIP file number; the file must be permanent 5.

Word count

6. Record number 7.

Buffer size

8. BDI of the TCDBF 9. Relative bank address within the common bank If program execution produces a recoverable, deferred update, the update is staged, but it is not written to the file until the program step terminates. If a deferred update has already been staged on the same records by the program, this request overrides the previous deferred update. If after-looks are to be taken, an after-look of the deferred update is written to the audit trail. The number of words requested on the WL function may be less than or equal to the number of words previously locked by an LK or RL request. If the number of words requested is less than the number of words previously locked, then only the words specified on the WL are written to. The lock also remains on all the words previously locked.

3–34

7830 7402–014

TIP File Access

Write and Release Lock—WR Function Write a record or records and release the lock or locks. The records must have been previously locked by your program. Use the following parameters: 1.

WR, the function

2.

Return type 1, 2, or 3

3.

Buffer address, which does not have to be identical to the one specified in the request that created the block

4. TIP file number 5.

Word count

6. Record number 7.

Buffer size

8. BDI of the TCDBF 9. Relative bank address within the common bank At the end of data transfer, the lock is released if the file is nonrecoverable. If the file is recoverable, the WR function has the same effect as the WL function. If an Exec I/O error occurs during data transfer (write), the lock is still released upon completion of the WR request. The Exec I/O error status is returned to the requestor. If program execution produces a recoverable, deferred update, the update is staged, but is not written to the file until the program step terminates. If a deferred update has already been staged on the same records by the program, this request overrides the previous deferred update. If after-looks are taken, an after-look of the deferred update is written to the audit trail.

7830 7402–014

3–35

TIP File Access

3–36

7830 7402–014

Section 4 Program Steps and Integrated Recovery If your site uses Integrated Recovery features, you might need to use the ROLLBACK and COMMIT primitives, and you need to know how certain FCSS functions affect your program. This subsection gives some general information on Integrated Recovery and describes the use of the ROLLBACK and COMMIT primitives.

4.1. Integrated Recovery Your site defines each application group (including its program files and other database files) in your system as a unit numbered 1 to 16. The application group number is the same as the number of its audit trail, which is a tape or mass storage record of completed recoverable events. Integrated Recovery guarantees database integrity and recovers database updates and message queues lost during various types of failure, ranging from abnormal termination of your transaction program to a communications network failure. After a failure, Integrated Recovery provides one or more of the following: •

Program rollback The current transaction program is rolled back (that is, database updates from the beginning of the program or the last commit point to the point of failure are discarded), and the program is requeued for execution.

•

Short recovery All programs in your application (for application rollback) or in the TIP system (for system rollback) are rolled back, interface programs are reinitialized, and the transaction programs can be requeued.

•

Long recovery Your application’s database and message retention files are rebuilt from its audit trail.

The basic unit for recoverable events is a program step. A step for a transaction program lasts from input scheduling to program termination, while an offline batch program lasts from the CONECT call to the DISCON call. TIP defers updates to your database to protect it from simultaneous updates by the programs in your application. If a program terminates normally and the step is concluded successfully, the system then commits (applies) the deferred updates to your online database.

7830 7402–014

4–1

Program Steps and Integrated Recovery

If you also define those deferred updates as recoverable, they can be completed in case of program or system failure during the commit. If they are defined as both recoverable and audited, they are recorded (audited) on your application’s audit trail as after-looks. If long recovery is necessary, after-looks allow the Integrated Recovery Utility (IRU) to rebuild database files by reapplying updates to the database. Only one step can exist at a time for any recoverable program, although more than one activity of a multiactivity program can be performing recoverable actions for that program. The program can defer updates until it specifically applies them using the COMMIT primitive, or it can use COMMIT requests to create several recoverable entities during execution. For a thorough introduction to Integrated Recovery, see the Integrated Recovery Conceptual Overview.

4.2. Commit Points and Rollback The COMMIT primitive lets a recoverable program create a specific commit point during a program. The TERMN8 and DISCON primitives mark implicit commit points.

4.2.1. COMMIT The COMMIT primitive lets the program request that database updates performed up to that point be written to the audit trail and to the TIP database. Commit processing results in program step advance or program step termination. This request can be issued by a transaction program or by a batch or demand program connected to TIP. If program step termination occurs, all recoverable file and record locks are released. If program step advance occurs, a given program can issue successive COMMIT requests, if desired. During program step advance the following rules apply to lock release handling: •

4–2

Recoverable locks: −

If the U recovery option is set in the REC field of the validation table (VALTAB) entry or bit 12 is set in the CONECT request, all locks are released.

−

If the U recovery option is not set or bit 12 in the CONECT request is clear: ο

All locks that have been specifically released (via the functions UA, UN, WR, RU) are released.

ο

All locks that were not specifically released are retained past commit processing, and the program step resumes execution with these locks intact.

ο

Any lock is released at commit time if a deferred update is outstanding and a WR (Write and Release Lock) function or an UN (Unlock) function was previously issued by the program followed by a subsequent RL (Read and Lock) or LK (Lock) function for the same database area.

7830 7402–014

Program Steps and Integrated Recovery

•

Nonrecoverable locks: −

Unlocks are processed immediately on issue and no specific processing takes place during commit. Any locks outstanding are retained until they are specifically unlocked (UN) or until program termination.

4.2.2. TERMN8 A TERMN8 request marks an implicit commit point for a transaction program. Its purpose is to terminate the program.

4.2.3. DISCON A DISCON request marks an implicit commit point for a batch or demand program connected to TIP. For an online batch program, both TERMN8 and DISCON are commit points.

4.2.4. ROLLBACK A TIP program requests rollback through the ROLLBACK primitive. This primitive discards database deferred updates and unlocks all file and record locks. Rollback processing results in program step resumption or program step termination. This request can be used by either a transaction program or a batch and demand program connected to TIP. For program steps that involve both UDS Control and TIP File Control, FCSS commit or rollback processing occurs through the UDS interface. This ensures synchronization of TIP and UDS database processing.

4.3. Apply Updates to the Database—COMMIT Primitive Use the COMMIT primitive to commit (apply) updates from a program step to the database. The COMMIT request marks the end of that program step and the beginning of the next one, if step advance occurs (that is, if there is to be at least one more program step). If your program is long running and performs many database updates, or if it uses multiple INITAL calls (see 6.2), it can make repeated COMMIT requests. Table 4–1 shows the format for COMMIT requests, which do not require parameters. Table 4–1. COMMIT Request Formats Language

Request Format

ASCII or UCS FORTRAN

CALL COMMIT

UCS C

COMMIT();

UCS Ada

CALL C_OMMIT;

ASCII COBOL

CALL ’CCMMIT’.

7830 7402–014

4–3

Program Steps and Integrated Recovery

Table 4–1. COMMIT Request Formats Language

Request Format

UCS COBOL

CALL ’COMMIT’.

MASM

CALL COMMIT.

4.4. Roll Database Updates Back—ROLLBACK Primitive Use the ROLLBACK primitive to roll back the updates from a recoverable program step in case of any failure. The result of rollback is either program resumption or program step termination. The program can retain the step’s input message or release and optionally requeue the message. Partially staged messages are released. Table 4–2 shows the formats for ROLLBACK requests, which do not require parameters. Table 4–2. ROLLBACK Request Formats Language

Request Format

ASCII or UCS FORTRAN

CALL ROLLBACK

UCS C

ROLLBACK();

UCS Ada

CALL R_OLLBACK;

ASCII COBOL

CALL ’CRLBAK’.

UCS COBOL

CALL ’ROLLBACK’.

MASM

CALL ROLLBACK.

4.5. Step Control Summary Table 4–3 summarizes the system action taken with respect to Step Control. Table 4–3. Step Control System Action

COMMIT

ROLLBACK

TERMN8 (EXIT$)

FCSS

UDS

DISCON (PB$DIS)

FCSS

UDS

COMMIT (CO$MIT)

FCSS

UDS

ROLLBACK (RL$BAK)

4–4

System Action

User-Requested Action

FCSS

EMODE

UDS

7830 7402–014

Program Steps and Integrated Recovery

Table 4–3. Step Control System Action User-Requested Action

System Action COMMIT

ROLLBACK

EMODE FCSS/UDS if not

INITAL (PI$NIT)

committed Abnormal termination UDS FREE or DEPART

FCSS/UDS UDS

UDS ROLLBACK

FCSS UDS

FCSS

4.6. Recoverable Updates Recoverable updates to FCSS fixed files are dependent on the following four sources of control: •

Information about the file in the TIP file directory

•

Indication of a recoverable program step for the program

•

The FCSS function requested in the program

•

The audit trail/application group number specified for the file and the program

4.6.1. TIP File Directory There are two indicator bits in the TIP directory related to recoverable updates. One bit indicates the file is recoverable. The second bit indicates that an after-look is desired on the audit trail for each recoverable write to the file. If the file indicator bits indicate that the file is a recoverable file and after-looks are desired, the TIP directory can optionally specify the audit-trail number on which after-looks are to be recorded. If specified, it must match the audit-trail number specified (either explicitly or by default) in the VALTAB entry or the CONECT call. If not specified, the audit-trail number defaults to 1.

4.6.2. Audit Trail/Application Group Number For recoverable updates to occur, the audit trail number specified in the TIP file, either explicitly or by default in the file directory, must match the application group number specified (either explicitly or by default) in the VALTAB entry, or on the CONECT call. Database updates to recoverable FCSS TIP files through the FCSS interface can be performed only by recoverable program steps.

7830 7402–014

4–5

Program Steps and Integrated Recovery

4.6.3. Recoverable Program Steps and Primitive Requests Program step recovery information is specified in the VALTAB entry for a transaction program or in the CONECT call for a batch and demand program. This information consists of the following: •

Application group number; if not specified, it defaults to 1.

•

Recovery flags; for TIP File Control, only bit 17 (recoverable program step) is pertinent.

FCSS Requests If the program is defined to be a recoverable step with deferred updates desired, database updates are treated as recoverable for any TIP file defined to be recoverable. This affects the following FCSS functions: WL

Write and Keep Lock

RL

Read and Lock

WR

Write and Unlock

UN

Unlock

In addition, if the file directory specifies that after-looks are desired, an after-look is recorded on the audit trail for each recoverable database update. If the program is defined to be a recoverable step, the FCSS function AD (user audit) can be used to request that a user record be written to the audit trail.

Freespace Requests If the program is defined to be a recoverable step with deferred updates desired, database updates are treated as recoverable for any Freespace file defined as recoverable. This affects the following FCSS functions:

4–6

WL

Write and Keep Lock

RL

Read and Lock

WR

Write and Unlock

UN

Unlock

AL

Allocate

AW

Allocate and Write and Keep Locked

AN

Allocate and Write and Unlock

AP

Allocate Specific

RU

Release and Unlock

7830 7402–014

Program Steps and Integrated Recovery

FCSS Requests and Nonrecoverable Program Steps If the program is defined to be nonrecoverable, the following FCSS functions can be requested by the program on a recoverable file: RD

Read

FL

File Lock

4.7. Controlling Commit Processing When the program does a commit with step advance, the Exec frees all recoverable file locks but leaves nonrecoverable locks alone. When the program does a commit with step terminate, all locks are released. The VALTAB Y recovery (REC keyword) option defines default commit processing. If the Y option is specified for a program, the default commit processing is step terminate. Otherwise, the default is step advance. You can override the Y REC option by explicitly declaring the commit action within the program: •

For a TIP program, use the COMMIT primitive.

•

For a DMS 2200 program, use a command with the following syntax: FREE WITH MESSAGE ADVANCE FREE WITH MESSAGE TERMINATE DEPART WITH MESSAGE ADVANCE DEPART WITH MESSAGE TERMINATE

For programs that use DPS 2200, with DEPART followed by D$CLOSE, it would be better not to have the REC Y indicator set in the VALTAB entries for the programs and not to make the DPS 2200 files recoverable.

7830 7402–014

4–7

Program Steps and Integrated Recovery

4–8

7830 7402–014

Section 5 Using KONS The TIP system lets your site set up high-speed files to hold relatively static information that transaction programs frequently need to reference. Your site might set up TIP common data bank files (TCDBF) in addition to or instead of a KONS file, part of which is always generated with the Exec. A TCDBF is a mass storage file that transaction programs access through a main storage copy; KONS is permanently resident in main storage. A TCDBF is essentially free format; a KONS file has a fixed format. This section shows you how to work with KONS. To use the KONS file, you need to know the fixed areas in the file and how to reference records in those areas. Use the KONS primitive, along with a special set of functions.

Note: If the KONS training file is to be used, the KONS primitive must not be collected in the user program at addresses higher than 65,535. For information about using the KONS training file, see Section 9.1 KONS is divided into two separate areas of main storage: system KONS, containing values defined by the operating system; and user KONS, allocated for values your site defines. The user KONS area is written to mass storage by a utility program or by a periodically scheduled transaction program. An Extended Transaction Capacity (XTC) system supports user KONS and system KONS in the local TIP File Control Superstructure (FCSS) directory, but it does not support KONS in the shared TIP directory. See Section 3.4 for more information on the XTC system. System KONS is a fixed-size area that is always generated as a part of the TIP system. This area, made up of counters, status indicators, queues, test-and-set cells, and constants, is critical to running the TIP system. The system KONS is subdivided into two areas: S1 and S2. Transaction programs can read any part of S1 or S2, but only transaction programs that have the S execution option (write to protected KONS areas) set in their validation table (VALTAB) entry are permitted to write to the S2 area. Transaction programs cannot write to the S1 area. TIP File Security does not protect the data residing in KONS, the main storage resident file. It does control access to the KONS TIP system file.

7830 7402–014

5–1

Using KONS

The site administrator generates user KONS as a part of the TIP system. User KONS is subdivided into three areas: U1, U2, and U3, which contains the security directory. The sizes of the three areas and the security directory are defined by configuration parameters. Any transaction program can read from the word- or record-addressable U1 and U2 areas and can write to the U2 area. A program can write to the U1 area only if the S execution option (allowing writes to protected KONS areas) is set in its VALTAB entry. But no program should change the first word of U1, word 0, because TIP uses that word to control the timing feature. Words 1 through 3 of U1 are also reserved for use by the Exec. The U3 area is block addressable. To read or write to this area, a program might have to include a security key or password. If the password configuration parameter for your system is set, use the security key specified in the security directory for the range of U3 blocks containing the block you want. If that configuration parameter is not set, use the 1-word security key that has been established for the entire application. To write to the security directory at the end of U3, the program needs both the S and Q (manipulate the KONS security directory) execution options (OPTIONS) set. Configuration parameters define the length of the U3 blocks and the number of security directory entries (that is, the number of security keys and the number of ranges of U3 blocks).

5.1. KONS Function Requests In the limits set by the TIP system and by your site administrator, you reference and manipulate the user and system KONS through KONS functions. To access the KONS file, use the KONS primitive and specify a function plus other parameters. The KONS function (the operation) is always the first parameter, expressed as a mnemonic or as a numeric value. Use the request format required for your programming language (see Table 5–1). Table 5–1. KONS Function Requests Language

Request Format

ASCII or UCS FORTRAN

CALL KONS (parameters)

UCS C

KONS (parameters) ;

ASCII COBOL

CALL ’CKONS’ USING parameters.

UCS COBOL

CALL ’KONS’ USING parameters.

MASM

CALL KONS parameters.

Here are descriptions of parameters you use in KONS function requests: Block number Indicates the number of a block within the U3 area; the first block number is 1.

5–2

7830 7402–014

Using KONS

Buffer address Specifies a location in the program’s D-bank where the KONS words/records are stored. Buffer size Indicates the size of the buffer area. Comparison count and record location Specifies a buffer area in the program’s D-bank for storing this information: •

In H1, the number of comparisons actually made during a search.

•

In H2, the location in KONS (relative to the start of the user area) of the first word of the KONS record being searched for.

Comparison limit and record length Specifies: •

In H1, the maximum number of comparisons to be made during a search.

•

In H2, the length of a KONS record (4095 at most), which is also the increment between searched words.

Error return address A label in your program that you wish to return to in case of an error. Increment Indicates a signed value to be added to the J-designator at the start of an operation. J-descriptor The numeric code that specifies the length of the search key (whole or partial word) and the increment to the next KONS entry in a sequential search/read operation: 0

whole word

1

half word

2

third word

3

sixth word

7830 7402–014

5–3

Using KONS

J-designator The mnemonic or numeric code that specifies which portion of the KONS entry is compared with the search key or updated: 0=W

full word

1=H2

second half-word

2=H1

first half-word

3=XH2

second half-word with sign extension

4=XH1

first half-word with sign extension

5=T3

third third-word

6=T2

second third-word

7=T1

first third-word

8=S6

sixth sixth-word

9=S5

fifth sixth-word

10=S4

fourth sixth-word

11=S3

third sixth-word

12=S2

second sixth-word

13=S1

first sixth-word

KONS index Indicates the start of the specific KONS area, relative to the start of the U1 user area. Table 5–2 shows each KONS area, its system address, and the KONS index (for the starting word) you use to reference the system address. The names in the table are defined by the system definition procedure SYSDEF; the values are set through the following configuration parameters:

5–4

TIPMIN

The start of the U1 area and, therefore, of user KONS.

KONSEC

The length in words of the write-protected U1 area.

KONSFL

The length in words of user KONS (areas U1, U2, and U3, including the security directory).

KONU3L

The length in words of the block-addressable U3 area, not including the security directory.

KSECNB

The number of security directory entries, each of which is 2 words long. Therefore, the length of the security directory is KSECNB*2 words.

7830 7402–014

Using KONS

Table 5–2. KONS Area Addressing Scheme KONS Area

System Address

KONS Index

System KONS Area (S2)

TIPMIN-65

-64

System KONS Area (S1)

TIPMIN-1

-1

User KONS Area (U1)

TIPMIN

0

User KONS Area (U2)

TIPMIN+KONSEC

KONSEC

User KONS Area (U3)

TIPMIN+KONSFLKONU3L-KSECNB*2

RANGEU2

Security Directory

TIPMIN+KONSFLSECURL

RANGEU3

Mask Specifies which bits (up to 36, in any combination) of the search key are compared with KONS records during a search. Next statement The number of a statement in the program where control is to be transferred, or if a requested lock would cause a deadly embrace. No-find return address A label in your program that you wish to return to if no match is found for the search key. Record location Indicates a 1-word buffer area in the program’s D-bank where the system can store the location in KONS (relative to the start of the user area) of the first word of the KONS record being searched for. Search key Specifies the word compared with KONS records during a search. Security key The security key for the range containing the U3 block you want to access. If passwords are not set up in the security directory, use the 1-word security key that has been established for the entire application. Word/record count Indicates the number of words or records to be read or written to.

7830 7402–014

5–5

Using KONS

5.2. KONS Function Descriptions This subsection describes each function you use with the KONS primitive, the KONS areas that it accesses, and the additional parameters the function requires. Eight of the 16 functions access the U3 area; the other eight access areas U1 and U2 and possibly areas S1 and S2. In a KONS request, specify either a mnemonic or a numeric function code. Table 5–3 lists the KONS functions in order of their numeric codes and indicates with Xs which KONS areas the functions access. An asterisk (*) after an X indicates that the function accesses the area only if the S execution option (OPTIONS keyword) is set in the program’s VALTAB entry. Following the table are detailed descriptions of the KONS functions, in alphabetical order. For those descriptions, the numeric function codes are shown in parentheses after the associated mnemonic function codes. Table 5–3. KONS Functions and Areas Accessed Numeric Code

Function Code

Description

S1

S2

U1

U2

U3

CUPDAT

6

Update KONS counter.

X*

X*

X

FILLWR

-2

Fill-write KONS words.

X*

X*

X

KRDLK

7

Read and lock a U3 block.

KREAD

1

Read KONS records.

KWRITE

2

Write KONS records.

KWRKP

9

Write to a U3 block and keep locked.

X

KWRUN

8

Write and unlock a U3 block.

X

LUPDAT

11

Update counter in a U3 block.

X

MSREAD

3

Search with a mask and read KONS records.

SCATRD

-1

Scatter-read KONS records.

SEQSRD

5

SERCHR

X X

X

X

X

X*

X*

X

X

X

X

X

Search sequentially and read KONS records.

X

X

4

Search vertically and read KONS records.

X

X

SREAD

12

Security read of a U3 block.

X

SUPDAT

14

Update security counter.

X

SWRITE

13

Security write to a U3 block.

X

UNLOCK

10

Unlock a U3 block.

X

X

X

* This function accesses the area only if the S execution option is set in the program’s VALTAB entry (OPTIONS keyword) or on the @XQT statement.

5–6

7830 7402–014

Using KONS

5.2.1. Update KONS Counter—CUPDAT Function (6) Update the KONS counter. 1.

CUPDAT, the function, or 6

2.

KONS index, indicating location of counter

3.

J-designator, specifying portion of the counter to update

4. Increment This function accesses the following KONS areas: U1 (with S option), U2, and S2 (with S option).

5.2.2. Fill-Write KONS Words—FILLWR Function (-2) Replace or overlay one or more KONS words with a 1-word constant from the program buffer. Use this function to clear a KONS record or area by filling it with blanks or zeroes. 1.

FILLWR, the function, or -2

2.

KONS index

3.

Buffer address

4. Word count; number of KONS words to be overlaid by the constant This function accesses the following KONS areas: U1 (with S option), U2, and S2 (with S option).

5.2.3. Read and Lock a U3 Block—KRDLK Function (7) Read KONS words from a U3 area block to the program’s D-bank and then lock the block. You can also use this function to allocate a block for use. 1.

KRDLK, the function, or 7

2.

KONS index

3.

Buffer address

4. Word count 5.

Block number, in the range associated with the security key by the security directory entry

6. Security key 7.

Next statement

For Fieldata COBOL, use the COBSEC primitive with this function. Parameters 1 through 6 are the same as shown here; parameter 7 is not used. When using COBSEC, if access to the block indicated causes a deadly embrace, -1 is returned to your program in H2 of the block number field.

7830 7402–014

5–7

Using KONS

5.2.4. Read KONS Records—KREAD Function (1) Read KONS words to the program buffer. 1.

KREAD, the function, or 1

2.

KONS index

3.

Buffer address

4. Word count If the word count is 1, the KONS primitive does not validate the other parameters, and a fast read is performed. This function accesses the following KONS areas: U1, U2, S1, and S2.

5.2.5. Write KONS Records—KWRITE Function (2) Write words to KONS from the program buffer. 1.

KWRITE, the function, or 2

2.

KONS index

3.

Buffer address

4. Word count If the word count is 1, the KONS primitive does not validate the other parameters, and a fast write is performed. If the count is 0, an attempt is made to write outside the KONS area. This function accesses the following KONS areas: U1 (with S option), U2, and S2 (with S option).

5.2.6. Write to U3 Block and Keep Locked—KWRKP Function (9) Write to a U3 area block and then lock the block again. 1.

KWRKP, the function, or 9

2.

KONS index

3.

Buffer address

4. Word count 5.

5–8

Block number

7830 7402–014

Using KONS

5.2.7. Write and Unlock U3 Block—KWRUN Function (8) Write to a U3 area block and then release the block to the pool of unlocked U3 blocks. 1.

KWRUN, the function, or 8

2.

KONS index

3.

Buffer address

4. Word count 5.

Block number

5.2.8. Update Counter in U3 Block—LUPDAT Function (11) Update a counter in a locked U3 area block. 1.

LUPDAT, the function, or 11

2.

KONS index, indicating location of counter

3.

J-designator, specifying portion of the counter to update

4. Increment 5.

Block number

5.2.9. Mask Search and Read KONS Records—MSREAD Function (3) Search a KONS area for a record that matches the mask (the specified combination of bits of the search key). The mask is compared with records in the KONS area, one record at a time. If a match is found, the KONS record is stored in the program buffer and the program terminates. The program is also terminated if the search cannot find a match during the specified number of comparisons. 1.

MSREAD, the function, or 3

2.

KONS index

3.

Buffer address

4. Comparison limit (H1) and record length (H2) 5.

Search key

6. Mask 7.

Record location

8. No-find return address For ASCII FORTRAN, the reference to bit positions in the BITS function is from left to right. If you use NCOUNT for comparison limit and record length (parameter 4), you would construct NCOUNT in this way: BITS (NCOUNT, 1, 18) = M BITS (NCOUNT, 19, 18) = N

7830 7402–014

5–9

Using KONS

H1 of NCOUNT would contain M, and H0 would contain N. For Fieldata COBOL, use the COBKON primitive with this function. The parameters are the same as shown here, except that parameter 8 is not used; if a match is not found, the returned record location is negative. This function accesses the following KONS areas: U1 and U2.

5.2.10. Scatter-Read KONS Records—SCATRD Function (-1) Read to the program buffer a specified number of KONS records of different lengths and from different areas of KONS. A 1-word scatter-read descriptor describes each KONS record to be read by the length of the KONS record (in H1) and by the relative location in KONS of the first word to be read (in H2). The descriptors are stored in a buffer in the desired order. The KONS records that they describe are read into the corresponding area after the descriptors. For example, if you want to read three KONS records of different lengths, your data will appear as shown below. The descriptor in BUFFER(0) allows you to read the KONS record at Address 1 into BUFFER(3). Of course, the buffer area must be large enough to hold the records and the corresponding descriptors. 1

Address 1

0

2

Address 2

1

3

Address 3

2

One word from Address 1 Two words from Address 2 Three words from Address 3

Descriptor Area

3 4,5

Data Area

6,7,8

The SCATRD function uses the following parameters: 1.

SCATRD, the function, or -1

2.

Record count. This is the number of descriptors (three in the above example).

3.

The address of the first scatter-read descriptor; the records are stored in the user’s D-bank after the last scatter-read descriptor (0 in the above example).

4. Buffer size. The size of the entire buffer, descriptors and data area. (This would be 9 in the example above; 3 descriptor words plus 6 data words.) This function accesses the following KONS areas: U1, U2, S1, and S2.

5–10

7830 7402–014

Using KONS

5.2.11. Sequentially Search and Read KONS Records—SEQSRD Function (5) Search a KONS table horizontally for a record. The search returns one or more partial words, the number of partial words compared, and the relative location of the word containing the found partial word. 1.

SEQSRD, the function, or 5

2.

KONS index

3.

Buffer address

4. Comparison limit in H1; in H2, the number of words to transfer from KONS to the user buffer (may be the same as the length of the user buffer) 5.

Search key

6. J-descriptor 7.

Record location

8. No-find return address Each partial word returned is stored, right-justified, in a separate word of the program buffer. The buffer length must be the same as the record length (H2 of parameter 4). In an ASCII COBOL program, use a J-designator instead of a J-descriptor for parameter 6. Define the buffer so you can access the returned values. Partial words are right-justified in whole words of the buffer. For Fieldata COBOL, use the COBKON primitive with this function. The parameters are the same as shown here, except that parameter 8 is not used. If no match is found, the returned record location is negative. This function accesses the following KONS areas: U1 and U2.

5.2.12. Vertically Search and Read KONS Records—SERCHR Function (4) Search a KONS table vertically for a record. The search returns one or more words and the relative location of the found words. A search key is compared with a specified portion of each KONS record, one record at a time. If a match is found, the KONS record is stored in the program buffer and the program terminates. The program is also terminated if no match is found during the specified number of comparisons. 1.

SERCHR, the function, or 4

2.

KONS index

3.

Buffer address

4. Comparison limit (H1) and record length (H2) 5.

Search key

6. J-designator

7830 7402–014

5–11

Using KONS

7.

Record location

8. Next statement For ASCII FORTRAN, the reference to bit positions in the BITS function is from left to right. For Fieldata COBOL, use the COBKON primitive with this function. The parameters are the same as shown here, except that parameter 8 is not used. If no match is found, the returned record location is negative. This function accesses the following KONS areas: U1 and U2.

5.2.13. Security Read of a U3 Block—SREAD Function (12) Read from a U3 area block to the program’s D-bank. No locks are placed on the block, and block locks requested by other programs are not honored. 1.

SREAD, the function, or 12.

2.

KONS index

3.

Buffer address

4. Word count, which may exceed one block 5.

Block number, in the range associated with the security key

6. Security key 7.

Error return address

For Fieldata COBOL, use the COBSEC primitive with this function. Parameters 1 through 6 are the same as shown here; parameter 7 is not used.

5.2.14. Update Security Counter—SUPDAT Function (14) Update security counter in a U3 area block. The block does not need to be locked. 1.

SUPDAT, the function, or 14

2.

KONS index, indicating location of counter

3.

J-designator, specifying portion of counter to update

4. Increment 5.

Block number, in the range associated with the security key

6. Security key 7.

Next statement, where control is passed if the block is locked out by another program.

For Fieldata COBOL, use the COBSEC primitive with this function. Parameters 1 through 6 are the same as shown here; parameter 7 is not used. When using COBSEC, if the U3 block is locked by another program, -1 is returned to your program in H2 of the block number field.

5–12

7830 7402–014

Using KONS

5.2.15. Security Write to a U3 Block—SWRITE Function (13) Write a KONS record to a U3 area block. The block does not have to be locked, but if it is, the lock is retained. Block locks requested by other programs are honored. 1.

SWRITE, the function, or 13

2.

KONS index

3.

Buffer address

4. Word count, which may exceed one block 5.

Block number, in the range associated with the security key

6. Security key 7.

Next statement, where control is passed if the block is locked out by another program

For Fieldata COBOL, use the COBSEC primitive with this function. Parameters 1 through 6 are the same as shown here; parameter 7 is not used. When using COBSEC, if the U3 block is locked by another program, -1 is returned to your program in H2 of the block number field.

5.2.16. Unlock a U3 Block—UNLOCK Function (10) Release a U3 area block. 1.

UNLOCK, the function, or 10

2.

Block number

For ASCII COBOL, use UNLOK instead of UNLOCK for parameter 1.

7830 7402–014

5–13

Using KONS

5–14

7830 7402–014

Section 6 Using Performance Improvement Techniques This section discusses the following techniques that can be used to speed up the scheduling and execution of standard TIP (non-HVTIP) application programs: •

Next message

•

Multiple initialization (multiple INITAL)

•

Resident online (RTPS) programs

•

Self-destructive program reload

•

Block transfer loading

•

Program restart

•

Program sticking and reactivation

This subsection describes the advantage of each technique and explains what the administrator needs to do to implement the technique, how you need to structure TIP programs that can use the technique, and under what execution conditions the technique can be used. Self-destructive program reload and program restart are set up program by program; block transfer loading and program sticking and reactivation are set up program by program and then enabled or disabled for the entire system. See Section 1 for guidelines on structuring a transaction program as self-destructive, self-initializing, or reentrant. Parameters for validation table (VALTAB) entries, which the administrator defines for transaction programs, are described in the Transaction Processing Administration and Operations Reference Manual. Console keyins (such as TP MAX) for operators and administrators are described in the Exec Operations Reference Manual. The setting of flagbox bits is covered in both manuals, as well as in the description of the FOXER and FLBOX primitives in this manual (see Section 8.4).

7830 7402–014

6–1

Using Performance Improvement Techniques

6.1. Next Message Request Messages for a transaction program are queued and processed sequentially. When a program using the next message request feature transmits its output message, the TIP termination logic scans the input queue; if there are outstanding messages for it, the program is restarted. The time needed for restarting, however, is considerably more than for requesting the next message. The next message feature is valid only for reentrant, self-initializing, or HVTIP programs. The transaction program does not request the next message until it is finished with the current message. Here is the correct processing sequence: 1.

Initialize and read input message.

2.

Process message and prepare output message.

3.

Transmit output message.

4. Repeat steps 1 through 3. If your site uses the TIP File Security feature, transaction programs that use the next message feature may not be desirable. See Section 8.3 for more information on writing transaction programs when TIP security features are configured.

6.2. Multiple Initialization—Multiple INITAL You can include multiple initialization requests in a transaction program as a program performance improvement technique. This technique is sometimes called “multiple INITAL” because of the INITAL primitive (see Section 2.1.2), which is part of the COMPOOL interface. But you can also use the same technique with other interfaces. If a transaction program issues multiple initialization requests, the updates from each program activity must be successfully committed before the next initialization request is issued to process the next activity. Thus, the program must issue a commit request (the COMMIT primitive, as described in Section 4.3, if you use the TIP File Control interface) before each successive initialization request. The program must also supply an escape address for the next instruction, to be processed when there are no more program activities to process. The multiple INITAL feature is supported only for self-initializing (VALTAB PRG 2), reentrant (PRG 3), and HVTIP (PRG 5) programs. It is not available for self-destructive and online batch transactions. Here is a general sequence for incorporating multiple initialization requests to a transaction program: 1.

Start the program.

2.

Issue an initialization request:

3.

6–2

•

If there is no program activity to process, terminate the program.

•

If there is an activity to process, continue with the remaining steps.

Process the program activity.

7830 7402–014

Using Performance Improvement Techniques

4. Issue a commit request to commit the updates from the completed activity. 5.

Go back to step 2.

If the program uses COMPOOL, the terminate-commit default action provides greater efficiency than the advance-commit default action. With the UDS interface, a program issues a Free request before each successive initialization request to let UDS Control interface with Step Control. This allows sets of multiple initialization requests in a given Impart/Depart sequence, providing a reduction in processing overhead. 1.

Start the program.

2.

Issue an Impart request to access the UDS interface.

3.

Issue an initialization request: •

If there is no program activity to process, skip to step 7.

•

If there is an activity to process, continue with step 4.

4. Process the program activity. 5.

Issue a Free request.

6. Go back to step 3. 7.

Issue a Depart request to commit the updates from the completed activities.

8. Terminate program. If your site uses the TIP File Security feature, transaction programs using the multiple initialization feature may not be desirable. See Section 8.3 for more information on writing programs for operating with the TIP security features configured. You must include an Executive request LEVEL$ in the program to reset the activity level of the program after each execution. The VALTAB entry for the program cannot reset the activity level because the value in the LEV (switching level) field affects only the initial loading of the program. See the ER Programming Reference Manual for additional information.

6.3. Resident Online Programs—RTPS Feature In an environment where a large percentage of incoming transactions are handled by a small subset of transaction programs, an increase in system throughput is achieved by using the Resident Transaction Program System (RTPS) program. This feature lets a transaction program be loaded and permanently “stuck” in memory. This program can then process incoming transactions without the overhead necessary for program reloading. The RPINIT utility or a TIP keyin loads a resident online program. Once loaded, the program resides in main storage until a TIP keyin or RPINIT is requested to delete it. However, RTPS programs are eligible for paging. The RPINIT utility is described in the Transaction Processing Administration and Operations Reference Manual and the TIP keyins in the Exec Operations Reference Manual.

7830 7402–014

6–3

Using Performance Improvement Techniques

In an XTC system, RTPS is supported only in the local host mode of operation. If your site uses the TIP File Security feature, the use of the RTPS program may not be allowed. RTPS programs executed outside of a TIP session have only minimal security capability and no security privileges. Beginning with HMP IX 4.0, changes to TPMAX were made that may allow your site to realize a performance gain by increasing its use of RTPS and multiple-initial features. These changes include the following: •

TIP scheduling can always be suspended by setting TPMAX to zero, even if RTPS transactions are registered.

•

At RTPS initialization time, the system administrator can specify (on an RTPS program number basis) whether RTPS transactions are to be dedicated or nondedicated. Dedicated RTPS transactions operate as before, with the exception that TPMAX can be set to zero when they are registered. Nondedicated RTPS transactions do not have a TIP scheduling advantage over other transactions, and the number of nondedicated RTPS transactions is allowed to exceed TPMAX. TPMAX control does not consider nondedicated RTPS-deactivated transactions to be active. Therefore, nondedicated RTPS-deactivated transactions do not impact TIP scheduling beyond the resources that they hold, such as MCB or UDS slots.

•

TPMAX control is extended to multiple-initial requests. If the number of active transactions in a system equals or exceeds TPMAX and TPMAX control determines that higher priority scheduling requests are queued, ERs QI$NIT and PI$NIT return a “no message” status. (This change does not impact dedicated RTPS transactions, since they are always considered the highest priority scheduling requesters.)

6.3.1. Resident Online Program Logic To most efficiently use the RTPS program feature, code your program using the multiple INITAL call logic. Similarly, you can modify an existing program to use the multiple INITAL call logic and, therefore, to be ready for use as an RTPS program. When your transaction program is loaded as a resident online program, the escape address provided by the INITAL call is used only when the program terminates and reloads because of an error, or when the program is deleted by the RTPS program or by TIP keyin. During the period of its residency, the program is deactivated when no input is received, and it is reactivated when there is input destined for it. A transaction program that does not perform the multiple INITAL call can be used as an RTPS program. Such a program loses some throughput advantage of multiple calls to INITAL but retains the advantage of being “stuck” in memory.

6–4

7830 7402–014

Using Performance Improvement Techniques

6.3.2. Initialize Resident Online Program—RTPSI Primitive The RTPSI primitive lets a utility program initialize an RTPS program or alter the number of copies. The primitive loads copies of a transaction program as resident online programs. The number of copies loaded can be between one and the maximum allowed in the VALTAB entry. If you do not specify a number, or if a number greater than the VALTAB maximum is specified, then the maximum number of copies allowed by the program’s VALTAB entry are loaded. The following is the format for an RTPSI request: CALL RTPSI parameter1, parameter2, parameter3 The parameters are as follows: 1.

S1: Bits 0 through 3 are unused. Bit 4, if set, indicates transactions for this RTPS program number are nondedicated; if clear, it indicates they are dedicated. Bit 5, if set, indicates parameter 3 is present and contains the number of resident copies to be loaded. S2,S3: RTPS program number (1 ≤ u ≤ PRIRTP) H2: Program number, from VALTAB entry

2.

Program name, from the VALTAB entry; 1 to 6 Fieldata characters left-justified, space-filled.

3.

Number of resident copies to be loaded; this parameter is optional and is recognized only if bit 5 of S1 of parameter 1 is set.

On return, parameter 1 contains one of the following status indicators: 000

Normal completion

001

Illegal program name

002

Not reentrant or self-initializing program

003

Program number already defined as resident

004

Illegal program number

005

I/O error on VALTAB read

006

RTPS program number previously defined

007

Illegal RTPS program number (that is, not 1 ≤ u ≤ PRIRTP)

010

Wait time exceeded while loading the RTPS program. (The program can be partially loaded but cannot execute. Use RTPSD to delete it.)

011

RTPS program load in progress

012

No VINDEX entry for requested program

013

Total RTPS program resident copies requested exceeds value set by TIPTPS configuration parameter or by TIPMAX keyin.

7830 7402–014

6–5

Using Performance Improvement Techniques

Following are additional considerations about the RTPSI primitive: •

If H2 of parameter 3 contains an error status of 5, H1 contains the I/O error status code. In all other circumstances, parameter 2 is zero.

•

When completed, copies of the program are resident in main storage with real-time positioning and are waiting to process transaction input.

•

The RTPSI primitive can be called even if input is being received during the initialization process for this program.

•

If the target program is initialized through a previous RTPSI request, this function is reissued to alter the number of resident copies.

6.3.3. Delete Resident Online Program—RTPSD Primitive The RTPSD primitive lets a utility program delete an RTPS program. It purges all copies of the previously initialized program from main storage. Here is the format for an RTPSD request: CALL RTPSD parameter1, parameter2, parameter3 The parameters are as follows: 1.

S1: If 01, then optional parameter 3 is specified S2,S3: RTPS program number (1 ≤ u ≤ PRIRTP) H2: Program number, from VALTAB entry

2.

Program name, from the VALTAB entry; 1 to 6 Fieldata characters left-justified, space filled.

On return, parameter 1 contains one of the following status indicators:

6–6

000

Normal completion

001

Illegal program name

003

Program not defined as an RTPS program

006

RTPS program number not defined

007

Illegal RTPS number

010

Wait time exceeded while trying to delete the RTPS program. (Program still in execution and therefore not yet unloaded. It is automatically unloaded when execution terminates.)

011

RTPS program deletion in progress

012

No VALTAB index (VINDEX) entry for requested program

7830 7402–014

Using Performance Improvement Techniques

6.4. Block Transfer Loading A copy of an active program is made by block transfer, and the new copy of the program is loaded. Advantage You can avoid the overhead of I/O to read the program banks from mass storage. Implementation •

•

In the VALTAB entry for the program, the administrator sets the following: −

The program type (PRGTYP keyword) to 2 (self-initializing) or 3 (reentrant)

−

The concurrency limit (COPIES keyword) for the program to at least 2 (the default is 5)

−

The K program status option (STATUS keyword) to enable block transfer loading for the program

To enable block transfer loading for the system, the administrator or operator sets the BTLOADING flagbox bit.

Programming Requirements •

The program must be self-initializing or reentrant.

•

The program cannot expand, contract, or create banks.

•

If the program is an absolute element, it cannot be segmented and it cannot have any dynamic banks.

Execution-Time Requirements •

A copy of the program must currently be active.

•

If the program is a ZOOM, all of the program’s banks must be in main storage, and the program cannot have taken any contingencies.

6.5. Program Restart The program is restarted if there is an input message on the wait queue at program termination. Advantage You can avoid the overhead of allocating and loading the banks of the restarted program. Implementation In the VALTAB entry for the program, the administrator sets the program type (PRGTYP keyword) to 2 (self-initializing), 3 (reentrant), or 5 (HVTIP).

7830 7402–014

6–7

Using Performance Improvement Techniques

Programming Requirements •

The program must be self-initializing, reentrant, or HVTIP.

•

The activity at program termination must be the initial activity.

•

If the program is a ZOOM, the program cannot expand, contract, or create banks.

•

If the program is an absolute, it cannot contract or create banks.

•

The program cannot create any print or punch files.

•

If the N execution option (OPTION keyword) is set in the program’s VALTAB entry, the program must send an output or pass-off message before terminating.

•

If COMPOOL is used, the program must release all input and output COMPOOL before terminating. If MCB is used, the program must terminate normally with MCB.

•

Any Exec files or TIP scratch files that the program assigns must be freed before program termination.

Execution-Time Requirements •

The program must terminate normally. If it is a ZOOM, it cannot have taken any contingencies.

6.6. Program Sticking and Reactivation A copy of the program is saved (sticks) in main storage if there is no input message on the wait queue at program termination. The program copy is reactivated when there is an input message on the queue. Advantage You can avoid the overhead of allocating and loading the program banks. Implementation •

•

In the VALTAB entry for the program, the administrator sets the following: −

The program type (PRGTYP keyword) to 2 (self-initializing), 3 (reentrant), or 5 (HVTIP)

−

The I program status option (STATUS keyword) to enable sticking for the program

To enable program sticking and reactivation for the system, the administrator or operator sets the STICKING flagbox bit.

Programming Requirements

6–8

•

The program must be self-initializing, reentrant, or HVTIP.

•

The activity at program termination must be the initial activity.

•

Any Exec files or TIP scratch files that the program assigns must be freed before program termination.

•

The program cannot create any print or punch files.

7830 7402–014

Using Performance Improvement Techniques

•

If the program is a ZOOM, it cannot expand, contract, or create banks.

•

If the program is an absolute, it cannot contract or create banks.

•

If the N execution option (OPTION keyword) is set in the program’s VALTAB entry, the program must send an output or pass-off message before terminating.

•

If COMPOOL is used, the program must release all input and output COMPOOL before terminating.

•

If MCB is used, the program must terminate normally with MCB.

•

The program cannot create a queue bank repository at the program or activity level.

Execution-Time Requirements •

The program must terminate normally. If it is a ZOOM, it cannot have taken any contingencies.

•

Test or test/training mode cannot be in effect; the O or Y execution option (OPTION keyword) cannot be set in the program’s VALTAB entry or by the UOPTOR primitive, and the TRAINFB flagbox bit cannot be set.

Additional Considerations Sticking and reactivation are useful for programs that are frequently referenced and can be made to conform to the programming requirements described in this subsection. But sticking may introduce performance problems if it is used on inappropriate programs. Also, allowing too many stuck programs can have a negative effect on system performance because of the amount of system resources (memory or EXPOOL) they use. Stuck programs do not fragment memory, but they can be flushed from the system after a period of time if the system needs the resources they are using.

7830 7402–014

6–9

Using Performance Improvement Techniques

6–10

7830 7402–014

Section 7 HVTIP Programs The High-Volume Transaction Processing (HVTIP) environment is intended for programs with the following structure: •

The processing of any given transaction can pass through an arbitrary sequence of subprograms.

•

A high rate of throughput must be maintained.

Under the standard transaction environment, such an application must use user-to-user (program-to-program) pass-off to process a transaction program. See 2.2.3 for a description of user-to-user (or program-to-program) pass-off. The user-to-user pass-off technique has several restrictions: •

The program’s D-bank is not passed along.

•

Database locks are lost when each program terminates.

•

The pass-off is inefficient, since sending a message can involve extra I/O operations. The target program must retrieve the message, which again can create I/O overhead.

In an HVTIP environment, you call a subprogram by replacing your program’s I-bank but keeping the D-bank. Furthermore, each subprogram is independently compiled and collected or linked to ease the maintenance of a large set of subprograms. Figure 7–1 shows the string of execution for an HVTIP session, including how the D-bank is passed from the initial control program (ICP) to the subprograms.

7830 7402–014

7–1

HVTIP Programs

Figure 7–1. HVTIP Execution The use of HVTIP may not be desirable if a site is using TIP File Security. HVTIP’s multi-input environment and its processing of transactions through an arbitrary sequence of subprograms is not compatible with the maintenance of some secure files.

7.1. HVTIP Program Structure A transaction is processed under the control structure of a single-activity program defined by a validation table (VALTAB) entry or record. This program is called the initial control program (ICP). Transactions executing under different transaction codes (and, therefore, from different VALTAB entries) access the same subprogram banks in the HVTIP libraries. Multiple VALTAB entries are used to maintain concurrency control on different classes of work or to vary the D-bank requirement. All VALTAB entries, however, refer to an ICP. Subprogram banks do not have VALTABS. The VALTAB entry describes the initial state under which transaction processing begins. All input is initially processed by an ICP from some HVTIP library based in the main I-bank window. The main D-bank window contains the activity work area (AWA), which remains in existence for the duration of the transaction processing. The utility I-bank and utility D-bank can contain common banks, if you choose.

7–2

7830 7402–014

HVTIP Programs

During transaction processing, any HVTIP subprogram bank can be switched to the main I-window through a special Executive request (ER) or call. Any other window can be switched to or from any common bank through normal bank basing instructions. Finally, it is possible to expand or contract the size of the AWA during transaction processing to handle transaction programs that are much larger or much smaller than normal. See Section C.3 for information on bank expansion and contraction. The initial AWA size should be large enough to handle a normal transaction. The AWA does not appear in any library file and is never loaded. The initial control program is responsible for initializing the AWA.

7.1.1.

Common Banks HVTIP programs can reference alternate file common banks (AFCB) by using bank basing instructions or initial basing specifications. AFCBs are processed by the Exec dynamic allocator (DA) complex. The templates must reside in absolute elements in program files to be properly processed by the DA complex. References to nonconfigured common banks (NCCB) are not supported by the HVTIP program environment. User program banks cannot be switched in the main I-bank window through bank basing instructions. The only way to base a new bank in the main I-window for an HVTIP program is to use one of the HVTIP bank switching requests described later in this section.

7.1.2. Extended Mode HVTIP There are several differences between basic mode and extended mode in HVTIP. In extended mode, the ICP does not have to initialize the D-bank; the universal run-time system does it automatically. However, each I-bank does have to load the D-bank. In addition, all unused B-registers can be used to base common banks, enlarging the utility area significantly. The subsection (7.1) and 7.3 are the only parts of Section 7 that you need to read for HVTIP program coding. The standard extended mode primitives may be used. Performance improvement is obtained by linking instead of coding. For more information, see the Linking System Programming Guide. See the UCS Application Development Programming Guide for information about extended mode HVTIP and mixed mode HVTIP. Multiactivity programs are useable in extended mode if the dynamic configuration parameter HVTIPMACT is true. See the Exec Installation and Configuration Guide.

7830 7402–014

7–3

HVTIP Programs

7.1.3. HVTIP Program Libraries Each HVTIP bank that can be used by an HVTIP program is derived from an independent absolute element. Each must contain a reentrant, write-protected I-bank to allow multiple transactions to base the same bank. One or more HVTIP library files must exist. Each library file contains static banks, dynamic banks, or both. Static banks are in storage whenever the associated library is online. A dynamic bank is in storage if one or more activities has the bank based. An HVTIP program uses any bank in any library as long as the desired library is online. The contents and status of HVTIP libraries are controlled through the TPUR processor. Before a library is placed online, the proper TIP main storage groups must be established, since HVTIP bank loading occurs only through TIP main storage control. The contents and status of HVTIP libraries are controlled through the TPUR processor. The contents and status of HVTIP libraries are controlled through the TPUR processor. Before a library is placed online, the proper TIP main storage groups must be established, since HVTIP bank loading occurs only through TIP main storage control. In an Extended Transaction Capacity (XTC) system, the HVTIP program libraries are maintained in shared mass storage. See 3.4 for more information on the XTC system.

7.1.4. HVTIP Program Banks To create any HVTIP bank, you compile and collect an absolute element, or compile and link a ZOOM, using standard 2200 Series processors. In general, the absolute element or ZOOM for an HVTIP bank consists of one write-protected I-bank. It must also contain one D-bank if the I-bank is an initial control program. After the Collector has created the absolute element, the TPUR utility must be used to insert the element to some HVTIP library file. The bank is ready for use when the library is online. Since each HVTIP bank is reentrant and write-protected, multiple transactions can base the same bank simultaneously. At most, only one copy of a given I-bank is in main storage. Since there is a one-to-one correspondence between transactions and their D-banks, and the processing of a transaction passes through an arbitrary sequence of I-banks (all of which may require D-bank space), creating a single D-bank that satisfies the D-bank requirement of every high-volume transaction is impossible. Main storage space to be used as a D-bank throughout the processing of a transaction is allocated when the initial control program is scheduled for execution. In basic mode, the initial control program must initialize the D-bank. In extended mode, the D-bank is automatically initialized by the universal run-time system. Then, as each succeeding subprogram receives control, it initializes its required space in the transaction D-bank. Thus, each program I-bank must contain information in some form that enables it to initialize its D-bank text. The techniques for performing D-bank text initialization vary depending on the compiler used. If you are writing a program in Meta-Assembler (MASM), you must write a subroutine for initializing the D-bank. But, if you are writing in ASCII COBOL or ASCII FORTRAN, the compiler automatically generates the necessary code or invokes the necessary library subroutines.

7–4

7830 7402–014

HVTIP Programs

Once a program library is initialized for online use, the site administrator uses TPUR to add, delete, or replace individual banks in that library, and to pack or list the contents of a library file. The administrator can update a program library while the library is being used in the active system. Only one HVTIP I-bank is based at a time; this bank, which may or may not be the ICP, is assigned bank descriptor index (BDI) 4. In a basic mode HVTIP environment, a contingency routine should be placed in the D-bank (BDI 5) so that it is always based.

7.2. Passing Control by Call, Transfer, and Return Control in basic mode is passed between HVTIP banks by call, transfer, and return. A call implies that a return subsequently occurs, whereas a transfer is a one-way transfer of control. These functions are invoked in high-level languages by an external subprogram call and return, and the required bank switching is performed through special ERs: CALL$

Call a subprogram bank.

XFR$

Transfer control to another HVTIP program bank.

RTN$

Return from a called subprogram.

XRS$

Cancel an outstanding return stack.

The rest of this subsection shows sample MASM routines that call these ERs.

7.2.1. Calling an External Subroutine For an external subroutine call, the compiler generates the following: LXI,U

X11, BDICALL$+module-name

IBJ$

X11, module-name

BDICALL$ must precede the module name in the expression. The Collector resolves the reference in one of the following three ways: 1. LXI,U

X11, 0

LMJ

X11, module-address

This calling sequence is used in two cases: a.

The called module is collected in the same bank.

b. The called module is defined in CERU$ as an entry point in a certain common bank. When a program bank is collected, an additional directive

7830 7402–014

7–5

HVTIP Programs

IBANK, UXL common-bank-name or DBANK, UXL common-bank-name may denote that the common bank is assumed to be based in the utility I- or D- window. The L option denotes that the Collector assumes the common bank is based at the time the call is made. 2. LXI,U

X11, module-id

LMJ

X11, interface-routine1

This calling sequence is used if the module-id is defined in a module name equate (MNQ) element that is included in the collection. The following TYPE directive is needed: TYPE IBJLNK element1, routine1 where element1 is the MNQ element name defining modules entered by call, and routine1 is the call interface routine. The interface routine can be collected with each bank, or it can be in a common bank. This routine must translate the module-id to a library number, bank number, and entry point, and execute an ER CALL$ that simulates an LIJ by switching a new HVTIP bank to the main I-window. 3. LXI,U

X11, common-BDI

LIJ

X11, entry-point

This calling sequence is used if the called module is defined in a common bank other than the one covered in case 1b.

7.2.2. Call Interface The call interface routine is entered for a call as follows: LXI,U

X11, module-id

LMJ X11,

entry-point

The parameters are passed in A0 as follows: A0 = (number-of-parameters, parameter-list) The following is the call interface routine:

7–6

L

A2,X11

LXI,U

X11,0400000

LXM,U

A2,0

7830 7402–014

HVTIP Programs

ER

CALL$

J

0,X11

This interface routine assumes the module-id is defined in the MNQ element in the following form: ABCDEF* EQU 0llbbbb000000 where ll is the library number and bbbb is the bank number. The entry point is assumed to be determined by the Collector. The label must be externalized. The entry and exit points for ER CALL$ are •

Entry A2 = (llbbbb, p) where ll is the library number (6 bits), bbbb is the bank number (12 bits), and p is the entry point. If p = 0, the bank entry point determined by the Collector is used.

•

Exit ER CALL$ Return occurs to the location following the ER CALL$ when the called bank executes ER RTN$. The library, bank, and return point of the calling bank are saved when the ER CALL$ is executed. The maximum number of returns that can be nested is a configuration parameter.

7.2.3. Transferring Control to Another Bank A transfer is an external transfer of control to another program bank. The compiler generates the following: LXI,U X11, BDICALL$+module-name IBJ$ X11, module-name The Collector always resolves this in a manner similar to case 2 (in 7.2.1) for subroutine calls: LXI,U X11, module-id LMJ X11, interface routine2 A second IBJLNK directive must be included in the collection of any bank that does a transfer: TYPE

IBJLNK element2, routine2

where element2 is the MNQ element name defining modules entered by transfer, and routine2 is the transfer interface routine.

7830 7402–014

7–7

HVTIP Programs

7.2.4. Transfer Interface The transfer interface routine is similar to the call interface routine, except that it executes an ER XFR$. This routine is entered for a transfer by the Collector as follows: LXI,U

X11, module-id

LMJ

8 X11, transfer-interface-routine

For a transfer, no arguments are passed; therefore A0 = 0 The interface routine sets A0 negative; this serves as a flag to the called module that it is being entered by transfer. The entry and exit points for ER XFR$ are •

Entry A2 = (llbbbb,p) ER XFR$

where ll is the library number (6 bits), bbbb is the bank number (12 bits), and p is the entry point. If p = 0, the bank entry point determined by the Collector is used. •

Exit None

Because this is an unconditional transfer of control, no return occurs.

7.2.5. Returning Control After a Call The compiler must generate a return sequence that allows for any of the three types of calling sequence generated by the Collector: 1.

J

0,X11

This calling sequence returns control directly to the calling routine. 2.

If an ER CALL$ was executed on the call, an ER RTN$ must be executed on the return.

3.

LIJ X11,0,X11 This calling sequence returns control to the main I-bank if a common bank is switched to the main I-window through LIJ on the call.

7–8

7830 7402–014

HVTIP Programs

The return sequence generated by the compiler must test the upper half of X11 to determine the type of return, as in this example: L

A4,X11

SSL

A4,18

JZ

A4,0,X11

TNE,U

A4,0400000

ER

RTN$

LIJ

X11,0,X11

The use of register A4 is arbitrary; any A-register suffices. No information is passed to the Exec on the ER RTN$. Execution control passes to the location following the most recent ER CALL$ in the calling bank. The entry and exit points for ER RTN$ are •

Entry ER RTN$ No entry parameters are passed with this ER.

•

Exit None This ER returns to the location following the most recent CALL$.

7.2.6. Cancel Return Stack To allow a program to cancel an outstanding return stack, an ER XRS$ is used. The entry and exit points for ER XRS$ are as follows: •

Entry ER XRS$ No entry parameters are passed with this ER.

•

Exit Upon return, the return stack, if any, has been cleared.

7830 7402–014

7–9

HVTIP Programs

7.3. Extended Mode Call, Transfer, and Return HVTIP absolutes and HVTIP ZOOMs can reside in the same HVTIP library. But you cannot switch between HVTIP absolutes and HVTIP ZOOMs within an execution thread unless the program is set up as a mixed mode HVTIP program. HVTIP programs can switch modes when doing a CALL or TRANSFER to another HVTIP subprogram. In other words, an extended mode HVTIP ZOOM can access a basic mode HVTIP absolute and vice-versa. This is allowed for all HVTIP transactions where •

The ICP is an extended mode ZOOM.

•

The VALTAB W indicator is used (IND,W).

Refer the UCS Application Development Programming Guide for more complete information on extended mode and mixed mode HVTIP programs. HVTIP I-banks are allowed to call extended mode or basic mode basic mode banks (for example, common banks or subsystems) using the CALL or LBJ instructions. The following CALL interfaces are used: HV_CALL_SUB

Call a subprogram bank.

HV_XFR_SUB

Transfer control to another HVTIP program bank.

HV_CANCEL_RS

Cancel return information for inactive programs.

HV_XFR_CANCL

Transfer control and cancel return information.

7.3.1. Call Subprogram For control to be passed, there must be no outstanding I/O. The use of the HV_CALL_SUB interface implies that control will return at the end of the program called.

7.3.2. Transfer Subprogram The HV_XFR_SUB interface unconditionally transfers control to the called subprogram. No return information is saved.

7.3.3. Cancel Return Stack The HV_CANCEL_RS interface cancels the return information on all subprograms that do not return control to the calling subprogram. This interface cannot be used in programs that have any outstanding subsystem transitions.

7.3.4. Transfer and Cancel Return Stack The HV_XFR_CANCL interface unconditionally transfers control to the called subprogram, and cancels all return information. It can be simulated by calling HV_XFR_SUB and then HV_CANCEL_RS.

7–10

7830 7402–014

HVTIP Programs

7.4. Initial Control Program In basic mode, the ICP must initialize the D-bank; it is done automatically in extended mode. The initial control program then performs any program initialization desired, such as contingency registration and retrieval of input message. Control then passes to some other HVTIP bank through a call or a transfer.

7.4.1. Constructing an Initial Control Program An initial control program must be collected with one I-bank and one D-bank. These banks must be initially based in the main I- and main D-window. Common banks are optionally based in the utility I- and utility D-windows. The site administrator uses the TPUR utility to place the I-bank in a library file in the same manner as for any other HVTIP bank. TPUR does not transfer the D-bank contents to the library, but the D-bank is required in the collection to define the initial D-bank requirement for the program. The initial control program is either a static bank or a dynamic bank. You specify this property by using the D option on the Collector I-bank statement for the bank. Dynamic banks (D option) are loaded only when needed. Static banks (no D option) are permanently loaded in main storage, and give better performance (at the expense of main storage space). Static banks are used for subprograms frequently used by the application.

7.4.2. VALTAB Entries for an Initial Control Program An initial control program is associated only with the Main, Alternate, or Test library cycles in one or more VALTAB entries. The site administrator sets up these library cycles, which are described in the Transaction Processing Administration and Operations Reference Manual. The administrator creates the VALTAB entry (or entries) for the ICP by specifying the HVTIP program type (PRGTYP = 5). The system can have multiple VALTAB entries for each ICP; this allows the ICP to be called with different options and execution-time characteristics. Each VALTAB entry must have the HVTIP program type (PRGTYP = 5).

7.4.3. Initial Register State When the initial control program begins execution, the Exec passes the following values in the A and R registers: A0 Possible values are as follows: 0—This instance of execution is the result of an initial program start. Therefore, complete program initialization is required. 1—This instance of execution is the result of a program restart. Therefore, it is possible to bypass portions of program initialization.

7830 7402–014

7–11

HVTIP Programs

A1 Storage limits of the main D-bank: Upper limit (H1) The relative address of the last word of the D-bank. Lower limit (H2) The relative address of the first word of the D-bank. This is always equal to the Collector-determined value of FRSTD$. The upper limit at execution time may or may not be equal to the value of LASTD$ (determined by the Collector). It is possible to specify the desired D-bank size in the VALTAB for the ICP, thereby ignoring the size determined by the Collector. A2 - A3 Feature mask: Bits 0-35

Unused

Bits 36-41

Numerical Host-ID, (1 = A, 2 = B ...)

Bits 42-63

Unused

Bit 64

VERSION3E type hardware

Bit 65

Unused

Bit 66

Queuing Architecture supported

Bit 67

Unused

Bit 68

Unused

Bit 69

Basic mode

Bit 70

Extended mode

Bit 71

Unused

A4 Program type: 011

Self-destructive

012

Self-initializing

013

Reentrant

014

Online batch

015

HVTIP

A5 Bit 33 is always 1. Bits 17 through 0 contain program options as defined in the VALTAB entry.

7–12

7830 7402–014

HVTIP Programs

R1 Date in ER DATE$ format (Fieldata) with a local time base. R2 Time and date in ER TDATE$ format with a local time base. R3 Accumulated CPU time Registers R11 through R15 contain the first 5 words of the master configuration table (MCT): R11 and R12 System type (two words, left-justified) R13 and R14 Exec level (two words, left-justified) R15 Site-id (left-justified)

7.5. HVTIP Information The information in this subsection applies to HVTIP programs written in MASM, ASCII FORTRAN, or ASCII COBOL. Also see Section 8, which presents language-specific information for TIP programs in general.

7.5.1. MASM Programs When you code a reentrant MASM program, you cannot use the Store Location and Jump (SLJ) instruction when the jump address is in the program’s I-bank. Literals are collected in the I-bank. This minimizes use of main storage because only one copy is necessary. You can compile the literals under a separate location counter, as in this example, which is mapped to the I-bank: $(3) LIT

7.5.2. ASCII FORTRAN Programs Use the automatic storage feature of ASCII FORTRAN for HVTIP program banks. This feature is enabled by the DATA=AUTO and DATA=REUSE COMPILER statement options. For complete information on automatic storage, see the ASCII FORTRAN Programming Reference Manual. The following restrictions apply: •

A RETURN can never be done from a subprogram with a DATA=REUSE option.

•

Local variables not initialized by DATA statements do not have a value of zero on entry.

7830 7402–014

7–13

HVTIP Programs

•

Arguments set on entry at one entry point are not available on entry at another point of the same subprogram.

•

Names of internal subprograms cannot be passed to other external subprograms to be called at that time.

•

If the program reads to a Hollerith field of a FORMAT statement, the value remains only as long as the subprogram containing it is active.

•

Local variables do not have their last value on reentry to a subprogram.

•

Because the Test-Set (TS) instructions are used to make a program reentrant, ASCII FORTRAN programs are not good candidates for block transfer loading. Errors resulting from block transfer loading might not appear immediately.

7.5.3. ASCII COBOL Programs ASCII COBOL programs or subprograms written for the HVTIP environment are subject to the following restrictions: •

The MEMORY 3 MODULES phrase must be used in the OBJECT-COMPUTER clause of each subprogram.

•

The program must ensure that its own internal data is self-initializing. Altered working-storage items do not have initial value unless the Procedure Division contains code to initialize them before they are used.

•

Asynchronous processing, using the COBOL PROCESS command, is not allowed.

•

Standard I/O against files (with the exception of Universal Data System interfaces) is not allowed in self-initialize mode; however, the ACCEPT and DISPLAY commands are allowed.

•

Transfer from a COBOL HVTIP bank to FTN I HVTIP banks is not supported.

•

The program D-bank must be collected as a relocatable segment (RSEG) so the D-bank is properly initialized at execution.

For complete information on ASCII COBOL, see the ASCII COBOL Programming Reference Manual.

7.5.4. Alternate ASCII Primitives to Use with HVTIP An alternate set of ASCII primitives with the version name “HVTIP” is available for use by an HVTIP program bank. These primitives have the same entry-point names as the standard ASCII primitives, so your program uses the same primitive calls as a program that is not for HVTIP. But your program must first reference the following elements, which define the primitives:

7–14

•

CONECT/HVTIP

•

INITAL/HVTIP

•

KONS/HVTIP

•

UOPAND/HVTIP

•

UOPTOR/HVTIP

7830 7402–014

HVTIP Programs

•

CRDPHS/HVTIP

•

CSTPHS/HVTIP

For KONS/HVTIP, the test and training modes of execution are not available. The way you reference these definition elements depends on the language of your program. Use the format shown in Section 8 for referencing the procs (definition procedures) for your language.

7.6. Collector Considerations for HVTIP Program Banks For successful processing by TPUR, an absolute element must meet certain format requirements. This section states those requirements and describes the use of the Collector directives needed to meet them. TPUR processes an absolute element containing up to 25 banks. Although up to 25 banks appear in the absolute element, TPUR assumes a specific use for only three banks. Extra banks are ignored by TPUR. The COPY command is aborted by TPUR if incorrect bank format and use are detected. High-volume banks are formatted in a manner internal to HVTIP, while AFCB templates are processed by the Exec dynamic allocator complex. Consequently, high-volume programs cannot contain an AFCB template. However, high-volume program banks may reference AFCB basing instructions. NCCB templates and references to NCCBs are not supported by HVTIP or TIP.

7.6.1. I-Bank The I-bank has the lowest bank descriptor index (BDI) of all banks contained in the absolute element and is assumed to contain in its main segment portion the entire text to be copied to the I-bank text component of the program bank. It is defined by the first IBANK statement in the Collector directive set. The I-bank must be write-protected. If the R option does not appear on the Collector IBANK directive, TPUR sets the write-protect bit when it copies the bank to the library file. The entire I-bank text is described by one access control word (ACW). Intervening zero-filled ACWs are not permitted. This restriction prevents the I-bank from containing any void areas (described by RES directives) that are larger than the value of MINGAP for the collection. Unisys does not recommend increasing the size of MINGAP through Collector directives if initialization segments are included in the program bank. Large MINGAP values cause the segment texts to become too large, wasting storage space. This restriction does not concern users of high-level languages, because compilers do not generate void areas in the I-bank. Load-control information for initialization segments may assume arbitrary format. The I-bank is present in every case. It can be the only bank present.

7830 7402–014

7–15

HVTIP Programs

7.6.2. D-Bank The D-bank has the next lowest BDI after that of the I-bank. The D-bank can appear in the absolute element. Its presence is required in two cases: •

If initialization segments are used, they are defined and contained completely in the D-bank.

•

If this absolute element defines an initial control program (designated by using the V option on the COPY command), the D-bank appears to identify the address limits of the D-bank allocated for the program’s execution. The D-bank need not contain any data and is not transferred to the program library.

Data included in initialization segments defined in the D-bank by SEG or RSEG directives is included in the program bank. SEG and RSEG directives for segments other than the main segment do not appear in any other bank.

7.6.3. Control Bank The control bank can be included in addition to the D-bank. Its only purpose is to contain the Collector-generated segment load table. If used, this bank is defined as the control bank (C option on DBANK Collector directive) and therefore has the highest BDI of all banks in the collection. If initialization segments are present, the Collector inserts a segment load table at the start of the main segment text of the control bank. This table displaces addresses assigned in the bank by an amount equal to the word length of the segment load table, which depends on the number of segments appearing in the collection. If a separate control bank is not used, the segment load table is located at the beginning of the main segment D-bank text, and all D-bank address assignments (including addresses in SEGs) are displaced accordingly. This situation prevents two high-volume program banks from correctly satisfying address references to a common data block in the D-bank work area if the program banks contain a different number of initialization segments in their respective collections. TPUR locates and processes the segment load table regardless of its containing bank. No restriction is made about absolute element granularity, although 64-word granularity, specified by the BLOCKSIZE64 Collector directive, is recommended to minimize wasted mass storage space. TPUR automatically converts to 64-word granularity for program loading.

7.7. Program D-Bank Initialization Main storage space used as a D-bank work area throughout the processing of a transaction (which may involve calls or transfers to several high-volume program banks) is allocated according to the address limits of the D-bank included in the initial control program when the initial control program is scheduled for execution. No text is loaded from the program library to the D-bank work area. Each program bank must initialize the D-bank work area that it requires during its execution. Therefore, each program bank must contain information in some form that enables it to initialize its D-bank.

7–16

7830 7402–014

HVTIP Programs

To accomplish D-bank initialization at execution time, a segment loader routine for high-volume program banks produced by TPUR uses the Collector to segment the D-bank text. All the information necessary to initialize D-bank space can be contained in initialization segments. The use of initialization segments is optional. TPUR processes an absolute element containing no initialization segments. However, an element compiled and collected without initialization segments must have an alternate method for D-bank initialization, such as generating code inline before program execution.

7.7.1. Initialization Segments Initialization segments are defined in a collection by the SEG and RSEG Collector directives, which appear in the D-bank. If one or more SEGs or RSEGs appear in the absolute element to be copied (COPY) to the library, TPUR combines the I-bank text and all initialization segments into a single I-bank entity and loads it to main storage as a unit. TPUR determines the address of each segment relative to the first I-bank address and stores it in a modified segment load table, also in the I-bank. Each initialization segment is transferred in its entirety, including load control groups, segment text, and in the case of RSEGS, a bit stream containing relocation information. Whether D-bank text is included in a SEG or RSEG depends on how the D-bank text is used in the application.

7.7.2. Using SEG The D-bank destination of data words included in a SEG is determined at collection time. This D-bank address depends on the segmentation structure of the D-bank as well as the initial address of the D-bank. During bank execution, the initialization segment loader routine transfers data words from the SEG included in the I-bank to the D-bank work area, according to the load control information contained in the SEG starting at the D-bank address specified by the Collector. A SEG is used to initialize portions of the D-bank work area that are used as a common data block by several program banks. Although SEGs may be included in and loaded by any program bank, Unisys recommends that they appear only in the initial control program. The size and address limits of the D-bank depend solely on the data area defined in the VALTAB or in the ICP element itself—for example, under location counter $(0). These elements are not redefined when HVTIP subprograms are called. Nothing forces the SEGs in subprograms to match the limits of the D-bank. Subprograms are, therefore, not aware of the ICP or its VALTAB, yet any SEGs defined in these subprograms must be loaded correctly into the D-bank if the program is to execute without error. This means that the SEG text is guaranteed to fit into the D-bank without guard-mode violation only at load time.

7830 7402–014

7–17

HVTIP Programs

7.7.3. Using RSEG The D-bank destination of data words included in an RSEG is determined during the execution of the program bank. The program bank allocates space in the D-bank work area and calls the initialization segment loader routine to initialize the allocated D-bank space using an RSEG. The initialization segment loader routine transfers words from the RSEG text to the D-bank (starting at the address specified by the calling program) according to the load control information contained in the RSEG.

7.7.4. Loading Initialization Segment (RSEGLOAD) Each program bank contains one or more initialization segments, each describing the initial state of a D-bank area. Before executing, the program bank calls the initialization segment loader routine (RSEGLOAD), passing the address of the segment load table entry for the segment to be loaded. If the segment is an RSEG, the D-bank address at which to begin loading RSEG text is ascertained and passed to RSEGLOAD. RSEGLOAD uses the SLT entry to find the load control information contained in the segment in the program bank. The text words of the segment transfer to their proper relative locations in the transaction D-bank. Void areas in the D-bank are not zero-filled. Thus, any words of zero must be explicitly defined in the segment text. Next, if the segment is an RSEG, the half-words selected in the relocation bit stream are relocated. The calling sequence is as follows: L L LMJ

X10, SLT-entry-address A0, D-bank-address (for RSEGs only) X11, RSEGLOAD

The initialization segment loader routine RSEGLOAD is collected along with the I-bank text, or exists independently in a common bank. This routine is available at collection time in the TIP primitive library file. The ASCII COBOL compiler automatically generates the correct calling sequence to the RSEGLOAD routine to accomplish D-bank initialization using RSEGS for high-volume TIP programs. Common data block loading for ASCII FORTRAN high-volume TIP programs is accomplished using an explicit call to the ASCII FORTRAN library subroutine SEGLD$. SEGLD$ calls RSEGLOAD to load common data blocks contained in SEGs.

7–18

7830 7402–014

Section 8 Programming Requirements This section describes the following: •

Design-dependent programming requirements

•

Language-dependent programming requirements

•

Security-dependent programming requirements

•

Requirements for execution-time features

8.1. Design-Dependent Requirements This subsection describes general design-dependent requirements for transaction programs and the specific requirements for each programming language.

8.1.1.

TIP Definition Parameters The TIP library file named TIPLIB$ and the SYS$LIB$*PROC$ file both contain elements defining system parameters for your transaction program. Some of these parameters are static, such as file control superstructure (FCSS) function codes or the system KONS area definition; while others, such as the sizes of tables, are configuration dependent. Always use the parameter label rather than a literal equivalent. Using the label decreases the chance of error if the system value of the parameters is changed and the program is recompiled without being recoded. To satisfy program references to the parameters defined in the appropriate element, reference the specific definition procedure, but not the element that contains it. If the program is in ASCII COBOL or ASCII FORTRAN, reference the ASYSDF procedure. If the program is in a Universal Compiling System (UCS) language, reference the USYSDF procedure. If the program is in Meta-Assembler (MASM), reference the SYSDEF procedure. Before compiling the program, assign TIPLIB$ or whatever file your site uses for those elements.

7830 7402–014

8–1

Programming Requirements

8.1.2. COBOL Definition Procedures For an ASCII COBOL program, assign TIPLIB$ and copy the procedures to the Data Division: @ASG,A TIP$*TIPLIB$. @USE COB$PF.,TIP$*TIPLIB$. . . . @ACOB,I file.symb-prog-elt,file.rel-prop-elt . . . COPY ASYSDF. COPY ACMPDF. * For ASCII COBOL level 3R2 or higher, or COPY SYSDEF. COPY CMPDEF. * For COBOL level 3R1 or lower. For extended mode programs, assign TIPLIB$ and copy the “u” procedures to the Data Division: @UCOB file.prog-elt,file.obj . . COPY USYSDF. COPY UCMPDF.

8.1.3. FORTRAN Definition Procedures For an ASCII FORTRAN program, assign TIPLIB$ before compilation and reference the procedures at collection time: @ASG,A TIP$*TIPLIB$. @USE FOR$PF.,TIP$*TIPLIB$. . . @FTN,SIM file.symb-prog-elt,file.rel-prog-elt . . INCLUDE ASYSDF . For ASCII FORTRAN INCLUDE CMPDEF . Optionally, for COMPOOL record definition For extended mode FORTRAN programs, assign TIPLIB$ before compilation and re ference the procedure at linking time. @UFTN file.prog-elt,file.obj-mod . . INCLUDE USYSDF INCLUDE UCMPDF

8–2

7830 7402–014

Programming Requirements

8.1.4. MASM Definition Procedures For a MASM program, assign TIPLIB$ before compilation and reference the definition procedures at collection time: @ASG,A TIP$*TIPLIB$. @USE ASM$PF.,TIP$*TIPLIB$. . . . @MASM,IS file.symb-prog-elt,rel-prog.elt . . . SYSDEF CMPDEF (optional)

8.1.5. Collecting Your Program See Section 8.1.10 for information on linking in extended mode. References to the TIP primitive library, TIP$*TIPLIB$, are common to all TIP transaction program collections. Both the program bank calling a primitive and the bank that the primitive is in must be based at the time of the call. They cannot overlap each other. (The same is true of any bank containing buffers to which the primitive refers, if different from the calling bank.) This constraint exists because all returns from the primitives are done by a direct Jump instruction. The Collector directive “LIB TIPLIB$” causes the primitives to map to the control bank. The easiest way to ensure that the constraint is met is to place the calling program in the control bank. The primitives must not be mapped to a void bank. References to alternate file common banks (AFCB) are made using bank basing instructions or initial basing specifications and are supported in TIP and HVTIP program environments. AFCB templates cannot be collected into absolute elements loaded from TIP files, because of the special format of these absolutes. AFCB templates reside in absolute elements in program files for processing. Nonconfigured common banks (NCCB) and references to NCCBs are not supported in TIP and HVTIP program environments. For HVTIP programs (type 5), see also Section 7. A maximum of 262K segments is allowed. Online-batch programs (type 4) and normal runstream batch-connected programs are collected like type 1 and type 2 programs (self-initializing and self-destructive) except for ASCII COBOL routines. If your transaction program is in ASCII COBOL, see the ASCII COBOL Programming Reference Manual for additional information.

7830 7402–014

8–3

Programming Requirements

8.1.6. Self-Initializing Transaction Programs Self-initializing transaction programs set their D-banks at the starting position at execution time. This lets such features as restart, sticking power, and block transfer loading be implemented. This program type is preferable to the self-destructive program type for performance reasons.

8.1.7. Reentrant Transaction Programs The reentrant program type is a special case of self-initializing programs. One of the program’s banks is the reentrant I-bank. This reentrant bank is never modified during execution. One copy of the reentrant I-bank can, therefore, be shared with several concurrent program copies. For absolutes, a reentrant program has only one I-bank and one D-bank that is not voided. One or more void banks can be included in the collection of a reentrant program for a common bank to be invoked during execution. If a reentrant program has a low probability of initial load of the reentrant I-bank, it is likely that two or more copies will be used concurrently. There is an advantage to having the program classified as reentrant. The reentrant I-bank remains in storage for an extended period of time. Since a reentrant I-bank cannot be swapped or moved, storage allocation of the bank occurs at a higher priority than that of all other non-real-time user program banks. To avoid swapping other programs for the reentrant I-bank, classify the bank as a self-initializing transaction program. Coding changes are not required to change a reentrant program to a self-initializing program.

8.1.8. Mapping Reentrant Programs Reentrant transactions require a bank-named collection. The I-bank is designated as the control bank. The program does not modify its I-bank, which is marked as read-only. Any attempt to change I-bank code results in a guard-mode interrupt. A reentrant program has only two program banks, an I-bank and a D-bank (both initially based). Configured common banks and AFCBs are referenced by using bank basing instructions (LIJ, LDJ, or LBS) or by specifying them as initially based. One or more void banks can be included in the collection. In Example 8–1 and Example 8–2, IB is the name of a user-defined I-bank and DB is the name of a user-defined D-bank. @MAP,IS ABSFILE.PROG IBANK,CMR IB IN RELFILE.PROG LIB (IB/$ODD,DB/$EVEN) LIB TIPLIB$() DBANK,M DB IN RELFILE.PROG END Example 8–1. Mapping a Reentrant Program

8–4

7830 7402–014

Programming Requirements

ASCII COBOL TIP programs can use library elements modified to interface with TIP in place of the standard library elements. To use these elements, include them in the collection and specifically exclude the standard elements with the collector directive NOT. Example 8–2 assumes that SYS$LIB$*ACOB contains the ASCII COBOL library, SYS$LIB$-TIPLIB contains the ASCII COBOL TIP library, and TIP$*TIPLIB$ contains the TIP program library. @MAP,IS IBANK,CMR IN LIB LIB LIB DBANK,M IN IN IN NOT NOT NOT NOT . . . END

AB$FILE.PROG IB . SEE NOTE RELFILE.PROG (IB/$ODD,DB/$EVEN) SYS$LIB$*ACOB-TIPLIB(),SYS$LIB$*ACOB() SYS$LIB$*ACOB-TIPLIB(),TIP$*TIPLIB$() DB RELFILE.PROG MEM$ERR SYS$LIB$*ACOB-TIPLIB.C$S400/TIP SYS$LIB$*ACOB.C$S200,.C$S205,.C$S210,.C$S230 SYS$LIB$*ACOB.C$S240,.C$S250,.C$S260,.C$S400 SYS$LIB$ACOB-TIPLIB.C$D8BT,.C$RETO,.C$S30S SYS$LIB$*ACOB-TIPLIB.C$S310,.C$S390,.C$S395

Example 8–2. Mapping a Reentrant COBOL Program The following are additional restrictions for reentrant programs: •

Program segmentation is not allowed.

•

Void banks can be included in the collection (V option on I-bank or D-bank directives), but cannot be initially based and cannot be based during execution through the LIJ/LDJ/LBJ instructions.

•

You must use a bank-named collection and place a C option on the IBANK directive to make the I-bank the control bank. If the I-bank is not the control bank, the program is loaded, but the bank descriptor indexes (BDIs) of the I-bank and the D-bank may be reversed. Any reference to the BDIs would then cause a system or program error. The previous examples show the C option for both MASM and COBOL programs.

•

The reentrant bank must be write-protected.

7830 7402–014

8–5

Programming Requirements

8.1.9. Mapping Self-Initializing and Self-Destructive Programs For a self-destructive program (type 1) or a self-initializing program (type 2), a simple bank-implied collection is sufficient, as in the following example: @MAP,IS ABSFILE.PROG IN RELFILE.PROG LIB TIPLIB$. END ASCII COBOL TIP programs can use library elements modified to interface with TIP in place of the standard library elements. To use these elements, include them in the collection and specifically exclude the standard elements with the collector directive NOT. Example 8–3 assumes that SYS$LIB$*ACOB contains the ASCII COBOL library, SYS$LIB$-TIPLIB contains the ASCII COBOL TIP library, and TIP$*TIPLIB$ contains the TIP program library. @MAP,IS IN IN LIB LIB NOT NOT NOT NOT . . . END

AB$FILE.PROG RELFILE.PROG SYS$LIB$*ACOB-TIPLIB.C$S400/TIP SYS$LIB$*ACOB-TIPLIB,SYS$LIB$*ACOB SYS$LIB$*ACOB-TIPLIB,TIP$*TIPLIB$ SYS$LIB$*ACOB.C$S200,.C$S205,.C$S210,.C$S230 SYS$LIB$*ACOB.C$S240,.C$S250,.C$S260,.C$S400 SYS$LIB$*ACOB-TIPLIB.C$D8BT,.C$RETO,.C$S30S SYS$LIB$*ACOB-TIPLIB.C$S310,.C$S390,.C$S395

Example 8–3. Collecting an ASCII COBOL Self-Initializing or Self-Destructive Program More sophisticated collections for self-destructive and self-initializing programs include features such as multibanked programs, dynamic banks, and segmented programs.

8.1.10. Compiling and Linking in Extended Mode Other than the compiler used, there are no differences between the procedures for UCS FORTRAN, UCS COBOL, UCS C, and UCS Ada.

Compiling In extended mode, the program is compiled with a UCS compiler to produce an object module. It is necessary to use static linking to turn the object module into a zero overhead object module (ZOOM). The object modules produced by the UCS compilers are in a standard form, so object modules from different languages can be linked into one program.

8–6

7830 7402–014

Programming Requirements

Linking Following is a sample runstream for using the static linker to produce a ZOOM (output*file.ZOOM) from a compiled object module (input*file.object-module) for a standard TIP program: @LINK ,output*file.ZOOM INCLUDE input*file.object-module RESOLVE ALL REFERENCES USING SYS$LIB$*EMOMRTS.,LCN PROCESS FOR EXTENDED ZOOM DELETE ALL DEFINITIONS EXCEPT START$ @EOF For HVTIP examples and detailed instructions on using UCS compilers and the Linking System, see the UCS Application Development Programming Guide and the Linking System Programming Reference Manual.

8.1.11. Standard-Load and Fast-Load ZOOMs The following restrictions apply to both standard-load and fast-load ZOOMs: •

You cannot run multiactivity ZOOMs as TIP transactions if they contain any activity-level banks.

•

Banks must not have contiguous BDIs.

Standard-load ZOOMs also have a limit of 4092 program-level banks and 4086 activitylevel banks. Fast-load ZOOMs have the following additional restrictions: •

There is a limit of four user banks, including both void and nonvoid banks, but not Exec allocated banks. Program-level and I/O activity-level banks are reserved for system use.

•

The program must not contain any program banks with more than one access control word (ACW).

•

The total size of all user banks cannot exceed 262K.

7830 7402–014

8–7

Programming Requirements

8.2. Language-Dependent Requirements This subsection describes the restrictions and considerations for each programming language supported in the TIP environment.

8.2.1. FORTRAN Considerations The following considerations apply to transaction programs written in FORTRAN.

ASCII FORTRAN Restrictions For ASCII FORTRAN programs, these restrictions apply: •

ASCII FORTRAN uses the COMPILER statement to provide options to the compiler that are intrinsic to the program. This statement directs the ASCII FORTRAN compiler to place a BDI in the parameter list for each subprogram call (subroutine) or reference (function). For example: COMPILER (BANKED=ACTARG) The items used as parameters must be named in a BANK statement or in a named COMMON that is in a BANK statement. Otherwise, the BDI for the control bank (BDI$) is used in the parameter list; this is not allowed in ASCII FORTRAN.

•

You cannot use the O option to compile an ASCII FORTRAN program. With this option, addresses in the argument list could reach 262,000 (0777560), which infringes on the indirect bit and index bits (h,i). With indirect addressing to pick up the proper address, these addresses in the argument list cannot exceed 16 bits or 65K.

•

The program cannot pass labels as parameters to a TIP primitive in a call; passing labels usually passes a BDI in the parameter list. For the same reason, the program cannot pass routine names.

•

The program cannot pass character parameters under the ASCII FORTRAN level 9R1 compiler. This causes the number of character parameters being passed to be placed in S1 of A0. The single-word descriptors for each character parameter follow the BDI/ADDR words and contain a length in characters and a character offset for each character parameter. A word or more of types follows all these character descriptor words if character items are used, or BDI/ADDR words if no character items are passed. The character items cannot be on word boundaries, and the length and offset must be used when the character items are picked up. Following is the format of the A0: A0

8–8

Number of character items

Number of parameters

Address of parameter list

7830 7402–014

Programming Requirements

Figure 8–1 shows the format of the parameter list. BDI/Address words A - BDI/Address words Offset

Character length

Not used

B - Character descriptor words Param 1 type Param 2 type

Param 3 type

Param 4 type Param 5 type Param 6 type

(A+5)/6 Type words

Figure 8–1. FORTRAN Parameter List •

If the K program status (STATUS parameter) option is set in the VALTAB entry, the program can do block transfer loading. Do not use block transfer loading with a reentrant ASCII FORTRAN program. The program uses test-and-set instructions to be reentrant, and these instructions are not compatible with the TIP block transfer loading environment.

Implicit Label Typing The following statement directs the compiler to type all variable labels, parameter labels, and so on as integers: IMPLICIT INTEGER (A-Z) This means that fixed-point instructions, as opposed to floating-point instructions, are generated. Because in transaction processing, most label references are to data fields in a record, you should normally avoid typing any variables as real. Floating-point variables are established explicitly by using the REAL directive. Implicit label typing is required if the TIP procedure elements are referenced. The following is the ASCII FORTRAN calling sequence for implicit label typing: IMPLICIT INTEGER (A-Z) INCLUDE ASYSDF DIMENSION PARAM1 (20) PARAM2 = X PARAM3 = Y PARAM4 = Z CALL PRIMITIVE (PARAM1, PARAM2, PARAM3, PARAM4)

8.2.2. COBOL Considerations The following considerations apply to transaction programs written in COBOL.

Extended Mode Primitive Compatibility To preserve compatibility for existing TIP programs, the UCS COBOL primitives can be called with their ASCII COBOL names.

7830 7402–014

8–9

Programming Requirements

Subroutine Parameters Since the parameters used in a COBOL call are aligned on word boundaries, they are specified as level 01 or level 77 data items. Parameters used to pass numerical data are computational. Here is an example: 77 COMPOOL-LENGTH PIC 9(10) USAGE COMP. 77 USER-CRT PIC 9(10) VALUE IS 11. 016 COMPOOL-BUFFER COPY ACMPDF. 02 SCREEN-IMAGE PIC X(4) OCCURS 240 TIMES.

ASCII COBOL UDS/TIP Program ASCII COBOL does not accommodate address handling. Some TIP calls need data or instruction addresses passed to the primitive in a parameter. The TIP ASCII primitive library provides a routine, CLOCTE, that places the address of the first parameter in the lower half of the second. Example 8-4 shows how to use TIP primitives in an ASCII COBOL UDS/TIP program. DATA DIVISION. WORKING-STORAGE SECTION. 77 ADDRESS-ARG PIC 9(10) COMP. 01 INIT-ARG-2. 02 ESCAPE-ADDRESS PIC 9(5) COMP. 02 MESSAGE-LENGTH PIC 9(5) COMP VALUE IS 72. 01 CMPBUF PIC X(288). . . . PROCEDURE DIVISION. START-TXN. IMPART. OPEN ALL. GET-MESSAGE. CALL ’CINIT’ USING CMPBUF, INIT-ARG-2. CALL ’CRELOG’. . * * D-BANK INITIALIZED * . * * INPUT MESSAGE PROCESSED * . * * RECORD LOCKS FREED, ETC. * .

8–10

7830 7402–014

Programming Requirements

SEND-REPLY. . ESCAPE. CLOSE ALL. DEPART. CALL ’CTRMN8’ USING DUMMY. Example 8–4. ASCII COBOL UDS/TIP program

8.2.3. Partial Word Fields Example 8–5 shows how to declare partial word fields. WORKING-STORAGE SECTION. 01 FULL-WORD. 02 W PIC S9(10) COMP. 01 HALF-WORD. 02 H1 PIC S9(5) COMP. 02 H2 PIC S9(5) COMP. 01 THIRD-WORD. 02 T1 PIC S1(12). 02 T2 PIC S1(12). 02 T3 PIC S1(12). 01 SIXTH-WORD. 02 S1 PIC S1(6). 02 S2 PIC S1(6). 02 S3 PIC S1(6). 02 S4 PIC S1(6). 02 S5 PIC S1(6). 02 S6 PIC S1(6). 01 QUARTER-WORD. 02 Q1 PIC S9(2) COMP. 02 Q2 PIC S9(2) COMP. 02 Q3 PIC S9(2) COMP. 02 Q4 PIC S9(2) COMP. Example 8–5. Partial Word Fields Word definitions begin on word boundaries, and all partial words must be properly defined even if they are not used. A FORTRAN subroutine (FIELD), described in Appendix C, is provided to let COBOL programs access one or more bits of a word. The following Fieldata COBOL program sample selects bits 17 through 20 from the FIELD-A and stores them in the FIELD-B: DATA DIVISION. 77 FIELD-A PICTURE IS X(6). 77 FIELD-B PICTURE IS X(6). 77 BITNUMBER PICTURE IS 9(10).

7830 7402–014

8–11

Programming Requirements

77 NUMBERBIT PICTURE IS 9(10). PROCEDURE DIVISION. . . . MOVE 20 TO BITNUMBER. MOVE 4 TO NUMBERBIT. * * ENTER FORTRAN FIELD SUBROUTINE REFERENCING * BITNUMBER, NUMBERBIT, FIELD-A, FIELD-B. * When control is returned, FIELD-B contains bits 17 through 20 of FIELD-A in bits 0 through 3.

8.2.4. Calling Sequences Following is the Fieldata COBOL calling sequence: WORKING-STORAGE SECTION. 77 ARG1 PICTURE IS X(120). 01 ARG2 PICTURE IS 9(10) VALUE IS X. 01 ARG3 PICTURE IS 9(10) VALUE IS Y. 01 ARG4 PICTURE IS 9(10) VALUE IS Z. 01 BUFFER COPY SYSDEF. PROCEDURE DIVISION. * * ENTER FORTRAN PRIMITIVE SUBROUTINE REFERENCING * ARG1, ARG2, ARG3, ARG4. * . . . Following is the general ASCII COBOL calling sequence: WORKING-STORAGE SECTION. 77 ARG1 PIC X(80). 01 ARG2 PIC 9(10); USAGE COMP; VALUE IS X. 01 ARG3 PIC 9(10); USAGE COMP; VALUE IS Y. 01 ARG4 PIC 9(10); USAGE COMP; VALUE IS Z. 01 BUFFER COPY ASYSDF. PROCEDURE DIVISION. CALL PRIMITIVE USING ARG1, ARG2, ARG3, ARG4. . . .

8–12

7830 7402–014

Programming Requirements

8.2.5. MASM Considerations The following considerations apply to transaction programs written in MASM.

TIP Primitive Requests When you use a TIP primitive in your program, you make a request in this format: CALL primitive parameter1, . . .parametern The number and nature of the parameters, if any, depend on the primitive. The name of the primitive and the exact format of the request depend on the language of the program. The primitive is actually a CALL subroutine element that generates a MASM version of your request for the Exec. The MASM sequence specifies a storage address for each parameter in your request. If your request contains a primitive from the ASCII or HVTIP set, the CALL subroutine element generates the following MASM sequence: LXM,U A0,list-address LXI,U A0,n LMJ X11,primitive J $+n+1 .jump around parameters + parameter1-address + parameter2-address . . . + parametern-address In this sequence of MASM commands, list-address is the address of the parameter list, and n is the number of parameters in the list (that is, specified in your request). If the request does not require parameters, the generated MASM sequence begins as follows: L,U A0,0 LMJ X11,primitive . . . If you want to generate the parameter list under a different location counter, you can specify the counter as a subfield of the CALL field. In the MASM sequence, the LMJ instruction is followed immediately by the parameter addresses, with no separate jump (J) instruction. This type of request has the parameter list generated under location counter 2: CALL,2 primitive parameter1,...parametern Example primitive calls are included in the description of each primitive, including the number of parameters.

7830 7402–014

8–13

Programming Requirements

Parameter Addressing The primitives use indirect addressing to reference the parameters. Therefore, by using an index register, the MASM language programmer can generate a calling sequence in which the parameters are not in fixed locations. For example, you could use the declaration: CMPBUF EQUF 0,X7 instead of the declaration: CMPBUF RES 100

8.2.6. Register Use The primitives restrict themselves to the minor register set, as follows: •

X8 to X11

•

A0 to A5

•

R1 to R3

Be aware that any registers in the minor register set may be destroyed by a primitive CALL.

8.2.7. Illegal Executive Requests Several ERs may not be requested by a transaction program. The program results in error termination with a type 4, code xx, contingency type 012. Symbiont ERs All symbiont ERs are illegal, except the following: •

PRINT$

•

APRINT$

•

PRTCN$

•

APRTCN$

•

SYMB$ (W$ and SM$ for PRINT$)

CSF$ Control Statements The following CSF$ control statements are illegal:

8–14

•

@ADD

•

@CKPAR

•

@BRKPT

•

@CKPT

•

@RSPAR

•

@RSTRT

7830 7402–014

Programming Requirements

An @SYM statement is allowed through CSF$ control statements of PRINT$ files and of user files. An @SYM of PRINT$ is allowed only after a PRINT$ file has been created by an ER. Only one PRINT$ file per transaction is possible, since BRKPT PRINT$ is not available through CSF$. Multiple @SYM statements for a transaction program are possible, with the last @SYM statement being effective. Transaction programs can use @SYM to specify a print banner other than the default banner, which is transaction code for HVTIP and program name for standard TIP.

8.2.8. CSF$ @START for TIP Transactions @START control statements from TIP transaction programs using CSF$ are allowed, with the following restrictions. If required by the system, the account number and the user-id parameter must be specified on the @START image, or the CSF$ request is rejected. The account number is required only if the system parameter (ACCTON) is configured. The user-id parameter is required only if user-ids are configured (USERON or TSS_CONTROL). The default symbiont device is used for the print file of the started run addstream. The security attributes of the started run and any subsequent started runs are the same as those of the TIP transaction that issued the initial @START request. The format of the @START image is the same as that used by batch and demand programs. For example: @START file.elt,,,123/userid The runstream in file.elt is started; the account number is 123.

8.2.9. Quarter-Word Mode MASM transaction programs that interface with an ASCII database or ASCII screen images must run in quarter-word mode. You must set the designator bit D10 in the program’s designator register. For example: SPD A0 OR,U A0,010 LPD 0,A1 This sequence sets only bit D10; the others are unchanged. The character string literals generated by the assembler can be in ASCII. The procedure call $ASCII causes subsequent character strings to be generated in ASCII.

7830 7402–014

8–15

Programming Requirements

8.3. Security-Dependent Requirements This subsection tells you how to create transaction programs that work efficiently while maintaining system security. The points made here are relevant if you are developing transaction programs that run on OS 2200 systems with TIP Session Control, TIP File Security, and TIP Message Security configured.

Note: TIP Session Control is not available for systems on which the highest application group number configured is greater than 16. TIP Session Control allows the operating system to identify and validate TIP end users. TIP users engage in sign-on dialog that establishes the user-id, privilege set, project-id, account-id, clearance level (Security Option 1 or higher), and compartment set (Security Option 2 or higher) for the TIP session. From the end user’s viewpoint, every transaction program runs with the security attributes established for the TIP session. A transaction’s security attributes determine the set of protected objects it can access (cataloged files, TIP files, and so forth). A transaction program obtains its security attributes from the particular input message it is processing. The same transaction program can behave differently with regard to security, depending on the security attributes of the TIP session executing that program. A transaction program’s operating characteristics are defined in its transaction program validation table record. The VALTAB record relates a transaction code to a specific transaction program and tells TIP how to handle the loading and execution of the program. The program type (PRGTYP) and program status (STATUS) fields in the VALTAB area, and the TIP flagbox settings (set via FB keyins), are of particular interest because they control the multiple-input features. The following paragraphs describe various TIP attributes that affect security, and cautions to be observed accordingly: •

TIP program types (8.3.1)

•

Multiple-input-transactions (8.3.2)

•

High-Volume TIP (HVTIP) (8.3.3)

•

Special Security Option 3 environment considerations (8.3.4)

8.3.1. TIP Program Type Every transaction program is one of the following types:

8–16

•

Online batch

•

Self-destructive

•

Self-initializing

•

Reentrant

•

HVTIP

7830 7402–014

Programming Requirements

Online batch programs are single-input. They are not allowed to read multiple-inputs and are never reused once they terminate. Single-input transaction programs usually do not perform as well as multiple-input programs, but they typically require no special considerations for security. The other program types support multiple-input programs, but multiple-input messages are not allowed in the Security Option 3 Controlled Access Protection Environment or the Security Option 3 Trusted Environment (see Subsection 8.3.4.). Subsection 8.3.2 describes security considerations for multiple-input programs in other environments.

8.3.2. Multiple-Input Transactions To obtain the best performance, transaction programs can be designed so that one program processes many input messages. A multiple-input transaction eliminates the overhead needed to reload the program for each input message it processes. Table 8–1 describes features of TIP that help support multiple-input transactions. If a transaction program’s VALTAB record designates it as a multiple-input transaction, then it must be designed to process input messages from many different TIP sessions in its lifetime. From the program’s point of view, its security record can change with every new input message read; therefore, the program must be designed so that it cannot accidentally compromise any secured information. The subsections following Table 8–1 describe some situations that a multiple-input transaction can encounter and suggest ways to avoid security problems in each situation. Table 8–1. TIP Features That Support Multiple-Input Transactions Feature

Description

Comments

Multiple INITIAL

This feature allows a transaction program to read and process an unlimited number of input messages in a single execution.

Self-destructive and online batch programs are never allowed to perform multiple INITAL.

Program restart

This feature automatically restarts a terminating transaction program if an input message is waiting for it.

Program restart is disabled if RESIDUE_ CLEAR is configured and the sticking flagbox option is turned off.

Program sticking

This feature automatically retains a terminating transaction program in main storage until another input message arrives. When the new input arrives, the program is restarted. The program status field controls sticking capabilities for multiple-input programs.

If the status option STA = I is enabled, and the sticking flagbox option is turned on, the transaction becomes a candidate for sticking.

7830 7402–014

8–17

Programming Requirements

Table 8–1. TIP Features That Support Multiple-Input Transactions Feature

Description

Block transfer loading

This feature allows a new transaction program to be loaded by copying the contents of an existing program already in main storage. The program status field controls block transfer loading capabilities for multiple-input programs.

Comments

If the status option STA = K is enabled, and the BTLOADING flagbox option is turned on, the transaction becomes a candidate for block transfer loading.

Resident Transaction Program System (RTPS) Program An RTPS program is a special case of a multiple-input program. It is loaded only once into memory—as specified in the VALTAB entry for the transaction. An RTPS program must reside in a system-low TIP file. Until the program processes its first message, its attributes are system-low. It is not associated with any user until it receives an input message.

Residual Cataloged File Assignments Transaction programs can assign cataloged files and read or write information to them by using one of the Executive requests in the IOW$ family. In a secure system, cataloged files are protected from unauthorized access. A transaction program can assign a file successfully only if the security record of the user currently in control of the program allows it. In a multiple INITAL transaction, a program can assign a cataloged file while under control of the first user, because the first user’s security record allows it. If that program comes under control of a different user through multiple INITAL, the cataloged file remains accessible to the next user. This would happen even if the next user would not have otherwise gained access to the file. There are several ways to avoid this situation. First, if the transaction is designed not to use cataloged files, the concern disappears. When the application relies on TIP files exclusively, TIP File Security automatically handles the multiple INITAL case. Next, the transaction could be designed to explicitly free cataloged files before requesting another input message and before termination.

8–18

7830 7402–014

Programming Requirements

Print File Residue Most transaction programs communicate their results back to the end user’s terminal by using output messages. A transaction program can send output to a printer by issuing a PRINT$ type request. The security label of a transaction program’s PRINT$ file is established when it performs its first PRINT$ type request. The security label reflects the security record of the user in control of the program when the first request is made. The system ensures that the print file’s security label appears on the printed output. Once a transaction PRINT$ file is established, it remains accessible to the program even if the program comes under control of a different end user who might not otherwise have obtained write access to the file. In this way, it is possible for a multiple INITAL program to declassify information through its PRINT$ file. If your site is a Security Option 3 Trusted Environment, you must have the approval of the security officer to design multiple INITAL programs that issue PRINT$ requests.

D-Bank Residue Most transaction programs have at least one D-bank used for storing and manipulating data. Data enters a D-bank through read operations. Sources of data include TIP files, cataloged files, input messages, and so forth. The security system protects the information in these containers from unauthorized access. In the case of transaction program read operations, the security record of the user in control of the program determines if read access is allowed. If the security record of a multiple-input transaction changes, its D-banks might contain residual data obtained while a previous user was in control. The current user might not be qualified for read access to the original data container. If the transaction program is not designed correctly, the residual data could be declassified. A multiple-input transaction program should be designed to protect residual data in its D-banks. It should avoid writing residual data to any file or sending an output or pass-off message that contains residue. A technique that always works is to clean up residue before reading another input and before termination.

General Register Set (GRS) Residue A multiple-input transaction program should be designed to protect residual data in GRS. If a program loads security-relevant data into GRS, that residue data should be cleaned up before reading another input and before termination.

Activity-Local Stack (ALS) Bank Residue Extended mode multiple-input programs can reuse ALS space. Because of the difficulty in clearing residue from the ALS space, programs should avoid using multiple-input programs in extended mode.

7830 7402–014

8–19

Programming Requirements

Reentrant I-Bank Residue TIP loads a reentrant transaction program in a special way. When several copies of a reentrant program are in main storage at the same time, the system arranges all copies to share one reentrant I-bank between them. When a new program copy is loaded, the system loads its D-bank only. The new copy is added to the set of program copies sharing the reentrant I-bank. The security records of the reentrant program copies normally are different, since each copy is processing a different input message. The data accessible to each copy is also different, since the availability of data is controlled by the security record. If the program stores data in the reentrant I-bank, that data is visible to all program copies. That can cause protected data to be declassified. A program that writes to its I-bank violates the principle of reentrance. TIP enforces write protection of the I-bank of a reentrant TIP ZOOM program and a reentrant absolute program if RESIDUE_CLEAR is configured. Reentrant programs should be designed so that they never alter their I-bank. Data manipulation should be carried out only in the D-bank. The easiest way to ensure that a transaction program satisfies the reentrant requirement is to collect the absolute element so that the I-bank is write protected. This can be accomplished by using the R option on the IBANK collector directive.

8.3.3. HVTIP Each HVTIP program is given a unique memory domain number. All I-banks and D-banks for that HVTIP program are allocated from absolute space under that domain. Up to 64 HVTIP libraries can be configured (1 through 64) with the HVTIP configuration parameter. When TIP File Security is configured, calls to subprograms via HVTIP interfaces pass through TIP File Security access-verification logic to ensure that the requested access is allowed. Program errors can occur in the following cases: •

If the caller does not have execute access privilege to the target HVTIP library

•

If a reference is made to an HVTIP subprogram, and the HVTIP library containing that subprogram is in the process of being bundled in a TIP File Security bundle with files of identical security characteristics

In either case, the access validation is not allowed to continue, and the following message appears: TIP File Security error. Caller is refused access to the target library. Check auxiliary status for more information.

8.3.4. Special Security Option 3 Environment Considerations The following paragraphs briefly describe supported TIP program types and unsupported TIP features in a Security Option 3 Controlled Access Protection Environment or a Security Option 3 Trusted Environment. For detailed information, refer to the Security Administration for ClearPath OS 2200 Help.

8–20

7830 7402–014

Programming Requirements

Supported TIP Program Types With either a Security Option 3 Controlled Access Protection Environment or a Security Option 3 Trusted Environment, all TIP program types are supported on 2200/XPA systems if transaction program reuse and multiple-input programs are prevented (see the Security Administration for ClearPath OS 2200 Help for details). When TIP is configured to prevent program reuse, each program is initially loaded into memory that is cleared to binary zeros. When the program finishes execution, it is completely deleted from the system. With the exception of messages processed using the multiple INITAL feature (see the caution in the next subsection), no reuse of the program to process another message is allowed—thus, there is no danger that data residue from a previous execution of a program copy can be read during a subsequent reuse of the program copy.

Note: When RESIDUE_CLEAR is configured, the transaction processing system always loads reentrant type programs with the I-bank write protected.

Unsupported TIP Features The following TIP features are not supported in either the Security Option 3 Controlled Access Protection Environment or the Security Option 3 Trusted Environment: •

The sticking and multiple INITAL multiple-input transaction features

•

Block transfer loading

•

Resident Transaction Program System (RTPS) programs

•

The COMPOOL message interface

Caution Although no program is allowed to read multiple-input messages in a Security Option 3 Controlled Access Protection Environment or a Security Option 3 Trusted Environment, that restriction is enforced by the system only for self-destructive and online batch programs. You must ensure that no self-initializing, reentrant, or HVTIP programs are coded to use the multiple INITAL feature.

8.4. Requirements for Execution-Time Features This subsection describes the use of the following TIP execution-time features: •

TPLOG primitive

•

Flagbox and logbox manipulation (FOXER and FLBOX primitives)

•

Execution option indicator primitives

7830 7402–014

8–21

Programming Requirements

8.4.1. TPLOG Primitive The TPLOG primitive is used to log information on the TPM audit tape. TPLOG is supported in both basic mode and extended mode. The TPLOG primitive request requires these parameters: 1.

S5: major code in bits 11-6: 2

User logging

3

File control superstructure (FCSS) logging

4

Termination statistics logging

S6: minor code in bits 5-0 2.

Address in the online program’s D-bank of the data to be logged

3.

Buffer length (number of words to be logged)

4. Location in which the status of the operation is returned to the online program Your site assigns the minor codes necessary for recovery or statistical purposes. Up to 64 minor codes can be assigned. To assign minor codes, logging type 2 (user logging) must be enabled. The maximum length of the data buffer is determined by the Transfer SGS. The logging errors are indicated by the following bits: 35

Error return indicator

27

No TPM buffers available to audit this request

24

Bad access word or request exceeds maximum size

23

Not collecting for batch and demand or L option not set

22

TPM is not turned on for this trail

Table 8-2 shows the basic formats for a TPLOG primitive request. Table 8–2. TPLOG Request Formats Language

8–22

Request Format

ASCII or UCS FORTRAN

CALL TPLOG (parameters)

UCS C

TPLOG (parameters);

ASCII COBOL

CALL 'CTPLOG' USING parameters.

UCS COBOL

CALL 'TPLOG' USING parameters.

MASM

CALL TPLOG parameters

7830 7402–014

Programming Requirements

For more information on the TIP Performance Monitor, see the Transaction Processing Administration and Operations Reference Manual.

8.4.2. Flagbox and Logbox Settings The FOXER and FLBOX primitives let an executing program display or manipulate flagbox or TPM settings. Console operators usually perform these actions by means of FB, LB, and LC keyins, which are described in the System Console Messages Reference Manual.

Displaying and Setting Bits—FOXER Primitive The FOXER primitive lets a TIP transaction or batch-connected program display or manipulate the flagbox or logbox at execution time. Flagbox bits control TIP system operation; bit settings determine whether certain features (many of which have been set originally in the VALTAB entry for the program) are allowed or inhibited. Logbox is a control cell that specifies types of system logging; bit settings determine what type of logging, if any, is to be performed during program execution. FOXER is supported only in basic mode. Table 8–3 shows the basic format for a FOXER primitive request that contains one or two parameters. The specific format depends on the action performed. Table 8–3. FOXER Request Formats Request Format

Language

ASCII FORTRAN

CALL FOXER (parameter1[,parameter2])

ASCII COBOL

CALL ’CFOXER’ USING parameter1[,parameter2].

MASM

CALL FOXER parameter1[,parameter2].

Table 8–4 lists specific FOXER primitive request formats (in MASM), along with their meanings. Table 8–4. Specific FOXER Formats Request Format

Description

CALL FOXER FB

Display current flagbox settings.

CALL FOXER LB

Display current logbox settings.

CALL FOXER bit-name,ON

Turn on flagbox or logbox bit bit-name.

CALL FOXER bit-name,OFF

Turn off flagbox or logbox bit bit-name.

CALL FOXER LC,ON

Turn on logging.

CALL FOXER LC,OFF

Turn off logging.

CALL FOXER LC,SWAP

Swap logging to an alternate tape drive.

7830 7402–014

8–23

Programming Requirements

The possible values for the flagbox bit-name parameter are shown in Table 8–5, which also indicates the flagbox bit numbers and the meanings of the bits when set. Table 8–5. Flagbox Bits Bit Number

8–24

Bit Name

Description

0

TIPTRACE

Allows SEXEM dumps of basic mode transaction programs that terminate in error or diagnostic dumps of extended mode transaction program activities that terminate in error.

1

SCHEDULE

Transaction program scheduling permitted.

3

RECOVERY

System in recovery.

6

BTLOADING

Block transfer loading allowed.

7

TIPLOG

TIP system logging on.

8

TRAINFB

Training system disabled.

9

MESSAGES

Batch-id messages of all online batch transaction programs scheduled by TIP are sent to the system console.

14

STICKING

Program sticking power enabled.

15

NOCMPINIT

Core COMPOOL initialization disabled.

17

SDEADLOCK

Collection of shared (XPC–L) FCSS deadlock debugging information enabled.

18

MAXTIMEDP

Dynamic EXEC online dump generation of maximum wall clock time aborts enabled.

19

MAXTIMENQ

Immediate abort of transactions exceeding their maximum wall clock time enabled.

20

INHIBSTF

Loading from standard online program files inhibited.

21

CSUPPRESS

Suppression of repeated TIP transaction error console messages enabled.

22

DEBUGXX

Allows an unlimited number of dumps for a repeating transaction program that terminates in error. It prevents the scheduling of previous TIMER entries, and any updates or deletions of or to entries; new TIMER requests are scheduled immediately.

23

CKCKONSCH

CKCKON utility scheduled for execution every 30 seconds.

24

OP$MAIN

Loading from MAIN cycle of SUPUR program files enabled.

25

OP$ALT

Loading from ALTERNATE cycle of SUPUR program files enabled.

26

OP$TEST

Loading from TEST cycle of SUPUR program files enabled.

7830 7402–014

Programming Requirements

Table 8–5. Flagbox Bits Bit Number

Bit Name

Description

27

D$0432

Loading from standard program file ONLINED0432A disabled.

28

D$1782

Loading from standard program file ONLINED1782A disabled.

29

D$FAST

Loading from standard program file ONLINEFAST2A disabled.

30

SUPURLOG

TIP utility SUPUR command logging is enabled.

31

TPURLOG

TIP utility TPUR command logging is enabled.

Retrieving Flagbox Bit Values—FLBOX Primitive A program uses an FLBOX primitive request to retrieve the current value of a particular flagbox bit, which is identified by number rather than by name. If the bit is set, it has the value indicated in Table 8–5. FLBOX is supported only in basic mode. Table 8–6 shows the basic formats for an FLBOX primitive request. Table 8–6. FLBOX Request Formats Language

Request Format

ASCII FORTRAN

CALL FLBOX (parameter)

ASCII COBOL

CALL ’CFLBOX’ USING parameter.

MASM

CALL FLBOX parameter.

The FLBOX primitive request takes one parameter: the address of a 1-word buffer where FLBOX stores the bit values after retrieving them.

8.4.3. Execution Option Indicator Primitives Your program uses three types of option indicator requests: UOPGET, UOPAND, and UOPTOR primitive requests.

Option Indicator Retrieval—UOPGET Primitive The UOPGET primitive lets your transaction program get the option indicator word from its own status list of the operating program (SLOP) table. One parameter is required: the buffer location in the online program’s D-bank where the option indicators are stored, right-justified, in H2. The program must be part of the online system, and retrieves the option indicators only for its own execution. Table 8–7 shows the basic formats for a UOPGET primitive request.

7830 7402–014

8–25

Programming Requirements

Table 8–7. UOPGET Request Formats Language

Request Format

ASCII or UCS FORTRAN

CALL UOPGET (parameter)

UCS C

UOPGET (parameter);

ASCII COBOL

CALL 'CUOPGET' USING parameter.

UCS COBOL

CALL 'UOPGET' USING parameter.

MASM

CALL UOPGET parameter

Option Indicator Delete—UOPAND Primitive The UOPAND primitive lets your program delete options from its own option indicators. This removes the ability to use special facilities that were allowed at the time the program received control. The UOPAND primitive request requires two parameters: •

An 18-bit constant in H2 that describes the option indicators to be deleted. A 0 bit deletes the option indicator in that position, and a 1 bit leaves it as it presently exists.

•

One word in your program’s D-bank where the modified option indicators are returned, right-justified, in H2.

This facility is limited to programs that have the required option bit set in the SLOP table entry. The ability to modify the option indicator must have been set when the program was scheduled. It can modify only its own option word. The deletion of the “permit physical COMPOOL” option has no effect. The COMPOOL handler uses the original definition from the PCT, not the variable one from the SLOP table. Table 8–8 shows the basic formats for a UOPAND primitive request. Table 8–8. UOPAND Request Formats Language

8–26

Request Format

ASCII or UCS FORTRAN

CALL UOPAND (parameter)

UCS C

UOPAND (parameter);

ASCII COBOL

CALL 'CUOPAND' USING parameter.

UCS COBOL

CALL 'UOPAND' USING parameter.

MASM

CALL UOPAND parameter

7830 7402–014

Programming Requirements

Option Indicator Insert—UOPTOR Primitive The UOPTOR primitive lets your program insert options in its own option indicator word. It requires two parameters: •

An 18-bit constant in H2 that describes the option indicators to be inserted. A 1 bit inserts the option indicator in that position, and a 0 bit leaves it as it presently exists.

•

One word in the user program’s D-bank where the modified option indicators are returned, right-justified, in H2.

This facility is limited to programs that have the required option bit set in the SLOP table entry. The ability to modify the option indicator must have been set when the program was scheduled. It can modify only its own option word. The insertion of the “permit physical COMPOOL” option has no effect. The COMPOOL handler uses the original definition from the PCT, not the variable one from the SLOP table. Table 8–9 shows the basic formats for a UOPTOR primitive request. Table 8–9. UOPTOR Request Formats Language

Request Format

ASCII or UCS FORTRAN

CALL UOPTOR (parameter)

UCS C

UOPTOR (parameter);

ASCII COBOL

CALL 'CUOPTOR' USING parameter.

UCS COBOL

CALL 'UOPTOR' USING parameter.

MASM

CALL UOPTOR parameter

7830 7402–014

8–27

Programming Requirements

8–28

7830 7402–014

Section 9 Testing Programs and Using Diagnostic Information This section explains how to use test and training modes for testing your TIP programs and how to use diagnostic files for debugging the programs.

9.1. Testing and Training Modes After writing your program, you can test it by using special files instead of the online files to protect the online environment; only the read functions of TIP and KONS files are allowed. Before your program is run in normal mode in a production environment, you can run it in one of three alternate modes of operation: test, training, or test/training. •

Test mode Your program is loaded from an alternate file, instead of a normal online permanent TIP file. This allows debugging of a new or revised program online.

•

Training mode Alternate TIP files are reserved by the site administrator for use as training files instead of TIP permanent files. When a program is executed in training mode, an alternate KONS file is automatically set up for use as a training file.

•

Test/training mode Your program is loaded from an alternate file as in test mode, and alternate TIP files are reserved for use as training files. An alternate KONS file is automatically set up for use as a training file.

9.1.1.

Setting Up Alternate Program Modes Use one of the following three methods to establish an alternate program mode: •

Setting the program mode cell in the message parameter area (MPA) for the Message Control Bank (MCB) applications program interface packet

•

Passing the mode from one program to another

•

Setting execution options

7830 7402–014

9–1

Testing Programs and Using Diagnostic Information

Setting the MPA Program Mode Cell The MPA has a cell in the first sixth (S1) of word 1 for program mode of operation, which can be set to one of the following values: 0

Normal

1

Training

2

Test

3

Test/training

Passing a Mode to Another Program If your program is in one of the three alternate program modes and schedules another program, your program’s mode of execution passes to the scheduled program. Whatever program mode was set in the MPA program mode cell is overridden by the passed mode.

Setting Execution Options You can set the following execution option bits in the OPT parameter of a TIP program’s VALTAB entry or on the @XQT call for a batch- or demand-connect program: O

Test

Y

Training

O,Y

Test/training

If the program is in basic mode and the P execution option is set, the program can use the UOPTOR and UOPAND primitives to set and cancel these program mode options in its option indicator word (8.4).

9.1.2. Setting Up a Terminal for Alternate Modes When SILAS is initialized, each terminal is defined to be in normal mode. The mode of a terminal can be changed when SILAS receives an output message with a different program mode set in the MPA. The mode of the terminal can also be changed when a basic mode transaction program uses the UOPTOR primitive to set an alternate mode; the UOPAND primitive can be used to clear the alternate mode (8.4).

9.1.3. Executing Programs in Alternate Modes If a request is received to schedule a program from a standard program file in test or test/training mode, an alternate copy of the program is loaded from ONLINEFAST2A instead of the standard copy identified by the VALTAB entry. If the transaction program is identified as residing in a SUPUR program file, it is loaded from that file in the TEST library cycle. If a basic mode program scheduled in test, training, or test/training mode terminates abnormally, a SEXEM dump occurs, even if the RECOVERY Z option is not set in the VALTAB entry.

9–2

7830 7402–014

Testing Programs and Using Diagnostic Information

If a request is received to schedule in training or test/training mode, the request is rejected if the TRAINFB FLAGBOX bit is set. But this flagbox bit does not prevent a program containing the Y option from executing.

FCSS Requests In training or test/training mode, you will use special training files for TIP permanent files. In this way, you can read and write to the special files without affecting the online database. TIP temporary and scratch files cannot be changed by the TFUR CG or FREIPS CHA commands. Use the FREIPS RES or TFUR RV commands to allocate a training file. In test mode, you can read the live database, but you cannot write to it. The only functions you perform are Read (RD) and Read and Lock (RL). The read and lock is treated as a read, without locking. For other functions, the request parameters are checked, but not performed. I/O access to a temporary or scratch TIP file is treated normally. A training file is allocated for any permanent file by an RV command.

Timing Requests In test mode, all timing requests are checked for parameter syntax. In training and test/training modes for TIMREL and TIMABS, the program is scheduled immediately without timing delays. The release parameter is cleared and control is returned to the calling program. No timing entry is created.

Logging Requests In test mode, logging requests are not performed, but the request is checked.

User Pass-Off If the requesting program is in test, training, or test/training mode, the scheduled program continues processing in that mode. If the requesting program is in normal mode, the mode of the scheduled program is determined by the program mode cell. If the requesting program is in test mode, the input position identifier (PID) of the scheduled program is taken from the input PID of the requesting program.

Terminal Output If the requesting program is in test mode, the output is sent to the specified output PID if it matches the input PID (TL$PID) in the program control table (PCT) of the requesting program. Otherwise, the output is directed to output PID 0. This causes SILAS to interpret the output as undeliverable and sends the message to an onsite printer. Output is also sent to PID 0 if a program in test mode attempts to change terminal mode.

7830 7402–014

9–3

Testing Programs and Using Diagnostic Information

Note: A program in test mode cannot produce a message parameter area (MPA) through RT$OUT or RT$TRS with a mode change indicated. This prevents a non-debugged program executing in test mode from accidentally removing the originating terminal from test mode. Once in test mode, a terminal can be removed by the following procedure: the terminal operator can enter input to schedule a transaction that is expressly intended for this purpose. Since the terminal is in test mode, this transaction is scheduled out of the debug file, and it begins execution in test mode. The transaction clears test mode by UOPAND. VALTAB options must allow change. The transaction then sends its output with the desired mode change. Table 9-1 summarizes interpretation of the various modes. Table 9–1. Interpretation of Modes Purpose

File handling

Timing

9–4

Primitive

Function

FCSS

RD

Test

Training

Test/Training

TF

TF

RL

Read only

TF

TF

WR

PC

TF

TF

WW

PC

TF

TF

WL

PC

TF

TF

LK

PC

TF

TF

UN

PC

TF

TF

CK

PC

TF

TF

LF

PC

CG

PC

AS

PC

RV

PC

RE

PC

TIMREL

PC

QS

QS

TIMABS

PC

QS

QS

TIMUPR

PC

PC

PC

TIMUPA

PC

PC

PC

TIMDEL

PC

PC

PC

Logging

TPLOG

PC

Pass-off

RTRANU

PM

PM

PM

SYSERR

PM

PM

PM

RTSCHD

PM

PM

PM

7830 7402–014

Testing Programs and Using Diagnostic Information

Table 9–1. Interpretation of Modes Purpose

Terminal output

Primitive

Function

Test

RTRANO

RO

RTOUTP

RO

Training

Test/Training

Legend: PC

Parameter checking only

TF

Access to training file

QS

Quick scheduling

PM

Pass the requestor’s mode to the new program

RO

Output restricted to originating terminal, and change of terminal mode not allowed

9.1.4. Using KONS Functions and Files The KONS handler in the Exec protects against destruction of KONS by a non-debugged program in test mode. The KONS primitive provides a KONS training file in training mode or test/training mode. Use of the KONS training file occurs at the KONS primitive level. The KONS primitive issues ER UK$ONS for all functions in test mode; only read-type operations are performed. Write or locking operations are not performed, but the request parameters are checked. Both training and test/training are the same as normal mode. The KONS functions for test mode are listed in Table 9-2. Table 9–2. Interpretation of KONS Functions for Test Mode Test Mode

Function

FILLWR

Parameter checking only

SCATRD

Normal

KREAD

Normal

KWRITE

Parameter checking only

MSREAD

Normal

SERCHR

Normal

SEQSRD

Normal

CUPDAT

Parameter checking only

KRDLK

Read only

KWRUN

Parameter checking only

KWRKP

Parameter checking only

UNLOCK

Parameter checking only

7830 7402–014

9–5

Testing Programs and Using Diagnostic Information

Table 9–2. Interpretation of KONS Functions for Test Mode Function

Test Mode

LUPDAT

Parameter checking only

SREAD

Normal

SWRITE

Parameter checking only

SUPDAT

Parameter checking only

The KONS training file is an Exec cataloged file. It is not a TIP file. Its name is TIP$*SSKONS. The file type is D (word addressable). The length is KONSFL (user KONS length). This KONS training file is a substitute for accesses to user KONS for a program executing in training or test/training mode. The following are characteristics of the KONS training file: •

No access is allowed in test mode. Access is allowed only in training mode and test/training mode.

•

System KONS accesses are not simulated in training mode and test/training mode. System KONS accesses occur through ER UK$ONS, as in normal mode.

•

Security directory checks are not performed on U3 area access even if the KONSPW parameter is turned on.

•

U3 area locking is simulated through IOW$ locking functions.

•

SEQSRD (sequential search read) is not simulated. This function occurs through ER UK$ONS as in normal mode.

•

MSREAD (masked search read) and SERCHR (search read) are simulated in two phases. An ER UK$ONS is issued and functions as in normal mode. This ER accomplishes a search on the real KONS area. If the search is successful, a read occurs on the KONS training file through IOW$.

9.1.5. Other Considerations This subsection points out some considerations about the use of testing and training modes with specific products and environments: •

High-Volume Transaction Processing (HVTIP) The use of KONS in test/training mode is not supported in an HVTIP environment.

•

Universal Data System (UDS) UDS recognizes and supports test mode, training mode, and test/training mode. In training and test/training modes, alternate database areas are used that are transparent to your program. In test and test/training modes, database updates are captured, suppressed, and recorded in a change file for debugging.

•

Display Processing System (DPS 2200) You cannot use DPS 2200 in test mode, but training and test/training modes are supported. Before use, you need to establish alternate copies of the FCSS files used by DPS 2200. You must also initialize these files through the appropriate DPS 2200 utilities.

9–6

7830 7402–014

Testing Programs and Using Diagnostic Information

•

Message Control Bank (MCB) Test mode, training mode, and test/training mode are all supported by MCB. The MCB determines the mode of the transaction from the mode of the terminal initiating the transaction. Terminal mode establishment and user program interface considerations are described in the MCB Programming Reference Manual.

•

Extended Transaction Capacity (XTC) In an XTC environment, test, training, and test/training modes are supported only on a host-local basis. TIP training files defined in the shared TIP directory are accessible only on the host on which they were most recently reserved. If the training files are to be used on another host, the files must first be released from the one host and their TIP/Exec file containers deregistered from TIP. Then, the TIP/Exec files must be registered in the shared TIP directory from the other host, and the TIP training files must be reserved in them again.

9.2. Diagnostic Information If a basic mode program terminates in error, you can have the system create a diagnostic file or a SEXEM dump, which is a print file containing edited diagnostic information, or both a diagnostic file and a dump. You use the OS 2200 PostMortem Dump (PMD) processor to examine the contents of the diagnostic file. In the extended mode, you can have the system create a diagnostic file for an extended mode program with an entry for each program activity contingency. For a transaction or online-batch program, an entry is also created in the application’s TIP error history file for each diagnostic file. No SEXEM dump is created. You can use the Programmers Advanced Debugging System (PADS) to select the diagnostic file that you want to examine and to edit the diagnostic file.

9.2.1. Diagnostic Files Table 9–3 lists the diagnostic files that the Exec creates and indicates whether they are used in basic mode or extended mode. A more detailed description of each file follows the table. Table 9–3. Diagnostic Files File

Description

Environment

project-id*DIAG$

A temporary diagnostic file that the Exec creates at the initiation of a batch- or demand-connect run. The Exec might write to this file even if no errors occur during the run.

Extended or basic mode

TIPDIAG$*programname-run-id

A permanent diagnostic file that the Exec catalogs for a transaction or online program when the basic program terminates in error, or when an activity of the extended mode program results in an error.

Extended or basic mode

7830 7402–014

9–7

Testing Programs and Using Diagnostic Information

Table 9–3. Diagnostic Files File

TIP$*ERRHISTAPPapp#

Description

The TIP error history file that the Exec creates for each application in your TIP system. The Exec creates an entry in the file that corresponds to each TIPDIAG$ diagnostic file.

Environment

Extended mode only

Here are descriptions of the diagnostic files: •

project-id*DIAG$ The Exec creates a temporary diagnostic file with this name each time a batch- or demand-connect run is initiated; the project-id is the one under which the program is run. The Exec might write to this file even if no errors occur during the run. In basic mode, you can call PMD to read this DIAG$ file, which can contain up to 1,000 tracks. In extended mode, you can call PADS to read this file, which can contain up to 4,000 tracks. If you use the W run option, PADS (for extended mode) or PMD (for basic mode) is called automatically. Since the DIAG$ file is temporary, you can access it only in the environment of the run in which it is created.

•

TIPDIAG$*program-name-run-id The Exec catalogs a permanent diagnostic file with this name each time a basic mode transaction or online batch program terminates in error, or at the first activity contingency for an extended mode transaction or online batch program. In basic mode, you can call PMD to read this TIPDIAG$ file, which can contain up to 1,000 tracks. In extended mode, you can call PADS to let you read this file, which can contain up to 4,000 tracks. You can also write your own program to read the file.

•

TIP$*ERRHISTAPPapp# In extended mode, the Exec creates one of these TIP error history files for each application in your TIP system. If you do not use Integrated Recovery, the Exec creates a single error history file with the name TIP$*ERRHISTAPP01 for the default application (1). When a transaction program activity results in an error, the Exec creates a TIPDIAG$ file and a corresponding entry in the application’s error history file; it adds entries in chronological order. You can use PADS to request diagnostic information from the TIP error history file, or to find out which TIPDIAG$ file to examine.

9–8

7830 7402–014

Testing Programs and Using Diagnostic Information

9.2.2. Security Attributes If your system has SENTRY CONTROL and TSS CONTROL set to TRUE (for Security Option 1 or higher), DIAG$ file is assigned with the same security attributes as the executing run. Because it is a temporary file, it is accessible only during this run. The security attributes for the TIPDIAG$ file are the same as those of the executing user. Since the file is public, access to it in a secured environment depends on the user’s security clearance level. The TIP error history file for each application is a cataloged, public file. Only the Exec can write to the file; the default security level for the file is system-high. Anyone with the appropriate clearance level is permitted read access to the file. This means that you can use PADS to read the file, or you can write your own routine for reading it. If your system has only Fundamental Security features, write keys are used to control write access to the file.

9.2.3. Preparing Transaction and Online-Batch Programs for Diagnostic Files To provide for the creation of a TIPDIAG$ file in the event of a basic mode transaction or online-batch program’s error termination, or an extended mode program activity contingency, your site administrator needs to set a program execution option with the OPTIONS keyword in the program’s VALTAB entry: •

If the program is an absolute element, the T option should be set; if you also want a SEXEM dump to be created, the Z option should also be set: OPTIONS,TZ.

•

If the program is a ZOOM, either the T or the Z option can be used: OPTIONS,T or OPTIONS,Z. However, the Z option does not produce a SEXEM dump.

9.2.4. Preparing Batch- and Demand-Connect Programs for Diagnostic Files In basic mode, to have a SEXEM dump produced when a demand- or batch-connect program terminates in error, use the Z option on the @XQT statement. The Z option does not apply to extended mode, where no SEXEM dumps are produced. In either extended mode or basic mode, the Exec creates a DIAG$ file at the initiation of each batch- or demand-connect run. You can specify an option on the @RUN statement to control what the Exec does with the DIAG$ file: •

(blank) If you do not specify an option, the Exec writes to the DIAG$ file for the run when the basic mode program or extended mode program activity terminates, even if no errors have occurred. The Exec does not write to the file if the program is a system processor.

•

N The N option inhibits all DIAG$ file creation.

7830 7402–014

9–9

Testing Programs and Using Diagnostic Information

•

W The W option causes the Exec to write to the DIAG$ file only if the basic mode program or extended mode program activity terminates in error. If the program is a ZOOM, PADS is automatically called to edit the DIAG$ file; if the program is an absolute element, PMD is automatically called.

•

Y The Y option is the same as no option, except that the Exec writes to the DIAG$ file even if the program is a system processor.

•

WY The WY combination causes the Exec to write to the DIAG$ file even if the program is a system processor, but only if an error occurs. PADS (for a ZOOM) or PMD (for an absolute element) is called automatically.

9.2.5. Making Diagnostic Files Available for Transaction and Online-Batch Programs The TIPTRACE FLAGBOX bit must be on during transaction or online-batch program execution for diagnostic information to be collected in the event of abnormal termination. This is true for basic mode programs and extended mode program activities. The TIPTRACE bit can be set using the BOXER utility described in the Transaction Processing Administration and Operations Reference Manual, or the FB keyin, which is described in the Exec System Software Operations Reference Manual. A program can turn it on using the FOXER primitive, described in 8.4. By the same means, you can turn TIPTRACE off again.

9.2.6. Results of Abnormal Program Termination If the appropriate preparations have been made, a TIPDIAG$ file is created for a transaction or online batch program (a basic mode program or an extended mode program activity) only if an error occurs. For a demand- or batch-connect program, the Exec automatically creates a DIAG$ file for the run and writes to it when the basic mode program or the extended mode program activity terminates; unless you specify the W run option, the Exec writes to the file even if no error has occurred. If the termination is caused by an E,N keyin, diagnostics are not collected regardless of the VALTAB settings for transactions and online batch programs or @RUN options for batch- and demand-connect programs. For ZOOMs, however, the diagnostics are available if the diagnostic file has been written prior to the E,N keyin.

9–10

7830 7402–014

Testing Programs and Using Diagnostic Information

Absolute Elements If the transaction or online-batch program is an absolute element with the T program option set, the system notifies the system console of the unique name of the TIPDIAG$ file that it has cataloged: *TIP DIAG$ FILE CREATED - TIPDIAG$*program-name-run-id If the program has the Z option set as well as the T option, this message is also included in the program print file. If the program is an absolute element and the Z execution option has been set in the program’s VALTAB entry or on the @XQT statement, a SEXEM dump is also produced. If the DEBUGXX FLAGBOX bit is set and the same program continues to execute incorrectly within the next minute, an unlimited number of dumps can be produced and printed automatically; if DEBUGXX is not set, no more dumps are produced within the next minute. During the processing of the diagnostic file, if the system is unable to assign the file it has created, the processing terminates. If the program has the Z option set, the following message is included in the program print file: *TIP DIAG$ FILE FACILITY REQUEST STATUS - status - PMD NOT COMPLETED If an I/O error occurs in writing to the diagnostic file and the program has the Z option set, the following message is included in the program print file: I/O ERROR status WRITING DIAG$ - PMD NOT COMPLETED

ZOOMs If the program is a ZOOM, an entry is also created in the application’s TIP error history file, but no dump is produced. The DIAG$ or TIPDIAG$ diagnostic file is much larger than the one that would be produced for an absolute element, because the ZOOM diagnostic file contains much more diagnostic information. In extended mode, no unwanted dumps are printed automatically for the same program that is executed repeatedly before you can replace it; the same occurrences of errors are saved in TIPDIAG$ diagnostic files, but the TIP error history file provides a directory to let you analyze only the diagnostic files that are relevant. However, since diagnostic information is captured at activity contingency time for ZOOMs, a multiactivity program might receive a partial diagnostic file. If the time limit set by the DEBUGXX FLAGBOX indicator expires before all activities have terminated, it is possible that only some of the activities in error will be captured.

Traditional Diagnostic Files To examine DIAG$ or TIPDIAG$ diagnostic files for absolute elements that have terminated in error, you must use a program of your own.

7830 7402–014

9–11

Testing Programs and Using Diagnostic Information

Extended Mode Diagnostic Files The format of an extended mode diagnostic file is shown in C.6. The Exec creates an entry in the appropriate error history file each time an activity in a transaction or online-batch program terminates in error. The entry contains such information as the error type (contingency type), the program name, the name of the TIPDIAG$ file that the Exec created when the program activity resulted in an error, and the time of the error. The arrangement of the error history file is chronological, with the most recent entry numbered 1. A program with two entries in the error history file will have only one TIPDIAG$ file, but that file will have an entry corresponding to each error history file entry.

9.2.7. Using PADS to Examine Diagnostic Files Use the TIPDIAG keyword when calling PADS to examine TIP diagnostic files. If you do not include an application number, PADS defaults to application group 1. Example 9–1 shows how to call PADS for application group 3. @PADS TIPDIAG,3 PADS 6R1 1990-03020 1631:46 # Application 3 TIP Error History File contains 4 entries. Example 9–1. Calling PADS Once PADS has responded with the number of entries in the TIP error history file, you must find the diagnostic information for a particular transaction. PADS has several standard procedures that give you the ability to examine the TIP error history file to find the correct entry. The TIPLOG$ standard procedure takes the TIP error history file entry number as input and returns the information in that entry. The entry includes the name and transaction code of the program, so that the program can be identified easily. Example 9–2 shows the use of TIPLOG$ for entry 1, the most recent entry. # CMD >TIPLOG$ 1 # TIPLOG(1) #PROGRAM_NAME=RKWICP TRANSACTION_CODE=RKWHVT #ERROR_INFO # ERROR_VA=400004001071T CONTINGENCY_TYPE=2T ERROR_TYPE=0T # ERROR_CODE=2T ERROR_AUX_INFO=20T ERROR_ID=34001000311T # ERROR_DATE=900320 ERROR_TIME=160201 ERROR_INS=0T #TIP_INFO # PID=4320T TIP_TYPE=transaction HVTIP_LIB_BANK=310002T #FILENAME=TIPDIAG$*RKWICP31KHV. Example 9–2. Using the PADS TIPLOG$ Procedure

9–12

7830 7402–014

Testing Programs and Using Diagnostic Information

If there are more entries in the TIP error history file than can be looked at easily with the TIPLOG$ procedure, the PADS DISPLAY command can be used to show particular fields of more than one entry. Example 9–3 shows how to use the DISPLAY command to display both the TRANSACTION_CODE and ERROR_TIME fields of entries 1 through 4. # # # # # # # # # # #

CMD >DISPLAY NAMED TRANSACTION_CODE (1..4) TIPLOG.TRANSACTION_CODE(1)=RKWHVT TIPLOG.TRANSACTION_CODE(2)=XYZHVT TIPLOG.TRANSACTION_CODE(3)=RKWHVT TIPLOG.TRANSACTION_CODE(4)=RKWHVT CMD >DISPLAY NAMED ERROR_TIME (1..4) TIPLOG.ERROR_INFO.ERROR_TIME(1)=160201 TIPLOG.ERROR_INFO.ERROR_TIME(2)=155004 TIPLOG.ERROR_INFO.ERROR_TIME(3)=134644 TIPLOG.ERROR_INFO.ERROR_TIME(4)=134640 Example 9–3. Using the PADS DISPLAY Command

Use the TDIAG$ standard procedure to open the diagnostic file associated with a TIP error history file entry. The TDIAG$ procedure displays the information from the TIP error history file and the header of the diagnostic file opened. The header includes the condition that caused the contigency and the date and time the information was saved. Example 9–4 shows how to use the TDIAG$ standard procedure for entry 3 of the TIP error history file. # CMD >TDIAG$ 3 # TIPLOG(3) #PROGRAM_NAME=RKWICP TRANSACTION_CODE=RKWHVT #ERROR_INFO # ERROR_VA=400004000107T CONTINGENCY_TYPE=2T ERROR_TYPE=0T # ERROR_CODE=2T ERROR_AUX_INFO=110T ERROR_ID=34001002357T # ERROR_DATE=900322 ERROR_TIME=134644 ERROR_INS=0T #TIP_INFO # PID=4302T TIP_TYPE=transaction HVTIP_LIB_BANK=620001T #FILENAME=TIPDIAG$*HVTIP31L2$. # Diagnostic file from runid: *31L2$ # The DIAG file contains more than one saved state. Use the # SELECT PRIOR DIAG ENTRY command to select another saved state. # Activity with ID: 0 captured at 90/03/22 13:46:44 . # Postmortem CONDITION(2T,0T,2T) Guard Mode or Undefined # Sequence in (,,BDI 440000T,777776T). Example 9–4. Using the PADS TDIAG$ Procedure The diagnostic file opened in Example 9–4 contains more than one saved state from that program. When PADS opens the diagnostic file, it examines the most recent saved state. To debug the previous saved state, use the SELECT PRIOR DIAG ENTRY command. Use the SELECT NEXT DIAG ENTRY or SELECT LAST DIAG ENTRY commands to debug more recent saved states. See the PADS Programming Guide for more information on using PADS to examine diagnostic files.

7830 7402–014

9–13

Testing Programs and Using Diagnostic Information

9–14

7830 7402–014

Appendix A TIP Scheduling and Contingency Error Codes Note: The FCSS and FCREG$ status codes that were in this appendix previously are now located in the Transaction Processing Administration and Operations Reference Manual. This appendix describes errors detected at various points in the TIP system. The errors fall into two basic categories: scheduling errors and type 12 (error mode) contingency errors. For type 12 contingency errors, the program is terminated in error and given an error code indicating the problem; the TL$END cell (word 016) in the SLOP table portion of the program control table (PCT) is used to pass this error information in a SEXEM dump or a PMD. A SEXEM dump is produced for basic mode programs scheduled by TIP if the TIPTRACE flagbox bit is set and the program Z option is set in the program’s VALTAB entry or @XQT statement. 015

TL$ETY

TL$COD

TL$CON

TL$REN

Error Type

Error Code

Contingency Type

Program Reentry Address

The cell TL$ERR (word 06, S3) in the SLOP table passes auxiliary error information under certain conditions. For a description of the SLOP table, see Appendix C. 06

TL$ERR Auxiliary Error Status

Table A–1 describes the error codes included in error types 031 through 037, which are all TIP error types: •

Type 031, TIMER errors

•

Type 032, COMPOOL and CPLOGS errors

•

Type 033, MCB errors

•

Type 034, CONECT or DISCON errors

•

Type 035, TIP scheduling errors

•

Type 036, KONS errors

•

Type 037, miscellaneous TIP errors

7830 7402–014

A–1

TIP Scheduling and Contingency Error Codes

•

Type 040, scheduling errors

•

Type 076 and 077, ERR$TIM errors

An asterisk in the EMODE column of the table indicates that the error code is returned as a type 12 (error mode) contingency error. (For information on other contingency error types, see the ER Programming Reference Manual.) The type 033 MCB error codes shown in Table A–1 correspond in most cases to the error codes in the MCB Programming Reference Manual. In cases where an error code has a different meaning for programs using the MCB/COMPOOL primitives and for those using the MCB packet interface, both meanings are shown here. Table A–1. TIP Errors

A–2

Type

Code

EMODE

Error

031

00

*

TIMER call error.

031

01 040

*

TIMER file Exec I/O errors -- Codes same as I/O error codes (type 1).

032

00

032

01

*

Bad COMPOOL type requested through a physical assign.

032

02

*

No COMPOOL of any type left.

032

03

*

Program tried to release a bad drum COMPOOL type.

032

04

032

05

032

06

032

07

*

Program attempted to do a logical release without COMPOOL release option set.

032

010

*

Program attempted physical request without the “permit physical request” option set.

032

011

*

Bad CID submitted for a physical read or write.

032

012

*

No accessible mass storage COMPOOL available at this time.

032

013

*

Bad main storage COMPOOL address passed for release.

032

014

032

015

COMPOOL primitives cannot be used because COMPOOL is disabled on this system by the CMPDIS configuration parameter.

Program tried to release COMPOOL that is marked not in use. *

User’s buffer limits failed access word check. Connected batch type 2 or 3 attempted physical request.

Error return from mass storage I/O request. *

Main storage COMPOOL no longer available.

7830 7402–014

TIP Scheduling and Contingency Error Codes

Table A–1. TIP Errors Type

Code

EMODE

032

016

*

032

017

032

020

*

Invalid COMPOOL type requested, or no COMPOOL remaining.

032

021

*

Assigned main storage COMPOOL no longer available.

032

022

*

Program requested an overlay without an output CID represented in the SLOP table.

032

023

*

COMPOOL overlay request has a start point past the end of assigned output COMPOOL record.

032

024

032

025

032

026

032

027

*

Zero word count in COMPOOL record on read.

032

030

*

Submitted COMPOOL record has zero word count or word count in the submitted block and word count in the call not equal.

032

031

*

Bits 29-0 of submitted CID contain illegal address for type in S1.

032

032

*

Submitted COMPOOL record for output contains invalid COMPOOL indicator.

032

033

032

035

*

Zero start position on read or overlay request.

032

036

*

COMPOOL maximum exceeded.

032

037

Checksum error.

032

040

COMPOOL not released before program terminated or disconnected.

032

041

*

Submitted COMPOOL record contains link that points to itself.

032

042

*

ACW list out of addressing range.

033

Refer to the MCB Programming Reference Manual (Table B-1) for a complete list of error codes generated by the MCB.

034

00

7830 7402–014

Error

User’s I/O packet submitted for physical read/write marked busy. Mass storage COMPOOL checksum error.

Bad COMPOOL type submitted for mass storage access. *

User’s buffer limits failed access word check. Error return from I/O request for mass storage COMPOOL.

Attempted pass-off of released TTY PID.

*

CONECT or DISCON used by online program or by batch program with improper parameters.

A–3

TIP Scheduling and Contingency Error Codes

Table A–1. TIP Errors

A–4

Type

Code

EMODE

Error

034

01

*

No step exists for this activity.

034

02

*

Application has no available queue items.

034

03

*

Request rejected due to outstanding I/O.

034

04

*

Application number invalid.

034

05

034

06

*

Failure to commit before multiple INITAL (ER PI$NIT).

034

07

*

Application access rejected.

034

010

*

Error during audit processing.

034

011

*

Schedule packet or queue-item message type illegal.

034

012

*

Application number does not match application number assigned to program.

034

013

*

Application number does not correspond to recoverable application.

034

014

*

Request invalid for current queue-item state.

034

015

*

Attempt made by program activity to start a step while another activity of program is in program step.

034

016

*

Invalid parameter (A0 not equal to zero).

034

017027

034

030

*

ER EXIT$, PB$DIS, CO$MIT, RL$BAK request while still imparted to DMS 2200; DMS 2200 must request COMMIT or ROLLBACK.

034

031034

*

Not used.

034

035

*

Start-of-step rejected. This activity has XPC–L locks in a non-zero application different for the application for the requested at start-of-step.

034

036037

*

Not used.

034

040

*

FCSS page file error.

034

041

*

FCSS database file I/O error during COMMIT.

034

042

*

The application group mask in the caller's security record does not allow access to the application.

035

00

*

TIP ER done by program without SLOP table (for example, a batch program).

Not used.

Not used.

7830 7402–014

TIP Scheduling and Contingency Error Codes

Table A–1. TIP Errors Type

Code

EMODE

Error

035

01

No output COMPOOL.

035

02

VINDEX not initialized.

035

03

Invalid transaction code.

035

04

Unable to allocate schedule packet or Step Control queue item.

035

05

Unable to allocate SUB-Q. (EXPOOL).

035

06

Invalid COMPOOL-id.

035

07

Output message cannot be delivered. Reason can be any of the following: Specified output PID is not assigned (has not been opened by a CMS). Message type and CMS type are not compatible (MCB/COMPOOL). CMS output queue overflow buffer cannot be allocated.

035

010

035

011

035

012

035

013

Invalid program number.

035

014

Training fallback.

035

015

Maximum test mode programs exceeded.

035

016

Invalid application group number.

035

017

Application access rejected.

035

020

Input message queuing at this priority disabled.

035

021

Invalid user bank descriptor index.

035

022

Invalid common bank descriptor index.

035

023

Invalid initially based common bank.

035

024

Common bank guaranteed entry point not satisfied.

035

025

Invalid bank load table.

035

026

Number of user banks is zero, or START$ bank group is all void banks.

035

027

Program not in production load file.

035

030

Program not in test load file.

7830 7402–014

*

Program type not self-initializing or reentrant. Specified maximum wall clock time exceeded while queued (The "T" option is set in the VALTAB indicator field and TIP FLAGBOX bit MAXTIMENQ is enabled).

*

Response not generated before restart.

A–5

TIP Scheduling and Contingency Error Codes

Table A–1. TIP Errors Type

Code

EMODE

035

031

Unable to read VALTAB record.

035

032

Program file in fallback.

035

033

Program file search error.

035

034

Number of banks exceeds the limit for an absolute program, a ZOOM running in standard memory, or a ZOOM running in TIP memory; see 8.1.11.

035

035

I/O error reading absolute element header or the ZOOM control information.

035

036

No main D-bank for TIP main storage.

035

037

*

Error

No TIP storage group found (an MCORE$/LCORE$/TCORE$ error). Bank will not fit in any TIP main storage group. Bank is dynamic (absolutes only). Number of banks in a TIP main storage group is not sufficient to load the program. Attempt by TCORE$, MCORE$, or LCORE$ to expand D-bank beyond the maximum size specified in the VALTAB parameter DBMAX.

A–6

035

040

User-id is not allowed access to the application group.

035

041

Unable to read MPA.

035

042

Invalid MPA indicator.

035

043

VALTAB down, or contains corrupted information.

035

044

Invalid program type.

035

045

Invalid switching level.

035

046

Alternate file common bank cannot be processed.

035

047

Production load file not available.

035

050

Test load file not available.

035

051

PCT overflow, or ZOOM contains combination of more than 249 program-level banks and more than 246 activity-level banks.

035

052

Memory allocation request rejected by DA.

035

053

Unable to acquire data structure space needed.

035

054

Invalid combination of VALTAB parameters.

035

055

ZOOM has not been processed by SUPUR.

7830 7402–014

TIP Scheduling and Contingency Error Codes

Table A–1. TIP Errors Type

Code

EMODE

Error

035

056

Attempt made to load either an object module or a subsystem definition element as a TIP program. Execution of object modules and subsystem definition elements is not supported for TIP.

035

057

I/O error on attempted read of a ZOOM’s bank load table (BLT). Program not allowed access to HVTIP bank manager ER or CALL interface. A caller must be a high-volume transaction program with only one activity. A high-volume bank must be in the main I-bank window. A subsystem transition cannot be outstanding. When bank transition requests CALL$, XFR$, and RTN$ are made, no outstanding I/O requests may be present. Program issued ER PI$NIT from an activity other than its initial activity.

035

061

*

Maximum number of nested calls (through CALL$ or HV$CALL$SUB) exceeded, or RTN$ attempted when no outstanding calls are recorded.

035

062

*

Invalid library number, or library not available.

035

063

*

Invalid bank number, or bank not available.

035

064

*

I/O error on attempt to load a program bank.

035

065

*

MCORE$/LCORE$/TCORE$ rejected: Requesting program is not a transaction program. (TCORE$) Requesting program is not executing in TIP storage. (TCORE$) Specified BDI is not initially based in the main D-window (absolutes only). No BDI was specified (ZOOMs only).

035

066

*

Illegal HVTIP bank load, or switch between an extended mode bank and a basic mode bank.

035

067

*

TIP File Security configured, requestor does not qualify for execute access to target HVTIP library file, or to file containing requested transaction program.

035

070

Application error program was scheduled and the contingency error information is in the secondary link cell.

035

071

Response not generated before termination.

035

072

COMPOOL not released.

035

074

Message rolled back maximum number of times and requeued to application error program.

7830 7402–014

A–7

TIP Scheduling and Contingency Error Codes

Table A–1. TIP Errors

A–8

Type

Code

EMODE

Error

035

075

Message queued to application error program through ER DMRB$ or RL$BAK request.

035

076

EXIT$ with checkpoint message pending.

035

077

EXIT$ without reading initial input message.

036

01

*

Program attempted operation outside KONS area.

036

02

*

Program attempted to write to S1 portion of system KONS.

036

03

*

Program attempted to write to S2 portion of system KONS or U1 area of user KONS without “write” option set.

036

04

*

Program’s buffer outside program’s limits. Specified buffer length exceeds amount actually provided.

036

05

*

Illegal partial-word designator or partial-word descriptor.

036

06

*

Illegal function code.

036

07

*

Program attempted to use search function in system KONS area.

036

010

*

Illegal security operation. Option bit not set for writing or reading to security directory, or attempt made to perform any security operation without proper security code.

036

011

*

Attempt to access U3 area with incorrect function.

036

012

*

Attempt to perform any lock function past the end of block.

036

013

*

Requested block not locked.

036

014

*

Attempt to allocate request buffer failed, or reject received while attempting to read file directory.

036

015

*

File locked.

036

016

*

User has maximum number of locks allowed.

036

017

*

Excessive activity caused maximum number of retries to obtain lock.

037

02

*

Real-time (CMS) initialization error; caller is not realtime program, or it fails the access control word check, or another CMS is already initialized, or MCB background run attempted to register as CMS number zero.

037

03

*

User not allowed to change options without a particular SLOP option, or user has passed invalid parameter.

7830 7402–014

TIP Scheduling and Contingency Error Codes

Table A–1. TIP Errors Type

Code

EMODE

Error

037

04

*

Illegal ER for TIP program.

037

05

*

Illegal CSF$ image for TIP program.

037

06

*

Activity already assigned CMS number.

037

07

*

Must terminate CMS registration before going non-real-time. NRT$ request denied.

037

010

*

Must terminate CMS registration before releasing main storage area. LCORE$ request denied.

037

011

037

012

*

I/O error while reading queue-item spool block file.

037

013

*

User doing a COMPOOL ER and COMPOOL disabled.

037

014

*

TIP memory deadlocked, and transaction erred to free up banks.

037

015

*

Flagbox lock error (XTC).

037

016

*

Flagbox no interhost broadcast possible (XTC).

037

017

*

Flagbox invalidate error (XTC).

037

020

*

Deregistered TCDBF was based or in the process of being based by a user activity.

Address of input packet for a TIP Session Control ER (TIP$TALK, TIP$SM, or SC$SR) is out of range.

040

For ER RT$SCH and ER RT$TRS. Caller's application group mask not allowed access to the application group.

052

The D-option was specified on a TPUR copy command for an HVTIP ICP (Initial Control Program) and the corresponding VALTAB "DBK" field contains a value of zero.

076

For ER R$TIM. VALTAB is not initialized and the application group mask is not all zeroes or the program is not defined in the VINDEX.

077

For ER R$TIM. Caller's application group mask not allowed access to the application group.

7830 7402–014

A–9

TIP Scheduling and Contingency Error Codes

A–10

7830 7402–014

Appendix B Additional TIP File Control Information FREIPS is the TIP file management utility that is supported by Unisys. However, there may be an occasion when you need to manage TIP file registration, reservation, release and modification from a program. This appendix contains the technical interfaces and information you need if you must do TIP file management from a program. This appendix includes the following topics: •

The general format of the file control superstructure FCSS user buffer and the output status and control fields

•

The FCREG primitive, which registers a file with TIP or deregisters it

•

Three FCSS functions that manipulate permanent TIP files: −

The FCSS RV function, which allocates a permanent file

−

The FCSS RE function, which releases a permanent, temporary, or scratch file

−

The FCSS CG function, which changes the characteristics of a permanent file

B.1. General FCSS User Buffer The FCSS user buffer has the general format shown here. The output fields in the first three words contain request status and control information; words 3 through n contain the input parameters described in Section 3.5.1. 00

FLAGS

01

0

RQSTAT L2STAT

L1STAT

02

BTMASK

03

User data

PDF

FCSSCD DIADR

. n

Word 0 If the word contains a positive value, the request has been successfully completed; if it contains a negative value, the request has failed.

7830 7402–014

B–1

Additional TIP File Control Information

FLAGS Bits that, when set, indicate FCSS request completion status: 0 Request error; check other fields for specific information. 1 Recycle; system activity cannot currently be accepted by the Exec. If this bit is set, the FCSS primitive automatically reissues the TWAIT$ request. 11 Request successfully completed. RQSTAT This field is used as a substatus. Depending on the individual error code in FCSSCD (word 0,,T3) this field may be zero (unused) or contain an Exec I/O status code, a facilities status, an FCSS substatus, or another kind of status code. The individual error code text in C.1 of the Transaction Processing Administration and Operations Reference Manual describes the usage of RQSTAT for each code. PFD This field contains a partial file description of I/O errors, with the bits indicating the following when set: 18 Leg 2 of duplex file has been disabled because of write errors on this request, and because partial file disable was not possible. 19 Same as bit 18, but for leg 1. If this bit is set after simplex I/O, the entire simplex file is disabled. 20 DNR/DNW encountered while performing I/O on leg 2. Portions of leg 2 affected by this request have been previously disabled. 21 Same as bit 20, but for leg 1.

B–2

7830 7402–014

Additional TIP File Control Information

22 DNR/DNW set while performing write on leg 2. Portions of leg 2 have been disabled due to write errors. 23 Same as bit 22, but for leg 1. Note that this cell may be zero even though only one leg of a duplex file was written successfully. See the descriptions of the L2STAT and L1STAT fields. FCSSCD FCSS error code. If this bit is 0, no errors have occurred on the FCSS request. See C.1, “FCSS Error Codes,” of the Transaction Processing Administration and Operations Reference Manual for a complete description of all FCSS error codes. Word 1 L2STAT Leg 2 I/O status. For a duplex I/O request, this field contains a standard Exec I/O status code returned for I/O done on leg 2. If no I/O errors occurred on leg 2, this field is 0. Note that the FCSS request may be considered successful from the user point of view (RQSTAT = 0) even though L2STAT is not 0. L1STAT Leg 1 I/O status. If shared FCSS deadlock information is collected and an FCSS error 026 (deadly interlock condition) is returned, the cell will contain the host identifier where the conflicting lock/RUNID resides (1=HOSTA, 2=HOSTB, 3=HOSTC, 4=HOSTD, 5=HOSTE, 6=HOSTF, 7=HOSTG, 8=HOSTH, 9=HOSTI, 10=HOSTJ, 11=HOSTK, 12=HOSTL). For a duplex I/O request, this field is analogous to L2STAT except that it pertains to leg 1. For a simplex I/O request, L1STAT and RQSTAT contain identical values unless an FCSS error status is returned in RQSTAT. DIADR Address of a deadly interlock, or a partial word count for an RL request for Freespace records.

7830 7402–014

B–3

Additional TIP File Control Information

A lock request (RL, LK, FL, FR) is rejected if a deadly interlock condition exists. This occurs if the calling program (program A) owns a lock on record X and requests a lock on record Y, and if some other program (program B) owns a lock on record Y and requests a lock on record X. (More complicated interlock conditions can exist when there are more than two programs.) Neither program progresses until the interlock is solved. The calling program (program A) receives an FCSS 026 error, and the buffer address associated with lock X is returned in word 1 (H2) of this new lock request buffer. Lock X is the offending lock owned by program A and is released. If the calling program already owns a record lock on records and requests another lock that overlaps one or more of these records, an FCSS 011 error is returned. The buffer address associated with the outstanding lock is returned in word 1 (H2) of this new lock request buffer. If an FCSS 02026 error (reread of deferred update) is returned for an RL function request involving Freespace records, a partial-word count is returned to the user, along with the data read. This partial-word count is the size in words of the deferred update. Callers not using Freespace receive an error code. Word 2 BTMASK For the FCSS CG function (D.4), this word contains the bit mask. For Freespace allocate requests (FCSS AL, AN, or AW functions), this word contains the Freespace record key. For FCSS Read (RD) or Read-and-Lock (RL) requests, this word contains the number of words read on this FCSS request, but only on systems where the Freespace feature (FREEON) is turned on. The number of words read is returned on RD and RL requests for both Freespace and non-Freespace (direct access) FCSS files. If an FCSS 026 error (deadly interlock condition) is returned and FCSS deadlock debugging information is collected, this word will contain the RUNID of the other run/transaction involved in the deadly interlock.

B.2. FCREG Primitive Instead of a TIP Utility For sites that need to access TIP file registration functions from a program, the FCREG primitive is provided in the TIP delivery libraries. The primitive provides the same function as the REG, DREG, TPASG, TPFREE, MAP, and UPDIR functions of the FREIPS utility. To use the FCREG primitive, a calling program must have the U execution option (OPTIONS parameter) set in its VALTAB entry. See the Transaction Processing Administration and Operations Reference Manual for a description of the FCREG buffer, and the FCREG function and status codes. The calling sequence is as follows: CALL FCREG(FUNCTION, BUFFER, FCSTAT, AUX-STAT) where: FUNCTION Is the FCREG function code. B–4

7830 7402–014

Additional TIP File Control Information

BUFFER Is the FCREG buffer. FCSTAT Is the FCREG status code as documented in Appendix C of the Transaction Processing Administration and Operations Reference Manual. AUX-STAT Is a substatus providing supplementary information (such as I/O status code, facilities error code, or other error code) for the main error in FCSTAT. The substatuses are documented in detail for each FCREG status in Appendix C of the Transaction Processing Administration and Operations Reference Manual.

B.3. Using FCSS Primitive Functions Instead of a TIP Utility In addition to the standard functions of the TIP Primitive FCSS, described in Section 3, there are three TIP File Management FCSS functions that are exclusively used by FREIPS. These FCSS functions (RV, RE and CG) allow a caller to reserve, release, or change attributes of a TIP file. These three FCSS functions are not intended for use by normal applications programs. You can use them in user-written TIP file management programs; however, you must understand that you do so at your own risk. The standard FCSS error codes (see Appendix C of the Transaction Processing Administration and Operations Reference Manual) apply to the FCSS maintenance functions of the FCSS primitives. TIP File Control maintains a user attach count in the TIP file directory for all TIP files. Any I/O access of TIP files causes incrementation and then decrementation of the user attach count. While the count is nonzero, these three FCSS functions are not allowed to proceed; the functions are suspended until the attach count is clear. If the request takes longer than a certain amount of time, the system rejects the process with an 0563 error status. The FCSS TIP primitive calls for RV, RE, and CG follow the general FCSS primitive call format, using only parameters p1 through p4: CALL FCSS(p1, p2, p3, p4) Where: p1 p2 p3 p4

= function = return type = user buffer address = TIP file number

7830 7402–014

B–5

Additional TIP File Control Information

B.3.1. FCSS RV Function The RV function allocates a permanent TIP file in a TIP/Exec file. In addition to supplying the characteristics of the file, the calling program specifies the TIP file number, which must be between 17 and the value of the configuration parameter TFPMAX. UDS/TIP files must have numbers at the upper end of the range of possible TIP file numbers. On an XTC system, the TIP/Exec files containing both legs of a duplex TIP file must exist in the same TIP directory (local or shared). You cannot reserve a permanent TIP file in a temporary or scratch TIP/Exec file. Any transaction program can contain an FCSS RV function request. But Unisys recommends that only a utility program (preferably FREIPS) be used to reserve a permanent TIP file. Use the following parameters: p1 = RV (Reserve) p2 = Return type 1 p3 = Buffer address p4 = Not used. The TIP file number is contained in the input data buffer. Figure B–1 shows the FCSS RV user buffer format. 00

Status

01

Unused

02 Related TIP file number 04

Permanent TIP file number

FCSS file name

05 06 07

File type Record length

Storage type (reserved)

Fallback indicators Lock type

Audit # (optional)

010

Copy 1 status Copy 2 status

011

Number of records

012

Exec file start address relative (1) simplex file or copy 1 of duplex file

013

Exec file name (1)

014 015

Exec file start address relative (2) Copy 2 of duplex file

016

Exec file name (2)

017 020 .

Unused

036

Figure B–1. FCSS RV User Buffer Format

B–6

7830 7402–014

Additional TIP File Control Information

Following are descriptions of words in the FCSS RV buffer: Related TIP file number Identifies the corresponding (live) file number if the permanent file allocated is a training file. Whenever the corresponding (live) file is referenced in training mode, the training file is accessed instead. Permanent TIP file number Is the number of the permanent file to be allocated. FCSS file name Has 1 to 12 Fieldata characters, left-justified. File type Is one of these values: 1

Permanent

5

Permanent DMS/TIP

Storage type Is one of these values: 1

Simplex

2

Duplex

Fallback indicators Are optional: 01000

After-looks

00400

Recoverable file

00200

WW allowed on this file

00100

Training file

00020

Deferred write (DEWRIT) file

00010

Autoanswer console messages

Indicators 01000 and 00400 apply only to Integrated Recovery. When you reserve the file, you cannot set the fallback indicator to 00004 for a TIP common data bank file (TCDBF). You must reserve the file and then use the CG function to set the fallback indicator.

7830 7402–014

B–7

Additional TIP File Control Information

Record length Is the number of words per record. Lock type In an XTC environment, if the TIP file is associated with an application group, then the application group lock mode is used as the lock type and you can use the RV function without specifying lock type. If the TIP file is not associated with an application group, you must specify the lock type in the RV function to use XPC–L locking. 00

Software (FCSS) locking

01

Hardware (XPC–L) locking

Copy 1 status Indicates the status of leg 1: 0

Accessible

04

Maintenance read inhibit (cannot be set or changed except by IRU)

010

Maintenance write inhibit (cannot be set or changed except by IRU)

020

Write-only

040

Read-only

060

Inaccessible

Copy 2 status Has the same format as copy 1 status. This applies to a duplex file only. Number of records Is the total number of records to be allocated. Exec file relative start address (1) Is the relative word address in the Exec file where copy 1 of the TIP file is allocated. If this value is specified as negative, the TIP file is allocated in any free area in the Exec file. Note that placement for a recoverable file must be on a device area descriptor (DAD) boundary. Exec file name (1) Is the name of the Exec file where copy 1 of the TIP file is to be allocated; 1 to 12 Fieldata characters, left-justified.

B–8

7830 7402–014

Additional TIP File Control Information

Exec file relative start address (2) Is specified for a duplex file only. This refers to copy 2 of the TIP file. Placement fields for duplex files must be identical. Exec file name (2) Is specified for a duplex file only. This refers to copy 2 of the TIP file. Audit # (optional) Specifies the audit trail (application group) number.

B.3.2. FCSS RE Function The RE function releases a permanent, temporary, or scratch file. A scratch file is also released automatically at termination of the program that assigned it. Unisys recommends that permanent files be released only with a utility program (preferably FREIPS). A permanent file is released only if the calling program has the U execution option (OPTIONS parameter) set in its VALTAB entry. An RE function is rejected if the file is not completely inactive, including no I/O activity and no locks outstanding. Use the following parameters: p1 = RE (Release) p2 = Return type 1 p3 = Buffer address p4 = TIP file number Figure B–2 shows the FCSS RE user buffer format. 00

Status

01

FCSS File name

02 03

Release flag

04 . 036

Figure B–2. FCSS RE Buffer Format Following are descriptions of words in the FCSS RE buffer: FCSS file name Is required for a permanent file only. This name must match the name supplied when the file was reserved.

7830 7402–014

B–9

Additional TIP File Control Information

Release flag Is either of these values: 0

Do not release Exec granules

1

Release Exec granules back to the initial reserve

B.3.3. FCSS CG Function The CG function changes the characteristics of a permanent file. This function is rejected if the file is not completely inactive. The characteristics of a permanent file should be changed only with a utility program (preferably FREIPS). To use the CG function, the calling program must have the I execution option (OPTION parameter) set in its VALTAB entry. One or more individual file characteristics can be changed with a single CG function. To simplify interpretation of results in error cases, only one file characteristic should be changed with a CG function. The characteristics to be changed are specified by a bit mask supplied in the user buffer. The request requires the following parameters: p1 = CG (Change) p2 = Return type 1 p3 = Buffer address p4 = TIP file number Figure B–3 shows the FCSS CG user buffer format. 00

Status

01 02

Bit mask specifying fields to change

03

TIP file number

04

FCSS file name

05 06

File type

Storage type

07 010

Fallback extension

Leg to drop

Fallback indicators

Lock type

Audit #

Copy 1 status

TCDBF flag or

RPF Host

File status, leg 2

RPF AG 011

Number of records

012 013

Exec file name (1)

014 015

B–10

7830 7402–014

Additional TIP File Control Information

016

Exec file name (2)

017 020

Unused

. 036

Figure B–3. FCSS CG Buffer Format The bit mask can have bits set as follows: bit 0 Change storage type simplex to duplex or duplex to simplex. The new storage type is specified in word 6 (S3). If changing from simplex to duplex, the fields in words 13-15 must be specified. If changing duplex to simplex, a nonzero value in word 6 (S4) causes leg 2 to be retained as the simplex file. bit 1 Change FCSS file name; words 4, 5. bit 3 Change fallback indicators. The fallback indicators are specified in word 06(T3). 01000

After-looks desired on audit

00400

Recoverable file

00200

WW allowed on this file

00020

Deferred write (DEWRIT) file

00010

Autoanswer console messages

00004

TIP common data bank file (TCDBF). (You can register an FCSS fixed file, but not a Freespace file, as a TCDBF.)

The fallback extension indicators are specified in word 010(S3). 010

TPM data collection requested for the file.

bit 4 Change copy 1 status; word 7 (S6).

7830 7402–014

B–11

Additional TIP File Control Information

bit 5 Change copy 2 status; word 8 (S6); duplex only. bit 6 Change number of records; word 9. bit 8 Change Exec file name (1); words 11, 12. bit 11 Change Exec file name (2); words 14, 15; duplex only. bit 20 Change locking method (lock type); word 7 (S4). bit 21 Change audit number; word 7 (S5).

Creating the CG Buffer Use the buffer returned by the LF function to create the CG buffer. The buffer returned by the LF function contains the file directory. Modify any of the fields and set the corresponding bits in the bit mask. Clear the first two control words of any residue left by the LF function. Leave the remaining fields the same.

Note: If you do not use the LF buffer for the CG function, you must supply the FCSS file number in the CG buffer. This field is always required. Change bits 8 and 11 cause relocation of the TIP file to a different Exec file. The TIP file's definition is moved, but the TIP file's data is not moved by the CG function. Use caution when you contract TIP files (use CG to decrease the number of records), since the contraction may result in data loss. Any mass storage granules in the contracted area that are beyond the initial reserve specified on the @CAT statement for the TIP/Exec file are released when a CG function is executed. If a subsequent CG function is performed to expand the TIP file to its previous size, new mass storage must be allocated for the released area, and the data for the expanded records must be restored.

B–12

7830 7402–014

Additional TIP File Control Information

FCSS Fixed Files Bit 21 creates potential database recovery problems when used in conjunction with Integrated Recovery, especially in the area of long recovery. Recovery is performed on a per-application/audit-trail basis. This means multiple audit trail sources are not allowed or employed by Integrated Recovery when recovery of an application is performed.

Freespace Files You cannot set bit 21 in the Freespace file, nor can you change its recoverability (bit 3). Changing the number of records in the file does not cause bit maps to be generated or deleted. A program receives an error status code if it changes the number of records to a value less than the current value, and if bit maps that define the area remain. Delete bit maps and generate them separately.

7830 7402–014

B–13

Additional TIP File Control Information

B–14

7830 7402–014

Appendix C Additional Programming Information This appendix provides information on the following subjects: •

The format of the message parameter area (MPA), used by COMPOOL primitives and the MCB primitive interface

•

Special subroutines for FORTRAN and COBOL programs

•

UDS/TIP interface Executive requests (ER)

•

The format of a TIP program’s SLOP table

•

The format of an extended mode diagnostic file

C.1. Format of the Message Parameter Area The message parameter area (MPA), as shown in Figure C–1, consists of 16 words. It must contain the pointer for the start-of-text word and character position. The FORTRAN procedure element CMPDEF defines the message parameter area. You should include or copy this element in your FORTRAN program from TIP$*TIPLIB$. The message text, in the user/text area after the MPA, is basically free format. You call the same message handler primitives regardless of whether you are using MCB or COMPOOL for your program. However, there are some differences between the MCB version of the MPA and the COMPOOL MPA, which is illustrated and described here. For MCB, the format is modified in the following ways: •

The field marked “zero” and the blank fields have no meaning for MCB. They are not used by MCB or carried along with the message.

•

These fields have no meaning for MCB and are also ignored: word 4, T1 and T2, and word 9, H1.

•

For output messages, the input PID (word 1, H1) has no meaning.

7830 7402–014

C–1

Additional Programming Information

1

Mode flag

Function control

2

Word count

Position-id (PID)

3

Device type

4

Second previous program-id

5

Indicator character

Zero TIP ERR code First previous program-id

Partial DID

Queuing priority

Called program-id or program number

Mass storage retention area

6 7 8

Input time of day

9

Character position

10

Number of parameters

I/O start-of-text word

Output device position (PID)

11 12 13

Column coordinate

Line coordinate

14 15 16

Transaction code

17

User parameter area/text

. n

Figure C–1. Message Parameter Area (MPA) Here is a description of the MPA fields used by COMPOOL and, except for the differences noted earlier, by the MCB. Word 1 Mode flag One of the following:

C–2

0

Normal

1

Training mode

2

Test mode

3

Test/training mode

7830 7402–014

Additional Programming Information

Function control Function codes have different meanings depending upon indicator character codes. The following function control codes are applicable with indicator character codes 01, 07, 011, and 013: 002

Unsolicited message; turn on MESSAGE WAITING indicator.

003

Conversational link bell; input terminal operator pressed MESSAGE WAIT keyin or Interrupt key.

004

Multiaddress output message.

005

Multiline hunt output message.

006

F1 function key—067 numeric 7.

007

F2 function key—0107 uppercase G.

010

F3 function key—0127 uppercase W.

011

F4 function key—0147 lowercase G.

012

Function key; UTS 400 function key input is in the first word of the text. SILAS stores the function key input in the first word of the text for all terminals.

013

If the partial DID field of the MPA contains a valid partial DID and this function is chosen, COMPOOL will append a DC2 to the end of the message to activate the device.

Note: A DC2 transfers the message in screen format. An ESC DC2 transfers the message in print-transparent format, which allows the use of the full line width of the printer. 014

THRU response.

015

If the partial DID field of the MPA contains a valid partial DID and this function is chosen, COMPOOL does not append a DC2 to the message. The user is responsible for adding a DC2 to the end of the message to activate the device.

016

Test/training; this code denotes mode change.

037

This code puts the terminal in conversational link.

040

This code removes the conversational link mode.

041076

These codes put the terminal in conversational link.

042

Turn on MESSAGE WAITING indicator for UNISCOPE 100/200 Display Terminal.

043

Same function as 015, but for use in conversational mode.

045

Same function as 013, but for use in conversational mode.

The device handler can issue each of the following status codes. An input message is created to transmit one of these codes only if a conversational link is in effect. If it is not in effect, the status is processed entirely by SILAS.

7830 7402–014

C–3

Additional Programming Information

061

Power-on confidence test (POC); this status code can be for a terminal.

070

Device not configured; this status code indicates an explicit assignment error or a device address error in a request to an auxiliary device. This status probably will not be received for a terminal, because the request to open the session would have been rejected.

072

Input data error.

073

End of media, or no medium for the device; this status code, issued as the result of an activity on the addressed device, might indicate that a printer is out of paper or that the end of a cassette or diskette has been reached.

074

Output data error.

075

Device is not available (because in use) or is down.

076

Undefined error.

The following function code applies to remote symbiont interface (RSI) mode output with indicator character code 015: 01 Sign on RSI mode request. The following function codes are reserved for high-volume transaction system (HVTS) transactions with output indicator character 014:

C–4

000

Normal output

001

Conversational mode

002

Not used

003

Sign-on request

004

Reserved for general system usage

005

Reserved for general system usage

006

Sign-off request

007

Change PID language mode

010

Clear lock and resume count

011

Clear lock and discard count

012

Not used

013

Reserved for general system usage

014

Reserved for general system usage

015

Reserved for general system usage

04n

The leftmost bit of the function code is set to indicate last output block, that is, clear special input hold bit

7830 7402–014

Additional Programming Information

The following function codes are reserved, in addition to the general-purpose use, for HVTS transactions with input indicator character 01: 017

First input after break key

020

Sign-on error

021

PID is not in mode, but output indicator is 014

022

Terminal has timeout on input

Indicator character This binary value indicates which kind of message is being processed. Message types are 001

New input

003

User-to-user pass-off: using transaction code (if TPSNUM is 0) or request for scheduling by program number (if TPSNUM is not 0)

04037

Output to SILAS

007

SILAS internal message

011

Network control function

013

TIP transaction output

014

HVTS output

015

RSI output

037

TIP error code; this value indicates that the message is an output response generated by SEXEM as a result of a TIP scheduling error or a transaction program abnormal termination.

040077

Send to SYSERR

Word count The logical record binary word counter; this word count is inserted by anyone creating a COMPOOL block. It must correspond in value to the word count parameter used when making a call on COMPOOL record. It includes all words starting with word 1. Word 2 PID Input position-id (PID) of the remote input device

7830 7402–014

C–5

Additional Programming Information

Word 3 Device type A value defining the type of device from which the message was initiated. TIP error code This error code is set when an output response is generated by EXEM as a result of an error condition (see word 1, S3 = 037). The error codes are described in Appendix A. Queuing priority This binary value must be assigned by the user assembling an output message or by SILAS on input. One priority must be assigned for all output position-ids when multiple outputs are requested. Word 4 This word contains three binary fields representing the internal routing of the COMPOOL block. It is maintained by anyone using COMPOOL. If there are no previous program-ids, the field is binary zero. Second previous program-id First previous program-id Called program-id or program number This is the next program to be scheduled on a user-to-user pass-off if TPSNUM is not 0 (that is, if scheduling by program number is allowed). The transaction code (word 16) is used if TPSNUM is 0. Word 5 Partial DID This field defines the peripheral unit associated with a device (defined by the PID) to fulfill the output request. It is generated by the user on output. The DCT 1000 partial DIDs are 070

Keyboard

071

Printer

072

Card reader

073

Card punch

074

Paper tape reader

075

Paper tape punch

UNISCOPE 100/UNISCOPE 200 IDs are site dependent.

C–6

7830 7402–014

Additional Programming Information

Word 8 Input time of day Input time of day in milliseconds. This field is generated by the message control routine when it receives a complete message. Word 9 Character position The start position (character in word 0-5 or 6-9) of the text in the COMPOOL record. 0 through 5 represent S1 through S6, and 6 through 9 represent Q1 through Q4. Thus, 0-5 implies Fieldata text and 6-9 implies ASCII. I/O start of text word Input or output. Word 10 Number of parameters This field contains the number of user parameter words in the COMPOOL block. User parameter words start immediately following the transaction code (word 16). Output device position (PID) This field contains the address of the output device where the message is to be sent. It is a binary value. Words 11 and 12 Reserved Word 13 Column coordinate This is the column number (binary) normally designated as a coordinate of the input/output start-of-entry (SOE) position. It starts with 1, not 0. Line coordinate This is the line number (binary) normally designated as a coordinate of the input/output (SOE) position. It starts with 1, not 0. Words 14 and 15 Reserved

7830 7402–014

C–7

Additional Programming Information

Word 16 Transaction code Not required if TPSNUM is not 0 (that is, if scheduling by program number is allowed). Word 17-n User parameter area/text

C.2. Special Subroutines This subsection describes the FIELD subroutine, the Locate subroutine, and COBOL interfaces to KONS.

C.2.1. FIELD Subroutine The FIELD subroutine lets the ASCII FORTRAN program extract one or more bits from a data word. Parameters I Leftmost bit of bit field; bits are numbered from right to left starting with zero. J Number of bits to be extracted from the word. K Name of the word containing the bit field. L Name of the word to receive the bit field; the bit field is right-justified in the word. Example SUBROUTINE FIELD (I, J, K, L) IMPLICIT INTEGER (A - Z) L = BITS (K, 36-I, J) RETURN END

C–8

7830 7402–014

Additional Programming Information

C.2.2. LOCATE Subroutine The Locate subroutine lets an ASCII FORTRAN program obtain the address of a data field (one or more words) in H2 of a data word. Parameters A Name of a data field. B Name of a data word. Example @FTN SUBROUTINE LOCATE (A, B) IMPLICIT INTEGER (A - Z) B = LOC (A) RETURN END

C.2.3. COBOL Interfaces to KONS The COBKON and COBSEC subroutines give ASCII COBOL programs access to the KONS primitives.

COBKON The COBKON subroutine interfaces ASCII COBOL programs to KONS primitives. Arguments are the same as for SEARCH/READ of KONS, SEQUENTIAL SEARCH/READ of KONS, and MASKED SEARCH/READ of KONS except the abnormal return is not used. The return is always to the next sentence. If the KONS record is not found, H2 of argument G contains 0777776 (-1). Example SUBROUTINE COBKON (A, B, C, D, E, F, G) IMPLICIT INTEGER (A - Z) CALL KONS (A, B, C, D, E, F, G, $1) RETURN 1 BITS (G,19,18) = -1 RETURN END

7830 7402–014

C–9

Additional Programming Information

COBSEC The COBSEC subroutine interfaces ASCII COBOL programs to KONS primitives. The arguments are the same as for READ and LOCK of KONS, SECURITY READ of KONS, SECURITY WRITE of KONS, and SECURITY UPDATE COUNTER of KONS except the abnormal return is not used. The return is always to the next sentence. If the U3 block has the lock bit set, H2 of argument E contains 0777776 (-1). Example SUBROUTINE COBSEC (A, B, C, D, E, F) IMPLICIT INTEGER (A - Z) CALL KONS (A, B, C, D, E, F, $1) RETURN 1 BITS (E, 19, 18)= -1 RETURN END

C.3. Bank Expansion and Contraction ERs LCORE$, MCORE$, and TCORE$ are used to manage expansion and contraction of program banks for all HVTIP programs and all programs with the “O” indicator set in their VALTAB entry. For compatibility on 2200/XPA machines running SB6 or higher levels of software, these ERs operate in the same manner as they did on previous SB levels. Table C–1 shows the Executive requests (ER) you can use to expand or contract your program bank. Table C–1. Executive Requests for Memory Bank Expansion/Contraction ER

C–10

Description

MCORE$

Expand the specified bank.

LCORE$

Contract the specified bank.

TCORE$

Expand or contract the specified bank.

7830 7402–014

Additional Programming Information

C.3.1. Requesting Bank Expansion with MCORE$ ER Your program uses the MCORE$ ER to request expansion of a bank. A0

BDI

Upper storage limit

The parameters are loaded in the A0 register as follows: BDI Bank descriptor index; must be specified as 0 or as the BDI of the main D-bank for an absolute element, or as the BDI of the expanding bank for a ZOOM. Upper storage limit The address of the last word of the desired bank. Expansion occurs any number of times during program execution. If the upper limit you specify is less than or equal to the current upper limit of the bank, contraction occurs. The use of MCORE$ results in memory management activity, reducing system performance. ASCII COBOL’s data management system removes the need for ASCII COBOL programs to use MCORE$.

C.3.2. Requesting Bank Contraction with LCORE$ ER Your program uses the LCORE$ ER to request contraction of a memory bank. BDI

A0

Upper storage limit

The parameters are loaded in the A0 register as follows: BDI Bank descriptor index; must be specified as 0 or as the BDI of the main D-bank for absolute elements, or as the BDI of the contracting bank for ZOOMs. Upper storage limit The relative address of the last word of the desired bank. If the address you specify is greater than the current end of the D-bank, expansion occurs.

7830 7402–014

C–11

Additional Programming Information

C.3.3. Requesting Bank Expansion or Contraction with TCORE$ ER Your program uses the TCORE$ ER to request expansion or contraction of a bank. Note the following: •

TCORE$ ER is supported for all transaction programs.

•

Parameters in register A1 are ignored.

A0

BDI

Upper storage limit

A1

Lower transfer address

Upper transfer address

The parameters are loaded in the A0 and A1 registers as follows: BDI Bank descriptor index; must be specified as 0 or as the BDI of the main D-bank for an absolute element, or as the BDI of the specified bank for a ZOOM. Upper storage limit Address of the last word of the desired bank. Lower transfer address This parameter is not ignored. Upper transfer address This parameter is ignored. When you call the TCORE$ ER, you make an implicit request for expansion or contraction, rather than the explicit request with LCORE$ or MCORE$. If a program expands or contracts its banks, and then issues multiple INITAL requests, automatic contraction is not performed for the INITAL. A TCORE$ may not be required before transaction restart. If you want contraction, the program must request it specifically.

C.4. UDS/TIP Interface Executive Requests Four requests to TIP File Control permit UDS Control to perform all the I/O and I/O-related functions needed to place user-specified UDS/TIP control files and data areas under the control of TIP File Control. Each of these requests emulates a compatible Executive request supplied by the normal Exec. The major difference between using the Exec ER and the TIP File Control ER is the usage of a UDS/TIP area (file) number instead of the file name used in the Exec ER.

C–12

7830 7402–014

Additional Programming Information

The following are the TIP File Control ER functions: DM$IOW

Emulates IOW$

DM$IO

Emulates IO$

DM$WT

Emulates WAIT$

DM$FAC

Emulates FACIL$

C.4.1. DM$IOW Request Issue an I/O request and wait for completion.

Input Format A0,I/O packet address L,U ER DM$IOW Figure C–2 shows the DM$IOW packet format. 0

Not used

Area number

1

Not used

2

Not used

3 4 5

Not used G

Funtion

Not used

Word count I/O type

Buffer address Word or sector address in file

6

3 3 4 5

7

Not used

Figure C–2. DM$IOW Packet Format Word 0 Area number UDS/TIP area number. This is also the number of the TIP files that are greater than 16 but not greater than the configured maximum, specified by the Exec TFPMAX parameter.

7830 7402–014

C–13

Additional Programming Information

Word 3 Function Function code. If TIP File Security is used, read access is required for read functions and write access for write functions: 020

R$, Read

010

W$, Write

043

SCR$, Scatter-read

015

GW$, Gather-write

073

FSAFE$, File save

054

BDR$, Read by BDI

004

BDW$, Write by BDI

057

BDRX$, Read by BDI extended

Word 4 G-bits (bits 0–1) Have the following meanings when set: 00

Increase buffer address after each word is transferred

10

Decrease buffer address after each word is transferred

01, 11

Do not modify buffer address during I/O transfer

Word count (bits 2–17) Word count for R$ and W$, number of ACWs for SCR$ and GW$, or number of ACW pairs for BDR$ and BDW$ Buffer address I/O buffer address for R$ and W$, or address of ACW list for SCR$ and GW$, BDR$, and BDW$ Word 5 I/O type (S1) Is one of the following:

C–14

1

Perform I/O on leg 1 only of duplex file

2

Perform I/O on leg 2 only of duplex file

040

Mass storage address is a word address; if this indicator is not set, mass storage address is a sector address

7830 7402–014

Additional Programming Information

Word or sector address (S2-S6) Word or sector address of data area in the file. Word 6 This word is supplied only when the BDRX$ function is used, and contains extra parameters that can be used to specify how I/O is performed. No resource queuing (Bit 34) When set, indicates the I/O request would rather receive a status than be queued for internal system resources. This includes returning status instead of queuing an asynchronous I/O request (IO$) when the program already has too many asynchronous requests outstanding. Use XPC–L bypass (Bit 35) When set, indicates that if the I/O request uses an XPC–L, no data should be staged into an XPC–L for this request. This should be used when the application knows it will not reuse the data, for example, a file backup or load from tape. This flag is meaningful only for I/O to mass storage files.

Output The following status information is returned in word 3 of the packet at I/O completion: 03

RQSTAT

PFD

DMSL2

DMSL1

RQSTAT (word 3,,S1) The contents of this field depend on the type of request: •

I/O request failure This field contains a standard Exec I/O status code describing the reason for failure, with one exception: a status of 02 indicates the TIP file directory was unavailable.

•

Simplex I/O request RQSTAT is 0 if every word of data was successfully transferred from the UDS/TIP file.

•

Duplex write request RQSTAT is 0 if every word of data was transferred to at least one leg of the duplex UDS/TIP file in a way that leaves the data retrievable in future duplex read requests.

•

Duplex read request RQSTAT is 0 if every word of data requested has been read from the duplex file.

7830 7402–014

C–15

Additional Programming Information

•

FSAFE$ (file safe) function request If an error occurs, RQSTAT does not contain an I/O error status code. Instead, it contains a 2-digit number indicating an FCSS maintenance error code (see Appendix A).

PFD (word 3,,S3) This field contains partial file disable status flags, defined as follows: Bit 12

Leg 2 of duplex UDS/TIP file has been disabled because of write errors on this request and because partial file disable was not possible.

Bit 13

Same as bit 23, but for leg 1; if this bit is set after simplex I/O, the entire simplex file is disabled.

Bit 14

DNR/DNW encountered while performing I/O on leg 2; portions of leg 2 affected by this request have been disabled.

Bit 15

Same as bit 21, but for leg 1.

Bit 16

DNR/DNW set while performing write on leg 2; portions of leg 2 have been disabled due to write errors.

Bit 17

Same as bit 19, but for leg 1.

DMSL2 (word 3,,S5) Is leg 2 I/O status. For a duplex I/O request, this field contains a standard Exec I/O status code returned for I/O done on leg 2. If no I/O errors occurred on leg 2, this field is zero. Note that the I/O request may be considered successful from the user point of view (RQSTAT=0) even though DMSL2 is not 0. DMSL1 (word 3,,S6) Is leg 1 I/O status. For a duplex I/O request, this field is analogous to DMSL2, except that it pertains to leg 1. For a simplex I/O request, DMSL1 and RQSTAT contain identical values unless an error occurs before the I/O is initiated (for example, a bad file number). The following status information is returned in word 7 of the packet at I/O completion only when the BDRX$ function is used: 7

3 5

I/O used XPC–L (Bit 35) When set, this bit indicates the XPC–L was used to perform the I/O request. The flag is meaningful only when for I/O to mass storage files.

C–16

7830 7402–014

Additional Programming Information

C.4.2. DM$IO Request DM$IO issues an I/O request and receives an immediate return. Format L,U A0,I/O packet address ER DM$IO The packet format and the returned status information are identical for DM$IOW. Control returns immediately to the calling program, without waiting for completion of the I/O operation. It is necessary for the calling program to test the packet status or issue an ER DM$WT to wait for completion.

Note: If the packet address or buffer address resides in a common bank, an immediate-return request cannot be issued; the same restriction exists for ER IO$.

C.4.3. DM$WT Request Wait for completion of an I/O request previously issued by ER DM$IO. Format TP I/O-packetaddress + 3 ER DM$WT Indexing can be used in the TP instruction. However, the H or I bits cannot be set. It is also possible for the calling activity to use the following standard ERs: •

ER WANY$: Wait for completion of any outstanding I/O request.

•

ER WALL$: Wait for completion of all outstanding I/O requests.

C.4.4. DM$FAC Request Request file status information for a specific file. The purpose of this request is to determine if the file is defined and to obtain pertinent characteristics. Format L,U A0,packet address ER DM$FAC Figure C–3 shows the DM$FAC packet format. 0

Not used

Area number

1

Not used

2

Not used

3

Status

Not used

4

Not used

5

Not used

6

File type

7

File status

8

Leg1 status

Leg2 status

Not used

TIP file number

Not used File length in sectors

Figure C–3. DM$FAC Packet Format

7830 7402–014

C–17

Additional Programming Information

Word 0 Area number If zero, the TIP file number in word 6 is the maximum number of permanent fixed TIP files (TFPMAX). If an area number is specified, the TIP file number in word 6 contains the corresponding FCSS number for this area. Word 3 Status If nonzero, request was not successful (see C.4.6). Word 6 File type If zero, this file is not defined in TIP File Control. If the file is defined, file type bits are 0

Duplex

1

Temporary

2

Scratch

3

Always set to 1

4

Freespace

5

Always set to 1

Leg 1 status Primary leg status bits: 6

Write inhibited

7

Read inhibited

8

Maintenance write inhibit

9

Maintenance read inhibit

10-11

Not used

Leg 2 status Secondary leg status bits (duplex file only):

C–18

12

Write inhibited

13

Read inhibited

14

Maintenance write inhibit

15

Maintenance read inhibit

16-17

Not used

7830 7402–014

Additional Programming Information

TIP file number The TIP FCSS file number for the area specified in word 0 or, if the area number in word 0 is 0, the maximum number of permanent TIP files (TFPMAX). Word 7 File status bits 0

File locked (exclusive use)

1

Read allowed through file lock

2

FCSS after-looks desired

3

Recoverable file

4

FCSS “WW’’ function allowed

5

Not used

C.4.5. EMODE Conditions The following conditions cause the calling activity to terminate in error: •

If the caller is not an online TIP program or a batch-connect program, the caller terminates with error 03500.

•

For DM$IOW, DM$IO, and DM$FAC requests, the caller supplies a packet address in A0. If this packet address is out of range or if it is in a write-protected bank, the caller terminates with error 0402.

•

If an ER DM$WT is not preceded by a valid TP I/O-packet-address+3 instruction, the caller terminates with error 0136.

C.4.6. DM$IOW/DM$IO I/O Status Codes DM$IOW/DM$IO I/O status codes are compatible with standard Executive I/O error codes, as shown in the ER Programming Reference Manual. The status codes have the following format: 00

Normal completion

01-037

Error

040

Request in progress

041-077

Not used

Errors in the range 01 to 017 refer to physical hardware problems; status code 02 is an exception for DM$IOW and DM$IO I/O. Errors in the range 020 to 037 refer to logical problems. The status code is returned in the I/O packet word 3 (S1); error 036 is an exception since this causes an EMODE.

7830 7402–014

C–19

Additional Programming Information

Error conditions can be detected by TIP File Control or by the Exec I/O routines. If an error is detected by TIP, it probably indicates that the corresponding TIP file is not properly defined, or that the request is not valid with respect to the TIP file directory. The following are the main errors detected by TIP: 02 TIP file directory was not available. This meaning is different from that of the standard IO$ 02 error code; this is a temporary condition, and the request should be attempted again. 05 Attempt to read unassigned area of mass storage; check starting sector address in packet. 017 The request failed because not enough system resources were available. 020 The read or write request to the TIP file was inhibited. Either the file is in read-only or write-only mode, or TIP File Security does not permit access to the file. 021 File does not exist; invalid TIP file number (out of range). File not a UDS/TIP file. 022 Attempt to write unassigned area of mass storage; check starting sector address in packet. 024 Invalid function; only R$, W$, SCR$, and GW$ are allowed. 025 Invalid ACW or ACW list; probably indicates an invalid buffer address. 036 Invalid DM$WT; probably indicates that a valid “TP” instruction does not precede ER DM$WT. For requests which use the BDRX$ function, this status code is returned when a reserved area in the packet is nonzero. The status code is returned if any of the undefined cells in word 6 are nonzero when the request is issued. 037 TIP File Control internal RLP lock request failed.

C–20

7830 7402–014

Additional Programming Information

C.5. Format of a SLOP Table When TIP initializes a TIP program or a program connected to TIP, control parameters are inserted into the program control table (PCT). These parameters are inserted in that portion of the PCT called the status list of the operating program (SLOP) table. The SLOP control word (currently, word 0337) of the PCT indicates whether the SLOP table is being used. The SLOP table starts immediately after the SLOP control word (currently, word 0340 of the PCT).

Note: The PCT (including the SLOP table) is an internal Exec structure and is therefore subject to change with each release. The latest changes to the PCT might not be reflected in this documentation.

C.5.1. SLOP Table Format and Field Descriptions Figure C–4 shows the format of the SLOP table. 00

TL$NAM

01

TL$PRI

TL$TYP

TL$XID TL$MAX

02

TL$LOADTYP

TL$FDX

TL$JAVA

03

TL$ERCALL

TL$MCB

TL$NSF

TL$RSP

04

TL$CIM

05

TL$COM

06

TL$TSCAPN

TL$FLG

TL$ERR

TL$ACCT

TL$SESSION

07

TL$OPT

TL$PID

010

TL$SUB

TL$SLE

011

TL$CMSE

012

TL$STA

TL$SCHT

013

TL$ENT

014

TL$FCQ

TL$RCT

015 016

TL$IIN

TL$LLB TL$ETY

TL$COD

TL$CGY

TL$REN

017

TL$CMP

TL$PAS

020

TL$XST

TL$QI

021

TL$CMS

022

TL$TIM

023 024

TL$PFN

TL$LKCN

Figure C–4. Format of the SLOP Table

7830 7402–014

C–21

Additional Programming Information

These are the SLOP table fields shown in Figure C–4: Word 00 TL$NAM Name of TIP program (absolute element or ZOOM) in Fieldata. Word 01 TL$PRI Execution priority (A through Z). TL$TYP TIP program type: 1

Self-destructive

2

Self-initializing

3

Reentrant

4

Online batch

5

High-Volume Transaction Processing (HVTIP)

TL$XID Execution identifier. Word 02 TL$LOADTYP TIP program load type. TL$FDX Program file index. TL$JAVA If nonzero, this transaction is JAVA enabled (the VALTAB indicator option V is specified). TL$MAX Maximum allowed execution time; this is measured in standard unit of processing (SUP) seconds for transaction programs and in minutes for online-batch programs.

C–22

7830 7402–014

Additional Programming Information

Word 03 TL$ERCALL Indicates TPM is collecting statistics on the total number of requests for each ER and CALL if nonzero. TL$MCB Transaction execution through MCB (VALTAB status word bit J). This flag is interrogated by DPS 2200 to determine whether the transaction program uses COMPOOL or the MCB. TL$NSF Number of scratch files assigned to this program. TL$RSP Flag indicating whether user response is generated. TL$ACCT TIP log accounting flag: 0

Log entry already created

01

Log entry to be created during transaction termination

02

Log entry to be created during transaction termination with no-inputavailable subtype; TIP log accounting pending flag. A type 41 log entry is created for transaction termination; a type 42 log entry is created for transaction restart by multiple INITAL, reactivation, or sticking.

TL$IIN (TIPBUG) Handled by interlock code flag. Word 04 TL$CIM Input COMPOOL identifier; type and address of the input COMPOOL record assigned to the program. Word 05 TL$COM Output COMPOOL identifier; type and address of the output COMPOOL assigned to the program.

7830 7402–014

C–23

Additional Programming Information

Word 06 TL$TSCAPN Number of the application group for which a TIP session (identified by TL$SESSION in H2) has been opened; this cell exists only if TIP Session Control is configured. TL$FLG Contains TIP transaction information flags; following is the list of flag bits and their meanings. Bits 0 – 3

Unused.

Bit 4

The transaction exceeded the specified maximum wall clock time and TIP diagnostics was requested.

Bit 5

The transaction exceeded the maximum wall clock time as specified by the VALTAB TIME parameter/keyword.

TL$ERR Auxiliary error status; see word 016 (TL$END). TL$SESSION TIP session-id; this cell exists only if TIP Session Control is configured. Word 07 TL$OPT Program options (I through Z). TL$PID Position-id of input terminal. Word 010 TL$SUB Submitted queue pointer. TL$SLE Switch list pointer.

C–24

7830 7402–014

Additional Programming Information

Word 011 TL$CMSE Extended CMS bit map for CMS numbers 36 to 63. If any activities of this program have registered as CMS programs within this range, the corresponding bits are set in this cell. Bit 8 is set for CMS number 63 and bit 35 for CMS number 36. Word 012 TL$STA Status bits. TL$SCHT Scheduled time in system minutes (only for TIMER transactions). Word 013 TL$ENT Reentry point for reusable program. Word 014 TL$FCQ File control request list chain. TL$RCT Buffer for recording nested CALL$ requests until RTN$ is issued. Word 015 TL$LLB Contains the HVTIP library and bank number of the HVTIP I-bank that an HVTIP transaction is currently executing in. Word 016 (TL$END) TL$ETY TIP error type (031 through 037). TL$COD Error code, described in A.2 under the error type; any auxiliary error status is in word 06, S3 (TL$ERR). TL$CGY Contingency type. 7830 7402–014

C–25

Additional Programming Information

TL$REN Reentry address. Word 017 (TL$CNT) TL$CMP Total COMPOOL blocks assigned. TL$PAS Number of COMPOOL records passed off. Word 020 TL$XST Number of activities connected to TIP. TL$QI Queue-item address for first input message. Word 021 TL$CMS CMS bit map for CMS numbers 0 to 35. If any activities of this program have registered as CMS programs within this range, the corresponding bits are set in this cell. Bit 0 is set for CMS number 35 and bit 35 for CMS number 0. Words 022 and 023 TL$TIM Time and date of program creation. Only the first word is used for absolute programs; both words are used for ZOOMs. Word 024 TL$PFN TIP program file number. TL$LKCN Count of outstanding FCSS record locks.

C–26

7830 7402–014

Additional Programming Information

C.5.2. SLOP Control Word in the PCT Figure C–5 shows the format of the SLOP control word, which is followed immediately by the SLOP table (Figure C–4) in the PCT. The SLOP control word is currently word 0337 of the PCT. TL$SCH

TL$RDO

TL$SLP

Figure C–5. Format of the SLOP Control Word The SLOP control word contains the following fields: TL$SCH Offset to the scheduling packet. TL$RDO PRINT$ file assignment flag. TL$SLP Transaction program state: 00000

Not TIP (has no SLOP table)

00001

Batch or demand program connected to TIP

00050

TIP transaction

05000

Online batch program not connected to TIP

05001

Online batch connected to TIP

C.6. Format of an Extended Mode Diagnostic File This subsection describes the format of an extended mode diagnostic file (TIPDIAG$ or DIAG$ file) that the system creates when an extended mode program terminates in error. You can use PADS to examine this file, or you can write your own program. Except for the contents of the transaction SUBQ, which the system copies into the diagnostic file in the new format, as described in the following pages, and the program file name, text in the file is in ASCII format. The diagnostic file has a header section, followed by multiple program header entries and activity (bank) entries. Each section begins on a sector boundary. The system writes one program header entry for each program that terminates in error and one activity entry for each activity in the program that encounters an error.

7830 7402–014

C–27

Additional Programming Information

C.6.1. Diagnostic File Header The diagnostic file header is at sector 1000 (decimal) and is 8 words long. The header contains these fields: Word 00 A validation constant that distinguishes this diagnostic file from a basic mode diagnostic file; the constant is *df*. Word 01 H2 Not used. Word 02 Sector-relative file address of the first activity entry. Word 03 Sector-relative file address of the last activity entry written to the file. Word 04 Sector-relative file address of the next available space in the diagnostic file. Word 05 Number of sectors remaining in the file. Word 06 H1 Size in sectors of the file header area. H2 Size in sectors of the program common area. Word 07 The time the program was started.

C.6.2. Program Header Each program header can be up to 51 words long and contains these fields: Word 00-Word 01, H1 Transaction ID if the program is batch- or demand-connect.

C–28

7830 7402–014

Additional Programming Information

Word 01, H2 Not used. Word 02 H1 Size in sectors of the activity header. H2 Size in sectors of the bank header. Words 03-04 Directory-id for the program file from which the last program was loaded; 0, if none. Words 05-010 Name of the program file (not ASCII). Word 011 H1 Not used. H2 File cycle of the program file. Words 012-014 Name of the element from which the last program was loaded. Words 015-017 Version name of the element. Words 020-021 Not used. Words 022-024 Exec level under which the program is executing. Word 025 H1 The domain and ring numbers assigned to this subsystem. H2 Not used. 7830 7402–014

C–29

Additional Programming Information

Words 026-031 Bank name and bank offset for four gates that the Exec uses to call the Linking System. Words 032-057 Transaction SUBQ information packet (for TIP version 1 programs only); 22 words are reserved for the SUBQ packet. The packet is described after the program header. Word 060 T1 The type of program, which is defined by the following values: 00000

Not TIP

00001

Batch or demand connect

00050

Transaction program

05000

Online batch not connected to TIP

05001

Online batch connected to TIP

S3 Must be zero. H2 For HVTIP programs, the library and bank number of the program; for programs that are not HVTIP, zero. Word 061 For HVTIP programs, the virtual address of the HVTIP software return stack; for programs that are not HVTIP, zero. Word 062 H1 For HVTIP programs, the library and bank number of the initial control program (ICP); for programs that are not HVTIP, zero. H2 Must be zero.

C–30

7830 7402–014

Additional Programming Information

Figure C–6 shows the format of the TIP SUBQ information packet. 00

pgm_nam

01 02

max_run_time 0 1 2

4 5

priority *

*

pgm_type

*

file_index pgm_options

03

(reserved)

pgm_file_number

04

errant_subq_chain_pointer

rtps_number

05

*

*

*

06

(reserved)

*

*

07

*

control_flag

*

error_flag

wait_count

reentrant_bcp_va

010

vindex_entry_number

(reserved)

011

printq_device

012

pgm_addr

013

dwtime_stamp

*

3 3 4 5

014 015

zoom_pgm_entry_point

016

latent_parameter

017

als_initial_size

als_max_size

020

zoom_bank_load_table

021

(reserved)

022

(reserved)

indicator_flags

Figure C–6. TIP SUBQ Information Packet Word 00 Program name; the transaction program name taken directly from the VALTAB. It is left-justified and space-filled. Word 01 T1 The maximum run time of this transaction (in minutes for an online-batch program and in seconds for a transaction program). S3 The run priority for this transaction program (within a range from A to Z).

7830 7402–014

C–31

Additional Programming Information

S4 Program type, which is one of the following: 1

Self-destructive program

2

Self-initializing program

3

Reentrant program

4

On-line batch program

5

HVTIP program

S5 File index. This field indicates which program file cycle the program should be loaded from. Program types 0 through 2 are loaded from SUPUR files; 3 through 5 are for transactions loaded from standard online program files (which are not allowed for ZOOMs), and must be 0 for HVTIP transactions. 0

Main library cycle

1

Alternate library cycle

2

Test library cycle

S6 Maximum number of copies of this transaction allowed to be in memory concurrently. Word 02 H1 Status bits, defined as follows:

C–32

0

I status option—if set and sticking is turned on, the transaction may be stuck in main storage.

1

J status option—if set, the production version of the transaction program uses the MCB; if not set, it uses COMPOOL.

2

K status option—if set, block transfer loading is allowed.

3

L status option—if set, the test version of the transaction program uses the MCB; if not set, it uses COMPOOL.

4

M status option—if set, a new main SUBQ is created if the current main SUBQ is marked in error. Transaction scheduling then takes place from the new main SUBQ.

5

N status option—reserved for system use.

6-11

Status options O through T are user defined.

7830 7402–014

Additional Programming Information

12-14

The desired wait-queue length expressed as a multiple of the number of active program copies. The default is zero.

15-17

The number of 512-word PCT blocks–1. The default is zero.

H2 Program options, which are the following: 0

The program will produce a dump (SEXEM dump) upon abnormal termination.

1

Indicates training mode.

2

Allows the program to access protected system files, and allows the use of FCSS maintenance functions.

3

Not in use at present, but used for debugging with STPAUL on.

4

Allows physical COMPOOL requests.

5

Allows the FCSS release function (RE); also allows the FCREG file registration/deregistration.

6

Creates a diagdump file upon abnormal program termination.

7

Allows the program to write into protected KONS area; also allows the program to read this area with or without option.

8

Allows the program to release logical COMPOOL blocks by way of the CRELOG primitive cell.

9

Allows the manipulation of the KONS security directory.

10

Allows the program to manipulate its SLOP table entry.

11

Test mode.

12

Tells the program to schedule another program or send an output response before terminating.

13

Allows maximum number of print pages to be exceeded.

14

Permits TIP logging for this program.

15

Inhibits common bank dumps when dumping to the printer (only meaningful when used with the Z option).

16

Not used.

17

Allows the FCC change function (CG).

Word 03 H1 Reserved.

7830 7402–014

C–33

Additional Programming Information

H2 The TIP program file number. Applies only to SUPUR program files. Word 04 H1 The relative address of the next errant SUBQ in an errant SUBQ chain or 0 if the end of the chain. This is a global cell. The main SUBQ must be locked when altering or searching an errant SUBQ chain. H2 The index into the RTPS name table for this SUBQ (0 = not RTPS). Word 05 S1 The number of deactivated RTPS program copies. S2 The number of active copies of this transaction. In a main SUBQ linked to one or more errant SUBQs, this field represents the cumulative total of active program copies for all linked SUBQs. In an errant SUBQ, this field only reflects the number of active copies for that SUBQ. This field is a global cell that is updated only when the main SUBQ is locked. S3 The program format indicator, defined as follows: 0

A value of 0 indicates absolute standard load format.

1

A value of 01 indicates absolute fast-load format.

2

A value of 02 indicates ZOOM standard load format.

3

A value of 03 indicates ZOOM fast-load format.

4

A value of 04 indicates ZOOM HVTIP format.

S4 Control flag status, defined as follows:

C–34

0

A 0 (null) value indicates no activity, and that the SUBQ is eligible for loading another program copy.

1

A 01 value indicates that the SUBQ is being constructed by TRFUNC.

2

A 02 value indicates that the SUBQ is on the PSH/TIPMEM initial load chain.

7830 7402–014

Additional Programming Information

3

A 03 value indicates that the program load is in progress.

4

A 04 value indicates that the program is waiting for a reentrant bank load.

5

A 05 value indicates that all TIP memory banks for this transaction have been acquired.

6

A 06 value indicates that the SUBQ is temporarily held in its current state. This is the control flag for the transaction, indicating current or pending SUBQ activity. One usage of this field is to prevent the SUBQ from being released between the time it is unlocked and relocked.

S5 The number of copies of this transaction that are stuck. S6 Error flag status, defined as follows: 0

The SUBQ is not in error.

01

The SUBQ is in error.

03

The program needs more banks in a TIP memory group than that group can hold. This field can be set to indicate that no more schedule requests are to be processed through this SUBQ. After active copies terminate, the SUBQ is to be rebuilt to process any schedule requests on the wait-queue.

Word 06 S1 Unused. S2 The number of resident copies. In a main SUBQ linked to one or more errant SUBQs, this field represents the cumulative total of resident copies for all the linked SUBQs. In an errant SUBQ, this field only reflects the number of resident copies for that SUBQ. This field is a global cell that is updated only when the main SUBQ is locked. S3 The TIP program initial switching level. H2 The number of schedule packets on the wait-queue.

7830 7402–014

C–35

Additional Programming Information

Word 07 The virtual address in L,BDI, offset format of the reentrant bank BCP. This field contains zero when there is no reentrant bank attached to the SUBQ. Word 010 H1 The VINDEX entry number for this transaction. It must be multiplied by VXLEN to get offset in VINDEX bank to point at either real VINDEX or test VINDEX entry. S4 Unused. S5 Unused. S6 This field contains the SUBQ flags, defined as follows: 30

Not used.

31

Not used.

32

Unused.

34

The alternate load file available flag.

35

The transaction code in use flag.

Word 011 The default print queue that transactions for this SUBQ will use. It is derived from the VALTAB PRT field. It contains FIELDATA spaces if no print queue was explicitly defined. Word 012 The file-relative sector address of the beginning of the transaction program within the TIP program file. For programs in standard-load format, the entire element is present (including control information), whether it is an absolute element or a ZOOM. For programs in a fast-load format, only the bank text is present. In either case, this is the start of the program. It must be converted to a word address by multiplying by 28 (words per sector) to be useful to the Exec for reading TIP files. Words 013 and 014 The time and date (in DWTIME$ format) when this ZOOM was created. Word 015 The program entry point, in L,BDI, offset format, where execution begins. C–36

7830 7402–014

Additional Programming Information

Word 016 The latent parameter (R0) value (currently the virtual address of the link vector bank). Word 017 H1 The activity-local stack initial size. H2 The maximum size of the activity-local stack. Word 020 The virtual address, in L,BDI, offset format, of the ZOOM’s bank load table. Word 021 Unused. Word 022 H1 Unused. H2 Indicator flags.

C.6.3. Activity Entry The number of activity entries in a diagnostic file does not depend on the number of activities in the program. Each time an activity of the program receives a contingency, an activity entry is written to the diagnostic file. For a transaction or online-batch program, only error contingencies are written to the TIPDIAG$ file. For a demand- or batch-connect program, even nonerror contingencies are written to the DIAG$ file if the Y run option or no run option is used. Each activity entry in the diagnostic file consists of an activity entry header and a bank entry for each of the activity’s banks. All activity entries start on a sector boundary. Each activity entry has a header with the following fields: Word 00 Sector-relative file address of the previous activity entry; 0, if none. Word 01 Sector-relative file address of the next activity entry; if the next entry is not yet written, this field points to the next available space.

7830 7402–014

C–37

Additional Programming Information

Word 02 Size in sectors of the current activity entry, not including the activity header length. Words 03 and 04 Timestamp from the creation of this activity entry. Word 05 S1 Activity-id (from ER FORK$); 0, if none. S2-S6 Not used. Word 06 Not used. Word 07 H1 Not used. H2 Pointer to the current entry on the return control stack (RCS). Word 010 Virtual address of this activity’s RCS. Word 011 Virtual address of the control block. Words 012-021 Contents of the jump history stack (JHS) buffer at the time of the interrupt. Words 022-0157 Contingency packet for this activity. Word 022 H1 Version number of packet. S4 Contingency flags. C–38

7830 7402–014

Additional Programming Information

S5 Previous return action. S6 Contingency state. Word 023 Contingency status. Word 024 Contingency descriptor. Word 025 H1 Contingency status. S4 Error type. S5 Error code. S6 Contingency type. Word 026 Auxiliary status. Word 027 H1 Not used. H2 Bank identifier. Word 030 H1 Bank type.

7830 7402–014

C–39

Additional Programming Information

H2 Base algorithm phase. Word 031 H1 Interface specification. H2 Base register. Word 032 Data. Words 033-035 Status words. Words 036-041 Data. Word 042 Access privilege. Word 043 S1 Not used. S2 IP privilege. S3 Address translation mode. H2 Base register. Word 044 Operand address. Word 045 Executing instruction.

C–40

7830 7402–014

Additional Programming Information

Word 046 IP conditions (rightmost 11 bits). Words 047-065 Base registers. Words 066-0145 General registers. Word 0146 RCS status. Word 0147 H1 RCS flags. H2 Function. Word 0150 H1 Not used. H2 RCS offset. Words 0151-0154 Not used. Word 0155 Contingency routine data. Word 0156 Return action. Word 0157 Virtual address of the original contingency.

7830 7402–014

C–41

Additional Programming Information

C.6.4. Bank Entry A bank entry contains information about the activity’s level 2 and 3 banks and their contents. There may be multiple bank entries for each activity entry. Each bank entry consists of a bank entry header and bank text and starts on a sector boundary. The bank header entry contains the following fields: Word 00 H1 Level and BDI of the bank. H2 Not used. Word 01 Size in words of the entire bank entry; this includes the bank header and text but does not include any gaps to round to the next sector boundary. Word 02 Sector-relative file address of the next bank entry; this address is on a sector boundary; value is 0 if there are no more bank entries for this activity. Words 03-010 Bank description. Word 011 Relative file address of the start of the bank text.

C–42

7830 7402–014

Appendix D Quick Reference for the FCSS Primitive The FCSS TIP primitive has many functions available. For each individual function some requirements can vary, including the use of each parameter, the number of parameters required, the security privileges needed, and the content of the user-provided buffer. Table D-1 provides a summary of all the variables associated with each of the FCSS functions based on the detailed descriptions of each function call provided in subsection 3.5. A general FCSS primitive call looks like this: CALL FCSS(p1, p2, p3, p4, p5, p6, p7) Where: p1 = function p2 = return type p3 = user buffer address p4 = TIP file number p5 = word count p6 = record number or Freespace record key p7 = buffer size All requests must specify p1 through p3. Use of p4 through p7 is function dependent. The user buffer (from p3) must always contain at least a 3-word status area. Some functions require that the status buffer be followed by an additional input or output data area. In the table, if a field is required for the specified function, the table shows a check mark in that column. If the field is used for specification of something other than the general FCSS primitive call (above) or column heading shows, then a description of the field’s usage is in the column. If the field is not required for the specified function, the table shows n/a (not applicable) in that column.

7830 7402–014

D–1

Quick Reference for the FCSS Primitive

AD

22

Write a record to the audit trail. The TIP file must be recoverable, and program execution must begin in a recoverable program step. Default AG = 1.

1,3

Status only







N/A




None

Security File Access

Securitiy Privileges Needed

Buffer Size

Record #/Key

Word Count

User Buffer Content

File Number

FCSS Primitive Function

Status Buffer

Return Types

Detailed Operation

Value

Function

Table D-1

None

Audit Trail #

AL *

27

Allocate a Freespace record. A lock is automatically created for the allocated area. Where feasible, use functions AN or AW instead of AL. Note that an allocated but unwritten Freespace record is not recoverable by Freespace recovery.

1,2,3




Status and FS record key







N/A




SSMHFSCR Write EATE or SSMHFSAC CESS

AN *

31

Allocate a Freespace record, lock it, write to it and unlock the area following the data transfer.

1,2,3




Status and FS record key







N/A




SSMHFSCR Write EATE or SMHFSAC CESS

AP *

29

Allocate a specific Freespace record.

1,2,3




Status only













SSMHFSCR Write EATE or SMHFSAC CESS

1




Status and input data




N/A

N/A




SSMHFSCR Write EATE or SSMHFSAC CESS

Note: Due to the number of I/O requests that may be needed to satisfy this function, excessive use may affect system performance. AS

D–2

8

Create a TIP scratch or temporary file, or associate a device index with a TIP/Exec scratch or temporary file.

7830 7402–014

Quick Reference for the FCSS Primitive

Security File Access

Securitiy Privileges Needed

Buffer Size

Record #/Key

Word Count

User Buffer Content

File Number

FCSS Primitive Function

Status Buffer

Return Types

Detailed Operation

Value

Function

Table D-1

AW * 28

Allocate a Freespace record, lock it, write to it, and retain the lock on the area following the data transfer.

1,2,3




Status, FS record key, and data to write







N/A




SSMHFSCR Write EATE or SSMHFSAC CESS

CG ** 12

Change the characteristics of a permanent TIP file.

1




Status and input data




N/A

N/A

N/A

SSMHFSCR Write EATE

CK

7

Check for completion 1,3 of any requests the program has issued with the immediate return specification. It waits only for the completion of FCSS I/O.




Status only

N/A

N/A

N/A

N/A

None

CP

20

1,3 Force a checkpoint to occur for any volatile or checkpoint TCDBF. If the target is a checkpoint TCDBF, a new timestamp is acquired and placed in the header record. If the target is a recoverable checkpoint TCDBF, the second timestamp (earliest active, ready, or commit-in-progress step with checkpoint TCDBF updates) is acquired and placed in the header record.




Status only




N/A

N/A

N/A

SSMHFSCR Write EATE or SSMHFSAC CESS

7830 7402–014

None

D–3

Quick Reference for the FCSS Primitive

Security File Access

Securitiy Privileges Needed

Buffer Size

Record #/Key

Word Count

User Buffer Content

File Number

FCSS Primitive Function

Status Buffer

Return Types

Detailed Operation

Value

Function

Table D-1

FL

35

Locks a file from 1,3 access by others. The caller can access the file with the lock up using the RD and the WW functions. Attempts by other activities to access the file are rejected while the file lock is in effect. FL is not allowed on systems with an XPC–L or files specifying RLPLCK=P.




Status only




N/A

N/A

N/A

SSMHFSCR Read EATE or SSMHFSAC CESS

FR

36

Locks a file from write access by others. The caller can access the file with the lock up using the RD and the WW functions. Other activities can access the file for reads (RD) while the file lock is in effect. FR is not allowed on systems with an XPC–L or files specifying RLPLCK=P.

1,3




Status only




N/A

N/A

N/A

SSMHFSCR Read EATE or SSMHFSAC CESS

LF

10

List the characteristics of a TIP file.

1




Status and returned file data




N/A

N/A

N/A

None

LK

34

Lock record(s) in a TIP 1,2,3, file. If any of the 4,5,6 requested records have been locked by another activity, the caller is suspended until the lock can be granted for return types 1-3. For return types 4-6, error 031 is given.




Status only













SSMHFSCR Read EATE or SSMHFSAC CESS

D–4

None

7830 7402–014

Quick Reference for the FCSS Primitive

Security File Access

Securitiy Privileges Needed

Buffer Size

Record #/Key

Word Count

User Buffer Content

File Number

FCSS Primitive Function

Status Buffer

Return Types

Detailed Operation

Value

Function

Table D-1

RD

1

Read record(s). No record locking is performed or checked on this request. The word count need not be a multiple of the record size.

1,2,3




Status and read data













SSMHFSCR Read EATE or SSMHGSA CCESS

RR

1

Exact same actions as RD function. Function unique to COBOL.

1,2,3




Status and read data













SSMHFSCR Read EATE or SSMHFSAC CESS

RE

13

Release a permanent, 1 temporary, or scratch file. This function is rejected if the file is not completely inactive.




Status and input data




N/A

N/A

N/A

SSMHFSCR Write EATE

RL

2

1,2,3, Create a lock on the referenced record(s) 4,5,6 and read them. If any of the requested records have been locked by another activity, the calling activity is suspended until the lock can be granted for return types 1-3. For return types 4- 6, error 031 is given.




Status and read data













SSMHFSCR Read EATE or SSMHGSA CCESS

The word count must be a multiple of the record size. Whether or not the read succeeds, the lock is retained. For Freespace files, if a 0 word count is specified, the record length from the given record key is used.

7830 7402–014

D–5

Quick Reference for the FCSS Primitive

Security File Access

Securitiy Privileges Needed

Buffer Size

Record #/Key

Word Count

User Buffer Content

File Number

FCSS Primitive Function

Status Buffer

Return Types

Detailed Operation

Value

Function

Table D-1

RU

30

Unlock a record and 1,3 return it to the system as a free record. Record release requires that the record be locked before releasing.




Status only













SSMHFSCR Write EATE or SSMHFSAC CESS

RV

9

Reserve a permanent TIP file in a TIP/EXEC file

1




Status and input data

N/A

N/A

N/A

N/A

SSMHFSCR Write EATE

SF

18

Save file updates that are staged in cache disk for the Exec file that contains the specified TIP file.

1




Status only




N/A

N/A

N/A

SSMHFSCR Write EATE

UA

3

Unlock all recoverable file and record locks. Locks currently owned by the activity are flagged “to-be-released” upon the occurrence of a commit with step advance.

1,3




Status only

N/A

N/A

N/A

N/A

None

None

UN

5

1,3 Unlock file and record locks. If either a record or file lock with the matching TIP file output packet exists for the calling activity, only the specified record lock is released. If there is no lock with a matching packet, action is determined by the J-option setting:




Status only

N/A

N/A

N/A

N/A

None

None

J-option clear - all locks for the activity are released. J-option set - all locks are retained.

D–6

7830 7402–014

Quick Reference for the FCSS Primitive

WL *

26

WR * 4

Security File Access

Securitiy Privileges Needed

Buffer Size

Record #/Key

Word Count

File Number

User Buffer Content

FCSS Primitive Function

Status Buffer

Return Types

Detailed Operation

Value

Function

Table D-1

Write record(s) and keep locked. Used on permanent files only.

1,2,3




Status and
data to write










SSMHFSCR Write EATE or SSMHFSAC CESS

Write record(s) and release lock(s). Your program must have locked the record(s) previously. If the write errors the lock is still released.

1,2,3




Status and
data to write










SSMHFSCR Write EATE or SSMHGSA CCESS

Write record(s) without 1,2,3 checking for a lock. The word count need not be a multiple of the record size.




Status and
data to write










SSMHFSCR Write EATE or SSMHFSAC CESS

For Freespace files, if a 0 word count is specified, the record length from the given record key is used. For temporary or scratch files, the word count need not be a multiple of the record size. WW

25

For permanent files, the function can be used only if the WW_allowed option is set in the file’s directory, or if the program has already locked the area being referenced with the FL, FR, RL or LK function. For temporary or scratch files, the function is always available.

7830 7402–014

D–7

Quick Reference for the FCSS Primitive

* For these functions, the record key (if allocated or reallocated) is returned in word 2 of the output buffer. WR and WL operations performed on Freespace files may result in reallocation of the supplied record if the word count forces expansion or contraction. Therefore, word 2 must be checked to see if reallocation occurred. ** CG is unique in that a required input is expected in the output buffer. Word 2 of the buffer contains a Bit Mask.

D–8

7830 7402–014

Index A abnormal program termination, 2-20 ABORT$/EABT$ contingency routine, 2-21 absolute element AFCB templates and, 8-3 block transfer load and, 6-7 Collector, 1-5 diagnostic files, 9-9, 9-11 dynamic allocator, 7-3 TPUR processing of, 7-15 absolute timing, 2-17 ACCEPT command, 7-14 access control word (ACW), 7-15, 8-7, C-14 accessing FCSS files, 3-4 accessing Freespace files, 3-6 ACCTON parameter, 8-15 activity work area (AWA), 7-2 activity-local stack (ALS), 8-19 ACW, See access control word AD FCSS function, 3-14 address handling COBOL, 8-10 AFCB, See alternate file common banks AL FCSS function, 3-14, 4-6 allocation permanent TIP file, B-6 training file, 9-3 ALS, See activity-local stack alternate file common banks (AFCB) HVTIP programs, 7-3, 7-15 referencing, 8-3, 8-4 Alternate library cycle, 7-11 alternate program modes, 9-1 AN FCSS function, 3-15, 4-6 AP FCSS function, 3-15, 4-6 application group diagnostic files and, 9-12 failure, 3-7 Freespace file access, 3-6 7830 7402–014

recovery, 1-4, 2-3, 4-1, 4-5 TIP Session Control, 8-16 XTC, 3-8, B-8 APRINT$, 8-14 APRTCN$, 8-14 AS FCSS function, 3-17 ASCII FORTRAN, See FORTRAN ASCII HVTIP primitives, 7-14 ASYSDF procedure, 8-1 audit trail, 1-8, 4-5, B-9, B-13 automatic storage FORTRAN, 7-13 AW FCSS function, 3-19, 4-6 AWA, See activity work area

B bank descriptor index (BDI), 7-15, 7-16 basic mode alternate modes, 9-2 changing terminal mode, 9-2 COMPOOL, 1-3 diagnostic files, 9-7, 9-9 FOXER support, 8-23 HVTIP, 7-4, 7-5, 7-10, 7-11 programs in, 1-5 RTRANO, 2-14 set and cancel program modes, 9-2 TCDBF and, 1-4, 3-32 TIPDIAG$ file, 9-8 TPLOG primitive, 8-22 batch-connected programs ABORT$/EABT$, 2-21 activating, 2-4 collection of, 8-3 diagnostic files, 9-8, 9-10, C-37 DISCON primitive, 2-5 execution options, 9-2 flagbox manipulation, 8-23 initialization of, 2-1 non-TIP, 1-2

Index–1

Index

SEXEM dump, 9-9 BDICALL$, 7-5 bit maps, 3-5, B-13 BITS function, 5-9, 5-12 block transfer loading description, 6-7 flagbox bit, 8-24 reentrant FORTRAN program, 7-14, 8-9 security restrictions, 8-21 BRKPT$ PRINT$, 8-15 BTLOADING flagbox bit, 6-7, 8-18 Business Information Server files, 3-9

C CALL interfaces HVTIP, 7-10 CALL$, 7-5, 7-6, C-25 CANCEL$$, 2-9 CDATAC primitive, 2-7 CDATCR primitive, 2-8 CERU$, 7-5 CG function FCSS, 2-4, B-10 CID V program option, 2-14 CK FCSS function, 3-19 CLOCTE, 8-10 CMPBUF CDATAC primitive, 2-7 CDATCR primitive, 2-8 CMPDEF FORTRAN procedure element, C-1 CMS, See Communications Management System COBKON primitive, 5-10, 5-12, C-9 COBOL address manipulation, 8-10 calling sequence, 8-12 COBKON primitive, 5-12 COBSEC primitive, 5-7, 5-12, 5-13 CONECT request format, 2-2 CRELOG request format, 2-10 CSTLOG request format, 2-9 CSTOVR request format, 2-10 Data Division, 8-2 definition procedures, 8-2 DISCON request formats, 2-5 FOXER request format, 8-23 HVTIP programs in, 7-13, 7-14 Index–2

INITAL request format, 2-6 initializing D-bank, 7-4 KONS function request, 5-2 KONS interfaces, C-9 library elements, 8-6 MCORE$ and, C-11 Procedure Division, 7-14 PROCESS command, 7-14 RD reserved word, 3-27 RTOUTP request format, 2-13 RTRANO request format, 2-14 RTRANU request format, 2-12 RTSCHD request format, 2-11 SEQRD function, 5-11 SREAD function, 5-12 subroutine parameters, 8-10 TERMN8 request format, 2-7 TIMABS request format, 2-17 TIMDEL request format, 2-20 TIMREL request format, 2-17 transaction programs in, 8-9 UNLOK function, 5-13 COBSEC primitive, 5-7, 5-12, 5-13, C-10 collecting a program reentrant program, 8-4 self-destructive program, 8-6 self-initializing program, 8-4 Collector, 1-5, 7-8, 7-15 COMMIT primitive, 4-3, 4-7, 6-2 commit processing, 3-28, 4-2, 4-7 Communications Management System (CMS) alternate modes, 9-2 device handler, C-3 function key input, C-3 message processing, C-5 queuing priority, C-6 COMPOOL basic mode, 1-3 CDATAC primitive, 2-7 CSTLOG, 2-9 ERTERM, 2-20 INITAL primitive, 2-6 intitializing, 2-6 message parameter area (MPA), C-1, C-5, C-6, C-7 messsage handler primitives, C-1 MPA DID field, C-3 mutiple initialization, 6-3 program restart, 6-8 program sticking, 6-9 RTOUTP, 2-14 RTRANO, 2-14 7830 7402–014

Index

RTRANU, 2-12 SLOP table, C-23, C-26 off, 2-11 user-to-user pass-off, 2-11 VALTAB entry, 1-9 XTC, 2-1, 3-10 CONECT primitive, 2-1, 4-1, 4-5, 4-6 configuration parameters FCMXLK, 3-3 general description, 1-5 KONS, 5-4 password, 5-2 RESIDUE_CLEAR, 8-17, 8-20 system, 1-7 TFPMAX, B-6, C-13, C-18, C-19 TIPMIN, 2-15, 2-18, 2-19, 5-4 TIPTPS, 6-5 connecting a program to TIP, 2-1 control bank HVTIP, 7-16 COPY command, 7-15 COUNT CDATAC primitive, 2-8 CDATCR primitive, 2-8 CRELOG primitive, 2-4, 2-10 CSF$ control statements, 8-14 CSTLOG primitive, 2-9 CSTOVR primitive, 2-10 CUPDAT KONS function, 5-7

D D$CLOSE, 4-7 DA, See dynamic allocator Data Division COBOL, 8-2 DATA=AUTO statement, 7-13 DATA=REUSE statement, 7-13 DATE$, 7-13 day queue-id, 2-17 D-bank HVTIP, 7-16 initialization segments, 7-17 residue, 8-19 RSEG usage, 7-18 SEG usage, 7-17 DBANK Collector directive, 7-16 DEBUGXX flagbox bit, 9-11 deferred updates, 4-1 defining Freespace parameters, 3-5 7830 7402–014

definition procedures COBOL, 8-2 FORTRAN, 8-2 MASM, 8-3 delete execution option indicators, 8-26 delete TIMER entry, 2-19 demand-connected programs activity entry, C-37 diagnostic files, 9-9 execution options, 9-2 non-TIP, 1-2 density map, 3-6 DEPART, 4-7 Depart request, 6-3 DIAG$, 9-8, 9-10 @RUN statement, 9-9 absolute elements, 9-11 activity entry, C-37 description, 9-7 extended mode format, C-27 security attributes, 9-9 ZOOMs, 9-11 diagnostic files activity entry, C-37 extended mode, 9-12 extended mode format, C-27 general description, 9-7 preparation, 9-9, 9-10 DISCON primitive, 2-5, 4-1 disconnecting a program from TIP, 2-5 DISPLAY command, 7-14 Display Processing System (DPS 2200), 9-6, C-23 DM$IO, C-17, C-19 DM$IOW, C-13, C-19 DM$WT, C-17 DMAP, 3-6 DPS 2200, See Display Processing System duplex files permanent TIP file, 3-1 TIP File Control functions for, 3-4 UDS/TIP interface, 3-2 XTC, B-6 dynamic allocator (DA), 7-3, C-11 dynamic bank, 7-4

E ERTERM primitive, 2-20 Exec dynamic allocator complex, 7-15

Index–3

Index

Executive requests, See TIP File Control ER functions APRINT$, 8-14 APRTCN$, 8-14 CALL$, 7-5, 7-6, 7-8, C-25 contract memory, C-10 CSF$, 8-14, 8-15 DATE$, 7-13 expand memory, C-10 FRSTD$, 7-12 LASTD$, 7-12 LCORE$, C-11 LEVEL$, 6-3 MCORE$, C-11 PRINT$, 8-14 PRTCN$, 8-14 RTN$, 7-5, 7-8, 7-9, C-25 SYMB$, 8-14 symbiont, 8-14 TCORE$, C-12 TDATE$, 7-13 UK$ONS, 9-5, 9-6 WALL$, 3-19, C-17 WANY$, C-17 XFR$, 7-5, 7-8 XRS$, 7-5, 7-9 EXEM, C-6 EXPOOL, 3-3, 6-9 extend or overlay output message, 2-10 extended mode access to TCDBFs, 3-32 activity-local stack, 8-19 call interfaces HVTIP, 7-10 calling UCS COBOL primitives, 8-9 COBOL definition procedure, 8-2 compiling and linking, 8-6 CONECT request parameters, 2-2 CONECT-DISCON pairs, 2-1 diagnostic files DIAG$, 9-9 format, 9-12, C-27 general description, 9-7 list, 9-7 HVTIP, 7-3 initializing D-bank, 7-11 Message Control Bank (MCB), 1-3 program activity contingency, 9-9 reading TIPDIAG$, 9-8 TCDBF and, 1-4 TIP error history file, 9-8 TIP File Control, 3-2 Index–4

Extended Processing Complex (XPC), 3-7, 3-8 Extended Transaction Capacity (XTC) alternate program modes, 9-7 application groups, 3-8 description, 3-7 duplex files, B-6 Extended Processing Complex (XPC), 3-8 FCSS directories in, 3-7 FCSS LF function, 3-21 file locking, 3-9 HVTIP program libraries, 7-4 Integrated Recovery, 3-9 lock type on RV function, B-8 MCB and COMPOOL, 2-1 RTPS program support, 6-4 shared TIP files, 3-2, 3-9 support for KONS, 5-1 TIMER, 2-15 Extended Transaction Processing Architecture (XTPA), 1-4 external subroutine calls, 7-10

F fast-load zoom, 8-7 FCMXLK, 3-3 FCREG primitive, B-4 FCSS access, 3-4 AD function, 3-14 AL function, 3-14, 4-6 AN function, 3-15, 4-6 AP function, 3-15, 4-6 AS function, 3-17 AW function, 3-19, 4-6 buffer address parameter, 3-11 buffer size parameter, 3-12 CG function, 2-4, B-10 CK function, 3-19 Extended Transaction Capacity, 3-7 fixed files, 3-2, B-13 FL function, 3-20, 4-7 FR function, 3-21 Freespace files, 3-5 LF function, 3-21 LK function, 3-26 nonrecoverable steps, 4-7 RD function, 3-4, 3-26, 4-7 RE function, B-9 record number/key parameter, 3-12 7830 7402–014

Index

recoverable steps, 4-6 request format, 3-13 return type parameter, 3-11 RL function, 3-4, 3-27, 4-6 RR function, 3-27 RU function, 3-28, 4-6 RV function, B-6 SF function, 3-28 test mode, 9-3 TIP file number parameter, 3-12 UA function, 3-28 UN function, 2-4, 3-29, 4-6 WL function, 3-29, 4-6 word count parameter, 3-12 WR function, 3-4, 3-30, 4-6 WW function, 3-31 FCSS fixed files, 3-2, 3-29, B-13 FCSS primitive call, D-1 FCSS TIP primitive, D-1 FIELD subroutine, C-8 File Control Superstructure, See FCSS file locking commit processing and, 4-7 file locks, 3-9, 3-18, 3-20, 3-28, 3-29 FILLWR KONS function, 5-7 FL FCSS function, 3-20, 4-7 flagbox, 8-23 flagbox bit-name parameter, 8-24 flagbox option sticking, 8-17 FLBOX primitive, 8-23, 8-25 FORMAT statement, 7-14 FORTRAN automatic storage feature of, 7-13 bit extraction, C-8 BITS function, 5-12 block transfer loading, 8-9 CONECT request format, 2-2 CRELOG request format, 2-10 CSTLOG request format, 2-9 CSTOVR request format, 2-10 definition procedures, 8-2 DISCON request format, 2-5 extended mode, 8-6 FIELD routine, C-8 FOXER request format, 8-23 HVTIP programs in, 7-13 INITAL request format, 2-6 initializing D-bank, 7-4 KONS function request, 5-2 Locate subroutine, C-9 7830 7402–014

message parameter area, C-1 restrictions on, 8-8 RTOUTP request format, 2-13 RTRANO request format, 2-14 RTRANU request format, 2-12 RTSCHD request format, 2-11 TERMN8 request format, 2-7 TIMABS request format, 2-17 TIMDEL request format, 2-19 TIMREL request format, 2-16 FOXER primitive, 2-4, 8-23 FR FCSS function, 3-21 Free request, 6-3 Freespace files access, 3-6 bit maps, 3-5 CG function, B-13 converting FCSS files to, 3-6 creation of, 3-2 density map (DMAP), 3-6 description, 3-3 duplex files, 3-5 index table, 3-6 organization, 3-5 parameters, 3-5 record keys, 3-6 record type, 3-5 recoverable steps, 4-6 unlock and release, 3-28 use of, 3-5 FREIPS, 3-6, 9-3, B-4 FRSTD$, 7-12

H high-level languages MINGAP and, 7-15 high-volume transaction system (HVTS), C-4, C-5 HV_CALL_SUB, 7-10 HV_CANCEL_RS, 7-10 HV_XFR_CANCL, 7-10 HV_XFR_SUB, 7-10 HVTIP alternate file common bank (AFCB), 8-3 Collector directives, 7-15 control bank, 7-16 control transfer, 7-5, 7-10 D-bank, 7-16 D-bank initialization, 7-16 Index–5

Index

extended mode diagnostic file, C-30 general description, 1-5 I-bank, 7-15, 8-20 initial control program (ICP), 7-2, 7-11 KONS test/training mode and, 9-6 library files, 3-8 MASM, 8-13 next message feature, 6-2 nonconfigured common banks (NCCB), 8-3 primitives, 7-14 print banner, 8-15 program errors, 8-20 program restart, 6-8 program sticking, 6-8 program structure, 7-2 programs in, 7-1 security, 8-20 shared TIP database, 3-10 SLOP table, C-25 subprograms, 7-1 HVTS, See high-volume time sharing

I I-bank, 7-15, 8-20 IBANK statement, 7-15 illegal Executive requests, 8-14 Impart request, 6-3 Impart/Depart sequence, 6-3 INITAL primitive general description, 2-6 memory expansion and, C-12 multiple, 6-2, 6-4, 8-17, 8-18, 8-19, 8-21 TIMER request, 2-15 initial control program (ICP), 7-16 description, 7-11 extended mode, 7-3 I-bank, 7-5 passing D-bank to subprograms, 7-1 program structure, 7-2 VALTAB entries, 7-11 initialization segment loader, 7-18 initialize D-bank HVTIP, 7-16 initiate absolute timing, 2-17 initiate relative timing, 2-16 INPREL$$, 2-7 input messages reading, 2-7 insert execution option indicators, 8-27 Index–6

Integrated Recovery CG function, B-13 COMMIT primitive, 4-3 commit processing, 4-2, 4-7 Extended Transaction Capacity, 3-9 general description, 1-4 multiple audit trail sources, B-13 overview, 4-1 program steps, 4-6, 4-7 recoverable updates, 4-5 ROLLBACK primitive, 4-4 Integrated Recovery Utility (IRU), 3-7, 4-2 IOW$, 9-6 IRU, See Integrated Recovery Utility

J jump (J) instruction MASM, 8-13 jump history stack (JHS), C-38 jump instruction direct, 8-3

K KONS alternate modes, 9-5 COBOL interfaces, C-9 CUPDAT function, 5-7 description, 5-1 FILLWR function, 5-7 function requests, 5-2 KRDLK function, 5-7 KREAD function, 5-8 KWRITE function, 5-8 KWRKP function, 5-8 KWRUN function, 5-9 LUPDAT function, 5-9 MSREAD function, 5-9 parameters for requests, 5-2 primitive, 5-2 SCATRD function, 5-10 security directory, 2-4, 5-2 SEQSRD function, 5-11 SERCHR function, 5-11 shared TIP database and, 3-10 SREAD function, 5-12 SUPDAT function, 5-12 SWRITE function, 5-13 system KONS, 5-1 7830 7402–014

Index

test/training mode HVTIP, 9-6 training files, 9-6 UNLOCK function, 5-13 user, 5-2 KONS TIP system file, 5-1 KONSEC configuration parameter, 5-4 KONSFL configuration parameter, 5-4 KONSPW parameter, 9-6 KONU3L configuration parameter, 5-4 KRDLK KONS function, 5-7 KREAD KONS function, 5-8 KSECNB configuration parameter, 5-4 KWRITE KONS function, 5-8 KWRKP KONS function, 5-8 KWRUN KONS function, 5-9

L label typing, 8-9 LASTD$, 7-12 LCORE$, C-11 LEVEL$, 6-3 LF FCSS function, 3-21 library cycles, 7-11 Linking System, 8-7, C-30 LK FCSS function, 3-26 LMJ instruction MASM, 8-13 local TIP FCSS directory, 3-7, 3-8, 3-9, 5-1 local TIP file directory listing, 3-21 Locate subroutine, C-9 logbox, 8-23 logging requests alternate modes, 9-3 long recovery, 4-1, B-13 LUPDAT KONS function, 5-9

M Main library cycle, 7-11 7830 7402–014

MASM, 8-14 CONECT request format, 2-2 CRELOG request format, 2-10 CSTLOG request format, 2-9 CSTOVR request format, 2-10 definition procedures, 8-3 DISCON request format, 2-5 FOXER primitive request format, 8-23 FOXER request format, 8-23 HVTIP programs in, 7-13 INITAL request format, 2-6 initializing D-bank, 7-4 KONS function request, 5-2 reference to parameters, 8-14 RTOUTP request format, 2-13 RTRANO request format, 2-14 RTRANU request format, 2-12 RTSCHD request format, 2-11 TERMN8 request format, 2-7 TIMABS request format, 2-17 TIMDEL request format, 2-20 TIMREL request format, 2-17 transaction programs in, 8-13 master configuration table (MCT), 7-13 MCB, See Message Control Bank MCORE$, C-11 MCT, See master configuration table memory, C-12 MEMORY 3 MODULES phrase, 7-14 Message Control Bank (MCB) alternate modes, 9-1, 9-7 CANCEL$$ function, 2-9 extended mode, 1-3 initialization function, 2-1 INPREL$$ function, 2-7 message handler primitives, C-1 program restart, 6-8 program sticking, 6-9 recoverable programs, 2-3 RECV$$ function, 2-7 RTRANO, 2-14 RTRANU, 2-12 SEND$$ function, 2-9 SLOP table, C-23 termination function, 2-1 TRINIT$$, 2-6 user-to-user pass-off, 2-11 VALTAB entry, 1-9 XTC, 2-1, 3-10 message parameter area (MPA) alternate program mode, 9-1 COMPOOL, C-2 COMPOOL version, C-1 Index–7

Index

DID field, C-3 format, C-1 MCB, C-1, C-2 pass--off, 2-12 program mode cell, 9-2 RTRANO, 2-14 RTRANU, 2-11, 2-13 RTSCHD, 2-11 test mode programs, 9-4 transaction code, 2-11 message pass-off, 2-11 MESSAGE WAIT keyin, C-3 MESSAGE WAITING indicator, C-3 message-handling, 2-7, 6-2 Meta-Assembler, See MASM MHFS, See Multi-Host File Sharing feature MINGAP, 7-15 MPA, See message parameter area MSREAD, 5-9, 9-6 Multi-Host File Sharing (MHFS) feature, 3-7 multi-input transactions, 8-17 multiple initialization, 6-2

N NCCB, See nonconfigured common banks next message request feature, 6-2 nonconfigured common banks (NCCB), 7-3, 7-15, 8-3 nonrecoverable program steps, 4-7

O OBJECT-COMPUTER clause, 7-14 online batch programs collection of, 8-3 commit points, 4-3 diagnostic files, 9-7, 9-9, 9-10 DISCON primitive, 2-5 general description, 1-5 initialization of, 2-1 multiple inputs, 8-17 output message MPA read, 2-13, 2-14 overlay or extend, 2-10 primitives, 2-9 release, 2-10 storing, 2-9 overlay or extend output message, 2-10

Index–8

P PADS, See Programmers Advanced Debugging System parameter addressing MASM, 8-14 partial DIDs DCT 1000, C-6 partial-word fields, 8-11 passing program mode, 9-2 password configuration parameter, 5-2 PCT, See program control table permanent file allocating, B-6 changing characteristics of, B-10 defined, 3-1 file locking, 3-20 listing characteristics of, 3-21 number allowed, 1-7 record locks, 3-3 releasing, B-9 reserving, B-6 training mode, 9-3 WW function and, 3-31 PID, See position identifier PMD, See PostMortem Dump processor POC, See power-on confidence test position identifier (PID), C-4, C-5, C-6 description, 2-1 input terminal, C-24 output device position, C-7 remote input device, C-5 PostMortem Dump (PMD) processor, 9-7 power-on confidence test (POC), C-4 primitives CDATAC, 2-7, 2-8 COBKON, 5-10 COMMIT, 4-3 CONECT, 2-1 CRELOG, 2-4, 2-10 CSTLOG, 2-9 CSTOVR, 2-10 DISCON, 2-5 ERTERM, 2-20 execution option indicator, 8-25 FCREG, B-4 FLBOX, 8-25 FOXER, 2-4, 8-23 HVTIP, 7-14 INITAL, 2-6 KONS, 5-2 7830 7402–014

Index

message-handling, 2-7 output messages, 2-9 requests, 8-13 ROLLBACK, 4-4 RTOUTP, 2-13 RTPSD, 6-6 RTPSI, 6-5 RTRANO, 2-14 RTRANU, 2-12 RTSCHD, 2-11 TERMN8, 2-7 TIMABS, 2-17 TIMDEL, 2-19 TIMER, 2-16 TIMREL, 2-16 TIMUPA, 2-19 TIMUPR, 2-18 TIP library, 8-3 TPLOG, 8-22 UOPAND, 2-4, 8-26, 9-2 UOPGET, 8-25 UOPTOR, 2-4, 6-9, 8-27, 9-2 PRINT$, 8-14, 8-15 PRINT$ file residue, 8-19 program banks HVTIP, 7-4 program control table (PCT), C-21, C-27, See SLOP table program libraries HVTIP, 7-4 program mode of operation, 9-2 program number scheduling by, 2-13 program restart, 6-7, 8-17 program status (STATUS) field, 1-9, 8-16 program step defined, 4-1 recovery information, 4-6 Programmers Advanced Debugging System (PADS), 9-7, 9-12 PRTCN$, 8-14

Q QUAL statement, 3-21 quarter-word mode, 8-15

7830 7402–014

R RD FCSS function, 3-18, 3-20, 3-21, 3-26, 4-7, 9-3 RE FCSS function, B-9 reading input messages, 2-7 REC VALTAB keyword, 4-7 record lock processor (RLP), B-8 record locks, 3-26, 3-27, 3-28, 3-29 FCSS fixed files, 3-12 Freespace files, 3-12 general description, 3-3 XTC, 3-7 recoverable program steps, 4-6 recoverable updates, 4-5 RECV$$, 2-7 reentrant programs block transfer loading, 6-7, 8-9 FORTRAN, 7-14 general description, 1-5, 8-4 loading, 8-4 MASM, 7-13 next message feature, 6-2 program restart, 6-8 restrictions, 8-5 sticking, 6-8 register use MASM, 8-14 relative time, 2-16, 2-17 release an output message, 2-10 remote symbiont interface (RSI), C-4, C-5 Resident Transaction Program System (RTPS), 6-4 description, 8-18 multiple INITAL, 6-4 restrictions, 8-21 shared TIP database and, 3-10 residue activity-local stack (ALS), 8-19 D-bank, 8-19 general register set (GRS), 8-19 reentrant I-bank, 8-20 TIP, 8-19 RESIDUE_CLEAR, 8-17, 8-20, 8-21 restrictions TIP 2200/XPA, 8-20 retrieve execution option indicators, 8-25 RL Index–9

Index

FCSS function, 3-27, 4-6, 9-3 rollback, 2-21, 4-1 ROLLBACK primitive, 4-4 ROUTING output queue, 2-13 RPINIT utility, 6-3 RR FCSS function, 3-27 RSEG, 7-14, 7-16, 7-17, 7-18 RSEGLOAD, 7-18 RTN$, 7-5, 7-9, C-25 RTOUTP primitive, 2-13 RTPS, See Resident Transaction Program System RTPSD primitive, 6-6 RTPSI primitive, 6-5 RTRANO primitive, 2-14 RTRANU primitive, 2-12 RTSCHD primitive, 2-11 RU FCSS function, 3-28, 4-6 RV function FCSS, B-6

S SCATRD KONS function, 5-10 scheduling programs, 2-15 scratch files access, 3-4 AS function, 3-18 listing characteristics of, 3-21 record locks, 3-3 setup, 1-7, 3-2 shared database, 3-9 WR function, 3-31 Security Option 3, 8-17, 8-19, 8-21 SEG, 7-16, 7-17 segment load table, 7-16 selfdestructive programs general description, 1-5 self-destructive programs collection, 8-6 self-initializing programs, 6-1, 6-8 block transfer loading, 6-7 collection, 8-6 general description, 1-5, 8-4 next message feature, 6-2 program sticking, 6-8 SEND$$, 2-9 SENTRY CONTROL, 9-9 Index–10

SEQSRD (sequential search read), 9-6 SEQSRD KONS function, 5-11 SERCHR KONS function, 5-11 SERCHR (search read) KONS, 9-6 SEXEM dump, 9-7 SF FCSS function, 3-28 shared TIP database, 3-9 shared TIP file directory KONS, 5-1 listing, 3-21 short recovery, 4-1 simplex files, 3-1 single-input programs, 8-17 SLOP control word, C-27 SLOP table, 2-12, 2-20, 8-25, C-21 SREAD KONS function, 5-12 standard TIP programs, 1-5 standard-load zoom, 8-7 START CDATAC primitive, 2-8 CDATCR primitive, 2-8 start absolute timing, 2-17 start relative timing, 2-16 static banks, 7-4 sticking, 6-3, 6-8, 6-9, 8-21 sticking flagbox option, 8-17 Store Location and Jump Instruction MASM programs and, 7-13 storing output messages, 2-9 subroutine parameters, 8-10 SUPDAT KONS function, 5-12 switching level VALTAB, 6-3 switching modes HVTIP, 7-10 SWRITE KONS function, 5-13 SYMB$, 8-14 symbiont ERs, 8-14 SYSDEF procedure, 5-4, 8-1 system KONS, 5-1, 9-6 system parameters TIP, 1-7

7830 7402–014

Index

T tape logging, 2-4, 8-22 TCDBF accessing, 3-32 comparison to KONS, 5-1 defined, 3-32 definition, 1-4 record lock processing, 3-8 shared database and, 3-9 XTC, 3-10 TCDIO primitive, 3-32 TCORE$, C-12 TDATE$, 7-13 TDIAG$ procedure, 9-13 temporary files access, 3-4 AS function, 3-18 listing characteristics of, 3-21 record locks, 3-3 security attributes, 9-9 setup, 1-7, 3-2 shared database, 3-9 WR function, 3-31 terminal mode changing, 9-2 terminating the program, 2-20 TERMN8 primitive, 2-7 Test library cycle, 7-11 test mode, 2-4, 7-15, 9-1, 9-5 test/training mode, 9-1, 9-5 Test-Set (TS) instructions, 7-14 TFPMAX, B-6, C-13, C-18, C-19 TFUR, 9-3, 9-7 TIMABS primitive, 2-17 TIMDEL primitive, 2-19 TIMER control, 2-15 overview, 2-15 primitives, 2-16 queue, 2-15 shared TIP database and, 3-10 SLOP table, C-25 system minutes, 2-15 TIP Message Security, 2-15 XTC support, 2-15 timing requests alternate modes, 9-3 TIMREL primitive, 2-16 TIMUPA primitive, 2-19 TIMUPR primitive, 2-18 TIP 7830 7402–014

supported programs C2 environment, 8-20 TIP common data bank file, See TCDBF TIP error history file examining with PADS, 9-12 extended mode, 9-7, 9-8 security attributes, 9-9 ZOOMs, 9-11 TIP features security and, 8-21 TIP File Control alternatives for UDS, 3-2 description, 3-2 duplex TIP files, 3-4 error detection, C-20 file types, C-18 record locks, 3-3 UDS Control, C-12 TIP File Control ER functions DM$FAC, C-17 DM$IO, C-17 DM$IOW, C-13 DM$WT, C-17 error status codes, C-19 I/O status codes, C-19 TIP File Control Superstructure, See FCSS TIP File Security DMIO$W, C-14 duplex files and, 3-5 error message, 8-20 HVTIP and, 7-2, 8-20 multiple INITAL, 8-18 multiple initialization feature, 6-3 next message feature, 6-2 residual assignments, 8-18 system KONS, 5-1 TIP File Security feature, 6-4 TIP files duplex, See duplex files FCSS, See FCSS Freespace, See Freespace files listing, 3-21 overview, 3-1 permanent, See permanent files scratch, See scratch files temporary, See temporary files TIP flagbox options setting via FB keyins, 8-16 sticking, 8-17 TIP memory contracting, C-11, C-12 expanding, C-11 TIP Message Security Index–11

Index

TIMER, 2-15 TIP programs abnormal termination, 2-20 ALS bank residue, 8-19 block transfer loading, See block transfer loading COBOL, See COBOL D-banks, 8-19 debugging, 9-1 design, 1-5 diagnostic files for, See diagnostic files execution in alternate modes, 9-2 FORTRAN, See FORTRAN GRS residue, 8-19 HVTIP, See HVTIP I-bank residue, 8-20 initializing, 2-6 MASM, See MASM multiple INITAL, 6-2, 8-18, 8-19 overview, 2-1 parameters, 1-7 program step recovery information, 4-6 reentrant, See reentrant programs Resident Transaction Program System (RTPS), See Resident Transaction Program System restart, 8-17 retrieving input message, 2-6 reuse, 8-17, 8-21 scheduling, 2-4, 2-11, 2-15 security requirements, 8-16 self-initializing, See self-initializing programs sticking, 6-3, 6-8, 6-9, 8-17 supported in C2 environment, 8-20 system parameters, 8-1 terminating, 2-7 types, 1-5, 8-16 VALTAB record, 8-16 TIP security creating secure transaction programs, 8-16 TIP Session Control, 8-16, C-24 TIP system logging, 2-4 TIPDIAG$ file, 9-9 absolute elements, 9-11 basic mode, 9-8 CONECT primitive option, 2-4 creation of, 9-10 description of, 9-7 error contingencies, C-37 extended mode, 9-8 format, C-27 Index–12

online batch program, 9-8 security attributes, 9-9 ZOOMs, 9-11 TIPLIB$, 8-1, 8-2 TIPLOG$ procedure, 9-13 TIPMIN, 2-15 KONS function requests, 5-4 KONS location, 2-18 TIMUPA, 2-19 TIPABS primitive, 2-18 TIPTPS configuration parameter, 6-5 TIPTRACE, 2-4, 2-20, 8-24 TIPTRACE FLAGBOX bit, 9-10 TPLOG primitive, 8-22 TPSNUM MPA, C-5, C-6, C-8 scheduling programs, 2-11, 2-13 TPUR, 7-15, 7-16 absolute element, 7-4, 7-15 bank management, 7-5 initial control program, 7-11 program libraries, 7-4 TRAINFB flagbox bit, 6-9 training files allocating, 9-3 KONS, 9-6 training mode, 7-15, 9-1, 9-5 transaction code, 2-11, 7-2, 8-15, 9-12, C-7 RTRANU, 2-13 scheduling by, 2-11 VALTAB parameter, 1-7 transaction program display flagbox or logbox, 8-23 transfer interface, 7-10 transferring control to another bank, 7-7 TREG utility, B-4 TRMRG$, 2-21 TSS_CONTROL parameter, 8-15, 9-9

U UA FCSS function, 3-28 UCS Ada CONECT request format, 2-2 DISCON request format, 2-5 extended mode, 8-6 TIMABS request format, 2-17 TIMDEL request format, 2-20 TIMREL request format, 2-16 UCS C 7830 7402–014

Index

CONECT request format, 2-2 DISCON request format, 2-5 extended mode, 8-6 TIMABS request format, 2-17 TIMDEL request format, 2-19 TIMREL request format, 2-16 UDS, See Universal Data System UDS/TIP files, 3-2, 3-5 UK$ONS, 9-5, 9-6 UN FCSS function, 2-4, 3-29, 4-6 Universal Data System (UDS), 3-2, 9-6 UNLOCK KONS function, 5-13 unlock U3 block, 5-13 UOPAND primitive, 2-4, 8-26, 9-2 UOPGET primitive, 8-25 UOPTOR primitive, 2-4, 6-9, 8-27, 9-2 user KONS, 5-2 USERON parameter, 8-15 user-to-user pass-off, 2-11, 7-1, C-5, C-6 USYSDF procedure, 8-1

system KONS, 5-1 test/training modes, 9-2 TIMER, 2-15 TIP SUBQ, C-31 training files, 9-2 user KONS, 5-2 V program option, 2-14 VINDEX, 1-7

W WALL$, 3-19, C-17 WANY$, C-17 WL FCSS function, 3-29, 4-6 WR FCSS function, 3-18, 3-30, 4-6 WW FCSS function, 3-18, 3-20, 3-21, 3-31

X V VALTAB application group number, 4-5 block transfer loading, 6-7 CG function, B-10 diagnostic files, 9-9 FCREG primitive, B-4 flagbox settings, 8-16 HVTIP programs, 7-2 initial control program, 7-11 multi-input transactions, 8-17 multiple initialization, 6-3 OPT parameter, 9-2 program parameters, 1-7 program restart, 6-7 program scheduling, 2-13 program status (STATUS) field, 1-9, 8-16 program sticking, 6-8 program type (PRGTYP) field, 8-16 PRT field, C-36 REC keyword, 4-7 recovery information in, 4-6 recovery option, 4-7 release of file, B-9 RTPSI and, 6-5 shared database, 3-10 switching level, 6-3 7830 7402–014

XFR$, 7-5, 7-8 XPC, See record lock processor XRS$, 7-5, 7-9 XTC, See Extended Transaction Capacity XTPA, 1-4

Z zero overhead object module (ZOOM) block transfer load, 6-7 diagnostic files, 9-9, 9-11 HVTIP bank, 7-4 memory expansion/contraction, C-11, C-12 program sticking, 6-9 static linking, 8-6

Special Characters @RUN statement, 9-9 @START control statements, 8-15 @XQT, 2-4, 9-2 @XQT statement, 9-11

Index–13

Index

Index–14

7830 7402–014

.

© 2014 Unisys Corporation. All rights reserved.

*78307402-014* 7830 7402–014