Extended General
Device Support (GDSX)
Manual
Abstract
This is a reference manual for GDSX. GDSX is a nonprivileged, multitasking process
used to handle datastream conversion and data communications-related functions for
a business application. This manual provides information on how to design and code
the user-supplied part of a GDSX process, and how to compile, bind, debug, and run
GDSX. It is intended for people doing systems analysis, design and development,
operation, and support of GDSX applications.
Product Version
GDSX D44
Supported Release Version Updates (RVUs)
This manual supports the G06.26 RVU and all subsequent G-series and D-series
RVUs until otherwise indicated by its replacement publication.
Part Number
Published
529931-001
March 2005
Document History
Part Number
Product Version
Published
067742
GDSX D10
January 1993
095805
GDSX D10
June 1993
134303
GDSX D44
July 1997
529931-001
GDSX D44
March 2005
Extended General Device
Support (GDSX) Manual
Glossary
Index
What’s New in This Manual xv
Manual Information xv
New and Changed Information
Examples
Figures
xv
About This Manual xvii
Audience xvii
What’s in This Manual xviii
How to Use This Manual xix
Related Manuals xxiv
Notation Conventions xxv
1. Overview of GDSX
Purpose of GDSX 1-1
Communicating With User’s Devices 1-1
GDSX Architecture 1-3
TSCODE Components 1-5
Multithreading Functions 1-5
Fault-Tolerance Facilities 1-5
External Interfaces 1-6
Support for USCODE User Exits 1-8
Support for Service Routines 1-8
Hardware and Software Requirements 1-9
GDSX and Pathway/iTS 1-10
Direct Terminal Access 1-10
Indirect Terminal Access 1-12
Starting SU/Line With accessname NONE 1-15
Communicating Directly With a NonStop TS/MP Server
When to Use GDSX 1-16
2. Design and Development
Prerequisites for Design and Development
Design Considerations 2-1
Using D-Series Features 2-3
2-1
Hewlett-Packard Company—529931-001
i
1-16
Tables
Contents
2. Design and Development
Converted Application Features 2-3
Unconverted Application Features 2-3
GDSX D44 Features Supported 2-4
Coding and Testing Considerations 2-5
Coding the DEVICE^HANDLER 2-6
Coding the LINE^HANDLER 2-6
Debugging Your GDSX Application 2-7
Run-Time Environment 2-7
System Tasks 2-8
User Tasks 2-9
Overview of GDSX Processing 2-10
Calling Restrictions 2-12
Memory Management 2-13
Intertask Communication 2-14
Steps for Coding New Applications and Conversion 2-15
Coding New Applications 2-15
Conversion for Extended Features of D-Series Systems 2-16
Data Declarations 2-16
User Code Declarations 2-17
Space Usages and Limitations 2-19
User Data Segment 2-20
Extended Segment for Control Structures 2-21
Extended Segments for Trace Files 2-24
Memory Pools 2-24
Local Pools 2-25
Extended Memory Pools 2-26
Checkpointing Memory Pool Buffers 2-27
Pool Checking 2-28
Fault Tolerance 2-28
Level 0 Fault Tolerance 2-28
Level 1 Fault Tolerance 2-29
Level 2 Fault Tolerance 2-29
Fault-Tolerance Processing in GDSX Initialization 2-29
Checkpointing 2-31
Takeover Processing 2-34
Transaction Management Facility 2-37
TMF Configuration Parameter 2-37
Using the Pseudo Procedures 2-37
Linked Lists 2-38
Extended General Device Support (GDSX) Manual—529931-001
ii
2. Design and Development
Contents
Example 2-39
Semaphore Control 2-39
The GDSX Generation Process 2-40
Installed Subvolume Files 2-41
The User Source File 2-42
Compiling 2-43
Binding 2-45
GDSX Configuration Parameters 2-46
Setting Configuration Parameters 2-49
Descriptions of Configuration Parameters 2-51
ASSOCIATIVE 2-51
AUTOSTOP 2-51
BACKUPCPU 2-52
BREAKENABLED 2-52
BUFFERTIMEOUT 2-52
CONTROLFLAGS 2-52
CTRL26 2-54
DEBUGFLAGS 2-54
DEVICEINFO 2-56
DYNAMIC 2-58
EXTSUSIZE 2-59
IOCBWAITTIME 2-59
LOGSTATUS 2-59
LOOPTIME 2-59
MAXBUFPOOL 2-60
MAXCPSIZE 2-60
MAXDCBPOOL 2-61
MAXFCBPOOL 2-62
MAXFILES 2-62
MAXIOCBPOOL 2-63
MAXIOCBS 2-63
MAXITC 2-63
MAXLDCBPOOL 2-64
MAXLINEPOOL 2-64
MAXLINES 2-65
MAXLINKS 2-65
MAXMSGPOOL 2-66
MAXOPENS 2-66
MAXPCBPOOL 2-66
Extended General Device Support (GDSX) Manual—529931-001
iii
2. Design and Development
Contents
MAXPROCESSES 2-67
MAXRCBPOOL 2-67
MAXRCVPOOL 2-68
MAXTASKS 2-68
MAXTCBPOOL 2-69
MAXTERMS 2-69
NONSTOP 2-69
POOLSIZE 2-70
PROCNOWAIT 2-70
RECEIVEDEPTH 2-71
RECEIVESIZE 2-71
RESTARTTIME 2-71
SECURITY 2-72
SEGMENTID 2-73
SERVER 2-73
TASKCPSIZE 2-73
TASKPOOLSIZE 2-74
TASKSIZE 2-74
TMF 2-74
TRACERECSIZE 2-75
TRAPERROR 2-75
USERFLAGS 2-75
USERSTARTSU 2-76
File-System Errors 2-76
Notes on Specific Codes 2-77
EMS Filters and GDSX 2-79
Running the Filter 2-80
Tracing GDSX 2-80
Selecting Trace Events Supported by TSCODE
User-Coded Trace Calls 2-83
Turning On the Trace Facility 2-86
Modifying the Trace 2-88
Examining the Trace 2-89
GDSX Internals 2-90
I/O for Files Other Than $RECEIVE 2-90
I/O Involving $RECEIVE 2-94
Intertask Communication 2-97
USAMPLE Example Program 2-98
USER^STOP 2-99
2-81
Extended General Device Support (GDSX) Manual—529931-001
iv
3. Operations and Support
Contents
The LINE^HANDLER Procedure 2-99
The DEVICE^HANDLER Procedure 2-104
3. Operations and Support
Running a GDSX Application 3-1
Running GDSX at a High or Low PIN 3-1
ASSIGN and PARAM Commands 3-2
Running a GDSX Process 3-2
Running SCF and Starting Requesters 3-4
Running a Pathway/iTS Application 3-9
Running GDSX as a TS/MP Server 3-10
Space Usages and Limitations 3-12
User Data Segment 3-12
Extended Segment 3-12
Extended Segments for Trace Files 3-12
GDSX Configuration Parameters 3-13
Setting Configuration Parameters 3-13
Management With SCF 3-14
Command Summary 3-14
Interpreting Console and EMS Messages 3-16
Where Messages Are Displayed 3-16
Types of Messages Generated 3-17
Startup Configuration Error Messages 3-17
Abend Messages 3-19
Trap Messages 3-23
EMS Event Messages 3-24
Fault Messages 3-26
If GDSX Abends 3-28
4. DEVICE^HANDLER Example, Running and Managing
Running an Application Process 4-2
Compiling the Requester 4-2
Running the Application 4-2
Running Two Requesters 4-3
Generating the Example GDSX Process 4-3
Compiling 4-4
Binding 4-6
Running the DEVICE^HANDLER Example 4-6
Using SCF 4-7
Running an Application Process 4-8
Extended General Device Support (GDSX) Manual—529931-001
v
5. DEVICE^HANDLER Example, Design
Contents
Running a Second Application Process 4-11
Stopping the First Application and GDSX 4-13
5. DEVICE^HANDLER Example, Design
Environment of an Executing DEVICE^HANDLER Task
Task I/O Calls 5-2
Basic Structure of DEVICE^HANDLER Code 5-6
USKELEX Example Code 5-7
The DEVICE^HANDLER Procedure 5-9
Inspecting the DEVICE^HANDLER Example 5-14
Device Control Blocks 5-15
Task Control Blocks 5-17
I/O Control Blocks 5-18
The USER^STOP Procedure 5-19
Fault-Tolerance Processing 5-19
Testing Failure at a ^WRITEREAD 5-20
Testing Failure at a ^WRITE 5-23
5-1
6. LINE^HANDLER Example, Running and Managing
Running the LINE^HANDLER Example 6-2
Preconfiguring the LINE and Subdevices 6-2
Running an Application Process 6-4
Running More Application Processes 6-5
7. LINE^HANDLER Example, Design
Environment of an Executing LINE^HANDLER Task 7-1
Intertask Communication—LINE^HANDLER Perspective
Transaction Flow 7-7
Basic Structure of LINE^HANDLER Code 7-10
E^ITC 7-12
E^IOC 7-12
E^CAN 7-12
E^STOP 7-13
LINE^HANDLER Example Code 7-13
LINE^HANDLER Procedure 7-13
Other Procedure Declarations 7-20
Inspecting the LINE^HANDLER Example 7-20
Line Control Blocks 7-22
The Task Control Block 7-22
The IOCB 7-23
7-3
Extended General Device Support (GDSX) Manual—529931-001
vi
8. Service Routines
Contents
Tracing a ^CANCEL
7-23
8. Service Routines
Utility Procedures 8-1
Bit Map Control 8-2
Break Handling 8-2
Debugging Facilities 8-2
Fault-Tolerance Facilities 8-2
Identifier Manipulation 8-2
Intertask Communication 8-3
IOCB Maintenance 8-3
List Manipulation 8-3
Pool Management 8-3
Semaphore Control 8-4
Task Maintenance 8-4
Pseudo Procedures 8-4
Pseudo Procedure Syntax 8-6
^ABORTTRANSACTION 8-7
ADD^TRACE^DATA 8-7
ADD^TRACE^DATA^INT 8-9
ALLOCATEIOCB 8-9
^AWAITIO[X] 8-10
^BEGINTRANSACTION 8-12
BIT^MAP 8-12
BIT^RESET 8-13
BIT^SET 8-14
BIT^TEST 8-14
BOUNDS^CHECK 8-15
^CANCEL 8-15
^CANCELREQ 8-16
^CANCELTIMEOUT 8-16
CHANGE^BUFF^OWNER[X] 8-17
CHECK^BUFFER^BOUNDS 8-17
^CHECKPOINT 8-18
^CLOSE 8-19
^CONTROL 8-19
DEALLOCATEIOCB 8-19
^DELAY 8-19
DELETE^[X]ITEM 8-20
Extended General Device Support (GDSX) Manual—529931-001
vii
8. Service Routines
Contents
^DEVICEINFO2 8-20
DO^CP 8-21
^ENDTRANSACTION 8-22
FAULT 8-22
^FILE_CLOSE_ 8-24
^FILE_GETINFO_ 8-24
^FILE_GETINFOBYNAME_ 8-25
^FILE_GETRECEIVEINFO_ 8-25
^FILEINFO 8-26
^FILE_OPEN_ 8-26
^FNAMEEXPAND 8-28
GET^CPSEM 8-28
GETEXTPOOL 8-30
GETEXTPOOLX 8-33
GET^ITC^FCB 8-34
GETLOCALPOOL 8-36
GET_PROCESS_HANDLE_FROM_NAME_ 8-38
GET_PROCESS_HANDLES_CPU_ 8-39
GET_PROCESS_HANDLES_NODE_ 8-39
GET^TASK^NAME 8-39
GIVEBREAK 8-40
GIVE^CPSEM 8-40
INIT^[X]LIST 8-41
INIT^SEM 8-41
INIT^XLIST 8-43
INSERT^[X]ITEM 8-43
ITC^OPENX 8-44
^LISTEN 8-45
^LOCKREC 8-48
MAKE_PROCESS_HANDLE_NULL_ 8-48
^MYTERM 8-49
^NEWPROCESS 8-49
NOTIFY^IO^COMPLETION[X] 8-50
^OPEN 8-52
^PROCESS_CREATE_ 8-53
PROCESS_HANDLE_IS_NULL_ 8-54
PROCESS_STOP_ 8-54
PSEM 8-55
PUTEXTPOOL 8-56
Extended General Device Support (GDSX) Manual—529931-001
viii
8. Service Routines
Contents
PUTLOCALPOOL 8-57
Q^CP[X] 8-57
^READ[X] 8-61
^READLOCK[X] 8-61
^READUPDATE[X] 8-61
^READUPDATELOCK[X] 8-63
^RECEIVEINFO 8-63
^RECLAIMBUFFER 8-64
^REPLY[X] 8-66
^RESUMETRANSACTION 8-67
SEND^ITC^MSG[X] 8-68
^SERVERCLASS_DIALOG_ABORT_ 8-71
^SERVERCLASS_DIALOG_BEGIN_ 8-71
^SERVERCLASS_DIALOG_END_ 8-72
^SERVERCLASS_DIALOG_SEND_ 8-72
^SERVERCLASS_SEND_ 8-73
^SERVERCLASS_SEND_INFO_ 8-74
^SETMODE 8-74
^SETMODENOWAIT 8-74
^SETMYTERM 8-75
^SETPARAM 8-76
^SHUTDOWN 8-76
^SIGNALINTERRUPT 8-77
^SIGNALTIMEOUT 8-78
STOP^TASK 8-80
TAKEBREAK 8-80
TCBADDR 8-81
^TERMINATE 8-82
^UNLOCKREC 8-83
USER^CLOSE^TRACE^FILE 8-83
USER^OPEN^TRACE^FILE 8-83
VSEM 8-84
WAITED^IO[X] 8-85
WAIT^EVENT 8-86
WAKE^TASK 8-89
^WRITE[X] 8-90
WRITE^ITC^MESSAGE[X] 8-90
^WRITEREAD[X] 8-92
^WRITEUPDATE[X] 8-92
Extended General Device Support (GDSX) Manual—529931-001
ix
9. User Exit Descriptions
Contents
^WRITEUPDATEUNLOCK[X]
8-93
9. User Exit Descriptions
User Exit Routines 9-1
DEVICE^HANDLER 9-2
LINE^HANDLER 9-3
PROCESS^ASSIGNS 9-5
PROCESS^USER^PARAMS 9-5
USER^ATTRIBUTES 9-7
USER^BACKUP 9-10
USER^COMMANDS 9-12
USER^INITIALIZE 9-18
USER^INIT^CONFIG^PARAMS 9-19
USER^REPLIES 9-20
USER^START 9-22
USER^STOP 9-23
USER^TAKEOVER 9-25
USER^VERSION 9-26
A. APPLS Requester Listing
APPLS Listing
A-1
B. USKELEX and USKELEXC Listings
USKELEX Listing B-1
USKELEXC Listing B-14
C. DCCBDECS and ULHDECSE Listings
DCCBDECS Listing C-1
ULHDECSE Listing C-12
D. Using Pseudo Procedures in a TS/MP Environment
GDSX Without Pathway/iTS and TMF Procedures D-1
Compiling USAMPLE1 D-2
Binding D-3
Creating the Database D-3
Starting NonStop TS/MP D-3
Running the GDSX Application D-5
Configuring and Starting the Terminal Tasks D-5
USAMPLE1 Listing D-6
SCOBGDSX Listing D-11
Extended General Device Support (GDSX) Manual—529931-001
x
E. Intertask Communication Example
Contents
WRITER Listing D-13
DELETER Listing D-16
GDSX With NonStop TS/MP and TMF Procedures D-19
Compiling USAMPLE2 D-20
Binding D-21
Creating the Database D-21
Starting NonStop TS/MP D-21
Running the GDSX Application D-22
Configuring and Starting the Terminal Tasks D-23
USAMPLE2 Listing D-23
E. Intertask Communication Example
Running the Example E-1
Compiling USAMPLE3 E-1
Binding E-2
Running the GDSX Application E-2
Configuring and Starting the Terminal Tasks
USAMPLE3 E-3
E-3
Glossary
Index
Examples
Example 5-1.
Example 5-2.
Example 5-3.
Example 5-4.
Example 5-5.
Example 5-6.
Example 7-1.
Example 7-2.
Example 7-3.
Example 7-4.
Example 7-5.
Example 7-6.
Example 9-1.
USKELEX Global Declarations 5-8
DEVICE^HANDLER Local Declarations 5-10
Reading and Decoding Requests 5-11
Request Processing 5-12
The USER^STOP Procedure 5-19
Requester Code for Takeover at a ^WRITEREAD 5-21
LINE^HANDLER Local Declarations 7-14
Main Entry: Decoding Events 7-15
PROCESS^DH^REQ Subprocedure 7-16
WT^TO^LINE and WR^RD^TO^LINE Subprocedures 7-17
LINE^IO^CMPLT Subprocedure 7-18
CANCEL^ITC Subprocedure 7-19
Listing of TELLGDS File 9-15
Figures
Figure 1-1.
Communicating With User’s Devices
1-1
Extended General Device Support (GDSX) Manual—529931-001
xi
Tables
Contents
Figure 1-2.
Figure 1-3.
Figure 1-4.
Figure 1-5.
Figure 1-6.
Figure 1-7.
Figure 1-8.
Figure 2-1.
Figure 2-2.
Figure 2-3.
Figure 4-1.
Figure 4-2.
Figure 4-3.
Figure 4-4.
Figure 5-1.
Figure 5-2.
Figure 5-3.
Figure 5-4.
Figure 5-5.
Figure 5-6.
Figure 6-1.
Figure 7-1.
Figure 7-2.
Figure 7-3.
Figure 7-4.
Figure D-1.
Figure D-2.
Communicating With Back-End Network 1-2
Handling Message Switching 1-3
Application With GDSX and Pathway/iTS 1-4
Direct Terminal Access Transaction Flow 1-11
GDSX Without a LINE^HANDLER 1-12
Indirect Terminal Access Transaction Flow 1-13
GDSX With a LINE^HANDLER 1-15
User Data Segment 2-21
Extended Segment for GDSX 2-22
GDSX Generation Process 2-42
Overview of DEVICE^HANDLER Example 4-1
Example Generation Process 4-5
Initial Message Flow 4-9
Processing an Input String 4-10
DEVICE^HANDLER Task Run-Time Environment 5-2
DEVICE^HANDLER Example: Sending a Request to a Terminal
DEVICE^HANDLER Program Structure 5-6
Locating DCBs 5-16
Control Block Pointer Tracing 5-17
Fault Tolerance in the DEVICE^HANDLER Example 5-22
Environment of the LINE^HANDLER Example 6-1
LINE^HANDLER Run-Time Environment 7-2
Sending a WRITEREAD Through a LINE^HANDLER 7-4
LINE^HANDLER Example Message Flow 7-8
Basic Structure of LINE^HANDLER Code 7-11
GDSX Application Without Pathway/iTS and TMF Pseudo
Procedures D-2
GDSX Application With NonStop TS/MP and TMF Pseudo
Procedures D-20
5-4
Tables
Table i.
Table 2-1.
Table 2-2.
Table 2-3.
Table 2-4.
Table 2-5.
Table 2-6.
Table 2-7.
Summary of GDSX Tasks xx
Global Declarations Sourced in by User Code 2-18
Static Parameters 2-46
Dynamic Parameters 2-48
TSCODE Trace Classes and Entry Types 2-81
USCODE Trace Classes and Entry Types 2-84
TSCODE Trace Classes, Trace^control^flags DEFINEs, and Events
Traced 2-86
Events Traced by USAMPLE 2-88
Extended General Device Support (GDSX) Manual—529931-001
xii
Contents
Table 3-1.
Table 3-2.
Table 3-3.
Table 3-4.
Table 3-5.
Table 3-6.
Table 3-7.
Table 5-1.
Table 7-1.
Table 8-1.
Table 8-2.
GDSX Subsystem-Specific SCF Commands 3-15
Abend Error Messages 3-20
Error 220 Message Breakdown 3-22
TSCODE Trap Messages 3-24
GDSX EMS Event Message Summary 3-25
Number Ranges for Fault Messagesw 3-26
TSCODE Fault Messages 3-27
Global Declarations Sourced in by USKELEX 5-8
Events Detected With WAIT^EVENT 7-6
Pseudo Procedures 8-5
Events Detected With WAIT^EVENT 8-87
Extended General Device Support (GDSX) Manual—529931-001
xiii
Contents
Extended General Device Support (GDSX) Manual—529931-001
xiv
What’s New in This Manual
Manual Information
Extended General Device Support (GDSX) Manual
Abstract
This is a reference manual for GDSX. GDSX is a nonprivileged, multitasking process
used to handle datastream conversion and data communications-related functions for
a business application. This manual provides information on how to design and code
the user-supplied part of a GDSX process, and how to compile, bind, debug, and run
GDSX. It is intended for people doing systems analysis, design and development,
operation, and support of GDSX applications.
Product Version
GDSX D44
Supported Release Version Updates (RVUs)
This manual supports the G06.26 RVU and all subsequent G-series and D-series
RVUs until otherwise indicated by its replacement publication.
Part Number
Published
529931-001
March 2005
Document History
Part Number
Product Version
Published
067742
GDSX D10
January 1993
095805
GDSX D10
June 1993
134303
GDSX D44
July 1997
529931-001
GDSX D44
March 2005
New and Changed Information
•
In Section 2, Design and Development, these changes have been incorporated:
•
•
•
•
A new sentence about GDSX D44 support is added to GDSX D44 Features
Supported on page 2-4.
The details about global data declarations is added to Data Declarations on
page 2-16.
The details about accessing the files of size greater than 4 GB is added to
Global Declarations on page 2-17.
Wherever DCCBDECS occurs, DCCBDEC2 is included and wherever
PEXTGDS occurs, PEXTGDS2 is included in Table 2-1 on page 2-18.
Extended General Device Support (GDSX) Manual—529931-001
xv
What’s New in This Manual
•
•
•
•
•
•
New and Changed Information
The details for DCCBDEC2, PEXTGDS2, and TSCODE2 are added to
Installed Subvolume Files on page 2-41.
The details about accessing format 2 files of size greater than 4 GB is added to
The User Source File on page 2-42.
The example in Compiling on page 2-43 has been changed.
The first sentence and the commands below the first sentence have been
modified in Binding on page 2-45.
In Section 3, Operations and Support, the TS fault codes 21 to 26 have been
added to the Table 3-7, TSCODE Fault Messages, on page 3-27.
In Appendix C, DCCBDECS and ULHDECSE Listings, a new element "elections"
is added to the Structure "FCB^TEMPLATE" on page C-9.
Extended General Device Support (GDSX) Manual—529931-001
xvi
About This Manual
This manual describes the operation of the Extended General Device Support (GDSX)
product. GDSX is used to help you develop either a back-end process for message
switching or a front-end process for implementation or modification of data
communications protocols or support of nonstandard terminal devices.
GDSX code contains the following:
•
•
A set of generic service routines that are supplied by HP to support multithreaded,
fault-tolerant processing.
User-written code for application-specific data communications requirements.
When the code supplied by HP and the user-supplied code are bound, the result is an
operational GDSX process. This operational GDSX process runs as an interface
between a business-oriented application program and either an input/output process
(IOP) or a message-switching process.
Audience
This manual is written for people doing systems analysis, design, development,
operation, and/or support of GDSX applications. Because, for a given application, one
person may be doing any or all of these functions, headings in the manual refer to
analysis, design, development, operation, and support as roles or phases in the
product life cycle, rather than as job titles for different people.
With the exception of some system operators who may be concerned only with
operations of GDSX applications, readers are assumed to be experienced system
programmers who are experts in the following:
•
•
•
•
TAL programming
Guardian procedure calls
HP NonStop Transaction Management Facility (TMF)
Data communications, if their application is to include protocol conversion
Readers are also assumed to be familiar with the following:
•
•
Principles of multithreading
Principles of fault tolerance, if their application is to run as a process pair
Extended General Device Support (GDSX) Manual—529931-001
xvii
What’s in This Manual
About This Manual
What’s in This Manual
This manual is directed to all users who need information on how to design and code
the user-supplied part of a GDSX process, and to those who need to know how to
compile, bind, debug, and run GDSX. The manual includes the following:
Sections 1-3
Introductory material
Sections 4-7
Tutorial
Sections 8 and 9
Reference material
Appendixes A-E
Appendixes and example program listings
What Is Included in This Manual?
This preface contains a guide to help you find material you need. It has headings for
system analysis, design and development, operations, and support functions. Under
each heading is a list of parts of the manual that are likely to be useful in doing the
tasks involved in that function. The sections are as follows:
•
•
•
•
Section 1 contains introductory material useful for a high-level understanding of
GDSX, including an explanation of the purpose for which GDSX is used, typical
applications, hardware and software requirements, a description of the component
of the GDSX code supplied by HP, and the interface of GDSX with HP NonStop
Pathway/iTS.
Section 2 contains suggestions and considerations on designing and developing
USCODE; steps for coding new applications and conversion; a description of
D-series features; instructions on how to compile USCODE and how to bind
USCODE and TSCODE object modules to form a complete GDSX front-end
process. Also included is information on basic internal control flow, memory pools,
space and calling restrictions, configuration parameters, fault tolerance, file system
errors, EMS (Event Management Service) filters, tracing, GDSX internals, and the
USAMPLE example program.
Section 3 includes material for operations and support functions, including
instructions on running a GDSX application at a high or low PIN, space usages and
limitations, GDSX configuration parameters, management with SCF (Subsystem
Control Facility), console and EMS messages, and procedures to follow if GDSX
abnormally ends (abends).
Sections 4 through 7 comprise a tutorial covering the compilation, binding, and
execution of an example application and the use of SCF to configure and manage
the example. A thorough description of the example’s design and functioning is
included in Sections 5 and 7.
In Sections 4 and 5 the example is run with a DEVICE^HANDLER and no
LINE^HANDLER, because approximately 80 percent of GDSX applications have
DEVICE^HANDLERs only.
Extended General Device Support (GDSX) Manual—529931-001
xviii
What Is Not Included in This Manual?
About This Manual
In Sections 6 and 7 the example is run with a LINE^HANDLER. Material presented
in the tutorial is also presented in the introductory and reference parts of the
manual so that experienced users do not need to refer to the tutorial for
information.
•
•
•
•
•
•
Sections 8 and 9 contain reference material on the procedures and user exits
needed for development.
Appendix A, “APPLS Requester Listing,” provides a listing of an example program
in APPLS.
Appendix B, “USKELEX and USEKELEXC Listings,” includes listings of the
USKELEX and USEKELEXC example programs.
Appendix C, “DCCBDECS and ULHDECSE Listings,” includes listings for the
DCCBDECS and ULHDECSE files for GDSX.
Appendix D, “Using Pathway and TMF Pseudo Procedures,” contains an example
of converting a GDSX application to use Pathway and TMF pseudo procedures.
Appendix E, “Intertask Communication Example,” contains an example of sending
and receiving ITC messages between two DEVICE^HANDLER tasks.
What Is Not Included in This Manual?
This manual is intended for experienced system programmers and so does not explain
TAL programming or the operating system. Also, this manual does not describe the
syntax of GDSX supported pseudo procedures that function exactly like their
corresponding Guardian, HP NonStop TS/MP, Pathway/iTS, and TMF procedures
because those procedures are explained in other manuals.
Finally, this manual was not written as a cookbook that may be followed step by step to
develop a given application. Although essential information, tutorials with working
examples, and guidelines are provided for development of typical applications, not all
applications could be anticipated for this very adaptable product.
How to Use This Manual
The following headings should help you find the material you need in this manual.
Under each function heading there is a list of tasks usually performed for the function,
followed by a list of parts of the manual that are likely to be useful in doing the tasks.
Table i provides a summary of the tasks usually required for these different functions.
Depending on the level of detail required for the analysis, you may wish to see Section
2 for general guidelines on design and development.
Extended General Device Support (GDSX) Manual—529931-001
xix
How to Use This Manual
About This Manual
Table i. Summary of GDSX Tasks (page 1 of 2)
System
s
Analysi
s
Task
Design and
Development
Operations
Support
Understand the range of GDSX
applications
X
X
Learn the basic internal control flow
of a typical GDSX application
X
X
Determine what hardware and
software would be necessary to
use GDSX for a given application
X
X
Understand the experience and
level of expertise necessary for
developers
X
Identify guidelines and restrictions
relevant to the design and
development effort, including those
applying to space, memory pools,
and procedure calls
X
X
Understand the restrictions on
communication between GDSX
and other processes
X
X
Understand the different levels of
fault tolerance supported by GDSX
X
X
X
Determine whether GDSX can be
used to develop a particular
application
X
X
X
X
X
X
X
X
X
X
Configure GDSX to run converted
or unconverted, at a low PIN or a
high PIN
X
X
X
Run GDSX with different options
and parameters, and change
configuration parameter values
after creation time
X
X
X
Compile, bind, and run example
programs
X
Use SCF to configure and manage
GDSX objects, and to obtain
statistical data on GDSX operation
X
X
X
Extended General Device Support (GDSX) Manual—529931-001
xx
X
Systems Analysis
About This Manual
Table i. Summary of GDSX Tasks (page 2 of 2)
System
s
Analysi
s
Task
Design and
Development
Operations
Support
Understand the typical environment
of executing DEVICE^HANDLER
tasks, as well as the typical basic
structure of DEVICE^HANDLER
code
X
X
Understand the purposes of the
various control structures and how
to access them
X
X
Determine which user exits need to
be developed for an application
X
X
Code user exits necessary for an
application, using the available
TSCODE utilities and the pseudo
procedures
X
Interpret GDSX abend, trap, fault,
EMS event, and configuration error
messages
X
Run a trace in GDSX
X
X
X
X
Systems Analysis
Readers doing systems analysis might need to do the following tasks:
•
•
•
•
•
•
•
•
Understand the range of GDSX applications.
Learn the basic internal control flow of a typical GDSX application.
Determine what hardware and software would be necessary to use GDSX for a
given application.
Understand the experience and level of expertise necessary for developers.
Identify guidelines and restrictions relevant to the design and development effort,
including those applying to space, memory pools, and procedure calls.
Understand the restrictions on communication between GDSX and other
processes.
Understand the different levels of fault tolerance supported by GDSX.
Determine whether GDSX can be used to develop a particular application.
Extended General Device Support (GDSX) Manual—529931-001
xxi
Design and Development
About This Manual
References
See Section 1 for an overview of GDSX, including its general purpose, the range of
GDSX applications, hardware and software requirements, a description of the
functional components of the GDSX code supplied by HP, and the interface of GDSX
with TS/MP and Pathway/iTS.
Depending on how detailed your understanding of GDSX needs to be, you may wish to
use the tutorial in Sections 4 through 7 to learn more about GDSX. The tutorial
includes generating the object file; configuring and running example programs; using
SCF for management of GDSX objects; DEVICE^HANDLER and LINE^HANDLER
design; control structures; memory management; and fault tolerance.
Design and Development
Readers doing design and development might need to do the following tasks:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Learn the basic internal control flow of a simple GDSX application.
Determine what hardware and software would be necessary to use GDSX for an
application.
Identify guidelines and restrictions relevant to the design and development effort,
including those applying to space, memory pools, and procedure calls.
Understand the restrictions on communication between GDSX and other
processes.
Understand the different levels of fault tolerance supported by GDSX.
Determine whether GDSX can be used to develop a particular application.
Configure GDSX to run converted or unconverted, and at a low PIN or a high PIN.
Run GDSX with different options and parameters, and change configuration
parameter values after creation time.
Compile, bind, and run example programs.
Use SCF to configure and manage GDSX objects, and to obtain statistical data on
GDSX operations.
Understand the typical environment of executing DEVICE^HANDLER tasks, as
well as the typical basic structure of DEVICE^HANDLER code.
Understand the purposes of the various control structures and how to access
them.
Determine which user exits need to be developed for their application.
Code user exits, using the available TSCODE utilities and the pseudo procedures.
Interpret GDSX abend, trap, fault, EMS event, and configuration error messages.
Run a trace in GDSX.
Extended General Device Support (GDSX) Manual—529931-001
xxii
Operations
About This Manual
References
See Section 1 for an overview of GDSX. Unless you are already very familiar with
GDSX, it will probably be helpful to do the tutorial in Sections 4 through 7. If your
application has or will have a DEVICE^HANDLER only, you need only Sections 4 and
5. If your DEVICE^HANDLER is or will be multithreaded, you might find Sections 6 and
7 helpful.
See Section 2 for prerequisites for development; alternatives to using GDSX; general
guidelines on design and development, including information on converting existing
applications; D-series features; instructions for coding, compiling, binding, and testing;
memory pool, calling, and space restrictions; basic internal control flow; fault tolerance;
file system errors; EMS filters; semaphores; linked lists; configuration parameters;
tracing; GDSX internals; and the USAMPLE example program. For information on
running and managing GDSX, see Section 3.
Operations
Readers responsible for operations might need to perform the following tasks:
•
•
•
•
•
•
Determine what hardware and software are necessary to use GDSX for a given
application.
Understand the restrictions on communication between GDSX and other
processes.
Configure GDSX to run converted or unconverted, and at a low PIN or a high PIN.
Run GDSX with different options and parameters, and change configuration
parameter values after creation time.
Use SCF to configure and manage GDSX objects, and to obtain statistical data on
GDSX operations.
Interpret GDSX abend, trap, fault, EMS event, and configuration error messages.
References
See Section 1 for an overview of GDSX.
Unless you are already familiar with GDSX, it is helpful to do parts of the tutorial.
Sections 4 and 6 of the tutorial contain step-by-step instructions on configuring and
running an example program and using SCF for management of GDSX objects. You
might wish to skip Sections 5 and 7 on DEVICE^HANDLER and LINE^HANDLER
design.
See Section 3 for material on running GDSX, dealing with space usages and
limitations, controlling configuration parameter values, managing objects by means of
SCF, interpreting warning and error messages, and gathering information if GDSX
abends.
Extended General Device Support (GDSX) Manual—529931-001
xxiii
Support
About This Manual
See the SCF Reference Manual for GDSX for more information on managing GDSX
using SCF.
Support
Readers responsible for support of the GDSX product might need to perform any or all
of the tasks listed under the “Systems Analysis,” “Design and Development,”
“Operations,” and “Support” headings.
References
In addition to the references cited under the preceding headings, individuals supporting
GDSX may need to refer to Section 2 for the layout of the user data segment and
TSCODE’s extended data segment, and a description of TSCODE internals.
Related Manuals
The following manuals are usually relevant for development and management of a
GDSX application:
•
•
•
The SCF Reference Manual for GDSX describes the Subsystem Control Facility
(SCF) interactive interface that allows operators and network managers to
configure and control a GDSX data communications subsystem. SCF also
provides a means for examining the configuration and status of a GDSX data
communications subsystem.
The Guardian Procedure Calls Reference Manual, NonStop TS/MP Pathsend and
Server Programming Manual, Pathway/iTS TCP and Terminal Programming Guide,
and NonStop TMF Application Programmer’s Guide describe the syntax of
procedure calls for NonStop systems, and are useful to the developer using GDSX
procedures that are identical to their Guardian, TS/MP, Pathway/iTS, and TMF
counterparts.
The GDS Management Programming Manual provides subsystem-specific
information about the management programming interfaces to GDSX using the
Subsystem Programmatic Interface (SPI) and the Event Management Service
(EMS). This manual is useful for programmers writing management applications
that communicate with GDSX, and for TACL users writing macros to perform
system and network management functions using GDSX.
The following manuals are also useful:
•
•
•
•
•
Binder Manual
SPI Programming Manual
EMS Manual
Guardian Programmer’s Guide
Inspect Manual
Extended General Device Support (GDSX) Manual—529931-001
xxiv
Notation Conventions
About This Manual
•
•
•
•
•
•
Introduction to NonStop Transaction Processing
Introduction to NonStop Transaction Manager (TM/MP)
PTrace Reference Manual
Subsystem Control Facility (SCF) Reference Manual
TAL Reference Manual
NonStop TMF Application Programmer’s Guide
Notation Conventions
Hypertext Links
Blue underline is used to indicate a hypertext link within text. By clicking a passage of
text with a blue underline, you are taken to the location described. For example:
This requirement is described under Backup DAM Volumes and Physical Disk
Drives on page 3-2.
General Syntax Notation
This list summarizes the notation conventions for syntax presentation in this manual.
UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words. Type
these items exactly as shown. Items not enclosed in brackets are required. For
example:
MAXATTACH
lowercase italic letters. Lowercase italic letters indicate variable items that you supply.
Items not enclosed in brackets are required. For example:
file-name
computer type. Computer type letters within text indicate C and Open System Services
(OSS) keywords and reserved words. Type these items exactly as shown. Items not
enclosed in brackets are required. For example:
myfile.c
italic computer type. Italic computer type letters within text indicate C and Open
System Services (OSS) variable items that you supply. Items not enclosed in brackets
are required. For example:
pathname
Extended General Device Support (GDSX) Manual—529931-001
xxv
General Syntax Notation
About This Manual
[ ] Brackets. Brackets enclose optional syntax items. For example:
TERM [\system-name.]$terminal-name
INT[ERRUPTS]
A group of items enclosed in brackets is a list from which you can choose one item or
none. The items in the list can be arranged either vertically, with aligned brackets on
each side of the list, or horizontally, enclosed in a pair of brackets and separated by
vertical lines. For example:
FC [ num ]
[ -num ]
[ text ]
K [ X | D ] address
{ } Braces. A group of items enclosed in braces is a list from which you are required to
choose one item. The items in the list can be arranged either vertically, with aligned
braces on each side of the list, or horizontally, enclosed in a pair of braces and
separated by vertical lines. For example:
LISTOPENS PROCESS { $appl-mgr-name }
{ $process-name }
ALLOWSU { ON | OFF }
| Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in
brackets or braces. For example:
INSPECT { OFF | ON | SAVEABEND }
… Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you
can repeat the enclosed sequence of syntax items any number of times. For example:
M address [ , new-value ]…
[ - ] {0|1|2|3|4|5|6|7|8|9}…
An ellipsis immediately following a single syntax item indicates that you can repeat that
syntax item any number of times. For example:
"s-char…"
Punctuation. Parentheses, commas, semicolons, and other symbols not previously
described must be typed as shown. For example:
error := NEXTFILENAME ( file-name ) ;
LISTOPENS SU $process-name.#su-name
Quotation marks around a symbol such as a bracket or brace indicate the symbol is a
required character that you must type as shown. For example:
"[" repetition-constant-list "]"
Extended General Device Support (GDSX) Manual—529931-001
xxvi
Notation for Messages
About This Manual
Item Spacing. Spaces shown between items are required unless one of the items is a
punctuation symbol such as a parenthesis or a comma. For example:
CALL STEPMOM ( process-id ) ;
If there is no space between two items, spaces are not permitted. In this example, no
spaces are permitted between the period and any other items:
$process-name.#su-name
Line Spacing. If the syntax of a command is too long to fit on a single line, each
continuation line is indented three spaces and is separated from the preceding line by
a blank line. This spacing distinguishes items in a continuation line from items in a
vertical list of selections. For example:
ALTER [ / OUT file-spec / ] LINE
[ , attribute-spec ]…
!i and !o. In procedure calls, the !i notation follows an input parameter (one that passes data
to the called procedure); the !o notation follows an output parameter (one that returns
data to the calling program). For example:
CALL CHECKRESIZESEGMENT (
segment-id
, error
) ;
!i
!o
!i,o. In procedure calls, the !i,o notation follows an input/output parameter (one that both
passes data to the called procedure and returns data to the calling program). For
example:
error := COMPRESSEDIT ( filenum ) ;
!i:i.
!i,o
In procedure calls, the !i:i notation follows an input string parameter that has a
corresponding parameter specifying the length of the string in bytes. For example:
error := FILENAME_COMPARE_ (
filename1:length
, filename2:length ) ;
!i:i
!i:i
!o:i. In procedure calls, the !o:i notation follows an output buffer parameter that has a
corresponding input parameter specifying the maximum length of the output buffer in
bytes. For example:
error := FILE_GETINFO_ (
filenum
, [ filename:maxlen ] ) ;
!i
!o:i
Notation for Messages
This list summarizes the notation conventions for the presentation of displayed
messages in this manual.
Extended General Device Support (GDSX) Manual—529931-001
xxvii
Notation for Messages
About This Manual
Bold Text. Bold text in an example indicates user input typed at the terminal. For example:
ENTER RUN CODE
?123
CODE RECEIVED:
123.00
The user must press the Return key after typing the input.
Nonitalic text. Nonitalic letters, numbers, and punctuation indicate text that is displayed or
returned exactly as shown. For example:
Backup Up.
lowercase italic letters. Lowercase italic letters indicate variable items whose values are
displayed or returned. For example:
p-register
process-name
[ ] Brackets. Brackets enclose items that are sometimes, but not always, displayed. For
example:
Event number = number [ Subject = first-subject-value ]
A group of items enclosed in brackets is a list of all possible items that can be
displayed, of which one or none might actually be displayed. The items in the list can
be arranged either vertically, with aligned brackets on each side of the list, or
horizontally, enclosed in a pair of brackets and separated by vertical lines. For
example:
proc-name trapped [ in SQL | in SQL file system ]
{ } Braces. A group of items enclosed in braces is a list of all possible items that can be
displayed, of which one is actually displayed. The items in the list can be arranged
either vertically, with aligned braces on each side of the list, or horizontally, enclosed in
a pair of braces and separated by vertical lines. For example:
obj-type obj-name state changed to state, caused by
{ Object | Operator | Service }
process-name State changed from old-objstate to objstate
{ Operator Request. }
{ Unknown.
}
| Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in
brackets or braces. For example:
Transfer status: { OK | Failed }
Extended General Device Support (GDSX) Manual—529931-001
xxviii
Notation for Management Programming Interfaces
About This Manual
% Percent Sign. A percent sign precedes a number that is not in decimal notation. The
% notation precedes an octal number. The %B notation precedes a binary number.
The %H notation precedes a hexadecimal number. For example:
%005400
%B101111
%H2F
P=%p-register E=%e-register
Notation for Management Programming Interfaces
This list summarizes the notation conventions used in the boxed descriptions of
programmatic commands, event messages, and error lists in this manual.
UPPERCASE LETTERS. Uppercase letters indicate names from definition files. Type
these names exactly as shown. For example:
ZCOM-TKN-SUBJ-SERV
lowercase letters. Words in lowercase letters are words that are part of the notation,
including Data Definition Language (DDL) keywords. For example:
token-type
!r.
The !r notation following a token or field name indicates that the token or field is
required. For example:
ZCOM-TKN-OBJNAME
!o.
token-type ZSPI-TYP-STRING.
!r
The !o notation following a token or field name indicates that the token or field is
optional. For example:
ZSPI-TKN-MANAGER
token-type ZSPI-TYP-FNAME32.
Extended General Device Support (GDSX) Manual—529931-001
xxix
!
About This Manual
Notation for Management Programming Interfaces
Extended General Device Support (GDSX) Manual—529931-001
xxx
1
Overview of GDSX
This section contains introductory material useful for a high-level understanding of
GDSX, including an explanation of the purpose for which GDSX is used, typical GDSX
applications, hardware and software requirements, a description of the functional
components of the GDSX code supplied by HP, and the interface of GDSX with
Pathway.
Purpose of GDSX
The general purpose of a GDSX process is to handle datastream conversion and data
communications-related functions for a business application. There are two main parts
of a GDSX process:
•
•
The part supplied by HP, referred to as TSCODE
The part written by you, referred to as USCODE
TSCODE provides generic routines and management services that help create a
multithreaded, fault-tolerant process. USCODE handles the application-specific, data
communications-related functions.
GDSX is applicable to many terminal support environments. The following pages give
several examples
Communicating With User’s Devices
GDSX interfaces with standard application software, such as Pathway, for
communication with a user’s own devices, as shown in Figure 1-1. The devices may
be automated teller machines (ATMs) or point-of-sale terminals, for example.
Figure 1-1. Communicating With User’s Devices
Device
Business
Application
GDSX
IOP
Device
Device
VST001.vsd
Extended General Device Support (GDSX) Manual—529931-001
1 -1
Communicating With User’s Devices
Overview of GDSX
GDSX interfaces with standard application software, such as Pathway, for
communication with a back-end network, such as a banking network as shown in
Figure 1-2.
Figure 1-2. Communicating With Back-End Network
Business
Application
GDSX
IOP
Network
Business
Application
Device
Device
Device
VST002.vsd
GDSX is also used to handle message switching, either from terminal devices or from
a back-end network, as shown in Figure 1-3.
Extended General Device Support (GDSX) Manual—529931-001
1 -2
GDSX Architecture
Overview of GDSX
Figure 1-3. Handling Message Switching
Device
Business
Application
GDSX
IOP
Device
Device
IOP
Device
Network
Business
Application
Device
Device
VST003.vsd
GDSX Architecture
Figure 1-4 depicts the architecture of a GDSX process that is serving as a front end for
a Pathway application.
Extended General Device Support (GDSX) Manual—529931-001
1 -3
GDSX Architecture
Overview of GDSX
Figure 1-4. Application With GDSX and Pathway/iTS
GDSX Process
SPI/SCF
Kernel
Service Routines
USCODE
(Pseudo Calls)
(Utility Routines)
IOP
(such as CP6100)
Management
Programming
Interfaces
TACL Macros or
User Application
Pathway/iTS
TCP
Event
Report
POBJ
File
User's Business
Program
(SCREEN COBOL)
Communication
Line
IDS or
6530 or
$0
Event Collector
Conversati
onal
Control
3270
Run Unit
SCF
VST004.vsd
This figure shows a business-oriented Pathway/iTS application interfacing with GDSX.
GDSX interfaces with an I/O process that handles the lower levels of the
communication protocol. High-level communication functions, such as screen
presentation and line management, are handled by GDSX USCODE. In general, the
I/O process can be any access method provided by HP or any user-supplied process.
In fact, several access methods can be supported by a LINE^HANDLER.
The GDSX process has two parts, TSCODE and USCODE. TSCODE, the unshaded
part of the GDSX process in Figure 1-4, provides generic services that help you create
a multithreaded, fault-tolerant process. The TSCODE kernel provides coordination
among all components of GDSX. The SPI/SCF interface provides the capability to use
SCF or other applications to manage devices and lines opened by GDSX.
Extended General Device Support (GDSX) Manual—529931-001
1 -4
TSCODE Components
Overview of GDSX
USCODE consists of a number of procedures, called user exits, that are called by
TSCODE to handle data manipulation, protocol conversion, and/or message routing.
Two of the user exits are called the DEVICE^HANDLER and the LINE^HANDLER.
USCODE is typically written in TAL, compiled separately, and bound with TSCODE to
produce a functional GDSX front-end process. See Section 9, User Exit Descriptions
for a description of all the user exits.
TSCODE Components
This subsection describes the functional components provided within TSCODE.
Multithreading Functions
GDSX is a nonprivileged, multithreaded Guardian process that builds and manages
tasks within itself in a manner similar to that of an operating system. A GDSX task is
an independent job entity running within GDSX to perform a specific function. While
only one task can actually be executing at any given time, TSCODE coordinates the
processing of many simultaneously active tasks. TSCODE also picks up all system
messages and I/O requests from $RECEIVE, and wakes up and executes the
appropriate active task to process messages and requests.
A task is a running instance of either a TSCODE procedure or a USCODE procedure.
A TSCODE task is called a system task, and a USCODE task is called a user task. A
task has its own data stack, calls TSCODE procedures, and usually executes in a
infinite loop. Generally, a user task manages exactly one terminal, line, or process.
Fault-Tolerance Facilities
Fault tolerance is achieved by the use of process pairs and TSCODE-supported
checkpointing procedures. GDSX tasks cannot use normal Guardian checkpointing.
Each user task within a GDSX process runs with one of three possible levels of fault
tolerance, depending on the checkpointing done within the task.
If GDSX is run as a process pair, TSCODE creates a backup task and a GDSX backup
process. Without any user checkpointing, the backup task automatically checkpoints
to the backup GDSX process the initial values for all globals, the changing values for
control block variables, and the changing state of each configured task. The backup
process monitors the status of the primary GDSX process and takes over in case of
primary process failure, restarting from the beginning the user tasks that were active at
the time of failure and were doing no checkpointing. This is the default level of fault
tolerance.
TSCODE supports two additional levels of fault tolerance, depending on the type of
checkpointing done by a user task. If a task does type 1 checkpointing, its stack
images and task control block are copied to the backup process. After a takeover,
such a task is restarted at the instruction following the last type 1 checkpoint call. If a
task does type 2 checkpointing, its stack images, task control block, and allocated
memory pool buffers are copied to the backup process. After a takeover, such a task
Extended General Device Support (GDSX) Manual—529931-001
1 -5
External Interfaces
Overview of GDSX
is restarted at the instruction following the last type 2 checkpoint call, and all its
memory pool data is preserved.
External Interfaces
There are three standard external interfaces provided by GDSX:
•
•
•
The file system interface between TSCODE and business application processes.
The file system interface between TSCODE and the IOPs.
The SCF/SPI interface.
File System Interface Between TSCODE and Business
Application Processes
GDSX supports the following Guardian file-system calls from external processes:
Procedure Name
Function
CLOSE
Closes an open device
CONTROL
Performs device-dependent I/O operations
DEVICEINFO
Retrieves information about a device or subtype 30 process
OPEN
Establishes a communication path between an application process and
a device
SETMODE
Sets device-dependent functions
WRITE
Writes data from an array in an application program to an open device
WRITEREAD
Writes data to a device from an application program, then waits for
data to be transferred back from the device
Refer to the Guardian Procedure Calls Reference Manual for the detailed syntax,
parameter meanings, condition codes, and considerations for each call.
File System Interface Between TSCODE and IOPs
GDSX supports any type of terminal equipment for any vendor, so long as HP provides
the basic access method such as Envoy, TERMPROCESS, SNAX, and so on. GDSX
supports all the system procedure calls that are supported by the I/O processes.
GDSX can issue requests to IOPs according to what is supported by an I/O process;
each call is either preprocessed within GDSX or passed directly to the I/O process.
SCF/SPI Interface
This interface provides two types of access:
•
Conversational input by means of the Subsystem Control Facility (SCF) provided
by HP
Extended General Device Support (GDSX) Manual—529931-001
1 -6
External Interfaces
Overview of GDSX
•
Management programming control by means of a user-written management
application program that uses the Subsystem Programmatic Interface (SPI).
The interactive SCF interface includes generic commands used to configure and
manage SU, LINE, TASK, and PROCESS objects; control the tracing facility; and
display statistics on object status and resource allocation. You can also add your own
commands or modify attributes to extend functionality by customizing the
USER^ATTRIBUTES, USER^COMMANDS, and USER^REPLIES user exits (see
Section 9, “User Exit Descriptions,” for more information).
Use of the SPI interface to program customized subsystem management applications
or EMS filters requires use of some of the GDSX subsystem-specific token definitions
and EMS template definitions from the following files in the installed subvolume:
File Contents
GDSX File Name
EMS template definitions source file
SGDXTMPL
GDSX COBOL85 definitions
ZGDXCOB
GDSX DDL definitions
ZGDXDDL
EMS segment file
ZGDXSEGF
GDSX TACL definitions
ZGDXTACL
GDSX TAL definitions
ZGDXTAL
EMS template definitions object file
ZGDXTMPL
For further information on use of the EMS template files, see the DSM Template
Services Manual.
GDSX supports the following system procedure calls issued by management
applications:
Procedure
Function
CLOSE
Closes a GDSX process
OPEN
Establishes a communication path between an external process and a
GDSX process
WRITEREAD
Writes commands/control to a GDSX process, then waits for a response
from the GDSX process
GDSX can issue the following calls to another process, such as $0 for EMS event
logging:
Procedure
Function
CLOSE
Closes an application process
OPEN
Establishes a communication path between an external process and a
GDSX process
WRITE
Writes event information to an application process
WRITEREAD
Writes output to an application process, then waits for a response from the
application
Extended General Device Support (GDSX) Manual—529931-001
1 -7
Support for USCODE User Exits
Overview of GDSX
Support for USCODE User Exits
USCODE consists of 14 user exits called by TSCODE to allow you to implement
application-specific data manipulation, protocol conversion, and message switching.
All GDSX applications require the use of a DEVICE^HANDLER procedure, whether
user-customized or copied from an example program. The GDSX developer includes
stubs, such as those provided in the USKEL file in the installed subvolume, for all user
exits that do not provide user-defined function. After the USCODE is developed, it is
bound with TSCODE to form a runnable object file. See Section 9, “User Exit
Descriptions,” for descriptions of all user exits supported by GDSX.
Support for Service Routines
To help with the development of USCODE routines, the following service routines are
supported by TSCODE:
•
•
Utility procedures
Pseudo Guardian file system, Pathway/iTS, and TMF procedures
By calling one of these routines, a user task transfers control to the TSCODE kernel.
TSCODE carries out the requested processing internally or passes the procedure call
on to the operating system. When TSCODE subsequently wakes up the task to
resume execution, control is returned to the task at the instruction immediately
following the procedure call.
Utility Procedures
TSCODE provides utility procedures that can be used in developing USCODE.
The following groups of procedures are available to developers. See Section 8,
“Service Routines,” for descriptions of all procedures supported internally by
GDSX.
•
•
•
•
•
•
•
•
•
•
•
Bit map control
Break handling
Debugging facilities
Fault-tolerance facilities
Identifier manipulation
Intertask communication
I/O control block (IOCB) maintenance
List manipulation
Pool management
Semaphore control
Task maintenance
Extended General Device Support (GDSX) Manual—529931-001
1 -8
Hardware and Software Requirements
Overview of GDSX
Pseudo Procedures
TSCODE provides you with a set of pseudo procedure calls that, with some
exceptions, have the same parameters, syntax, meaning, and resultant capabilities as
their Guardian file system, Pathway/iTS, and TMF counterparts. They comprise a
layer of TSCODE software between USCODE and the Guardian file system that is
virtually transparent to USCODE, providing you with a consistent interface to facilities
similar to those of the HP NonStop operating system. This layer of software allows
TSCODE to keep track of each internal I/O operation and ensures that every I/O
operation is handled correctly at completion time.
Caution. The pseudo procedure calls must be used instead of their Guardian file system,
Pathway/iTS, or TMF procedure counterparts.
See Section 8, “Service Routines,” for descriptions of all procedures supported
internally by GDSX.
Hardware and Software Requirements
The GDSX D44.00 product runs only for D-series on NonStop operating system.
Although customized management applications may be developed to use the SPI
interface provided by GDSX, for standard external system management with the GDSX
D44.00 product you should use D30 SCP and D30 SCF. The Subsystem Control
Facility (SCF) Reference Manual describes the SCF, and the restrictions on using SCF
and SCP to manage applications in a network having C-series systems and D-series
systems.
You also need ZGDSSCF, the GDSX standalone product module (not bound in with all
other subsystem modules) that interfaces with the SCF kernel. This module is
automatically installed when you install SCF and SCP.
GDSX product modules should have their file security set for network execution. For
example, the file security should be set to xxNx, where x is any valid level of security.
The read, write, and purge security attributes are not significant, except that if the
SCFLIB library is moved from $SYSTEM.SYSTEM, the GDSX product module must
allow write access for the user who issues the first command to the product module.
To allow GDSX to send event messages to the primary collector ($0), EMS is
necessary.
Tools needed for USCODE development include a text editor, a TAL compiler, and the
Binder program. Tools that are helpful during USCODE development include the
PTrace trace formatter and the Inspect debugging program.
For GDSX applications requiring specific protocols, a particular controller, for example,
CP6100, may be necessary.
Extended General Device Support (GDSX) Manual—529931-001
1 -9
GDSX and Pathway/iTS
Overview of GDSX
GDSX and Pathway/iTS
The Pathway/iTS transaction processing software, together with its parent product,
TS/MP, provides an easy-to-use, powerful, and effective means of implementing online
transaction processing (OLTP) applications.
Pathway/iTS was designed to support the following terminals:
•
•
•
6510, 6520, 6530, 6540, and IBM 3270 terminals operating in block mode.
6510, 6520, 6530, 6540, and IBM 3270 terminals, or any other devices that the
Guardian file system recognizes as operating in conversational mode.
Intelligent devices such as personal computers, point-of-sale devices, ATMs,
communication lines, or Guardian processes, and the 6540 terminal operating as a
personal computer.
There is a wide variety of other general-purpose and special-purpose terminals in the
marketplace, and many of these terminals differ significantly from those that
Pathway/iTS supports. Despite not being able to interface Pathway/iTS to these
nonsupported terminals directly, many applications stand to benefit greatly from TS/MP
server class resource management and other features.
To widen the applicability of Pathway/iTS, the GDSX product was developed to serve
as an intermediate process between Pathway/iTS and an I/O process, handling the
terminal protocol on the I/O process side, and sometimes simulating a terminal
supported by Pathway/iTS on the TCP side. (The Pathway/iTS requester is usually
configured for Intelligent Device Support [IDS] mode, so that the program does not
control how data appears to the intelligent device, nor does it perform any other
device-dependent functions.)
Direct Terminal Access
In an application using Pathway/iTS and GDSX, the Pathway/iTS TCP simultaneously
supports multiple threads. Each thread is a continuing session with an I/O device,
typically a terminal. A SCREEN COBOL program controls data transmission with the
terminals. The terminals typically act as input devices for requests that are sent to
server classes for processing.
When an application using Pathway/iTS and GDSX is started, the GDSX process is
started first. For example, the following TACL RUN command can be issued to run a
GDSX object named $GDS:
> RUN GDSE /NAME $GDS, NOWAIT/
Then, depending on the application design, SCF might or might not be used to
configure subdevices (SUs) and lines (LINEs) before Pathway/iTS is started. For
Extended General Device Support (GDSX) Manual—529931-001
1-10
Direct Terminal Access
Overview of GDSX
example, if a GDSX application is designed to use SCF to preconfigure SUs T1 and T2
using devices $T1 and $T2, the following commands could be issued:
-> SCF
-> ADD SU $GDS.#T1
-> ADD SU $GDS.#T2
Note how the device names $T1 and $T2 become #T1 and #T2, respectively, when
combined with the GDSX process name in these commands. When GDSX receives
these commands, it derives the proper device names but does not open the files until
receiving an open message from Pathway/iTS.
Then, in the Pathway/iTS command interpreter, PATHCOM, you configure terminals to
be opened through GDSX. In this example, if a Pathway/iTS requester is to
communicate directly (without a LINE) with device $T2 through a GDSX process
named $GDS, the file name $GDS.#T2 is used in a series of PATHCOM commands:
=
=
=
=
=
SET
SET
SET
SET
ADD
TERM
TERM
TERM
TERM
TERM
TCP TCP-X
TYPE T16-6530:0
INITIAL LOGON-SCREEN
FILE $GDS.#T2
TX-2
TERM TYPE specifies the type of terminal that the GDSX process is simulating for
Pathway/iTS.
A session or thread is established when you issue the PATHCOM command:
= START TERM TX-2
Then the TCP opens the file specified in the configuration commands, $GDS.#T2 in
this example. Within the GDSX process, TSCODE receives the open message,
derives the device name $T2 from the message, and opens the device. GDSX then
creates a DEVICE^HANDLER task to modify the communication of the thread, by
datastream conversion, for example. For the life of the requester’s open, the thread
exists from the TCP requester through $GDS to $T2.
The typical transaction flow in this environment is shown in Figure 1-5.
Figure 1-5. Direct Terminal Access Transaction Flow
Open
$GDS.#T2
TCP
Open $T2
TCP
VST005.vsd
When a Pathway/iTS requester submits a request to GDSX, the request is picked up
by the DEVICE^HANDLER task associated with the requester, shown in Figure 1-6.
The task processes the request, and passes it to TSCODE, which passes it directly to
Extended General Device Support (GDSX) Manual—529931-001
1-11
Indirect Terminal Access
Overview of GDSX
the I/O process. When the I/O completes, the message is picked up by the
DEVICE^HANDLER task and passed back to the requester.
Figure 1-6. GDSX Without a LINE^HANDLER
$GDS
Requester
Pseudo$RECEIVE File
D^H Task
$RECEIVE
D^H Task
Requester
Pseudo$RECEIVE File
VST006.vsd
This type of direct interface between DEVICE^HANDLER tasks and I/O processes
requires the terminal to have a unique Guardian file name that can be opened directly
by TSCODE. Some access methods that support this kind of direct access by
Pathway/iTS are AM3270, ASYNC TERMPROCESS, X25AM, and CSS ASYNC
(6100). Each of these access methods requires a two-part file name for the device,
except ASYNC TERMPROCESS, which requires a one-part file name.
The following are examples of applications that can be handled with this type of
environment:
•
•
•
Accepting or initiating connections in X25AM
A two-step read in AM3270
Control-sequence translation for a nonsupported terminal, for example, the VT100
Indirect Terminal Access
There are applications, however, that involve shared data communication facilities
where the line (or message switching process) has a Guardian file name, but the
Extended General Device Support (GDSX) Manual—529931-001
1-12
Indirect Terminal Access
Overview of GDSX
individual devices on the line do not. Some data communication products that do not
allow direct addressing of terminals on line are:
•
•
•
•
CP6100 ADCCP/NRM
CP6100 Bisync Multipoint
Envoy
EnvoyACP/XF
GDSX applications using these products cannot use a direct interface of
DEVICE^HANDLER tasks with I/O processes—LINE^HANDLER tasks must also be
used to implement communication protocols and to manage the line so that different
threads accessing the line do not interfere with each other.
When an application using Pathway/iTS and GDSX is started, the GDSX process is
run first. For example, the following commands can be issued to run a GDSX object
named $GDS:
> PARAM MAXLINES 1
> RUN GDSE /NAME $GDS, NOWAIT/
The MAXLINES configuration parameter there is to be a maximum of one line in the
configuration.
Then SCF is used to configure the LINE and devices under the line, and to START the
LINE. Here is an example of a configuration having one LINE and three SUs under the
LINE:
->
->
->
->
->
->
SCF
ADD LINE $GDS.#LINE1, ACCESSNAME $IOP1
ADD SU $GDS.#LINE1.DEV1
ADD SU $GDS.#LINE1.DEV2
ADD SU $GDS.#LINE1.DEV3
START LINE $GDS.#LINE1
When the LINE is started in SCF, GDSX refers to the line’s access name (the file
associated with the LINE object), opens the file ($IOP1 in this case), and creates a
LINE^HANDLER task to manage communication with the devices on the line, as
shown in Figure 1-7. All devices on the LINE are then available for access.
Figure 1-7. Indirect Terminal Access Transaction Flow
Open
$IOP1
START LINE
$GDS.#LINE1
SCF
$GDS
IOP
VST007.VSD
Extended General Device Support (GDSX) Manual—529931-001
1-13
Indirect Terminal Access
Overview of GDSX
Using PATHCOM, you configure SUs that Pathway/iTS is to open through GDSX. For
example, if a Pathway/iTS requester is to communicate through a GDSX process
named $GDS with a subdevice DEV2 configured under line $LINE1, the file name
$GDS.#LINE1.DEV2 is used in the following PATHCOM commands:
=
=
=
=
=
SET
SET
SET
SET
ADD
TERM
TERM
TERM
TERM
TERM
TCP TCP-X
TYPE T16-6530:0
INITIAL LOGON-SCREEN
FILE $GDS.#LINE1.DEV2
TX-2
A session or thread is established when you issue the PATHCOM command:
= START TERM TX-2
Then the TCP opens the file specified in the configuration commands,
$GDS.#LINE1.DEV2 in this example. Within the GDSX process, TSCODE receives
the open message, derives the name $LINE1.#DEV2 from the message, and
determines from configuration information previously entered with SCF that device
$DEV2 is configured under line $LINE1. TSCODE sets a flag to indicate that the SU is
open and notifies the LINE^HANDLER of the open.
The LINE^HANDLER must handle the protocol so that requests are properly routed to
the SU device under the line. Then GDSX creates a DEVICE^HANDLER task to
modify the communication of the thread, by datastream conversion, for example. The
thread established among requester, DEVICE^HANDLER task, LINE^HANDLER task,
line, and terminal is fixed for the life of the open.
Typical transaction flow in this environment can be outlined as follows and is shown in
Figure 1-8:
•
•
•
When a Pathway/iTS requester submits a request to GDSX, the request is picked
up by the DEVICE^HANDLER task associated with the requester.
The task processes the request, and passes it to TSCODE, which queues the
message up to the LINE^HANDLER task associated with this DEVICE^HANDLER
task.
At this point the LINE^HANDLER task may, for example, issue one I/O request to
the target device, or the task may issue one I/O request to each device attached to
the line (as would be the case in a multidrop environment).
Extended General Device Support (GDSX) Manual—529931-001
1-14
Starting SU/Line With accessname NONE
Overview of GDSX
Figure 1-8. GDSX With a LINE^HANDLER
$GDS
TSCODE
Requester
D^H Task
Requester
$RECEIVE
D^H Task
IN^QUEUE^FI
LE^NUM
D^H Task
Requester
L^H Task
IOP
LINE^FILE^NUM
VST008.vsd
When the I/O operation(s) completes, the data is picked up by the LINE^HANDLER
task, sent through TSCODE to the DEVICE^HANDLER task, and then passed back to
the requester.
Starting SU/Line With accessname NONE
This feature provides support for preconfigured SUs and LINEs without the need for an
associated file as accessname. TSCODE will not open any device for a task configured
with accessname NONE. The Device^Handler/Line^Handler procedure gets called with
term^file^num/line^file^num set to -1.
The example below shows two SUs configured through SCF under the GDSX process
$gds:
-> add su $gds.#t1, accessname NONE
-> add su $gds.#t2, accessname $LT1
-> start su $gds.#t1
-> start su $gds.#t2
SU T1 has no associated IOP and is configured with accessname NONE (instead of
using a dummy $NULL process). SU T2 communicates through $gds to $LT1.
Extended General Device Support (GDSX) Manual—529931-001
1-15
Communicating Directly With a NonStop TS/MP
Server
Overview of GDSX
Communicating Directly With a NonStop TS/MP Server
In general, you do not need a SCREEN COBOL program to handle the data
transmissions with terminals. You can use the TS/MP pseudo procedure
^SERVERCLASS_SEND_ to send terminal data from GDSX directly to a TS/MP
server. Another pseudo procedure, ^SERVERCLASS_SEND_INFO_, can be used
when an error occurs to retrieve more information about the failed call to
^SERVERCLASS_SEND_.
See Section 8, “Service Routines,” for more information about these procedures and
Section D, “Using Pseudo Procedures in a TS/MP Environment,” for an example of
using them in a user task.
When to Use GDSX
GDSX is a very complex product, and should not be used to implement an application
if Pathway/iTS alone can handle the application requirements. For any of the following
reasons, however, a GDSX process may be used as a front end to a Pathway/iTS
application:
•
•
•
The specified data communications protocols are not supported by the
Pathway/iTS TCP. One example is HP OSI/TS.
Performance is critical. Interpreted SCREEN COBOL may not be efficient enough
when used to program a data communications protocol.
Simplicity of programming is critical. Handling a data communications protocol can
be awkward with SCREEN COBOL, which has a limited set of data types and
verbs.
For more information about alternatives to GDSX, including RSC, see Introduction to
NonStop Transaction Processing.
Extended General Device Support (GDSX) Manual—529931-001
1-16
2
Design and Development
This section contains design prerequisites and considerations for designing GDSX
applications; information on D-series features; steps for converting applications to use
extended features of the D-series operating system; considerations for coding,
compiling, and binding GDSX procedures; a description of the basic internal control
flow; procedure call and space restrictions; and information on memory pools, fault
tolerance, semaphores, linked lists, EMS filters, file-system errors, tracing, GDSX
internals, and the USAMPLE example program.
Prerequisites for Design and Development
A programmer developing a GDSX application must:
•
•
•
•
•
•
Be an expert TAL programmer
Know the requirements for the application to be developed
Know HP architecture and NonStop operating system programming
Be familiar with multithreaded processes
Be familiar with fault-tolerance principles, if the application is to run as a process
pair
Know data communications, if the application is to include protocol conversion
Before you begin designing a GDSX application, you should read Section 2, Design
and Development and do the tutorial in Section 4, DEVICE^HANDLER Example,
Running and Managing through Section 7, LINE^HANDLER Example, Design, unless
you are already proficient in GDSX programming. (If your application does not involve
a LINE^HANDLER, you do not need to do Section 6, LINE^HANDLER Example,
Running and Managing and Section 7, LINE^HANDLER Example, Design of the
tutorial.)
Finally, before designing a GDSX application, it is recommended that you consider
alternative implementations, such as Pathway/iTS IDS or conversational mode. See
When to Use GDSX on page 1-16.
Design Considerations
The following considerations and suggestions may be helpful when designing a GDSX
application.
•
Determine the environment in which GDSX is to function. Chart the overall
interprocess data flow. Include the interprocess flow of data from external
business application to GDSX to IOP/other process. Diagram the GDSX internal
data flow.
Extended General Device Support (GDSX) Manual—529931-001
2 -1
Design and Development
•
•
•
Design Considerations
Determine which D-series features will be used, including whether GDSX will run
at a low PIN or a high PIN. For information on using these features, see Using DSeries Features on page 2-3.
Complete a detailed business application design, including specifying:
°
°
°
Requester processes with which GDSX is to communicate
Pathway/iTS configurations, if applicable
Whether static or dynamic SUs will be used
Fully specify requirements for the proposed GDSX process, including:
°
Different types of tasks that are required. Normally there are two different
types, DEVICE^HANDLER tasks and LINE^HANDLER tasks. However, by
means of the term^type parameter (which may be determined by the SCF ADD
command’s SUTYPE attribute) passed to DEVICE^HANDLER tasks, you can
effectively create different types of DEVICE^HANDLER tasks by executing
different subsets of code within the DEVICE^HANDLER procedure.
°
Which user exits will be customized, and which exits will be stubs (see
Section 9, User Exit Descriptions for information on user exits).
°
Information that needs to be shared among tasks. Because multiple copies of
a USCODE procedure can be running at the same time in a multithreaded
GDSX environment, USCODE variables must be defined properly. If the value
of a variable is unique for each task at run time, declare the variable as a local
variable. If a variable must be shared among tasks, declare the variable as a
global. For read-only globals, the shared extended pool (see Memory Pools on
page 2-24) can be used. In order to properly update globals, semaphore
control may be necessary (see Semaphore Control on page 2-39).
Typically, user code has global data blocks, such as common^data and
user^private—see the example listings in Appendix B, USKELEX and
USKELEXC Listings. Global data within the common^data block can be
referenced and updated by both TSCODE and USCODE, while global data
within the user^private data block can be referenced and updated only by
USCODE tasks.
°
Which memory pools will be used, and what memory pool record structures will
be. See Memory Pools on page 2-24.
°
°
Special memory requirements.
°
Level of fault tolerance required for each user task in the GDSX process.
Weigh the need for fault tolerance against the overhead incurred with all three
levels of processing. See Fault Tolerance on page 2-28.
°
Whether to use the TMF product in USCODE to protect transactions.
Which files will be opened privately and which will be opened publicly. See the
considerations for ^OPEN and ^FILE_OPEN_ in Service Routines on page 8-1.
Extended General Device Support (GDSX) Manual—529931-001
2 -2
Design and Development
•
Using D-Series Features
Specify any necessary access method control details.
Using D-Series Features
A converted application is one that has been modified to use some extended feature of
the D-series operating system. An unconverted application uses no extended features
of the D-series operating system. TSCODE assumes that USCODE is converted if
and only if d^plus^enabled of the CONTROLFLAGS configuration parameter is set to
1. In other words, if USCODE is a converted application, d^plus^enabled is set to 1. If
USCODE is unconverted, d^plus^enabled is set to 0.
Converted Application Features
For converted applications, the following statements are true:
•
•
•
•
•
•
•
•
TSCODE assumes that USCODE is converted.
TSCODE supports GDSX being run either at a high PIN or at a low PIN (of course,
USCODE must be designed and coded to support the desired mode of operation).
TSCODE internally opens $RECEIVE with the file system procedure call
FILE_OPEN_, and intercepts and forwards D-series-format system messages to
individual USCODE tasks.
TSCODE maintains control blocks using the D-series format for internal data (for
example, process handles and process descriptors).
TSCODE assumes that any process identifier used by USCODE will be a D-series
process handle
TSCODE stores a file name as a variable-length string whose length in bytes is
specified as a separate integer value.
GDSX can open and be opened by external high PIN processes. GDSX can
create high or low PIN processes.
TSCODE allows USCODE to call all D-series service routines and most C-series
service routines. Illegal calls to other C-series service routines receive file-system
error 29 or 560.
Unconverted Application Features
For unconverted applications, the following statements are true:
•
•
•
TSCODE assumes that USCODE is unconverted.
GDSX may only be run at a low PIN.
TSCODE internally opens $RECEIVE with OPEN, and intercepts and forwards
C-series format system messages to individual USCODE tasks.
Extended General Device Support (GDSX) Manual—529931-001
2 -3
Design and Development
•
•
•
•
•
GDSX D44 Features Supported
TSCODE maintains control blocks using the C-series format for internal data (for
example, process ID).
TSCODE assumes that any process identifier used by USCODE is a C-series
process ID.
TSCODE stores file name information in a 12-word format (as in GDSX C30).
GDSX can be opened only by low PIN processes (except $ZNET); GDSX can
open any process except an unnamed, high PIN process.
TSCODE allows USCODE to call all C-series service routines and a few D-series
service routines. Illegal calls to other D-series service routines receive file-system
error 29 or 560. GDSX can create only low PIN processes.
GDSX D44 Features Supported
GDSX D44 supports the ability to run as a high PIN process. A GDSX process started
with a RUN command can run at a high PIN only if all of the following are true:
•
•
•
Its HIGHPIN object file attribute is set ON (as a result of settings made at compile
time or bind time).
Either the TACL #HIGHPIN built-in variable is ON or the HIGHPIN ON option is
specified when you run the GDSX process.
D^plus^enabled of the CONTROLFLAGS configuration parameter is set to 1.
In all other cases, the operating system runs GDSX at a low PIN. Even if all the above
conditions are true, if a high PIN is not available, GDSX runs at a low PIN.
GDSX D44 supports the ability to communicate with other processes, as follows:
•
•
•
Any process, whether named or unnamed, can open any GDSX process, except
for a high PIN (converted) process that is trying to open an unconverted GDSX
process. Because any GDSX process examines its openers, an unconverted
GDSX process cannot have a high PIN requester (see the discussion of
HIGHREQUESTERS in the Guardian Application Conversion Guide). Therefore,
settings of the HIGHREQUESTERS object-file attribute for a high PIN requester
have no effect in allowing the requester to open unconverted GDSX processes.
A GDSX process can open any other process, except for an unconverted GDSX
process that is trying to open an unnamed, high PIN process.
Because all GDSX processes must run named, a GDSX C30 process running on a
C-series system can open an unconverted GDSX D44 process or a converted
GDSX D44 process running at a low PIN. However, a GDSX C30 process cannot
open a converted GDSX D44 process running at a high PIN. An unconverted or
converted low PIN GDSX D44 process can open a GDSX C30 process running on
a C-series system, although a converted high PIN GDSX D44 process cannot
open a GDSX C30 process running on a C-series system.
Extended General Device Support (GDSX) Manual—529931-001
2 -4
Design and Development
•
Coding and Testing Considerations
D-series service routines, which are procedures that are new in the D44 RVU, as
well as C-series service routines, which are C-series compatible procedures that
can be called on either a D-series system or a C-series system. See Section 8,
Service Routines for descriptions of all these procedures.
°
Of the service routines, most of the utility procedures are available to any
GDSX application, except for a few procedures that are reserved for converted
applications. See Section 8, Service Routines for descriptions of all these
procedures.
°
In general, if GDSX is run converted, only the GDSX pseudo procedures that
correspond to the D-series Guardian, Pathway/iTS and TMF procedures are
available to USCODE (except for ^OPEN, ^CLOSE, ^FILEINFO, and
^FNAMEEXPAND). If other calls are attempted, TSCODE returns file-system
error 29 or 560. See Section 8, Service Routines for descriptions of all these
procedures.
°
In general, if GDSX is run unconverted, only the GDSX pseudo Guardian,
Pathway/iTS and TMF procedures that correspond to the C-series procedures
are available to USCODE (except for ^FILE_OPEN_, ^FILE_CLOSE_, and
^FILE_GETINFO_). If other calls are attempted, TSCODE returns file-system
error 29 or 560. See Section 8, Service Routines8 for descriptions of all these
procedures.
GDSX D44 supports both C-series and D-series file name structures and C-series and
D-series-format system messages. If GDSX is run as a converted process, system
messages passed to USCODE by TSCODE are in D-series format. If GDSX is run as
an unconverted process, system messages passed to USCODE by TSCODE are in
C-series format.
GDSX D44 supports the ability of a GDSX process to create high PIN processes.
GDSX D44 supports the ability of a GDSX process to access the file of size greater
than 4 GB using pseudo procedure call ^FILE_OPEN/ ^XFILE_OPEN.
Coding and Testing Considerations
The following considerations and suggestions may be helpful when coding, compiling,
binding, and testing a GDSX application. Guidelines for running GDSX and managing
it with SCF are provided in Section 3, Operations and Support
•
•
•
Before coding your application, install GDSX and run the example
DEVICE^HANDLER—see Section 4, “DEVICE^HANDLER Example, Running and
Managing,”and Section 5, DEVICE^HANDLER Example, Design
Read about the GDSX application generation process in Section 4,
DEVICE^HANDLER Example, Running and Managing and later in this section.
See Steps for Coding New Applications and Conversion on page 2-15 for the tasks
necessary to code a new GDSX application and to convert an existing application
to use the extended D-series features.
Extended General Device Support (GDSX) Manual—529931-001
2 -5
Design and Development
•
•
Coding the DEVICE^HANDLER
See Section 9, User Exit Descriptions for details on customizing other user exits
and providing stubs for the remaining user exits.
If possible, test DEVICE^HANDLER tasks by themselves, or with dummy
LINE^HANDLERs.
Coding the DEVICE^HANDLER
•
•
•
•
•
•
•
See Section 4, DEVICE^HANDLER Example, Running and Managing and
Section 5, DEVICE^HANDLER Example, Design of the tutorial and the USAMPLE
example program for examples. USAMPLE design is described in USAMPLE
Example Program on page 2-98.
See Section 9, User Exit Descriptions for a description of the DEVICE^HANDLER
user exit.
See Section 8, Service Routines for syntax of the utilities and pseudo procedures.
Use pseudo Guardian procedures instead of the Guardian counterparts. TSCODE
supports a set of pseudo Guardian procedures that correspond to the D-series
Guardian procedures and a set of pseudo Guardian procedures that map to the Cseries Guardian procedures.
Control block manipulation should not be necessary, but if it is, see Inspecting the
DEVICE^HANDLER Example on page 5-14 and Inspecting the LINE^HANDLER
Example on page 7-20.
Most DEVICE^HANDLER procedures are single-threaded. If your
DEVICE^HANDLER must be multithreaded, see the tutorial on the
LINE^HANDLER (which is multithreaded) in Section 6, LINE^HANDLER Example,
Running and Managing and Section 7, LINE^HANDLER Example, Design.
If you need to manage resources to be shared among tasks, use the INIT^SEM,
PSEM, VSEM procedures to be consistent with TSCODE—see Section 8, Service
Routines for procedure descriptions.
Any USCODE fault number must be greater than 100. Use only fault numbers
from 101–300 for a DEVICE^HANDLER.
Coding the LINE^HANDLER
•
•
•
See Section 6, LINE^HANDLER Example, Running and Managing and Section 7,
LINE^HANDLER Example, Design of the tutorial and the USAMPLE example
program for examples. You may wish to modify example programs or use them for
ideas. USAMPLE design is described in USAMPLE Example Program on
page 2-98.
See Section 9, User Exit Descriptions for a description of the LINE^HANDLER user
exit.
See Section 8, Service Routines for syntax of the utilities and pseudo procedures.
Use pseudo Guardian procedures instead of the Guardian counterparts. TSCODE
Extended General Device Support (GDSX) Manual—529931-001
2 -6
Design and Development
Debugging Your GDSX Application
supports a set of pseudo Guardian procedures that correspond to the D-series
Guardian procedures and a set of pseudo Guardian procedures that map to the Cseries Guardian procedures.
•
Any USCODE fault number must be greater than 100. Use only fault numbers
from 301–500 for a LINE^HANDLER.
Debugging Your GDSX Application
•
•
•
•
•
You can use a filter to display EMS messages. See EMS Filters and GDSX on
page 2-79.
You can use a trace in troubleshooting. See Tracing GDSX on page 2-80.
You can use INSPECT. The INSPECT labs in Section 5, DEVICE^HANDLER
Example, Design and Section 7, LINE^HANDLER Example, Design may be useful
as examples.
You can look up warning and error messages in Interpreting Console and EMS
Messages on page 3-16. A listing of “File-System Errors” appears later in this
section.
You can refer to GDSX Internals on page 2-90.
Run-Time Environment
GDSX is a nonprivileged, multithreaded, Guardian process that builds and manages
tasks within itself in a manner similar to the way an operating system handles tasks. A
GDSX task is an independent job entity running within GDSX to perform a specific
function. While only one task can actually be executing at any given time, the
TSCODE kernel coordinates the processing of multiple simultaneously active tasks,
swapping them in and out of the user data segment as necessary.
The TSCODE kernel provides the following functions:
•
•
•
•
•
Creating new tasks
Picking up all system messages and I/O requests from $RECEIVE
Dispatching (waking up and executing) the appropriate active task to process
messages and requests
Stopping tasks
Handling traps and errors
At any point in time, GDSX runs on behalf of a task unless:
•
•
The kernel is creating or stopping a task.
The kernel is preparing to dispatch a task.
Extended General Device Support (GDSX) Manual—529931-001
2 -7
System Tasks
Design and Development
•
The kernel is waiting for an internal resource or an I/O completion and no other
tasks are ready to dispatch.
A task is a running instance of either a TSCODE procedure or a USCODE procedure.
A TSCODE task is called a system task, and a USCODE task is called a user task. A
task has its own data stack, calls TSCODE procedures, and usually executes in a
infinite loop. Generally, a user task manages exactly one terminal, line, or process.
System Tasks
The TSCODE kernel includes the monitor and listener tasks, and the backup task if
GDSX is run as a process pair. Depending on the GDSX subsystem state, the kernel
may also include temporary system tasks. Following are descriptions of the different
types of system tasks.
Monitor Task
This task is created during GDSX process initialization and is always active thereafter.
There is only one monitor task per GDSX process, and it is always task number 1.
This task handles the SCF/SPI interface and message logging to the $0 collector. The
USER^ATTRIBUTES, USER^COMMANDS, and USER^REPLIES user exits, which
support user-customized EMS and SCF processing, are also handled by the monitor
task.
Listener Task
This task is created during GDSX process initialization and is always active thereafter.
There is only one listener task per GDSX process, and it is always task number 2.
The kernel forwards all system messages (except BREAK and 3270 status) received
by GDSX to the listener task. The listener task executes an endless loop that
processes or routes system messages such as:
ABEND
CLOSE
CONTROL
CPU DOWN
CPU RELOAD/UP
DEVICEINFO
NET MONITOR
OPEN
STOP
The Listener also acts as an agent for the kernel. When TSCODE receives a request
by means of $RECEIVE, it may be the case that resources required to process the
message (for example, pool space) are not currently available. In such cases, the
request is passed to the Listener, which acquires the missing resources before
forwarding the request to the appropriate task.
The listener task maintains a count of currently active system tasks (including Monitor,
Listener, and Backup if GDSX is running as a process pair). Upon receipt of a system
message that requires a system task to handle it, if five system tasks are active, the
Listener waits until one of the five tasks terminates before initiating the new task.
$RECEIVE is blocked while the Listener is waiting for an available task.
Extended General Device Support (GDSX) Manual—529931-001
2 -8
Design and Development
User Tasks
Backup Task
If GDSX is run as a process pair, TSCODE creates a backup task (task 3) during
GDSX primary process initialization, which in turn creates a GDSX backup process
and checkpoints data to the backup process. There is only one backup task per GDSX
process, and it is always active after it is started.
UserInit Task
This task exists temporarily upon startup of a GDSX process.
Netmon Task
When the listener task receives a NETMON system message (CPU UP or CPU
DOWN), this task is created temporarily to oversee the creation of a DOWNCPU task
or the processing of an UPCPU system message.
DownCPU Task
This task exists temporarily during the processing of a DOWNCPU system message.
Open Task
During an open of a line or device this task creates a new DEVICE^HANDLER task or
LINE^HANDLER task and then is deleted.
ProcDel Task
The Process Deletion task is created temporarily to oversee the stopping, cleanup, and
deletion of another task that is to be stopped or abnormally ended (abended).
User Tasks
Following are descriptions of the different types of user tasks:
DEVICE^HANDLER Task
A DEVICE^HANDLER is a required, user-customized procedure typically used to
modify the communication of each thread between a requester and another file (often a
terminal). Running copies of DEVICE^HANDLER code are called DEVICE^HANDLER
tasks. These tasks are separate entities although they all use the same
DEVICE^HANDLER procedure code. DEVICE^HANDLER tasks are also called term
tasks.
In a GDSX application there is usually one DEVICE^HANDLER task created for each
terminal or device configured. A DEVICE^HANDLER task is created when a requester
process opens a dynamic SU through GDSX or when a preconfigured device or
subdevice is started.
Extended General Device Support (GDSX) Manual—529931-001
2 -9
Design and Development
Overview of GDSX Processing
LINE^HANDLER Task
A LINE^HANDLER is an optional USCODE procedure typically used to implement data
communications protocols and to allow each requester thread to use a shared
resource (often a communications line) without allowing the threads to interfere with
each other. Running copies of LINE^HANDLER code are called LINE^HANDLER
tasks. These tasks are separate entities although they all use the same
LINE^HANDLER procedure code. LINE^HANDLER tasks are also called LINE tasks.
Using a LINE^HANDLER to provide line protocol functions is necessary only if the
access method to which GDSX interfaces does not provide these functions. For
example, LINE^HANDLER functions are required within GDSX where GDSX interfaces
to multidrop Envoy; however, they are not required where GDSX interfaces to AM3270.
In a GDSX application there is usually one LINE^HANDLER task created for each line
configured. A LINE^HANDLER task is created when a user starts a preconfigured line
by means of SCF. The maximum number of LINE^HANDLER tasks, specified by the
MAXLINES configuration parameter, is 15.
Although a LINE^HANDLER is often used to handle messages to or from a
communication line, a LINE^HANDLER procedure may also be used to route
messages to an external process.
Overview of GDSX Processing
TSCODE does the following at GDSX process initialization time:
1. Initializes configuration parameters from default values.
2. Calls the USER^INIT^CONFIG^PARAMS user exit.
3. Opens the $RECEIVE file for the GDSX process.
4. Calls the PROCESS^ASSIGNS user exit once for each ASSIGN command entered
from a TACL process before GDSX was started. If no such commands were
entered, this user exit is not called.
5. Calls the PROCESS^USER^PARAMS user exit once for each USERPARAM
defined in PARAM commands entered from a TACL process before GDSX was
started. If no such commands were entered, this user exit is not called.
6. Calls the USER^VERSION user exit.
7. Allocates memory for control blocks, memory pools, stack images, checkpointed
buffers, EMS log messages, and so on.
8. Initializes monitor and listener system tasks. Starts the listener task. If GDSX was
run as a process pair, a backup task is started.
9. Calls the USER^INITIALIZE user exit.
10. Starts the monitor task.
Extended General Device Support (GDSX) Manual—529931-001
2- 10
Design and Development
Overview of GDSX Processing
11. If GDSX is run as a process pair, the backup task starts the backup process, and
in the backup process TSCODE calls user exits in the following order:
a. USER^INIT^CONFIG^PARAMS
b. USER^VERSION
c. USER^INITIALIZE
12. If GDSX is run as a process pair, in the primary process TSCODE checkpoints
data to the backup, then calls USER^BACKUP.
When GDSX receives an open message for a file from an external process (for
example, a TCP dynamically opening a terminal), a user task is created. The listener
task creates an open system task to process the external open, and the task opens the
requested subdevice. Any errors encountered during the open are passed back to the
external process. If the open proceeds without error, the open task is relaunched as a
user task (either a DEVICE^HANDLER task or a LINE^HANDLER task).
User tasks never exit back to the procedure that first called them. Instead, they
execute in a perpetual loop, and when they require TSCODE services, they call an
appropriate TSCODE service routine (see Section 8, Service Routines). These service
routines provide facilities similar to those provided by the operating system, yet allow
TSCODE to keep track of each internal I/O operation and to ensure that every I/O
operation is handled correctly at completion time.
When a user task calls one of these routines, control is transferred to the TSCODE
kernel. TSCODE either passes the procedure call on to the operating system or
performs the requested function internally, returning immediately to the user task.
In other cases the routine has to wait for some external event (for example, the
completion of I/O). The service routine then transfers control to the kernel, which
determines whether another task is ready to run. (When TSCODE eventually wakes
up the calling task to resume execution, control is returned to the task at the instruction
immediately following the procedure call.) The kernel saves the current task stack and
then checks to see if another task is ready to run. If another task is ready, the kernel
restores the stack of the ready task and exits back into it. If no task is ready to run, the
kernel waits for I/O completion on any file. When an I/O completes, the kernel
determines which task initiated it (or in the case of $RECEIVE, which task the request
is directed to) and reinstates the task (by restoring the task stack and exiting back into
it).
If the external opener closes a file, the listener task places the user task that manages
the file in a stopping state so that the file may be closed and the task terminated. The
user task does not participate in this close process. However, TSCODE calls the
USER^STOP user exit to allow USCODE to clean up the file before TSCODE closes
the file and terminates the task.
Extended General Device Support (GDSX) Manual—529931-001
2- 11
Calling Restrictions
Design and Development
Calling Restrictions
User code is compiled to produce an object file that is bound with TSCODE, so there
are restrictions to which user code must conform.
Multithreaded operation would not be possible within GDSX if user tasks called
Guardian I/O procedures in a waited manner. For example, if a DEVICE^HANDLER
task called a waited READ, the whole process, not just the one DEVICE^HANDLER
task, would come to a halt, and the other tasks could not be serviced during the
suspension.
Therefore, TSCODE provides you with a set of pseudo Guardian, Pathway/iTS, and
TMF procedure calls that, with some exceptions, have the same parameters, syntax,
meaning, and resultant capabilities as their Guardian, Pathway/iTS, and TMF
counterparts. These procedures comprise a layer of TSCODE software between
USCODE and Guardian systems that is virtually transparent to USCODE, while
allowing TSCODE to support multithreaded operation and keep track of each internal
I/O operation. Pseudo procedures determine whether an operation is to be handled
completely within GDSX or is to be handled outside GDSX.
Caution. The pseudo Guardian, Pathway/iTS, and TMF procedure calls must be used instead
of their counterparts.
Note that a number of Guardian procedures—NUMIN, NUMOUT, MYTERM, and
PROCESSHANDLE_DECOMPOSE_, for example—are resident system procedures
and do not cause the GDSX process to be suspended. Therefore, they can be called
by USCODE. As a rule, if a Guardian call would suspend not just a task but the whole
GDSX process, do not use it.
Following is a list of pseudo procedure calls supported by TSCODE. (Many TSCODEsupported utility procedures do not have Guardian file-system counterparts, and are
not included here. See Section 8, “Service Routines,” for a description of all TSCODEsupported procedures.) An X at the end of or in the middle of a procedure name
indicates that both local-memory and extended-memory procedures are available. For
example, ^AWAITIO[X] indicates that the ^AWAITIO and ^AWAITIOX procedures are
available.
**
**
**
^ABORTTRANSACTION
^READ[X]
^AWAITIO[X]
^READLOCK[X]
^BEGINTRANSACTION
^READUPDATE[X]
^CANCEL
^READUPDATELOCK[X]
^CANCELREQ
^RECEIVEINFO
^CANCELTIMEOUT
^REPLY[X]
^CLOSE
^CONTROL
**
^RESUMETRANSACTION
^SERVERCLASS_DIALOG_ABORT_
Extended General Device Support (GDSX) Manual—529931-001
2- 12
Memory Management
Design and Development
*
^DELAY
^SERVERCLASS_DIALOG_BEGIN_
*
^DEVICEINFO2
^SERVERCLASS_DIALOG_END_
**
^ENDTRANSACTION
^SERVERCLASS_DIALOG_SEND_
**
^FILE_CLOSE_
^SERVERCLASS_SEND_
**
^FILE_GETINFO_
^SERVERCLASS_SEND_INFO_
*
^FILE_GETINFOBYNAME_
^SETMODE
**
^FILE_GETRECEIVEINFO_
^SETMODENOWAIT
^FILEINFO
^SETMYTERM
^FILE_OPEN_
^SETPARAM
^FNAMEEXPAND
^SIGNALINTERRUPT
^LOCKREC
^SIGNALTIMEOUT
^MYTERM
^UNLOCKREC
**
^NEWPROCESS
^WRITE[X]
*
^OPEN
^WRITEREAD[X]
*
^PROCESS_CREATE_
^WRITEUPDATE[X]
**
^PROCESS_STOP_
^WRITEUPDATEUNLOCK[X]
*
*
**
Procedures that usually cause a task to be suspended.
Procedures that are waited operations.
Suspension of a task is transfer of control to the TSCODE dispatcher, which may then
execute a different task; when the task resumes execution, control is returned to the
instruction immediately following the pseudo call.
Because a USCODE task must execute a statement that gives up control before
TSCODE switches to the next ready task, only these procedures marked with asterisks
plus the TSCODE-supported utility procedures ^CHECKPOINT, DO^CP, FAULT,
STOP^TASK, WAITED^IO[X], and WAIT^EVENT need to be considered when
determining when a task will be suspended.
USCODE must communicate with external requesters by calls to ^READUPDATE[X]
and REPLY[X] on pseudo-$RECEIVE files created and managed by TSCODE for the
DEVICE^HANDLER tasks. See the tutorial in Section 5, DEVICE^HANDLER
Example, Design for details.
Memory Management
Because the working stack images of tasks are swapped to and from an extended data
segment, I/O operations must be performed by means of global buffers, and large
amounts of data local to tasks are best maintained somewhere other than the tasks’
stack images. To facilitate the efficient use of memory by both TSCODE and
Extended General Device Support (GDSX) Manual—529931-001
2- 13
Intertask Communication
Design and Development
USCODE, TSCODE provides local memory pools and extended data segment memory
pools, as well as the following memory pool management procedures:
GETEXTPOOL
GETEXTPOOLX
GETLOCALPOOL
PUTEXTPOOL
PUTLOCALPOOL
In order to be consistent with TSCODE, when managing the available global memory
pools, USCODE should use these procedures rather than another means. For further
information on these procedures see Section 8, Service Routines For further
information on memory pools, see Memory Pools on page 2-24.
Although it is not generally advisable, USCODE can use its own extended segment
through calls to ALLOCATESEGMENT and USESEGMENT. The segment IDs
available to USCODE range from 0 through 1023. Such a segment cannot be
checkpointed with a call to ^CHECKPOINT(2), so this kind of space should be
considered temporary working storage.
Caution. TSCODE expects that if USCODE changes the segment ID from m to n, immediately
after USCODE next relinquishes control, the segment ID has been restored to m. Therefore,
once a user task is using its own segment, it must not relinquish control until the previous
segment ID has been restored.
Intertask Communication
TSCODE provides a set of procedures to support communication between TSCODE
and USCODE, and communication among user tasks. These procedures make it
possible for a DEVICE^HANDLER task to communicate with other DEVICE^HANDLER
or LINE^HANDLER tasks, and for a LINE^HANDLER task to communicate with other
LINE^HANDLER tasks.
The procedures also provide a mechanism for a LINE^HANDLER to efficiently handle
several different types of asynchronous events. The WRITE^ITC^MESSAGE[X]
procedure supports communication between any two user tasks. The procedures
supported are:
GET^ITC^FCB
SEND^ITC^MSG[X]
ITC^OPENX
WAIT^EVENT
^LISTEN
WAKE^TASK
NOTIFY^IO^COMPLETION
WRITE^ITC^MESSAGE[X]
In order to be consistent with TSCODE, when doing intertask communication,
USCODE should use these procedures rather than another means. For further
information on these procedures, see Section 8, Service Routines
Extended General Device Support (GDSX) Manual—529931-001
2- 14
Design and Development
Steps for Coding New Applications and Conversion
Steps for Coding New Applications and
Conversion
Whether you are developing new applications or converting an existing application, this
subsection describes the sequence of steps involved in (1) coding a new GDSX D44
application and (2) converting a GDSX D44 application to use extended D-series
features.
You can migrate an existing Basic GDS or GDSX C30 application to GDSX D10
without converting it to use the extended features of the D-series system. If you wish
to do this, follow the instructions in “Migrating From Basic GDS” or “Migrating From
GDSX C30” in the GDSX D10.00+ manual. If you have an existing Basic GDS or
GDSX C30 application and wish to use extended D-series features, first migrate the
application to GDSX D10 without converting to use extended D-series features (using
the instructions in “Migrating From Basic GDS” or “Migrating From GDSX C30” in the
GDSX D10.00+ manual), and then convert to use the D-series features as desired,
using the instructions in Conversion for Extended Features of D-Series Systems on
page 2-16 later in this section.
If you want to use the USAMPLE code without modification, then (1) use the OGDS
object file in the installed subvolume and (2) run GDSX. You can configure OGDS as
either converted or unconverted. See Running a GDSX Application on page 3-1.
Coding New Applications
Follow these steps when coding new applications:
1. Start by modifying GDSX example programs USKELEX, USKELEXC, or
USAMPLE on the installed subvolume. You can also begin with USKEL, the
skeleton file supplied in the installed subvolume. See The User Source File on
page 2-42.
2. See Data Declarations on page 2-16 for information on sourcing in definitions and
declarations.
3. Code as desired, creating a converted application that uses the D-series pseudo
Guardian procedures instead of the corresponding C-series procedures. That is,
instead of using C-series procedures ^CLOSE, ^DEVICEINFO2, ^OPEN,
^RECEIVEINFO, ^NEWPROCESS, and STOP (not a pseudo procedure), use the
corresponding D-series procedures ^FILE_CLOSE_, ^FILE_GETINFOBYNAME_,
^FILE_OPEN_, ^FILE_GETRECEIVEINFO_, ^PROCESS_CREATE_, and
^PROCESS_STOP_.
4. Use D-series file names and process identifiers as required. See the Guardian
Application Conversion Guide for detailed information.
5. Compile user code and bind with GDSX files. See The GDSX Generation Process
on page 2-40. The UBINDHI file from the installed subvolume may be used to set
the HIGHPIN object file attribute.
Extended General Device Support (GDSX) Manual—529931-001
2- 15
Design and Development
Conversion for Extended Features of D-Series
Systems
6. Run GDSX. See Running a GDSX Application on page 3-1. Ensure that
d^plus^enabled of the CONTROLFLAGS configuration parameter is set to 1.
Conversion for Extended Features of D-Series Systems
Follow these steps when converting your application to use the extended features of
the D-series systems:
1. Ensure that d^plus^enabled of the CONTROLFLAGS configuration parameter is
set to 1. There are several ways to do this. See Setting Configuration Parameters
on page 2-49.
2. Use the D-series pseudo Guardian procedures instead of the corresponding Cseries procedures. That is, instead of using C-series procedures ^CLOSE,
^DEVICEINFO2, ^OPEN, ^RECEIVEINFO, and ^NEWPROCESS, use the
corresponding D-series procedures ^FILE_CLOSE_, ^FILE_GETINFOBYNAME_,
^FILE_OPEN_, ^FILE_RECEIVEINFO_, and ^PROCESS_CREATE_. (Converting
^CLOSE procedure calls to ^FILE_CLOSE_ calls is optional, as the two
procedures are functionally equivalent.)
3. If the ^SETMYTERM procedure is used, the object name length parameter must
be supplied. If the GET^TASK^NAME or ^MYTERM procedures are called, invoke
them implicitly with an assignment statement instead of a CALL in order to obtain
the length of the object name.
4. Use D-series file names and process identifiers as required. Any process IDs and
12-word SU or LINE data structures must be changed. See the Guardian
Application Conversion Guide for detailed information.
5. Compile user code and bind with GDSX files. See “The GDSX Generation
Process” in Section 2. The UBINDHI installed subvolume file may be used to set
the HIGHPIN object file attribute.
6. Run GDSX. See Running a GDSX Application on page 3-1. You can run GDSX at
a high PIN or low PIN.
See Appendix B, USKELEX and USKELEXC Listings for USKELEXC, an example of
how to convert the USKELEX sample application to take advantage of the extended
features of the D-series systems. Wherever possible, C-series service routines in
USKELEX are replaced in USKELEXC by D-series service routines.
Data Declarations
TSCODE sources in global data declarations from the DCCBDECS, DGCBDECS, and
PEXTGDS files of the installed subvolume. These declarations define:
•
•
•
Configuration parameters
Control block tables
Memory pools
Extended General Device Support (GDSX) Manual—529931-001
2- 16
Design and Development
•
•
User Code Declarations
Resource maps
SPI definitions
Some of these declarations are public to USCODE (user code can source them in at
compile time). The data structures accessible to user code are:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
I/O control block template (iocb^template)
Device control block template (dcb^template)
Task control block template (tcb^template)
Line control block template (lcb^template)
Receive control block template (rcb^template)
File control block template (fcb^template)
Device control block address table (DCBTBL global)
Task control block table (TCBTBL global)
Line control block table (LINETBL global)
File control block table (FCBTBL global)
Map template structure for resource map usage
Configuration data template
Event mask definitions and event result literals
Guardian file error code literals
Caution. Before altering a global used by TSCODE, make sure you know what TSCODE is
doing with it.
User Code Declarations
Because multiple copies of a USCODE procedure can be running at the same time in a
multithreaded GDSX environment, USCODE variables must be defined properly. If the
value of a variable is unique for each task at run time, declare the variable as a local
variable. If a variable must be shared among tasks, declare the variable as a global.
For read-only globals, the shared extended pool (see Memory Pools on page 2-24)
may be used. For globals to be updated, semaphore control may be necessary (see
Semaphore Control on page 2-39).
Global Declarations
Typically user code has global data blocks, such as common^data and user^private—
see the example listings in Appendix B, USKELEX and USKELEXC Listings. (The
names common^data and user^private are used throughout this manual, although you
can use other names for these data blocks.) Global data within the common^data
Extended General Device Support (GDSX) Manual—529931-001
2- 17
User Code Declarations
Design and Development
block can be referenced and updated by both TSCODE and USCODE, while global
data within the user^private data block can be referenced and updated only by
USCODE tasks.
In all GDSX applications, user code must source in the three sections of the
DCCBDECS file listed on the first line of Table 2-1. These sections define the IOCB,
TCB, and FCB control structures shared by TSCODE and USCODE. A listing of
DCCBDECS is contained in Appendix C, DCCBDECS and ULHDECSE Listings.
Table 2-1. Global Declarations Sourced in by User Code
Description of Contents
File Name
Sections of File
Control block template definitions
DCCBDECS,
DCCBDEC2
IOCB^LAYOUT, TCB^LAYOUT,
FCB^LAYOUT
Control block template definitions
DCCBDECS,
DCCBDEC2
RCB^LAYOUT
Standard or user-modified Device
and Line control block template
definitions
DCCBDECS,
DCCBDEC2,
USKELDEC, or
ULHDECS
TEMPLATES
Structure used for calling
^FILE_GETRECEIVEINFO_
USKELDEC,
ULHDECS, or
ULHDECSE
GETRECEIVEINFO^TEMPLATE
Configuration template definition
DCCBDECS,
DCCBDEC2
CONFIG^TEMPLATES
Configuration template allocation
DCCBDECS,
DCCBDEC2
CONFIG^DATA
DEFINEs; literals; various globals
allocated
DCCBDECS,
DCCBDEC2
COMMON^DATA, ERRORS
External procedure declarations
EXTDECS0
DEBUG, NUMOUT, NUMIN
External procedure declarations for
TSCODE routines
PEXTGDS,
PEXTGDS2
(Entire file used)
Depending on application requirements, user code may source in the section of the
DCCBDECS file listed on the second line of the table. This section defines the RCB
control structure.
Depending on application requirements, user code may source in the
getreceiveinfo^template section of the ULHDECS, ULHDECSE, or USKELDEC
installed subvolume files. This structure may be useful if you are calling
^FILE_GETRECEIVEINFO_.
User code must source in the DCB and LCB control structures. The standard
declarations for these structures can be sourced in from the templates section of either
DCCBDECS or USKELDEC, an installed subvolume file that contains these two
structures. However, you may want to add some DEFINEs for the structures or modify
the standard template for a device control block. (The DCB can be modified to add
Extended General Device Support (GDSX) Manual—529931-001
2- 18
Design and Development
Space Usages and Limitations
scratchpad variables or user-defined attributes that are specific to a class of devices.)
To do this, you modify the USKELDEC file as desired and source in its templates
section at compile time.
Caution. Although the DCB template is user-modifiable, the LCB template is not.
If you are using either the USKELEX example program or the USKELEXC example
program for your user code, you source in the templates section of the ULHDECSE file
in the installed subvolume, which contains the standard LCB template and a modified
DCB template.
If you are using the USAMPLE example program for your user code, you source in the
templates section of the ULHDECS file in the installed subvolume, which contains the
standard LCB template and a DCB template modified for USAMPLE.
User code must source in the config^templates, config^data, common^data, and errors
sections from DCCBDECS. The config^templates section allows programmatic access
to the configuration parameters used by TSCODE. The config^data section contains
an allocation of the configuration template defined in the config^templates section.
(For a description of the variables defined see GDSX Configuration Parameters on
page 2-46.) Common^data contains some miscellaneous globals (including DCBTBL
and LINETBL) and DEFINEs. The errors section contains event mask definitions,
event result literals, and Guardian file error code literals.
From EXTDECS0, user code sources in the Guardian procedures that you intend to
use. PEXTGDS contains EXTERNAL declarations for all TSCODE procedures
callable from USCODE. All the pseudo procedures and the utility procedures are
declared in PEXTGDS.
If the GDSX application must access files of size greater than 4 GB, the user code
must source in DCCBDEC2.
PEXTGDS2 contains EXTERNAL declarations for all TSCODE2 procedures callable
from USCODE2. All the pseudo procedures and the utility procedures are declared in
PEXTGDS2.
Naming Conventions
When writing code, you are free to choose identifiers conforming to normal TAL rules.
If you use a local variable whose identifier starts with a circumflex character (^), be
sure that TSCODE does not use the identifier for a global variable.
Space Usages and Limitations
Because USCODE is bound with TSCODE to become a GDSX runnable unit, there are
limitations in code space and data space in user code. However, as multiple code
spaces are available, code space is not likely to be a problem.
Regarding the data space, GDSX uses a user data segment with a size of 64 pages.
TSCODE uses two extended segments—one for trace data (with trace^seg^id equal to
Extended General Device Support (GDSX) Manual—529931-001
2- 19
Design and Development
User Data Segment
1025) and one for various control and data structures. The latter segment ID
(ext^data^pool^seg^id) is 1024 by default, but can be specified by you with the
SEGMENTID configuration parameter. For further information, see the description of
the parameter later in this section.
Although it is generally not advisable, USCODE can use its own extended segment
through calls to ALLOCATESEGMENT and USESEGMENT. The segment IDs
available to USCODE range from 0 to 1023. The segment IDs from 1024 up are
reserved for TSCODE. A segment allocated by USCODE cannot be checkpointed with
a call to ^CHECKPOINT(2), so this kind of space should be considered temporary
working storage.
Caution. If a user task uses its own segment, it must not relinquish control until the segment
ID previously used by TSCODE has been restored. In other words, if TSCODE uses segment
m and transfers control to USCODE, when USCODE next relinquishes control to TSCODE,
TSCODE expects the segment ID to be m.
Caution. In general, in USCODE the dynamic allocation of extended memory (with an
extended pointer, for example) should be avoided, because the TAL compiler would allocate
such space in extended segment 1024, which is reserved for use by TSCODE.
For information on the five memory pools, see Memory Pools on page 2-24.
User Data Segment
The user data segment of the GDSX process is specified at bind time to have a size of
64K words. The size of various areas within the segment is determined by the
configuration parameters. (See GDSX Configuration Parameters on page 2-46.)
Figure 2-1 shows the usage of the user data segment, along with algorithms that
determine space allocations. The bold line below the free space area marks the
boundary between the lower 32K words and the upper 32K words.
The working data stack is limited to 2000 words. This stack area is the local variable
space used by an executing DEVICE^HANDLER or LINE^HANDLER task, plus a
reserved space (up to 350 words may be needed) for the executing task’s calls to
system and TSCODE procedures. Therefore, the maximum size of the task’s data
stack image (configuration parameter TASKSIZE) is 1650 words (equal to 2000
minus 350).
Caution. Exceeding these limits may produce unpredictable results at run time.
Extended General Device Support (GDSX) Manual—529931-001
2- 20
Extended Segment for Control Structures
Design and Development
Figure 2-1. User Data Segment
TSCODE global primary area
size = 128 words
User globals (bound in)
maximum size of user global primary area = 128 words
User global secondary area also available
Buffer pool
Area extends from end of user globals to %73000 (to 29.5K words)
Working data stack
maximum size = 2000 words
Free space (unused)
size = 524 words
Hash table used to search RCB pool
size = 524 words
LOG message buffer
size = 256 words
Message pool
Area extends from end of LOG message buffer to %177777 (64K words)
VST009.vsd
Extended Segment for Control Structures
For various control and data structures, GDSX allocates an extended segment with a
size determined by the configuration parameters. Unless you specify a different
segment by means of the SEGMENTID configuration parameter, segment ID 1024 is
allocated. (See Descriptions of Configuration Parameters on page 2-51.) If the space
is not available, GDSX will not run, and an internal error message is created (abend
error 30).
See Figure 2-2 for a summary of the contents of the extended segment. Areas
illustrated in this table have distinct boundaries and appear in the order shown, except
for those areas in the diagram from the table of checkpointed buffers down to and
including the statistics table (or the $RECEIVE queue if the statistics table is not
allocated), which are typically intermingled and checkerboarded over the space
allocated for all of them.
A user task is assigned space in the table of checkpointed buffers when it first calls
^CHECKPOINT(2). A user task is assigned space in the stack image area when it is
started; an equal amount of space will be allocated at the task’s first call to
^CHECKPOINT. The statistics table is allocated only if stats^flag is set (see the
description of CONTROLFLAGS on page 2-52); space in this table is assigned when a
LINE or a preconfigured SU is added. Unprinted log messages are stored in the LOG
message queue.
Extended General Device Support (GDSX) Manual—529931-001
2- 21
Extended Segment for Control Structures
Design and Development
Figure 2-2. Extended Segment for GDSX
Extended buffer pool
default size (in words) = 32K
Extended message pool
default size (in words) = 32K
TCB pool
TCB pool size (in bytes) = $LEN(TCB^TEMPLATE) *(MAXTASKS + 5)
IOCB pool
IOCB poolsize (in bytes) = $LEN(IOCB^TEMPLATE) *MAXIOCBS
RCV pool
RCV pool size (in bytes) = ( RECEIVEDEPTH + 1 * 2)
RCB pool
RCB pool size (in bytes) = $LEN(RCB^TEMPLATE) * (MAXOPENS +1)
FCB pool
FCB pool size (in bytes) = (MAXFILES + 1) *$LEN(FCB^TEMPLATE)
DCB pool
DCB pool size (in bytes) = (DCBTBL size) + $LEN(DCB^TEMPLATE) +
(MAXTERMS *($LEN(DCB^TEMPLATE) + (EXTSUSIZE * 2)))
where DCBTBL size is ((MAXTERMS + 1) * 4)
LDCB pool
LDCB pool size (in bytes) = *$LEN(LDCB^TEMPLATE) * (MAXTASKS +5)
LCB pool
LCB pool size (in bytes) = *$LEN(LINE^TEMPLATE) * MAXLINES
PCB pool
PCB pool size (in bytes) = *$LEN(PCB^TEMPLATE) * MAXPROCESSES
Table of checkpointed buffers
Table size (in words) = (TASKCPSIZE) * (MAXTASKS +5)
Stack image area
Area size (in words) = ((TASKSIZE + 14) *2) * (MAXTASKS +5)
System memory pool
(reserved for TSCODE)
Shared extended pool
Shared extended pool size (in bytes) = POOLSIZE * 2
Private extended pool
Private extended pool size (in bytes) = (TASKPOOLSIZE * 2) * MAXTASKS
$RECEIVE queue
$RECEIVE queue size (in bytes)= receivesize * (masktasks +5)
Statistics table (optional)
Statistics table size (in bytes) = $LEN(XSTATS^TEMPLATE) * (MAXTASKS +5)
LOG message queue
LOG message queue size (in bytes) = 16K
Checkpoint buffer (backup^cp^buffer) (allocated only if GDSX is running as process pair)
Checkpoint buffer size = MAXCPSIZE words
VST010.vsd
At process startup, TSCODE calculates the space required in extended memory for
each type of control block. Only after all calculations have been completed are
Extended General Device Support (GDSX) Manual—529931-001
2- 22
Design and Development
Extended Segment for Control Structures
allocations done for the pools. Equations for these calculations are given in Figure 2-2.
Calculations are made in the following order:
TCB
Task control block
IOCB
I/O control block
RCV
Receive control block
RCB
Requester control block
FCB
File control block
DCB
Device control block
LDCB
Logical device control block
LCB
LINE control block
PCB
Process control block
Generally, it is not necessary to override the size that TSCODE calculates for a pool,
but it can be overridden either by using a TACL PARAM command to assign a value to
the configuration parameter’s external name, or by assigning a value to a configuration
parameter’s internal name in the USER^INIT^CONFIG^PARAMS user exit. The
external names are:
MAXTCBPOOL
MAXIOCBPOOL
MAXRCVPOOL
MAXRCBPOOL
MAXFCBPOOL
MAXDCBPOOL
MAXLDCBPOOL
MAXLINEPOOL
MAXPCBPOOL
(For more information on these parameters, see GDSX Configuration Parameters on
page 2-46.) TSCODE will use the user-specified setting unless it determines that the
pool size would be insufficient, in which case TSCODE will use the value that it
calculated.
If the pool size specified by such a configuration parameter is too large (more than
7.5 megabytes), or if the size causes the running total calculated for control block
pools, the extended buffer pool, and the extended message pool to exceed 16,777,216
bytes, an error message is sent to the home terminal, and the GDSX process stops
with abend error 020. (The message is sent to the home terminal, because at
configuration time the monitor task, which normally handles EMS messages, is not yet
active.)
Possible configuration error messages are:
10002 maxTCBpool or Buffer/Msg pool too large
10003 maxIOCBpool or previous pools too large
10004 maxRCVpool or previous pools too large
Extended General Device Support (GDSX) Manual—529931-001
2- 23
Design and Development
10005
10006
10007
10008
10009
10010
10011
10012
Extended Segments for Trace Files
maxRCBpool or previous pools too large
maxFCBpool or previous pools too large
maxDCBpool or previous pools too large
maxLDCBpool or previous pools too large
maxLINEpool or previous pools too large
maxPCBpool or previous pools too large
Sum of all max***pools are > 16777216d
Sum of final EXT. MEM size > 16777216d
For example, if the TCB and IOCB pool sizes have been calculated, and the total
requirement for the TCB and IOCB pools, the extended buffer pool, and the extended
message pool exceeds 16,777,216 bytes, the following error message is sent to the
home terminal:
10003 maxIOCBpool or previous pools too large
If the total calculated for all the control block pools, the extended buffer pool, the
extended message pool, and the checkpoint buffer exceeds 16,777,216 bytes, error
message 10011 is sent to the home terminal. If the total calculated for all the areas to
be allocated in the extended segment exceeds 16,777,216 bytes, error message
10012 is sent to the home terminal.
The configured control block pool sizes may be displayed by issuing the following SCF
command at the SCF prompt:
-> INFO PROCESS $GDSX-process-name, DETAIL
where is the name you gave to the GDSX process.
Extended Segments for Trace Files
When the trace facility is turned on in the primary GDSX process, TSCODE allocates
an extended segment with segment ID 1025, a default size of 64 pages, and the
default file name TRACEP under the default subvolume. The SCF TRACE command
may be used to specify a different file name, and the USER^OPEN^TRACE^FILE
procedure may be used to specify a different file size. (For other information regarding
the trace facility, see Tracing GDSX on page 2-80.)
When the trace facility is turned on in the backup process, TSCODE allocates an
extended segment with segment ID 1025, a default size of 64 pages, and the file name
TRACEB under the default subvolume.
If the specified trace file does not exist, the GDSX process creates and uses the file. If
the default subvolume already has a file with the name specified and the file has not
been opened by another process, the GDSX process opens the file. If the specified
trace file is in use by any other process, the GDSX process will not initiate the trace.
Memory Pools
Because the working stack images of tasks are swapped to and from an extended data
segment during I/O operations, I/O must be performed to and from global buffers. To
facilitate buffer allocation and deallocation, TSCODE provides users with two local
Extended General Device Support (GDSX) Manual—529931-001
2- 24
Design and Development
Local Pools
memory pools within the user data segment—the buffer pool and the message pool—
and two pools in an extended segment (by default, segment ID 1024)—the shared
extended pool and the private extended pool—along with procedures to allocate and
deallocate space from these pools (for additional information about memory pools, see
Space Usages and Limitations on page 2-19). Besides these four pools, GDSX also
provides the extended buffer pool and the extended message pool (also by default in
the extended segment with ID 1024). The sizes of all these pools are determined at
GDSX initialization and are dependent on static configuration parameters (see GDSX
Configuration Parameters on page 2-46).
Caution. Pool space allocated by you must be deallocated (by a call to PUTLOCALPOOL or
PUTEXTPOOL—see Section 8, Service Routines for details) when it is no longer needed.
Pool space may be allocated by TSCODE on behalf of a user task (see the
considerations for ^READUPDATE[X] on page 8-61). However, this TSCODEallocated pool space must be deallocated by a user task when the space is no longer
needed. TSCODE deallocates a task’s pool space only when the task is stopped.
Then buffer space allocated by the task from any of the memory pools will
automatically be deallocated.
Caution. During execution of the PROCESS^ASSIGNS, PROCESS^USER^PARAMS,
USER^INITIALIZE, and USER^INIT^CONFIG^PARAMS user exits, buffers may be allocated
from memory pools, but when these procedures are exited, the buffers are automatically
deallocated by TSCODE.
You can view pool sizes by issuing the following SCF command at the SCF prompt:
-> INFO PROCESS $GDSX-process-name, DETAIL
Local Pools
The selection of the pool names, buffer pool and message pool, was arbitrary. For
GDSX applications there is no recommendation on how to use these two pools.
Buffer Pool
The buffer pool (also called the local buffer pool) is often used by USCODE for request
buffers. This pool is in the lower 32K of the user data segment, and contains
approximately 28,000 words. The entire 28K words of memory present in the buffer
pool may not be available to USCODE as TSCODE also allocates memory for itself
from this pool for processing any messages received by it. Hence, its recommended
that USCODE manage its processing using a maximum of 22K words from the buffer
pool. Memory allocated from this pool is byte addressable. The GETLOCALPOOL and
PUTLOCALPOOL procedures are used to allocate and deallocate space from this
pool.
Extended General Device Support (GDSX) Manual—529931-001
2- 25
Design and Development
Extended Memory Pools
Message Pool
The message pool (also called the local message pool) is used primarily for queuing
purposes. If data is received by GDSX but no recipient has been identified, the data is
temporarily stored in this pool. This pool is in the upper 32K of the user data segment
and contains approximately 32,000 words (see User Data Segment on page 2-20).
Memory allocated from this pool is only word addressable. The GETLOCALPOOL and
PUTLOCALPOOL procedures are used to allocate and deallocate space from this
pool.
Extended Memory Pools
USCODE can use memory pool space in the extended segment (by default, ID 1024)
in whatever ways you determine, except that the shared extended pool is intended to
hold information that is to be visible to all tasks, and the private extended pool should
be used by tasks to hold data that is not to be visible to other tasks. The selection of
the pool names, extended buffer pool and extended message pool, was arbitrary.
No mechanism for queuing of allocation requests or timeout is provided. For private
storage, such a facility has no purpose, because each task has its own individual pool.
Shared Extended Pool
The shared extended pool is intended to hold information that is to be visible to all
tasks. Memory allocated from this pool is byte addressable. The GETEXTPOOL[X]
and PUTEXTPOOL procedures are used to allocate and deallocate space from this
pool. It is your responsibility to manage this area.
Before issuing a call to GETEXTPOOL[X] for space in this pool, you specify the
maximum pool space to be used by setting a configuration parameter (see GDSX
Configuration Parameters on page 2-46). The maximum size of the shared extended
pool can be established by setting the POOLSIZE configuration parameter.
POOLSIZE specifies the maximum pool size (in words) that all user tasks can share.
TSCODE calculates an extended memory requirement of POOLSIZE * 2 bytes for the
shared extended pool. The default for POOLSIZE is 16,398 words. TSCODE will
allocate this pool unless the total for all the areas to be allocated in this extended
segment exceeds 16,777,216 bytes, in which case configuration error message 10012
is sent to the home terminal:
10012 Sum of final EXT. MEM size > 16777216d
Private Extended Pool
The private extended pool should be used by tasks to hold data that is not to be visible
to other tasks. Memory allocated from this pool is byte addressable. The
GETEXTPOOL[X] and PUTEXTPOOL procedures are used to allocate and deallocate
space from this pool.
Extended General Device Support (GDSX) Manual—529931-001
2- 26
Design and Development
Checkpointing Memory Pool Buffers
Before issuing a call to GETEXTPOOL[X] for space in this pool, the maximum size of
the private extended pool is established by setting the TASKPOOLSIZE configuration
parameter (see GDSX Configuration Parameters on page 2-46). TASKPOOLSIZE
specifies the maximum pool size (in words) that each user task is allowed to acquire
privately. TSCODE calculates an extended memory requirement of total size
(TASKPOOLSIZE * 2) * MAXTASKS bytes for all the private extended pools. The
default for TASKPOOLSIZE is 128 words. TSCODE will allocate this pool unless the
total for all the areas to be allocated in this extended segment exceeds 16,777,216
bytes, in which case configuration error message 10012 is sent to the home terminal:
10012 Sum of final EXT. MEM size > 16777216d
Extended Buffer Pool
This pool may be used as desired. Memory allocated from this pool is byte
addressable. The GETEXTPOOL[X] and PUTEXTPOOL procedures are used to
allocate and deallocate space from this pool.
The maximum size of the extended buffer pool can be established by setting the
MAXBUFPOOL configuration parameter (see GDSX Configuration Parameters on
page 2-46). The default for MAXBUFPOOL is 32,000 bytes, and the maximum is
7.5 megabytes. If the size specified for the extended buffer pool is too large,
configuration error message 10002 is sent to the home terminal:
10002 maxTCBpool or Buffer/Msg pool too large
Extended Message Pool
This pool may be used as desired. Memory allocated from this pool is byte
addressable. The GETEXTPOOL[X] and PUTEXTPOOL procedures are used to
allocate and deallocate space from this pool.
The size of the extended message pool can be established by setting the
MAXMSGPOOL configuration parameter (see GDSX Configuration Parameters on
page 2-46). The default for maxmsgpoolsize is 32,000 bytes, and the maximum is 7.5
megabytes. If the size specified for the extended message pool is too large,
configuration error message 10002 is sent to the home terminal:
10002 maxTCBpool or Buffer/Msg pool too large
Checkpointing Memory Pool Buffers
A call to ^CHECKPOINT(2) checkpoints all local and extended memory pool buffers
acquired by the calling task. If USCODE has allocated an extended segment (with an
ID in the range from 0 to 1023) through calls to ALLOCATESEGMENT and
USESEGMENT, such a segment is not checkpointed with a call to ^CHECKPOINT(2).
Because user tasks share the memory pools and would overwrite each other’s data if
they were allowed to checkpoint directly across to corresponding memory pools in the
backup process, pool buffers are checkpointed to a section of the backup process’s
Extended General Device Support (GDSX) Manual—529931-001
2- 27
Design and Development
Pool Checking
extended memory where each task has a separate, TASKCPSIZE-sized area for
checkpointing. Buffer images are copied, but to different addresses. Therefore, in the
event of a takeover, any memory pool buffer addresses that the task has stored in its
data stack are no longer valid.
A task recovers its buffer images via calls on ^RECLAIMBUFFER. This procedure is
passed (by reference) the word pointer to the data as it was allocated in the primary.
The task’s last checkpoint block in the (former) backup’s extended memory is searched
for an address match. When one is found, space in the specified buffer pool is
allocated and the data image is copied. Finally, the word pointer in the task’s stack is
updated to point to the new location of the data. See the description of
^RECLAIMBUFFER on page 8-64 for more information.
Pool Checking
If the poolcheck^flag (see the DEBUGFLAGS configuration parameter later in this
section) is set, each time a task is dispatched, TSCODE will check the buffer pool,
message pool, extended buffer pool, and extended message pool for corruption. If
corruption is detected, GDSX stops with abend error 230 or 231.
The poolcheck^flag can be set when debugging a program and turned off during
production to allow GDSX to run more efficiently.
Bounds^checking of the DEBUGFLAGS configuration parameter is used to indicate
whether TSCODE is to do bounds checking on buffers used during USCODE service
routine (pseudo procedure and utility procedure) calls. If this bit is set to 1, TSCODE
ensures that all buffers used for I/O are in global or extended memory, not in the
swappable stack. If this bit is set to 0, TSCODE does not check the location of the
buffers used. The default setting for this flag is 0. See also the description of
CHECK^BUFFER^BOUNDS on page 8-17.
Fault Tolerance
You can create different levels of fault tolerance by the use of process pairs and
TSCODE-supported checkpointing procedures. GDSX tasks cannot use normal
Guardian checkpointing. Each user task within a GDSX process runs with one of three
possible levels of fault tolerance, depending on the checkpointing done within the task.
Caution. TSCODE does not support the checkpoint facilities for dynamic tasks (those that are
not preconfigured) unless the DYNAMIC configuration parameter is set on. See DYNAMIC on
page 2-58.
Level 0 Fault Tolerance
If GDSX is run as a process pair, TSCODE creates a backup task (task 3) and a GDSX
backup process. Whether user tasks do any checkpointing, the backup task
checkpoints to the backup GDSX process the following items:
Extended General Device Support (GDSX) Manual—529931-001
2- 28
Design and Development
•
•
•
Level 1 Fault Tolerance
The initial values for all globals, except those in user-named or private global data
blocks
The changing values for control block variables, except task control block variables
The changing state of each configured task
The backup process monitors the status of the primary GDSX process and takes over
in case of primary process failure, restarting from the beginning the tasks that were
active at the time of failure and were not doing any checkpointing. For such tasks,
context is lost, and any data held in memory pool buffers at the time of failure is lost.
This default level of persistent operation for user tasks that do no checkpointing is
called level 0 fault tolerance.
Level 1 Fault Tolerance
When a task does type 1 checkpointing, its stack images and task control block are
copied to the backup process. After a takeover, such a task is restarted at the
instruction following the last type 1 checkpoint call. The task loses any data held in
memory pool buffers at the time of failure. This is called level 1 fault tolerance. Within
a process some tasks may be doing no checkpointing, in which case TSCODE
provides them with level 0 fault tolerance, while other tasks are doing type 1
checkpointing, providing level 1 fault tolerance.
Level 2 Fault Tolerance
If a task does type 2 checkpointing, its stack images, task control block, and allocated
memory pool buffers are copied to the backup process. After a takeover, such a task
is restarted at the instruction following the last type 2 checkpoint call, and all of the
task’s memory pool data is preserved. This is called level 2 fault tolerance. Within a
GDSX process some tasks may be doing no checkpointing while other tasks are doing
type 1 checkpointing, and still other tasks are doing type 2 checkpointing.
Fault-Tolerance Processing in GDSX Initialization
If GDSX is run as a process pair, TSCODE does the following at process initialization
time:
•
•
•
•
•
Initializes configuration parameters from default values.
Calls the USER^INIT^CONFIG^PARAMS user exit.
Opens the $RECEIVE file for the GDSX process.
Calls the PROCESS^ASSIGNS user exit once for each ASSIGN command entered
from the TACL prompt before GDSX was started. If no such commands were
entered, this user exit is not called at all.
Calls the PROCESS^USER^PARAMS user exit once for each USERPARAM
defined in PARAM commands entered from the TACL prompt before GDSX was
started. If no such commands were entered, this user exit is not called at all.
Extended General Device Support (GDSX) Manual—529931-001
2- 29
Design and Development
•
•
•
•
•
•
Fault-Tolerance Processing in GDSX Initialization
Calls the USER^VERSION user exit.
Allocates memory for control blocks, memory pools, stack images, checkpointed
buffers, EMS log message, and so on.
Initializes monitor and listener system tasks. Starts the listener task. If GDSX was
run as a process pair, a backup task is started. There is only one backup task per
GDSX process, and it is always active after it is started. The backup task is
awakened by the kernel when checkpointing or CPU monitoring needs to be done.
Calls the USER^INITIALIZE user exit. Data retrieved from external sources (such
as files) including semaphores that are located in a global data block cannot be
checkpointed in the USER^INITIALIZE user exit, because the backup GDSX
process is not running. Checkpointing this type of data must be deferred until the
USER^BACKUP exit is called.
Starts the monitor task.
Attempts to create a backup process. The backup task calls
PROCESS_CREATE_ to create a backup process.
After a successful PROCESS_CREATE_ call, brother (the backup process) calls
USER^INIT^CONFIG^PARAMS and opens $RECEIVE. (The processing by brother
follows the same general sequence described for the primary process in Overview of
GDSX Processing on page 2-10.)
Then the backup task opens brother and sends it a type -32768 system message.
This message contains the startup message data received by the primary process,
including TACL ASSIGN values and configuration parameters set by TACL PARAM
commands that brother requires for data space initialization.
Brother then calls the USER^VERSION user exit.
The backup task next closes brother, signaling that brother should proceed with data
space initialization.
Having initialized its data space, brother does the following:
•
•
•
•
•
Determines that it is in fact the backup.
Sets the global variable backup^process^flag to 1.
Bypasses the remainder of normal initialization (such as opening the log file) and
starts up the monitor task.
Calls the USER^INITIALIZE user exit. The monitor then creates the listener task
and backup task.
Idles in the listener task’s CHECKMONITOR procedure.
In the meantime, the backup task in the primary process has reopened brother. This
open is assigned to the backup process’s listener task (that is, any messages from the
primary will be handled by the backup’s listener). The backup task in the primary next
sets the global variable nonstop to one, signaling all other tasks that brother is up and
Extended General Device Support (GDSX) Manual—529931-001
2- 30
Checkpointing
Design and Development
running and that checkpointing of significant events is required. The backup task then
proceeds to bring brother up-to-date. (This process is similar to that involved in
reviving a mirrored volume.) The backup task makes a pass through the primary’s
data structures, including all the control blocks, checkpointing them to the backup.
When the backup task has completed its work, it sets the global variable
backup^process^flag to one and checkpoints it to brother. This signals brother that it is
now a consistent backup and is capable of takeover if necessary. The backup task in
the primary GDSX process then calls USER^BACKUP, giving users the opportunity to
checkpoint their own global data (declared in a named or private global data block).
An example of USER^BACKUP that checkpoints data input at a terminal is given in
USER^BACKUP on page 9-10. In the example, obtaining the checkpoint semaphore
is not necessary, because TSCODE is not checkpointing and no user task exists.
Also, calling DO^CP is not necessary, because after exiting USER^BACKUP a DO^CP
is done automatically by the backup task.
The USER^BACKUP procedure is only called once in the lifecycle of a GDSX process.
Checkpointing
USCODE cannot use normal Guardian checkpointing. The following TSCODEsupported procedures can be used:
•
•
•
•
•
GET^CPSEM. This procedure is used to acquire the checkpoint semaphore.
Q^CP[X]. This procedure is used to queue data to be checkpointed in the
checkpoint buffer.
^CHECKPOINT. This procedure acquires the checkpoint semaphore, queues the
task stack image and TCB (and all allocated memory pool buffers for a type 2
checkpoint), sends data to the backup process, releases the checkpoint
semaphore, and establishes a restart point for the task.
DO^CP. This procedure sends data to the backup process.
PUT^CPSEM. This procedure is used to release the checkpoint semaphore.
See Section 8, “Service Routines,” for detailed explanations of these procedures.
Within the extended segment used for control structures, the primary GDSX process
allocates a checkpoint buffer of length MAXCPSIZE (see GDSX Configuration
Parameters on page 2-46). This buffer is used to assemble checkpoint messages.
Access to this buffer and brother is controlled by the checkpoint semaphore cpsem.
Records sent to brother generally represent logical checkpoint requests instead of
physical checkpoints as when using the Guardian library checkpointing facility.
Each block sent to brother has the general format:
Word 0
Size of checkpoint block in words (n)
Words 1–n-1
One or more checkpoint records
Extended General Device Support (GDSX) Manual—529931-001
2- 31
Checkpointing
Design and Development
Each checkpoint record is structured as:
Word 0
Size of checkpoint record in words (m)
Word 1
Type of checkpoint record
Word 2
Address of entity being checkpointed
Words 3–m-1
Checkpoint data
For example, to checkpoint a file, TSCODE uses the following record:
Word 0
23
Word 1
Word 2
Words 3–10
Words 11–22
3
Address of associated FCB
FCB
File name
Upon receiving this checkpoint message, brother compares the message with its FCB.
(The FCB is logically structured into two parts: noncheckpointed and checkpointed.
While the primary GDSX process actually passes the entire FCB to its backup, the
backup copies only the checkpointed portion to the appropriate location in the FCB
pool.) If the message indicates that the file is in the same state (open or closed) in the
primary and backup processes, no action is taken. If the state is not the same, brother
opens or closes the file as appropriate. (In case brother cannot open the file, it replies
to the primary with a file number and the Guardian file error number returned from
OPEN. The primary issues an appropriate message and stops the backup process.)
Checkpointing User Global Data
Checkpoints including both global data and task stack are accomplished by the
following technique:
INT I^GOT^CP^SE M;
I^GOT^CP^SEM := GET^CPSEM;
CALL Q^CP(...); !As many as required to checkpoint globals
IF ^CHECKPOINT( ) THEN
! either type 1 or type 2
BEGIN
I^GOT^CP^SEM := 0;
.
Do takeover processing
.
END
ELSE
IF I^GOT^CP^SEM THEN
BEGIN
CALL GIVE^CPSEM;
I^GOT^CP^SEM := 0;
END;
Q^CP queues the global data in the checkpoint buffer (of size MAXCPSIZE). The call
to ^CHECKPOINT is used to queue the task’s stack image and TCB (and the task’s
allocated memory pool buffers if it is a type 2 checkpoint) in the checkpoint buffer and
Extended General Device Support (GDSX) Manual—529931-001
2- 32
Design and Development
Checkpointing
to send the data to the backup process. The call to ^CHECKPOINT establishes a
restart point at the instruction following the call.
Note that this example synchronizes the checkpointed globals with the state of the
calling task, but does not guarantee that the globals will be synchronized with the
states of other tasks. Synchronization of the globals with other tasks depends on the
application’s design.
For example, suppose task A checkpoints a global list and its stack image and then
adds item x to the global list. Then task B adds item y to the list and checkpoints the
global list and its stack image. If there is a takeover, item x is included in the list, but
task A tries to add it again.
Type 1 Checkpoint
When a user task does a type 1 checkpoint, the following actions occur. Note that
before CHECKPOINT(1) is called by a task, global data may have been put in the
checkpoint buffer by call(s) to Q^CP[X].
1. The semaphore cpsem is acquired.
2. The task’s stack image and TCB are placed at the next available word in the
checkpoint buffer. (Global data may have previously been queued in the buffer.)
3. The checkpoint buffer is written to brother.
4. The semaphore cpsem is released.
When the backup process receives the checkpoint message, any global data included
is copied to the same address in the backup. The checkpointing task’s stack image is
copied to an extended memory area of size specified by the TASKSIZE configuration
parameter. The backup copies the checkpointed portion of the TCB to the appropriate
location in the TCB pool.
Type 2 Checkpoint
A call to ^CHECKPOINT(2) checkpoints all local and extended memory pool buffers
acquired by the calling task. If USCODE has allocated an extended segment (with an
ID in the range from 0 to 1023) through calls to ALLOCATESEGMENT and
USESEGMENT, such a segment is not checkpointed with a call to ^CHECKPOINT(2).
When a task does a type 2 checkpoint, the following actions occur. Note that before
CHECKPOINT(2) is called by a task, global data may have been put in the checkpoint
buffer by call(s) to Q^CP[X].
1. The semaphore cpsem is acquired.
2. All memory pools are searched and all areas owned by the task are copied into the
extended memory area with address tcb.buffers.
Extended General Device Support (GDSX) Manual—529931-001
2- 33
Takeover Processing
Design and Development
The format of this area is:
cpbuffer.size
Total size of the checkpoint record
cpbuffer.task
Task number of checkpointer
cpbuffer.data
Buffer pool images
Each pool image is formatted as:
size
Size of checkpointed data
xaddr
Address of data in the primary buffer pool
data
Buffer pool data image
The last pool entry is a dummy and has a size of zero.
3. The area just constructed is moved to the next available word in the checkpoint
buffer. (Global data may have previously been queued in the buffer.)
4. The task’s stack image and TCB are placed in the checkpoint buffer.
5. The checkpoint buffer is written to brother.
6. The semaphore cpsem is released.
When the backup process receives the checkpoint message, any global data included
is copied to the same address in the backup. The checkpointing task’s stack image is
copied to an extended memory area of size specified by the TASKSIZE configuration
parameter. The backup copies the checkpointed portion of the TCB to the appropriate
location in the TCB pool. The task’s buffer images are copied to the TASKCPSIZE
area in extended memory.
User tasks would overwrite each other’s data if they were allowed to checkpoint
memory pool buffers directly across to corresponding addresses in memory pools for
the backup process. Suppose, for example:
1. Task 3 owns a buffer at address A and performs a type 2 checkpoint.
2. Task 3 deallocates the buffer at A.
3. Task 6 allocates a buffer at address A.
4. Task 6 performs a type 2 checkpoint.
If buffers were checkpointed directly, the data checkpointed by task 6 would have
overwritten the data checkpointed by task 3. Therefore, pool buffers are checkpointed
to a section of the backup process’s extended memory where each task has a
separate, TASKCPSIZE-sized area for checkpointing. Buffer images are copied, but to
different addresses, outside the memory pools.
Takeover Processing
If there is a takeover, any sync depth specified by external processes when GDSX is
opened has no effect. I/O operations of external requesters are not automatically
Extended General Device Support (GDSX) Manual—529931-001
2- 34
Design and Development
Takeover Processing
redirected to the backup GDSX process. Instead, GDSX emulates data
communications I/O processes: any outstanding requester I/O operation is terminated
with file-system error 210 (device ownership changed). For WRITEREADs and
READs, no data is returned to the requester. All I/O that the previously active tasks
had outstanding is canceled by TSCODE, and any semaphores that were held by
those tasks (including the checkpoint semaphore) are released.
Initializing Tasks
No matter what level of fault tolerance is supported by USCODE tasks, when the
backup takes over, the following occurs:
1. Those preconfigured tasks that were active in the primary but had not
checkpointed are queued for reinitialization. They will be restarted from their main
entry point.
2. Those tasks that had checkpointed and did not own a semaphore (either the
checkpoint semaphore or a user-defined semaphore) at their last checkpoint have
their takeover flag set (tcb.statex.takeover^bit) and are placed on the ready list.
They will be restarted at the instruction following the last checkpoint.
3. Those tasks that owned a semaphore (either the checkpoint semaphore or a userdefined semaphore) at their last checkpoint are placed on linked lists, one list for
each semaphore. They will be restarted at the instruction following the last
checkpoint.
4. The task at the head of each list is given the corresponding semaphore and is
placed on the ready list.
5. The remaining tasks in each list are queued for the corresponding semaphore with
tcb.statex.wait^cause set to sem^wait (a literal equal to 1).
USER^TAKEOVER
This user exit is called when system and user tasks have been created but are
stopped. Thus USER^TAKEOVER can alter memory contents prior to resumption of
normal operation.
Caution. In the USER^TAKEOVER procedure you cannot remap buffers allocated in the
former primary process (which existed before the takeover) by calling ^RECLAIMBUFFER,
because each active user task must reclaim its own buffers, and no user task is active during
execution of USER^TAKEOVER.
Creating a New Backup Process
After normal operation is resumed, the backup task attempts to create a new backup
process.
If the primary process failed for any reason other than CPU failure, the backup task in
the backup process waits 30 seconds and then attempts to create a new backup. If
Extended General Device Support (GDSX) Manual—529931-001
2- 35
Design and Development
Takeover Processing
this attempt fails, another attempt will be made after 15 seconds. This process
continues, with the time between attempts increasing to 30 seconds, then 45 seconds,
then 60 seconds, and so on, until the time between attempts reaches 10 minutes
where it remains until a backup is successfully created. (If the backup process fails for
some reason, the same process occurs as the primary attempts to create a new
backup.)
If the primary process failed due to CPU failure, the steps just described start 30
seconds after the CPU is reloaded.
In the backup process TSCODE calls user exits in the following order:
1. USER^INIT^CONFIG^PARAMS
2. USER^VERSION
3. USER^INITIALIZE
Then, in the primary process TSCODE checkpoints data to the backup and calls
USER^BACKUP.
^RECLAIMBUFFER
When a task does a type 2 checkpoint in the former primary, the task has its buffer
images copied to different addresses in the former backup. In the new primary,
therefore, any memory pool buffer addresses that the task stored in its data stack are
no longer valid.
A task recovers its buffer images by making calls to ^RECLAIMBUFFER. This
procedure is passed (by reference) the word pointer to the data as it was allocated in
the primary process. The task’s last checkpoint block in the former backup’s extended
memory of size TASKCPSIZE is searched for an address match. When one is found,
space in the specified buffer pool is allocated and the data image is copied. Finally,
the word pointer in the task’s stack is updated to point to the new location of the data.
For more information, see the description of the ^RECLAIMBUFFER procedure in
Section 8, Service Routines.
Caution. Following a takeover, if a task does not recover all its buffer images before it does a
type 2 checkpoint, those buffers not reclaimed are lost.
A Second Takeover
When designing a GDSX application, consider what happens if a takeover occurs, and
then a second takeover occurs before a task checkpoints.
Caution. Following a takeover, if a task recovers its buffer images with ^RECLAIMBUFFER
but does not do a type 2 checkpoint before a second takeover occurs, after the second
takeover the task’s buffer images are lost.
Extended General Device Support (GDSX) Manual—529931-001
2- 36
Design and Development
Transaction Management Facility
Transaction Management Facility
TMF protects transactions originating from the user tasks of a GDSX application.
GDSX supports four pseudo TMF procedures:
•
•
•
•
^ABORTTRANSACTION
^BEGINTRANSACTION
^ENDTRANSACTION
^RESUMETRANSACTION
Except for ^BEGINTRANSACTION, these pseudo procedures have the same syntax
and function as their TMF counterparts. You must set the TMF configuration
parameter to 2 to have these procedures work properly from a user task.
TMF Configuration Parameter
The TMF configuration parameter can be set for three processing modes:
Mode
Description
0
TSCODE does not permit any TMF processing from a user task, and it will not
pass a TMF transaction from an external process to another process, such as
Pathway. This is the default setting.
1
TSCODE does not permit any TMF processing from a user task; however, it will
pass a TMF transaction from an external process to another process.
2
TSCODE permits TMF processing from a user task, but it will not pass a TMF
transaction from an external process to another process.
See GDSX Configuration Parameters on page 2-46 for an explanation of how to set
configuration parameters.
Using the Pseudo Procedures
In a user task, you use ^BEGINTRANSACTION and ^ENDTRANSACTION to define
the elements of a transaction. When processing successfully completes for all
elements of the transaction, the transaction is said to be complete.
If any of the elements cannot be processed, the transaction is incomplete and an error
is returned to the user task. When an error is returned, the user task must determine
what to do next. One choice is to cancel the transaction with a call to
^ABORTTRANSACTION. Any elements of the transaction that were completed at the
time ^ABORTTRANSACTION is called are backed out of the system, as if the
transaction had never taken place. For example, data written to a database is
removed and the database is returned to the state it had before the new data changed
it.
If a user task needs to suspend processing of a TMF transaction to do processing
unrelated to the TMF transaction, the transaction’s status can be changed to pending
Extended General Device Support (GDSX) Manual—529931-001
2- 37
Linked Lists
Design and Development
by calling ^RESUMETRANSACTION with trans-begin-tag set to 0D. The user
task subsequently calls ^RESUMETRANSACTION with trans-begin-tag set to the
transid of the suspended transaction to change its status from pending to active.
An example of a GDSX application using the TMF pseudo procedures is given in
Appendix D, Using Pseudo Procedures in a TS/MP Environment. For more
information on TMF and the counterpart procedures of the pseudo procedures, see the
NonStop TMF Application Programmer’s Guide.
Linked Lists
TSCODE maintains a number of two-way linked lists to tie together control blocks
associated with a task, a file open, an I/O request, and so on. The linked lists have a
structure identical to that used by the operating system. TSCODE provides standard
procedures for USCODE-maintained linked lists:
•
•
•
INIT^[X]LIST
INSERT^[X]ITEM
DELETE^[X]ITEM
See Section 8, “Service Routines,” for detailed descriptions of these procedures.
Knowing how to follow these lists is often helpful in debugging GDSX applications.
Each list has a header and a number of items that are linked together. The header of a
linked list has two parts, header[0] and header[1]. Header[0] contains the address of
the first item in the list. If the list is empty, header[0] contains its own address.
Header[1] contains the address of the last item in the list. If the list is empty, header[1]
contains the address of header[0].
header[0]:
Address of first item in list. If list is empty, contains address of header[0].
header[1]:
Address of last item in list. If list is empty, contains address of header[0].
Each item in the list also has two parts, item-part[0] and item-part[1]. Item-part[0]
contains the address of the next item in the list. If this item is the last item in the list,
item-part[0] contains the address of header[0]. Item-part[1] contains the address of the
previous item in the list. If this item is the first item in the list, item-part[1] contains the
address of header[0].
item-part[0]:
Address of next item in list. If this item is last in list, contains address of
header[0].
item-part[1]:
Address of previous item in list. If this item is first in list, contains address of
header[0].
For lists in global memory, the header uses two words, and each item in the list uses
two words. For lists in extended memory, the header uses two doublewords, and each
item in the list uses two doublewords.
Extended General Device Support (GDSX) Manual—529931-001
2- 38
Design and Development
Example
Example
This example shows how TSCODE handles a linked list of IOCBs associated with a
task (a TCB). Each item in this list uses two doublewords.
! initialize tcb queue header
CALL INIT^XLIST (tcb.qh);
! As a result, the header points to itself.
! The following gives possible content.
!
!
Address
Content
!
! tcb.qh 588362
588362
! tcb.qt 588366
588362
!
! put iocb onto tcb queue
CALL INSERT^XITEM (tcb.qt, @iocb );
! As a result, the iocb is linked to the header.
! The following gives possible content.
!
!
Address
Content
!
!
tcb.qh 588362
589000
!
tcb.qt 588366
589000
!
! iocb.tcblink[0] 589000
588362
! iocb.tcblink[1] 589004
588362
!
! take iocb off tcb queue
CALL DELETE^XITEM (@iocb );
! As a result, the iocb is removed from the list.
!
!
Address
Content
!
!
tcb.qh 588362
588362
!
tcb.qt 588366
588362
!
! iocb.tcblink[0] 589000
0
! iocb.tcblink[1] 589004
588362
Semaphore Control
The purpose of a semaphore is to ensure the serial access of a shared resource. A
task is considered to have acquired a resource when it owns the semaphore
associated with the resource. TSCODE defines and maintains a checkpoint
semaphore to guarantee that no more than one task is doing a checkpoint at any given
time. A unique user-defined semaphore should be established for each resource
requiring exclusive access. For example, a semaphore may be used to control access
to a global variable updated by several tasks. Three utility procedures are available for
managing semaphores other than the checkpoint semaphore: INIT^SEM, PSEM, and
VSEM. (The checkpoint semaphore is defined by TSCODE and managed with the
GET^CPSEM and GIVE^CPSEM procedures.)
Extended General Device Support (GDSX) Manual—529931-001
2- 39
The GDSX Generation Process
Design and Development
A semaphore is first initialized with INIT^SEM. The semaphore may be defined either
in global or extended memory; however, it is recommended that it be declared in global
memory, within a user private block, for example. If a backup GDSX process exists,
the semaphore must be initialized in both primary and backup GDSX processes. The
semaphore may then be acquired by calls to PSEM and released by calls to VSEM.
A task takes control of a semaphore when a call to PSEM inserts the address of the
task’s TCB (@TCB) into the first element of the semaphore structure (described in the
table below). If the semaphore is already owned, a task requesting ownership will
have its TCB address inserted at the end of a linked list of tasks waiting for the same
resource (tasks are linked via tcb.locklink); the task’s tcb.statex.wait^cause is set to 1;
and the task waits on DISP^RESOURCE. The linked list is also part of the semaphore
structure, which has the three elements shown in the following table:
Variable Name
Description
Contents
sem.semowner
Current owner of
semaphore
0 if semaphore is available; owner’s TCB address
if semaphore is owned
sem.semhead
Head of the wait list
Address of SEMHEAD if no tasks are waiting;
otherwise, first waiter’s TCB address
sem.semtail
Tail of the wait list
Address of SEMHEAD if no tasks are waiting;
otherwise, last waiter’s TCB address
For any semaphore other than the checkpoint semaphore, the VSEM procedure is
used to release the semaphore so that other tasks can use the associated resource.
When a task calls VSEM, TSCODE verifies that the caller owns the semaphore, then
checks the semaphore’s wait list. If this list is not empty, the first task on the list is
given the semaphore and a DISP^RESOURCE event is caused for the task.
Caution. If a task owning one or more semaphores stops, the primary GDSX process stops.
If a task owning one or more semaphores faults with noretn equal to 1, the primary GDSX
process stops.
A description of how tasks owning semaphores are restarted following a takeover is
given in Takeover Processing on page 2-34.
A user may wish to define a semaphore to ensure serial I/O to a disk file. This may be
accomplished in the USER^INITIALIZE exit by calls on ^OPEN and INIT^SEM to open
the disk file and initialize a semaphore for the file. See the example in the
considerations for the ^OPEN procedure in Section 8, Service Routines.
The GDSX Generation Process
Every runnable GDSX process is a combination of code supplied by HP and usersupplied code. The user-supplied code is typically written in TAL. (Only USCODE
written in TAL has been tested; although USCODE may be written in other languages,
GDSX has not been tested with other languages.) When your source code file is
compiled, declarations contained in files supplied by HP (DCCBDECS and PEXTGDS)
are sourced in (see Figure 2-3 on page 2-42); depending on the application, userExtended General Device Support (GDSX) Manual—529931-001
2- 40
Installed Subvolume Files
Design and Development
supplied declarations may also be sourced in from ULHDECS, ULHDECSE,
USKELDEC, or a user-supplied declaration file with a different name. See User Code
Declarations on page 2-17 for more information on files used during source code
compilation.
The object code file resulting from the compilation, named USCODE in Figure 2-3 on
page 2-42, is then bound with TSCODE, the object code file supplied by HP. A
BINDER IN file is commonly used for this step. The result of binding USCODE with
TSCODE is a runnable GDSX object file.
Installed Subvolume Files
When generating a GDSX process, you normally use the following files from a GDSX
installed subvolume:
File
Description
DCCBDECS
Source file containing global variables and other common declarations
DCCBDEC2
Source file containing global variables and other common declarations to
support access to a file of size greater than 4 GB
PEXTGDS
Another source file, containing external declarations for procedures within
TSCODE
PEXTGDS2
Another source file, containing external declarations for procedures within
TSCODE2
UBUILD
Command (OBEY) file used to compile your program
TSCODE
Object code supplied by HP; you cannot modify this file
TSCODE2
Object code supplied by HP provides support for accessing file of size
greater than 4 GB
ubind
BINDER IN file used to bind TSCODE with USCODE, producing a
runnable GDSX object file named OGDS
UBINDHI
Same as the UBIND file, except that it includes the SET HIGHPIN ON
command
Extended General Device Support (GDSX) Manual—529931-001
2- 41
The User Source File
Design and Development
Figure 2-3. GDSX Generation Process
Installed Subvolume
DCCBDECS
?SOURCE
?SOURCE
(Optional)
TSCODE
PEXTGDS
?SOURCE
User
Source File
ULHDECS
or
TAL
USKELDEC
USCODEE
BINDER
IN File
BIND
Runnable
GDSX
Object
VST011.vsd
The User Source File
The user source code file must contain all the user exits (procedures) called by
TSCODE. (See Section 9, User Exit Descriptions) Your user code may have been
prepared by modifying USKELEX, USKELEXC, or USAMPLE, or your coding may
have started with USKEL, the user code skeleton file (containing user exit stubs)
supplied in the GDSX installed subvolume.
Extended General Device Support (GDSX) Manual—529931-001
2- 42
Design and Development
Compiling
User code must source in certain sections of the DCCBDECS and EXTDECS0 files, as
well as the PEXTGDS file. (See User Code Declarations on page 2-17 for details.)
To access format 2 files greater than 4 GB, the user code must source in sections of
the DCCBDEC2 and PEXTGDS2 file.
User code must also source in the DCB and LCB control structures. There are four
ways to do this:
•
•
•
•
The standard declarations for these structures can be sourced in from the
templates section of either DCCBDECS or USKELDEC, an installed subvolume file
which contains these two structures.
If you want to modify the DCB control structure, you can change the USKELDEC
file as desired and source in its modified templates section at compile time.
If you are using either the USKELEX example program or the USKELEXC example
program for your user code, you source in the templates section of the
ULHDECSE file (in the installed subvolume), which contains the standard LCB
template and a modified DCB template.
If you are using the USAMPLE example program for your user code, you source in
the templates section of the ULHDECS file (in the installed subvolume), which
contains the standard LCB template and a DCB template modified for USAMPLE.
Compiling
When you compile your user code, the PEXTGDS file, sections of the DCCBDECS file,
and—if you modified the templates section of DCCBDECS—the USKELDEC (or
ULHDECSE, or ULHDECS) files are sourced in, and the resulting object code is
named USCODE. (To access format2 files of size greater than 4 GB, the user code
must source in sections of the DCCBDEC2 and PEXTGDS2 file. The resulting object
code is named USCODE2)
To facilitate the compiling and binding procedures, you can use UBUILD and UBIND
files. While in the subvolume where you wish to work, copy the UBUILD and UBIND
files from the installed subvolume.
Edit UBUILD to assign SSV1 to the installed subvolume, and assign SSV2 to
$SYSTEM.SYSTEM. If you have source files in the subvolume where you are
working, you can assign SSV0 to the subvolume.
Extended General Device Support (GDSX) Manual—529931-001
2- 43
Compiling
Design and Development
For example, you could create the following UBUILD file:
Comment*********************************************************
Comment *
UBUILD Build Example USCODE from USAMPLE
(16Mar93) *
Comment *
Aded a compilation step to create USCODE2 (03Feb05) *
Comment*********************************************************
Clear
Comment
Comment
All
Assign SSV1 TO GDSX volume.subvolume
for ULHDECS, DCCBDECS, ZGDXTAL, PEXTGDS and USAMPLE
Assign SSV1,< vol>.< subvol>
Comment
Comment
ASSIGN SSV2 TO EXTDECS0 location
Assign SSV2,$System.System
Comment
Comment
location
ASSIGN SSV3 TO SPI subvolume for ZCOMTAL, ZSPITAL
Assign SSV3,$System.Zspidef
Comment
Tal /In Usample,Mem
64/uscode;Symbols,Inspect,NoCode,NoIcode,NoMap
Clear
Comment
All
Compilation Step to create USCODE2
Tal /In Usample2,Mem
64/uscode2;Symbols,Inspect,NoCode,NoIcode,NoMap
Clear All
Comment
Compilation Step to create USCODE2
Tal /In Usample2,Mem
64/uscode2;Symbols,Inspect,NoCode,NoIcode,N
oMap
Clear All
In this example, the user code file is named USKEL1, and the object file is named
USCODE. An OUT file is used to capture the compile listing. If your program has
been converted to run at a high PIN, you can set the HIGHPIN object-file attribute with
the following statement:
> TAL /IN USKEL1, MEM 64, OUT $S.#USKEL1/ USCODE; HIGHPIN
After creating UBUILD, issue the command OBEY UBUILD to compile the source code
file and produce the object file.
Extended General Device Support (GDSX) Manual—529931-001
2- 44
Binding
Design and Development
Binding
Next you use the UBIND file to bind TSCODE and USCODE and TSCODE2 with
USCODE2. UBIND contains the following commands
COMMENT -- Make sure current default volume contains tscode and
uscode obje
cts
add *
from tscode
add *
from uscode
, delete
set data 64 pages
set inspect on
set saveabend on
set subtype 30
build OGDS
!
COMMENT -- Make sure current default volume contains TSCOD2 &
USCODE2 objects
add
*
from tscode2
add
*
from uscode2
, delete
set data 64 pages
set inspect on
set saveabend on
set subtype 30
build GDS2
!"
The UBINDHI file is the same as the UBIND file, except that it includes the SET
HIGHPIN ON command used to set the HIGHPIN object-file attribute at bind time.
For this example, the resulting GDSX object file is called OGDS. TSCODE should be
added before USCODE so that TSCODE is loaded into the first code segment. The
SET SUBTYPE 30 command makes it possible for the GDSX process to receive and
respond to device type requests from other processes. For more information about the
BIND program, see the Binder Manual.
Before using the UBIND file, depending on the location of the TSCODE file, you may
need to qualify the TSCODE file name in the first command. To produce the runnable
object file, issue the command:
> BIND /IN UBIND/
You may want to include an OUT file in this command in order to capture binding
process information or to speed up the binding process.
Extended General Device Support (GDSX) Manual—529931-001
2- 45
GDSX Configuration Parameters
Design and Development
GDSX Configuration Parameters
GDSX uses configuration parameters to control memory allocation and numerous
aspects of the run-time environment (RTE). Some configuration parameters are called
static, because once their values are determined at process creation time. They
cannot be changed for that process. The other configuration parameters are called
dynamic, because their values can be changed after the process has been initialized.
Table 2-2 and Table 2-3 contain information about the static and dynamic configuration
parameters for GDSX. The first column of the tables gives the external parameter
names used when setting parameter values by means of an SCF or TACL PARAM
command.
The second column lists the internal DEFINE names used when setting parameter
values in USCODE (usually within the USER^INIT^CONFIG^PARAMS user exit).
These globals are defined in the config^params^template STRUCT of the
config^templates section of DCCBDECS (see Appendix C, DCCBDECS and
ULHDECSE Listings).
Each internal parameter name listed in the third column is defined in terms of a
STRUCT variable. For example,
CONFIG^PARAMS.term^data
An asterisk in the Default Value column indicates that the default value is calculated by
TSCODE according to an equation. The equation is given with the parameter’s
description later in this section.
Table 2-2. Static Parameters (page 1 of 3)
External
Parameter
Name
Internal
DEFINE Name
CONFIG^
PARAMS Name
Default
Value
Range
BACKUPCPU
brother^cpu^no
N.A.
-1
0–15
EXTSUSIZE
termdata
term^data
8 words
0–64 words
MAXBUFPOOL
maxbufpoolsize
maxbufpool^size
32,000
bytes
Up to 7.5
megabytes
MAXCPSIZE
max^cp^wds
max^chkpt^wds
4096 words
512–16,364
words
MAXDCBPOO
L
maxdcbpoolsize
maxdcbpool^size
*
Up to 131,064
bytes
MAXFCBPOO
L
maxfcbpoolsize
maxfcbpool^size
*
Up to 131,064
bytes
MAXFILES
maxfiles
maximum^files
48 files
10–2048 files
MAXIOCBPOO
L
maxiocbpoolsize
maxiocbpool^size
*
Up to 131,064
bytes
MAXIOCBS
maxiocbs
maximum^iocbs
128 I/Os
128–2047 I/Os
Extended General Device Support (GDSX) Manual—529931-001
2- 46
GDSX Configuration Parameters
Design and Development
Table 2-2. Static Parameters (page 2 of 3)
External
Parameter
Name
Internal
DEFINE Name
CONFIG^
PARAMS Name
Default
Value
Range
MAXITC
maxitc
max^itc
0
0–1020 tasks
MAXLDCBPO
OL
maxldcbpoolsize
maxldcbpool^size
*
Up to 131,064
bytes
MAXLINEPOO
L
maxlinepoolsize
maxlinepool^size
*
Up to 131,064
bytes
MAXLINES
maxlines
maximum^lines
0 L^H tasks
0–15 tasks
MAXLINKS
max^links
maximum^links
MAXTASKS
From 1 to the
system
configured limit
MAXMSGPOOL
maxmsgpoolsize
maxmsgpool^size
32,000
bytes
Up to 7.5
megabytes
MAXOPENS
maxopens
maximum^opens
48 openers
2–1169 openers
MAXPCBPOO
L
maxpcbpoolsize
maxpcbpool^size
*
Up to 131,064
bytes
MAXPROCESSES
maxprocesses
maximum^processe
s
2 processes
2–1024
processes
MAXRCBPOO
L
maxrcbpoolsize
maxrcbpool^size
*
Up to 131,064
bytes
MAXRCVPOO
L
maxrcvpoolsize
maxrcvpool^size
*
Up to 131,064
bytes
MAXTASKS
maxtsk
maximum^tasks
34 tasks
7–846 tasks
MAXTCBPOO
L
maxtcbpoolsize
maxtcbpool^size
*
Up to 131,064
bytes
MAXTERMS
maxterms
maximum^terms
32 SUs
2–1128 SUs
NONSTOP
nonstop^param
N.A.
0 (OFF)
0–1
POOLSIZE
poolsize
pool^size
16,392
words
Configuration
dependent
PROCNOWAIT
proc^nowait
procedure^nowait
0 (OFF)
0–1
RECEIVEDEPTH
receivedepth
receive^depth
78
messages
16–255
messages
RECEIVESIZE
recvsz
recvsize
4096 bytes
1024–16,384
bytes
SEGMENTID
segment^id
segment^number
1024
1024 or
> 1025
SERVER
server
server^flg
0 (OFF)
0-1
Extended General Device Support (GDSX) Manual—529931-001
2- 47
GDSX Configuration Parameters
Design and Development
Table 2-2. Static Parameters (page 3 of 3)
External
Parameter
Name
Internal
DEFINE Name
CONFIG^
PARAMS Name
Default
Value
TASKCPSIZE
cpcontextsz
cp^context^sz
2048 words
Configuration
dependent
TASKPOOLSI
ZE
taskpoolsize
task^pool^size
128 words
Configuration
dependent
TASKSIZE
tsksz
task^size
512 words
128 words;
configuration
dependent
TMF
tmf
tmf^flag
0 (OFF)
0-2
Range
* Calculated according to an equation given in the parameter descriptions in Descriptions of Configuration
Parameters on page 2-51
Table 2-3. Dynamic Parameters (page 1 of 2)
External
Parameter
Name
Internal DEFINE Name
CONFIG^
PARAMS Name
Default
Value
Range
ASSOCIATIVE
associative
associative^term
0 (OFF)
0–1
Autostop
autostop
auto^stop
0 (OFF)
0–1
BREAK
ENABLED
breakenabled
breakenabled^term
1 (ON)
0–1
Buffertimeout
buffertimeout
buffer^timeout
1000 ticks
0–65,535
ticks
CONTROL
FLAGS
controlflags
control^flags
2
N.A.
dmap^flag
control^flags.<0>
0 (OFF)
0–1
d^plus^enabled
control^flags.<12>
0 (OFF)
0–1
auto^restart^flag
control^flags.<13>
0 (OFF)
0–1
stats^flag
control^flags.<14>
1 (ON)
0–1
sysmsgs^flag
control^flags.<15>
0 (OFF)
0–1
CTRL26
ctrl^26
ctrl26
1
0–1
DEBUG
FLAGS
debugflags
debug^flags
%2 (pool
check)
N.A.
debug^error^trap
debug^flags.<0:7>
0 (OFF)
0–255
bounds^checking
debug^flags.<8>
0
0–1
auto^trace^flag
debug^flags.<11>
0 (OFF)
0–1
uscode^debug^flag
debug^flags.<12>
0 (OFF)
0–1
Extended General Device Support (GDSX) Manual—529931-001
2- 48
Setting Configuration Parameters
Design and Development
Table 2-3. Dynamic Parameters (page 2 of 2)
External
Parameter
Name
Internal DEFINE Name
CONFIG^
PARAMS Name
Default
Value
Range
backup^debug^flag
debug^flags.<13>
0 (OFF)
0–1
poolcheck^flag
debug^flags.<14>
1 (ON)
0–1
debug^fatal^flag
debug^flags.<15>
0 (OFF)
0–1
DEVICEINFO
support^devinfo
device^info
0 (OFF)
0–1
DYNAMIC
dynamic
dynamic^term
%21 (ON)
N.A.
dynamic^recovery
dynamic^term.<10>
1 (ON)
0–1
dynamic^autostop
dynamic^term.<11>
1 (ON)
0–1
dynamic^nowaitdepth
dynamic^term.<12:15>
1 (ON)
0–15
IOCBWAITTIME
iocbwait
iocb^wait^time
1,000 ticks
0–6000
ticks
LOGSTATUS
log^enabled
log^status
1
(enabled)
0–1
LOOPTIME
looptime
loop^time
200 ticks
0–32,767
ticks
RESTARTTIME
auto^restart^delay^time
auto^restart^time
6000 ticks
0–65,535
ticks
SECURITY
security
sg^security
1 (group)
N.A.
user^group
sg^security.<0:7>
0
0–255
remote^change^flag
sg^security.<13>
0
0–1
access^group
sg^security.<14:15>
1 (group)
0–3
TRACERECSI
ZE
tracerecsize
trace^rec^size
256 words
0–16,383
words
TRAPERROR
debug^error^trap2
d^series^error
0
0–32,767
USERFLAGS
userflags
user^flags
%100000
0–65,535
USERSTART
SU
userstartsu
user^start^su
0 (OFF)
0–1
(continued)
Setting Configuration Parameters
There are five ways to set the configuration parameters:
1. Within the USER^INIT^CONFIG^PARAMS user exit (called during process
initialization), assign parameter values to TSCODE globals. This method may be
used with static or dynamic parameters. Use the internal DEFINE names listed in
the second column of Table 2-2 and Table 2-3.
Extended General Device Support (GDSX) Manual—529931-001
2- 49
Design and Development
Setting Configuration Parameters
For example, to specify the restart time delay, assign a value to the name
auto^restart^delay^time:
PROC USER^INIT^CONFIG^PARAMS;
BEGIN
auto^restart^delay^time := 10000;
To turn on the trace facility, assign 1 to the name auto^trace^flag:
PROC USER^INIT^CONFIG^PARAMS;
BEGIN
auto^trace^flag := 1;
2. Before running GDSX, use TACL PARAM commands to assign values to external
parameter names. This method may be used with static or dynamic parameters.
Use the external parameter names listed in the first column of Table 2-2 and
Table 2-3.
For example, to specify the restart time delay, enter the following command at a
TACL prompt:
> PARAM RESTARTTIME 10000
Or, to turn on the trace facility (give bit 11 of DEBUGFLAGS a value of 16), enter
the following command at a TACL prompt:
> PARAM DEBUGFLAGS 16
Caution. The PARAM DEBUGFLAGS command also turns off all the other flags in the bitencoded DEBUGFLAGS configuration parameter. See DEBUGFLAGS on page 2-54.
To turn on the trace facility (give bit 11 of DEBUGFLAGS a value of 16) and also
pool checking (give bit 14 of DEBUGFLAGS a value of 2), set DEBUGFLAGS
equal to 18 (16 + 2):
> PARAM DEBUGFLAGS 18
3. Use an SPI management application program to change parameter values. This
method can be used only with dynamic parameters.
4. Use SCF to change parameter values. This method can be used only with
dynamic parameters.
For example, to turn off the trace facility, enter the following SCF command:
-> TRACE PROCESS $GDSX, STOP
5. After the GDSX process has been initialized, change parameter values within
USCODE. This method can be used only with dynamic parameters.
For example, within the DEVICE^HANDLER you can assign:
auto^restart^delay^time := 6000;
Extended General Device Support (GDSX) Manual—529931-001
2- 50
Descriptions of Configuration Parameters
Design and Development
Or, to turn off the trace facility, assign the following within USCODE:
auto^trace^flag := 0;
Methods 1 and 2 can be used to set either dynamic or static parameters, while
methods 3 through 5 can be used only with dynamic parameters (SCF and SPI
interfaces are established only after all parameters have been initialized).
Method 2 will override settings made using method 1. Methods 3, 4, and 5 are of
equal priority and all will override settings made with methods 1 and 2.
Descriptions of Configuration Parameters
Following are descriptions of all the static and dynamic configuration parameters. The
parameters appear in alphabetical order by external parameter name (see the first
column of Tables 2-2 and 2-3).
ASSOCIATIVE
This dynamic parameter indicates whether all preconfigured DEVICE^HANDLER tasks
are to be associative or not. If DEVICE^HANDLER tasks are associative, multiple
opens from external processes for a given file name are allowed by TSCODE and
cause the assignment of exactly one DCB and one TCB, and the creation of only one
DEVICE^HANDLER task. Identical file names in open messages do not cause
multiple tasks to be created, but merely cause the tcb.opens counter to be incremented
by 1.
If DEVICE^HANDLER tasks are not associative, an open from an external process for
a given file name causes the assignment of exactly one DCB and one TCB.
Subsequent open messages containing the same file name are rejected by TSCODE.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
associative
associative^term
0 (OFF)
0–1
Preconfigured SUs have an associative attribute that can be set ON or OFF to indicate
for this one SU whether the corresponding task is associative. The setting of the
associative attribute for this SU takes precedence over the associative parameter
setting for all DEVICE^HANDLER tasks.
AUTOSTOP
This dynamic parameter determines whether the GDSX process is to stop if there are
no external openers. If autostop is 1, the process is to stop if no more opens exist.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
autostop
auto^stop
0 (OFF)
0–1
This parameter is different from dynamic^autostop of the DYNAMIC configuration
parameter, which determines whether dynamic DEVICE^HANDLER tasks are to be
stopped if they have no openers.
Extended General Device Support (GDSX) Manual—529931-001
2- 51
BACKUPCPU
Design and Development
BACKUPCPU
This static parameter is used to specify a backup processer when a GDSX application
is run in NonStop mode. You must specify a backup processor that is different from
the primary processor.
When a GDSX application designed for NonStop mode is configured to run as a
TS/MP server, you do not use the BACKUPCPU configuration parameter to specify a
backup processor. For this case, the specification of the primary and backup
processors is always assigned by TS/MP. However, you must use the NONSTOP and
SERVER configuration parameters to notify the GDSX server to start a backup process
in the processor specified by TS/MP.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
brother^cpu^no
N.A.
-1
0–15
BREAKENABLED
This dynamic parameter determines whether user tasks can take break ownership by
means of TAKEBREAK.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
breakenabled
breakenabled^term
1 (ON)
0–1
If this BREAKENABLED is set to 1, user tasks can successfully call the TAKEBREAK
procedure, otherwise calls to TAKEBREAK return file error 99. See Section 8, Service
Routines for a description of GIVEBREAK and TAKEBREAK.
BUFFERTIMEOUT
This dynamic parameter specifies the maximum time that TSCODE should wait for a
buffer to become available during a call to GETLOCALPOOL that does not specify a
timeout. (See GETLOCALPOOL on page 8-36.) If a task waits longer than
BUFFERTIMEOUT ticks, it is suspended with a fault.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
buffertimeout
buffer^timeout
1,000 ticks
0–65,535 ticks
CONTROLFLAGS
This dynamic parameter is used to set multiple configuration controls. It is a bitencoded parameter, but bit 12 (d^plus^enabled) cannot be changed after GDSX is
started.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
controlflags
control^flags
2
N.A.
dmap^flag
control^flags.<0>
0 (OFF)
0–1
d^plus^enabled
control^flags.<12>
0 (OFF)
0–1
Extended General Device Support (GDSX) Manual—529931-001
2- 52
CONTROLFLAGS
Design and Development
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
auto^restart^flag
control^flags.<13>
0 (OFF)
0–1
stats^flag
control^flags.<14>
1 (ON)
0–1
sysmsgs^flag
control^flags.<15>
0 (OFF)
0–1
Dmap^flag
Dmap^flag is not used by TSCODE. It is used by the USAMPLE example program to
establish dynamic session control (dynamic mapping). The value of this parameter
may be displayed with the SCF INFO, DETAIL command on the GDSX process.
D^plus^enabled
D^plus^enabled is used to indicate to TSCODE whether USCODE has been
converted. TSCODE assumes that USCODE is converted only if this bit is set to 1.
Although CONTROLFLAGS is a dynamic parameter, d^plus^enabled cannot be
changed after GDSX startup. The other bits within CONTROLFLAGS can be changed
after GDSX is started.
While d^plus^enabled indicates if USCODE is converted or unconverted, it does not
control whether USCODE runs only at a low PIN or only at a high PIN. When
d^plus^enabled is set to 1, USCODE can run at a low PIN or a high PIN; when
d^plus^enabled is set to 0, USCODE can only run at a low PIN.
If you run GDSX as a high PIN process but neglect to set d^plus^enabled to 1, GDSX
will abend with an error 10014.
Auto^restart^flag
Auto^restart^flag determines whether a user task will be restarted after faulting with an
irrecoverable error. If this flag is set, after a time delay specified by the
RESTARTTIME configuration parameter, a user task faulted with an irrecoverable error
is automatically restarted (the noretn parameter of the call to FAULT must also be
equal to 1). The restart is transparent to the task’s openers, except that during restart
all prior requests are returned a file-system error 140 (modem error) and new requests
are queued.
Stats^flag
Stats^flag determines whether statistical information is to be collected on user task
operations. If this flag is set, TSCODE allocates extended memory in which this data
is stored. Statistics are displayed with the SCF STATS command. If GDSX is run as a
process pair, the primary process checkpoints this statistical data to the backup.
Extended General Device Support (GDSX) Manual—529931-001
2- 53
CTRL26
Design and Development
Sysmsgs^flag
Sysmsgs^flag determines whether TSCODE sends system messages to user tasks. If
this flag is set, TSCODE forwards system messages to USCODE.
Open message formats may be found in the Guardian Procedure Errors and Messages
Manual. Maximum length of the D-series message forwarded is 81 words.
The close message format is:
INT type;
! = -104
INT processhandle[0:9]; ! = Requester process handle
INT file;
! = file
TSCODE allocates an IOCB for each open and close message. USCODE should call
^REPLYX without its parameters or DEALLOCATEIOCB to deallocate this IOCB. For
example,
CALL ^REPLYX()
! Do not use any ^REPLYX parameter
or
CALL DEALLOCATEIOCB (CB)
CTRL26
This dynamic parameter determines how GDSX responds to a Pathway/iTS TCP
control 26 message. CTRL26 should be set to 1 if TSCODE is to respond correctly.
When CTRL26 is set to 1, TSCODE responds to a Pathway/iTS TCP control 26
message with a parameter of 1, by replying with a FECONTINUE(70). When CTRL26
is set to 0, TSCODE responds to a Pathway/iTS TCP control 26 message with a
FEINVALOP(2).
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
ctrl^26
ctrl26
1 (ON)
0–1
DEBUGFLAGS
This dynamic parameter is bit encoded, and is used to set multiple configuration
controls.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
debugflags
debug^flags
%2 (pool check)
N.A.
debug^error^trap
debug^flags.<0:7>
0 (OFF)
0–255
bounds^checking
debug^flags.<8>
0 (OFF)
0–1
auto^trace^flag
debug^flags.<11>
0 (OFF)
0–1
uscode^debug^flag
debug^flags.<12>
0 (OFF)
0–1
backup^debug^flag
debug^flags.<13>
0 (OFF)
0–1
poolcheck^flag
debug^flags.<14>
1 (ON)
0–1
debug^fatal^flag
debug^flags.<15>
0 (OFF)
0–1
Extended General Device Support (GDSX) Manual—529931-001
2- 54
Design and Development
DEBUGFLAGS
Debug^error^trap
Debug^error^trap is used to indicate a file error number, which when detected by
TSCODE will cause TSCODE to take one of two actions:
•
•
Invoke DEBUG, which is done in case uscode^debug^flag is set to 1
Send a warning message with the file error number to the home terminal, in case
uscode^debug^flag is set to 0
If you want TSCODE to trap file errors with numbers greater than 255, use the
TRAPERROR configuration parameter with uscode^debug^flag.
Bounds^checking
Bounds^checking is used to indicate whether TSCODE is to do bounds checking on
buffers used during USCODE service routine calls (pseudo and utility procedures). If
this flag is set to 1, TSCODE ensures that all buffers used for I/O are in global or
extended memory, not in the swappable stack. If this flag is set to 0, TSCODE does
not check the location of the buffers used. See also the description of the
CHECK^BUFFER^BOUNDS utility procedure in Section 8, Service Routines.
Auto^trace^flag
Auto^trace^flag is used to turn on the trace facility at startup. With this flag set,
TSCODE traces all significant events.
Uscode^debug^flag
Uscode^debug^flag is used to indicate what action is to be taken if a fault or a userspecified file error is detected by TSCODE. If this flag is set to 1, and if TSCODE
detects a fault or a file error specified in debug^error^trap (bits 0-7) or in the
TRAPERROR configuration parameter, then TSCODE calls DEBUG. If this flag is set
to 0, and if TSCODE detects a fault or a file error specified in debug^error^trap (bits
0-7) or in the TRAPERROR configuration parameter, then TSCODE sends a message
with the fault number or file error number to the home terminal. USCODE is also free
to use this flag for application-specific purposes.
Backup^debug^flag
Backup^debug^flag is used to indicate that DEBUG is to be called in the backup
process. If this flag is set to 1, DEBUG is called in the backup process immediately
following process creation. You can then set breakpoints as desired. From then on, a
GDSX process enters DEBUG only if an I/O error occurs during a write to the backup
process. The process does not time out on I/O operations to the backup process.
Extended General Device Support (GDSX) Manual—529931-001
2- 55
DEVICEINFO
Design and Development
Poolcheck^flag
Poolcheck^flag is used to indicate whether memory pools should be checked when
tasks are dispatched. If poolcheck^flag is set, each time a task is dispatched TSCODE
checks the buffer pool, message pool, extended buffer pool, and extended message
pool for corruption. This pool checking is in addition to that always done when the
GETLOCALPOOL and GETEXTPOOL procedures are called. If corruption is detected,
GDSX stops with abend error 230 or 231. The poolcheck^flag can be set when
debugging a program and turned off during production to allow GDSX to run more
efficiently.
Debug^fatal^flag
Debug^fatal^flag is used to indicate that TSCODE is to invoke DEBUG if any fatal error
is detected.
DEVICEINFO
Because GDSX runs as a subtype 30 process, it receives DEVICEINFO (-40) system
messages when external applications call the file-system DEVICEINFO and
DEVICEINFO2 procedures. This dynamic parameter determines how TSCODE
responds to external processes issuing a DEVICEINFO or DEVICEINFO2 on the SUs
under the GDSX process. Also, when this parameter is set, SCF accepts
DEVICETYPE, DEVICESUBTYPE, and PHYSRECLEN attributes defined for SUs or
LINEs.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
support^devinfo
device^info
0 (OFF)
0–1
Regardless of the setting of DEVICEINFO, if GDSX receives a DEVICEINFO message
requesting information about the GDSX process itself, TSCODE replies with device
type 57 (for the GDSX process), subtype 0, and physical record length 132. See the
logic box diagram below.
The GDSX process name must be specified in one of these formats:
$GDSX-process-name
$GDSX-process-name.#GDS
$GDSX-process-name.#GDS.qualifier
Does the DEVICEINFO message specify the GDSX process?
Yes
No
Extended General Device Support (GDSX) Manual—529931-001
2- 56
DEVICEINFO
Design and Development
Reply with
(57, 0, 132)
Is DEVICEINFO parameter = 1?
Yes
No
Is DEVICETYPE specified?
Return record length
and type and subtype
of process (0, 0)
Yes
No
Return
DEVICETYPE,
DEVICESUBTYPE,a
nd PHYSRECLEN
Return values from
DEVICEINFO2 call
on access name
device
If GDSX receives a DEVICEINFO message specifying a file other than the GDSX
process, and if DEVICEINFO is equal to 1, then TSCODE determines whether the
DEVICETYPE attribute is specified (by means of an SCF ADD or ALTER command
with DEVICETYPE and PHYSRECLEN). If the DEVICETYPE attribute is specified, the
PHYSRECLEN attribute must also be specified, and DEVICETYPE,
DEVICESUBTYPE, and PHYSRECLEN are returned when completing the request.
For example, if DEVICEINFO is equal 1 and an SU is configured with the SCF
command:
-> ADD SU $GDSX.#CP6100.SDN, DEVICETYPE 6, PHYSRECLEN 80
then a DEVICEINFO2 request specifying $GDSX.#CP6100.SDN is returned device
type 6 and physical record length 80. This type of response is useful in situations
where the values returned by calling DEVICEINFO2 against the access name device
(see following paragraphs) would not be appropriate: for example, when the terminal
is presented to the requester application as a 3270 device, although the physical
device is not a 3270 device.
If GDSX receives a DEVICEINFO message specifying a file other than the GDSX
process, if DEVICEINFO is equal to 1, and if TSCODE determines that DEVICETYPE
is not specified, then the values returned by calling DEVICEINFO2 for the access
name device are used to complete the request. For example, if DEVICEINFO is equal
to 1 and a LINE is configured with the SCF command:
-> ADD LINE $GDSX.#CP6100
then a DEVICEINFO2 request specifying $GDSX.#CP6100 is returned the values
received by calling DEVICEINFO2 for $CP6100 (the derived access name for the line).
If DEVICEINFO is equal to 1 and an SU is configured with the SCF command:
-> ADD SU $GDSX.#TERM.A, ACCESSNAME \COMM.$TA
then a DEVICEINFO2 request specifying $GDSX.#TERM.A is returned the values
received by calling DEVICEINFO2 for \COMM.$TA (the explicitly configured access
name for the SU).
If GDSX receives a DEVICEINFO message specifying a file other than the GDSX
process, and if DEVICEINFO is equal to 0, the default, TSCODE returns the record
length and the type and subtype of a process (0,0) to complete the request. Thus the
default value guarantees that applications converted from older versions of GDS can
execute as before.
Extended General Device Support (GDSX) Manual—529931-001
2- 57
DYNAMIC
Design and Development
DYNAMIC
This dynamic parameter is bit encoded and is used to set multiple configuration
controls. Any nonzero value for dynamic signals TSCODE that dynamic SUs can be
created. If dynamic equals zero, all SUs must be preconfigured.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
dynamic
dynamic^term
%21 (ON)
N.A.
dynamic^recovery
dynamic^term.<10>
0 (OFF)
0–1
dynamic^autostop
dynamic^term.<11>
1 (ON)
0–1
dynamic^nowaitdepth
dynamic^term.<12:15>
1 (ON)
0–15
Dynamic^recovery
Dynamic^recovery is used to indicate whether TSCODE is to restart dynamic tasks
after a takeover. If this flag is 1, TSCODE restarts all dynamic tasks that existed at the
time of the failure of the former primary process. Setting this variable also implies that
dynamic terminals are allowed.
Dynamic^autostop
Dynamic^autostop is used to indicate whether TSCODE is to stop a dynamic SU by
calling STOP^TASK if the SU has no openers. Setting this variable also implies that
dynamic terminals are allowed.
Preconfigured SUs have an SCF autostop attribute that may be set ON or OFF. This
attribute is not used by TSCODE; it may be used as desired.
Dynamic^nowaitdepth
Dynamic^nowaitdepth is used to indicate the nowaitdepth (the maximum number of
concurrent nowaited I/Os) for files associated with dynamic SUs. Setting this variable
also implies that dynamic terminals are allowed.
Example
To use a TACL PARAM command to set autostop on and also enter a value of 10 for
nowaitdepth, add 16 (for autostop—bit 11—ON) plus the value 10 for nowaitdepth, and
set DYNAMIC equal to the total:
> PARAM DYNAMIC 26
Extended General Device Support (GDSX) Manual—529931-001
2- 58
EXTSUSIZE
Design and Development
EXTSUSIZE
This static parameter specifies the number of words added to the device control block
for application-specific purposes (see the dcb^template in the ULHDECSE file listed in
Appendix C).
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
termdata
term^data
8 words
0–64 words
If additional space is not required in the DCB, EXTSUSIZE should be set to 0 so that
unneeded space is not allocated in the DCB pool (see the description of MAXTERMS
on page 2-69 for an explanation of how the size of the pool is calculated). If the
sample GDSX object file called OGDS is run as a line handler, MAXLINES must be
greater than 0 and EXTSUSIZE must be equal to 8.
Changing the value of EXTSUSIZE after the GDSX process is initialized has no effect
on the structure of a DCB or the allocation of the DCB pool.
IOCBWAITTIME
This dynamic parameter specifies the maximum time that TSCODE should wait for an
IOCB to become available during a call to ALLOCATEIOCB that does not specify a
timeout. (See ALLOCATEIOCB on page 8-9) If a task waits longer than
IOCBWAITTIME ticks, it will be suspended with a fault.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
iocbwait
iocb^wait^time
1000 ticks
0–6000 ticks
IOCB allocation faults may be displayed by issuing an SCF STATS command.
LOGSTATUS
This dynamic parameter indicates whether event messages are to be sent to the EMS
$0 collector. If the parameter value is nonzero, all status, events, faults, and errors are
sent to the $0 collector. If the parameter value is zero, EMS messages are not
generated by TSCODE.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
log^enabled
log^status
1 (enabled)
0–1
LOOPTIME
This dynamic parameter indicates the maximum processor time that any task is
allowed to execute before relinquishing control. Unless this parameter is set to zero, in
which case TSCODE makes no attempt to monitor looping tasks, if a task executes for
Extended General Device Support (GDSX) Manual—529931-001
2- 59
MAXBUFPOOL
Design and Development
looptime ticks without transferring control, it is presumed to be in a loop and is
suspended with a fault.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
looptime
loop^time
200 ticks
0–32,767 ticks
MAXBUFPOOL
This static parameter can be used to specify the maximum size of the extended buffer
pool.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
maxbufpoolsize
maxbufpool^size
32K bytes
Up to 7.5
megabytes
If the size specified for the extended buffer pool is too large, error message 10002 is
sent to the home terminal:
10002 maxTCBpool or Buffer/Msg pool too large
MAXCPSIZE
This static parameter determines the size of the buffer sent when USCODE does a
checkpoint to the backup process. This buffer is in the extended segment for control
structures. See Space Usages and Limitations on page 2-19.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
max^cp^wds
max^chkpt^wds
4096 words
512–16,364
words
The Q^CP procedure moves local memory global data within a user’s named or private
global data block to the checkpoint buffer. The Q^CPX procedure moves extended
memory data to the checkpoint buffer. Up to four data areas can be moved to the
checkpoint buffer with a single call to Q^CP[X]. Multiple calls to Q^CP[X] can be done
before calling DO^CP or ^CHECKPOINT. Q^CP[X] queues data until the data in the
checkpoint buffer, of the word size specified by MAXCPSIZE, including three control
words per data area copied, exceeds the size of MAXCPSIZE.
Caution. If the checkpoint buffer overflows during a call to Q^CP[X] from a user exit other than
USER^BACKUP, the backup process will be terminated and Q^CP[X] will return 0. To prevent
this, ensure that MAXCPSIZE is large enough. If the backup process is terminated, it is still
the caller’s responsibility to release the semaphore by means of GIVE^CPSEM.
If the checkpoint buffer overflows during a call to Q^CP[X] from the USER^BACKUP
exit, TSCODE automatically writes the current checkpoint buffer to the backup
process.
TSCODE ensures that MAXCPSIZE is at least the size of TASKCPSIZE.
Extended General Device Support (GDSX) Manual—529931-001
2- 60
MAXDCBPOOL
Design and Development
MAXDCBPOOL
This static parameter can be used to override the calculation of DCB pool space done
automatically by TSCODE during process initialization. In general, you should not
need to set this parameter.
Internal DEFINE
Name
CONFIG^PARAMS
Name
maxdcbpoolsize
maxdcbpool^size
Default Value
Range
(see following
equation)
Up to 131,064 bytes
The size that TSCODE calculates for the pool can be overridden by using a TACL
PARAM command to assign a value to the external name MAXDCBPOOL, or by
assigning a value to the internal parameter name in the
USER^INIT^CONFIG^PARAMS user exit. TSCODE uses the user-specified setting
unless it is determined that the pool size would be insufficient, in which case TSCODE
uses the value that it calculated.
If the pool size specified by this parameter is too large (more than 131,064 bytes), or if
the size causes the running total calculated for control block pools, the extended buffer
pool, and the extended message pool to exceed 16,777,216 bytes, an error message
is sent to the home terminal, and the GDSX process stops with abend error 020. The
configuration error message is:
10007 maxDCBpool or previous pools too large
TSCODE allocates the device control block (DCB) pool from extended memory. (See
dcb^template in the DCCBDECS file in Appendix C.) The size in bytes of the DCB
pool is calculated as follows:
DCB pool size =(DCBTBL size) + $LEN(DCB^TEMPLATE) +
(MAXTERMS * ($LEN(DCB^TEMPLATE) + (EXTSUSIZE *
2)))
One DCB is allocated for the #ZSPI monitor, making a total of (MAXTERMS + 1) DCBs
to be allocated. DCBTBL, an INT(32) address table that points into the DCB pool area,
is also allocated from extended memory. The DCBTBL size is thus ((MAXTERMS + 1)
* 4), because each address in the table requires 4 bytes.
The first $LEN(DCB^TEMPLATE) to appear in the equation is for the #ZSPI monitor.
The remaining area (MAXTERMS * ($LEN(DCB^TEMPLATE) + (EXTSUSIZE * 2))) is
for the other DCBs; (EXTSUSIZE * 2) bytes for application-dependent data is included
for each DCB.
Extended General Device Support (GDSX) Manual—529931-001
2- 61
MAXFCBPOOL
Design and Development
MAXFCBPOOL
This static parameter may be used to override the calculation of FCB pool space done
automatically by TSCODE during process initialization. In general, you should not
need to set this parameter.
Internal DEFINE
Name
CONFIG^PARAMS
Name
maxfcbpoolsize
maxfcbpool^size
Default Value
Range
(see following
equation)
Up to 131,064 bytes
The size that TSCODE calculates for the pool can be overridden by using a TACL
PARAM command to assign a value to the external name MAXFCBPOOL, or by
assigning a value to the internal parameter name in the
USER^INIT^CONFIG^PARAMS user exit. TSCODE uses the user-specified setting
unless it is determined that the pool size would be insufficient, in which case TSCODE
will use the value that it calculated.
If the pool size specified by this parameter is too large (more than 131,064 bytes), or if
the size causes the running total calculated for control block pools, the extended buffer
pool, and the extended message pool to exceed 16,777,216 bytes, an error message
is sent to the home terminal, and the GDSX process stops with abend error 020. The
configuration error message is:
10006 maxFCBpool or previous pools too large.
TSCODE allocates the FCB pool from extended memory. (See fcb^template in the
DCCBDECS file in Appendix C.) The size in bytes of the FCB pool is calculated as
follows:
FCB pool size = (MAXFILES + 1) * $LEN(FCB^TEMPLATE)
One is added to MAXFILES for $RECEIVE.
MAXFILES
This static parameter specifies the maximum number of files, except for $RECEIVE,
that GDSX can have open simultaneously. If LINE^HANDLER tasks are to be created,
TSCODE increases any value assigned by you to accommodate ITC files needed.
The actual number of files opened by GDSX may be less than the number specified for
MAXFILES. This is caused by a system limit that takes precedence over the value set
by MAXFILES. The system limit depends on the type of each open, the type of the
device being opened, and the available space for each Access Control Block.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
maxfiles
maximum^files
48 files
10–2048 files
Extended General Device Support (GDSX) Manual—529931-001
2- 62
MAXIOCBPOOL
Design and Development
MAXIOCBPOOL
This static parameter can be used to override the calculation of IOCB pool space done
automatically by TSCODE during process initialization. In general, you should not
need to set this parameter.
Internal DEFINE
Name
CONFIG^PARAMS
Name
maxiocbpoolsize
maxiocbpool^size
Default Value
Range
(see following
equation)
Up to 131,064 bytes
The size that TSCODE calculates for the pool can be overridden by using a TACL
PARAM command to assign a value to the external name MAXIOCBPOOL, or by
assigning a value to the internal DEFINE name in the USER^INIT^CONFIG^PARAMS
user exit. TSCODE uses the user-specified setting unless it is determined that the
pool size would be insufficient, in which case TSCODE uses the value that it
calculated.
If the pool size specified by this parameter is too large (more than 131,064 bytes), or if
the size causes the running total calculated for control block pools, the extended buffer
pool, and the extended message pool to exceed 16,777,216 bytes, an error message
is sent to the home terminal, and the GDSX process stops with abend error 020. The
configuration error message is:
10003 maxIOCBpool or previous pools too large.
TSCODE allocates an IOCB pool from extended memory. (See iocb^template in the
DCCBDECS file in Appendix C.) The size in bytes of the IOCB pool is calculated as
follows:
IOCB pool size = $LEN(IOCB^TEMPLATE) * MAXIOCBS
MAXIOCBS
This static parameter specifies the maximum number of nowait I/O operations that can
be outstanding at one time.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
maxiocbs
maximum^iocbs
128 I/Os
128–2047 I/Os
MAXITC
This static parameter specifies the maximum number of DEVICE^HANDLER tasks that
communicate with each other by ITC messages. If LINE^HANDLER tasks are to be
created, TSCODE increases the MAXITC value assigned by you to accommodate
other needed ITC files.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
maxitc
max^itc
0
0–1020 tasks
Extended General Device Support (GDSX) Manual—529931-001
2- 63
MAXLDCBPOOL
Design and Development
To calculate the actual number for MAXITC, TSCODE first chooses the minimum value
between the value you supply and 1,020. This is expressed by the following equation:
Minimum value = $MIN(MAXITC, 1020)
Then TSCODE chooses the maximum value between the MAXITC number from the
above equation and a number derived from MAXTASKS and MAXLINES, as
expressed in the following equation:
Actual value = $MAX((MAXTASKS - MAXLINES), minimum value))
MAXLDCBPOOL
This static parameter can be used to override the calculation of the logical device
control block (LDCB) pool space done automatically by TSCODE during process
initialization. In general, you should not need to set this parameter.
Internal DEFINE
Name
CONFIG^PARAMS
Name
maxldcbpoolsize
maxldcbpool^size
Default Value
Range
(see following
equation)
Up to 131,064 bytes
The size that TSCODE calculates for the pool can be overridden by using a TACL
PARAM command to assign a value to the external name MAXLDCBPOOL, or by
assigning a value to the internal parameter name in the
USER^INIT^CONFIG^PARAMS user exit. TSCODE will use the user-specified setting
unless it is determined that the pool size would be insufficient, in which case TSCODE
will use the value that it calculated.
If the pool size specified by this parameter is too large (more than 131,064 bytes), or if
the size causes the running total calculated for control block pools, the extended buffer
pool, and the extended message pool to exceed 16,777,216 bytes, an error message
is sent to the home terminal, and the GDSX process stops with abend error 020. The
configuration error message is:
10008 maxLDCBpool or previous pools too large.
TSCODE calculates the size in bytes of the LDCB pool as follows:
LDCB pool size = $LEN(LDCB^TEMPLATE) * (MAXTASKS + 5)
MAXLINEPOOL
This static parameter can be used to override the calculation of the LINE control block
(LCB) pool space done automatically by TSCODE during process initialization. In
general, you should not need to set this parameter.
Internal DEFINE
Name
CONFIG^PARAMS
Name
maxlinepoolsize
maxlinepool^size
Default Value
Range
(see following
equation)
Up to 131,064 bytes
Extended General Device Support (GDSX) Manual—529931-001
2- 64
MAXLINES
Design and Development
The size that TSCODE calculates for the pool can be overridden by using a TACL
PARAM command to assign a value to the external name MAXLINEPOOL, or by
assigning a value to the internal parameter name in the
USER^INIT^CONFIG^PARAMS user exit. TSCODE uses the user-specified setting
unless it is determined that the pool size would be insufficient, in which case TSCODE
uses the value that it calculated.
If the pool size specified by this parameter is too large (more than 131,064 bytes), or if
the size causes the running total calculated for control block pools, the extended buffer
pool, and the extended message pool to exceed 16,777,216 bytes, an error message
is sent to the home terminal, and the GDSX process stops with abend error 020. The
error message is:
10009 maxLINEpool or previous pools too large.
TSCODE allocates the LINE control block (LCB) pool from extended memory. (See
line^template in the DCCBDECS file in Appendix C.) The size in bytes of the LCB pool
is calculated as follows:
LCB pool size = $LEN(LINE^TEMPLATE) * MAXLINES
MAXLINES
This static parameter specifies the maximum number of LINE^HANDLER tasks that
can be created within the running GDSX process. If GDSX is not being used to handle
a LINE, then MAXLINES should be set to 0, in which case GDSX only allows
DEVICE^HANDLER tasks.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
maxlines
maximum^lines
0 L^H tasks
0–15 tasks
MAXLINKS
By default, the number of system linkage control blocks (XLBs) allocated by a GDSX
process is set to the value of the MAXTASKS parameter. (Note that linkage control
blocks are different from LINE control blocks (LCBs).) With a number of GDSX
processes running on a system, the pool of these blocks can be exhausted, preventing
other system or application processes from dispatching. This static parameter
specifies the maximum number of system linkage control blocks that can be allocated
by the GDSX process.
Internal DEFINE
Name
CONFIG^PARAMS
Name
Default Value
Range
max^links
maximum^links
MAXTASKS
From 1 to the system
configured limit
Extended General Device Support (GDSX) Manual—529931-001
2- 65
MAXMSGPOOL
Design and Development
MAXMSGPOOL
This static parameter can be used to specify the maximum size of the extended
message pool.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
maxmsgpoolsize
maxmsgpool^size
32K bytes
Up to 7.5
megabytes
If the size specified for the extended message pool is too large, configuration error
message 10002 is sent to the home terminal:
10002 maxTCBpool or Buffer/Msg pool too large
MAXOPENS
This static parameter specifies the maximum number of external openers (other than a
backup GDSX process) that the GDSX primary process will handle at one time. If
there are already MAXOPENS openers, an additional process attempting to open
GDSX will receive an open error (FETOOMANY).
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
maxopens
maximum^opens
48 openers
2–1169
openers
MAXPCBPOOL
This static parameter can be used to override the calculation of the process control
block (PCB) pool space done automatically by TSCODE during process initialization.
In general, you should not need to set this parameter.
Internal DEFINE
Name
CONFIG^PARAMS
Name
maxpcbpoolsize
maxpcbpool^size
Default Value
Range
(see following
equation)
Up to 131,064 bytes
The size that TSCODE calculates for the pool can be overridden by using a TACL
PARAM command to assign a value to the external name MAXPCBPOOL, or by
assigning a value to the internal parameter name in the
USER^INIT^CONFIG^PARAMS user exit. TSCODE uses the user-specified setting
unless it is determined that the pool size would be insufficient, in which case TSCODE
uses the value that it calculated.
If the pool size specified by this parameter is too large (more than 131,064 bytes), or if
the size causes the running total calculated for control block pools, the extended buffer
pool, and the extended message pool to exceed 16,777,216 bytes, an error message
is sent to the home terminal, and the GDSX process stops with abend error 020. The
configuration error message is:
10010 maxPCBpool or previous pools too large.
Extended General Device Support (GDSX) Manual—529931-001
2- 66
MAXPROCESSES
Design and Development
TSCODE allocates the process control block (PCB) pool from extended memory. (See
pcb^template in the DCCBDECS file in Appendix C.) The size in bytes of the PCB
pool is calculated as follows:
PCB pool size = $LEN(PCB^TEMPLATE) * MAXPROCESSES
MAXPROCESSES
This static parameter specifies the maximum number of processes that can be active
simultaneously as a result of GDSX calls to the pseudo Guardian
^PROCESS_CREATE_ procedure. If GDSX is to run as a process pair,
MAXPROCESSES must be at least 1 to allow for the creation of the backup.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
maxprocesses
maximum^processes
2 processes
2–1024
processes
MAXRCBPOOL
This static parameter can be used to override the calculation of RCB pool space done
automatically by TSCODE during process initialization. In general, you should not
need to set this parameter.
Internal DEFINE
Name
CONFIG^PARAMS
Name
maxrcbpoolsize
maxrcbpool^size
Default Value
Range
(see following
equation)
Up to 131,064 bytes
The size that TSCODE calculates for the pool can be overridden by using a TACL
PARAM command to assign a value to the external name MAXRCBPOOL, or by
assigning a value to the internal parameter name in the
USER^INIT^CONFIG^PARAMS user exit. TSCODE uses the user-specified setting
unless it is determined that the pool size would be insufficient, in which case TSCODE
uses the value that it calculated.
If the pool size specified by this parameter is too large (more than 131,064 bytes), or if
the size causes the running total calculated for control block pools, the extended buffer
pool, and the extended message pool to exceed 16,777,216 bytes, an error message
is sent to the home terminal, and the GDSX process stops with abend error 020. The
configuration error message is:
10005 maxRCBpool or previous pools too large.
TSCODE allocates the requester control block (RCB) pool from extended memory.
(See rcb^template in the DCCBDECS file in Appendix C.) The size in bytes of the
RCB pool is calculated as follows:
RCB pool size = $LEN(RCB^TEMPLATE) * (MAXOPENS + 1)
One is added to MAXOPENS so that if GDSX is run as a process pair, there will be an
RCB for the backup process open on the primary process.
Extended General Device Support (GDSX) Manual—529931-001
2- 67
MAXRCVPOOL
Design and Development
MAXRCVPOOL
This static parameter may be used to override the calculation of RCV pool space done
automatically by TSCODE during process initialization. In general, you should not
need to set this parameter.
Internal DEFINE
Name
CONFIG^PARAMS
Name
maxrcvpoolsize
maxrcvpool^size
Default Value
Range
(see following
equation)
Up to 131,064 bytes
The size that TSCODE calculates for the pool can be overridden by using a TACL
PARAM command to assign a value to the external name MAXRCVPOOL, or by
assigning a value to the internal parameter name in the
USER^INIT^CONFIG^PARAMS user exit. TSCODE will use the user-specified setting
unless it is determined that the pool size would be insufficient, in which case TSCODE
will use the value that it calculated.
If the pool size specified by this parameter is too large (more than 131,064 bytes), or if
the size causes the running total calculated for control block pools, the extended buffer
pool, and the extended message pool to exceed 16,777,216 bytes, an error message
is sent to the home terminal, and the GDSX process stops with abend error 020. The
configuration error message is:
10004 maxRCVpool or previous pools too large.
TSCODE calculates the size in bytes of the RCV pool as follows:
RCV pool size = RECEIVEDEPTH * 2
MAXTASKS
This static parameter specifies the total number of user tasks that may be active
simultaneously within the GDSX process.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
maxtsk
maximum^tasks
34 tasks
7–846 tasks
TSCODE uses system tasks that each require a TCB: a monitor task, a listener task, a
backup task if GDSX is running as a process pair, and six other kinds of system tasks.
Therefore, when allocating the TCB pool, TSCODE adds five to MAXTASKS to handle
all the system tasks. However, as more than five system tasks could be active
simultaneously, it is a good idea to set MAXTASKS a little higher than the number of
DEVICE^HANDLER and LINE^HANDLER tasks needed, because if TSCODE
determines that all TCBs are in use, it does not allow a new task to be created.
Extended General Device Support (GDSX) Manual—529931-001
2- 68
MAXTCBPOOL
Design and Development
MAXTCBPOOL
This static parameter can be used to override the calculation of TCB pool space done
automatically by TSCODE during process initialization. In general, you should not
need to set this parameter.
Internal DEFINE
Name
CONFIG^PARAMS
Name
maxtcbpoolsize
maxtcbpool^size
Default Value
Range
(see following
equation)
Up to 131,064 bytes
The size that TSCODE calculates for the pool can be overridden by using a TACL
PARAM command to assign a value to the external name MAXTCBPOOL, or by
assigning a value to the internal parameter name in the
USER^INIT^CONFIG^PARAMS user exit. TSCODE uses the user-specified setting
unless it is determined that the pool size would be insufficient, in which case TSCODE
uses the value that it calculated.
If the pool size specified by this parameter is too large (more than 131,064 bytes), or if
the size causes the running total calculated for control block pools, the extended buffer
pool, and the extended message pool to exceed 16,777,216 bytes, an error message
is sent to the home terminal, and the GDSX process stops with abend error 020. The
configuration error message is:
10002 maxTCBpool or previous pools too large.
TSCODE allocates the TCB pool from extended memory. (See tcb^template in the
DCCBDECS file in Appendix C.) The size in bytes of the TCB pool is calculated as
follows:
TCB pool size = $LEN(TCB^TEMPLATE) * (MAXTASKS + 5)
MAXTERMS
This static parameter specifies the maximum number of subdevices (SUs) that can be
active simultaneously within a GDSX process. This number should include those SUs
preconfigured with SCF as well as those configured dynamically. As each device to be
opened by GDSX is assigned a DCB control block, this parameter determines how
many device control blocks to allocate.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
maxterms
maximum^terms
32 SUs
2–1128 SUs
NONSTOP
This static parameter permits a GDSX application that is run as a TS/MP server to also
run in NonStop mode. The NONSTOP parameter is only checked if the SERVER
configuration parameter is set to 1.
Extended General Device Support (GDSX) Manual—529931-001
2- 69
POOLSIZE
Design and Development
See Running GDSX as a TS/MP Server on page 3-10 for more information.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
nonstop^param
N.A.
0 (OFF)
0–1
POOLSIZE
This static parameter specifies the maximum size of the shared extended pool
allocated for all user tasks.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
poolsize
pool^size
16,392 words
Configuration
dependent
TSCODE allocates an extended memory area of size POOLSIZE multiplied by 2 bytes
for the shared extended pool.
PROCNOWAIT
This static parameter determines how TSCODE implements nowaited USCODE
execution of these service routines:
•
•
•
•
•
•
•
•
^DEVICEINFO2
^FILE_GETINFOBYNAME_
^PROCESS_CREATE_
^SERVERCLASS_SEND_
^SERVERCLASS_DIALOG_BEGIN_
^SERVERCLASS_DIALOG_SEND_
^SERVERCLASS_DIALOG_ABORT_
^SERVERCLASS_DIALOG_END_
If PROCNOWAIT is set to 0, a call to one of these procedures by any USCODE task
causes TSCODE to do the following:
1. Suspend the calling USCODE task.
2. Call AWAITIO[X] on behalf of the calling USCODE task.
3. Check $RECEIVE for the I/O completion and return the requested information in
the output parameters of the procedure called by the USCODE task.
4. Wake up the calling task.
Therefore, in this case, USCODE should not call ^AWAITIO[X] as would be done for a
typical nowaited Guardian procedure call.
Extended General Device Support (GDSX) Manual—529931-001
2- 70
RECEIVEDEPTH
Design and Development
If PROCNOWAIT is set to 1, a call to one of the procedures by any USCODE task
does not cause TSCODE to suspend the task and assumes USCODE will call
^AWAITIO[X] on the pseudo-$RECEIVE file to wait for I/O completion. When the I/O
completes, TSCODE returns the requested information in the output parameters of the
^AWAITIO[X] procedure and wakes up the calling task.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
proc^nowait
procedure^nowait
0 (OFF)
0–1
RECEIVEDEPTH
This static parameter specifies the maximum number of messages incoming to
$RECEIVE that will be queued for the GDSX process before replies must be issued.
When the GDSX process opens $RECEIVE, the value of this parameter is used as the
receivedepth input parameter to OPEN.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
receivedepth
receive^depth
78 messages
16–255
messages
The minimum value for RECEIVEDEPTH is (MAXTASKS + 5) multiplied by 2.
(MAXTASKS specifies the total number of user tasks that may be active
simultaneously, and TSCODE adds five to MAXTASKS for all the system tasks. See
the explanation under the heading “MAXTASKS.“) Therefore, if MAXTASKS is allowed
to default to 34, the default value for RECEIVEDEPTH is (34 + 5) * 2 = 78.
RECEIVESIZE
This static parameter specifies the largest $RECEIVE request that the GDSX process
will accept. Messages larger than RECEIVESIZE bytes will be rejected with a filesystem error 21.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
recvsz
recvsize
4096 bytes
1024–16,384
bytes
In order to be able to queue up multiple messages from $RECEIVE, TSCODE
allocates a $RECEIVE queue from extended memory. The size in bytes of the queue
is calculated as follows:
$RECEIVE queue size = RECEIVESIZE * (MAXTASKS + 5)
MAXTASKS specifies the total number of user tasks that may be active
simultaneously. TSCODE adds five to MAXTASKS to handle all the system tasks (see
“MAXTASKS” on page 2-64).
RESTARTTIME
This dynamic parameter specifies the restart time allowed when a user task has faulted
with an irrecoverable error and is being automatically restarted (the noretn parameter
Extended General Device Support (GDSX) Manual—529931-001
2- 71
SECURITY
Design and Development
of the call to FAULT must be equal to 1). This parameter is only meaningful when
auto^restart^flag is set on. See CONTROLFLAGS on page 2-52.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
auto^restart^delay^time
auto^restart^time
6000 ticks
0–65,535 ticks
SECURITY
This dynamic parameter is bit encoded and is used to set multiple configuration
controls.
$ZNET SCP program is usually owned by the super ID (255,255). As a result, the
GDSX process normally allows any SCF or SPI commands. However, bit settings of
SECURITY can be used to define restrictions for issuing sensitive SCF or SPI
commands.
Sensitive SPI commands are those having values in the range 4096-8191. Sensitive
GDSX-specific SCF commands are the following:
ABORT
ADD
ALLOWOPENS
ALTER
DELETE
PRIMARY
START
STOP
STOPOPENS
TRACE
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
security
sg^security
1 (group)
N.A.
user^group
sg^security.<0:7>
0
0–255
remote^change^flag
sg^security.<13>
0
0–1
access^group
sg^security.<14:15>
1 (group)
0–3
User^group
User^group can be used to indicate who can issue sensitive SCF/SPI commands. If
access^group is set to 1, user^group is used to indicate the group ID of users allowed
to issue sensitive commands. However, if $ZNET SCP program is owned by the super
ID, all sensitive commands are allowed. If access^group does not equal 1, user^group
is not referenced by TSCODE.
Remote^change^flag
Remote^change^flag is used to indicate whether remote changes are allowed. If this
flag is set to1, the sensitive SPI commands are allowed from a remote node.
Extended General Device Support (GDSX) Manual—529931-001
2- 72
SEGMENTID
Design and Development
Access^group
Access^group is used to indicate which users are allowed to issue sensitive SCF or
SPI commands. If access^group is set to 0 (owner), then the process sending a
request (a $ZNET SPI message to GDSX) must have a process accessor ID that
allows access to the GDSX process.
If access^group is set to 1 (group), user^group is used to indicate the group ID of users
allowed to issue sensitive commands. If access^group does not equal 1, user^group is
not referenced by TSCODE.
If access^group is set to 2 (all), the sensitive commands can be issued by anyone. If
access^group is set to 3 (255,255), the sensitive commands can be issued only by the
super ID.
SEGMENTID
This static parameter allows you to specify the extended segment allocated by
TSCODE for various control and data structures. Segment ID 1025 is reserved by
TSCODE for tracing purposes. GDSX stops with abend error 30 if you set
SEGMENTID to 1025.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
segment^id
segment^number
1024
1024 or
>1025
SERVER
This static parameter allows you to run a GDSX application as if it were a TS/MP
server. See Running GDSX as a TS/MP Server on page 3-10 for more information.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
server
server^flg
0 (OFF)
0–1
TASKCPSIZE
This static parameter specifies the size of the area for checkpointed memory pool
buffers that is allocated for each user task in extended memory. When a task
checkpoints its memory pool buffers by a call to ^CHECKPOINT(2), the data sent to
the backup process is stored in the task’s TASKCPSIZE-sized area.
This is the area that ^RECLAIMBUFFER traverses to recover buffer images after a
failure. See ^RECLAIMBUFFER on page 8-64.
Internal DEFINE
Name
CONFIG^PARAMS
Name
Default Value
Range
cpcontextsz
cp^context^sz
2048 words
16–configuration dependent
Extended General Device Support (GDSX) Manual—529931-001
2- 73
TASKPOOLSIZE
Design and Development
The size of the pool in bytes allocated by TSCODE for all user and system tasks is:
(TASKCPSIZE * 2) * (MAXTASKS + 5)
MAXTASKS specifies the total number of user tasks that may be active
simultaneously, and TSCODE adds five to MAXTASKS for all the system tasks. See
the explanation under MAXTASKS on page 2-68.
TASKPOOLSIZE
This static parameter specifies the maximum size of the private extended pool
allocated for each user task.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
taskpoolsize
task^pool^size
128 words
Configuration
dependent
TSCODE allocates an extended memory area of total size (TASKPOOLSIZE * 2)
multiplied by the number of bytes specified by MAXTASKS for all the private extended
pools.
TASKSIZE
This static parameter determines the maximum size of the data stack image that can
be swapped to and from extended memory for any one task.
Internal DEFINE
Name
CONFIG^PARAMS
Name
Default Value
Range
tsksz
task^size
512 wds
128 words; configuration
dependent
The total extended memory swap area in words allocated by TSCODE for all tasks is
given by:
((TASKSIZE + 14) * 2) * (MAXTASKS + 5)
Fourteen is added to TASKSIZE for sync information (which is not currently used).
(TASKSIZE + 14) is multiplied by 2 to allow for both the working stack image and the
checkpointed stack image.
TMF
This static parameter specifies whether the TMF is being used in a user task.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
tmf
tmf^flag
0 (OFF)
0–2
If TMF is set to 0, TSCODE does not permit any TMF processing from a user task, and
it will not pass a TMF transaction from an external process to another process, such as
Pathway.
Extended General Device Support (GDSX) Manual—529931-001
2- 74
TRACERECSIZE
Design and Development
If TMF is set to 1, TSCODE does not permit any TMF processing from a user task;
however, it will pass a TMF transaction from an external process to another process.
If TMF is set to 2, TSCODE permits TMF processing from a user task, but it will not
pass a TMF transaction from an external process to another process.
TRACERECSIZE
This dynamic parameter specifies the maximum size of each record added to the trace
file. The maximum record size can also be specified in a call to
USER^OPEN^TRACE^FILE. If the record size specified by TRACERECSIZE differs
from that specified in a call to USER^OPEN^TRACE^FILE, the latter value has
precedence.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
tracerecsize
trace^rec^size
256 words
0–16,383
words
TRAPERROR
This dynamic configuration parameter can be used only by converted processes. It is
used to indicate a file error number, which when detected by TSCODE causes
TSCODE to do one of the following:
•
•
Invoke DEBUG, which is done if uscode^debug^flag of the DEBUGFLAG
configuration parameter is set to 1.
Send a warning message with the file error number to the home terminal, if
uscode^debug^flag is set to 0.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
debug^error^trap2
d^series^error
0
0–32,767
For both converted and unconverted applications, if you want TSCODE to trap file
errors numbered 1 through 255, you can use debug^error^trap and
uscode^debug^flag. See the description of the DEBUGFLAGS configuration
parameter for more information.
USERFLAGS
You can define this dynamic parameter as desired.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
userflags
user^flags
%100000
0-65,535
The USAMPLE example program uses the USERFLAGS parameter to define the
following:
handle^break = userflags.<0>
dedicated^rcv = userflags.<1>
clock
= userflags.<2>
Extended General Device Support (GDSX) Manual—529931-001
2- 75
USERSTARTSU
Design and Development
If running OGDS (the USAMPLE object file), set userflags.<0> to 1, which is the
default.
USERSTARTSU
This dynamic parameter indicates whether the USER^START exit is to be called
whenever the TSCODE monitor task is about to open a file associated with an SU.
Internal DEFINE Name
CONFIG^PARAMS Name
Default Value
Range
userstartsu
user^start^su
0 (OFF)
0–1
If USERSTARTSU is equal to 1, whenever the monitor task is about to open a dynamic
or preconfigured SU—whether the SU is under a LINE or not—TSCODE procedure
OPEN^MESSAGE will call USER^START.
On the other hand, if USERSTARTSU is not equal to 1, whenever the monitor task is
about to open an SU, procedure OPEN^MESSAGE will call USER^START only if the
SU is configured under a LINE. Thus the default value of USERSTARTSU guarantees
that applications converted from older versions of GDSX can execute as before:
USER^START is invoked only for SUs under a LINE.
File-System Errors
The following is a list of Guardian file error codes that might be passed to USCODE
from TSCODE. Not all the Guardian file error codes are used by TSCODE. This list is
extracted from the errors section of the DCCBDECS file. (See Appendix C,
DCCBDECS and ULHDECSE Listings for a complete listing.)
LITERAL
feok
feeof
fesysmess
fenotfound
febadname
fenotopen
febadcount
feboundserr
fetoomany
fenolcb
fenopoolspace
fenocbspace
fenoiophysmem
fesecviol
feopenstop
fecontinue
fenotransid
feinvtransid
fetoomanytransbegins
fetransabrtownerdied
fetransabrtnetdown
fetransabrtoprcmd
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
0
1
6
11
13
16
21
22
28
30
32
34
37
48
61
70
75
78
83
90
92
94
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
feinvalop
fedup
feinuse
fenosuchdevice
fenoprimary
=
=
=
=
=
2
10
12
14
17
,
,
,
,
,
fenonout
femissparm
fenobufspace
fenoiobufspace
fenoiocbspace
fetimedout
fewrongid
fedevdown
febadreply
feendedtransid
fetmfnotrunning
fetmfnotconfigured
fetransabrtbaddbid
fetransabrtaudoflow
feabortedtransid
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
26
29
31
33
35
40
60
66
74
76
81
84
91
93
97
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
Extended General Device Support (GDSX) Manual—529931-001
2- 76
Notes on Specific Codes
Design and Development
fetoocheap
febreakonly
felinereset
feeotreceived
fenodata
feownership
fecpupon
fescerror
fepathdown
fefatpin
=
=
=
=
=
=
=
=
=
=
99
110
124
163
187
200
230
233
201
560
,
,
,
,
,
,
,
,
,
;
fenotready
febreak
femodemerr
fepollend
=
=
=
=
100
111
140
176
,
,
,
,
feownabort
feiopon
= 210 ,
= 231 ,
fenetdown
= 250 ,
The DEBUGFLAGS and TRAPERROR configuration parameters are used to indicate
file error numbers, which when detected by TSCODE cause TSCODE to invoke
DEBUG or send a warning message with the file error number to the home terminal.
See the descriptions of these GDSX Configuration Parameters on page 2-46.
Notes on Specific Codes
Following are descriptions for some of the file-system error codes returned by
TSCODE:
Feinuse, Error 12
This error is returned in response to an OPEN request when there are no available
user tasks.
Febadname, Error 13
This error is returned in response to an OPEN request for one of the following reasons:
•
•
•
The subdevice name is the same as the GDSX process name.
The open specifies only two levels of qualification for a subdevice under a line.
The open specifies no subdevice and the DYNAMIC configuration parameter is
OFF.
Fenosuchdevice, Error 14
This error is returned in response to an OPEN where the subdevice named in the
OPEN message does not exist.
Fenoprimary, Error 17
When GDSX does not have a current open of the backup by the primary, this error is
returned in response to an OPEN request for the backup by a process other than
GDSX.
Extended General Device Support (GDSX) Manual—529931-001
2- 77
Design and Development
Notes on Specific Codes
Febadcount, Error 21
This error is returned when the size of an external process’s request exceeds the
smaller value of RECEIVESIZE and the task’s READUPDATE on $RECEIVE.
Femissparm, Error 29
If GDSX is run converted, only the GDSX pseudo Guardian procedures that
correspond to the D-series Guardian procedures are available to USCODE (except for
^OPEN, ^CLOSE, ^FILEINFO, and ^FNAMEEXPAND). If other calls are attempted,
TSCODE returns file-system error 29 or 560.
If GDSX is run unconverted, only the GDSX pseudo Guardian procedures that
correspond to the C-series Guardian procedures are available to USCODE (except for
^FILE_OPEN_, ^FILE_CLOSE_, and ^FILE_GETINFO_). If other calls are attempted,
TSCODE returns file-system error 29 or 560.
Fenolcb, Error 30
This error is returned when GDSX is unable to obtain an IOCB to assign to the request.
Fenobufspace, Error 31
This error is returned when GDSX is unable to obtain buffer space for the request.
Fenocbspace, Error 32
This error is returned in response to an OPEN message for which GDSX is unable to
obtain a required control block.
Fewrongid, Error 60
This error is returned when GDSX receives a request from a process that has not
opened GDSX.
Feopenstop, Error 61
This error is returned in response to an OPEN request when a GDSX shutdown is in
process, or when the line or device to be opened is in the STOP PENDING state.
Fedevdown, Error 66
This error is returned when the task handling the open has been stopped.
Fenotready, Error 100
This error is returned when an OPEN request is received while the GDSX process is
still handling its startup messages.
Extended General Device Support (GDSX) Manual—529931-001
2- 78
Design and Development
EMS Filters and GDSX
Feownabort, Error 210
This error is returned when there has been a takeover by the backup process since the
last request by this opener.
Fefatpin, Error 560
If GDSX is run converted, only the GDSX pseudo Guardian procedures that
correspond to the D-series Guardian procedures are available to USCODE (except for
^OPEN, ^CLOSE, ^FILEINFO, and ^FNAMEEXPAND). If other calls are attempted,
TSCODE returns file-system error 29 or 560.
If GDSX is run unconverted, only the GDSX pseudo Guardian procedures that
correspond to the C-series Guardian procedures are available to USCODE (except for
^FILE_OPEN_, ^FILE_CLOSE_, and ^FILE_GETINFO_). If other calls are attempted,
TSCODE returns file-system error 29 or 560.
EMS Filters and GDSX
GDSX processes send tokenized fault and event messages to the Event Management
Service (EMS) primary collector ($0) process. (See Interpreting Console and EMS
Messages on page 3-16 for a listing of these messages.) The collector stores these
messages in the current EMS log file. EMS distributor processes select messages
from the log file and deliver them to consumers.
A distributor process can use a filter to limit the types of events passed to a consumer.
For example, a distributor can be used with a filter to deliver only event messages from
GDSX processes running in the network where the distributor is running. The following
file (named FILTGDS) implements such a filter, using a subsystem ID check to
determine what event messages are to be routed to an EMS terminal.
FILTER GDSX;
BEGIN
[#SET ZGDS^VAL^SSID
[ZSPI^VAL^TANDEM].[ZSPI^SSN^ZGDS].[ZGDS^VAL^VERSION]]
IF ZEMS^TKN^SSID = SSID(ZGDS^VAL^SSID) THEN PASS;
END;
See the EMS Manual for more information on filters.
This filter must be compiled with EMF, the EMS filter compiler. The following OBEY
file, named LOADFILT, loads subsystem and EMS TACL definitions (ZSPITACL and
ZEMSTACL) and GDSX TACL definitions (ZGDXTACL) required for the compilation.
After loading these definitions, LOADFILT compiles FILTGDS and starts a printing
distributor (EMSDIST) employing the filter and directing output to the designated EMS
terminal.
PUSH X
#LOAD /KEEP 1, LOADED X/ $vol.subvol.ZSPITACL
#LOAD /KEEP 1, LOADED X/ $vol.subvol.ZEMSTACL
#LOAD /KEEP 1, LOADED X/ $vol.subvol.ZGDXTACL
Extended General Device Support (GDSX) Manual—529931-001
2- 79
Design and Development
Running the Filter
POP X
EMF /IN FILTGDS/ FGDS
EMSDIST COLLECTOR $0, TYPE P, FILTER FGDS, TEXTOUT $term-name
Running the Filter
To run this filter, edit the LOADFILT file so that the ZSPITACL, ZEMSTACL, and
ZGDXTACL files are properly qualified. (These files are often kept in the ZSPIDEF
subvolume.) Change $vol and subvol to the appropriate volume and subvolume
names; change $term-name to the name of the device where you want the messages
to be displayed. Then issue the following command at any terminal:
> OBEY $vol.subvol.LOADFILT
The EMS filter compiler runs at that terminal. When the compiler finishes, the cursor is
at the bottom left corner of the screen.
If you ran the LOADFILT file at a terminal other than the one where you want GDSX
messages to be displayed, press the Break key at the terminal where you issued the
OBEY command, and type in PAUSE at the display terminal. (If you ran the
LOADFILT file at the display terminal, no extra steps are necessary.)
To check if all is in order, you can start up a GDSX process. A START GDS event
message should be displayed.
Tracing GDSX
GDSX allocates an extended segment for a trace when a request is received to start a
trace. After the trace file is open, depending on settings of auto^trace^flag and the
trace^control^flags, as the GDSX process runs, TSCODE automatically generates
trace entries for the file. (You can also generate trace entries by calling
ADD^TRACE^DATA or ADD^TRACE^DATA^INT.)
GDSX deallocates the trace segment when a request is received to stop the trace.
Once the trace has been stopped, PTrace is used to display the trace records.
Here is an example of tracing a GDSX process and displaying the trace records:
1. Start a named GDSX process, $GDSX, for example:
> RUN GDSE /NAME $GDSX, NOWAIT/
2. Start an interactive SCF process:
> SCF
3. Issue an SCF TRACE command to trace all significant events (SELECT ALL)
occurring during execution of $GDSX and write the records to a file named
TRCFILE:
-> TRACE PROCESS $GDSX, TO TRCFILE, SELECT ALL
This SELECT option sets all the trace^control^flags to 1.
Extended General Device Support (GDSX) Manual—529931-001
2- 80
Selecting Trace Events Supported by TSCODE
Design and Development
4. When GDSX processing is done, stop the trace session:
-> TRACE PROCESS $GDSX, STOP
-> EXIT
5. Run the PTrace utility to display all records in the file TRCFILE:
>
?
?
?
PTRACE
FROM TRCFILE
OCTAL ON
RECORD ALL
Selecting Trace Events Supported by TSCODE
The first step in tracing a GDSX process is to decide what events you want to trace.
Then determine from Table 2-4 which of these events TSCODE automatically
generates trace records. Read the descriptions of events traced in the fourth column
of the table, checking for those events you want to trace. Make a note of the trace
classes (a class includes several event types) in the first column in which the events
fall.
When you start the trace, you directly or indirectly (by means of SCF) set the
appropriate trace^control^flags (or auto^trace^flag) for these trace classes. (See
Turning On the Trace Facility on page 2-86.)
Table 2-4. TSCODE Trace Classes and Entry Types (page 1 of 3)
SCF Trace
Class Keyword
Literal Name for
Entry Type
Literal
Value
EXTREQ
REQ^IN^APPL
1
Incoming request occurred on
$RECEIVE
REQ^OUT^IOP
2
Outgoing request sent to a process
or IOP
REQ^RET^APPL
3
Reply sent to $RECEIVE
REQ^RET^IOP
4
I/O completion occurred on a file
other than $RECEIVE
None
5-7
None
DATA^IN^APPL
8
Buffer of incoming request on
$RECEIVE
DATA^OUT^IOP
9
Parameters of outgoing request
sent to a process or IOP
DATA^RET^APPL
10
Buffer of reply sent to $RECEIVE
DATA^RCV^IOP
11
Buffer of I/O completion on file
other than $RECEIVE
None
12-15
None
REQ^IN^SR
16
(Not currently supported)
REQ^OUT^SR
17
(Not currently supported)
EXTDATA
INTREQ
Events Traced by TSCODE
Extended General Device Support (GDSX) Manual—529931-001
2- 81
Selecting Trace Events Supported by TSCODE
Design and Development
Table 2-4. TSCODE Trace Classes and Entry Types (page 2 of 3)
SCF Trace
Class Keyword
INTDATA
INTDISP
CBRESRCE
POOLRESRCE
EXTCTRL
Literal Name for
Entry Type
Literal
Value
Events Traced by TSCODE
REQ^IN^BT
18
(Not currently supported)
REQ^OUT^BT
19
(Not currently supported)
None
20-23
None
DATA^IN^SR
24
Incoming response from TS/MP
server
DATA^OUT^SR
25
Outgoing request to TS/MP server
TMF^TX^BEGIN
26
TMF transaction that was started
TMF^TX^END
27
TMF transaction that ended
TMF^TX^ABORT
28
TMF transaction that was canceled
TMF^TX^RESUME
29
TMF transaction that became
active in user task
TMF^ACT^TRANS
30
TMF transaction that became
active in server task
None
31
None
TASK^DISP^DP
32
A dispatch occurred (general)
TASK^DISP^IOC
33
A dispatch occurred for I/O
completion
TASK^DISP^CP
34
A dispatch occurred for a
checkpoint
None
35-39
None
TCB^ALLOC
40
(Not currently supported)
TCB^DEALLOC
41
(Not currently supported)
IOCB^ALLOC
42
(Not currently supported)
IOCB^DEALLOC
43
(Not currently supported)
FCB^ALLOC
44
(Not currently supported)
FCB^DEALLOC
45
(Not currently supported)
RCB^ALLOC
46
(Not currently supported)
RCB^DEALLOC
47
(Not currently supported)
LOC^POOL^ALLOC
48
Allocation of local pool space
LOC^POOL^DEALLOC
49
Deallocation of local pool space
EXT^POOL^ALLOC
50
Allocation of extended pool space
EXT^POOL^DEALLOC
51
Deallocation of extended pool
space
None
52-55
None
SYSTEM^MSG
56
(Not currently supported)
Extended General Device Support (GDSX) Manual—529931-001
2- 82
User-Coded Trace Calls
Design and Development
Table 2-4. TSCODE Trace Classes and Entry Types (page 3 of 3)
SCF Trace
Class Keyword
INTREQCTRL
INTTSKCTRL
NSTCTRL
ERRCTRL
Literal Name for
Entry Type
Literal
Value
Events Traced by TSCODE
OPEN^MSG^REQ
57
Open message request
None
58-63
None
FSREQ^FLOW
64
(Not currently supported)
None
65-71
None
TASK^CREATED
72
New task created
TASK^WAIT^EVENT
73
Task called WAIT^EVENT
TASK^WAKED^UP
74
Task awakened—an event
occurred for the task
TASK^OPEN^REQ
75
Task opened
TASK^STOPPED
76
Task stopped
None
77-79
None
NST^BK^CREATED
80
Backup task created
NST^BK^STOPPED
81
Backup task stopped
NST^BK^LISTENING
82
Backup task received checkpoint
data
NST^BK^TAKEOVER
83
Backup process is taking over
NST^CP^OP
84
Checkpointing operation
NST^Q^CP^OP
85
(Not currently supported)
None
86-87
None
DEBUG^ERR^MSG
88
Going into DEBUG
INT^ERR^MSG
89
A configuration error or an internal
error (abend) occurred
TRAP^ERR^MSG
90
Trap occurred
None
91-95
None
User-Coded Trace Calls
If there are events that you want to trace that are not included among those for which
TSCODE automatically generates trace records, you can generate trace entries for
these events by calling ADD^TRACE^DATA or ADD^TRACE^DATA^INT at
appropriate places in USCODE. Trace entries generated by these procedure calls are
merged with any trace entries that you specify to be generated by TSCODE.
GDSX uses variable-length trace records, allowing users to define different record
formats for different types of trace entries. The default for the maximum record size is
256 words. You can change the maximum record size by setting the TRACERECSIZE
dynamic configuration parameter (see GDSX Configuration Parameters on page 2-46)
Extended General Device Support (GDSX) Manual—529931-001
2- 83
User-Coded Trace Calls
Design and Development
or by setting the maximum in a call to USER^OPEN^TRACE^FILE (see Section 8,
Service Routines).
Trace entries are differentiated from each other by a trace entry type. Type values
from 0–127 are reserved for TSCODE events. Values from 128–255 are used for
USCODE events. Except for these restrictions, use of type, which is a parameter
passed in calls to ADD^TRACE^DATA or ADD^TRACE^DATA^INT, is completely user
dependent: whatever value is assigned to type is be passed through to the trace
records.
Dynamic Control of User-Coded Tracing
If you want to dynamically control the tracing of classes of these user-defined events,
you need to group the events into the classes to be controlled, and then assign trace
record type values to the events so that the events fall into the desired classes.
For example, two user-defined events can be assigned type as equal to 200 and 201
so that they fall within the trace class defined by the SCF keyword SRMISC (see
Table 2-5). You can then turn on and off the tracing of these two events by setting and
resetting the SCF trace class keyword SRMISC, which is equivalent to
SR^MISC^TRACE (see Table 2-7).
A simple form of the trace call used for event type 200 is:
IF SR^MISC^TRACE THEN
CALL ADD^TRACE^DATA (SR^MISC^REQ, MYBUF1,100, MYBUF2,10);
A simple form of the trace call used for event type 201 is:
IF SR^MISC^TRACE THEN
CALL ADD^TRACE^DATA (SR^MISC^RSP, MYBUF1,100, MYBUF2,10);
Table 2-5 shows which type values fall into the standard SCF trace classes for
USCODE events. The first column of the table contains the keywords used in SCF to
select the classes of events to be traced. The far right column contains a description
of the events for those entry types traced in the USAMPLE example program.
However, you can assign type values to events in a completely different way from the
correspondence shown for USAMPLE.
Table 2-5. USCODE Trace Classes and Entry Types (page 1 of 3)
SCF Trace
Class Keyword
Literal Name for
Entry Type
Literal
Value
Events Traced by USAMPLE
Example Program
TERMREQ
TERM^REQ^IN
128
$RECEIVE request received by
DEVICE^HANDLER
TERM^REQ^OUT
129
Reply returned by
DEVICE^HANDLER to external
process
None
130-135
None
Extended General Device Support (GDSX) Manual—529931-001
2- 84
User-Coded Trace Calls
Design and Development
Table 2-5. USCODE Trace Classes and Entry Types (page 2 of 3)
SCF Trace
Class Keyword
Literal Name for
Entry Type
Literal
Value
Events Traced by USAMPLE
Example Program
TERMDATA
TERM^DATA^IN
136
Data input to DEVICE^HANDLER
from non-$RECEIVE file
TERM^DATA^OUT
137
Data output from
DEVICE^HANDLER to non$RECEIVE file
None
138-143
None
TERM^STATE^CTRL
144
Determination of state by
DEVICE^HANDLER
TERM^ACTION^CTRL
145
Determination of action to be
taken by DEVICE^HANDLER
None
146-151
None
LINE^REQ^IN
152
$RECEIVE request received by
LINE^HANDLER
LINE^REQ^OUT
153
Reply returned by
LINE^HANDLER to external
process
None
154-159
None
LINE^DATA^IN
160
Data input to LINE^HANDLER
from non-$RECEIVE file
LINE^DATA^OUT
161
Data output from LINE^HANDLER
to non-$RECEIVE file
None
162-167
None
LINE^STATE^CTRL
168
Determination of state by
LINE^HANDLER
LINE^ACTION^CTRL
169
Determination of action to be
taken by LINE^HANDLER
None
170-176
None
SR^CB^REQ
176
Control block request
SR^CB^RSP
177
Control block request response
None
178-183
None
SR^POOL^REQ
184
Pool request
SR^POOL^RSP
185
Pool request response
None
186-191
None
SR^CTRL^REQ
192
None
SR^CTRL^RSP
193
None
None
194-199
None
TERMINTL
LINEREQ
LINEDATA
LINEINTL
SRCB
SRPOOL
SRCTRL
Extended General Device Support (GDSX) Manual—529931-001
2- 85
Turning On the Trace Facility
Design and Development
Table 2-5. USCODE Trace Classes and Entry Types (page 3 of 3)
SCF Trace
Class Keyword
Literal Name for
Entry Type
Literal
Value
Events Traced by USAMPLE
Example Program
SRMISC
SR^MISC^REQ
200
Miscellaneous requests from
USCODE
SR^MISC^RSP
201
Miscellaneous responses to
USCODE
None
202-207
None
Turning On the Trace Facility
There are four ways to turn on the trace facility. In all cases, the trace entries that are
generated depend on settings of the global trace^control^flags (found in the
common^data section of DCCBDECS) and auto^trace^flag (see DEBUGFLAGS on
page 2-54).
DEFINEs for the trace^control^flags are given in Table 2-6 and Table 2-7. As long as
the trace file is open, setting the defined text to 1 causes trace records to be generated
for the corresponding trace class. Setting the defined text to 0 turns off the generation
of trace records for the corresponding trace class. Setting the auto^trace^flag to 1 is
equivalent to turning on all the trace^control^flags for TSCODE and USCODE events.
Table 2-6. TSCODE Trace Classes, Trace^control^flags DEFINEs, and Events
Traced
SCF Trace
Class Keyword
Equivalent
trace^control^flags DEFINE
TSCODE Events Traced
EXTREQ
EXT^REQ^TRACE
Traces external requests
EXTDATA
EXT^DATA^TRACE
Traces external data
INTREQ
INT^REQ^TRACE
Traces internal requests
INTDATA
INT^DATA^TRACE
Traces internal data
INTDISP
INT^DISP^TRACE
Traces internal task dispatches
CBRESRCE
RESRCE^CB^TRACE
Traces control block resources
POOLRESRCE
RESRCE^POOL^TRACE
Traces pool resources
EXTCTRL
EXT^CTRL^TRACE
Traces external controls
INTREQCTRL
INT^REQ^CTRL^TRACE
Traces internal request controls
INTTSKCTRL
INT^TASK^CTRL^TRACE
Traces internal task controls
NSTCTRL
NST^CTRL^TRACE
Traces fault tolerance processing
controls
ERRCTRL
ERR^CTRL^TRACE
Traces error controls
TSCODE
TSCODE^TRACE
Traces all the above TSCODE
events
Extended General Device Support (GDSX) Manual—529931-001
2- 86
Design and Development
Turning On the Trace Facility
The trace facility is turned on in four different ways:
1. Enter the following PARAM command at the TACL prompt:
> PARAM DEBUGFLAGS 16
The PARAM command should be entered before creating the GDSX process. This
traces all TSCODE events described in Table 2-6 as well as all USCODE-defined
events.
Note. DEBUGFLAGS is a bit-encoded configuration parameter—see GDSX Configuration
Parameters on page 2-46 for details.
2. Within USCODE, set auto^trace^flag to 1, as defined in the config^template section
of DCCBDECS. This traces all TSCODE events described in Table 2-6 as well as
all USCODE-defined events.
3. Open the trace file with the USER^OPEN^TRACE^FILE procedure. This
procedure causes TSCODE to allocate an extended segment for a trace file, which
is saved as TRACEP by a primary process or as TRACEB by a backup process.
After the trace file is open, depending on the settings of auto^trace^flag and
trace^control^flags, TSCODE automatically generates trace entries for the file.
You may also generate trace entries by calling ADD^TRACE^DATA or
ADD^TRACE^DATA^INT.
4. Issue an SCF command to start the trace. For example:
-> TRACE PROCESS $GDSX, SELECT SRMISC, TO MYTRACE
generates trace records for the SRMISC trace class. SCF requires a trace file
name. In this example, the trace file is named MYTRACE and is saved in the
subvolume where SCF is running.
The command:
-> TRACE PROCESS $GDSX, SELECT ALL, TO MYTRACE
traces all TSCODE events described in Table 2-6 and all USCODE-defined events.
The trace classes are defined by means of the SELECT option:
SELECT select-spec
where select-spec is one of the following specifications:
{ keyword }
{ ( keyword [ , keyword ] ... ) }
To view trace options settings, enter:
-> HELP GDS TRACE PROCESS
See the SCF Reference Manual for GDSX for the complete syntax of the TRACE
PROCESS command.
Extended General Device Support (GDSX) Manual—529931-001
2- 87
Modifying the Trace
Design and Development
Table 2-7. Events Traced by USAMPLE
SCF Trace
Class Keyword
Equivalent
trace^control^flags
DEFINE
USCODE Events Traced by USAMPLE
TERMREQ
TERM^REQ^TRACE
Traces terminal requests
TERMDATA
TERM^DATA^TRACE
Traces terminal data
TERMINTL
TERM^INTR^TRACE
Traces internal activities within a
DEVICE^HANDLER task
LINEREQ
LINE^REQ^TRACE
Traces line requests
LINEDATA
LINE^DATA^TRACE
Traces line data
LINEINTL
LINE^INTR^TRACE
Traces internal activities within a
LINE^HANDLER task
SRCB
SR^CB^TRACE
Traces USCODE control block resources
SRPOOL
SR^POOL^TRACE
Traces USCODE pool resources
SRCTRL
SR^CTRL^TRACE
Traces USCODE controls
SRMISC
SR^MISC^TRACE
Traces miscellaneous requests from USCODE
USCODE
USCODE^TRACE
Traces all the above USCODE events
Opening the Trace File
When the trace facility is turned on in the primary GDSX process without using SCF,
TSCODE allocates an extended segment with segment ID 1025, a default size of 64
pages, and the default file name TRACEP in the subvolume where GDSX is running.
The SCF TRACE command can be used to turn on the trace and specify a different file
name (in which case the file will be created in the subvolume where SCF is running),
and the TSCODE-supported USER^OPEN^TRACE^FILE procedure can be used to
specify a different file size.
When the trace facility is turned on in the backup process without using SCF, TSCODE
allocates an extended segment with segment ID 1025, a default size of 64 pages, and
the file name TRACEB in the subvolume where GDSX is running.
If the specified trace file does not exist, the GDSX process creates and uses the file. If
the default subvolume already has a file with the name specified and the file has not
been opened by another process, the GDSX process opens the file and writes over the
old data. If the specified trace file is in use by any other process, the GDSX process
will not initiate the trace.
Modifying the Trace
During the tracing of a GDSX process, records are added to the trace file until the end
of file is reached. When the end of the file is reached, the trace records wrap to
replace the oldest records in the file, except for the file header. The default for the
maximum number of records that can be generated for the TRACE file before the
Extended General Device Support (GDSX) Manual—529931-001
2- 88
Design and Development
Examining the Trace
entries wrap is 4096. Calls to ADD^TRACE^DATA and ADD^TRACE^DATA^INT can
change the maximum number of records that can be generated for the TRACE file
before the entries wrap.
The TRACERECSIZE dynamic configuration parameter specifies the maximum size of
each record added to the trace file. The default for this size is 256 words. The
maximum record size can also be specified in a call to USER^OPEN^TRACE^FILE. If
the record size specified by the TRACERECSIZE configuration parameter differs from
that specified in a call to USER^OPEN^TRACE^FILE, the latter value has precedence.
Once a trace has been initiated, the set of trace classes for which trace records are
being generated can be changed. This is done within USCODE by setting
trace^control^flags or the equivalent DEFINE text. Trace classes cannot be changed
within SCF without first stopping the trace.
The trace can be stopped in two ways:
•
•
USCODE can call USER^CLOSE^TRACE^FILE to close the trace file in extended
memory. If USER^CLOSE^TRACE^FILE is called, all trace flags are set to zero,
the trace file is saved, and the extended segment for the trace is deallocated.
Then TSCODE does not generate trace entries for the file, and USCODE is not
allowed to generate trace entries for the file by calls to ADD^TRACE^DATA or
ADD^TRACE^DATA^INT. (See Section 8, Service Routines for detailed
information on this procedure.)
You can issue the following SCF command at the SCF prompt:
-> TRACE PROCESS $GDSX-process-name, STOP
When a trace STOP request is received by TSCODE, all trace flags are set to zero, the
trace file is saved, and the extended segment for the trace is deallocated.
Examining the Trace
Before you can display the trace data, the trace file must be closed. To examine trace
files created by GDSX, you use the PTrace utility. PTrace extracts data stored in
unstructured trace files and formats the data for output to terminals, printers, and disk
files.
The following is an example of using the PTrace formatter:
> RUN PTRACE
Ptrace - Trace Formatter-T9385C20- (10JUL89) -(092509)
? FROM TRACEP; OCTAL ON
? RECORD 1/10
? RECORD ALL
! The ALL command lists all records
? OUT TO $S.#LP1; RECORD ALL
? EXIT
PTrace supports standard commands for display of GDSX trace files. The SELMASK
command combined with the SELECT command may be used to select sets of trace
records within a trace file. The FILTER and TEXT commands are not supported.
Extended General Device Support (GDSX) Manual—529931-001
2- 89
GDSX Internals
Design and Development
For more information, see the PTrace Reference Manual.
GDSX Internals
This subsection describes task I/O internals, including I/O involving $RECEIVE and I/O
for files other than $RECEIVE, and the internals of intertask communication.
I/O for Files Other Than $RECEIVE
Two tables are used by the GDSX I/O procedures: the IOCB table and the FCB table.
TSCODE allocates an IOCB to manage each outstanding nowait I/O. Among the
entries in the IOCB are the following:
iocb.tcblink[0:1]
Two-way linked list pointers for list of IOCBs for a given task.
Also used to link available IOCBs.
iocb.fcblink[0:1]
Two-way linked list pointers for list of IOCBs for a given file.
iocb.lhlink[0:1]
Two-way linked list pointers for use by LINE^HANDLER
tasks.
iocb.wakeup=lhlink
For signaltimeout, IOCB contains the GDSX internal time
when the signal is to pop.
iocb.syncid=lhlink
For $RECEIVE requests, contains the sync ID returned from
RECEIVEINFO (or FILE_GETRECEIVEINFO_).
iocb.state
State of IOCB:
0 - Available: IOCB currently unused
1 - Queued: I/O is currently in process
2 - ITC-Queued: ITC IOCB that has not yet been
LISTENed
3 - Signal: ^SIGNALTIMEOUT IOCB
4 - N.A.
5 - Pending: I/O complete but not passed back to task
6 - ITC active: Task is processing the request
7 - Canceled: Task has not yet processed cancel event
8 - Receive: $RECEIVE request queued for task
9 - Reply: $RECEIVE request passed to task
Extended General Device Support (GDSX) Manual—529931-001
2- 90
I/O for Files Other Than $RECEIVE
Design and Development
iocb.optype
Operation type for this I/O:
0 - System message
1 - WRITE
2 - READ
3 - WRITEREAD
4 - CONTROL
5 - SETMODENOWAIT
6 - READUPDATE
7 - READLOCK
8 - READUPDATELOCK
9 - LOCKREC
10 - UNLOCKREC
11 - OPEN (nowait)
12 - WRITEUPDATE
13 - WRITEUPDATEUNLOCK
14 - ENDTRANSACTION
15 - SIGNALTIMEOUT
16 - PROCESS_CREATE_
17 - DEVICEINFO2
18 - SERVERCLASS_SEND_
19 - LOCKFILE
20 - UNLOCKFILE
21 - SETPARAM
iocb.histag
Nowait I/O tag passed by user
iocb.xbufaddr=histag
Where state is equal to 1, address in extended segment
where the queued request is stored. If state is equal to 0D,
request was a READ (no request data). Only used for
$RECEIVE IOCBs.
iocb.tcbaddr
Address of TCB for requesting task
iocb.file
File number
iocb.msgtag
If file is equal to 0, this is the message tag associated with
the $RECEIVE request.
iocb.openid
If this is an intertask message IOCB, this is the openid
assigned to requesting task by USER^START.
iocb.iocnt
Write count or count transferred
iocb.cnt
Read count or maximum reply size
iocb.err
File management error number
Extended General Device Support (GDSX) Manual—529931-001
2- 91
I/O for Files Other Than $RECEIVE
Design and Development
iocb.bufaddrx
Buffer address
iocb.rcbaddr
If file is equal to 0, the address of the requester control block
associated with this request
iocb.pid
If file is equal to 0, the process ID of process making this
request
An FCB is a file control block. Each file opened within GDSX, with the exception of
$RECEIVE, is assigned an FCB that is used to manage the file. Among the entries in
the FCB are the following:
fcb.file
File number
fcb.error
Last file management error on file
fcb.iocbh
Address of first IOCB for this file
fcb.iocbt
Address of last IOCB for this file
fcb.flags
Open flags for file. If flags.<0> is equal to 1, this is a public open
(that is, the file is accessible to all tasks).
fcb.sync
Sync depth of open
fcb.lhaddr
If file is an ITC file, this is the address of the associated
LINE^HANDLER’s TCB. See discussion under Intertask
Communication on page 2-14.
fcb.owner
If public file, the G-relative address where the file number is stored.
Otherwise, TCB address of opener.
fcb.type[0:4]
The type (<4:9>) and subtype (<10:15>) of the associated device.
For I/O for files other than $RECEIVE, the following events occur:
•
•
•
•
•
•
The task calls one of the pseudo Guardian procedures (for the remainder of this
discussion, the operation is assumed to be ^READ).
^READ allocates an IOCB (if none is available, ^READ returns with CCL and a
subsequent call to ^FILEINFO returns FENOLCB).
^READ stores the user’s nowait tag (if any) in iocb.histag.
^READ calls Guardian READ, passing $DBL(@IOCB) as the tag parameter.
If the read operation is successfully initiated, ^READ calls GOODEIO, which fills
out the remaining fields in the IOCB. In particular, iocb.tcbaddr is set to the
address of the TCB for the requesting task. GOODEIO also links the IOCB onto a
list with head at tcb.iocbh. Finally, the IOCB is linked through iocb.fcblink to the
end of the list with header fcb.iocbh. The state of the IOCB is changed to 1
(queued).
When the I/O operation completes, GDSX receives notification of this completion
by its call to AWAITIO in the dispatcher. The nowait I/O tag (tag) returned by
AWAITIO allows the dispatcher to identify the task that initiated the operation. The
Extended General Device Support (GDSX) Manual—529931-001
2- 92
Design and Development
I/O for Files Other Than $RECEIVE
IOCB is deleted from the list with head at tcb.iocbh and linked onto the end of a
completed I/O list with header at tcb.qh. The IOCB is also deleted from the FCB
list and its state is changed to 5 (pending).
•
At some time, the task initiating the I/O calls either ^AWAITIO or WAIT^EVENT.
Assume that ^AWAITIO is called. Then TSCODE first determines if an I/O
matching the file parameter has already completed by calling ^LISTEN. ^LISTEN
scans the task’s completed I/O list looking for an appropriate IOCB. (Notice that
^LISTEN differs from the Guardian procedure LISTEN in that it is called to check
for all I/O completions.)
If ^LISTEN finds that the I/O is not complete, ^AWAITIO calls WAIT^EVENT and
the task is suspended. The events waited upon may include a combination of:
°
E^IOC: if the task has an outstanding I/O on files other than $RECEIVE
and the file number passed to ^AWAITIO is not equal to 0.
°
E^IMSG: if the task has a ^READUPDATE posted on $RECEIVE and the
file number passed to ^AWAITIO is less than or equal to 0.
When the task is awakened, TSCODE again calls ^LISTEN. This process is
repeated until ^LISTEN finds a completed I/O or until a timeout occurs. The first
call to WAIT^EVENT uses the user’s timeout parameter to ^AWAITIO.
Subsequent calls pass -2d.
•
Assuming that the I/O completes, ^LISTEN returns the address of the associated
IOCB. If the task passed a tag parameter, ^AWAITIO stores iocb.histag into the
tag. In this way, the user is returned the I/O tag (tag) that was supplied to the
original call. Similarly, the buffer address (iocb.bufaddr) and count transferred
(iocb.iocnt) may be returned to the user. The IOCB, having now fulfilled its role, is
returned to the available IOCB list.
The available IOCB list operates in FIFO fashion if DEBUG^FLAGS is nonzero and
IOCBs are cleared when they are allocated rather than when they are deallocated.
Thus the available IOCB list provides a history of completed I/O operations in the
order in which those operations were passed back to the initiating task. While this
list can be a handy debugging aid, it does tend to increase the memory
requirements of GDSX when any debug flags are set.
•
If the task initiating the I/O completes it with a call to WAIT^EVENT instead of
^AWAITIO, TSCODE determines whether the masked events have occurred by
scanning the task’s completed I/O list. TSCODE then causes an appropriate event
(E^IOC or E^IMSG, for example) for the calling task. The task then calls ^LISTEN
to obtain the address of the IOCB. (See the description of the LINE^HANDLER in
Section 7, LINE^HANDLER Example, Design for details on the use of
WAIT^EVENT and ^LISTEN.)
Extended General Device Support (GDSX) Manual—529931-001
2- 93
I/O Involving $RECEIVE
Design and Development
I/O Involving $RECEIVE
For task I/O involving $RECEIVE, GDSX uses the IOCB and TCB tables described
previously and an additional table, the receive control block (RCB) table. An RCB is
associated with each GDSX opener.
When the TSCODE dispatcher is passed a new $RECEIVE request from Guardian
AWAITIO, it calls RECEIVEINFO (or FILE_GETRECEIVEINFO_) to obtain the process
ID (assigned to rcb.processid) and file number (assigned to rcb.tcp^file) of the
requester. After this data is hashed and the appropriate RCB list is searched, the
proper RCB can be located.
Among the entries in the RCB are the following:
rcb.link[0:1]
List linkage for available RCBs and for RCBx
corresponding to the same hash bucket
rcb.iocbh
Address of first IOCB (actually iocb.fcblink)
representing a request from this opener
rcb.iocbt
Address of last IOCB (actually iocb.fcblink)
representing a request from this opener
rcb.tcbaddr
Address of TCB for task associated with this
opener
rcb.pri^process^handle[0:9]
rcb.p^phandle[0:9]
= pri^process^handle
Process handle for primary
rcb.processid[0:3] = p^phandle
C-series process ID of this opener
rcb.ppid
PID of primary opener
rcb.bpid
PID of backup opener (0 if none)
rcb.tcp^file = pfile
Opener’s file number
rcb.flags
Opener’s flags parameter
rcb.syncdepth
Opener’s sync depth parameter
rcb.owner
Opener’s process access ID
Then rcb.tcbaddr is used to locate the proper TCB. An IOCB is allocated (if none is
currently available, the request is referred to the listener task, which may wait for an
IOCB). The IOCB is set up as follows:
iocb.iocnt
Count transferred from AWAITIO
iocb.cnt
Read count from RECEIVEINFO
iocb.tcbaddr
Address of TCB
iocb.file
0
Extended General Device Support (GDSX) Manual—529931-001
2- 94
I/O Involving $RECEIVE
Design and Development
iocb.msgtag
Message tag from RECEIVEINFO
iocb.rcbaddr
Address of requester control block
iocb.err
0 or FESYSMESS
The DEVICE^HANDLER Task Calls ^READUPDATE
At this point in time, the DEVICE^HANDLER task to receive the request may or may
not have a ^READUPDATE posted on its pseudo $RECEIVE. When a
DEVICE^HANDLER task calls ^READUPDATE(0,...), the following happens:
•
•
The task’s completed I/O list is searched to determine whether the task already
has a new request. If so, the task’s E^IMSG event is caused, the state of the IOCB
is set to 5 (pending), iocb.mytag is set to the caller’s tag parameter (if any), and
^READUPDATE returns.
If the task has no request on its completed I/O list, the task’s TCB is modified as
follows:
tcb.rcbsz
Read count, if passed; otherwise recvsz
tcb.rcvbuf
Buffer address, if passed; otherwise 0
tcb.rcvtag
Caller’s tag parameter, if passed; otherwise -1D
TSCODE Queues the IOCB
After TSCODE sets up the IOCB, it does the following:
•
•
•
•
•
If tcb.rcvsz is greater than 0 but tcb.rcvbuf is equal to 0 (the task has a
^READUPDATE posted but did not pass a buffer to ^READUPDATE), an attempt
is made to obtain a buffer in the buffer pool. The size of this buffer is the maximum
value of iocb.cnt and iocb.iocnt. If a buffer is obtained, its address is stored in
iocb.bufaddr and the state of the IOCB is set to 8.
If a buffer cannot be obtained or the task had no ^READUPDATE, an attempt is
made to allocate space in extended segment 1024. The size of this buffer is
iocb.iocnt. If space is not allocated, the request is deferred to the listener task to
wait for buffer space. If the allocation is successful, the address of the area is
stored in iocb.xbufaddr and iocb.state is set to 1. (If iocb.iocnt is 0, no extended
buffer is allocated and iocb.xbufaddr is set to 0D.)
Data is moved from the GDSX $RECEIVE buffer to the buffer addressed by
iocb.bufaddr (or xbufaddr).
The IOCB is inserted at the end of the receiving task’s completed I/O list and onto
the end of the RCB’s IOCB list (using iocb.fcblink).
If tcb.rcvsz is greater than 0:
°
The sign of tcb.rcvsz is inverted.
Extended General Device Support (GDSX) Manual—529931-001
2- 95
Design and Development
•
°
I/O Involving $RECEIVE
An E^IMSG event is posted against the receiving task.
Rcvtbl[iocb.msgtag] is set to @IOCB.
The DEVICE^HANDLER Task Calls ^AWAITIO
After the DEVICE^HANDLER task’s call to ^READUPDATE, when the task calls
^AWAITIO with the file parameter 0 or -1:
•
If an IMSG event for a task has occurred, ^LISTEN is called to look for IOCBs on
the task’s completed I/O list with iocb.file equal to 0. If found, the IOCBs are
deleted from the completed I/O list and its address is returned.
As ^LISTEN is passing a new $RECEIVE request to a task, it sets tcb.lastrcviocb
to the address of the IOCB representing that request. This is done so that
^RECEIVEINFO can locate all of the information that it needs to return to the
caller. IOCBs returned by ^LISTEN have iocb.state set to 9.
If iocb.state is equal to 1, ^LISTEN must allocate space in the buffer pool to hold
the request. If this attempt is not successful within the time specified in the
BUFFERTIMEOUT configuration parameter, the request is replied to with
FENOBUFSPACE (31). Otherwise, the request data, if any, is moved from
extended memory as iocb.xbufaddr and the extended memory space is
deallocated.
•
If ^LISTEN does not find a new request, and the file parameter to ^AWAITIO was
zero, tcb.rcvsz should be nonzero (that is, the task should have a ^READUPDATE
posted on $RECEIVE). If not, ^AWAITIO returns with CCL; a subsequent call to
^FILEINFO(0, ...) returns FENONEOUT.
WAIT^EVENT is called with the mask parameter allowing the task to be awakened
on the IMSG event.
When the DEVICE^HANDLER task finishes processing the request and calls ^REPLY:
•
•
•
Tcb.lastrcviocb is set to the address of the IOCB.
If no message tag is passed and the address of IOCB is zero, ^REPLY returns with
CCL; a subsequent call to ^FILEINFO returns FEBADREPLY.
If a message tag is passed and does not match iocb.msgtag:
°
°
•
•
•
The address of the IOCB is set to RCVTBL[message tag].
If the address of IOCB is 0 or iocb.tcbaddr is not equal to the current task’s
TCB, ^REPLY returns with CCL; a subsequent call to ^FILEINFO returns
FEBADREPLY.
REPLY is called.
RCBTBL[iocb.msgtag] is set to 0.
The IOCB is deleted from its RCB’s list.
Extended General Device Support (GDSX) Manual—529931-001
2- 96
Design and Development
•
Intertask Communication
The IOCB is deallocated.
Intertask Communication
The intertask communication (ITC) facility was implemented to enable
DEVICE^HANDLER tasks to have a device-oriented interface to subdevices on a line
or to communicate with other DEVICE^HANDLER or LINE^HANDLER tasks without
using the Guardian file and message system. ITC communication is also possible
between LINE^HANDLER tasks.
The first consideration for this type of facility is the allocation of device file numbers.
File numbers F in the range:
(MAXFILES - MAXTSK + MAXLINES + 5)< F <= MAXFILES
are reserved for ITC files. If a TSCODE call to the Guardian procedure OPEN returns
a file number in this range, ^OPEN closes the file and returns file error 32
(FENOCBSPACE) to the calling task’s ^FILEINFO(-1,..).
When initiating a new user task, TSCODE allocates the largest currently unused
number in the ITC range and assigns it as that task’s file number. The FCB for the file
is set up as follows:
fcb.public
0
fcb.lhaddr
Address of LINE^HANDLER’s TCB
fcb.owner
Address of DEVICE^HANDLER task’s TCB
fcb.type
1
So that GDSX $RECEIVE handling would not need to be changed, a file separate from
$RECEIVE was used for the LINE^HANDLER’s input queue. The actual value passed
to each LINE^HANDLER in the in^queue^file^num parameter is MAXFILES + 1.
When a DEVICE^HANDLER task initiates an I/O operation, the TSCODE-supported
service routines examine the file number passed to them. If the number is in the ITC
range, the request is routed to the associated LINE^HANDLER task by a call on the
procedure SEND^ITC^MSG.
The SEND^ITC^MSG procedure allocates an IOCB and links it to the
DEVICE^HANDLER’s TCB and the ITC file’s FCB, just as the IOCB would be for a
Guardian file. If the LINE^HANDLER has a current ^READUPDATE on its ITC file, the
IOCB is also linked to the LINE^HANDLER’s ITC request queue. The I/O initiation is
completed by causing the LINE^HANDLER’s ITC event.
LINE^HANDLER Processing
After the LINE^HANDLER task’s WAIT^EVENT returns E^ITC, the task calls
^LISTEN(0,0,1). ^LISTEN looks at the LINE^HANDLER’s ITC request queue; if the
queue is nonempty, the first element in the queue is delinked from the queue, its state
is changed to 6 (active), and its address is returned.
Extended General Device Support (GDSX) Manual—529931-001
2- 97
USAMPLE Example Program
Design and Development
When the task finishes processing the request and calls NOTIFY^IO^COMPLETION,
the IOCB is delinked from the DEVICE^HANDLER task’s TCB and the ITC file’s FCB
and is queued on the DEVICE^HANDLER task’s completed I/O list. Also, the IOCB’s
state is changed to 5 (pending). Finally, the DEVICE^HANDLER task’s IOC event is
posted. This is the same action that takes place when a Guardian I/O operation
completes.
Canceling a Request
When a DEVICE^HANDLER task cancels an I/O that is linked to its tcb.iocbh, the
^CANCELREQ procedure locates the associated IOCB just as it would for a Guardian
file I/O. Rather than calling CANCELREQ, however, ^CANCELREQ determines the
state of the IOCB and acts as follows:
•
•
If the iocb.state is 2 (io^itc^queued), TSCODE delinks and deallocates the IOCB.
Note that when the LINE^HANDLER calls ^LISTEN, it may be the case that no
IOCB is returned.
If the iocb.state is 6 (active), TSCODE delinks the IOCB from the
DEVICE^HANDLER task’s TCB and links it to the LINE^HANDLER’s TCB in
tcb.iocbh/iocbt. This is done so that the IOCB is guaranteed to be deallocated
even if both the DEVICE^HANDLER task and the LINE^HANDLER are terminated.
The IOCB’s state is set to io^canceled. Finally, the LINE^HANDLER’s E^CAN
event is canceled.
USAMPLE Example Program
The sample LINE^HANDLER provided in the installed subvolume file USAMPLE was
used to validate and debug the Envoy interface facility, and is not intended for
production use. It does, however, show one possible approach to implementing an
Envoy interface and can serve as the basis for a viable production LINE^HANDLER.
USAMPLE can be run as a converted or an unconverted process. See Running a
GDSX Application on page 3-1.
The installed subvolume file ULHDECS is used when compiling USAMPLE.
ULHDECS was created by modifying DCCBDECS. Seven words have been added to
the DCB structure:
!2!
!2!
!1!
!1!
!1!
STRING
STRING
INT
INT
INT
poll^addr[0:3];
sel^addr [0:3];
iocbaddr;
poll^inx;
sel^inx;
!Current request
!Polling Index Into Poll list
!Select Index Into Poll list
Therefore, this example program must be started with EXTSUSIZE is equal to 7 or
greater. Notice that the procedure USER^INITIALIZE checks to be certain that this is
the case; if it is not, an error message is generated, and the GDSX process is stopped
by a call on ^TERMINATE.
Extended General Device Support (GDSX) Manual—529931-001
2- 98
Design and Development
USER^STOP
Opens are associated with devices by the simple expediency of assigning an openid
equal to the address of the associated DCB. Consequently, the procedure
USER^START merely sets openid to @DCB, clears dcb.link and dcb.iocbaddr, and
returns.
USER^STOP
The procedure USER^STOP must be able to handle the termination of both
LINE^HANDLER tasks and DEVICE^HANDLER tasks; the subprocedures STOP^LINE
and STOP^DEVICE^HANDLER handle these cases.
STOP^LINE does the following:
Initializes the local variable lineno from the task’s TCB state word. This is the line for
which the terminating task was the handler.
1. Initializes the local STRUCT pointer line to point to linetbl[lineno].
2. Scans the DCB table looking for active terminals on line LINENO. When one is
found, the first link word in the DCB is set to zero; this is done so that when the line
is restarted, attempts to insert the DCB on a linked list will not fail.
Also cleared is dcb.iocbaddr. This is done to prevent hanging up terminals on the
line that are also stopping (see STOP^DEVICE^HANDLER below).
3. The state word in the line table entry for the line being downed is set to zero.
STOP^DEVICE^HANDLER simply cancels any outstanding terminal I/O. Notice that
the subprocedure waits until dcb.iocbaddr is zero before returning. This is to ensure
that the LINE^HANDLER (STOP^LINE) has processed the cancel before the task is
deleted.
Note that in the USER^STOP procedure body, the determination of which
subprocedure to call is based on whether the openid for the stopping task is equal to
-1. If it is not -1, this is a DEVICE^HANDLER task being terminated, and GDSX is
functioning as an Envoy LINE^HANDLER. As the default value of openid is -1, if the
current openid is -1, this is either a LINE^HANDLER terminating, or GDSX is not
functioning as an Envoy LINE^HANDLER. This determination is made by testing
MAXLINES, which is nonzero if GDSX is functioning as a LINE^HANDLER.
The LINE^HANDLER Procedure
The following paragraphs comprise a top-down description of LINE^HANDLER
processing:
The main body of LINE^HANDLER consists solely of a call to the subprocedure
LINE^HANDLER^BODY. LINE^HANDLER^BODY declares an IOCB pointer, the
address of which is assigned by a call to ^LISTEN.
Extended General Device Support (GDSX) Manual—529931-001
2- 99
Design and Development
The LINE^HANDLER Procedure
First, a call is made to ^CHECKPOINT(1) to checkpoint the task stack. This is the only
call to ^CHECKPOINT in the LINE^HANDLER and merely serves to speed up takeover
after a failure.
Next LINE^HANDLER^BODY posts ^READUPDATE operations on $RECEIVE and
IN^QUEUE^FILE^NUM and calls the subprocedure LINE^STATE^MACHINE to start
the line. Although the parameter IOCB does not contain a valid IOCB address, the
state machine does not expect any IOCB to be associated with this call and does not
reference the parameter.
LINE^HANDLER^BODY then enters its main processing loop. The first step in this
loop is a CASE statement based on the value returned from WAIT^EVENT. This is the
only call to WAIT^EVENT in LINE^HANDLER. The events waited on are DISP^CAN,
DISP^IMSG, DISP^IOC, and DISP^ITC. In addition, if no event occurs in 10 seconds,
the wait will time out.
If a timeout occurs and the line is in a closed state, the state machine is called in an
attempt to restart the line. The error handling in this sample code is rather crude. If an
error cannot be dumped on a particular terminal, the line goes into a closed state, with
a restart attempted after 10 seconds.
If a cancel event occurs, a call is made to the subprocedure CANCEL^REQUESTS
(see the following paragraphs).
If an ITC event occurs, the IOCB describing the request is obtained by a call on
^LISTEN and passed to the subprocedure QUEUE^REQUEST. QUEUE^REQUEST
may handle the IOCB immediately or it may queue the request for later processing by
LINE^STATE^MACHINE (see the following paragraphs).
If an I/O completion event occurs, it must be a completion on the LINE file as this is the
only file other than $RECEIVE and IN^QUEUE^FILE^NUM that the LINE^HANDLER
deals with. Consequently, the IOCB describing the result of the I/O is obtained by
calling ^LISTEN and is passed to the state machine for processing.
The last step in the main processing loop is to call LINE^STATE^MACHINE if the line
is idle so that it can process any new requests that may have been queued as a result
of the last event.
As mentioned previously, initial request processing is done in QUEUE^REQUEST.
This subprocedure first does minimal tests to determine if the request’s openid is valid.
If it is not, the LINE^HANDLER suspends itself with fault 999 by invoking the define
“TRAP.” Otherwise, the procedure enters a CASE statement based on the operation
type of the passed IOCB. CONTROL and SETMODE requests are handled
immediately by calls on the subprocedures CONTROL^REQUEST and
SETMODE^REQUEST respectively. These subprocedures do not simulate the
behavior of Guardian CONTROL and SETMODE operations, but rather end the
request with no error if the request is likely for a terminal, or FEINVALOP if not.
For WRITE, READ and WRITEREAD requests, a test is made to see if there is already
an active request on the terminal. If so, the request is immediately completed with
error FETOOMANY. Otherwise, dcb.iocbaddr is set to the address of the current
Extended General Device Support (GDSX) Manual—529931-001
2 -100
The LINE^HANDLER Procedure
Design and Development
request’s IOCB. Next, a test is made to determine if this is a WRITE (or WRITEREAD)
request. If it is a WRITE, a call is made to INSERT^WRITE^QUEUE; otherwise,
READ^DEVICE is called.
INSERT^WRITE^QUEUE determines whether the write queue is empty. If the queue
is empty, INSERT^WRITE^QUEUE calls CHECK^HALT^POLL. CHECK^HALT^POLL
maintains a flag named polled^halting in LINE^HANDLER’s locals. If poll^halting is
false and the line is currently polling, a call to HALTPOLL is made, and poll^halting is
set to one. This is necessary because continuous polling is used on the multipoint line.
The only purpose for passing a DCB to CHECK^HALT^POLL is to be able to trace the
select index of the subdevice that necessitated stopping polling. The design strategy is
to favor WRITE operations over READs so that if there are any DCBs in the write
queue, no polling is done (the poll may be halting, however). Next, the DCB for the
current request is linked into the WRITE^QUEUE.
Rather than maintain a list of reading subdevices, a count (readers) of subdevices
whose current request is a READ is maintained. READ^DEVICE increments this count
and calls CHANGELIST to enable polling of this terminal.
After a request has been processed, there is a call to END^WRITE^REQUEST or
END^READ^REQUEST as appropriate.
END^WRITE^REQUEST deletes from the write queue the DCB for the device just
written and calls END^REQUEST. END^READ^REQUEST calls END^REQUEST,
decrements readers, and calls CHANGELIST to disable polling of the device.
END^REQUEST determines whether the passed IOCB is the current request for its
DCB. If it is, END^REQUEST sets dcb.iocbaddr to zero. After setting up iocb.err (if
appropriate), END^REQUEST posts this error for the STATUS SU command in SCF.
Finally, END^REQUEST calls NOTIFY^IO^COMPLETION to complete the
DEVICE^HANDLER task’s I/O operation.
Request cancellation is handled in two steps. Recall that when a cancel event occurs,
the main loop calls CANCEL^REQUESTS. This subprocedure sets the flag
cancel^seen and halts polling. No further action is taken at this time so that there is no
concern about what the state machine is doing with a request when its IOCB is
deallocated. The next time the line is idle, there is a call to subprocedure
CHECK^CANCELS, which finds cancel^seen set and scans all of the line’s active
DCBs checking IOCBs for cancellation.
The line state machine defines six line states, as follows:
Line State
Description
0 - line^closed
The line is logically closed. This is the initial line state.
1 - line^idle
The line is logically up with no current line activity.
2 - line^polling
A read is currently posted on the line.
3 - line^writing
A write operation is currently posted on the line.
4 - line^readeot
A continuation read is posted on the line.
5 - line^resetting
A CONTROL 13 is posted on the line.
Extended General Device Support (GDSX) Manual—529931-001
2 -101
Design and Development
The LINE^HANDLER Procedure
Entries in the state transition table (line^state^table) contain four bytes, as follows:
•
•
•
•
Byte 0: Current state
Byte 1: Result of previous action
Byte 2: Next action
Byte 3: Next state
The line state machine consists of an indefinite loop in which:
1. The result of the previous line action is evaluated and stored in the local variable
rslt. This evaluation is done by a CASE FORM expression with the case index
being the current line state. Typed subprocedures return a number indicating the
result of each particular action.
2. The state transition table is indexed based on the current line state and rslt.
When a match is found, byte 2 of the matching entry is stored in the local variable
action and the line state is changed to byte 3 of the entry. If a match is not found,
there is an error in constructing the state transition table.
3. The next line action is initiated by a CASE statement, which uses action as an
index. The possible actions are:
•
•
•
•
•
•
1 : la^null: Do nothing (but continue in the state machine).
2 : la^write: Initiate a WRITE operation on the line. If the operation is
successfully initiated, exit the state machine.
3 : la^abort: Issue a “Line aborted” message and exit the state machine.
4 : la^read: Initiate a READ operation on the line. If the operation is
successfully initiated, exit the state machine.
5 : la^reset: Initiate a CONTROL 13 on the line. If the operation is
successfully initiated, exit the state machine.
6 : la^wait: Exit the state machine.
Note that in those cases that initiate nowait I/O operations, if the operation is
initiated successfully, the state machine is exited and is reentered when the I/O
completes.
If the I/O is not successfully initiated, a file management error number is stored in
the variable action^error, and the subprocedure that attempted the I/O returns
zero. When this happens, the state machine obtains a temporary IOCB by a call
on ALLOCATEIOCB and stores action^error in iocb.err. In this way, the code for
handling I/O completions within the state machine does not have to be sensitive to
whether the error was detected at I/O initiation time or was returned at I/O
completion.
When an initial read operation completes, the subprocedure INITIAL^READ is called.
INITIAL^READ resets the poll^halting flag, then determines whether polling completed
with no subdevice responding (file error 176). If the latter is the case, any subdevices
Extended General Device Support (GDSX) Manual—529931-001
2 -102
Design and Development
The LINE^HANDLER Procedure
on the slow poll list are placed back on the poll list by a CHANGELIST(.., -2,..) call.
As the line is now idle, a call is made to CHECK^CANCELS to get rid of any canceled
IOCBs.
Note. If this LINE^HANDLER is to be used in a production environment, handling of the slow
poll list should be improved.
If no error occurred on the READ operation, some subdevice responded to the poll. A
call to the subprocedure FIND^DCB locates the DCB corresponding to this subdevice.
FIND^DCB returns 1 if the DCB is located, and 0 otherwise. If 1 is returned,
FIND^DCB has also set adcb to point to the proper DCB and aiocb to point to the
IOCB for the READ request.
Aiocb.bufaddr is examined to see whether the DEVICE^HANDLER task passed a
buffer to ^READ. If it did not, a buffer is allocated and given to the task. Note that if
the buffer owner is not changed, aiocb.bufaddr is reset, and the user’s request is
completed with file error 31 (FENOBUFSPACE) instead of trapping the
LINE^HANDLER. This is done to handle the case where the DEVICE^HANDLER task
requesting this I/O terminates during the wait for a buffer.
Assuming that a buffer is allocated, the text portion of the received message is moved
into that buffer. In the process:
•
•
The variable ab is set to point to the user’s buffer.
The variable asb is set to point to the next available byte in the buffer.
If an error other than 176 has occurred on the read, there is an attempt to dump the
error on the reader of the device.
To wrap up processing, the IOCB associated with the Envoy READ operation is
deallocated and a result is returned:
0
Error other than 176 occurred
1
Error 176
2
No error
If no error occurred, another READ is posted on the line. When this READ completes,
the subprocedure CONTINUATION^READ is called. CONTINUATION^READ ensures
that aiocb is nonzero, then determines if an EOT was received from the device. If it
was, the number of bytes read is stored in aiocb.iocnt, and the request is completed. If
no error occurred, another block of this input message has been received. Using asb,
the text from this message is appended to the end of the user’s buffer. In this case,
another read is initiated on the line and CONTINUATION^READ is called again. If an
error occurred on the read, the user task’s READ request is completed to return the
error.
Extended General Device Support (GDSX) Manual—529931-001
2 -103
The DEVICE^HANDLER Procedure
Design and Development
As a final step, CONTINUATION^READ deallocates the IOCB associated with the
Envoy READ operation and returns:
0
Error occurred
1
EOT received
2
Text received
When a WRITE or WRITEREAD operation is initiated on a line, the subprocedure
WRITE^ACTION is called. Before this call, the subprocedure LOOK has set adcb to
point to the DCB for the subdevice targeted for the write.
WRITE^ACTION verifies that adcb has a current WRITE or WRITEREAD request. If
this is not the case, a trap occurs. Otherwise, the appropriate control characters are
added to the DEVICE^HANDLER-supplied text and the WRITE or WRITEREAD
operation is initiated.
When the I/O completes, the subprocedure WRITE^COMPLETE is called. The
DEVICE^HANDLER task request is completed with any error that occurred, and the
IOCB associated with the Envoy WRITE operation is returned.
The DEVICE^HANDLER Procedure
The DEVICE^HANDLER procedure included in USAMPLE is usable either with the
LINE^HANDLER or in environments that are not Envoy environments. The procedure
body is a state machine having the same basic design as the machine employed in the
LINE^HANDLER. Seventeen device states are defined, as follows:
Device State
Description
0 - d^null
Task has no I/O operations outstanding.
1 - d^idle
READUPDATE posted on $RECEIVE; waiting on request from
requester process.
2 - d^request
A new request has been received from the external opener. No I/O
operations outstanding.
3 - d^write
WRITE operation in process to terminal.
4 - d^read
READUPDATE posted on $RECEIVE.
5 - d^read1
READ operation in process on terminal; READUPDATE posted on
$RECEIVE.
6 - d^setmode
SETMODENOWAIT in process to terminal.
7 - d^control
CONTROL in process to terminal.
8 - d^writeread
READUPDATE posted on $RECEIVE.
9 - d^writeread1
WRITEREAD operation in process on terminal; READUPDATE posted
on $RECEIVE.
10 - d^preread
READUPDATE posted on $RECEIVE.
11 - d^preread1
CONTROL 22 posted on terminal; READUPDATE posted on
$RECEIVE.
Extended General Device Support (GDSX) Manual—529931-001
2 -104
The DEVICE^HANDLER Procedure
Design and Development
Device State
Description
12 - d^preread2
READ posted on terminal; READUPDATE posted on $RECEIVE.
13 - d^preread3
READ posted on terminal; READUPDATE posted on $RECEIVE.
14 - d^reset1
A -20 system message has been received. A SETMODENOWAIT is in
process to set the access mode for the terminal to break access.
15 - d^reset2
A zero-length write is in process to position the cursor to column 1 of
the next row on the terminal.
16 - d^reset3
A SETMODENOWAIT is in process to set the terminal mode and
access to normal.
Device actions defined are as follows:
Device Action
Description
1 - da^null
Do nothing.
2 - da^read^receive
Post ^READUPDATE on $RECEIVE.
3 - da^read
Initiate READ on terminal.
4 - da^write
Initiate WRITE to terminal.
5 - da^setmode
Initiate SETMODENOWAIT to terminal.
6 - da^control
Initiate CONTROL to terminal.
7 - da^reply
Reply to oldest external process request.
8 - da^cancel
Cancel current terminal operation.
9 - da^writeread
Initiate WRITEREAD to terminal.
10 - da^preread
Initiate a READ on the terminal with no buffer specified
(LINE^HANDLER will supply buffer).
11 - da^readdata
Initiate READ for data (after completion of CONTROL 22).
12 - da^reset1
Initiate a SETMODENOWAIT to set access to break access.
13 - da^reset2
Initiate a null write to the terminal.
14 - da^reset3
Initiate a SETMODENOWAIT to set terminal mode and access to
normal.
15 - da^error
Unexpected event occurred at this state.
Using this DEVICE^HANDLER, the data from the device is read before replying to the
external requester’s CONTROL 22 so that when the requester issues a subsequent
READ, the data necessary for an immediate reply is available.
DEVICE^HANDLER implements debugging features by means of the DEBUGFLAGS
configuration parameter. These facilities are intended for debugging only and should
be deleted if the sample code is to form the basis of a production LINE^HANDLER.
Extended General Device Support (GDSX) Manual—529931-001
2 -105
Design and Development
The DEVICE^HANDLER Procedure
Extended General Device Support (GDSX) Manual—529931-001
2 -106
3
Operations and Support
This section contains information about:
•
•
•
•
•
•
Running a GDSX application
Managing a GDSX application with SCF
Using the code and data spaces
Setting GDSX configuration parameters
Dealing with a GDSX abend
Interpreting console and EMS messages
Running a GDSX Application
Running a GDSX application can involve six steps:
1. Running a filter to display EMS messages. This is optional. For instructions on
writing and running a filter, see EMS Filters and GDSX on page 2-79.
2. Entering TACL ASSIGN and/or PARAM commands. The commands entered
depend on the application.
3. Entering a TACL command to SET HIGHPIN ON or OFF.
4. Running a GDSX process or several GDSX processes.
5. Running SCF. SCF is usually needed to manage the GDSX subsystem, although
in some cases SCF may not be necessary, or another management application
may be used instead.
6. Running a requester process, or several requester processes. The requester may
be a Pathway/iTS TCP.
Tutorials on running GDSX example applications are presented in Section 4,
DEVICE^HANDLER Example, Running and Managing and Section 6, LINE^HANDLER
Example, Running and Managing.
Running GDSX at a High or Low PIN
A GDSX process started with a RUN command can run at a high PIN only if all three of
the following conditions are true:
•
•
•
The process’s HIGHPIN object file attribute is set ON (as a result of settings made
at compile time or bind time).
Either the TACL #HIGHPIN built-in variable is ON or the HIGHPIN ON option is
specified when you run the GDSX process.
D^plus^enabled of the CONTROLFLAGS configuration parameter is set to 1.
Extended General Device Support (GDSX) Manual—529931-001
3 -1
Operations and Support
ASSIGN and PARAM Commands
In all other cases, the operating system runs GDSX at a low PIN. Even if all the above
conditions are true, if a high PIN is not available, GDSX runs at a low PIN.
For information on setting the HIGHPIN object file attribute or the TACL #HIGHPIN
built-in variable, see the Guardian Application Conversion Guide.
ASSIGN and PARAM Commands
Before running a GDSX process, if it is necessary to clear any previously set
parameter values, enter the following command at a TACL prompt:
> CLEAR ALL
Then enter any TACL ASSIGN or PARAM commands that are necessary for your
application. The syntax for the ASSIGN command is:
ASSIGN logical-unit , actual-file-name
The syntax for the PARAM command is:
PARAM configuration-parameter value
For example, to specify a maximum of two LINE^HANDLER tasks for a GDSX
process, enter the following command:
> PARAM MAXLINES 2
To specify a maximum of 30 simultaneous external openers for a GDSX process, enter
the following command:
> PARAM MAXOPENS 30
To specify that your GDSX process is converted, set d^plus^enabled of the
CONTROLFLAGS configuration parameter to 1 by entering the following command:
> PARAM CONTROLFLAGS 8
Caution. The PARAM CONTROLFLAGS command also turns off all the other flags in the
CONTROLFLAGS configuration parameter. See CONTROLFLAGS on page 2-52.
Many configuration parameters can also be set or changed within SCF. For detailed
information on the configuration parameters, see GDSX Configuration Parameters on
page 3-13.
Running a GDSX Process
The RUN command to start GDSX is:
RUN GDSX-object-file / run-option-list / [ backup-cpu-number
]
Extended General Device Support (GDSX) Manual—529931-001
3 -2
Operations and Support
Running a GDSX Process
GDSX-object-file
is the name of the GDSX object file.
run-option-list
is a list of one or more Guardian run options separated by commas. Only the
NAME option is required. The options that are significant for running GDSX are
the following:
NAME $GDSX-process-name
designates the symbolic name to be assigned to the GDSX process. The
GDSX-process-name must follow Guardian naming conventions for
processes. The process must be named so that application processes and
SCF can open GDSX.
NOWAIT
means that the initiating command interpreter is not to wait while GDSX starts
up, but is to return a command input prompt immediately after sending the
startup message to the process.
OUT file-name
specifies a file for output from the GDSX process.
PRI priority-number
specifies the execution priority of the GDSX process.
CPU integer
designates the CPU in which the GDSX primary process is to run.
HIGHPIN { ON | OFF }
specifies whether NonStop operating system is to try to run the GDSX process
at a high PIN.
backup-cpu-number
is an optional parameter. It indicates the CPU in which a backup GDSX process is
to run.
If you run a filter before starting GDSX, running GDSX causes a startup message to
appear on the display terminal specified by the filter.
Examples
1. Running a single GDSX process named $GDSX:
> RUN GDSE /NAME $GDSX, NOWAIT/
Extended General Device Support (GDSX) Manual—529931-001
3 -3
Operations and Support
Running SCF and Starting Requesters
2. Running GDSX as a process pair named $GDSX. The execution priority is 150,
the primary process is to run in CPU 2, and the backup is to run in CPU 3:
> RUN GDSE /NAME $GDSX, NOWAIT, PRI 150, CPU 2/ 3
Running SCF and Starting Requesters
A GDSX application is usually designed either to never run with a LINE or to always
run with one or more LINEs. (The tutorial example programs are unusual, because
they can be run either without any LINE or with one or more LINEs.) In any case, SCF
is normally used to configure the GDSX application. The two basic configurations are:
•
Without a LINE
This type of configuration requires that the devices have unique Guardian file
names that can be opened directly by GDSX. Some access methods that support
this kind of direct access are AM3270, Async Termprocess, X25AM, and CSS
Async (6100).
In this type of configuration there can be dynamic SUs and preconfigured SUs. A
dynamic SU is an SU not configured through SCF, but created when an external
process opens a file through GDSX. A preconfigured SU is an SU configured with
SCF before a requester sends GDSX an OPEN for the file associated with the SU.
•
With a LINE
These applications involve shared data communications facilities where the line (or
message switching process) has a Guardian file name, but the individual devices
on the line do not. Some data communications products that do not allow direct
addressing of terminals on lines are CP6100 ADCCP/NRM, CP6100 Bisync
Multipoint, Envoy, and EnvoyACP/XF.
In this type of configuration there can be (preconfigured) LINEs, dynamic SUs, and
preconfigured SUs.
Running GDSX Without a LINE
In all of the following examples of commands used to configure GDSX applications
without a LINE, the requester program APPLS is used. (A listing of APPLS appears in
Appendix A.)
The OUT file specified in the RUN command used to start APPL is used by APPL to
open GDSX. The OUT file always specifies the name of a GDSX process qualified by
a subdevice name. (GDSX requires that external processes provide a two-level or
three-level qualified name when opening GDSX. A simple process name, for example,
$GDSX, is not allowed.)
An example of how Pathway/iTS requesters may be used in a GDSX application is
provided in Running a Pathway/iTS Application on page 3-9.
Extended General Device Support (GDSX) Manual—529931-001
3 -4
Operations and Support
Running SCF and Starting Requesters
The simplest GDSX configuration has no LINE and only dynamic SUs. Here are
commands for a configuration that does I/O by means of a device $TC1:
> RUN GDSE /NAME $GDSX, NOWAIT/
> RUN APPL /NAME $A1, OUT $GDSX.#TC1, NOWAIT/
The default for the configuration parameter MAXLINES (the maximum number of
LINE^HANDLER tasks) is 0, so this parameter value is not entered. (This is how the
GDSX example program is started in Section 4, DEVICE^HANDLER Example,
Running and Managing.)
This is the only type of configuration for which SCF is not needed to configure the
application. If SCF is used to manage the application, all currently configured SUs,
preconfigured and dynamic, are listed when the following command is issued:
-> INFO SU $GDSX-process-name.*.*
In the preceding example the device name $TC1 becomes #TC1 when combined with
the GDSX process name in the RUN command for the requester. When the
application process $A1 opens $GDSX.#TC1, GDSX receives the open message,
derives the device name $TC1 from the message, and opens file $TC1.
If the preceding example uses a device with name $TC1.#C11, the commands are:
> RUN GDSE /NAME $GDSX, NOWAIT/
> RUN APPL /NAME $A1, OUT $GDSX.#TC1.C11, NOWAIT/
Here the device name $TC1.#C11 becomes #TC1.C11 when combined with the GDSX
process name in the RUN command for the requester. When the application process
$A1 opens $GDSX.#TC1.C11, GDSX receives the open message, derives the device
name $TC1.#C11 from the message, and opens file $TC1.#C11.
If a GDSX application uses SCF to preconfigure an SU TC1 using a device named
$TC1, the following commands could be issued:
> RUN GDSE /NAME $GDSX, NOWAIT/
-> SCF
-> ADD SU $GDSX.#TC1
> RUN APPL /NAME $A1, OUT $GDSX.#TC1, NOWAIT/
Note how the device name $TC1 becomes #TC1 when combined with the GDSX
process name in the last two commands. When SCF is used to add the SU, the GDSX
process derives the proper device name from the ADD command, but does not open
the file until receiving an open message from requester $A1.
If the last example uses a device with name $TC1.#C11, the commands are:
> RUN GDSE /NAME $GDSX, NOWAIT/
-> SCF
-> ADD SU $GDSX.#TC1.C11
> RUN APPL /NAME $A1, OUT $GDSX.#TC1.C11, NOWAIT/
Now the device name $TC1.#C11 becomes #TC1.C11 when combined with the GDSX
process name in the last two commands.
Extended General Device Support (GDSX) Manual—529931-001
3 -5
Operations and Support
Running SCF and Starting Requesters
The last example can also be done with an SU having object name D1 and an access
name, which is used to specify the file to be accessed through GDSX:
> RUN GDSE /NAME $GDSX, NOWAIT/
-> SCF
-> ADD SU $GDSX.#D1, ACCESSNAME $TC1.#C11
> RUN APPL /NAME $A1, OUT $GDSX.#D1, NOWAIT/
When GDSX is opened by requester $A1, the name of the file to be opened is not
derived as in the above examples but is taken from the name given by the
ACCESSNAME attribute.
Note that for any of the three preceding examples using preconfigured SUs, dynamic
SUs may also be used. Dynamic SUs and preconfigured SUs may coexist in a GDSX
application. For example, in the preceding example after running application process
$A1, another command could be issued to start a requester $A2 that sends output
through GDSX to terminal $TC2.#C22:
> RUN GDSE /NAME $GDSX, NOWAIT/
-> SCF
-> ADD SU $GDSX.#D1, ACCESSNAME $TC1.#C11
> RUN APPL /NAME $A1, OUT $GDSX.#D1, NOWAIT/
> RUN APPL /NAME $A2, OUT $GDSX.#TC2.C22, NOWAIT/
Here requester $A1 communicates through $GDSX to $TC1.#C11, and requester $A2
communicates through $GDSX to $TC2.#C22. Within SCF, all currently configured
SUs (both preconfigured and dynamic) are listed when the following command is
issued:
-> INFO SU $GDSX-process-name.*.*
A GDSX process can access a device located on a remote node if the device is
preconfigured with SCF. (This cannot be done with a dynamic SU, because the node
name cannot be specified.) For example, suppose a GDSX process $GDSX is run on
node \LA:
> RUN GDSE /NAME $GDSX, NOWAIT/
-> SCF
-> ADD SU $GDSX.#D1, ACCESSNAME \NY.$IOP1.#TC1
> RUN APPL /NAME $A1, OUT $GDSX.#D1, NOWAIT/
When requester $A1 starts up, the file $IOP1.#TC1 will be accessed on node \NY.
Running GDSX With a LINE
In all of the following examples of commands used to configure GDSX applications
with a LINE, the requester program APPL is used. (A listing of APPLS appears in
Appendix A.) The OUT file specified in the RUN command used to start APPL is used
by APPL to open GDSX. The OUT file always specifies the name of a GDSX process
qualified by LINE and/or subdevice names.
Note. GDSX requires that external processes provide a two-level or three-level qualified name
when opening GDSX. A simple process name, $GDSX, for example, is not allowed.
Extended General Device Support (GDSX) Manual—529931-001
3 -6
Operations and Support
Running SCF and Starting Requesters
An example of how Pathway/iTS requesters may be used in a GDSX application is
provided in Running a Pathway/iTS Application on page 3-9
The configuration parameter with external parameter name MAXLINES is used to
specify the maximum number of LINEs that may be configured for the GDSX process.
The default for the parameter is zero. To run GDSX with a LINE, the configuration
parameter must be set to some positive integer less than 15 either by an assignment
within the USER^INIT^CONFIG^PARAMS user exit of the GDSX object file or by a
TACL PARAM command. See MAXLINES on page 2-65.
In a GDSX application with a LINE, there can also be dynamic SUs and preconfigured
SUs. All SUs under a LINE must be preconfigured. SUs not under a LINE can be
dynamic or preconfigured.
When adding SUs under a LINE:
1. Add the LINE.
2. Add the SUs under the LINE.
3. Start the LINE.
Then run the applications that communicate with the SUs under the LINE.
Note. SUs may not be added under a LINE unless the LINE is stopped. After starting a LINE,
if you want to add an SU under the LINE, you need to stop the LINE first.
Here is an example of a configuration having a LINE and two SUs under the LINE:
> PARAM MAXLINES 1
> RUN GDSE /NAME $GDSX, NOWAIT/
-> SCF
-> ADD LINE $GDSX.#LINE1, ACCESSNAME $IOP1
-> ADD SU $GDSX.#LINE1.DEV1
-> ADD SU $GDSX.#LINE1.DEV2
-> START LINE $GDSX.#LINE1
> RUN APPL /NAME $A1, OUT $GDSX.#LINE1.DEV1, NOWAIT/
> RUN APPL /NAME $A2, OUT $GDSX.#LINE1.DEV2, NOWAIT/
When the LINE is started in SCF, GDSX references the access name for the LINE and
opens $IOP1. All devices on the LINE are then available for access. When requester
$A1 runs, GDSX opens SU $DEV1 under LINE1, establishing a thread from $A1
through $GDSX to $IOP1.#DEV1. When requester $A2 runs, GDSX opens SU $DEV2
under LINE1, establishing a thread from $A2 through $GDSX to $IOP1.#DEV2.
The last example can also be configured using ACCESSNAME attributes to specify the
files to be accessed through GDSX:
> PARAM MAXLINES 1
> RUN GDSE /NAME $GDSX, NOWAIT/
-> SCF
-> ADD LINE $GDSX.#LINE1, ACCESSNAME $IOP1
-> ADD SU $GDSX.#LINE1.D1, ACCESSNAME $IOP1.#DEV1
-> ADD SU $GDSX.#LINE1.D2, ACCESSNAME $IOP1.#DEV2
-> START LINE $GDSX.#LINE1
Extended General Device Support (GDSX) Manual—529931-001
3 -7
Operations and Support
Running SCF and Starting Requesters
> RUN APPL /NAME $A1, OUT $GDSX.#LINE1.D1, NOWAIT/
> RUN APPL /NAME $A2, OUT $GDSX.#LINE1.D2, NOWAIT/
When the LINE is started in SCF, GDSX opens $IOP1. When requester $A1 runs,
GDSX opens SU D1, establishing a thread from $A1 through $GDSX to $IOP1.#DEV1.
When requester $A2 runs, GDSX opens SU D2, establishing a thread from $A2
through $GDSX to $IOP1.#DEV2.
If a preconfigured SU D3 is ADDed to the last example, but D3 is not added under the
LINE, the following commands can be used:
> PARAM MAXLINES 1
> RUN GDSE /NAME $GDSX, NOWAIT/
-> SCF
-> ADD LINE $GDSX.#LINE1, ACCESSNAME $IOP1
-> ADD SU $GDSX.#LINE1.D1, ACCESSNAME $IOP1.#DEV1
-> ADD SU $GDSX.#LINE1.D2, ACCESSNAME $IOP1.#DEV2
-> START LINE $GDSX.#LINE1
> RUN APPL /NAME $A1, OUT $GDSX.#LINE1.D1, NOWAIT/
> RUN APPL /NAME $A2, OUT $GDSX.#LINE1.D2, NOWAIT/
-> ADD SU $GDSX.D3, ACCESSNAME $TC3.#C33
> RUN APPL /NAME $A3, OUT $GDSX.#D3, NOWAIT/
The example can be further extended with a dynamic SU $TC4.#C44 that is not
configured under the LINE:
> PARAM MAXLINES 1
> RUN GDSE /NAME $GDSX, NOWAIT/
-> SCF
-> ADD LINE $GDSX.#LINE1, ACCESSNAME $IOP1
-> ADD SU $GDSX.#LINE1.D1, ACCESSNAME $IOP1.#DEV1
-> ADD SU $GDSX.#LINE1.D2, ACCESSNAME $IOP1.#DEV2
-> START LINE $GDSX.#LINE1
> RUN APPL /NAME $A1, OUT $GDSX.#LINE1.D1, NOWAIT/
> RUN APPL /NAME $A2, OUT $GDSX.#LINE1.D2, NOWAIT/
-> ADD SU $GDSX.D3, ACCESSNAME $TC3.#C33
> RUN APPL /NAME $A3, OUT $GDSX.#D3, NOWAIT/
> RUN APPL /NAME $A4, OUT $GDSX.#TC4.C44, NOWAIT/
If SCF is used to manage the application, all currently configured SUs (both
preconfigured and dynamic) are listed when the following command is issued:
-> INFO SU $GDSX-process-name.*.*
A GDSX process can access a device on a remote node if the device is preconfigured
with SCF. For example, suppose a GDSX process $GDSX is run on node \LA:
> PARAM MAXLINES 1
> RUN GDSE /NAME $GDSX, NOWAIT/
-> SCF
-> ADD LINE $GDSX.#LINE1, ACCESSNAME \NY.$IOP1
-> ADD SU $GDSX.#LINE1.D1, ACCESSNAME \NY.$IOP1.#DEV1
-> ADD SU $GDSX.#LINE1.D2, ACCESSNAME \NY.$IOP1.#DEV2
-> START LINE $GDSX.#LINE1
> RUN APPL /NAME $A1, OUT $GDSX.#LINE1.D1, NOWAIT/
> RUN APPL /NAME $A2, OUT $GDSX.#LINE1.D2, NOWAIT/
Extended General Device Support (GDSX) Manual—529931-001
3 -8
Running a Pathway/iTS Application
Operations and Support
When requester $A1 starts up, the file $IOP1.#DEV1 will be accessed on node \NY.
Running a Pathway/iTS Application
When starting an application using Pathway/iTS (and its parent product, TS/MP) and
GDSX, the GDSX process is started first. For example, the following command may
be issued to run a GDSX object named $GDSX:
> RUN GDSE /NAME $GDSX, NOWAIT/
The configuration either involves a LINE or does not involve a LINE. Suppose that the
application has no LINE. Then, if SUs are to be preconfigured, SCF is used to
configure them before TS/MP (and Pathway/iTS) is started. Otherwise, SCF is simply
started.
If a GDSX application is designed to use SCF to preconfigure SUs T1 and T2 using
devices $T1 and $T2, the following commands could be issued:
-> SCF
-> ADD SU $GDSX.#T1
-> ADD SU $GDSX.#T2
Note how the device names $T1 and $T2 become #T1 and #T2, respectively, when
combined with the GDSX process name in these commands. When GDSX receives
these commands, it derives the proper device names, but does not open the files until
it receives an open message from Pathway/iTS.
In PATHCOM, you configure terminals to be opened through GDSX. If a Pathway/iTS
requester is to communicate through a GDSX process named $GDSX with a device
$T2, the file name $GDSX.#T2 is used in a series of PATHCOM commands like the
following:
=
=
=
=
=
SET
SET
SET
SET
ADD
TERM
TERM
TERM
TERM
TERM
TCP TCP-X
TYPE T16-6530:0
INITIAL LOGON-SCREEN
FILE $GDSX.#T2
TX-2
Term type specifies the type of terminal that the GDSX process is simulating for
Pathway/iTS.
A session or thread is established when you issue the following PATHCOM command:
= START TERM TX-2
Then the TCP opens the file specified in the configuration commands, $GDSX.#T2 in
this example. Within the GDSX process, TSCODE receives the open message,
derives the device name $T2 from the message, and opens the device. A thread is
established from the TCP requester through $GDSX to $T2.
Extended General Device Support (GDSX) Manual—529931-001
3 -9
Running GDSX as a TS/MP Server
Operations and Support
Pathway/iTS Applications With a LINE
Suppose that an application using Pathway/iTS and GDSX has a LINE. When starting
such an application, the GDSX process is run first. For example, the following
command can be issued to run a GDSX object named $GDSX:
> PARAM MAXLINES 1
> RUN GDSE /NAME $GDSX, NOWAIT/
The MAXLINES configuration parameter indicates to GDSX that there is to be a
maximum of one line in the configuration.
Then SCF must be used to configure the LINE and devices under the line, and to
START the LINE. Here is an example of a configuration having one LINE and three
SUs under the LINE:
->
->
->
->
->
->
SCF
ADD LINE $GDSX.#LINE1, ACCESSNAME $IOP1
ADD SU $GDSX.#LINE1.DEV1
ADD SU $GDSX.#LINE1.DEV2
ADD SU $GDSX.#LINE1.DEV3
START LINE $GDSX.#LINE1
When the LINE is started in SCF, GDSX refers to the line’s access name (the file
associated with the LINE object), opens the file ($IOP1 in this case), and creates a
LINE^HANDLER task to manage communication with the devices on the line. All
devices on the LINE are then available for access.
In PATHCOM, you configure SUs that Pathway/iTS is to open through GDSX. For
example, if a Pathway/iTS requester is to communicate through a GDSX process
named $GDSX with a subdevice DEV2 configured under line $LINE1, the file name
$GDSX.#LINE1.DEV2 is used in a series of PATHCOM commands like the following:
=
=
=
=
=
SET
SET
SET
SET
ADD
TERM
TERM
TERM
TERM
TERM
TCP TCP-X
TYPE T16-6530:0
INITIAL LOGON-SCREEN
FILE $GDSX.#LINE1.DEV2
TX-2
A session or thread is established when you issue the following PATHCOM command:
= START TERM TX-2
Then the TCP opens the file specified in the configuration commands,
$GDSX.#LINE1.DEV2 in this example. The GDSX process receives the open
message, derives the name $LINE1.#DEV2 from the message, determines from
configuration information previously entered with SCF that DEV2 is configured under
line $LINE1, and establishes a thread from the TCP requester through $GDSX to the
line $LINE1 and then to device DEV2.
Running GDSX as a TS/MP Server
You can configure a GDSX application to run as if it were a TS/MP server. Running an
application as a server has two benefits:
Extended General Device Support (GDSX) Manual—529931-001
3- 10
Operations and Support
•
•
Running GDSX as a TS/MP Server
If the GDSX server is not running in NonStop mode and it fails, TS/MP
automatically restarts the GDSX server if the server is configured with the TS/MP
AUTORESTART parameter set to a value equal to or greater than 1.
A GDSX server is affected by the PATHCOM commands that deal with servers,
such as THAW and START. (The PATHCOM commands FREEZE or STOP affect
a GDSX server when only Pathway/iTS requesters have opened GDSX. If
processes outside the TS/MP or Pathway/iTS application have also opened a
GDSX server, a FREEZE or STOP command does not affect the GDSX server.)
To have a GDSX object file run as a server process, you must use a PATHCOM SET
SERVER PARAM command to set the GDSX SERVER configuration parameter to 1.
In addition, TSCODE automatically sets the value of the AUTOSTOP configuration
parameter to 1, which means that a GDSX server stops if there are no external
processes opening it.
Note. A GDSX server does not reply with error 70 to a startup message from the PATHMON
process.
A GDSX application configured to run as a server process can also be designed and
coded to run in NonStop mode. For this case, you still set the SERVER configuration
parameter to 1 and specify a primary and backup processor during configuration. In
addition, you must set the NONSTOP configuration parameter to 1 with a SET
SERVER PARAM command.
The following example shows the PATHCOM configuration commands that define a
GDSX object file as a TS/MP server. The GDSX server process also runs in NonStop
mode and uses the TMF pseudo procedures.
Set the TS/MP configuration parameters as follows:
= RESET SERVER
Primary and backup processors
= SET SERVER CPUS (0:1)
= SET SERVER MAXSERVERS 1
Run one GDSX process
= SET SERVER NUMSTATIC 1
GDSX should always be active
= SET SERVER SECURITY “N”
Server class security
= SET SERVER TMF ON
Server handles TMF transactions
= SET SERVER PROGRAM $SKY.LINZ.GDSE GDSX object name
= SET SERVER DEBUG OFF
No debugging mode
= SET SERVER PROCESS $GDSX
GDSX process name
Set the GDSX configuration parameters as follows:
= SET SERVER PARAM MAXLINES 0
Run as a device handler
= SET SERVER PARAM CONTROLFLAGS 8 Run as a converted process
= SET SERVER PARAM MAXBUFPOOL 50000 Reserve some pool space
= SET SERVER PARAM TASKSIZE 2048 Size of data stack
= SET SERVER PARAM DEVICEINFO 1
Allow DEVICEINFO requests
= SET SERVER PARAM TMF 2
Let USCODE start TMF transactions
Extended General Device Support (GDSX) Manual—529931-001
3- 11
Space Usages and Limitations
Operations and Support
= SET SERVER PARAM PROCNOWAIT 1
Run in nowait mode
= SET SERVER PARAM SERVER 1
Run as a server
= SET SERVER PARAM NONSTOP 1
Run in NonStop mode
= ADD SERVER GDSX-SERVER
= START SERVER GDSX-SERVER
Name of server class
Start the GDSX server
Space Usages and Limitations
Because USCODE is bound with TSCODE to become a GDSX runnable unit, there are
limitations in code space and data space in user code. However, because multiple
code spaces are available, code space is not likely to be a problem.
Regarding the data space, GDSX uses a user data segment with a size of 64 pages.
TSCODE uses two extended segments—one for various control and data structures
and one for trace data. The segment allocated by default for the control and data
structures is segment ID 1024. Segment ID 1025 is always allocated for the trace
data. Segment IDs from 1024 up are reserved for TSCODE.
Although it is generally not advisable, USCODE can use its own extended segment
through calls to ALLOCATESEGMENT and USESEGMENT. The segment IDs
available to USCODE range from 0 to 1023.
User Data Segment
The user data segment of the GDSX process is specified at bind time to have a size of
64K words. The size of various areas within the segment is determined by the
configuration parameters. (See GDSX Configuration Parameters on page 2-46 and
3-13.)
Extended Segment
GDSX allocates an extended segment (with default segment ID 1024) and a size
determined by the configuration parameters. If the space is not available, GDSX will
not run, and an internal error message is created—abend error 30.
Extended Segments for Trace Files
When the trace facility is turned on in the primary GDSX process, TSCODE allocates
an extended segment with segment ID 1025, a default size of 64 pages, and the
default file name TRACEP under the default subvolume. The SCF TRACE command
may be used to specify a different file name, and the USER^OPEN^TRACE^FILE
procedure may be used to specify a different file size. (For further information
regarding the trace facility, see Tracing GDSX on page 2-80.)
When the trace facility is turned on in the backup process, TSCODE allocates an
extended segment with segment ID 1025, a default size of 64 pages, and the file name
TRACEB under the default subvolume.
Extended General Device Support (GDSX) Manual—529931-001
3- 12
Operations and Support
GDSX Configuration Parameters
If the specified trace file does not exist, the GDSX process creates and uses the file. If
the default subvolume already has a file with the name specified and the file has not
been opened by another process, the GDSX process opens the file. If the specified
trace file is in use by any other process, the GDSX process will not initiate the trace.
GDSX Configuration Parameters
GDSX uses configuration parameters to control memory allocation and numerous
aspects of the run-time environment. Some configuration parameters are called static,
because once their values are determined at process creation time, they cannot be
changed. The other configuration parameters are called dynamic because their values
can be changed after the process has been initialized.
See GDSX Configuration Parameters on page 2-46 for detailed information about the
static and dynamic configuration parameters for GDSX.
Setting Configuration Parameters
Other than assigning values to configuration parameters within USCODE, there are
three ways to set the configuration parameters. (For information on assigning values
to configuration parameters within USCODE, see GDSX Configuration Parameters on
page 2-46.)
1. Before running GDSX, use TACL PARAM commands to assign values to external
parameter names. This method may be used with static or dynamic parameters.
Use the external parameter names listed in the first column of Tables 2-2 and 2-3.
For example, to specify the restart time delay, enter the following command at a
TACL prompt:
> PARAM RESTARTTIME 10000
Or, to turn on the trace facility (give bit 11 of DEBUGFLAGS a value of 16), enter
the following command at a TACL prompt:
> PARAM DEBUGFLAGS 16
Caution. The PARAM DEBUGFLAGS command also turns off all the other flags in the bitencoded DEBUGFLAGS configuration parameter. See DEBUGFLAGS on page 2-54.
To turn on the trace facility (give bit 11 of DEBUGFLAGS a value of 16) and also
pool checking (give bit 14 of DEBUGFLAGS a value of 2), set DEBUGFLAGS
equal to 18 (16 + 2):
> PARAM DEBUGFLAGS 18
2. Use an SPI management application program to change parameter values. This
method can be used only with dynamic parameters.
3. Use SCF to change parameter values. This method may be used only with
dynamic parameters.
Extended General Device Support (GDSX) Manual—529931-001
3- 13
Management With SCF
Operations and Support
For example, to turn off the trace facility, enter the following SCF command:
-> TRACE PROCESS $GDSX, STOP
Methods 2 and 3 are of equal priority; they both override settings made with method 1.
Management With SCF
There are two management interfaces:
•
•
Interactive, conversational input by means of the Subsystem Control Facility (SCF)
Management programming control by means of a user-written management
application program that uses the Subsystem Programmatic Interface (SPI)
The interactive SCF interface includes commands used to configure and manage SU,
LINE, and GDSX objects; control the tracing facility; and display statistics on object
status and resource allocation. For general information about SCF functions and
command formats, see the Subsystem Control Facility (SCF) Reference Manual. For
detailed information on running SCF specifically to manage GDSX, see the SCF
Reference Manual for GDSX.
Summary information on managing GDSX is presented later in this section. You can
also add your own commands or modify attributes to extend the functions by
customizing the USER^ATTRIBUTES, USER^COMMANDS, and USER^REPLIES
user exits (see Section 9, “User Exit Descriptions,” for more information).
Use of the SPI interface to program customized subsystem management applications
or EMS filters requires some of the GDSX subsystem-specific token definitions and
EMS template definitions from the following files in the installed subvolume:
Description of File Contents
Extended GDSX File Name
EMS template definitions source file
SGDXTMPL
GDSX COBOL85 definitions
ZGDXCOB
GDSX DDL definitions
ZGDXDDL
EMS segment file
ZGDXSEGF
GDSX TACL definitions
ZGDXTACL
GDSX TAL definitions
ZGDXTAL
EMS template definitions object file
ZGDXTMPL
For more information about EMS template files, see the DSM Template Services
Manual.
Command Summary
GDSX supports the SCF commands listed in Table 3-1.
Extended General Device Support (GDSX) Manual—529931-001
3- 14
Command Summary
Operations and Support
The typical command syntax is:
command object-type object-name [ modifier ] , ...
For example:
-> START LINE $XGDS.#LX
Object Type
The object type can be one of the following:
LINE
An object managed by a LINE^HANDLER task and mapped to a
file (often a physical communications line)
PROCESS
A running GDSX process
SU
A logical terminal (subdevice) managed by a
DEVICE^HANDLER task and mapped to a physical terminal or
a process
TASK
A generic object type that refers to either an SU or a LINE within
GDSX. Each SU and LINE is also a TASK.
Object Name
The object name is the name of the specified object type. In general, the PROCESS
name follows the Guardian process-naming convention. For example, $GDSX is the
name of a PROCESS object.
The LINE name follows the Guardian device-naming convention. For example,
$GDSX.#CP6100 can be the name of a LINE object.
The SU name also follows the Guardian device-naming convention. For example,
$GDSX.#TERM1 and $GDSX.#AM3270.TERM2 may be names of SU objects.
Table 3-1. GDSX Subsystem-Specific SCF Commands
Object Type
Command
PROCESS
TASK
LINE
SU
ABORT
X
X
ADD
X
X
ALLOWOPENS
ALTER
X
X
DELETE
INFO
X
X
X
X
X
X
X
X
LISTOPENS
NAMES
X
X
X
Extended General Device Support (GDSX) Manual—529931-001
3- 15
Interpreting Console and EMS Messages
Operations and Support
Table 3-1. GDSX Subsystem-Specific SCF Commands
Object Type
Command
PROCESS
PRIMARY
X
TASK
START
LINE
SU
X
X
STATS
X
X
X
X
STATUS
X
X
X
X
STOP
X
X
X
STOPOPENS
X
TRACE
X
VERSION
X
Interpreting Console and EMS Messages
Messages generated by GDSX can be classified according to severity:
Status messages
Report a state change within a GDSX process. Some examples
of status messages are startup, open, and close messages.
Warning
messages
Report an unexpected state change within a GDSX process.
An example is a message reporting that the backup stopped.
Error messages
Report that an error occurred within a GDSX process. Two
examples of conditions that cause the generation of error
messages are a checkpoint failure and a memory pool error.
Where Messages Are Displayed
GDSX can generate console messages to the home terminal and EMS messages to
an EMS display terminal. These terminals can be configured to be the same device or
different devices.
Home Terminal
At process initialization time, all messages from TSCODE are sent to the home
terminal, because the monitor task, which handles messages sent to EMS, is not yet
active. To ensure that all messages are seen, you can change the home terminal to a
paused terminal. For example, the following RUN command changes the home
terminal to device $TF2.#F22:
> RUN GDSE /NAME $GDSX, NOWAIT, TERM $TF2.#F22/
Make sure you pause such a terminal.
Extended General Device Support (GDSX) Manual—529931-001
3- 16
Operations and Support
Types of Messages Generated
EMS Terminal
GDSX processes send tokenized event messages to the Event Management Service
(EMS) primary collector ($0) process. The collector stores these messages in the
current EMS log file. EMS distributor processes select messages from the log file and
deliver them to consumers.
A distributor process can use a filter to limit the types of events passed to a consumer.
(For instructions on how to program and run a filter with GDSX, see EMS Filters and
GDSX on page 2-79.) The distributor process will direct output to a designated
terminal, called the EMS terminal.
Types of Messages Generated
GDSX generates the following types of messages. For listings of the messages in
each type see the following headings.
•
•
Console messages (at home terminal)
°
°
°
Startup configuration error messages
Abend messages
Trap messages
EMS messages (at EMS terminal)
°
°
EMS event messages
Fault messages
An abnormal condition within GDSX can generate a number of different messages.
For example, a trap can generate a fault message at the EMS terminal, and a trap
message and an abend message at the home terminal.
EMS messages generated by converted GDSX processes always show the PIN with a
value of 255.
Startup Configuration Error Messages
These messages may be generated by GDSX during data space initialization. At
GDSX process startup, TSCODE calculates the space required in extended memory
for each type of control block. Only after all calculations have been completed are
allocations done for the control block pools. Equations for these calculations are given
in Figure 2-2 on page 2-22. Calculations are made in the following order:
TCB
Task control block
IOCB
I/O control block
RCV
Receive control block
RCB
Requester control block
Extended General Device Support (GDSX) Manual—529931-001
3- 17
Operations and Support
FCB
File control block
DCB
Device control block
LDCB
Logical device control block
LCB
LINE control block
PCB
Process control block
Startup Configuration Error Messages
Generally, it is not necessary to override the size that TSCODE calculates for a pool,
but it can be overridden either by using a TACL PARAM command to assign a value to
the configuration parameter’s external name, or by assigning a value to a configuration
parameter’s internal name in the USER^INIT^CONFIG^PARAMS user exit. The
external names are:
MAXTCBPOOL
MAXIOCBPOOL
MAXRCVPOOL
MAXRCBPOOL
MAXFCBPOOL
MAXDCBPOOL
MAXLDCBPOOL
MAXLINEPOOL
MAXPCBPOOL
(For more information on these parameters see GDSX Configuration Parameters on
page 2-46.) TSCODE uses the user-specified setting unless it is determined that the
pool size would be insufficient, in which case TSCODE uses the value that it
calculated.
If the pool size specified by such a configuration parameter is too large (more than
7.5 megabytes), or if the size causes the running total calculated for control block
pools, the extended buffer pool, and the extended message pool to exceed 16,777,216
bytes, an error message is sent to the home terminal, and the GDSX process abends
with abend error 20. (The message is sent to the home terminal, because at
configuration time the monitor task, which normally handles EMS messages, is not yet
active.)
Configuration Error Messages
Possible configuration error messages are:
10001
10002
10003
10004
10005
10006
10007
10008
10009
CONFIGURATION PARAM > THAN ALLOWED LIMIT
maxTCBpool or Buffer/Msg pool too large
maxIOCBpool or previous pools too large
maxRCVpool or previous pools too large
maxRCBpool or previous pools too large
maxFCBpool or previous pools too large
maxDCBpool or previous pools too large
maxLDCBpool or previous pools too large
maxLINEpool or previous pools too large
Extended General Device Support (GDSX) Manual—529931-001
3- 18
Operations and Support
10010
10011
10012
10013
10014
10015
10016
10017
Abend Messages
maxPCBpool or previous pools too large
Sum of all max***pools are > 16777216d
Sum of final EXT. MEM size > 16777216d
GDSX process to run converted at high PIN - continuing
GDSX process running high PIN not enabled - terminating
Nonnumeric char in configuration param
Number of tasks exceed limit with TMF
Task size is too small (Param TASKSIZE)
For example, if the TCB and IOCB pool sizes have been calculated, and the total
requirement for the TCB and IOCB pools, the extended buffer pool, and the extended
message pool exceeds 16,777,216 bytes, the following error message is sent to the
home terminal:
10003 maxIOCBpool or previous pools too large
If the total calculated for all the control block pools, the extended buffer pool, the
extended message pool, and the checkpoint buffer exceeds 16,777,216 bytes, error
message 10011 is sent to the home terminal. If the total calculated for all the areas to
be allocated in the extended segment exceeds 16,777,216 bytes, error message
10012 is sent to the home terminal.
Error message 10001 is sent to the home terminal if a configuration parameter other
than a control block pool size configuration parameter (see the above external
parameter names) is assigned a value greater than 65,532.
The configured control block pool sizes may be displayed by issuing the following SCF
command:
-> INFO PROCESS $GDSX-process-name, DETAIL
Error message 10013 is sent to the home terminal when TSCODE determines that the
GDSX process is running at a high PIN. At this point TSCODE has not checked the
setting of d^plus^enabled of the CONTROLFLAGS configuration parameter. If this
parameter is set to 0, error message 10014 is sent to the home terminal, and the
process abends; if the parameter is set to 1, processing continues with no message to
the home terminal.
Error message 10015 is sent to the home terminal if from outside SCF a configuration
parameter is assigned a value containing a nonnumeric character.
Abend Messages
If the GDSX process ceases to function, it attempts to send an abend error message to
the home terminal where the process was created.
When TSCODE detects an internal inconsistency, the GDSX trap handler is called.
The trap handler in turn calls the procedure DIE. If debug^fatal^flag of the
DEBUGFLAGS configuration parameter is set, DIE calls DEBUG. Regardless of the
value of DEBUGFLAGS, the process calls ABEND, so that if SAVEABEND is set for
the process (at bind time), a memory image file is created for later investigation using
INSPECT. Should GDSX enter DIE, an abend error message is produced indicating
the internal error number, the code space ID, and the value of the P register.
Extended General Device Support (GDSX) Manual—529931-001
3- 19
Abend Messages
Operations and Support
GDSX problem reports should be accompanied by a SAVEABEND dump (if a dump
was generated) and the object code file (with SYMBOLS) running at the time of the
failure.
Following is the format of an abend error message:
process-name: INTERNAL ERROR #number AT %ee.address
Save file created: vol.subvol.filename
ABENDED: process-name
number
is the abend error number
ee
is the code space ID
address
is the value of the P register
For example:
$GDSX: INTERNAL ERROR #020 AT %00.053252
Save file created: $DATA1.T9170B35.ZZSA0356
ABENDED: $GDSX
The abend errors are described in Table 3-2. Items marked with an asterisk are
described under the headings following the table.
Table 3-2. Abend Error Messages
Abend
Number
Literal for Error Number
Description of Event Causing Abend
10
error^startup^msg
Wrong startup message
20
error^pool^space
Error in allocating pool space
30
error^ext^seg
Error in allocating extended segment
31
error^ext^pool^space
Error in allocating ext^pool
100
error^soft^license
No software license
110
error^processor^type
Not the right processor type
120
error^file^system
File-system-related problems
200
error^internal^resource
Internal problems
210
error^looping
Looping error
220
error^flag^or^state
*
230
error^inval^buf^pool
*
231
error^inval^msg^pool
*
300
error^unexpected^io
I/O message cannot be handled by GDSX
Extended General Device Support (GDSX) Manual—529931-001
3- 20
Abend Messages
Operations and Support
Table 3-2. Abend Error Messages
Abend
Number
Literal for Error Number
Description of Event Causing Abend
310
error^unexpected^case
Case statement error
320
error^wrong^case
Case statement error
500
error^q^cp
Fault-tolerance processing problems
Errors Less Than 100
An abend error number less than 100 usually indicates that the system does not have
enough space to run a GDSX process. To recover, use a disk that has more free
space. If you determine there is no problem with disk space, check the configuration
parameter values.
Error 220
Internal control flags or states are not synchronized. GDSX abends at the location
where the problem is detected, although the problem may have happened long before
it was detected. Check the places where the flags were most recently updated and
check that all I/O buffers are in extended memory.
This error can occur at the beginning of the kernel’s dispatcher routine if location zero
in the GDSX process data stack is altered. To see whether this is the case, check the
value of data stack location zero (location G0 may be referenced by a variable name).
The value should be %52525. If it is not, check USCODE for uninitialized pointers.
A breakdown of error 220 messages is given in Table 3-3. Regardless of the reason
for getting this abend error, it is always a good idea to check that all I/O buffers are in
extended memory.
Error 230
The buffer pool has been corrupted. Check to see how previously allocated buffer
space has been used. The problem often occurs when data moved into a buffer
overflows the allocated area.
Error 231
The message pool has been corrupted. Check to see how previously allocated buffer
space has been used. The problem often occurs when data moved into a buffer
overflows the allocated area.
Extended General Device Support (GDSX) Manual—529931-001
3- 21
Abend Messages
Operations and Support
Table 3-3. Error 220 Message Breakdown (page 1 of 2)
TSCODE Procedure/
Subprocedure Executing
Description of Event Causing Error 220
ALLOCATETCBX
A task is being created, and the state of the allocated
TCB is not 0.
^AWAITIOX
No event is found for waking up a task, or no valid
buffer address was returned from procedure ^LISTEN.
BACKUP^LISTENERX (MAIN)
The backup process receives a file error that is not a
system message (6).
BACKUP^LISTENERX/
CHECK^ON^BROTHER
A sanity check failed within the backup process.
BACKUP^LISTENERX/
RECEIVE^FCB^CHECKPOINT
The backup process opened a file and the file number
returned was not the same as that returned for the
primary process.
BAD^GOTO
The task stack is corrupted.
CHECK^CP^SPACEL
The current TCB is not the owner of the checkpoint
semaphore.
CHECK^CP^SPACEX
The current TCB is not the owner of the checkpoint
semaphore.
CREATE^BACKUPX/
CREATEBACKUP
The nonstop^flag is not set.
DEALLOCATEIOCB
IOCB passed to this procedure is still linked to an
FCB, or address of IOCB passed to this procedure is
out of bounds.
DECREMENT^STOPMODE
The procedure was called to decrement stop^mode,
but stop^mode is 0.
DELETE^ITEM
The linked list is corrupted.
DELETE^XITEM
The linked list is corrupted.
DISPATCHX (MAIN)
The procedure was called from the backup process,
or global memory was destroyed, or DISPATCHX was
not exited correctly last time (this prevents recursive
calls of DISPATCHX).
DISPATCHX/
CHECK^POINT
The primary checkpoints and the address of the
current task is not equal to the address of the mapped
task.
DISPATCHX/
CHECK^WAIT^LIST
A file error occurred on the call to AWAITIO, and the
error is not 40 (timeout) or 26 (no outstanding I/O).
DISPATCHX/
HANDLE^RECEIVE
A break message was received, but the break tag of
the message does not match the break tag of the TCB
table.
DISPATCHX/
HANDLE^SIGNAL^TIMEOUT
No SIGNALTIMEOUT is outstanding for this file, or the
state of the TCB is STOPPED.
Extended General Device Support (GDSX) Manual—529931-001
3- 22
Trap Messages
Operations and Support
Table 3-3. Error 220 Message Breakdown (page 2 of 2)
TSCODE Procedure/
Subprocedure Executing
Description of Event Causing Error 220
DISPATCHX/
IO^COMPLETION
An I/O completed on some file other than $RECEIVE
but the file did not have an outstanding I/O.
FAULT
The procedure was called for a system task.
GETEXTPOOL
A user task tried to get space from the system pool,
which is reserved for TSCODE.
INSERT^ITEM
The linked list is corrupted.
INSERT^XITEM
The linked list is corrupted.
LISTENER^TASKX/
HANDLE^RECEIVE
A message is picked up from $RECEIVE, the address
of the received buffer is 0, and the state of the IOCB
is not QUEUED.
MONITORX/
LOG^WRITE
Length of message to be written is equal to 0.
MONITORX/
NEXTREQUEST
An I/O on the log file completed, but the IOCB
returned is not from the log file.
NOTIFY^IO^COMPLETIONX
Procedure was called without first parameter (IOCB),
or address of IOCB is 0, or file number in IOCB is 0.
POSTRCV
There is still a read outstanding on $RECEIVE (this
procedure reads $RECEIVE), or this procedure was
called by the backup process.
Q^CP/
PUSH^CP
The number of bytes passed would go beyond the
bounds of the local buffer pool.
Q^CPX/
PUSH^CP
The address passed is not in extended memory.
STOP^TASK^AND^CLEANUPX
(MAIN)
Stopped^bit is not set or stop^mode is set.
STOP^TASK^AND^CLEANUPX/
FREE^DCB
The address of the DCB that is to be freed is not in
the DCB table.
STOP^TASK^AND^CLEANUPX/
STOP^ACTIVE^IO
The active I/O on $RECEIVE is being canceled, but
the I/O is not a SIGNALTIMEOUT.
TAKEBREAK
GDSX tries to take break ownership, but there is no
free entry in the LDCB bitmap.
WAKE^TASK
The state of the current TCB is not 0, or event is
greater than or equal to 15.
Trap Messages
A trap can cause GDSX to generate a trap message and an abend message at the
home terminal, and a fault message at the EMS terminal.
Extended General Device Support (GDSX) Manual—529931-001
3- 23
EMS Event Messages
Operations and Support
When the operating system encounters a trap, the GDSX trap handler is called. The
trap handler in turn calls the procedure DIE. If debug^fatal^flag of the DEBUGFLAGS
configuration parameter is set, DIE calls DEBUG. Regardless of the value of
DEBUGFLAGS, the process will calls ABEND, so that if SAVEABEND is set for the
process (at bind time), a memory image file will be created for later investigation using
INSPECT. Should GDSX enter DIE, an abend error message is produced indicating
the internal error number, the code space ID, and the value of the P register.
Following is the format of a trap message:
process-name: TRAP number %ee.address
Save file created: vol.subvol.filename
ABENDED: process-name
number
is the trap number
ee
is the code space ID
address
is the value of the P register
Table 3-4 contains a summary of the trap messages issued by TSCODE.
Table 3-4. TSCODE Trap Messages
Fault Number
Description of Cause
0
Illegal address trap
1
Instruction failure trap
2
Arithmetic overflow trap
3
Stack overflow trap
4
Looptimer trap
11
No memory (Guardian) trap
12
Uncorrectable memory error trap
13
Map parity error trap
EMS Event Messages
These status, warning, and error messages are always directed to the $0 collector. All
EMS event messages have the following format:
hh:mi:ss: mm/dd/yy name (cpu,pin) message-type - text
Extended General Device Support (GDSX) Manual—529931-001
3- 24
EMS Event Messages
Operations and Support
hh is hour
mi is minute
ss is second
mm is month
dd is day
yy is year
name is process name
EMS event messages generated by converted GDSX processes always show the PIN
with a value of 255.
Here are some examples:
09:20:30 04/10/91 $GDSX (06,37) status - Startup (Version
04/01/91)
09:20:30 04/10/91 $GDSX (06,37) status - Backup created in
CPU 0007
09:21:30 04/10/91 $GDSX (06,37) warning- Backup stopped
09:22:00 04/10/91 $GDSX (06,37) status - Backup created in
CPU 0007
09:23:00 04/10/91 $GDSX (06,37) status - TERM 01
($GDSX.#T27B)
started
09:23:00 04/10/91 $GDSX (06,37) status - TERM 01
($GDSX.#T27B)
opened by
\ABC 01,042
Table 3-5 summarizes the EMS event messages that can be sent to an EMS terminal
by a GDSX process.
Table 3-5. GDSX EMS Event Message Summary (page 1 of 2)
EMS Message Number
Description of the Event Reported
1001
GDSX startup
1002
GDSX normal shutdown
1003
DEVICE^HANDLER error
1004
LINE^HANDLER error
1005
GDSX user-terminated
1006
GDSX shutdown pending
1021
Task fault
1022
Task started
1023
Task stopped
1024
Task opened
1025
Task aborted
1026
Task closed
1027
Task restarted
Extended General Device Support (GDSX) Manual—529931-001
3- 25
Fault Messages
Operations and Support
Table 3-5. GDSX EMS Event Message Summary (page 2 of 2)
EMS Message Number
Description of the Event Reported
1041
Checkpoint failure
1042
Checkpoint open failure
1043
Create Backup failure
1044
Open Backup failure
1045
Write to Backup failure
1046
Backup deleted
1047
Backup abended
1048
Backup stopped
1049
Backup takeover
1050
Backup created
1051
Checkpoint exceeded
1052
Checkpoint overflow
1053
Internal error
1054
Disallowed for converted process
1055
Disallowed for unconverted process
Fault Messages
These warning and error messages are handled by EMS. They appear at the EMS
terminal along with the EMS event messages.
A fault message may be generated by TSCODE or by a USCODE call to the FAULT
procedure. (See the procedure description in Section 8, Service Routines.) Table lists
the number ranges for fault messages.
Table 3-6. Number Ranges for Fault Messagesw
Number
Range
Type of Messages
0-100
Reserved for faults detected by TSCODE
101-200
Warning type of faults detected by a DEVICE^HANDLER task
201-300
Error type of faults detected by a DEVICE^HANDLER task
301-400
Warning type of faults detected by a LINE^HANDLER task
401-500
Error type of faults detected by a LINE^HANDLER task
All fault messages have the following format:
hh:mi:ss: mm/dd/yy name (cpu,pin) message-type - text
Extended General Device Support (GDSX) Manual—529931-001
3- 26
Fault Messages
Operations and Support
hh is hour
mi is minute
ss is second
mm is month
dd is day
yy is year
name is process name
Fault messages generated by converted GDSX processes always show the PIN with a
value of 255.
Here is an example of a fault message:
09:23:00 04/10/91 $GDSX (06,37) error
- TERM 01
($GDSX.#T27B)
Fault # 104 P =
%00.047502
Table 3-7 contains a summary of the fault messages issued by TSCODE. Fault
numbers 0-4 and 10-13 are usually generated by the GDSX trap handler.
Table 3-7. TSCODE Fault Messages
Fault Number
Description
0
Illegal address trap.
1
Instruction failure trap.
2
Arithmetic overflow trap.
3
Stack overflow trap.
4
Looptimer trap.
5
Message fault. GDSX was unable to obtain word-addressable memory
to queue a message for the task.
6
Reply fault. Task made an incorrect call to ^REPLY. Reply error was
either 60, or more than 200 and less than or equal to 254.
7
Sendmsg fault. Error occurred when issuing a message.
8
Context fault. Task gave up control when the size of its working stack
exceeded the size specified by TASKSIZE.
9
Incorrect parameter used to allocate or deallocate pool space.
10
Memory manager (Guardian) trap.
11
No memory (Guardian) trap.
12
Uncorrectable memory error trap.
13
Map parity error trap.
14
IOCB fault. GDSX was unable to allocate an IOCB to handle an I/O
request.
15
Checkpoint fault. Incorrect parameter to call CHECKPOINT routines, or
task has too much buffer space to checkpoint.
Extended General Device Support (GDSX) Manual—529931-001
3- 27
If GDSX Abends
Operations and Support
Table 3-7. TSCODE Fault Messages
Fault Number
Description
16
Task tried to close $RECEIVE.
17
Task called INIT^SEM passing a nonzero semaphore.
18
Task attempted to obtain an uninitialized semaphore.
19
Task attempted to release a semaphore it did not own.
20
Task passed an invalid task number to get a TCB address.
21
Timeout waiting for buffer
22
Bad putbuff address
23
Log buffer overrun
24
Parameter to rcbaddrX out of bounds
25
Task attempted illegal C-series call
26
Task attempted illegal D-series call
If GDSX Abends
If your GDSX application abends, perform the following before consulting an HP
support representative:
•
Record the full version procedure from the GDSX object file. You can determine
this by using either the VPROC utility or BIND. For example, using VPROC:
> VPROC
Enter filename:
> OGDS
Here is an example command using BIND:
> BIND LIST CODE(T6580) FROM $SYSTEM.Y6580D44.OGDS
•
Save the abend file for analysis. If the GDSX process ceases to function, it
attempts to send an abend message to the home terminal where the process was
created. An internal error number is displayed and the abend file is saved. For
information on what to do for various error numbers, see Abend Messages on
page 3-19.
To determine the sequence of events prior to the abend, you can issue the
commands shown in the following example. Note that the sequence of procedure
names (preceded by # signs) is only an example.
> INSPECT ADD PROGRAM $VOL.SUBVOL.ZZSAnnnn
--TRACE 1 ARG
ABEND
#DIE
#KERNELERROR
#DELETE^XITEM
--EXIT
Extended General Device Support (GDSX) Manual—529931-001
3- 28
Operations and Support
•
•
•
•
•
•
If GDSX Abends
If a problem occurs with a GDSX process that was running a trace, save the trace
file because subsequent GDSX runs might write over data in the file. The default
name for the primary process trace file is TRACEP; the default name for the
backup process trace file is TRACEB. For more information on the trace facility,
see Tracing GDSX on page 2-80.
If the problem involves SCF or SPI, record the version procedures for SCF and
SCP. Within SCF, use the LOG command to capture appropriate information
provided by commands such as INFO PROCESS, INFO LINE, INFO SU, and
STATUS PROCESS, DETAIL.
Gather any messages obtained by means of a filter. See EMS Filters and GDSX
on page 2-79 for detailed information.
Record the name of the I/O processes GDSX is using (such as CP6100) as well as
the version procedure of such I/O processes.
Record information on configuration settings for the I/O processes and
configuration parameter settings for GDSX.
If the problem involves Pathway/iTS, record the version of the TCP.
Extended General Device Support (GDSX) Manual—529931-001
3- 29
Operations and Support
Extended General Device Support (GDSX) Manual—529931-001
3- 30
If GDSX Abends
4
DEVICE^HANDLER Example,
Running and Managing
The typical purpose of a DEVICE^HANDLER is to modify the communication of each
thread between a requester and another file. The GDSX program demonstrated in this
section, called the DEVICE^HANDLER example, includes a DEVICE^HANDLER
procedure that modifies communication between multiple requesters and the terminals
to which they are mapped. Figure 4-1 shows an overview of the processing done in
this unconverted example program. $A1 and $A2 are requester processes, each of
which communicates with a terminal by way of $GDS; the DEVICE^HANDLER in
$GDS does datastream conversion on messages sent from requester to terminal.
Figure 4-1. Overview of DEVICE^HANDLER Example
$GDS
D^H Task
$A1
Datastream
Conversion
Passthrough
$TC1
D^H Task
Datastream
Conversion
$A1
Passthrough
$TC2
VST012.vsd
This section of the tutorial requires three terminals, designated the TACL terminal, the
first application terminal, and the second application terminal. (If a second application
terminal is not available, you can still do most of this section’s tutorial.) It is assumed
that the terminals are accessed by means of the TERMPROCESS IOP.
Extended General Device Support (GDSX) Manual—529931-001
4 -1
DEVICE^HANDLER Example, Running and
Managing
Running an Application Process
Running an Application Process
In the tutorials on both the DEVICE^HANDLER example and the LINE^HANDLER
example in Section 4, DEVICE^HANDLER Example, Running and Managing through
Section 7, LINE^HANDLER Example, Design, a simple unconverted TAL application is
used to send requests to the GDSX process. (FUP may also be used as a requester.)
The following exercise familiarizes you with this application so the requester’s
functioning may later be clearly distinguished from the functioning of the GDSX
process.
Compiling the Requester
The application source file, APPLS, is included in the GDSX installed subvolume. The
terminal to be used for compilation is called the TACL terminal. At the TACL terminal,
log on and, if necessary, use the VOLUME command to change the default subvolume
to the subvolume where you wish to work.
Then compile the application program APPLS, assigning an object file name of APPL:
> TAL /IN $vol.subvol.APPLS, OUT $S.#APPLS/ APPL
When compiling APPLS, you do not set the HIGHPIN object-file attribute on, because
this requester is unconverted and cannot run at a high PIN. A listing of the source file
is included in Appendix A.
Running the Application
The first application terminal is used for input to and output from the requester
application. At this terminal, log on and enter a WHO command to identify the
terminal’s device name. Suppose for this example that it is $TC1. Pause the TACL
process with the PAUSE command. Pausing the TACL process allows the application
process to control the terminal.
At the TACL terminal, start an application process, named $A1 in this example:
> RUN APPL /NAME $A1, OUT $TC1, NOWAIT/
$A1 is designed to open the specified OUT file and send a WRITEREAD to the file.
The application terminal should now show a prompt sent by the application. The
prompt contains the CPU number and PIN of the process. Verify this by entering the
following at the TACL terminal:
> STATUS *, TERM
At the application terminal, type a short text string followed by a carriage return. The
string of characters returned should be exactly those entered, displayed in reverse
order. Enter another text string.
After reading the startup message and opening the OUT file, this simple application
performs the following instructions in a loop:
1. Issue a waited WRITEREAD “CPU, PIN” prompt to the file.
Extended General Device Support (GDSX) Manual—529931-001
4 -2
DEVICE^HANDLER Example, Running and
Managing
Running Two Requesters
2. Reverse the text string that was input at the prompt.
3. Issue a waited WRITE of the reversed string to the file and delay two seconds.
Later in this section the APPLS application is used similarly to communicate with a
terminal, but with an intermediate GDSX process doing datastream conversion,
changing all lowercase text sent to the terminal to uppercase text. Although this
conversion is trivial, it serves to demonstrate how GDSX can be used to do datastream
conversion.
At the application terminal, press CTRL/Y. On the screen you see the following:
EOF!
APPLICATION STOPPING
If you press CTRL/Y at the prompt, file-system error 1 returns from the WRITEREAD,
the above message is written to the terminal, and the requester closes the file and
stops itself. The cursor moves to the far left-hand side of the application terminal’s
screen. Then press the Break key at the application terminal to get a TACL prompt.
To verify that the requester process is gone, enter the following at the TACL terminal
enter:
> STATUS *, TERM
Running Two Requesters
Make sure that the TACL process is paused at the application terminal.
At the TACL terminal, start a requester process named $A1:
> RUN APPL /NAME $A1, OUT $TC1, NOWAIT/
Then run another process named $A2, directed to the same OUT file:
> RUN APPL /NAME $A2, OUT $TC1, NOWAIT/
Enter text strings as before, and watch how the two threads interfere with each other.
(After you enter the first string, you probably see no output, just another prompt; simply
enter another string.) The LINE^HANDLER procedure discussed in Section 6,
LINE^HANDLER Example, Running and Managing and Section 7, LINE^HANDLER
Example, Design) makes it possible to communicate with a shared file without having
the threads interfere with each other.
Stop both requester processes by pressing CTRL/Y at both prompts.
In the next part of this tutorial you will generate the GDSX process used for both the
DEVICE^HANDLER and LINE^HANDLER examples.
Generating the Example GDSX Process
When generating the GDSX process used for both the DEVICE^HANDLER example
(Section 4, DEVICE^HANDLER Example, Running and Managing and Section 5,
DEVICE^HANDLER Example, Design) and the LINE^HANDLER example (Section 6,
Extended General Device Support (GDSX) Manual—529931-001
4 -3
DEVICE^HANDLER Example, Running and
Managing
Compiling
LINE^HANDLER Example, Running and Managing and Section 7, LINE^HANDLER
Example, Design), use the following files from a GDSX installed subvolume:
File
Description
DCCBDECS
Source file containing global variables and other common
declarations
Source file containing declarations specific to the example
program
Another source file containing external declarations for
procedures within TSCODE
U ser source code file containing all the user exits (procedures)
called by TSCODE. USKELEX—the name is derived from
“USKEL Example for GDSX”—was prepared from USKEL, the
user code skeleton file supplied in the GDSX installed
subvolume, by replacing the three procedure stubs for
DEVICE^HANDLER, USER^STOP, and LINE^HANDLER with
user-customized procedures.
Command (OBEY) file used to compile the example program.
When you use an edited version of UBUILD to compile
USKELEX, the ULHDECSE and PEXTGDS files and sections
of the DCCBDECS file are sourced in, and the resulting object
code is named USCODEE.
Object code supplied by HP; you cannot modify this file
ULHDECSE
PEXTGDS
USKELEX
UBUILD
TSCODE
UBINDE
BINDER IN file used to bind TSCODE with USCODE,
producing a runnable GDSX object file named GDSE.
Compiling
To facilitate the compiling and binding procedures, you use UBUILD and UBINDE files.
At the TACL terminal, while in the subvolume where you wish to work, copy the
UBUILD and UBINDE files from the installed subvolume. Edit UBUILD to assign SSV1
to the installed subvolume, assign SSV2 to $SYSTEM.SYSTEM, and assign SSV3 to
the SPI subvolume. The IN file for the TAL compiler is USKELEX, and the object file is
named USCODEE. You might want to use an OUT file to capture the compile listing.
Extended General Device Support (GDSX) Manual—529931-001
4 -4
DEVICE^HANDLER Example, Running and
Managing
Compiling
Figure 4-2. Example Generation Process
Installed Subvolume
DCCBDECS
?SOURCE
?SOURCE
(Optional)
ULHDECS
TSCODE
PEXTGDS
?SOURCE
USKELEX
Source File
TAL
USCODEE
UBINDE
IN File
BIND
Runnable
GDSX
Object
VST013.vsd
Here is an example of the resulting UBUILD file:
COMMENT
UBUILD Build example of USCODE from USKELEX
CLEAR ALL
COMMENT
Assign SSV1 to GDSX volume and subvolume
COMMENT
for ULHDECS, DCCBDECS, ZGDXTAL, PEXTGDS,
COMMENT
and USAMPLE
ASSIGN SSV1, $STAR.T6580D44
COMMENT
Assign SSV2 to EXTDECS0 location
ASSIGN SSV2, $SYSTEM.SYSTEM
COMMENT
Assign SSV3 to SPI subvolume for ZCOMTAL and
Extended General Device Support (GDSX) Manual—529931-001
4 -5
DEVICE^HANDLER Example, Running and
Managing
Binding
COMMENT
ZSPITAL location
ASSIGN SSV3, $SYSTEM.ZSPI
TAL /IN USKELEX, MEM 64, OUT $S.#USKELEX/ USCODEE; &
SYMBOLS, INSPECT, NOCODE, NOICODE, NOMAP
CLEAR ALL
EXIT
After creating UBUILD, issue the command OBEY UBUILD to compile the source code
file and produce the object file USCODEE.
The HIGHPIN object-file attribute is not set on, because this example is an
unconverted application that cannot run at a high PIN. If you compile the converted
USKELEXC example program shown in Appendix B, you may set the attribute as
follows:
> TAL /IN USKELEXC, MEM 64, OUT $S.#USKELEC/ USCODEC; HIGHPIN
Appendix B has listings of USKELEX and USKELEXC.
Binding
Now use the UBINDE file to bind TSCODE and USCODE. UBINDE contains the
following commands:
add * from tscode
add * from USCODEE, delete
set data 64 pages
set inspect on
set saveabend on
set subtype 30
build GDSE !
The GDSX object file must be named GDSE in this example. TSCODE must be added
before USCODE so that TSCODE is loaded into the first code segment. The SET
SUBTYPE 30 command makes it possible for the GDSX process to receive and
respond to device type requests from other processes. For more information about the
BIND program, see the Binder Manual.
Before using the UBINDE file, depending on the location of the TSCODE file, you may
need to qualify the file name in the first command. To produce the runnable object file,
issue the command:
> BIND /IN UBINDE/
Running the DEVICE^HANDLER Example
At the TACL terminal, use CLEAR ALL if necessary to clear any previously set
parameter values, and then assign 1 to the configuration parameter EXTSUSIZE:
> PARAM EXTSUSIZE 1
Extended General Device Support (GDSX) Manual—529931-001
4 -6
DEVICE^HANDLER Example, Running and
Managing
Using SCF
This is necessary because of example-specific changes made to the device control
block declaration. (For more information, see the description for EXTSUSIZE on
page 2-59.)
Then run your new GDSX process:
> RUN GDSE /NAME $GDS, NOWAIT/
This GDSX process includes a DEVICE^HANDLER that does datastream conversion
on messages passed from multiple requesters to different asynchronous terminals.
You can enter:
> STATUS *, TERM
to see whether the GDSX process has been started.
Using SCF
The operator interface to running GDSX processes is the Subsystem Control Facility
(SCF). SCF provides a set of commands used to manage GDSX processes and the
devices (SUs) and lines (LINEs) used by the GDSX processes. For general
information about SCF functions and command formats, see the Subsystem Control
Facility (SCF) Reference Manual. For information on running SCF specifically to
manage GDSX, see the SCF Reference Manual for GDSX.
TSCODE supports the SCF commands listed in Table 3-1, “GDSX Subsystem-Specific
SCF Commands,” on page 3-15.
At the TACL terminal, start SCF by entering:
> SCF
If SCF does not reside in $SYSTEM.SYSTEM.*, you must enter:
> RUN SCF
Then enter a SETPROMPT command to cause SCF to display, as part of the prompt,
any object type and name currently being assumed:
-> SETPROMPT OBJECT
Now enter an ASSUME command to define the object type and name:
-> ASSUME PROCESS $GDS
After the ASSUME command executes, the SCF prompt includes the process name.
Now enter a STATUS command:
PROCESS $GDS # -> STATUS
The STATUS command tells you there are two TSCODE system tasks running, and no
USCODE user tasks running.
Enter:
PROCESS $GDS # -> VERSION, DETAIL
Extended General Device Support (GDSX) Manual—529931-001
4 -7
DEVICE^HANDLER Example, Running and
Managing
Running an Application Process
The VERSION command displays the version level and date for the GDSX process.
Enter:
PROCESS $GDS # -> INFO
The INFO command gives you current attribute and configuration parameter values for
the GDSX process.
Enter:
PROCESS $GDS # -> INFO, DETAIL
The INFO, DETAIL command gives the same data as INFO, plus additional attribute
values.
Running an Application Process
The application terminals will be used for I/O with the example application. At the first
application terminal, log on and enter a WHO command to identify the terminal device
name. Suppose for this example that it is $TC1. Pause the TACL process with the
PAUSE command. Pausing the TACL process allows the application process to
control the terminal.
Note. If you do not pause the TACL process, the application process will go into INSPECT.
At the TACL terminal, use the Break key to interrupt the SCF process and return to the
TACL prompt. Start an application process, named $A1 in this example:
> RUN APPL /NAME $A1, OUT $GDS.#TC1, NOWAIT/
This process must be run after the GDSX process has been started, so that I/O from
this process can pass through GDSX. APPLS is designed so that it opens the
specified OUT file, sending a message to GDSE to open the application terminal $TC1.
(A listing of APPLS is in Appendix A.)
The application terminal should now show a prompt sent by the application process
through the GDSE process. The prompt contains the CPU number and PIN of the
application program. At the TACL terminal, from the TACL prompt (you may need to
press the Break key to interrupt SCF) enter:
> STATUS *, TERM
to verify this. Then pause the TACL process to allow SCF to regain control of the
TACL terminal. When you see the SCF prompt, enter:
-> STATUS
The command tells you that now there are two TSCODE (system) tasks, and one
USCODE (user) task, which is a DEVICE^HANDLER task. (Even though GDSE
contains a LINE^HANDLER procedure, in this DEVICE^HANDLER example the
LINE^HANDLER is never called by TSCODE. In Section 6, LINE^HANDLER Example,
Running and Managing and Section 7, LINE^HANDLER Example, Design, the
LINE^HANDLER is demonstrated.)
Extended General Device Support (GDSX) Manual—529931-001
4 -8
DEVICE^HANDLER Example, Running and
Managing
Running an Application Process
Figure 4-3 illustrates the processing that occurred up to this point. The GDSX process,
named $GDS, performed its initialization processing and issued a READUPDATE on
$RECEIVE. Then the application program, named $A1, performed its initialization
processing and issued a call to OPEN $GDS.#TC1. $GDS received the open
message and in turn issued an OPEN $TC1, which was processed by the IOP.
Figure 4-3. Initial Message Flow
$GDS
$A1
IOP/Terminal
Initialization:
READUPDATE
$RECEIVE
Initialization:
OPEN $GDX.#TCI
OPEN $TCI
IOP opens device
Process OPEN
completion; reply
with completion code
WRITEREAD
prompt, "CPU, PIN-"
READUPDATE
Do datastream
conversion;
WRITEREAD prompt
WRITE "CPU, PIN-"
and read input text
VST014.vsd
$GDS then processed the OPEN completion and called REPLY with a completion
code, indicating whether the application’s OPEN for $GDS.#TC1 was successful. After
checking the condition code, the application program issued a WRITEREAD to
$GDS.#TC1, writing the prompt containing its own CPU number and PIN. $GDS
scanned the prompt text for lowercase alphabetic characters (and in this case found
none) to be converted to uppercase before issuing a WRITEREAD of the converted
text to $TC1. Finally, the IOP wrote the prompt to the screen and waited for input.
Extended General Device Support (GDSX) Manual—529931-001
4 -9
DEVICE^HANDLER Example, Running and
Managing
Running an Application Process
At the first application terminal, enter a short text string followed by a carriage return.
The string of characters should then be displayed in reverse order. In addition,
lowercase alphabetic characters should now appear as uppercase, indicating that the
intermediate GDSX process has done its datastream conversion. Figure 4-4 illustrates
the message flow for this transaction.
Figure 4-4. Processing an Input String
$GDS
$A1
IOP/Terminal
REPLY with
text input
REPLY with
text input
Reverse string
and WRITE
reverse string
Do datastream
conversion.
WRITE revised string
Display reversed
string and REPLY
REPLY (no
text returned)
WRITEREAD
prompt, "CPU, PIN-"
Do datastream
conversion;
WRITEREAD prompt
WRITE prompt
and read input text
VST015.vsd
The input string read by the IOP was passed to $GDS, and then on to $A1, which
reversed the sequence of characters in the string. $A1 then issued a call to WRITE
the reversed string to $GDS.#TC1. $GDS scanned the reversed text for lowercase
characters to be converted to uppercase before issuing a WRITE to terminal $TC1,
Extended General Device Support (GDSX) Manual—529931-001
4- 10
DEVICE^HANDLER Example, Running and
Managing
Running a Second Application Process
and the IOP displayed the uppercase reversed string. After checking the condition
code for its WRITE, $GDS REPLYs to $A1, which then sends another prompt to the
terminal by means of GDSX.
Now at the TACL terminal, enter the following command at the SCF prompt:
-> ASSUME SU $GDS.#TC1
The new prompt includes the name of the SU.
Enter an INFO command:
SU $GDS.#TC1 -> INFO
The INFO command gives information about the SU created and mapped to device
$TC1 when APPL was run.
Enter:
SU $GDS.#TC1 -> INFO, DETAIL
The INFO, DETAIL command gives even more information about the SU.
Enter another ASSUME command, followed by an INFO command:
SU $GDS.#TC1 -> ASSUME TASK
TASK $GDS #TC1 -> INFO
The prompt changes; then you see a display with the task number (3) and other
information. GDSX identifies a task externally by its task number and internally by a
task control block address.
Enter an INFO, DETAIL command:
TASK $GDS.#TC1 -> INFO, DETAIL
More detailed information is displayed. Note that the state of the SU is STARTED.
This is the normal state of a LINE or SU, when it is not faulted, stopped, or in the
process of being stopped.
Running a Second Application Process
If you have a second application terminal available, you can start a second application
process and direct I/O to the second application terminal. The second application
process uses the same object file APPL.
At the second application terminal, log on and enter a WHO command to identify the
terminal device name. Suppose for this example that it is $TC2. Pause the TACL
process with the PAUSE command.
At the TACL terminal, use the Break key to interrupt SCF and return to the TACL
prompt. Start the second application process, to be named $A2:
> RUN APPL /NAME $A2, OUT $GDS.#TC2, NOWAIT/
Extended General Device Support (GDSX) Manual—529931-001
4- 11
DEVICE^HANDLER Example, Running and
Managing
Running a Second Application Process
From the TACL prompt (you may need to use the Break key again to interrupt SCF),
you can enter:
> STATUS *, TERM
to see whether the process has started and what the CPU number and PIN are. The
CPU number and PIN should be the same as the numbers that now appear in the
prompt on the second application terminal.
Then pause the TACL process at the TACL terminal to allow SCF to regain control.
When you see the SCF prompt, enter:
-> STATUS PROCESS $GDS
The display tells you that now there are two TSCODE system tasks, and two USCODE
user tasks, which are both DEVICE^HANDLER tasks.
Enter:
-> INFO #TC2
You should see a display with the task number 4.
If you wish, you can enter strings at the second application terminal and verify that the
strings are reversed. GDSX may serve as a front-end process between multiple
requesters and a number of terminal devices.
At the second application terminal, press CTRL/Y. On the screen you see the
following:
EOF!
APPLICATION STOPPING
Press the Break key to get a TACL prompt at the application terminal.
At the TACL terminal, enter a FC command to repeat the previous SCF command.
(You may need to pause the TACL process to complete the command and see the
response.) You should see the message:
-> GDS E00001 Object name does not exist
This verifies that task number 4, the $GDS process’s DEVICE^HANDLER task that
was mapped to the second application terminal ($TC2), no longer exists.
To see if the $A2 application process has been stopped, enter the following command
at the TACL prompt:
> STATUS *, TERM
Then enter the following to allow SCF to regain control:
> PAUSE
Extended General Device Support (GDSX) Manual—529931-001
4- 12
DEVICE^HANDLER Example, Running and
Managing
Stopping the First Application and GDSX
Stopping the First Application and GDSX
At the SCF prompt, enter:
-> STOP SU
You should see the following message, indicating that the SU has an opener ($A1),
and therefore cannot be stopped:
-> GDS E00011 STOP failed:
Object is currently active
Then issue the following command for the same subdevice:
-> ABORT SU
At the first application terminal, after the CPU number and PIN prompt, you should see
the message:
D^H TASK STOPPED
At a TACL prompt, enter:
> STATUS *, TERM
Requester process $A1 should not appear.
If you enter the following command at the SCF prompt:
-> INFO SU
you should see a message that the object does not exist.
Then enter:
-> STOP PROCESS $GDS!
-> EXIT
The GDSX process is stopped and you exit from SCF. You may need to use the Break
key to get a TACL prompt.
Confirm that the GDSX process is gone by entering:
> STATUS *, TERM
Clear the values set by the PARAMs commands:
> CLEAR ALL
Extended General Device Support (GDSX) Manual—529931-001
4- 13
DEVICE^HANDLER Example, Running and
Managing
Stopping the First Application and GDSX
Extended General Device Support (GDSX) Manual—529931-001
4- 14
5
DEVICE^HANDLER Example, Design
The previous section described how to run and manage a simple DEVICE^HANDLER
example program. This section contains a description of the environment of an
executing DEVICE^HANDLER task, and an analysis of the design of the
DEVICE^HANDLER example, including the typical structure used by a
DEVICE^HANDLER for input, processing, and output to the IOP.
Environment of an Executing
DEVICE^HANDLER Task
The purpose of TSCODE is to provide a multithreaded, fault-tolerant shell for USCODE
procedures. To provide these services, GDSX was implemented in such a way that it
resembles a small, multitasking operating system.
In Guardian programming you have a source file and an object file, and the object file
runs under the operating system. In GDSX programming you have a
DEVICE^HANDLER procedure, which is like a normal Guardian source file, and a
DEVICE^HANDLER task, which is like a normal Guardian object file. The
DEVICE^HANDLER task runs under GDSX.
Figure 5-1 illustrates what a running DEVICE^HANDLER task looks like in this
example’s environment. (D^H represents the running DEVICE^HANDLER task within
the GDSX environment.) TSCODE, which surrounds the D^H tasks and includes the
monitor and listener tasks, provides a multithreaded, fault-tolerant environment for
USCODE.
TSCODE opens I/O devices on behalf of the tasks. When the example application
APPL opens a terminal under a GDSX process, TSCODE receives the OPEN request,
opens the terminal, and then assigns to the device a file number to be used by the task
that will be created to manage the device. The number assigned is the actual
Guardian file number for the device. (However, if a device is preconfigured under a
line, a different ITC file number is assigned—see the LINE^HANDLER example in
Section 6, LINE^HANDLER Example, Running and Managing and Section 7,
LINE^HANDLER Example, Design.)
TSCODE then calls the DEVICE^HANDLER procedure, thereby creating a
DEVICE^HANDLER task to manage the terminal. The first parameter supplied when
calling the procedure is the file number (filenum), which the DEVICE^HANDLER is to
use when communicating with the I/O device.
Extended General Device Support (GDSX) Manual—529931-001
5 -1
Task I/O Calls
DEVICE^HANDLER Example, Design
Figure 5-1. DEVICE^HANDLER Task Run-Time Environment
$GDS
Pseudo$RECEIVE File
Requester
TSCODE
D^H Task
$RECEIVE
D^H Task
Requester
Pseudo$RECEIVE File
Monitor Task
Listener Task
VST016.vsd
By means of a typical $RECEIVE file, TSCODE accepts incoming messages
addressed to subdevices under GDSX ($GDS.#TC1, for example). All requester
READ, WRITE, WRITEREAD, CONTROL, and SETMODE messages, and OPEN and
CLOSE messages if sysmsgs^flag of the CONTROLFLAGS configuration parameter is
set, are routed to the DEVICE^HANDLER task managing the device addressed. This
message passing is transparent to the DEVICE^HANDLER tasks. Each task reads
and replies to incoming messages by way of a pseudo-$RECEIVE file (with GDSX
internal file number 0), which TSCODE automatically opens for the task before creating
the task. Thus a DEVICE^HANDLER task does not directly open either its pseudo$RECEIVE file or the device that it manages.
Task I/O Calls
The usual strategy for managing I/O in a multithreaded program is to use the nowait
I/O tag facility of the Guardian file system. Such a design could have been
implemented in GDSX by letting you call the file system directly but requiring a
convention for nowait tags. This idea presented two problems:
•
The program would behave erratically if the you inadvertently supplied the wrong
tag.
Extended General Device Support (GDSX) Manual—529931-001
5 -2
DEVICE^HANDLER Example, Design
•
Task I/O Calls
You would no longer have access to nowait I/O tags for application-specific
purposes.
Therefore, in designing GDSX an additional layer of TSCODE software was placed
between USCODE and the Guardian file system, TS/MP server classes, and the TMF
product. This layer of software (called pseudo procedures) allows GDSX to monitor
every I/O operation that is initiated and ensures that each I/O can be properly handled
at completion time. Also, this approach allows GDSX to cancel any I/O operations that
a task has outstanding when the task is stopped.
Given this implementation of I/O, when developing a DEVICE^HANDLER, you must
not use the normal system procedures for I/O (for example, READUPDATE[X],
WRITEREAD[X], FILEINFO). You should use the GDSX pseudo Guardian procedures
(for example, ^READUPDATE[X], ^WRITEREAD[X], ^FILEINFO) that have the
identical functions as the system procedures (with a few exceptions).
For example, instead of sending a WRITEREAD directly to the IOP using the normal
system procedures, a DEVICE^HANDLER task sends it to the file designated by the
file number using the GDSX ^WRITEREAD procedure. Control is then transferred to
TSCODE, which does a Guardian nowaited call on behalf of the task. TSCODE then
returns control to the DEVICE^HANDLER task at the instruction following the
^WRITEREAD.
DEVICE^HANDLER tasks may continue processing while the IOP executes the
^WRITEREAD. Typically, the task issuing the ^WRITEREAD eventually uses a
^AWAITIO to wait for completion of the operation. See Figure 5-2 for an illustration of
WRITEREAD processing in the DEVICE^HANDLER example.
This multithreaded operation would not be possible if a DEVICE^HANDLER task called
Guardian I/O procedures in a waited manner. Even though GDSX may look like
separate processes running in an operating system, from the point of view of the
NonStop operating system, it is just one process. If a DEVICE^HANDLER task called
a waited I/O, such as a Guardian READ, the whole process, not just the
DEVICE^HANDLER task, would come to a halt, and the other tasks could not be
serviced during the suspension.
A number of Guardian procedures, such as NUMIN, NUMOUT, MYTERM, and
PROCESSHANDLE_DECOMPOSE, are resident system procedures and do not cause
the GDSX process to be suspended. Therefore, they may be called by USCODE.
Note. As a rule, if a Guardian call suspends not just a task but the whole GDSX process, do
not use it.
Extended General Device Support (GDSX) Manual—529931-001
5 -3
Task I/O Calls
DEVICE^HANDLER Example, Design
Figure 5-2. DEVICE^HANDLER Example: Sending a Request to a Terminal
Application
A WRITEREAD with
data is sent to GSDX
GDS (TSCODE and USCODE)
T S C O D E c h e c k s $ R E C E IV E fo r i np u t a n d
id e n t if ie s t h e U S C O D E D ^ H t a s k th a t i s t o
h a n d le th e W R IT E R E A D
IOP/Terminal
TSCODE checks to see whether a
^R E A D U P D A T E o n th e t a s k ' s p s e u d o $ R E C E IV E h a s b e e n is s u e d b y
th e ta s k . (I s s u in g ^R E A D U P D A T E m a k e s i t
p o s s ib l e to re c e i v e i n co m i n g m e s s a g e s .)
NO
YES
T S C O D E q u e u e s r e q u e s t. (D ^ H
t as k re c e i v e s th i s m e s s a g e w h e n it
i ss u e s a ^ R EA D U P D A T E .)
T S C O D E n o ti fi e s t h e D ^H ta s k o f t h e
p e n d in g me s s a g e b y c a ll in g WA K E ^T A S K ,
a n d f o rw a rd s th e m e ss a g e to th e D ^ H t a s k
fo r p r o c e ss i n g .
T h e U S C O D E D ^ H t a sk p e rf o rm s
d a ta s t re a m c o n v e r s io n .
T h e D ^ H ta s k is s u e s a ^W R IT E R E A D t o
s e n d t h e d a ta to th e te rm i n a l.
T S C O D E re c e iv e s th e ^WR I T E R E A D a n d
s e n d s a G u a rd i a n W R IT E R E A D t o th e
t e rm i n a l
Data goes to the IOP and
is sent to the terminal.
W h il e t h e I OP h a n d le s t h e d a t a , th e D ^ H
t a s k i s s u e s a n ^ A WA I T IO , w a it in g fo r
c o m p l e ti o n o f th e ^W R IT E R E A D .
T S C O D E re c e iv e s th e I/O c o m p le t io n
m e s s a g e a nd p a s s e s i t t o t h e D ^ H ta s k fo r
p r o c e s s in g .
Requester receives
response.
The I/O completion
message is sent.
T h e D ^H ta s k s e n d s a re s p o n s e to t h e
a p p l ic a t io n b y c a ll in g ^R E P L Y .
VST017.vsd
The following is a list of pseudo Guardian, TS/MP, and TMF procedures that must be
used instead of their counterparts. (Many TSCODE-supported procedures do not have
Extended General Device Support (GDSX) Manual—529931-001
5 -4
Task I/O Calls
DEVICE^HANDLER Example, Design
Guardian file-system counterparts, and are not included here. See Section 8, Service
Routines for a description of all TSCODE-supported procedures.)
**
**
**
^ABORTTRANSACTION
^READ[X]
^AWAITIO[X]
^READLOCK[X]
^BEGINTRANSACTION
^READUPDATE[X]
^CANCEL
^READUPDATELOCK[X]
^CANCELREQ
^RECEIVEINFO
^CANCELTIMEOUT
^REPLY[X]
^CLOSE
**
^RESUMETRANSACTION
^CONTROL
^SERVERCLASS_DIALOG_ABORT_
*
^DELAY
^SERVERCLASS_SEND_BEGIN_
*
^DEVICEINFO2
^SERVERCLASS_SEND_END_
**
^ENDTRANSACTION
^SERVERCLASS_SEND_SEND_
**
^FILE_CLOSE_
^SERVERCLASS_SEND_
**
^FILE_GETINFO_
^SERVERCLASS_SEND_INFO_
*
^FILE_GETINFOBYNAME_
^SETMODE
**
^FILE_GETRECEIVEINFO_
^SETMODENOWAIT
^FILEINFO
^SETMYTERM
^FILE_OPEN_
^SETPARAM
^FNAMEEXPAND
^SIGNALINTERRUPT
^LOCKREC
^SIGNALTIMEOUT
^MYTERM
^UNLOCKREC
**
^NEWPROCESS
^WRITE[X]
*
^OPEN
^WRITEREAD[X]
*
^PROCESS_CREATE_
^WRITEUPDATE[X]
**
^PROCESS_STOP_
^WRITEUPDATEUNLOCK[X]
*
*
**
Procedures that usually cause a task to be suspended.
Procedures that are waited operations.
Suspension of a task is transfer of control to the TSCODE dispatcher, which may then
execute a different task; when the task resumes execution, control is returned to the
instruction immediately following the pseudo call.
Because a USCODE task must relinquish control before TSCODE switches to the next
ready task, only those procedures marked with a single asterisk plus the TSCODEsupported utility procedures ^CHECKPOINT, DO^CP, FAULT, STOP^TASK,
WAITED^IO[X], and WAIT^EVENT need to be considered when an analyst determines
when a task will be suspended.
Extended General Device Support (GDSX) Manual—529931-001
5 -5
Basic Structure of DEVICE^HANDLER Code
DEVICE^HANDLER Example, Design
Basic Structure of DEVICE^HANDLER Code
A DEVICE^HANDLER task starts when TSCODE calls the DEVICE^HANDLER
procedure. After any necessary initialization processing, the task runs in a continuous
loop, reading from the pseudo-$RECEIVE file and sending output to and receiving
input from its device, never doing a RETURN to TSCODE. This structure is shown in
Figure 5-3.
Figure 5-3. DEVICE^HANDLER Program Structure
INIT
PROCESSING
WHILE (1)
DO
^READUPDATE
PSEUDO-$RCV
DECODE
REQUEST
WT
WT^RD
RD
CTRL
SET^MD
PROCESS REQUEST
DATA
^WT
TERM
^RD
TERM
^WT^RD
TERM
PROCESS
CTRL
PROCESS
SET^MD
PROCESS REPLY
DATA
^REPLY
VST018.vsd
Extended General Device Support (GDSX) Manual—529931-001
5 -6
DEVICE^HANDLER Example, Design
USKELEX Example Code
At different points the task may give up control to TSCODE, for example, when the
task does a ^AWAITIO following a ^WRITEREAD, the task is suspended, but there is
no actual exit from the DEVICE^HANDLER procedure. A task is stopped by TSCODE
if TSCODE receives a message from SCF to stop the SU, if TSCODE receives a
message from a requester thread to close the terminal to which it is mapped, or if the
task stops itself through a call to STOP^TASK.
This simple example program behaves like a single-threaded process (although
multithreaded operation is possible within a DEVICE^HANDLER task). In the loop, the
first thing done is a ^READUPDATE (not a Guardian READUPDATE) on pseudo$RECEIVE, which always has a file number of 0. Then there is logic to determine what
kind of request has been picked up from pseudo-$RECEIVE. (The types of requests
involved, while typical of a passthrough program, are example specific; other
applications might have more message-oriented requests.)
Datastream conversion is done at PROCESS REQUEST DATA in Figure 5-3, before
issuing a ^WRITE or ^WRITEREAD to the IOP. After a ^WRITEREAD or ^READ there
will be data coming back from the IOP. Although this example does not perform
incoming datastream translation, such processing could be included at the place in the
figure marked PROCESS REPLY DATA. CONTROL and SETMODE messages
picked up on the pseudo-$RECEIVE are simply passed on to the IOP.
Although every one of the I/O procedures used is inherently a nowait operation, from
the task’s point of view, the DEVICE^HANDLER uses waited I/O, because each of the
I/O calls is followed immediately with a ^AWAITIO, effectively making it a waited
operation.
USKELEX Example Code
This subsection examines the USKELEX source code. A complete listing is shown in
Appendix B. Example 5-1 shows the global declarations, which are typical for a user
source file. Global data within the common^data block can be referenced and updated
by both TSCODE and USCODE, while global data within the user^private data block
can be referenced and updated only by USCODE tasks.
Extended General Device Support (GDSX) Manual—529931-001
5 -7
USKELEX Example Code
DEVICE^HANDLER Example, Design
Example 5-1. USKELEX Global Declarations
! GDSX USCODE Skeleton File
?NOMAP, NOLMAP, NOCODE, SYMBOLS, CPU TNS/II
NAME uscode;
BLOCK COMMON^TEMPLATES;
?NOLIST, SOURCE
DCCBDECS (ERRORS)
?LIST, SOURCE
DCCBDECS (TCB^LAYOUT)
?LIST, SOURCE
DCCBDECS (IOCB^LAYOUT)
?LIST, SOURCE
DCCBDECS (FCB^LAYOUT)
?LIST, SOURCE
DCCBDECS (RCB^LAYOUT)
!===============================================================
!Comment Users may include their own file to modify DCB and
!
LINE Templates.
!Comment See file ULHDECS that USAMPLE sources in here
?LIST, SOURCE ULHDECSE (TEMPLATES)
!===============================================================
END BLOCK; ! COMMON^TEMPLATES
BLOCK CONFIG^PARMS^TEMPLATES;
?NOLIST, SOURCE
DCCBDECS (CONFIG^TEMPLATES)
?LIST
END BLOCK; ! CONFIG^PARMS^TEMPLATES
! Global Data
!
BLOCK CONFIG^PARMS^DATA;
?NOLIST, SOURCE
DCCBDECS (CONFIG^DATA)
?LIST
END BLOCK; ! CONFIG^PARMS^DATA
BLOCK COMMON^DATA;
?NOLIST, SOURCE
DCCBDECS (COMMON^DATA)
?LIST
END BLOCK; ! COMMON^DATA
BLOCK USER^PRIVATE;
LITERAL TRUE = -1, FALSE = 0;
END BLOCK; !USER^PRIVATE
!===============================================================
!Comment User may include System Procedures desired here.
?NOLIST, SOURCE $SYSTEM.SYSTEM.EXTDECS0(DEBUG, NUMOUT, NUMIN);
!===============================================================
?LIST
?NOLIST, SOURCE PEXTGDS
First of all, five sections of the DCCBDECS file are sourced in. These sections define
templates for control structures shared by TSCODE and USCODE, listed in Table 5-1.
A listing of DCCBDECS is contained in Appendix C.
Table 5-1. Global Declarations Sourced in by USKELEX
Description of Contents
File Name
Sections of File
Control block template definitions
DCCBDECS
errors, tcb^layout, iocb^layout,
fcb^layout, rcb^layout
User-modified control block template
definitions
ULHDECSE
templates
Extended General Device Support (GDSX) Manual—529931-001
5 -8
The DEVICE^HANDLER Procedure
DEVICE^HANDLER Example, Design
Table 5-1. Global Declarations Sourced in by USKELEX
Configuration template definition
DCCBDECS
config^templates
Configuration template allocation
DCCBDECS
config^data
DEFINEs; various globals allocated
DCCBDECS
common^data
External procedure declarations
EXTDECS0
debug, numout, numin
External procedure declarations for
TSCODE routines
PEXTGDS
(Entire file used)
The section sourced in from ULHDECSE contains a user-customized version of the
template declaration for a device control block (DCB). This type of file allows the
addition of scratchpad variables or user-defined attributes that are specific to a class of
devices.
The config^templates section from DCCBDECS allows programmatic access to the
configuration parameters used by TSCODE.
The config^data section of DCCBDECS contains an allocation of the configuration
template defined in the config^templates section. Common^data contains
miscellaneous globals and DEFINEs.
From EXTDECS0 you source in all the system procedures that you want to use.
PEXTGDS contains EXTERNAL declarations for all TSCODE procedures callable from
USCODE. All the pseudo procedures and the utility procedures are declared in
PEXTGDS.
The DEVICE^HANDLER Procedure
Now the procedure declarations for USKELEX may be examined. Stubs are provided
for all user exits except the DEVICE^HANDLER, LINE^HANDLER, and USER^STOP,
which are customized. The first procedure to be discussed is DEVICE^HANDLER.
USER^STOP is discussed later in this section, and the LINE^HANDLER, which is
never called in the example presented in Section 4, DEVICE^HANDLER Example,
Running and Managing and Section 5, DEVICE^HANDLER Example, Design, is
discussed in Section 6, LINE^HANDLER Example, Running and Managing and
Section 7, LINE^HANDLER Example, Design.
There are three parameters passed by TSCODE to the DEVICE^HANDLER, shown in
Example 5-2.
Extended General Device Support (GDSX) Manual—529931-001
5 -9
The DEVICE^HANDLER Procedure
DEVICE^HANDLER Example, Design
Example 5-2. DEVICE^HANDLER Local Declarations
PROC DEVICE^HANDLER (TERM^FILE^NUM, INTERNAL^TERM^NO, TERM^TYPE);
INT TERM^FILE^NUM
,
INTERNAL^TERM^NO,
TERM^TYPE
;
! FILE^NUM FOR THIS D^H TASK
! TERM NUMBER FOR THIS D^H TASK
! TERMINAL TYPE
BEGIN
!===============================================================
!
Comment - USCODE can declare desired Device^Handler Local
!
Variables here
!===============================================================
INT .EXT MY^DCB(DCB^TEMPLATE);
INT .EXT TERM^BUF;
STRING .EXT S^TERM^BUF;
INT .EXT RCV^BUF;
STRING .EXT S^RCV^BUF;
INT .EXT E^RCV^BUF := 0D;
INT RQSTR^WT^CT;
INT RQSTR^RD^CT;
INT TERM^CT^RD;
INT DOLR^RCV := 0;
INT RQST^TYPE := 0;
INT FERR;
INT TAKE^OVER;
LITERAL WT=1, RD=2, WT^RD=3, CTRL=4, SET^MD=5;
LITERAL BUF^SIZE = 1024;
The first, term^file^num, is the pseudo-file number (not a Guardian file number) used
for I/O to the file that this task is to manage. Note that the DEVICE^HANDLER does
not open this file; TSCODE opens it, assigns a term^file^num for the task to use, and
passes this number when the call to DEVICE^HANDLER creates the task.
The second parameter is the internal^term^no. Each DEVICE^HANDLER task has
exactly one device control block (DCB) associated with it. Internal^term^no is an index
used to find this task’s DCB in the array of DCBs. This is discussed later in this
section.
If a task is configured with the SCF ADD SU command (which is discussed in
Section 6, LINE^HANDLER Example, Running and Managing), the SU’s SUTYPE
attribute can be set, indicating what type of terminal is being configured. When
TSCODE calls the DEVICE^HANDLER procedure, it passes this setting as the
term^type parameter; the DEVICE^HANDLER task can then use a CASE statement on
term^type to branch to different code for different types of terminals.
Example 5-2 also shows miscellaneous pointers as well as literals used for analyzing
the five different kinds of requests that may be received.
Reading and Decoding Requests
Although the SCAN^BUF subprocedure appears next in the source code (see
Appendix B, USKELEX and USKELEXC Listings), it is discussed with the different
types of request processing below.
Extended General Device Support (GDSX) Manual—529931-001
5- 10
DEVICE^HANDLER Example, Design
The DEVICE^HANDLER Procedure
Within the main loop of the DEVICE^HANDLER (see Example 5-3 and Example 5-6), a
buffer of size buf^size is requested from the byte-addressable extended buffer pool.
The buffer holds a message read from the pseudo-$RECEIVE file. Because tasks are
swapped in and out, I/O cannot be done from buffers within a task’s data stack.
Instead of declaring local variables for message buffers, I/O buffer space is obtained
from the global memory pools.
Example 5-3. Reading and Decoding Requests
!===============================================================
!
Device^Handler Procedure MAIN ENTRY POINT begins here
!===============================================================
WHILE (1) DO
BEGIN
@RCV^BUF := GETEXTPOOL(10,BUF^SIZE); !EXT BUFFER POOL
IF @RCV^BUF = 0D THEN CALL DEBUG;
!(BYTE ADDRESSABLE)
@E^RCV^BUF := @RCV^BUF;
TAKE^OVER := FALSE;
CALL ^READUPDATEX(DOLR^RCV,RCV^BUF,BUF^SIZE);
IF <> THEN CALL DEBUG;
CALL ^AWAITIOX(DOLR^RCV,@RCV^BUF,RQSTR^WT^CT);
IF = THEN
! (CCE) NORMAL COMPLETION
CALL ^RECEIVEINFO(,,,,RQSTR^RD^CT,RQST^TYPE)
ELSE IF > THEN
! (CCG) SYSTEM MSG RECEIVED
BEGIN
IF RCV^BUF[0] = -32 THEN
RQST^TYPE := CTRL
ELSE IF RCV^BUF[0] = -33 THEN
RQST^TYPE := SET^MD
ELSE
CALL DEBUG;
END
ELSE
CALL DEBUG;
! (CCL) ERROR
The 10 in the GETEXTPOOL call indicates the extended buffer pool. The buffer
allocated is pointed to by @rcv^buf. The take^over variable is used when running this
example as a process pair, and is discussed later in this section.
Note. The USKELEX and USKELEXC example programs include very little error-handling
logic, because error-handling code depends on the application requirements, and extensive
error-handling code would detract from the overall design focus of this tutorial. Adequate error
handling, however, must be included in applications designed for actual production.
Then ^READUPDATE is called on dolr^rcv, which represents the pseudo-$RECEIVE
file set up by TSCODE. (The pseudo-$RECEIVE file is indicated by value 0 for all
DEVICE^HANDLER tasks.) Because this is a single-threaded routine, the
^READUPDATE is followed by a ^AWAITIO on dolr^rcv with no timeout specified.
Then there is a check to see what kind of operation is being requested. If the condition
code is equal, ^AWAITIO completed normally, and either a WRITE, a READ, or a
WRITEREAD came in. ^AWAITIO gives the WRITE count (rqstr^wt^ct) that the
requester specified, and ^RECEIVEINFO gives the READ count (rqstr^rd^ct) specified
by the requester and the request type (rqst^type).
Extended General Device Support (GDSX) Manual—529931-001
5- 11
DEVICE^HANDLER Example, Design
The DEVICE^HANDLER Procedure
If the condition code is > (CCG), a system message was received. The first character
of rcv^buf is examined to determine what kind of system message this is. The only
kind allowed for by this code is CTRL or SET^MD, -32 or -33, respectively. For
anything else, DEBUG is called.
Request Processing
Next in the source file is a section of code dealing with fault-tolerance processing, to be
discussed later in this section. Then there is code used to process the different types
of requests, shown in Example 5-4. A receiving buffer has already been allocated for
the data that came in on pseudo-$RECEIVE. Now a terminal buffer is allocated for the
data that will go out to the IOP.
Example 5-4. Request Processing (page 1 of 2)
@TERM^BUF := GETEXTPOOL(10,BUF^SIZE);
IF @TERM^BUF = 0D THEN CALL DEBUG;
CASE RQST^TYPE OF
BEGIN
WT^RD -> ! WRITEREAD
BEGIN
IF (NOT TAKE^OVER) THEN
BEGIN
CALL SCAN^BUF;
@MY^DCB := DCBTBL[INTERNAL^TERM^NO];
MY^DCB.WT^RD^PEND := TRUE; ! SET FLAG
! FOR USER^STOP PROCEDURE
CALL ^WRITEREADX(TERM^FILE^NUM,TERM^BUF,
RQSTR^WT^CT,RQSTR^RD^CT);
IF <> THEN CALL DEBUG;
CALL ^AWAITIOX(TERM^FILE^NUM,@TERM^BUF,
TERM^CT^RD);
CALL ^FILEINFO(TERM^FILE^NUM,FERR);
IF (FERR = 0) THEN
CALL ^REPLYX(TERM^BUF,TERM^CT^RD)
! NORMAL COMPLETION
ELSE
CALL ^REPLYX(,,,,FERR); ! APPL DEALS WITH
! IOP FS ERRORS
MY^DCB.WT^RD^PEND := FALSE;
! CLEAR FLAG
END;
END;
WT -> ! WRITE
BEGIN
CALL SCAN^BUF;
CALL ^WRITEX(TERM^FILE^NUM,TERM^BUF,RQSTR^WT^CT);
IF <> THEN CALL DEBUG;
CALL ^AWAITIOX(TERM^FILE^NUM);
CALL ^FILEINFO(TERM^FILE^NUM,FERR);
CALL ^REPLYX(,,,,FERR);
END;
Extended General Device Support (GDSX) Manual—529931-001
5- 12
DEVICE^HANDLER Example, Design
The DEVICE^HANDLER Procedure
Example 5-4. Request Processing (page 2 of 2)
RD -> ! READ
BEGIN
CALL ^READX(TERM^FILE^NUM,TERM^BUF,RQSTR^RD^CT);
IF <> THEN CALL DEBUG;
CALL ^AWAITIOX(TERM^FILE^NUM,@TERM^BUF,TERM^CT^RD);
CALL ^FILEINFO(TERM^FILE^NUM,FERR);
IF (FERR = 0) THEN
CALL ^REPLYX(TERM^BUF,TERM^CT^RD)
ELSE
CALL ^REPLYX(,,,,FERR);
END;
CTRL -> ! CONTROL
BEGIN
CALL ^CONTROL(TERM^FILE^NUM,RCV^BUF[1],RCV^BUF[2]);
IF <> THEN CALL DEBUG;
CALL ^AWAITIOX(TERM^FILE^NUM);
CALL ^FILEINFO(TERM^FILE^NUM,FERR);
CALL ^REPLYX(,,,,FERR);;
END;
SET^MD -> ! SETMODE
BEGIN
CALL ^SETMODENOWAIT(TERM^FILE^NUM,RCV^BUF[1],
RCV^BUF[2],RCV^BUF[3]);
IF <> THEN CALL DEBUG;
CALL ^AWAITIOX(TERM^FILE^NUM);
CALL ^FILEINFO(TERM^FILE^NUM,FERR);
CALL ^REPLYX(,,,,FERR);
END;
END;
!CASE
CALL PUTEXTPOOL(10,@TERM^BUF);
CALL PUTEXTPOOL(10,@RCV^BUF);
END;
END;
!WHILE
!PROC
The terminal buffer is needed because the application subroutine SCAN^BUF converts
the data in the receiving buffer (rcv^buf), changing each byte so that a hexadecimal 6
in the leftmost four bits becomes a hexadecimal 4, and a hexadecimal 7 in the leftmost
four bits becomes a hexadecimal 5. (Code for the SCAN^BUF subprocedure is shown
in Appendix B.) This conversion effectively capitalizes any lowercase alphabetic
characters.
The converted data is put into the terminal buffer. The terminal buffer is not allocated
until necessary; during the previous ^AWAITIO it was not needed. In general,
memory should not be allocated from the pools until it is needed, so that it is available
for other tasks.
The type of request is tested with a CASE statement. If the request is a WRITEREAD
(and it is not the case that a backup process has just taken over, as discussed later in
this section), the SCAN^BUF subroutine is called, and then ^WRITEREAD is called,
followed by ^AWAITIO. A flag, my^dcb.wt^rd^pend, is set before the ^WRITEREAD
and reset after the completion of the operation. If the task is stopped, this flag is tested
Extended General Device Support (GDSX) Manual—529931-001
5- 13
DEVICE^HANDLER Example, Design
Inspecting the DEVICE^HANDLER Example
to see whether there is an outstanding ^WRITEREAD to be canceled (this is discussed
under The USER^STOP Procedure on page 5-19). Any file-system error is passed
back to the requester application. The processing for WRITE and for READ is similar.
Incoming datastream conversion could be implemented by a procedure called
immediately before ^REPLY when processing READ and WRITEREAD requests.
CONTROL and SETMODE requests are passed through the DEVICE^HANDLER. If a
CTRL message is received, ^CONTROL is called, passing the first two characters of
the receiving buffer. The completion gives file-system error information, which is
passed on to the requester. SETMODE processing is similar.
Before returning to the beginning of the loop, the terminal buffer and the receiving
buffer are released.
Inspecting the DEVICE^HANDLER Example
The next part of the tutorial uses the Inspect utility to trace the operation of the
DEVICE^HANDLER example and to display the contents of relevant control structures.
It may be unnecessary to do this part if you are working with or developing a simple
DEVICE^HANDLER procedure that does not manipulate the contents of control blocks
shared with TSCODE. This tutorial useful if:
•
•
•
Your DEVICE^HANDLER manipulates control structures.
You are working with or developing a LINE^HANDLER.
You are debugging a GDSX subsystem.
This exercise requires three terminals to be designated the TACL terminal, the Inspect
terminal, and the application terminal. Log on to all three terminals.
At the application terminal, pause the TACL process with the PAUSE command.
Suppose for this example that the terminal’s device name is $TC1.
At the TACL terminal, use CLEAR ALL if necessary to clear any previously set
parameter values, and then issue commands as given in Running the
DEVICE^HANDLER Example on page 4-6 to run a DEVICE^HANDLER process:
> PARAM EXTSUSIZE 1
> RUN GDSE /NAME $GDS, NOWAIT/
Start an application process, named $A1 in this example:
> RUN APPL /NAME $A1, OUT $GDS.#TC1, NOWAIT/
The application terminal should now display a prompt.
At the Inspect terminal, PAUSE the TACL process. Suppose for this example that the
terminal’s device name is $TC2.
Extended General Device Support (GDSX) Manual—529931-001
5- 14
DEVICE^HANDLER Example, Design
Device Control Blocks
At the TACL terminal, bring your GDSX process under the control of Inspect by
entering:
> DEBUG $GDS, TERM $TC2
To make the source code visible under Inspect, in high-level Inspect at the Inspect
terminal, enter:
- SOURCE ON
- SCOPE #DEVICE^HANDLER
- SOURCE
Enter a few carriage returns until you see the CASE RQST^TYPE statement. Set a
breakpoint at this line:
- BREAK #line-num
Then press “R” to resume execution of your program.
At the application terminal, enter a short text string followed by a carriage return. This
should force the GDSX process to a breakpoint, which is displayed at the Inspect
terminal. (The requester has issued a WRITE to send the modified text string back to
its OUT file.)
At the Inspect terminal, use the DISPLAY command to find the current value of
rqst^type:
- DISPLAY RQST^TYPE
Check the LITERALs, defined near the beginning of the DEVICE^HANDLER code, to
determine what kind of operation has been initiated by the requester. (It should be a
WRITE.)
Device Control Blocks
Now you can examine some of the pertinent control structures for the
DEVICE^HANDLER task. The DCB is the starting point. A DCB is the internal
representation of an SU and is used to manage a DEVICE^HANDLER task’s
communication with a file. When the requester application in this example opened
terminal $TC1, TSCODE opened the terminal, assigned a DCB to manage the
terminal, and created a DEVICE^HANDLER task that maps to the DCB.
The DCB contains:
•
•
•
The variable name that contains the name of the SU object corresponding to the
DCB (this example uses a dynamic SU, so the variable name is set to $TC1)
The access name or file name actually opened for the corresponding SU ($TC1 in
this example)
The variable tcbaddr, a pointer to the associated task control block (discussed
below)
ULHDECSE contains USKELEX’s dcb^template and is included in Appendix C.
Extended General Device Support (GDSX) Manual—529931-001
5- 15
Device Control Blocks
DEVICE^HANDLER Example, Design
Storage for DCBs is declared at run time by TSCODE and is contained in extended
memory. The size of a DCB for a GDSX process depends on the EXTSUSIZE
configuration parameter, which can be supplied at startup time. Therefore, storage for
DCBs cannot be determined at compile time.
At startup time, depending on the EXTSUSIZE and MAXTERMS configuration
parameters, the maximum number of SUs that can be active simultaneously within a
GDSX process, TSCODE initializes an array containing pointers to each configured
DCB. See Figure 5-4. The index into this address array is stored in the variable
internal^term^no, which is passed by TSCODE’s call to the DEVICE^HANDLER to
create the task associated with the DCB. Finally, dcbtbl (found in the common^data
section of DCCBDECS) is the pointer to this array of addresses.
Figure 5-4. Locating DCBs
DCB Pointer
Array Indexed by
INTERNAL^TERM^NO
DCBs
DCBTBL
DCB Size
DCBTBL (0)
.
.
.
.
.
.
VST019.vsd
To get the octal address of the DCB, enter:
- DISPLAY (DCBTBL[INTERNAL^TERM^NO]) IN OCTAL
To see the contents of the DCB, use the octal value from the DISPLAY command:
- DISPLAY (octal-dcb-address) AS DCB^TEMPLATE
Record the displayed tcbaddr value (tcb-address). This is the address of the task
control block of the task that is mapped to the DCB. See Figure 5-5 for a preview of
the control block pointer tracing that will be done in the remainder of this exercise. The
task control block is explained shortly.
Extended General Device Support (GDSX) Manual—529931-001
5- 16
Task Control Blocks
DEVICE^HANDLER Example, Design
Figure 5-5. Control Block Pointer Tracing
TCB
DCBs
IOCB
BUFFER
IOCNT
BUFADDR [X]
TEXT
TCBADDR
LASTRCVIOCB
VST020.vsd
To confirm that the correct DCB has been located, you can display the name and
access name fields in ASCII, as follows:
- DISPLAY (octal-dcb-address) AS DCB^TEMPLATE IN ASCII
Verify that the value of the variable name is the OUT file ($TC1) opened by the
requester, and that the access name was correctly derived from the qualifier(s) in the
requester’s OUT file name.
Task Control Blocks
When a task is started, TSCODE assigns a task control block (TCB), which is used to
manage the task. When the requester application in this example opened terminal
$TC1, TSCODE opened the terminal, created a DCB to manage communication to the
terminal, created a DEVICE^HANDLER task that maps to the DCB, and created a TCB
to manage the task. The TCB includes the following:
•
•
•
•
Pointers to the linked list of I/O control blocks (IOCBs, to be discussed shortly)
owned by the task.
Lastrcviocb, the address of the IOCB representing the last $RECEIVE request
passed to the task.
Term, the GDSX internal file number of the device to which this task is mapped.
Dcbaddr, a pointer to the associated device control block.
DCCBDECS contains USKELEX’s tcb^template and is shown in Appendix C. Storage
for TCBs is declared by TSCODE and is contained in extended memory.
Display the contents of the DEVICE^HANDLER task’s TCB by issuing:
- DISPLAY (tcb-address) AS TCB^TEMPLATE
Record the value of lastrcviocb (iocb-address).
Extended General Device Support (GDSX) Manual—529931-001
5- 17
DEVICE^HANDLER Example, Design
I/O Control Blocks
I/O Control Blocks
Now examine the I/O control block (IOCB) representing the last $RECEIVE request (a
WRITE) passed to the task. TSCODE allocates an IOCB to manage each outstanding
nowait I/O. All IOCBs representing I/O operations for a particular task are linked to the
task’s TCB. An IOCB contains the following:
•
•
•
•
Optype, the I/O operation type
Iocnt, the I/O count in bytes returned from AWAITIO
Bufaddrx, the buffer address
Tcbaddr, the address of the task requesting the I/O
DCCBDECS contains USKELEX’s iocb^template and is shown in Appendix C.
Storage for IOCBs is declared by TSCODE and contained in extended memory.
Display the contents of the IOCB pointed to by lastrcviocb:
- DISPLAY (iocb-address) AS IOCB^TEMPLATE
and record the value of iocnt.
The buffer address is held in the doubleword variable bufaddrx. Record the value of
bufaddrx (buffer-address).
Now convert the buffer address value to octal with the command:
- D (buffer-address) IN OCTAL
and record the displayed quantity (octal-buffer-address).
The conversion to octal is necessary because high-level Inspect displays INT
variables, such as bufaddr, as signed quantities. Addresses in the upper 32K words of
your program’s data space will appear as negative numbers. Low-level Inspect, which
you will use to display the ASCII contents of buffers, expects unsigned values, octal by
default; hence, the conversion is necessary.
Enter low-level Inspect, and display the buffer contents in ASCII by entering:
- LOW
- A octal-buffer-address, 40
There should be eight spaces, followed by the reversed string of characters that you
entered at the application terminal.
Return to high-level Inspect and enter “R“ to resume program execution. The text you
observed at buffer-address should now display on the application terminal, except
for the additional datastream conversion. At the next breakpoint, enter STOP.
At the TACL terminal, confirm that both the GDSX process and the requester are gone.
Then log off all terminals.
Extended General Device Support (GDSX) Manual—529931-001
5- 18
DEVICE^HANDLER Example, Design
The USER^STOP Procedure
The USER^STOP Procedure
In an exercise in the previous section, an SU was stopped with an SCF ABORT
command. The abort message was sent to TSCODE, which then stopped the
DEVICE^HANDLER task.
When the task was stopped, the USER^STOP user exit was called by TSCODE, as
shown in Example 5-5. Because the stopped task, whose TCB address is passed in
the call to USER^STOP, was waiting on a ^WRITEREAD (dcb.wt^rd^pend equal to
TRUE) and was indeed a DEVICE^HANDLER task (in which case tcb.state is less than
or equal to 15), then ^CANCEL was called on the file to which the task was mapped
(tcb.term, which is the same as term^file^num for the DEVICE^HANDLER task).
Example 5-5. The USER^STOP Procedure
PROC USER^STOP (TCB);
INT .EXT TCB(TCB^TEMPLATE);
BEGIN
INT FILENO;
INT MESSG[0:8] := "D^H TASK STOPPED ";
INT .EXT DCB(DCB^TEMPLATE);
@DCB := TCB.DCBADDR;
IF ((TCB.STATE.<10:15> < 16 ) ! A D^H TASK IS BEING STOPPED
AND
(DCB.WT^RD^PEND = TRUE)) THEN
! WAITING ON A WRITEREAD
BEGIN
! CANCEL OUTSTANDING I/O FROM A D^H TASK
CALL ^CANCEL(TCB.TERM); ! (EITHER FOR DEVICE I/O OR FOR ITC)
IF <> THEN CALL DEBUG;
IF (DCB.LINENO = 0 ) THEN
BEGIN
FILENO := TCB.TERM;
CALL ^WRITE(FILENO, MESSG, 18); !We don't use WRITEX
IF <> THEN CALL DEBUG; !because MESSG is in local stack
CALL ^AWAITIO(FILENO);
END;
END;
END;
The variable dcb.wt^rd^pend was tested to see whether a WRITEREAD was pending,
because attempting to cancel a nonexistent I/O operation may cause the GDSX
process to stop. Calling ^CANCEL cancels the last incomplete operation sent to the
file, the ^WRITEREAD, which in this case, because the DEVICE^HANDLER effectively
uses waited I/O, was also the only outstanding operation. The ^CANCEL resulted in
TSCODE deleting the IOCB associated with the request and returning a file-system
error 66 to the requester process. The requester then sent a close message to GDSE
and stopped itself.
The SU was not configured under a LINE, so dcb.lineno is equal to 0, and therefore the
“D^H TASK STOPPED“ message was written to the task’s file.
Fault-Tolerance Processing
The next part of the tutorial uses Inspect to observe the action of GDSX fault-tolerance
features of the DEVICE^HANDLER example. TSCODE provides several features for
Extended General Device Support (GDSX) Manual—529931-001
5- 19
Testing Failure at a ^WRITEREAD
DEVICE^HANDLER Example, Design
support of fault-tolerant applications. Depending on the degree to which USCODE
implements these features, various levels of fault tolerance can be achieved.
Persistent operation is possible without checkpointing by USCODE if a backup CPU is
specified when the GDSX process is started. In this case TSCODE:
•
•
•
•
Starts the backup process and monitors for failures.
Checkpoints global information such as control structures.
Restarts each task that was active at the time of failure. Tasks are restarted from
the beginning.
Starts a new backup process after a failure.
It may be unnecessary to do this part of the tutorial if your GDSX application does not
require fault-tolerance features beyond restarting tasks in case of a takeover by the
backup process. You will probably find it useful, however, if you need to use
TSCODE-supported checkpointing procedures to send stack images or dynamically
allocated memory to the backup process.
This exercise requires three terminals to be designated the TACL terminal, the Inspect
terminal, and the application terminal. Log on to all three terminals.
Testing Failure at a ^WRITEREAD
At the application terminal, pause the TACL process with the PAUSE command. For
this example, the terminal’s device name is $TC1.
At the TACL terminal, use CLEAR ALL if necessary to clear any previously set
parameter values, and enter the following PARAM command:
> PARAM EXTSUSIZE 1
Then run the GDSX example as a process pair by specifying a backup CPU:
> RUN GDSE /NAME $GDS, NOWAIT, CPU primary / backup
where primary and backup are CPU numbers for your system.
See whether the processes have actually been started:
> STATUS *, TERM
Record the CPU and PIN values for the GDSX processes for later reference:
primary-cpu,primary-pin
backup-cpu,backup-pin
Start a requester process that will create a DEVICE^HANDLER task under GDSX:
> RUN APPL /NAME $A1, OUT $GDS.#TC1, NOWAIT/
The application terminal should now display a prompt.
At the application terminal, enter a few strings at the requester prompts to confirm that
the system behaves as you previously observed. Then enter some text at the prompt,
Extended General Device Support (GDSX) Manual—529931-001
5- 20
Testing Failure at a ^WRITEREAD
DEVICE^HANDLER Example, Design
but do not enter a carriage return. The requester and the DEVICE^HANDLER task
now have pending WRITEREADs.
At the TACL terminal, simulate a GDSX process failure by entering:
> STOP primary-cpu, primary-pin
At the application terminal, after the CPU and PIN prompt and the text that you
entered, in approximately half a minute you should see the following message:
PLEASE RE-ENTER DATA
followed by a new CPU and PIN prompt. Enter a text string or two to verify that the
system is still running as usual. Note that the prompt did not change. GDSX, not the
requester, switched over.
At the TACL terminal, enter:
> STATUS *, TERM
Record the new CPU and PIN values for the GDSX process:
primary-cpu,primary-pin
backup-cpu,backup-pin
When $GDS was stopped, file-system error 210 was returned to $A1. The code then
executed by $A1 is shown in Example 5-6. A message is sent by way of the new
primary process to the OUT file requesting that data be reentered, because anything
that was entered at a prompt before a carriage return was entered was not transferred
to the IOP. Then, after a two-second delay, a new prompt is sent to the terminal,
starting a new WRITEREAD-WRITE transaction. Therefore, the DEVICE^HANDLER
is designed so that it does not retry a ^WRITEREAD following a takeover.
Example 5-6. Requester Code for Takeover at a ^WRITEREAD
ELSE IF (FERR = 210) THEN
BEGIN
! OUTFILE SWITCHED TO BACKUP, CONTINUE
WT^CT :=28;
S^MSG^BUF ':=' 8*[“ “] & [“PLEASE RE-ENTER DATA“];
CALL WRITE(MSG^FILE,MSG^BUF,WT^CT);
IF <> THEN
BEGIN
! CONTINUE ON GDSX SWITCHOVER
CALL FILEINFO(MSG^FILE,FERR);
IF (FERR <> 210) THEN CALL DEBUG;
END;
END
Fault-tolerance processing in the DEVICE^HANDLER is diagrammed in Figure 5-6.
The fault-tolerance code is included in the listing in Appendix B. Suppose that the
DEVICE^HANDLER was executing a ^WRITEREAD when the primary process failed.
The GDSX backup process then takes over, and TSCODE restarts the
DEVICE^HANDLER at the return from the call to ^CHECKPOINT(2), which in this case
is the TAKEOVER := TRUE statement.
TSCODE restarts at this point because whenever there is a call to the ^CHECKPOINT
function, TSCODE establishes a restart point in the calling task at the return from the
call, in a manner similar to a call to the Guardian procedure CHECKPOINT. If there
Extended General Device Support (GDSX) Manual—529931-001
5- 21
Testing Failure at a ^WRITEREAD
DEVICE^HANDLER Example, Design
had been no ^CHECKPOINT call, the task would have been restarted from its main
entry point.
Figure 5-6. Fault Tolerance in the DEVICE^HANDLER Example
WHILE (1)
DO
@RCV^BUF :=
GETEXTPOOL (...
TAKEOVER :=
FALSE
^READUPDATEX
(PSEUDO-$RCV,...
ANALYZE
REQUEST TYPE
TAKEOVER
^CHECKPOINT(2)
TAKEOVER :=
TRUE
NORMAL
^RECLAIMBUFFER
(@E^RCV^BUF, 10)
WT
WTRD
TRUE
TAKEOVER?
^WTX TERM
FALSE
^WTX TERM
^REPLYX
VST021.vsd
If ^CHECKPOINT is called with type equal to 1, only the task’s stack image is
checkpointed to the backup. If the procedure is called with type equal to 2, the stack
image plus any memory pool buffers allocated by the task are checkpointed to the
Extended General Device Support (GDSX) Manual—529931-001
5- 22
DEVICE^HANDLER Example, Design
Testing Failure at a ^WRITE
backup process. Therefore, because this example calls ^CHECKPOINT(2), after
takeover the receiving buffer (rcv^buf) allocated from the buffer pool will be available.
In the event of a takeover, however, any memory pool buffer addresses that the task
has stored in its data stack are no longer valid. A task must recover its buffer images
by making calls on ^RECLAIMBUFFER. Thus, the statement CALL
^RECLAIMBUFFER (@e^rcv^buf , 10), which remaps rcv^buf from the buffer pool
(indicated by 0) is executed.
After a terminal buffer is allocated, the CASE statement determines that the operation
was a WRITEREAD. Then an IF statement, testing the value of take^over, causes the
code for normal processing of a WRITEREAD to be bypassed. The
DEVICE^HANDLER releases its buffers and returns to the beginning of its transaction
processing loop. The DEVICE^HANDLER does not retry the ^WRITEREAD, because
the requester is designed to start a new WRITEREAD-WRITE transaction if a takeover
occurs when the DEVICE^HANDLER is doing a ^WRITEREAD.
Testing Failure at a ^WRITE
Now you can continue the fault-tolerance processing exercise to observe how
checkpointing in the GDSX process can recover from a process failure during a WRITE
operation. First, PAUSE the Inspect terminal. Suppose that the terminal’s device
name is $TC2.
At the TACL terminal, bring the GDSX primary process under the control of Inspect by
entering:
> DEBUG primary-cpu, primary-pin, TERM $TC2
To make the source code visible under Inspect, in high-level Inspect at the Inspect
terminal, enter:
- SOURCE ON
- SCOPE #DEVICE^HANDLER
- SOURCE
Put a breakpoint at the CASE RQST^TYPE OF statement in DEVICE^HANDLER’s
main loop. Resume program execution.
At the application terminal, enter a short text string followed by a carriage return. This
forces the GDSX primary process to its breakpoint, which will be displayed on the
Inspect terminal.
At the Inspect terminal, display the value of rqst^type (it should be a 1), and check it
against the literals defined in DEVICE^HANDLER to confirm that the requester’s
operation is a WRITE.
Force a primary process failure by entering:
- STOP
At the application terminal, confirm that the transaction completes properly, and that
GDSX still functions as usual.
Extended General Device Support (GDSX) Manual—529931-001
5- 23
DEVICE^HANDLER Example, Design
Testing Failure at a ^WRITE
When the GDSX primary process was stopped, the requester received file-system
error 210 on its WRITE and completed its transaction processing loop as if the WRITE
had been completed normally. The requester is designed to let the
DEVICE^HANDLER retry the WRITE.
After the takeover, processing within the DEVICE^HANDLER was the same as
described above after a WRITEREAD, down to the CASE RQST^TYPE OF statement,
where it was determined that the operation was a WRITE. Then normal processing for
a WRITE was retried, and the transaction was completed.
At the TACL terminal, stop the GDSX process, confirm that the requester has stopped
as well, and log off all terminals.
Extended General Device Support (GDSX) Manual—529931-001
5- 24
6
LINE^HANDLER Example, Running
and Managing
The typical purpose of a DEVICE^HANDLER task is to modify the communication of
each thread between a requester and another file. The typical purpose of a
LINE^HANDLER is to allow each thread to use a shared resource without allowing the
threads to interfere with each other.
The GDSX program demonstrated in this section includes a LINE^HANDLER
procedure that manages communication of multiple requester processes with the same
resource, a terminal. (Section 4, DEVICE^HANDLER Example, Running and
Managing and Section 5, DEVICE^HANDLER Example, Design use the same program
but do not call the LINE^HANDLER procedure.) Figure 6-1 shows the environment for
this example.
Figure 6-1. Environment of the LINE^HANDLER Example
$GDS
D^H
$A1
T1
$A2
T2
L^H
LX
$TC1
$A3
T3
D^H
IOCB
Queue
VST022.vsd
$A1, $A2, and $A3 are requester processes, each of which communicates
simultaneously with the same file (a terminal) by way of GDSX. T1, T2, and T3 are
DEVICE^HANDLER tasks, and LX is a LINE^HANDLER task.
Extended General Device Support (GDSX) Manual—529931-001
6 -1
LINE^HANDLER Example, Running and Managing
Running the LINE^HANDLER Example
This section of the tutorial requires three terminals designated the TACL terminal, the
SCF terminal, and the application terminal. It is assumed that the terminals will be
accessed by way of the TERMPROCESS IOP.
Running the LINE^HANDLER Example
This example uses the same APPL and GDSE object files generated in Section 4,
DEVICE^HANDLER Example, Running and Managing. Although the LINE^HANDLER
was not called in the exercises in Section 4, DEVICE^HANDLER Example, Running
and Managing and Section 5, DEVICE^HANDLER Example, Design, a customized
LINE^HANDLER procedure is included in the GDSE object file.
At the TACL terminal, use CLEAR ALL if necessary to clear any previously set
parameter values, and then assign the value 1 to the configuration parameter
MAXLINES:
> PARAM MAXLINES 1
This indicates to the GDSX process that at most one LINE^HANDLER task will be
created. If MAXLINES is set to zero as in Section 4, DEVICE^HANDLER Example,
Running and Managing and Section 5, DEVICE^HANDLER Example, Design, the
LINE^HANDLER cannot be run.
Assign the value 1 to the configuration parameter EXTSUSIZE:
> PARAM EXTSUSIZE 1
This is necessary because of application-specific changes to the device control block
declaration. (See EXTSUSIZE on page 2-59.)
Then run your new GDSX process:
> RUN GDSE /NAME $GDS, NOWAIT/
This GDSX process includes a LINE^HANDLER that allows multiple requesters to
queue for access to a single asynchronous terminal. To see whether the GDSX
process has been started, enter the following:
> STATUS *, TERM
Preconfiguring the LINE and Subdevices
At the SCF terminal, log on and start SCF:
> SCF
Then enter a SETPROMPT command to cause SCF to display, as part of the prompt,
any object type and name currently being assumed:
-> SETPROMPT OBJECT
Now enter an ASSUME command to define the object type and name:
-> ASSUME PROCESS $GDS
Extended General Device Support (GDSX) Manual—529931-001
6 -2
LINE^HANDLER Example, Running and Managing
Preconfiguring the LINE and Subdevices
After the ASSUME command executes, the SCF prompt includes the object type and
process name. Now enter a STATUS command:
PROCESS $GDS # -> STATUS
The STATUS command tells you that there are two TSCODE system tasks running,
and no USCODE user tasks running.
Now ADD a LINE object (a logical LINE) called $GDS.#LX with an access name of the
device name of your application terminal. The ACCESSNAME attribute tells TSCODE
what device to open when it starts the LINE $GDS.#LX. To add the LINE, enter:
PROCESS $GDS # -> ASSUME LINE #LX
PROCESS $GDS # -> ADD, ACCESSNAME $TC1
This defines a LINE object to TSCODE. Now enter:
PROCESS $GDS # -> INFO, DETAIL
Note the access name. Then enter:
PROCESS $GDS # -> STATUS, DETAIL
Note that the state of the LINE is stopped. The LINE task number is 0, indicating that a
LINE^HANDLER task has not yet been created to manage the LINE object configured.
Now define three SU objects with names T1, T2, and T3, such that each subdevice is
under the LINE $GDS.#LX:
PROCESS $GDS # -> ADD SU T1
PROCESS $GDS # -> ADD SU T2
PROCESS $GDS # -> ADD SU T3
Check their state and the state of the LINE with:
PROCESS $GDS # -> STATUS, SUB ALL
PROCESS $GDS # -> INFO, DETAIL
The state of the SU objects is stopped, meaning that although the SU objects have
been configured, there are no corresponding DEVICE^HANDLER tasks. All SU
objects are defined under the LINE object, and therefore are accessed by way of $TC1
(the LINE object access name).
Now START the LINE object and check its status:
PROCESS $GDS # -> START
PROCESS $GDS # -> STATUS, DETAIL
The state is started. The task number is 3, indicating that a LINE^HANDLER task was
created when the LINE object was STARTed. (In addition to starting the LINE object,
TSCODE opened the $TC1 device specified by the LINE object access name.)
Enter:
PROCESS $GDS # -> STATUS PROCESS $GDS
Extended General Device Support (GDSX) Manual—529931-001
6 -3
LINE^HANDLER Example, Running and Managing
Running an Application Process
The STATUS command tells you that there are two TSCODE system tasks, and one
USCODE user LINE task. Enter:
PROCESS $GDS # -> STATUS SU T1, DETAIL
The task number is 0, indicating that a DEVICE^HANDLER task has not yet been
created to manage the T1 subdevice preconfigured. Enter:
PROCESS $GDS # -> STATUS SU *, DETAIL
The wild-card character (*) directs the STATUS command to give information about all
SU objects under the LINE object.
Running an Application Process
The application terminal is used for input to and output from the example application.
Log on at the application terminal, assumed to have device name $TC1. Pause the
TACL process with the PAUSE command. Pausing the TACL process allows the
application process to control the terminal.
At the TACL terminal, start a requester application, named $A1 in this example:
> RUN APPL /NAME $A1, OUT $GDS.#LX.T1, NOWAIT/
This process must be run after the GDSX process has been started so that I/O from
this process can pass through GDSX. $A1 opens the specified OUT file. GDSE
examines the open message and determines that T1 is configured under the line
$LX, opens subdevice T1, creates a DEVICE^HANDLER task to manage
communication to T1, and notifies the LINE^HANDLER task that the SU is open.
Messages sent to T1 are routed to the DEVICE^HANDLER task, and then passed to
the LINE^HANDLER task, which sends the messages on to device $TC1, specified by
the access name for the LINE object.
The application terminal should now show a prompt sent by the application program
through the GDSE process. The prompt contains the CPU number and PIN of the
application program. From the TACL prompt you may enter:
> STATUS *, TERM
to verify this.
At the SCF terminal, enter:
-> STATUS PROCESS $GDS
The STATUS command tells you that now there are two TSCODE system tasks, and
two USCODE user tasks, a DEVICE^HANDLER task and a LINE task.
Enter:
-> STATUS, SUB ALL
The state of both T1 and LINE object is STARTED, meaning that DEVICE^HANDLER
and LINE^HANDLER tasks exist. Both T1 and the LINE object have 1 open.
Extended General Device Support (GDSX) Manual—529931-001
6 -4
LINE^HANDLER Example, Running and Managing
Running More Application Processes
The GDSX process, named $GDS, did its initialization processing and issued a
READUPDATE on $RECEIVE. Then the application program, named $A1, did its
initialization processing and issued a call to OPEN $GDS.#LX.T1. After TSCODE
received the OPEN, the SU T1 was opened, a DEVICE^HANDLER task was created
to manage communication to T1, and the LINE^HANDLER task was notified that the
SU was opened.
$GDS called REPLY with a completion code, indicating that the application’s OPEN for
$GDS.#LX.T1 was successful. After checking the condition code, the application
program issued a WRITEREAD to $GDS.#LX.T1, writing the prompt containing its own
CPU number and PIN. $GDS scanned the prompt text for characters to be converted
before issuing a WRITEREAD of the converted text to $TC1. (The datastream
conversion is discussed in Section 5, DEVICE^HANDLER Example, Design) Finally,
the IOP wrote the prompt to the screen and waited for input. Section 7,
LINE^HANDLER Example, Design discusses the functioning of the LINE^HANDLER
task in this message flow.
At the application terminal, enter a few text strings in response to the prompts, and
observe what happens. The strings should be uppercase text and in reverse order.
The input string read by the IOP was passed to $GDS, and then on to $A1, which
reversed the sequence of characters in the string. $A1 then issued a call to WRITE
the reversed string to $GDS.#LX.T1. After changing lowercase text to uppercase text,
$GDS issued a WRITE to terminal $TC1, and the IOP displayed the reversed string.
After checking the condition code for its WRITE, $GDS REPLYed to $A1, which then
sent another prompt to the terminal by way of GDSX. The processing is as depicted in
Figure 4-4 on page 4-10.
Running More Application Processes
At the TACL terminal, run two more requesters, again from program file APPL. These
processes will direct their output to logical subdevices T2 and T3, both under LINE
$LX, which is mapped by access name to application terminal $TC1:
> RUN APPL /NAME $A2, OUT $GDS.#LX.T2, NOWAIT/
> RUN APPL /NAME $A3, OUT $GDS.#LX.T3, NOWAIT/
Enter:
> STATUS *, TERM
Note the CPU and PIN values for the new requester processes $A2 and $A3.
At the SCF terminal, enter:
-> STATUS PROCESS $GDS
The STATUS command tells you that there are two TSCODE system tasks, and four
USCODE user tasks.
-> STATUS, SUB ALL
Extended General Device Support (GDSX) Manual—529931-001
6 -5
Running More Application Processes
LINE^HANDLER Example, Running and Managing
All four user tasks are started. The SU objects have one open each and the LINE
object has three opens, one for each SU.
At the application terminal, enter at least three more text strings and observe the
rotation sequence of the prompts. The three requesters direct their output to logical
subdevices T1, T2, and T3, all of which are mapped to physical device $TC1 under
logical LINE $GDS.#LX.
At the SCF terminal, enter:
-> STOP SU Tn
where Tn is one of the two defined subdevices, T2 or T3, that is not currently
prompting on the application terminal. You should get the following message,
indicating that the SU has an opener ($An), and therefore cannot be stopped.
-> GDS E00011 STOP failed:
Object is currently active
Then issue the following SCF command for the same subdevice:
-> ABORT SU Tn
You should get no message in response. Then enter:
-> STATUS SU Tn, DETAIL
This STATUS commands shows that the SU is stopped, and there is no corresponding
task (task number equal to 0). The processing that occurred is described under The
USER^STOP Procedure on page 5-19, except that because here dcb.lineno is equal to
1, a message is not written to the terminal (a message would only interrupt the thread
currently displaying a prompt).
At the TACL terminal, enter:
> STATUS *, TERM
Requester process $An should not appear. If you try entering text strings at the
application terminal, you should only get prompts from the remaining two requesters.
At the SCF terminal, enter:
-> STATUS SU *
The display indicates that the SU Tn still exists in the stopped state, with no opens.
Now stop the SU Tm that is currently prompting on the application terminal:
-> ABORT SU Tm
On the application terminal, after the CPU and PIN prompt, you should see the
message:
D^H TASK STOPPED
followed by the prompt from the remaining requester application. At the SCF terminal,
enter:
-> STATUS, SUB ALL
Extended General Device Support (GDSX) Manual—529931-001
6 -6
LINE^HANDLER Example, Running and Managing
Running More Application Processes
The STATUS command display should show that one SU and the LINE object are
open and started, and Tn and Tm are stopped with no opens.
At the application terminal you may verify that only one requester process is sending
prompts to the terminal. Then press CTRL/Y to stop this process. You can press the
Break key to get a TACL prompt at the application terminal.
At the SCF terminal, enter:
-> STATUS, SUB ALL
The STATUS command display should show that the LINE object is started with no
opens, while the SU objects are all stopped with no opens.
Then enter:
-> STOP PROCESS $GDS!
-> EXIT
The GDSX process is stopped and you exit from SCF.
At the TACL terminal, confirm that the GDSX process is gone by entering:
> STATUS *, TERM
Clear the values set by the PARAM commands by entering CLEAR ALL.
Extended General Device Support (GDSX) Manual—529931-001
6 -7
LINE^HANDLER Example, Running and Managing
Running More Application Processes
Extended General Device Support (GDSX) Manual—529931-001
6 -8
7
LINE^HANDLER Example, Design
The previous section described how to run and manage a LINE^HANDLER example
program. This section contains a description of the environment of an executing
LINE^HANDLER task and an analysis of the design of the LINE^HANDLER example,
including the typical structure used by a LINE^HANDLER task for communication with
the DEVICE^HANDLER tasks and the IOP.
Environment of an Executing LINE^HANDLER
Task
The LINE^HANDLER example program has customized DEVICE^HANDLER,
LINE^HANDLER, and USER^STOP procedures. The DEVICE^HANDLER and
USER^STOP procedures in this example are identical to the DEVICE^HANDLER and
USER^STOP procedures described in the example of Section 4, DEVICE^HANDLER
Example, Running and Managing and Section 5, DEVICE^HANDLER Example,
Design.
The DEVICE^HANDLER tasks perform datastream conversion. The function of the
LINE^HANDLER task is to manage communication to the shared resource, a terminal
in this example, so that the requester threads do not interfere with each other.
Figure 7-1 illustrates the tasks in this example’s environment. (D^H represents a
DEVICE^HANDLER task and L^H represents a LINE^HANDLER task.)
In the previous section’s exercise, after the GDSX process was run, SCF was used to
configure a LINE object. The LINE is configured before the SU objects, because the
SU objects must be configured under the LINE object. Then three SU objects were
configured under the LINE, and the LINE object was started.
When the LINE was started, TSCODE opened the line file $TC1, in this case given by
the access name, and assigned to the file a file number to be used by the
LINE^HANDLER task to address the file. The number assigned is the actual Guardian
file number for the device.
TSCODE also created a $RECEIVE-like file with a file number for the LINE^HANDLER
task to use when picking up messages from the DEVICE^HANDLER tasks. TSCODE
then called the LINE^HANDLER procedure, thereby creating a LINE^HANDLER task
to manage the LINE object. Two parameters supplied when calling the procedure
were line^file^num and in^queue^file^num.
When a requester process was started, TSCODE determined that the SU to be opened
was under a line, opened the specified SU, and notified the LINE^HANDLER task that
the SU had been opened. A file number was then assigned for use by the
DEVICE^HANDLER task (which was about to be created) when communicating with
the terminal to which it would be mapped. Because T1 was configured under a LINE
object, the file number assigned was an ITC file number.
Extended General Device Support (GDSX) Manual—529931-001
7 -1
Environment of an Executing LINE^HANDLER Task
LINE^HANDLER Example, Design
Figure 7-1. LINE^HANDLER Run-Time Environment
$GDS
TSCODE
D^H Task
Requester
Requester
$RECEIVE
D^H Task
IN^QUEUE^
FILE^NUM
L^H Task
0
LINE^
FILE^
NUM
Requester
D^H Task
Monitor
Listener
VST023.vsd
ITC file numbers are not actual Guardian file numbers, but values assigned by
TSCODE to DEVICE^HANDLER tasks whose messages are to be routed to
associated LINE^HANDLER tasks. See Figure 7-3 for an illustration of
LINE^HANDLER message flow. When TSCODE receives an I/O request from a
DEVICE^HANDLER task, it examines the file number in the variable term^file^num. If
term^file^num is a Guardian file, the I/O request is sent directly to the IOP. However, if
the file number is an ITC file, the request is sent to the associated LINE^HANDLER
task.
Thus in this example, term^file^num represents a thread from the DEVICE^HANDLER
task through the ITC file to the LINE^HANDLER task, and then to the terminal.
DEVICE^HANDLER tasks are unaware of LINE^HANDLER tasks and intertask
communication with LINE^HANDLER tasks. The DEVICE^HANDLER sends
messages to term^file^num, just as it would if there were no LINE^HANDLER, and
TSCODE handles the routing of the message to the LINE^HANDLER.
In Section 6, LINE^HANDLER Example, Running and Managing, after a terminal file
number was assigned, TSCODE called the DEVICE^HANDLER procedure, creating a
DEVICE^HANDLER task and passing the terminal file number as a parameter. The
task read from, and replied to, incoming messages by way of a pseudo-$RECEIVE file
(with GDSX internal file number 0), which TSCODE automatically opened for the task
just before creating the task.
Extended General Device Support (GDSX) Manual—529931-001
7 -2
LINE^HANDLER Example, Design
Intertask Communication—LINE^HANDLER
Perspective
The layer of software called pseudo procedures Section 4, DEVICE^HANDLER
Example, Running and Managing and Section 5, DEVICE^HANDLER Example,
Design on the DEVICE^HANDLER example is also used with LINE^HANDLER tasks.
Both DEVICE^HANDLER and LINE^HANDLER tasks should avoid directly calling the
Guardian file-system I/O procedures, because if any user task initiated a waited
operation, processing for all other tasks would also be suspended, disrupting
multithreaded operation.
See Figure 7-2 for an illustration of how a WRITEREAD request is handled in a typical
GDSX process with a LINE^HANDLER. In this figure, text that crosses the line
between the “D^H TASK“ and “L^H TASK“ columns applies to TSCODE, not to the
DEVICE^HANDLER or LINE^HANDLER. Note that each interprocess request
submitted by the application requester that results in an I/O operation implemented by
the DEVICE^HANDLER does not go directly to the terminal. The I/O operation is sent
first to the LINE^HANDLER task associated with the terminal.
Intertask Communication—LINE^HANDLER
Perspective
This example is more complex than the DEVICE^HANDLER example, because a
LINE^HANDLER must be multithreaded, simultaneously handling several types of
events. For example, a LINE^HANDLER might handle I/O to the LINE, intertask
communication with DEVICE^HANDLER tasks, resource availability messages,
messages passed directly from $RECEIVE by TSCODE, and cancellation messages
from TSCODE. In addition, to handle these asynchronous events efficiently, a
LINE^HANDLER cannot use the ^AWAITIO[X] procedure, which would test only for I/O
completions.
Instead of using ^AWAITIO[X], a LINE^HANDLER task checks for I/O completions and
other events with the WAIT^EVENT procedure. WAIT^EVENT returns an indication of
the type of event that occurred. The ^LISTEN procedure may be used to get the
address of any associated IOCB, which in turn can be used to locate the message
buffer (as was done in the previous section’s control block tracing exercise). TSCODE
does not move data from an IOCB to a message buffer when WAIT^EVENT is called
as it does when ^AWAITIOX(DOLR^RCV, ...) is called after a call to ^READUPDATE
in a DEVICE^HANDLER .
Extended General Device Support (GDSX) Manual—529931-001
7 -3
Intertask Communication—LINE^HANDLER
Perspective
LINE^HANDLER Example, Design
Figure 7-2. Sending a WRITEREAD Through a LINE^HANDLER (page 1 of 2)
Application
A WRITEREAD
is sent to GDSX.
L^H Task
D^H Task
TSCODE identifies which D^H task should handle the request..
IOP/Terminal
TSCODE checks to see whether a ^READUPDATE has been
issued by the D^H task. ( The issuing of ^READUPDATE
makes it possible to receive incoming messages.)
NO
YES
TSCODE queues this request. (D^H task receives this
message when it issues a ^READUPDATE.)
Because a ^ READUPDATE has been issued, TSCODE notifies
the D^H task of the pending message by calling WAKE^TASK,
and forwards the message to the D^H task for processing.
The USCODE D^H task performs
datastream conversion.
The D^H task issues a ^WRITEREAD
and an ^AWAITIO to wait for
completion of the ^WRITEREAD.
TSCODE identifies which L^H task should handle the request.
TSCODE checks to see whether a ^READUPDATE has been
issued by the lL^H task.
NO
YES
TSCODE queues this message. (The L^H task receives this
message when it issues a ^READUPDATE.)
TSCODE notifies the L^H task of the pending message by calling
WAKE^TASK, and forwards the message to the L^H task of
processing.
VST024.vsd
Extended General Device Support (GDSX) Manual—529931-001
7 -4
Intertask Communication—LINE^HANDLER
Perspective
LINE^HANDLER Example, Design
Figure 7-2. Sending a WRITEREAD Through a LINE^HANDLER (page 2 of 2)
Application
D^H Task
L^H Task
IOP/Terminal
The L^H task detects the intertask
request and then issues a
^WRITEREAD to send the data to the
terminal (line).
The L^H task can continue to process
other requests, but checks for the I/O
completion event.
TSCODE receives the I/O completion message, identifies which L^H task
the message is for, and uses WAKE^TASK to pass it to the L%H task for
processing.
Data goes to
the IOP and is
sent to the
terminal (line).
The I/O
completion
message is
sent.
The L^H task locates the IOCB
belonging to the original request and
calls NOTIFY^IO^COMPLETION
NOTIFY^IO^COMPLETION causes TSCODE to execute a
WAKE^TASK and pass the information on to the D^H task.
The D^H task sends a response to
the application by calling ^REPLY.
Requester
receives
response.
VST029.vsd
When the WAIT^EVENT procedure is called, control is transferred to TSCODE, which
checks to see whether certain events have occurred. The events checked for are
specified in a bit-encoded mask passed to TSCODE along with a timeout parameter.
When one of these specified events occurs, TSCODE returns an indicator of the event
type.
Extended General Device Support (GDSX) Manual—529931-001
7 -5
Intertask Communication—LINE^HANDLER
Perspective
LINE^HANDLER Example, Design
The event descriptions and the global literals (declared in DCCBDECS (EVENTS))
used by TSCODE to define the events are given in Table 7-1. Events having an IOCB
associated with them are marked in the fourth column.
Table 7-1. Events Detected With WAIT^EVENT
Literal
Constant
Associate
d IOCB
Event Description
Literal Identifier
No event: timeout occurred
E^TIMEOUT
0
Request that L^H call STOP^TASK
E^STOP
1
Resume processing
E^CONTINUE
2
Intertask message or I/O canceled
E^CAN
3
X
Message arrived from $RECEIVE
E^IMSG
4
X
Intertask message arrived
E^ITC
5
X
Completion of I/O other than $RECEIVE and
intertask message
E^IOC
6
X
Resource is available
E^RESOURCE
7
Device added, deleted, altered, started, or
stopped
E^CHANGE
8
After TSCODE passes a value to the LINE^HANDLER task to indicate what event
occurred, if the event has an IOCB associated with it, the task can call ^LISTEN to get
a pointer to the IOCB. To get the IOCB pointer for a message from a
DEVICE^HANDLER task, use the statement:
@IOCB := ^LISTEN (0, 0, 1);
The third parameter value of 1 indicates an intertask communication.
To get the IOCB pointer for a message passed by TSCODE directly from $RECEIVE,
use the statement:
@IOCB := ^LISTEN (1, 0, 0);
The first parameter value of 1 indicates a message from $RECEIVE.
To get the IOCB pointer for an I/O completion on a file, use the statement:
@IOCB := ^LISTEN (0, i-o-message, 0);
where a nonzero i-o-message is interpreted as a file number from TSCODE for
which the procedure is to look for completed I/Os. A value of -1 for i-o-message
indicates that ^LISTEN looks for all completed I/Os except those for intertask requests
and messages from $RECEIVE.
A method for getting the IOCB for a canceled request is discussed in the next
subsection.
Extended General Device Support (GDSX) Manual—529931-001
7 -6
LINE^HANDLER Example, Design
Transaction Flow
NOTIFY^IO^COMPLETION[X] is a procedure commonly used to complete I/O
operations in a task. A task calls this procedure to notify a DEVICE^HANDLER task
that an intertask request is complete.
All DEVICE^HANDLER tasks may have intertask requests outstanding at the same
time. The LINE^HANDLER task must manage communication of these requests to a
shared file (a terminal in this example) so that the threads do not interfere with each
other. The LINE^HANDLER task may queue the requests that come in and track any
request outstanding on the file so that when the request completes, a reply by way of
NOTIFY^IO^COMPLETION[X] returns the response’s IOCB address to the right
DEVICE^HANDLER task.
To the DEVICE^HANDLER the completion appears to be a standard file-system I/O
completion, with data returned in the buffer specified when the I/O was initiated and
standard Guardian condition codes set.
Transaction Flow
Before the basic structure of the LINE^HANDLER code is described, consider the
normal thread, or sequence of actions that occur for a complete transaction
(WRITEREAD-WRITE) initiated by an APPL requester application.
TSCODE passes the request to the DEVICE^HANDLER task handling the SU
specified by the requester. The DEVICE^HANDLER does datastream conversion and
sends a ^WRITEREAD to the terminal file number, as shown in Figure 7-3.
Extended General Device Support (GDSX) Manual—529931-001
7 -7
Transaction Flow
LINE^HANDLER Example, Design
Figure 7-3. LINE^HANDLER Example Message Flow
D^H Task
ITC File
$RECEIVE
Pseudo$RECEIVE
IN^QUEUE^FIL
E^NUM/E^ITC L^H Task
T1
D^H Task
$A1
Pseudo$RECEIVE
#LX
E^IOC
T2
E^TIMEOUT
D^H Task
$A2
Pseudo$RECEIVE
ITC File
WT^IOCB
E^STOP
T3
ITC File
$A3
E^CAN
WT^RD^IOCB
^LIST
E^IMSG
Listener
VST025.vsd
TSCODE intercepts the message, determines that terminal file number is an ITC file
number, and passes the message to the ITC file for the appropriate LINE^HANDLER
task (in this example there is only one LINE^HANDLER task), which detects it as an
intertask message (E^ITC) when it calls WAIT^EVENT. Then the task calls ^LISTEN
to get the address of the IOCB for the message (@dh^iocb := ^LISTEN (0, 0, 1)).
When data is picked up from the IOCB, it is determined that the operation is a
^WRITEREAD, and a pointer to the IOCB is placed on a ^WRITEREAD IOCB queue,
where it remains until the transaction’s WRITE of the reversed string has been
completed. If the LINE file is free, a nowait ^WRITEREAD (the CPU, PIN prompt) is
sent to the LINE file (a terminal, in this case). A ^READUPDATE is posted on the in
queue referenced by the variable in^queue^file^num, so that another intertask
message can be picked up from the DEVICE^HANDLER task.
When the ^WRITEREAD completes, WAIT^EVENT detects the completion (E^IOC).
The task then calls ^LISTEN to get a pointer to the LINE IOCB (line^iocb, allocated by
TSCODE after the ^WRITEREAD is initiated) containing information about the
completion. Relevant fields in the line^iocb, including the text string input by the user
Extended General Device Support (GDSX) Manual—529931-001
7 -8
LINE^HANDLER Example, Design
Transaction Flow
at the prompt, are transferred to the original dh^iocb, and the task then calls
NOTIFY^IO^COMPLETION, which sends a message to the DEVICE^HANDLER task
that sent the request, notifying it of the completion. (This message looks like a
standard Guardian I/O completion to the DEVICE^HANDLER task.)
Then the LINE^HANDLER task calls DEALLOCATEIOCB to release the LINE object
IOCB that was allocated by TSCODE. Even though TSCODE allocates the LINE IOCB
, TSCODE depends on the LINE^HANDLER task to deallocate it, because only the
LINE^HANDLER task can determine when the information in the line^iocb is no longer
useful.
The DEVICE^HANDLER task passes the response back to the requester application,
which reverses the string and sends a WRITE request to the terminal through GDSE.
TSCODE passes the request to the same DEVICE^HANDLER task as before, and the
task does datastream conversion on the string and then issues a ^WRITE to the
terminal file number.
Once again TSCODE intercepts the request, determines that the terminal file number
is an ITC file number, and sends the request to the ITC file for the corresponding
LINE^HANDLER task, which detects it as an intertask message (E^ITC) when it calls
WAIT^EVENT. Then the task calls ^LISTEN to get the address of the IOCB for the
message (@dh^iocb := ^LISTEN (0, 0, 1)).
When data is picked up from the IOCB, it is determined that the operation is a
^WRITE, and a nowait ^WRITE (the reversed string) is immediately sent to the
terminal. The ^WRITE may be sent because requester design ensures that a
completed WRITEREAD of the string input at the prompt for the same thread preceded
the ^WRITE; and because after a WRITEREAD to the terminal has been initiated but
before the transaction has been completed, the LINE^HANDLER queues all I/O
(^WRITEREADs starting other threads) picked up with WAIT^EVENT until a ^WRITE
(assumed to be for the same thread) is received.
Once a thread displays its prompt at the terminal, it keeps control of the terminal until
its transaction is completed with the display of a reversed string. A ^READUPDATE is
posted on the queue assigned in the variable in^queue^file^num, so that another
intertask message can be picked up from the DEVICE^HANDLER task.
When the ^WRITE completes, WAIT^EVENT detects the completion (E^IOC). The
task then calls ^LISTEN to get a pointer to the LINE IOCB (line^iocb, allocated by
TSCODE after the ^WRITE is initiated) containing information about the completion.
The relevant error code in the LINE IOCB is transferred to the original dh^iocb, and the
task then calls NOTIFY^IO^COMPLETION, which sends a message to the
DEVICE^HANDLER task that sent the request, notifying it of the completion.
Then the pointer to the transaction’s ^WRITEREAD IOCB is taken off the queue, and if
there is another thread’s ^WRITEREAD on the queue, it is sent to the LINE file. The
LINE^HANDLER task calls DEALLOCATEIOCB in order to release the LINE IOCB that
was allocated by TSCODE.
The DEVICE^HANDLER task receives the reply that its ^WRITE has completed, and
passes the error code on to the requester. The transaction is then complete.
Extended General Device Support (GDSX) Manual—529931-001
7 -9
LINE^HANDLER Example, Design
Basic Structure of LINE^HANDLER Code
Basic Structure of LINE^HANDLER Code
A LINE^HANDLER task starts when TSCODE calls the LINE^HANDLER procedure.
After any necessary initialization processing, the task runs in a continuous loop,
reading from its $RECEIVE-like queue, never doing a RETURN to TSCODE, as shown
in Figure 7-4. TSCODE uses a nonpreemptive type of task scheduling so USCODE
must voluntarily give up control before TSCODE switches to the next ready task.
At different points you may give up control to TSCODE; for example, when you do a
WAIT^EVENT, your task is suspended, but you never actually exit from the
LINE^HANDLER procedure. A LINE^HANDLER task is stopped by TSCODE when
the GDSX process is stopped (see the last commands in Section 6, LINE^HANDLER
Example, Running and Managing) or when TSCODE receives a message from SCF to
stop a LINE object or stop a LINE task with no openers.
This simple LINE^HANDLER is multithreaded. In the loop, the first thing done is a
^READUPDATE (not a Guardian READUPDATE) on the $RECEIVE-like queue with a
file number in the variable in^queue^file^num, which is passed when this task is
created. This queue receives all messages sent from the DEVICE^HANDLER tasks.
Unlike a ^READUPDATE in a DEVICE^HANDLER task, a ^READUPDATE in a
LINE^HANDLER task does not cause TSCODE to put data into a buffer specified in
the call. Data must be accessed by way of the IOCB provided through a call to
^LISTEN.
Extended General Device Support (GDSX) Manual—529931-001
7- 10
Basic Structure of LINE^HANDLER Code
LINE^HANDLER Example, Design
Figure 7-4. Basic Structure of LINE^HANDLER Code
INIT
PROCESSING
^READUPDATE
(IN^Q^FILE)
WHILE (1)
DO
CASE
WAIT^EVENT
E^ITC
E^CAN
E^IOC
@IOCB : =
^LISTEN (...
Send I/O
To Line
^READUPDATE
(IN^Q^FILE)
E^STOP
Find
Cancelled
IOCB
@IOCB : =
^LISTEN (...
CALL
STOP^TASK
Process I/O
Completion
CALL
NOTIFY^IO^
COMPLETION
CALL
NOTIFY^IO^
COMPLETION
Cancel Line
Operation
Release
Line IOCB
^READUPDATE
(IN^Q^FILE)
VST026.vsd
Receipt of an intertask message is one of the events tested for with the CASE
WAIT^EVENT statement (see Figure 7-4). Then a perpetual loop is initiated with logic
to determine what kind of event has happened. A CASE statement tests the event
literal returned from WAIT^EVENT and determines which of four expected events have
occurred. In this example, events tested for are:
•
•
E^ITC, intertask message from DEVICE^HANDLER
E^IOC, I/O completion on a file, most likely the LINE file
Extended General Device Support (GDSX) Manual—529931-001
7- 11
LINE^HANDLER Example, Design
•
•
E^ITC
E^CAN, cancellation of an intertask message
E^STOP, a request to stop this LINE^HANDLER task
These literals are declared in DCCBDECS(EVENTS). See Figure 7-3 on page 7-7.
E^ITC
The E^ITC branch of the CASE statement handles an intertask message detected by
WAIT^EVENT. ^LISTEN is called to get the address of the IOCB for the message. If
the operation type for the request is ^WRITEREAD, the IOCB address is put on a
^WRITEREAD IOCB queue, and if that IOCB is the only one on the queue, the task
knows the LINE object is free, and a ^WRITEREAD is sent to the LINE file.
If the operation type for the request is a ^WRITE, the task knows, because of requester
and LINE^HANDLER design, that the preceding operation on the LINE object was the
corresponding ^WRITEREAD of the requester’s ^WRITEREAD-^WRITE transaction,
and the ^WRITE is sent to the LINE file. After either type of operation is handled,
another ^READUPDATE is posted on the queue addressed by in^queue^file^num.
E^IOC
The E^IOC branch of the CASE statement handles a LINE file I/O completion detected
by WAIT^EVENT. ^LISTEN is called to get the address of the IOCB for the message.
The task assumes that only WRITE or WRITEREAD operations are processed. In
either case, the file-system error code is passed back to the DEVICE^HANDLER task
with a call to NOTIFY^IO^COMPLETION.
If the operation was a WRITEREAD, the IOCB buffer and I/O count are also passed
back. If the operation was a WRITE, the corresponding and preceding WRITEREAD’s
IOCB address is taken off the ^WRITEREAD IOCB queue (because the
^WRITEREAD-^WRITE transaction is complete from the LINE^HANDLER’s
perspective), and if the queue is not empty, a ^WRITEREAD is sent to the LINE file.
Finally, the LINE IOCB is deallocated.
E^CAN
The E^CAN branch of the CASE statement deals with LINE^HANDLER task cleanup
after cancellation of an intertask message by a user exit other than LINE^HANDLER
and DEVICE^HANDLER. In this example it is assumed that only the ^WRITEREAD
sent from a DEVICE^HANDLER task to the LINE file will ever need to be canceled; a
^WRITE would not be outstanding for any appreciable period.
If such a user exit calls ^CANCEL to cancel a ^WRITEREAD, the call is passed to
TSCODE, which is aware of outstanding I/O because of its role as intermediary
between the Guardian file system and the user exits. TSCODE finds the IOCB
associated with the request. If the iocb.state is equal to 2 (io^itc^queued), TSCODE
deallocates the IOCB. If the iocb.state is equal to 6 (io^active), TSCODE links the
IOCB to the LINE^HANDLER task’s TCB and puts the IOCB in a canceled state so that
the LINE^HANDLER task can delete it. TSCODE then sends the LINE^HANDLER
Extended General Device Support (GDSX) Manual—529931-001
7- 12
LINE^HANDLER Example, Design
E^STOP
task an E^CAN event, indicating that an intertask request has been marked as
canceled.
The E^CAN event is detected by this example’s call to WAIT^EVENT. The
CANCEL^ITC SUBPROC is then called. In order to delete the IOCB for the
outstanding ^WRITEREAD to the LINE file, the LINE^HANDLER task needs to find the
IOCB marked for cancellation, but there is no way to use ^LISTEN to find such an
IOCB as there is to use ^LISTEN to find IOCBs for intertask messages, messages
from $RECEIVE, and I/O completion messages. Because this example’s
LINE^HANDLER task maintains a queue of IOCBs representing outstanding
^WRITEREAD requests from the DEVICE^HANDLER tasks, the queue is scanned to
find IOCBs put into a canceled state by TSCODE, and these are released by calling
NOTIFY^IO^COMPLETION. TSCODE recognizes the IOCB passed as belonging to
the canceled request.
Then the LINE^HANDLER task calls ^CANCEL on any WRITEREAD actually sent to
the LINE file. After canceling a WRITEREAD to the LINE file, if there is another
queued request, it is written to the file. Finally, another ^READUPDATE is posted on
the queue addressed by in^queue^file^num.
E^STOP
The E^STOP branch of the CASE statement handles requests from TSCODE to stop
the LINE^HANDLER task. If E^STOP is detected by WAIT^EVENT, the
LINE^HANDLER message buffer is deallocated, and the TSCODE-supported
STOP^TASK procedure is called.
LINE^HANDLER Example Code
A complete listing of source code file USKELEX is in Appendix B. The source and
object files used for this example are exactly the same as those used for the
DEVICE^HANDLER example program.
The customized LINE^HANDLER procedure, while included in USCODE, was never
called in the tutorial of Section 4, DEVICE^HANDLER Example, Running and
Managing and Section 5, DEVICE^HANDLER Example, Design. Customized user
exits for the DEVICE^HANDLER and USER^STOP were described in those sections;
here the LINE^HANDLER code is discussed.
LINE^HANDLER Procedure
There are three parameters passed by TSCODE to the LINE^HANDLER, as shown in
Example 7-1. The first, line^file^num, contains the Guardian file number used for I/O to
the file that this task is to manage. The LINE^HANDLER does not open this file.
When the LINE object is started, TSCODE opens the file, assigns line^file^num for the
task to use, and passes this number as a parameter when the call to LINE^HANDLER
creates the task.
Extended General Device Support (GDSX) Manual—529931-001
7- 13
LINE^HANDLER Example, Design
LINE^HANDLER Procedure
The second parameter is internal^line^no. Each LINE^HANDLER task has exactly one
line control block (LCB) associated with it. The value of internal^line^no is an index
used to find this task’s LCB in the array of LCBs. This is discussed further in the
Inspect exercise later in this section.
The third parameter is in^queue^file^num, which contains a file number for a TSCODEmaintained $RECEIVE-like queue of intertask messages sent to this task from all
DEVICE^HANDLER tasks. The value of n^queue^file^num is equal to (MAXFILES +
1) for every LINE^HANDLER task created.
Example 7-1. LINE^HANDLER Local Declarations
PROC LINE^HANDLER (LINE^FILE^NUM, INTERNAL^LINE^NO, IN^QUEUE^FILE^NUM);
INT LINE^FILE^NUM, INTERNAL^LINE^NO, IN^QUEUE^FILE^NUM;
BEGIN
LITERAL DISP^STOP = %000001,
! EVENT MASKS--THESE LITERALS MAY BE
DISP^ITC = %000020,
! SOURCED IN FROM DCCBDECS
DISP^IOC = %000040,
WT^OP
= 1,
! IOCB.OPTYPE VALUES
WT^RD^OP = 3;
LITERAL LIST^SZ = 15;
! MAX NUMBER OF D^H IOCBS
! WE CAN SAVE
INT(32) .WT^RD^IOCB^LIST[0:LIST^SZ-1]; !ARRAY FOR SAVING IOCBS
! FOR OUTSTANDING WRITEREADS FROM D^H TASKS
INT .EXT DH^IOCB(IOCB^TEMPLATE),
.EXT LINE^IOCB(IOCB^TEMPLATE),
.EXT WT^IOCB(IOCB^TEMPLATE); ! IOCB FOR THE ONE
! OUTSTANDING D^H WRITE
INT OLDEST, NEWEST; ! INDICES FOR WT^RD^IOCB^LIST
INT .EXT MSG^BUF;
INT EVT;
Example 7-1 also shows some literals used for analyzing the two different kinds of
intertask requests that are expected by USCODE. These literals may be sourced in
from the iocb^layout section of DCCBDECS. (See Appendix C, DCCBDECS and
ULHDECSE Listings.)
The variable wt^rd^iocb^list is the queue used to store IOCBs for pending
^WRITEREADs to the LINE file. The queue is a circular list, maintained with an oldest
index that points to the address of the IOCB for which a ^WRITEREAD has been sent
to the LINE file (if one has) and with a newest index that points to the next available
element in the queue. The list is empty if the value of oldest is equal to the value of
newest.
Wt^iocb holds the IOCB for the one possible outstanding ^WRITE operation, and
line^iocb holds the IOCB for the current LINE file operation, whether a WRITE or
WRITEREAD. Msg^buf is the buffer used when sending the WRITE or WRITEREAD.
Decoding Events
Processing in the main procedure was discussed Basic Structure of LINE^HANDLER
Code on page 7-10. Example 7-2 shows the example code.
Extended General Device Support (GDSX) Manual—529931-001
7- 14
LINE^HANDLER Procedure
LINE^HANDLER Example, Design
Example 7-2. Main Entry: Decoding Events
CALL ^READUPDATEX(IN^QUEUE^FILE^NUM);
IF <> THEN CALL DEBUG;
! GET INTERTASK MESSAGE
OLDEST := NEWEST := 0;
@MSG^BUF := GETEXTPOOL(10,1024); ! FROM EXTENDED BUFFER POOL
IF @MSG^BUF = 0D THEN CALL DEBUG;
WHILE (-1) DO
BEGIN
EVT := WAIT^EVENT((DISP^ITC+DISP^IOC+DISP^CAN+DISP^STOP),-1D);
CASE (EVT) OF
BEGIN
E^ITC ->
! INTERTASK MESSAGE RECEIVED FROM A D^H
BEGIN
CALL PROCESS^DH^REQ;
CALL ^READUPDATEX(IN^QUEUE^FILE^NUM);! GET NEXT MESSAGE
END;
E^IOC ->
! LINE I/O COMPLETED
CALL LINE^IO^CMPLT;
E^CAN ->
! ITC OPERATION CANCELED
CALL CANCEL^ITC;
CALL ^READUPDATEX(IN^QUEUE^FILE^NUM);! GET NEXT MESSAGE
E^STOP ->
! TASK STOPPED FROM SCF
CALL STOP^LINE;
OTHERWISE ->
CALL DEBUG;
END;
END;
END;
! CASE
! WHILE
! L^H PROC
Processing Intertask Requests
Example 7-3 shows the code for the PROCESS^DH^REQ subprocedure. Most of this
processing is described under Transaction Flow on page 7-7. Notice that because the
requester applications have been restricted to WRITE and WRITEREAD, only these
two operation types need to be handled in this routine.
Extended General Device Support (GDSX) Manual—529931-001
7- 15
LINE^HANDLER Procedure
LINE^HANDLER Example, Design
Example 7-3. PROCESS^DH^REQ Subprocedure
SUBPROC PROCESS^DH^REQ;
BEGIN
@DH^IOCB := ^LISTEN(0,0,1);
IF @DH^IOCB = 0D THEN RETURN;
! PICK UP REQUEST FROM D^H
CASE DH^IOCB.OPTYPE OF
BEGIN
WT^RD^OP ->
! PUT A NEW WT^RD REQUEST ON THE LIST
BEGIN
WT^RD^IOCB^LIST[NEWEST] := @DH^IOCB;
IF (OLDEST = NEWEST) THEN
! NO OTHER
! WT^RD IS OUTSTANDING
BEGIN
CALL INCR^INDEX(NEWEST);
CALL WT^RD^TO^LINE;
END
ELSE
CALL INCR^INDEX(NEWEST);
END;
WT^OP ->
BEGIN
@WT^IOCB := @DH^IOCB;
! SAVE IOCB FROM WRITE OP
! (REQUESTER DESIGN ENSURES THAT NO MORE THAN
! ONE WILL BE OUTSTANDING)
CALL WT^TO^LINE;
END;
OTHERWISE ->
CALL DEBUG;
END;
END;
! CASE
! SUBPROC
If there is an I/O on the LINE file, there is an IOCB address on the WRITEREAD IOCB
queue. Therefore, if the value of oldest is equal to the value of newest, the queue is
empty, and the LINE file must be free.
INCR^INDEX is a subroutine that simply increments an index to the WRITEREAD
IOCB queue; if the value of the parameter supplied is 14, 0 is returned.
I/O Operations to the LINE File
Example 7-4 shows the code for the WT^TO^LINE and WR^RD^TO^LINE
subprocedures. The WHILE statement deletes from the queue all items with a value of
0, which indicates a canceled request, as discussed in Cancel^ITC Procedure on
page 7-19.
Extended General Device Support (GDSX) Manual—529931-001
7- 16
LINE^HANDLER Example, Design
LINE^HANDLER Procedure
Example 7-4. WT^TO^LINE and WR^RD^TO^LINE Subprocedures
SUBPROC WT^TO^LINE;
BEGIN
INT .EXT BUF^PTR;
@BUF^PTR := WT^IOCB.BUFADDRX;
! MOVE TEXT INTO TASK'S OWN BUFFER
MSG^BUF ':=' BUF^PTR FOR WT^IOCB.IOCNT BYTES;
CALL ^WRITEX(LINE^FILE^NUM,MSG^BUF,WT^IOCB.IOCNT);
IF <> THEN CALL DEBUG;
END;
SUBPROC WT^RD^TO^LINE;
BEGIN
INT .EXT BUF^PTR, .EXT IOCB(IOCB^TEMPLATE);
WHILE ((WT^RD^IOCB^LIST[OLDEST] = 0D) AND ! SKIP CANCELED REQUESTS
(OLDEST <> NEWEST)) DO
CALL INCR^INDEX(OLDEST);
IF (OLDEST = NEWEST) THEN RETURN; ! NO OUTSTANDING REQUESTS
@IOCB := WT^RD^IOCB^LIST[OLDEST];
@BUF^PTR := IOCB.BUFADDRX;
MSG^BUF ':=' BUF^PTR FOR IOCB.IOCNT BYTES;
CALL ^WRITEREADX(LINE^FILE^NUM,MSG^BUF,IOCB.IOCNT,IOCB.CNT);
IF <> THEN CALL DEBUG;
END;
A ^WRITEREAD to the IOP makes use of information in the IOCB pointed to by the
oldest IOCB address on the wt^rd^iocb^list. Here iocb.iocnt specifies the WRITE
count, and iocb.cnt specifies the maximum expected reply length.
The completion of I/O is determined with WAIT^EVENT, instead of with ^AWAITIO as
in the DEVICE^HANDLER.
Completion of LINE I/O
Example 7-5 shows the code for the LINE^IO^CMPLT subprocedure. Most of this
processing is described in Transaction Flow on page 7-7.
The IOCB STRUCT has a TCB address field, tcbaddr, that indicates the
DEVICE^HANDLER task associated with intertask request. Therefore, if the
LINE^HANDLER keeps track of the address of the IOCB for an intertask message, and
completes its processing of the message by calling NOTIFY^IO^COMPLETION with
the same IOCB as a parameter, TSCODE is able to complete the intertask
communication back to the DEVICE^HANDLER task.
When an I/O completes, the IOCB allocated by TSCODE and containing completion
information is called line^iocb. Line^iocb.iocnt contains the number of bytes of data
transferred during the operation. If the operation was a WRITEREAD, the iocnt field
holds the number of bytes read, even though in this operation’s IOCB on the queue,
iocnt holds the number of bytes to be written.
Extended General Device Support (GDSX) Manual—529931-001
7- 17
LINE^HANDLER Procedure
LINE^HANDLER Example, Design
Example 7-5. LINE^IO^CMPLT Subprocedure
SUBPROC LINE^IO^CMPLT;
BEGIN
INT .EXT DH^BUF;
INT .EXT LH^BUF;
@LINE^IOCB := ^LISTEN(0,LINE^FILE^NUM,0);
IF @LINE^IOCB = 0D THEN RETURN;
CASE LINE^IOCB.OPTYPE OF
BEGIN
WT^OP ->
! THE SINGLE OUTSTANDING WRITE OP IS FINISHED
BEGIN
WT^IOCB.ERR := LINE^IOCB.ERR; ! PASS I/O
! PROCESS FS ERR BACK
CALL NOTIFY^IO^COMPLETIONX(WT^IOCB);
CALL INCR^INDEX(OLDEST);
! TAKE THIS WT^RD OFF THE LIST
IF (OLDEST <> NEWEST) THEN ! MORE WT^RDS PENDING
CALL WT^RD^TO^LINE;
END;
WT^RD^OP ->
! OLDEST WT^RD ON LIST IS FINISHED
BEGIN
! AND TEXT HAS BEEN READ AT THE PROMPT
@DH^IOCB := WT^RD^IOCB^LIST[OLDEST];
@DH^BUF := DH^IOCB.BUFADDRX;
@LH^BUF := LINE^IOCB.BUFADDRX;
IF (LINE^IOCB.ERR = 0) THEN
BEGIN
! NORMAL COMPLETION
DH^BUF ':=' LH^BUF FOR LINE^IOCB.IOCNT BYTES;
DH^IOCB.IOCNT := LINE^IOCB.IOCNT;
DH^IOCB.ERR := 0;
END
ELSE
BEGIN
! PASS I/O PROCESS FS ERR BACK TO APPL
DH^IOCB.IOCNT := 0;
DH^IOCB.ERR := LINE^IOCB.ERR;
END;
CALL NOTIFY^IO^COMPLETIONX(DH^IOCB);
END;
OTHERWISE ->
CALL DEBUG;
END;
! CASE
CALL DEALLOCATEIOCB(LINE^IOCB);
END;
! TSCODE ALLOCATED THIS IOCB
! SUBPROC
When a WRITE to the IOP completes, the proper IOCB to return to the
DEVICE^HANDLER task is wt^iocb. When a WRITEREAD to the IOP completes, the
proper IOCB is pointed to by the oldest entry on the wt^rd^iocb^list.
All file-system error handling is to be done by the requester process.
Note that the IOCB associated with a ^WRITEREAD to the LINE file is given by the
oldest element on the wt^rd^iocb^list, and that this IOCB is not removed from the
queue when the ^WRITEREAD completes, but only when the following ^WRITE
completes, ensuring that the ^WRITEREAD-^WRITE transaction is not interrupted by
Extended General Device Support (GDSX) Manual—529931-001
7- 18
LINE^HANDLER Procedure
LINE^HANDLER Example, Design
other threads. When the ^WRITE completes, the IOCB is removed from the queue by
incrementing the oldest index.
Caution. Although TSCODE handles deallocation of IOCBs for intertask communication
completed with NOTIFY^IO^COMPLETION, it will not deallocate LINE IOCBs. If the LINE
IOCB is not deallocated, eventually the GDSX process runs out of IOCBs. The default for the
maximum number of IOCBs is 128.
Cancel^ITC Procedure
Example 7-6 shows the code for the CANCEL^ITC subprocedure. Most of this
procedure is described under E^CAN on page 7-12.
Example 7-6. CANCEL^ITC Subprocedure
SUBPROC CANCEL^ITC;
BEGIN
INT X;
INT .EXT Q^IOCB(IOCB^TEMPLATE);
IF (OLDEST = NEWEST) THEN CALL DEBUG;
! SANITY CHECK
X := OLDEST;
WHILE (X <> NEWEST) DO ! SCAN LIST LOOKING FOR CANCELED IOCBS
BEGIN
@Q^IOCB := WT^RD^IOCB^LIST[X];
IF (Q^IOCB.STATE = IO^CANCELED) THEN ! (NOTE SPELLING)
BEGIN
WT^RD^IOCB^LIST[X] := 0D; ! MARK AS “CANCELED“
CALL NOTIFY^IO^COMPLETIONX(Q^IOCB);
END;
CALL INCR^INDEX(X);
END;
IF (WT^RD^IOCB^LIST[OLDEST] = 0D) THEN
BEGIN
! THE WT^RD OUTSTANDING TO LINE WAS CANCELED
CALL ^CANCEL(LINE^FILE^NUM);
IF <> THEN CALL DEBUG;
MSG^BUF ':=' [“ D^H TASK STOPPED "];
CALL ^WRITEX(LINE^FILE^NUM,MSG^BUF,18);
IF <> THEN CALL DEBUG;
CALL WAIT^EVENT(DISP^IOC,-1D); ! WAIT FOR
! ^WRITE TO COMPLETE
@LINE^IOCB := ^LISTEN(0,LINE^FILE^NUM,0);
IF @LINE^IOCB = 0D THEN CALL DEBUG;
CALL DEALLOCATEIOCB(LINE^IOCB);
CALL WT^RD^TO^LINE; ! ADVANCE TO NEXT QUEUED REQUEST (IF ANY)
END;
END;
! SUBPROC
Before this procedure is called, TSCODE finds the IOCB associated with the canceled
request and puts the IOCB in a canceled state by setting iocb.state equal to
IO^CANCELED. When the LINE^HANDLER task scans the queue of IOCBs, a list
item marked for cancellation is set to 0 to indicate the cancellation. In the
WT^RD^TO^LINE SUBPROC, list items equal to 0 are skipped when the queue is
scanned for the next IOCB address for a ^WRITEREAD.
Extended General Device Support (GDSX) Manual—529931-001
7- 19
LINE^HANDLER Example, Design
Other Procedure Declarations
A ^CANCEL on a ^WRITEREAD outstanding to the LINE file does not suspend the
task and is not completed by an ^AWAITIO. A message is sent with a ^WRITE to
indicate what happened to the prompt.
In an exercise in Section 6, LINE^HANDLER Example, Running and Managing, an SU
was stopped with the SCF ABORT command. The abort message is sent to TSCODE,
which then stops the DEVICE^HANDLER task. Whenever a task is stopped, the
USER^STOP user exit is called by TSCODE. See Figure 5-10 for this code. If the
stopped task, whose TCB address is passed in the call to USER^STOP, is waiting on a
^WRITEREAD, and is indeed a DEVICE^HANDLER task (tcb.state is greater than or
equal to zero and less than or equal to 15), then ^CANCEL is called on the file to which
the task is mapped (tcb.term, which is the same as the DEVICE^HANDLER task’s
terminal file number).
This call cancels the last incomplete operation on the file, the ^WRITEREAD, which in
this case, because the DEVICE^HANDLER effectively uses waited I/O, is also the only
outstanding operation. The ^CANCEL is sent to TSCODE, which finds the IOCB
associated with the request, and puts the IOCB in a canceled state so that the
LINE^HANDLER task can delete it. TSCODE then sends the LINE^HANDLER task
notification of an E^CAN event.
Processing of the E^CAN event is described under “E^CAN“ earlier in this section.
Because the SU was configured under a LINE, dcb.lineno is greater than 0, and no
additional message was written to the LINE file.
Other Procedure Declarations
Other than the LINE^HANDLER, DEVICE^HANDLER, and USER^STOP, all other
user-supplied procedures required by TSCODE, called user exits, are provided as
stubs in USKELEX. See Appendix B, USKELEX and USKELEXC Listings for the
listing.
Inspecting the LINE^HANDLER Example
The purpose of this exercise is to use Inspect for tracing the operation of a
LINE^HANDLER task and to display the contents of control structures relevant to the
task.
This exercise requires three terminals to be designated the TACL terminal, the Inspect
terminal, and the application terminal. Log on to all three terminals.
At the application terminal, pause the TACL process with the PAUSE command.
Suppose for this example that the terminal’s device name is $TC1.
Extended General Device Support (GDSX) Manual—529931-001
7- 20
LINE^HANDLER Example, Design
Inspecting the LINE^HANDLER Example
At the TACL terminal, use CLEAR ALL if necessary to clear any previously set
parameter values, and then issue commands as given in Section 6, LINE^HANDLER
Example, Running and Managing to run a LINE^HANDLER example process:
> PARAM MAXLINES 1
> PARAM EXTSUSIZE 1
> RUN GDSE /NAME $GDS, NOWAIT/
Configure a LINE object and three SU objects, and start the LINE:
> SCF
-> ADD LINE $GDS.#LX, ACCESSNAME $TC1
-> ADD SU $GDS.#LX.T1
-> ADD SU $GDS.#LX.T2
-> ADD SU $GDS.#LX.T3
-> START LINE $GDS.#LX
-> EXIT
Run three requester programs:
> RUN APPL/NAME $Al, OUT $GDS.#LX.Tl, NOWAIT/
> RUN APPL/NAME $A2, OUT $GDS.#LX.T2, NOWAIT/
> RUN APPL/NAME $A3, OUT $GDS.#LX.T3, NOWAIT/
The application terminal should now show a prompt.
At the Inspect terminal, pause the TACL process with the PAUSE command. Suppose
for this example that the terminal’s device name is $TC2.
At the TACL terminal, bring your GDSX process under the control of Inspect by
entering:
> DEBUG $GDS, TERM $TC2
To make the source code visible under Inspect, at the Inspect terminal, enter:
- SOURCE ON
- SCOPE #LINE^HANDLER
- SOURCE
Put a breakpoint at the CASE (EVT) OF statement in the main loop of
LINE^HANDLER. Change SCOPE to the USER^STOP procedure, type “SOURCE”
and set a second breakpoint at the CALL ^CANCEL statement. Resume program
execution.
At the application terminal, enter a short text string followed by a carriage return. This
should force the GDSX process to a breakpoint, which will be displayed at the Inspect
terminal. (The WRITEREAD to the IOP has completed, and the call to WAIT^EVENT
has detected the E^IOC event.)
At the Inspect terminal, use the display command to find the current value of EVT:
- DISPLAY EVT
You can check the literals in the errors section in DCCBDECS to determine what kind
of event occurred.
Extended General Device Support (GDSX) Manual—529931-001
7- 21
LINE^HANDLER Example, Design
Line Control Blocks
Line Control Blocks
Now the line control block (LCB) for the LINE file can be examined. An LCB is the
internal representation of a LINE and is used to manage a LINE^HANDLER task’s
communication with a file. When SCF was used to configure the LINE, TSCODE
assigned an LCB to manage the terminal. When the LINE object was started,
TSCODE created a LINE^HANDLER task that mapped to the LCB.
The LCB contains:
•
•
•
The variable name that contains the name of the LINE object configured with SCF
($LX in this example).
The access name, the name of the file actually opened for the corresponding LINE
($TC1 in this example).
The variable tcbaddr, a pointer to the associated task’s task control block.
ULHDECSE contains USKELEX’s line^template and is included in Appendix C.
The length of an LCB is determined at compile time, unlike the length of a DCB, which
is not established until run time (see Inspecting the DEVICE^HANDLER Example on
page 5-14.) The number of LCBs allocated depends on the MAXLINES configuration
parameter supplied at run time. MAXLINES specifies the maximum number of LINEs
that can be configured simultaneously within a GDSX process (those added with SCF
and not started, plus those added and started).
At startup time, linetbl (in the comman^data section of DCCBDECS) is initialized to
point to the array of LCBs, contained in extended memory. The index into this array is
internal^line^no, which is passed by TSCODE’s call to the LINE^HANDLER to create
the task associated with the LCB.
Display the internal^line^no parameter (line) passed to the LINE^HANDLER by
TSCODE:
-DISPLAY INTERNAL^LINE^NO
Then observe the contents of the LCB:
-DISPLAY LINETBL[line]
The Task Control Block
Record the displayed tcbaddr value (tcb-address). This is the address of the task
control block of the task that is mapped to the LCB.
Verify the LINE’s name and access name by issuing the following commands:
- DISPLAY LINETBL[line].NAME FOR 6 IN ASCII
- DISPLAY LINETBL[line].ACCESSPOINT FOR 10 IN ASCII
Extended General Device Support (GDSX) Manual—529931-001
7- 22
LINE^HANDLER Example, Design
The IOCB
You can display the contents of the LINE^HANDLER’s TCB with the DISPLAY
command:
- DISPLAY (tcb-address) AS TCB^TEMPLATE
Now display the values of the local variables oldest and newest:
- DISPLAY OLDEST
- DISPLAY NEWEST
These are the indexes to the queue of pending ^WRITEREAD IOCBs from
DEVICE^HANDLER tasks. Display the contents of this local array:
- DISPLAY WT^RD^IOCB^LIST
The IOCB
Record the IOCB address indicated by oldest (old-iocb). Look at the contents of
this IOCB with the following command:
- DISPLAY (old-iocb) AS IOCB^TEMPLATE
The buffer address is held in the doubleword variable bufaddrx. Record the value of
bufaddrx (buffer-address).
Now convert the buffer address value to octal with the command:
- DISPLAY (buffer-address) IN OCTAL
and record the displayed value (octal-buffer-address).
Go to low-level Inspect, and display the contents of the text buffer of old-iocb with
the command:
_ A octal-buffer-address, 20
The first four words of the buffer should contain the most recent prompt string
displayed on the application terminal.
Tracing a ^CANCEL
Return to high-level Inspect. Clear the breakpoint in the main loop of LINE^HANDLER:
- LIST BREAKPOINT
- CLEAR 1
Set a new breakpoint at the statement beginning with “IF
(WT^RD^IOCB^LIST[OLDEST]“ in the CANCEL^ITC subprocedure of
LINE^HANDLER by entering:
- SOURCE SEARCH "IF (WT"
- BREAK #line
Then resume program execution.
Extended General Device Support (GDSX) Manual—529931-001
7- 23
LINE^HANDLER Example, Design
Tracing a ^CANCEL
At the TACL terminal, enter SCF and stop the SU whose prompt currently appears on
the application terminal:
> SCF
-> ABORT SU $GDS.#LX.Tn
At the Inspect terminal, you should see that the program encountered the breakpoint at
the CALL ^CANCEL statement.
Display the value of tcb.term (the ITC file number that the DEVICE^HANDLER task
uses for intertask communication):
- DISPLAY TCB.TERM
Resume program execution. This time your process should hit the breakpoint in the
CANCEL^ITC SUBPROC. Display the values of oldest and newest. What is the value
at wt^rd^iocb^list[oldest]? A value of 0 means that the ^WRITEREAD outstanding to
the LINE object was marked as canceled.
Step the program through the remainder of CANCEL^ITC. Observe the output to the
application terminal and the deallocation of the IOCB allocated by TSCODE. Continue
single stepping until a new prompt appears at the application terminal, and then enter
“STOP“ to stop the GDSX process.
At the TACL terminal, exit from SCF:
-> EXIT
Confirm that GDSX and all requester processes are gone. Log off all terminals.
Extended General Device Support (GDSX) Manual—529931-001
7- 24
8
Service Routines
To help with the development of USCODE routines, the following service routines are
supported by TSCODE:
•
•
Utility procedures
Pseudo Guardian, TS/MP, Pathway/iTS, and TMF procedures
By calling one of these routines a user task transfers control to the TSCODE kernel.
TSCODE either carries out the requested processing internally, or passes the
procedure call to the operating system, Pathway/iTS, or TMF. When TSCODE
subsequently wakes up the task to resume execution, control is returned to the task at
the instruction immediately following the procedure call.
Utility Procedures
A list of the utility procedures follows. A bracketed X at the end of or in the middle of a
procedure name indicates that both local-memory and extended-memory procedures
are available. For example, DELETE^[X]ITEM means that the DELETE^ITEM and
DELETE^XITEM procedures are available. The procedures are grouped by function,
bit map control, break handling, and so on, after the list.
ADD^TRACE^DATA
ADD^TRACE^DATA^INT
ALLOCATEIOCB
BIT^MAP
BIT^RESET
BIT^SET
BIT^TEST
BOUNDS^CHECK
CHECK^BUFFER^BOUNDS
^CHECKPOINT
CHANGE^BUFF^OWNER[X]
DEALLOCATEIOCB
DELETE^[X]ITEM
DO^CP
FAULT
GET^CPSEM
GETEXTPOOL
GETEXTPOOLX
GET^ITC^FCB
GETLOCALPOOL
*GET_PROCESS_HANDLE_FROM_NAM
E_
*GET_PROCESS_HANDLES_CPU_
*GET_PROCESS_HANDLES_NODE_
GET^TASK^NAME
GIVEBREAK
GIVE^CPSEM
INIT^[X]LIST
*INIT^SEM
INSERT^[X]ITEM
ITC^OPENX
^LISTEN
*MAKE_PROCESS_HANDLE_NULL_
NOTIFY^IO^COMPLETION[X]
*PROCESS_HANDLE_IS_NULL_
PSEM
PUTEXTPOOL
PUTLOCALPOOL
Q^CP[X]
^RECLAIMBUFFER
SEND^ITC^MSG[X]
^SHUTDOWN
STOP^TASK
TCBADDR
TAKEBREAK
USER^CLOSE^TRACE^FILE
^TERMINATE
USER^OPEN^TRACE^FILE
VSEM
WAITED^IO[X]
WAIT^EVENT
WAKE^TASK
WRITE^ITC^MESSAGE[X]
Extended General Device Support (GDSX) Manual—529931-001
8 -1
Bit Map Control
Service Routines
Utility procedures flagged with an asterisk (*) can be called only if TSCODE recognizes
the application as converted. All other procedures can be called by USCODE, whether
the application is converted or unconverted.
Bit Map Control
You can test TSCODE line maps (CMAP and AMAP) and define and maintain their
own bit maps by means of the following procedures:
BIT^MAP
BIT^RESET
BIT^SET
BIT^TEST
Break Handling
The following procedures are used by a task to take and release break ownership of
the device that the task controls. The break-handling facility is enabled by means of
the BREAKENABLED configuration parameter.
GIVEBREAK
TAKEBREAK
Debugging Facilities
As an aid to debugging, TSCODE supports the trace facility and the FAULT procedure,
by which a task can report a fault and suspend itself.
ADD^TRACE^DATA
ADD^TRACE^DATA^INT
FAULT
USER^CLOSE^TRACE^FILE
USER^OPEN^TRACE^FILE
Fault-Tolerance Facilities
If a backup CPU is specified when the GDSX process is started, persistent operation is
possible without checkpointing by USCODE. In this case, after a switchover TSCODE
starts the backup process, checkpoints TSCODE global data, and restarts from the
beginning each task that was active at the time of the failure. The following facilities
are also supported by TSCODE to allow you to checkpoint user-defined globals, stack
images, and dynamically allocated memory to the backup process:
^CHECKPOINT
DO^CP
GET^CPSEM
GIVE^CPSEM
Q^CP[X]
^RECLAIMBUFFER
Identifier Manipulation
The following procedures manipulate process handles and extract CPU and node
information from process handles. They are called only by converted applications.
Extended General Device Support (GDSX) Manual—529931-001
8 -2
Intertask Communication
Service Routines
GET_PROCESS_HANDLE_FROM_NAME_
GET_PROCESS_HANDLES_CPU_
GET_PROCESS_HANDLES_NODE_
MAKE_PROCESS_HANDLE_NULL_
PROCESS_HANDLE_IS_NULL_
Intertask Communication
TSCODE provides a set of procedures to support communication between TSCODE
and USCODE, as well as communication among user tasks. These procedures make
it possible for a DEVICE^HANDLER task to communicate with a device on a line as if
there were no LINE^HANDLER task involved. They also provide a mechanism for a
LINE^HANDLER to efficiently handle several different types of asynchronous events.
The procedures supported are:
GET^ITC^FCB
ITC^OPENX
^LISTEN
NOTIFY^IO^COMPLETION
WRITE^ITC^MESSAGE[X]
SEND^ITC^MSG[X]
WAIT^EVENT
WAKE^TASK
IOCB Maintenance
The following procedures allow USCODE to acquire and release I/O control blocks for
I/O operations:
ALLOCATEIOCB
DEALLOCATEIOCB
List Manipulation
You can define and maintain linked lists by means of the following procedures:
DELETE^[X]ITEM
INIT^[X]LIST
INSERT^[X]ITEM
Pool Management
Because the working stack images of tasks are swapped to and from an extended data
segment, I/O operations must be performed by means of global buffers, and large
amounts of data local to tasks are best maintained somewhere other than the tasks’
stack images. To facilitate the efficient use of memory by both TSCODE and
USCODE, TSCODE provides local memory pools and extended data segment memory
pools, as well as the following memory pool management procedures:
BOUNDS^CHECK
CHANGE^BUFF^OWNER[X]
CHECK^BUFFER^BOUNDS
GETEXTPOOL
GETEXTPOOLX
GETLOCALPOOL
PUTEXTPOOL
PUTLOCALPOOL
Extended General Device Support (GDSX) Manual—529931-001
8 -3
Semaphore Control
Service Routines
Semaphore Control
The purpose of a semaphore is to ensure the serial access of a shared resource. A
task is considered to have acquired a resource when it owns the semaphore
associated with the resource. A unique user-defined semaphore should be established
for each resource requiring exclusive access.
The following procedures are available for managing semaphores other than the
checkpoint semaphore. The checkpoint semaphore is managed with the GET^CPSEM
and GIVE^CPSEM procedures.
INIT^SEM
PSEM
VSEM
Task Maintenance
The following procedures support various features related to task processing and
shutdown:
GET^TASK^NAME
^SHUTDOWN
STOP^TASK
TCBADDR
^TERMINATE
WAITED^IO[X]
Pseudo Procedures
TSCODE provides you with a set of pseudo procedure calls that, with some
exceptions, have the same parameters, syntax, meaning, and resultant capabilities as
their counterparts. They comprise a layer of TSCODE between USCODE and the
Guardian file system, NonStop server classes, and the TMF that is virtually transparent
to USCODE, providing you with a consistent interface to facilities similar to NonStop
systems.
This layer of software allows TSCODE to keep track of each internal I/O operation and
to ensure that every I/O operation is handled correctly at completion time. Pseudo
procedures determine whether an operation is to be handled completely within GDSX
or is to be handled outside GDSX.
Caution. The pseudo procedure calls must be used instead of their counterparts.
Table 8-1 contains a list of the pseudo procedure calls supported by TSCODE. Many
TSCODE-supported utility procedures do not have Guardian file-system counterparts,
and are not included here. A bracketed X at the end of or in the middle of a procedure
name indicates that both local-memory and extended-memory procedures are
available. For example, ^AWAITIO[X] indicates that the ^AWAITIO and ^AWAITIOX
procedures are available.
Extended General Device Support (GDSX) Manual—529931-001
8 -4
Pseudo Procedures
Service Routines
Table 8-1. Pseudo Procedures (page 1 of 2)
Procedure Name
Causes
Task
to Be
Suspended
*
^ABORTTRANSACTION
Is a
Waited
Operation
Used
Only for
Converted
Tasks
Used
Only for
Unconverted
Tasks
X
^AWAITIO[X]
^BEGINTRANSACTION
X
^CANCEL
^CANCELREQ
^CANCELTIMEOUT
^CLOSE
X
^CONTROL
^DELAY
X
^DEVICEINFO2
X
X
^ENDTRANSACTION
X
^FILE_CLOSE_
X
^FILE_GETINFO_
X
^FILE_GETINFOBYNAME_
X
^FILE_GETRECEIVEINFO_
X
X
X
^FILEINFO
^FILE_OPEN_
X
^FNAMEEXPAND
^LOCKREC
^MYTERM
^NEWPROCESS
X
^OPEN
X
^PROCESS_CREATE_
X
^PROCESS_STOP_
X
X
X
X
^READ[X]
^READLOCK[X]
^READUPDATE[X]
^READUPDATELOCK[X]
*Suspension of a task is the transfer of control to the TSCODE dispatcher, which may then execute a different
task. When the suspended task resumes execution, control is returned to the instruction immediately following the
pseudo call.
^RECEIVEINFO
Extended General Device Support (GDSX) Manual—529931-001
8 -5
X
Pseudo Procedure Syntax
Service Routines
Table 8-1. Pseudo Procedures (page 2 of 2)
Procedure Name
Causes
Task
to Be
Suspended
*
Is a
Waited
Operation
Used
Only for
Converted
Tasks
Used
Only for
Unconverted
Tasks
^REPLY[X]
^RESUMETRANSACTION
X
^SERVERCLASS_DIALOG_ABO
RT_
^SERVERCLASS_DIALOG_BEGI
N_
^SERVERCLASS_DIALOG_END
_
^SERVERCLASS_DIALOG_SEN
D_
^SERVERCLASS_SEND_
^SERVERCLASS_SEND_
INFO_
X
^SETMODE
^SETMODENOWAIT
^SETMYTERM
^SETPARAM
^SIGNALINTERRUPT
^SIGNALTIMEOUT
^UNLOCKREC
^WRITE[X]
^WRITEREAD[X]
^WRITEUPDATE[X]
^WRITEUPDATEUNLOCK[X]
*
Suspension of a task is the transfer of control to the TSCODE dispatcher, which may then execute a different
task. When the suspended task resumes execution, control is returned to the instruction immediately following
the pseudo call.
Pseudo Procedure Syntax
The following pages include syntax descriptions, considerations, and examples for all
the utility and pseudo procedures supported by TSCODE.
Extended General Device Support (GDSX) Manual—529931-001
8 -6
^ABORTTRANSACTION
Service Routines
^ABORTTRANSACTION
This procedure cancels the current TMF transaction associated with the calling user
task. Canceling a transaction assumes that a successful call to
^BEGINTRANSACTION occurred from the user task calling ^ABORTTRANSACTION.
See Appendix D, Using Pseudo Procedures in a TS/MP Environment for an example of
using this procedure.
A trace record is written after a successful call to ^ABORTTRANSACTION if bit 3 of
trace^control^flags in DCCBDECS is set to 1. The trace records contain the calling
task number of the user task and the TMF transaction identifier. See Tracing GDSX on
page 2-80 for more information.
The syntax, condition code settings, and considerations regarding this procedure are
the same as the TMF counterpart in the NonStop TMF Application Programmer’s
Guide.
ADD^TRACE^DATA
If the trace file is open, this procedure collects the specified trace data and copies it
into the trace data pool at the next available address. The
USER^OPEN^TRACE^FILE procedure may be used to open the trace file.
During execution of the following user exits, the GDSX process is not completely
initialized and, therefore, ADD^TRACE^DATA should not be called:
•
•
•
•
PROCESS^ASSIGNS
PROCESS^USER^PARAMS
USER^INIT^CONFIG^PARAMS
USER^VERSION
Once TSCODE has called the USER^INITIALIZE user exit (which is called after
USER^VERSION in either the primary or backup process), USCODE may generate
trace entries by calling ADD^TRACE^DATA or ADD^TRACE^DATA^INT.
Trace entries generated by these procedure calls are merged with any trace entries
that you specify to be generated by TSCODE.
CALL ADD^TRACE^DATA ( type
i
,data1
i
,bytes1
i
,[ data2
,[ data3
,[ data4
,[ data5
,[ data6
!
!
!
,
,
,
,
,
bytes2
bytes3
bytes4
bytes5
bytes6
]
]
]
]
] );
Extended General Device Support (GDSX) Manual—529931-001
8 -7
ADD^TRACE^DATA
Service Routines
input
type
INT:value
is the entry type, which indicates the type of data to be copied. The values for
type are:
0-127
Reserved for TSCODE events
128-255
Used for USCODE events
Except for these restrictions, use of this parameter is completely user-dependent.
Whatever value is assigned to type is passed through to the trace records. For
information on how to dynamically control the tracing of classes of user-defined
events, see Dynamic Control of User-Coded Tracing on page 2-84.
input
datai
INT .EXT:ref
is a pointer containing an address where data copying should begin.
input
bytesi
INT:value
is the length in bytes of the data to be copied starting at datai.
Consideration
Use the SCF HELP command to view trace option settings. For example,
-> HELP GDS TRACE PROCESS
Example
This example illustrates a user-defined trace call that tests the settings of the global
trace^control^flags array:
PROC USER^INITIALIZE(primary);
INT primary;
BEGIN
INT .MBUF;
INT ERR := 0;
IF SR^MISC^TRACE AND (@MBUF := GETLOCALPOOL(0,150)) THEN
BEGIN
IF NOT (ERR := USER^OPEN^TRACE^FILE(512,124,5000D)) THEN
BEGIN
IF primary THEN
MBUF ':=' "USER^INITIALIZE primary successful"
ELSE
MBUF ':=' "USER^INITIALIZE backup successful ";
CALL ADD^TRACE^DATA (SR^MISC^REQ,MBUF,34); !bytes
ERR := USER^CLOSE^TRACE^FILE;
END;
Extended General Device Support (GDSX) Manual—529931-001
8 -8
ADD^TRACE^DATA^INT
Service Routines
CALL PUTLOCALPOOL (0, MBUF);
END;
END;
If the global sr^misc^trace flag (which is the same as trace^control^flags[1].<9>, as
defined in the common^data section of DCCBDECS), is set to 1 before the preceding
code is executed, in addition to the preceding user-defined entries, TSCODE
generates a standard trace entry with a type of sr^misc^req whenever a user exit is
called. For more information on these globals, see the tables in Tracing GDSX on
page 2-80.
ADD^TRACE^DATA^INT
This procedure is exactly like ADD^TRACE^DATA, except that the datai parameter
is an INT:value, containing the address where data copying should begin.
ALLOCATEIOCB
This procedure allocates an I/O control block (IOCB) for an I/O request. Either an
IOCB address or 0 is returned to the calling task. You must deallocate the IOCB after
the I/O is completed. If IOCBs are not deallocated after use, they are inaccessible for
the remainder of the life of the GDSX process.
A task that allocates IOCBs should manage them with a linked list in global memory,
so that if the task is stopped unexpectedly, code in the USER^STOP user exit can
deallocate the IOCBs.
iocb-address := ALLOCATEIOCB ( [ time-out ] );
i
iocb-address
!
returned value
INT(32):value
is an IOCB address if an IOCB was allocated; otherwise this variable is set to zero.
input
time-out
INT(32):value
is the number of ticks (10 ms) to wait for an IOCB to become available. If no
time-out parameter is supplied, the value of the IOCBWAITTIME configuration
parameter is used. IOCBWAITTIME has a default of 1,000 ticks.
Consideration
This procedure may cause the calling task to be suspended.
Extended General Device Support (GDSX) Manual—529931-001
8 -9
^AWAITIO[X]
Service Routines
Example
In this example an IOCB is allocated by USCODE and then deallocated when it is no
longer needed.
INT .EXT IOCB (IOCB^TEMPLATE); !<- Now an INT .EXT
INT timeout := 1000;
! Wait for 10 seconds
INT(32) iocbaddr := 0D;
!<- Now an INT(32)
BEGIN
IF NOT (iocbaddr := ALLOCATEIOCB (timeout)) = 0D THEN
!IOCB acquired from extended memory
BEGIN
@IOCB := iocbaddr;
END;
IF iocbaddr <> 0D THEN
CALL DEALLOCATEIOCB (IOCB); ! No matter what happens
! remember to deallocate the IOCB control block
^AWAITIO[X]
The ^AWAITIO and ^AWAITIOX procedures complete a previously initiated I/O
operation. Use ^AWAITIOX with the extended 32-bit versions of the I/O procedures
such as ^WRITEX and ^WRITEREADX. AWAITIOX also completes calls made to the
16-bit I/O routines.
Except for the following considerations, the syntax, condition code settings, and
considerations regarding these two procedures are the same as the counterparts in the
Guardian Procedure Calls Reference Manual.
Considerations
•
•
^AWAITIO[X] causes the calling task to be suspended.
Nowait I/O operations are completed either with ^AWAITIO[X] or WAIT^EVENT.
WAIT^EVENT is commonly used when you need to detect not only I/O completions
on files, but other events, such as cancellations and notifications of available
resources.
Be careful when you are programming tasks that call both WAIT^EVENT and
^AWAITIO[X], because when the two procedures are used together, ^AWAITIO[X]
can “lose“ events. For example:
INT F1, F2;
.
.
CALL ^WRITE(F1, .... );
.
.
CALL ^WRITE(F2, .... );
Extended General Device Support (GDSX) Manual—529931-001
8- 10
^AWAITIO[X]
Service Routines
CALL ^AWAITIO(F2);
!Complete write to F2
.
.
CALL WAIT^EVENT(DISP^IOC); !Wait for F1 write to complete
.
.
If the ^WRITE to file F1 completes before the ^WRITE to F2, TSCODE’s
implementation of ^AWAITIO calls WAIT^EVENT(DISP^IOC .. ) and awakens on
the resulting IOC event for F1, but, not finding an I/O completion for F2 (by a call to
^LISTEN), will proceed to call WAIT^EVENT(DISP^IOC .. ) again. At this point the
IOC event from the completion of the ^WRITE to F1 has been cleared (see the
description of the WAIT^EVENT on page 8-86). When the WRITE to F2
completes, ^AWAITIO returns, but because the IOC event from the completion of
the ^WRITE to F1 has been lost, the last call to WAIT^EVENT never completes.
This kind of problem can occur if you generate two events of the same priority as
defined by WAIT^EVENT, for example, two DISP^IOC events, two DISP^ITC
events, and so on.
•
•
•
•
•
If you want USCODE to provide calls to ^AWAITIO[X] in order to wait for I/O
completion on ^DEVICEINFO2, ^FILE_GETINFOBYNAME_, and
^PROCESS_CREATE_ service routines, as would be done for typical nowaited
Guardian procedure calls, you must set the PROCNOWAIT configuration
parameter to 1. If you want TSCODE to supply AWAITIO[X] calls to complete
these nowaited I/Os, you set PROCNOWAIT to 0. See the description of
PROCNOWAIT on page 2-70 for more information.
^AWAITIOX does not allow a segment-id parameter.
The tag parameter returns the nowait I/O tag supplied when the I/O was initiated.
If no tag was supplied, -1D is returned.
The buffer-addr parameter returns the address of the buffer on which the I/O
completed. Where ^READUPDATE is called without a buffer parameter, GDSX
allocates a buffer and passes its address to you here. The size of this buffer is the
maximum of the $RECEIVE message size and the maximum reply size for the
request. It is your responsibility to return this buffer through a call on
PUTLOCALPOOL.
When ^AWAITIO[X] is called on the pseudo-$RECEIVE file, a READUPDATE
should be posted against the pseudo-$RECEIVE file. When this is not the case,
an error 26 is returned from ^AWAITIO[X]:
AWAITIO or CANCEL attempted on a file with no outstanding
operations.
USCODE should always check the return condition code for CCL or CCG. If the
condition code is CCE, the ^AWAITIO[X] completed successfully. If CCE is not
returned, USCODE should call ^FILEINFO for further examination.
CALL ^AWAITIO (......);
IF <> THEN
Extended General Device Support (GDSX) Manual—529931-001
8- 11
^BEGINTRANSACTION
Service Routines
BEGIN
CALL ^FILEINFO (......);
IF error = 26 THEN
.
.
^BEGINTRANSACTION
This procedure initiates a new TMF transaction. See Appendix D, Using Pseudo
Procedures in a TS/MP Environment for an example of using this procedure.
A trace record is written after a successful call to ^BEGINTRANSACTION if bit 3 of
trace^control^flags in DCCBDECS is set to 1. The trace records contain the calling
task number and the TMF transaction identifier. See Tracing GDSX on page 2-80 for
more information.
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as given for the TMF counterpart
in the NonStop TMF Application Programmer’s Guide.
Considerations
•
•
This procedure differs from its TMF counterpart by not allowing the transbegin-tag parameter. Even though you may not use this parameter, a transid
for the TMF transaction is returned to TSCODE and is stored in the variable
transtag of tcb^template.
A maximum of 100 concurrent TMF transactions are allowed for any single
multithreaded Guardian process. An attempt to issue more than 100 concurrent
^BEGINTRANSACTION calls is rejected with error 83.
A warning message displays when GDSX is started with more than 100 tasks
configured and the TMF configuration parameter is set to 2. The warning message
is:
10016 Number of tasks exceed limit with TMF
See MAXTASKS on page 2-68.
BIT^MAP
This procedure searches a specified range within a bit map table in either global or
extended memory, and returns the index value for the first bit found that is available
(equal to 0). The search begins with the leftmost bit (number 0) of the first word.
index := BIT^MAP ( table
i
,minimum
i
,maximum );
i
Extended General Device Support (GDSX) Manual—529931-001
8- 12
!
!
!
BIT^RESET
Service Routines
returned value
index
INT:value
is the index value for the first available bit (equal to 0) that is in the specified range.
input
table
INT:ref
(Use for global memory reference.)
INT .EXT:ref
(Use for extended memory reference.)
is a pointer to the bit map table.
input
minimum
INT:value
is the index for the first bit in the range to be tested. This parameter must be
greater than or equal to 0.
input
maximum
INT:value
is the index for the last bit in the range to be tested. This variable must be less
than 32,768.
Example
See USER^STOP on page 9-23 for an example using the BIT^TEST procedure.
BIT^RESET
This procedure resets to 0 the ith bit of a bit map table in either global or extended
memory.
Caution. You must not reset TSCODE-defined map bits.
CALL BIT^RESET ( table
i
,index );
i
!
!
input
table
INT:ref
(Use for global memory reference.)
INT .EXT:ref
(Use for extended memory reference.)
is a pointer to the bit map table.
Extended General Device Support (GDSX) Manual—529931-001
8- 13
BIT^SET
Service Routines
input
index
INT:value
is the index for the bit to be set to 0 (available). The range for this parameter is
specified by: 0 <= index < 32, 768.
BIT^SET
This procedure sets to 1 the ith bit of a bit map table in either global or extended
memory.
Caution. You must not reset TSCODE-defined map bits.
CALL BIT^SET ( table
i
,index );
i
!
!
input
table
INT:ref
(Use for global memory reference.)
INT .EXT:ref
(Use for extended memory reference.)
is a pointer to the bit map table.
input
index
INT:value
is the index for the bit to be set to 1 (not available). The range for this parameter is
specified by: 0 <= index < 32, 768.
BIT^TEST
This procedure tests whether the ith bit is set in a bit map table in either global or
extended memory.
result := BIT^TEST ( table
i
,index );
i
!
!
returned value
result
INT:value
is one of the following values:
-1
The bit indexed by index is 1 (ON)
0
The bit indexed by index is 0 (OFF)
Extended General Device Support (GDSX) Manual—529931-001
8- 14
BOUNDS^CHECK
Service Routines
input
tbl
INT:ref
(Use for global memory reference.)
INT .EXT:ref
(Use for extended memory reference.)
is a pointer to the bit map table.
input
index
INT:value
is the index for the bit to be tested. The range for this parameter is specified by:
0 <= index < 32, 768.
Example
See USER^STOP on page 9-23 for an example.
BOUNDS^CHECK
This procedure ensures a buffer is in global or extended memory, not in the swappable
stack. This procedure is the same as CHECK^BUFFER^BOUNDS except the return
code indicating the outcome of the call to BOUNDS^CHECK is stored in the FCB of the
file specified in the call.
BOUNDS^CHECK ( filenum
,buffer:length );
i:i
! i
!
input
filenum
INT:ref
is the number of the file whose FCB is used to store a returned status code. The
status code value is one of the following:
0
The buffer is valid
22
The buffer is in the swappable user stack
buffer:length
input:input
STRING .EXT:ref:*, INT:value
is a pointer to the buffer to be checked and the length of the buffer in bytes.
^CANCEL
This procedure cancels the oldest incomplete operation on a file opened for nowait I/O.
Extended General Device Support (GDSX) Manual—529931-001
8- 15
^CANCELREQ
Service Routines
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as the counterpart in the
Guardian Procedure Calls Reference Manual.
Considerations
•
•
^READUPDATE and ^CANCEL are the only two operations that a
LINE^HANDLER can issue against the in-queue file.
For information about using ^CANCEL to cancel a ^READUPDATE on a pseudo$RECEIVE file, see the considerations under ^READUPDATE[X] on page 8-61.
^CANCELREQ
This procedure cancels an incomplete operation, identified by a file number and tag, on
a file opened for nowait I/O. When the procedure successfully cancels an operation,
the associated IOCB is deallocated unless the procedure’s third parameter is used.
Except for the following consideration, the syntax, condition code settings, and
considerations regarding this procedure are the same as the counterpart in the
Guardian Procedure Calls Reference Manual.
Consideration
This procedure differs from its counterpart by having a third parameter (iocbaddress) that is used to return the address of the IOCB for the canceled
operation.The procedure is defined as follows:
CALL ^CANCELREQ ( filenum , [ tag ] , [ iocb-address ] ,
[Cancel^Tag ]);
where iocb-address and cancel^tag are INT(32). In case you call
WAIT^EVENT, time out, and want to cancel an outstanding I/O for
a file, this parameter can be used to examine the IOCB.
Caution. If iocb-address is used, USCODE is responsible for deallocating the IOCB.
^CANCELTIMEOUT
This procedure cancels an elapsed-time timer previously initiated by a call to the
^SIGNALTIMEOUT or ^SIGNALINTERRUPT procedure. The IOCB allocated as a
result of the call to ^SIGNALTIMEOUT or ^SIGNALINTERRUPT is deallocated.
Except for the following consideration, the syntax, condition code settings, and
considerations regarding this procedure are the same as the counterpart in the
Guardian Procedure Calls Reference Manual.
Extended General Device Support (GDSX) Manual—529931-001
8- 16
CHANGE^BUFF^OWNER[X]
Service Routines
Consideration
The tag parameter of ^CANCELTIMEOUT holds the address of the IOCB returned
when ^SIGNALTIMEOUT or ^SIGNALINTERRUPT was called. The tag parameter is
an INT(32) variable.
CHANGE^BUFF^OWNER[X]
This procedure gives the ownership of a local/extended buffer pool to another task.
CHANGE^BUFF^OWNER ( buf
,newowner );
buf
! i
! i
input
INT : ref
(Use with CHANGE^BUFF^OWNER)
INT .EXT : ref
(Use with CHANGE^BUFF^OWNERX)
is a pointer to the pool whose ownership is to be changed.
newowner
INT(32) : value
is the TCB address of the task that is to become the new owner of the pool
Condition Code Settings
=
CCE indicates that buffer ownership has changed.
<
CCL indicates that the current task does not own the buffer or the buffer is invalid.
>
CCG indicates either the TCB address of the newowner is invalid or this task is
not active.
CHECK^BUFFER^BOUNDS
This procedure ensures a buffer is in global (user^private) or extended memory, not in
the swappable stack.
status := CHECK^BUFFER^BOUNDS ( buffer:length );
i:i
!
returned value
status
INT:value
indicates the outcome of the call. The value of status is one of the following:
0
The buffer is valid
22
The buffer is in the swappable user stack
Extended General Device Support (GDSX) Manual—529931-001
8- 17
^CHECKPOINT
Service Routines
input:input
buffer:length
STRING .EXT:ref:*, INT:value
is a pointer to the buffer to be checked and the length of the buffer in bytes.
^CHECKPOINT
When GDSX is running as a process pair, this procedure is called by a
DEVICE^HANDLER task or LINE^HANDLER task to send information pertaining to its
current executing state to the backup process. The checkpoint information enables the
backup process to recover from a failure of the primary process.
A call to this function establishes a restart point in the calling task at the return from the
call, in a manner similar to a call to the Guardian CHECKPOINT procedure. Normally,
the procedure returns with a value of zero for status. However, if a failure of the
primary GDSX process occurs, all I/O that the task had outstanding is canceled by
TSCODE, any semaphores held (including the checkpoint semaphore) are released,
the procedure returns a nonzero value, and the task executes the statement following
the last call to ^CHECKPOINT.
For additional information on checkpointing, see Fault Tolerance on page 2-28.
status := ^CHECKPOINT ( type );
i
!
returned value
status
INT:value
indicates the outcome of the call. The value of status is one of the following:
0
The checkpoint was successful
Nonzero Number
There was a takeover by the backup process
input
type
INT:value
specifies the type of checkpoint. The value of type is one of the following:
1
Checkpoint only the stack image and the TCB
2
Checkpoint the task’s stack image, its TCB, and all local and extended
memory that the task currently has allocated by way of GETLOCALPOOL or
GETEXTPOOL
Considerations
•
^CHECKPOINT causes the calling task to be suspended.
Extended General Device Support (GDSX) Manual—529931-001
8- 18
^CLOSE
Service Routines
•
•
After a takeover, memory pool buffers must be allocated by a call to
^RECLAIMBUFFER.
If the checkpoint buffer overflows, the backup process is deleted. To prevent this,
ensure that the MAXCPSIZE configuration parameter is large enough. The default
size is 4096 words. (For restrictions imposed by MAXCPSIZE and TASKCPSIZE,
see MAXCPSIZE on page 2-60 and TASKCPSIZE on page 2-73)
^CLOSE
This procedure closes an open file. ^CLOSE can be called whether USCODE is
converted or unconverted. This procedure is a waited operation.
The syntax, condition code settings, and considerations regarding this procedure are
the same as given for the counterpart in the Guardian Procedure Calls Reference
Manual.
^CONTROL
This procedure performs device-dependent I/O operations.
The syntax, condition code settings, and considerations regarding this procedure are
the same as the counterpart in the Guardian Procedure Calls Reference Manual.
DEALLOCATEIOCB
This procedure deallocates an IOCB when an I/O request is finished. This procedure
also clears the contents of the IOCB.
CALL DEALLOCATEIOCB ( iocb );
i
!
input
iocb
INT .EXT:ref
iocb is a pointer to the IOCB to be deallocated.
Consideration
•
•
See Transaction Flow on page 7-7 for an explanation of how DEALLOCATEIOCB
is used in a LINE^HANDLER.
See the description of the ALLOCATEIOCB on page 8-9 procedure for an example
of usage of DEALLOCATEIOCB.
^DELAY
This procedure permits a task to suspend itself for a timed interval.
Extended General Device Support (GDSX) Manual—529931-001
8- 19
DELETE^[X]ITEM
Service Routines
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as the counterpart in the
Guardian Procedure Calls Reference Manual.
Considerations
•
•
When called with a time-period parameter value greater than 0, the ^DELAY
procedure causes the calling task to be suspended. However, the GDSX process
remains active and other tasks can run.
This procedure may be called to wait for a period of time after a deadlock or a
failure to obtain buffer space.
DELETE^[X]ITEM
The DELETE^ITEM and DELETE^XITEM procedures delete an item from a linked list.
DELETE^ITEM is intended for use with lists in local memory, while DELETE^XITEM is
intended for use with lists in extended memory.
CALL DELETE^[X]ITEM ( link-item-address );
i
link-item-address
INT:value
(Use with DELETE^ITEM.)
INT(32):value
(Use with DELETE^XITEM.)
!
input
is the address of an element to be deleted from the list.
The following condition code settings are valid:
=
CCE indicates that the item was successfully deleted.
<
CCG indicates that the item was not found on the list.
^DEVICEINFO2
This procedure obtains the device type and the physical record length of a file. The file
can be open or closed.
If USCODE is converted, TSCODE receives device information in the D-series system
message format, and so USCODE tasks cannot call this C-series service routine. If a
task within a converted application calls this procedure, file-system error 29 or 560 is
returned. Converted USCODE must instead call ^FILE_GETINFOBYNAME_.
Except for the following consideration, the syntax, condition code settings, and
considerations regarding this procedure are the same as the counterpart in the
Guardian Procedure Calls Reference Manual.
Extended General Device Support (GDSX) Manual—529931-001
8- 20
DO^CP
Service Routines
Considerations
•
•
Because the working stack images of tasks are swapped to and from an extended
data segment during I/O operations, I/O must be performed to and from global
buffers.
If you want USCODE to provide calls to ^AWAITIO[X] in order to wait for I/O
completion on ^DEVICEINFO2, ^FILE_GETINFOBYNAME_, and
^PROCESS_CREATE_ service routines, as would be done for typical nowaited
Guardian procedure calls, you must set the PROCNOWAIT configuration
parameter to 1.
If you want TSCODE to supply AWAITIO[X] calls to complete these nowaited I/Os
on behalf of USCODE, you set PROCNOWAIT to 0. See PROCNOWAIT on
page 2-70 for more information.
DO^CP
This procedure automatically does a GET^CPSEM, checkpoints whatever is in the
checkpoint buffer to the backup process, and then automatically does a GIVE^CPSEM.
The call to GIVE^CPSEM is not done if the call to GET^CPSEM determined that the
calling task already owned the checkpoint semaphore when GET^CPSEM was called.
Unlike ^CHECKPOINT, a restart point is not established at the statement following the
call to DO^CP.
At the time that DO^CP is called, you should already have queued data for
checkpointing by calling Q^CP or Q^CPX, both of which copy data to the TSCODE
checkpoint buffer. The size of the checkpoint buffer is specified by the MAXCPSIZE
configuration parameter. See the description of Q^CP[X] on page 8-57 for more
information.
Caution. If a task owning one or more semaphores stops, the primary GDSX process stops.
If a task owning one or more semaphores faults with noretn equal to 1 in a call to FAULT, the
primary GDSX process stops.
Caution. Use ^CHECKPOINT(2) instead of Q^CPX and DO^CP to checkpoint extended
memory buffer pools. As DO^CP checkpoints directly across to the backup process, using
Q^CPX and DO^CP to checkpoint extended memory buffers works only for pool areas
allocated in exactly the same area of memory in both the primary and the backup.
status := DO^CP
status
returned value
INT:value
Extended General Device Support (GDSX) Manual—529931-001
8- 21
^ENDTRANSACTION
Service Routines
indicates the outcome of the call. The value of status is one of the following:
0
The checkpoint failed
1
The data queued in checkpoint buffer was successfully checkpointed to the
backup process
Considerations
•
•
DO^CP causes the calling task to be suspended.
If GDSX is run as a process pair, TSCODE automatically calls DO^CP upon the
return from the USER^BACKUP user exit so that the primary and backup
processes are synchronized at startup.
Examples
•
•
For an example of user global checkpointing by DO^CP, see the description of
Q^CP[X] on page 8-57.
See the description of the USER^BACKUP on page 9-10 for an example showing
how user global checkpointing can be done when a GDSX process pair is
initialized.
^ENDTRANSACTION
This procedure completes a TMF transaction initiated by ^BEGINTRANSACTION.
You do not need to complete the call to ^ENDTRANSACTION with a call to ^AWAITIO
or ^AWAITIOX in a user task. See Appendix D, Using Pseudo Procedures in a TS/MP
Environment for an example of using this procedure.
A trace record is written after a successful call to ^ENDTRANSACTION if bit 3 of
trace^control^flags in DCCBDECS is set to 1. The trace records contain the calling
task number of the user task and the TMF transaction identifier. See Tracing GDSX on
page 2-80 for more information.
The syntax, condition code settings, and considerations regarding this procedure are
the same as the counterpart in the NonStop TMF Application Programmer’s Guide.
FAULT
When a situation is detected programmatically that requires investigation, USCODE
may call FAULT and pass a fault number that is reported in an EMS message.
TSCODE stores the fault number in tcb.fault.
If a task is not to be restarted (noretn parameter equal to 0), control is returned to the
calling user exit or task. FAULT can be called with the noretn parameter equal to 0
from any user exit or task except the first five exits that can be called by TSCODE:
•
•
PROCESS^ASSIGNS
PROCESS^USER^PARAMS
Extended General Device Support (GDSX) Manual—529931-001
8- 22
FAULT
Service Routines
•
•
•
USER^INIT^CONFIG^PARAMS
USER^INITIALIZE
USER^VERSION
During execution of these five exits, the monitor task, which handles the EMS
messages, has not been created.
If a task is to be restarted (noretn is equal to 1), TSCODE calls the USER^STOP exit,
with the suspended calling task as the current task. Then, if the auto^restart^flag of
the CONTROLGLAGS configuration parameter is set, TSCODE restarts the task from
the beginning after a time delay given by the RESTARTTIME configuration parameter.
Caution. FAULT may be called with noretn equal to 1 only from the DEVICE^HANDLER and
LINE^HANDLER user exits, because only within these exits is a user task executing.
Using the SCF STATUS command for a task calling FAULT shows an error condition.
Other tasks continue to run normally.
Caution. Before calling FAULT with noretn equal to 1, a task must release all semaphores
that it holds.
CALL FAULT ( fault-number
i
,[ noretn ]
i
,[ tcb ]
i
,[ p-reg ]
i
,[ e-reg ] );
i
fault-number
!
!
!
!
!
input
INT:value
is a user-supplied fault number, which must be greater than 100. Fault numbers
1-100 are reserved for system use. See Fault Messages on page 3-26 for more
information.
noretn
input
INT:value
indicates whether the calling user exit or task should be restarted after the fault is
posted. Restarting a task means the task is stopped and started by TSCODE.
Extended General Device Support (GDSX) Manual—529931-001
8- 23
^FILE_CLOSE_
Service Routines
The value of noretn is one of the following:
0
The user exit or task is not to be restarted. Control is given back to the
calling process. This is the default.
1
The user exit or task is to be restarted.
FAULT can be called with the noretn parameter equal to 0 from any user exit or
task.
input
tcb
INT .EXT:ref
is a pointer containing the calling task’s TCB address.
input
p-reg
INT:value
contains the contents of the P register when FAULT is called.
input
e-reg
INT:value
contains the contents of the E register when FAULT is called.
^FILE_CLOSE_
This procedure closes an open file. The ^CLOSE and ^FILE_CLOSE_ procedures
function exactly the same. ^FILE_CLOSE_ may be called whether USCODE is
converted or unconverted. This procedure is a waited operation.
The syntax, condition code settings, and considerations regarding this procedure are
the same as the counterpart in the Guardian Procedure Calls Reference Manual.
^FILE_GETINFO_
This procedure obtains a limited set of information about a file identified by file number.
The ^FILE_GETINFO_ procedure provides only a subset (last error, file name, and file
type) of the functions available with ^FILEINFO. ^FILEINFO and ^FILE_GETINFO_
can be called whether the application is converted or unconverted. ^FILE_GETINFO_
is a waited operation.
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as the counterpart in the
Guardian Procedure Calls Reference Manual.
Considerations
•
A filenum parameter value of -1 will return the last file-system error against the
current task.
Extended General Device Support (GDSX) Manual—529931-001
8- 24
^FILE_GETINFOBYNAME_
Service Routines
•
If TSCODE is unconverted, then it is recommended that USCODE call ^FILEINFO.
When TSCODE is unconverted and USCODE calls ^FILE_GETINFO, the following
should be noted regarding the returned information:
•
•
•
Filename uses the C-series internal expanded format.
Filename-length is always returned with a value of 24.
Type-info is returned in a buffer of 5 words of which only the first word is
relevant.
^FILE_GETINFOBYNAME_
This procedure obtains the device type and the physical record length of a file. The file
can be open or closed.
If USCODE is unconverted, TSCODE receives device information in the C-series
system message format, and so USCODE tasks cannot call this D-series service
routine. If a task within an unconverted application calls this procedure, file-system
error 29 or 560 is returned. Unconverted USCODE must instead call ^DEVICEINFO2.
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as the counterpart in the
Guardian Procedure Calls Reference Manual.
Considerations
•
•
Calling ^FILE_GETINFOBYNAME_ in a nowaited mode causes the calling task to
be suspended.
If you want USCODE to provide calls to ^AWAITIO[X] in order to wait for I/O
completion on ^DEVICEINFO2, ^FILE_GETINFOBYNAME_, and
^PROCESS_CREATE_ service routines, as would be done for typical nowaited
Guardian procedure calls, you must set the PROCNOWAIT configuration
parameter to 1. If you want TSCODE to supply AWAITIO[X] calls to complete
these nowaited I/Os on behalf of USCODE, you set the PROCNOWAIT to 0. See
PROCNOWAIT on page 2-70 for more information.
^FILE_GETRECEIVEINFO_
Information about the last message read on $RECEIVE is returned from
^FILE_GETRECEIVEINFO_. If USCODE is unconverted and a user task calls this
procedure, file-system error 29 or 560 is returned. Unconverted USCODE must
instead call ^RECEIVEINFO.
To facilitate coding of this procedure, USCODE may source in the
getreceiveinfo^template section of the ULHDECS, ULHDECSE, or USKELDEC
installed subvolume files.
The syntax, condition code settings, and considerations regarding this procedure are
the same as the counterpart in the Guardian Procedure Calls Reference Manual.
Extended General Device Support (GDSX) Manual—529931-001
8- 25
^FILEINFO
Service Routines
^FILEINFO
This procedure obtains error and characteristic information about a file. ^FILEINFO
may be called whether USCODE is converted or unconverted. The ^FILE_GETINFO_
procedure provides only a subset of the functions available with ^FILEINFO.
Except for the following consideration, the syntax, condition code settings, and
considerations regarding this procedure are the same as the counterpart in the
Guardian Procedure Calls Reference Manual.
Consideration
To get the last file management error for a task, use CALL ^FILEINFO( -1, ERROR).
^FILE_OPEN_
By calling the ^FILE_OPEN_ procedure, one task can establish a communication path
between all user tasks and a file. ^FILE_OPEN_ may be called whether USCODE is
converted or unconverted.
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as given for the Guardian
FILE_OPEN_ procedure in the Guardian Procedure Calls Reference Manual.
Considerations
•
•
•
•
•
•
Calling ^FILE_OPEN_ in a nowaited mode causes the calling task to be
suspended.
Because the working stack images of tasks are swapped to and from an extended
data segment during I/O operations, I/O must be performed to and from global
buffers.
If the options parameter is supplied and bit 1 is set for a nowaited call, USCODE
should not issue a subsequent ^AWAITIO. TSCODE will take care of issuing an
AWAITIO to Guardian to return the information to the calling task. No additional
user code is necessary to complete the call.
^OPEN does not support process file segment (PFS) buffering, while
^FILE_OPEN_ does support PFS buffering.
The primary-processhandle parameter supported for the Guardian
FILE_OPEN_ procedure is not supported for ^FILE_OPEN_. TSCODE
automatically opens files in the backup process on behalf of USCODE.
When a user task calls ^OPEN, the resulting open may be either private to that
task or public to all tasks in the GDSX process. The distinction made by TSCODE
is based on the address of the file number parameter passed to ^OPEN: if the
address is local to the task or is in the upper 32K words of the user data segment,
the open is considered private; if the address is in user globals or the buffer pool
(anywhere below %73000), the open is considered public.
Extended General Device Support (GDSX) Manual—529931-001
8- 26
^FILE_OPEN_
Service Routines
•
^Open is called in the primary process; hence, it is optional to provide the following
parameters:
°
°
°
°
primary file_id
primary process_id
primary block buffer
primary block length
Caution. When a user task stops, TSCODE automatically closes all of the task’s private
opens but leaves public opens open, because other tasks may be using them.
•
For the purpose of editing input data, it may be desirable to read disk files within
GDSX. Because the maximum nowait depth for disk files is 1, at most one nowait
I/O can be in process on a single open of a disk file. Multiple tasks use a
semaphore to control access to the publicly opened file in this example:
INT
DISKFILE,
.DISKSEM[0:3],
.DISKNAME[0:11];
.
PROC USER^INITIALIZE(PRIMARY);
INT PRIMARY;
BEGIN
DISKSEM[0] := DISKSEM[1] := DISKSEM[2] := 0;
CALL INIT^SEM(DISKSEM);
IF PRIMARY THEN
BEGIN
DISKNAME ':=' ["$XYZ
SOME
FILE
"];
CALL ^FILE_OPEN(DISKNAME, DISKFILE, ...);
IF < THEN
BEGIN
.
produce suitable error message
.
CALL ^TERMINATE;!Stop GDSX process
END;
END;
END;
PROC DEVICE^HANDLER(FILE, ME, TYPE);
BEGIN
.
IF PSEM(DISKSEM, 200D) THEN
BEGIN
CALL ^READ(DISKFILE, BUFFER, ....);
IF = THEN
CALL ^AWAITIO(DISKFILE,....);
IF <> THEN
.
.
Extended General Device Support (GDSX) Manual—529931-001
8- 27
^FNAMEEXPAND
Service Routines
CALL VSEM(DISKSEM);
END
ELSE
BEGIN
!UNABLE TO GET THE LOCK
.!WITHIN 2 SECONDS
.
END;
^FNAMEEXPAND
This procedure expands a partial file name from the compacted external form to the
12-word internal form usable by other file-system procedures. ^FNAMEEXPAND may
be called whether USCODE is converted or unconverted.
Except for the following consideration, the syntax, condition code settings, and
considerations regarding this procedure are the same as the counterpart in the
Guardian Procedure Calls Reference Manual.
Consideration
The ^FNAMEEXPAND procedure is defined as VARIABLE, which allows you to call it
with only the external-filename and internal-filename parameters. In this
case, GDSX submits the call with these two parameters to the Guardian
FNAMEEXPAND procedure, supplying FNAMEEXPAND with the default volume and
subvolume (from which the GDSX process was started), which is stored in a TSCODE
global variable.
If USCODE submits its own default volume and subvolume parameter to
^FNAMEEXPAND, then GDSX passes this to Guardian FNAMEEXPAND instead of
the default volume and subvolume name stored in the TSCODE global variable.
GET^CPSEM
This procedure allows a task to acquire the checkpoint semaphore maintained
internally by TSCODE in order to checkpoint data. Once the checkpoint semaphore is
obtained, the task can call Q^CP[X] to queue data in TSCODE’s checkpoint buffer, and
then call DO^CP or ^CHECKPOINT to actually copy the data to the backup process.
There is only one checkpoint semaphore, so a task obtaining this semaphore is
guaranteed that no other task (system or user task) can initiate a checkpoint operation
until the semaphore is released by means of GIVE^CPSEM. Therefore, the data that
is queued by a call to Q^CP[X] cannot be corrupted by another task.
If a task attempts to get the checkpoint semaphore when it is held by another task, the
task calling GET^CPSEM is suspended and put on a wait queue. (See INIT^SEM on
page 8-41 for an explanation of the queuing mechanism.) After acquiring the
semaphore the task may call Q^CP[X].
Extended General Device Support (GDSX) Manual—529931-001
8- 28
GET^CPSEM
Service Routines
Global data may be checkpointed concurrently with the task’s stack image and
memory pool buffers. See the example in the description of the Q^CP[X] on
page 8-57.
Caution. While a task owns one or more semaphores, it is in an unstoppable state; if the task
faults while in this state, the primary GDSX process stops.
status := GET^CPSEM
returned value
status
INT:value
indicates the outcome of the call. The value of status is one of the following:
0
The calling task owned the checkpoint semaphore before this call
1
The semaphore was acquired on this call
Considerations
•
•
A task calling this procedure may be suspended.
The manner in which GET^CPSEM returns the values 0 or 1 is intended to allow
procedures that need to call Q^CP[X] to obtain the semaphore while still ensuring
that checkpointed information from related calls is sent to the backup in a single
I/O.
For example, procedures P1 and P2 both require checkpointing and P2 calls P1.
P1 is also called in other places. P1 might be coded as follows:
PROC P1;
BEGIN
INT P1^GOT^CP^SEM := GET^CPSEM;
.
.
CALL Q^CP(.....);
.
.
IF P1^GOT^CP^SEM THEN
BEGIN
CALL DO^CP;
CALL GIVE^CPSEM;
END;
END;
Similarly, P2 is:
PROC P2;
BEGIN
INT P2^GOT^CP^SEM := GET^CPSEM;
.
.
CALL Q^CP(.....);
Extended General Device Support (GDSX) Manual—529931-001
8- 29
GETEXTPOOL
Service Routines
CALL P1;
CALL Q^CP(.....);
.
.
IF P2^GOT^CP^SEM THEN
BEGIN
CALL DO^CP;
CALL GIVE^CPSEM;
END;
END;
The procedure that acquires the semaphore is responsible for sending the
accumulated checkpoint buffer to the backup.
Assume that the caller of P2 does not own the checkpoint semaphore. When P2 is
called, the initialization of p2^got^cp^sem thus acquires the semaphore and
p2^got^cp^sem is set to 1. When P1 is entered, GET^CPSEM is again called
during initialization of p1^got^cp^sem . In this case, the task already owns the
checkpoint semaphore, so p1^got^cp^sem is initialized to zero. P1 does not
checkpoint the data nor does it release the checkpoint semaphore, because
p1^got^cp^sem is zero. When control is returned to P2, the data is checkpointed
and the semaphore is released, because p2^got^cp^sem is nonzero.
When P1 is called elsewhere, and the caller does not own the checkpoint
semaphore, P1 acquires the semaphore, checkpoints the data, and releases the
semaphore.
GETEXTPOOL
This procedure allocates extended memory pool space for the calling task from one of
four extended memory pools:
•
•
•
•
Pool 1, the shared extended pool
Pool 2, the private extended pool
Pool 10, the extended buffer pool
Pool 11, the extended message pool
Before issuing a call to GETEXTPOOL for one of the four memory pools, you allocate
the maximum pool space to be used by setting the POOLSIZE configuration
parameter.
The maximum size of the shared extended pool, pool 1, is established by setting
POOLSIZE with a TACL PARAM command or by setting the poolsize variable within
the USER^INIT^CONFIG^PARAMS user exit. POOLSIZE specifies the maximum pool
size in words that all user tasks may share. TSCODE allocates an extended memory
area of size POOLSIZE multiplied by 2 bytes for the shared extended pool. The
default for POOLSIZE is 16,392 words.
The maximum size of the private extended pool, pool 2, is established by setting the
TASKPOOLSIZE configuration parameter with a TACL PARAM command or by setting
Extended General Device Support (GDSX) Manual—529931-001
8- 30
GETEXTPOOL
Service Routines
the taskpoolsize variable within the USER^INIT^CONFIG^PARAMS user exit.
TASKPOOLSIZE specifies the maximum pool size in words that each user task is
allowed to acquire privately. TSCODE allocates an extended memory area of total
size (TASKPOOLSIZE * 2) multiplied by MAXTASKS bytes for all the private extended
pools. The default for TASKPOOLSIZE is 128 words.
The maximum size of the extended buffer pool, pool 10, is established by setting the
MAXBUFPOOL configuration parameter with a TACL PARAM command or by setting
the maxbufpoolsize variable within the USER^INIT^CONFIG^PARAMS user exit. The
default for MAXBUFPOOL is 32,000 bytes.
The size of the extended message pool, pool 11, is established by setting the
MAXMSGPOOL configuration parameter with a TACL PARAM command or by setting
the maxmsgpoolsize variable within the USER^INIT^CONFIG^PARAMS user exit. The
default for MAXMSGPOOL is 32,000 bytes.
Pool sizes can be viewed by an SCF INFO command. For example:
-> INFO $GDSX-process-name, DETAIL
For more information, see Memory Pools on page 2-24.
address := GETEXTPOOL ( pool
i
,size );
i
!
!
returned value
address
INT .EXT:value
is the relative extended address of area allocated, unless space was not available,
in which case a zero is returned.
input
pool
INT:value
is the pool to allocate space for. The values of pool are as follows:
1
Shared extended pool
2
Private extended pool
10
Extended buffer pool
11
Extended message pool
input
size
INT:value
indicates the number of words to allocate.
Extended General Device Support (GDSX) Manual—529931-001
8- 31
GETEXTPOOL
Service Routines
Considerations
•
•
•
No mechanism for queuing of allocation requests or timeout is provided. For
private storage such a facility has no purpose because each task has its own
individual pool.
A call to ^CHECKPOINT(2) checkpoints all local and extended memory pools
acquired by the calling task.
If poolcheck^flag of the DEBUGFLAGS configuration parameter is set, each time a
task is dispatched, TSCODE checks the buffer pool, message pool, extended
buffer pool, and extended message pool for corruption. If corruption is detected,
GDSX stops with abend error 230 or abend error 231. This pool checking is in
addition to that always done when the GETLOCALPOOL and GETEXTPOOL
procedures are called.
The poolcheck^flag can be set when debugging a program and turned off during
production to allow GDSX to run more efficiently.
Examples
1. This example allocates 20 words in the extended buffer pool and deallocates the
space when it is no longer needed with PUTEXTPOOL:
INT .EXT buf;
INT size := 20;
!Pointer for extended buffer pool.
!Length in words of extended pool
!area to acquire.
INT(32) holdaddr; !Hold extended buffer address (optional)
.
@buf := GETEXTPOOL (10, size);
holdaddr := @buf;
.
CALL PUTEXTPOOL (10, @buf);
or
CALL PUTEXTPOOL (10, holdaddr);
2. This example allocates 100 words in the shared extended pool and deallocates the
space when it is no longer needed with PUTEXTPOOL:
> PARAM TASKPOOLSIZE 2000 !comment 2000 words
> PARAM POOLSIZE 200
!comment 200 words
> RUN GDSC /NAME $GDSX, NOWAIT/
BLOCK USER^PRIVATE;
INT .EXT GLOBAL^SHARED^PTR := 0D;
INT .EXT TASK^SHARED^PTR;
.
END BLOCK;
PROC USER^START;
INT WDS;
! Pointer initialized @ first call to USER^START
IF @GLOBAL^SHARED^PTR = 0D THEN
BEGIN
Extended General Device Support (GDSX) Manual—529931-001
8- 32
GETEXTPOOLX
Service Routines
WDS := 100;
@GLOBAL^SHARED^PTR := GETEXTPOOL(1, WDS);
GLOBAL^SHARED^PTR ':=' "+ Let all tasks see this !+";
END;
.
END; ! of USER^START;
PROC DEVICE^HANDLER(.......);
INT .EXT WORK^PTR;
INT WDS, N;
.
.
@WORK^PTR := @GLOBAL^SHARED^PTR;
IF WORK^PTR = "+" THEN
!All user tasks can see
!this data
BEGIN
WORK^PTR ':=' " "; !Spaces on first time thru
!Allocate a second buffer of 100 words.
@TASK^SHARED^PTR := GETEXTPOOL(1, 100);
TASK^SHARED^PTR ':=' "5";
.
.
END
ELSE
BEGIN !We are not the first D^H task to be created
@WORK^PTR := @TASK^SHARED^PTR;
IF WORK^PTR = "5" THEN
BEGIN
.
.
CALL PUTEXTPOOL(1, @WORK^PTR);
GETEXTPOOLX
This procedure allocates extended memory pool space for the calling task. Unlike
GETEXTPOOL, GETEXTPOOLX can be used for allocating more than 64 KB of
memory space. The upper limit for the configuration parameters MAXCPSIZE and
TASKCPSIZE is increased to 65000 to support checkpointing of pools larger than
64KB size. The upper limit for the configuration parameters POOLSIZE and
TASKPOOLSIZE is set to 65000.
For more information, see Memory Pools on page 2-24.
address := GETEXTPOOLX ( pool
i
,size ) ;
i
!
!
returned value
address
INT .EXT:value
Extended General Device Support (GDSX) Manual—529931-001
8- 33
GET^ITC^FCB
Service Routines
is the relative extended address of area allocated, unless space was not available,
in which case a zero is returned.
input
pool
INT:value
is the pool to allocate space for. The values of pool are as follows:
1
Shared extended pool
2
Private extended pool
10
Extended buffer pool
11
Extended message pool
input
size
INT(32):value
indicates the number of words to allocate.
Considerations
•
•
•
No mechanism for queuing of allocation requests or timeout is provided. For
private storage such a facility has no purpose because each task has its own
individual pool.
A call to ^CHECKPOINT(2) checkpoints all local and extended memory pools
acquired by the calling task.
If poolcheck^flag of the DEBUGFLAGS configuration parameter is set, each time a
task is dispatched, TSCODE checks the buffer pool, message pool, extended
buffer pool, and extended message pool for corruption. If corruption is detected,
GDSX stops with abend error 230 or abend error 231. This pool checking is in
addition to that always done when the GETLOCALPOOL and GETEXTPOOL[X]
procedures are called.
The poolcheck^flag can be set when debugging a program and turned off during
production to allow GDSX to run more efficiently.
GET^ITC^FCB
This procedure allows a task to send ITC messages to other tasks. A task can send
an ITC message to another task only after it has the FCB address of the receiving task.
To obtain the FCB address, the sending task calls GET^ITC^FCB once for each task it
will send an ITC message to.
Extended General Device Support (GDSX) Manual—529931-001
8- 34
GET^ITC^FCB
Service Routines
To send an ITC message, the sending task calls SEND^ITC^MSG[X], using the FCB
address in that call to identify the receiving task.
status := GET^ITC^FCB ( buffer:length
i:i
,fcb-address
,[ dcb-address ] );
!
! o
! o
returned value
status
INT:value
indicates the outcome of the call. The value of status is one of the following:
-1
One or both of the addresses were not found
0
The FCB and DCB addresses were found
buffer:length
input:input
INT(32):ref, INT:value
is a pointer to the buffer that contains the SU name of the receiving task to search
for, and the length of the buffer in bytes. See Considerations on page 8-35 later in
this subsection for more information about specifying the SU name.
fcb-address
output
INT(32):ref
is the FCB address of the receiving task.
dcb-address
output
INT(32):ref
is the address of a DCB. This parameter is used when you require information
about the physical attributes of a device; physical attributes are stored in the DCB.
Considerations
When an SU is configured by SCF, the SU name consists of two or three names in one
of these formats:
$GDSX-process-name.#su-name
$GDSX-process-name.#su-name.qualifier
To specify the SU name of the receiving task for GET^ITC^FCB to search for, you
must allocate a buffer and initialize it to $GDSX-process-name, #su-name, and the
qualifier, if it has one. The buffer parameter of GET^ITC^FCB is a pointer to
that buffer. When GET^ITC^FCB finds a match between the SU name specified in
buffer and an SU name in dcb.name of the dcb^template, it returns the FCB and
DCB addresses.
Extended General Device Support (GDSX) Manual—529931-001
8- 35
GETLOCALPOOL
Service Routines
Example
In this example a task will send ITC messages to TERM1, which was configured with
an SU name of $GDSX.#SU00l.TERM0001. The task calls GET^ITC^FCB to obtain
the FCB address of TERM1. After it has the FCB address, the task can use
SEND^ITC^MSG[X] as many times as necessary to send messages to TERM1. The
example shows one instance of sending a message with SEND^ITC^MSGX:
@buffer^pointer := GETEXTPOOL(10, 8);
buffer^pointer ':=' ["$GDSX.#SU001.TERM0001"];
error := GET^ITC^FCB (buffer^pointer:21, fcbaddr, dcbaddr);
.
.
.
IF NOT error THEN
BEGIN
@itc^fcb^struct^pointer := fcbaddr;
CALL SEND^ITC^MSGX (itc^fcb^struct^pointer,
buffer^with^data,
length^sent,
length^returned,
tag,
writeread^operation);
.
.
GETLOCALPOOL
This procedure allocates local pool space for the calling task from one of two local
memory pools. The local buffer pool, pool 0, is in the lower 32K of the user data stack,
and contains approximately 28,000 words. The local message pool, pool 1, is in the
upper 32K of the user data stack and contains approximately 32,000 words.
For more information, see Memory Pools on page 2-24.
address := GETLOCALPOOL ( pool
i
,size
i
,[ timeout ] );
i
address
!
!
!
returned value
INT:value
is the word address of the allocated memory, unless a timeout occurred or space
was not available. In the latter two cases a zero is returned.
pool
input
INT:value
Extended General Device Support (GDSX) Manual—529931-001
8- 36
GETLOCALPOOL
Service Routines
defines which local pool to allocate memory for. The value for pool is one of the
following:
0
Local buffer pool
1
Local message pool
input
size
INT:value
is the number of words to allocate.
input
timeout
INT(32):value
is the maximum number of ticks (10 ms) to wait for space to be allocated.
If this parameter is omitted, the calling task waits the number of ticks defined by
the BUFFERTIMEOUT configuration parameter. BUFFERTIMEOUT has a default
of 1,000 ticks, equal to 10 seconds. If space is not allocated within that time,
TSCODE suspends the calling task with a fault.
Considerations
•
•
•
This procedure may cause the calling task to be suspended.
A call to ^CHECKPOINT(2) checkpoints all local and extended memory pools
acquired by the calling task.
If poolcheck^flag of the DEBUGFLAGS configuration parameter is set, each time a
task is dispatched, TSCODE checks the buffer pool, message pool, extended
buffer pool, and extended message pool for corruption. If corruption is detected,
GDSX stops with abend error 230 or abend error 231. This pool checking is in
addition to that always done when the GETLOCALPOOL and GETEXTPOOL
procedures are called.
Poolcheck^flag can be set when debugging a program and turned off during
production to allow GDSX to run more efficiently.
Example
This example shows the allocation of a 128-word buffer to be word-addressed through
the pointer buf and byte-addressed through bufs. The example also shows the
address equation used to allow the buffer to be referenced as a structure by means of
strct.
.
.
LITERAL BUFSZ = 128;
INT TICKS;
INT .BUF;
!Words to acquire.
Extended General Device Support (GDSX) Manual—529931-001
8- 37
GET_PROCESS_HANDLE_FROM_NAME_
Service Routines
STRING .BUFS; !String pointer
! Note that a string pointer will
! not work for the
! message pool (pool 1)
STRUCT .STRCT(SOME^STRUCT) = BUF; ! Point user structure to
! address returned.
.
.
TICKS := 300;
! Wait maximum of 3 seconds.
@BUF := GETLOCALPOOL(0, BUFSZ, TICKS); ! Get local buffer
! pool address
! (lower data stack).
IF @BUF = 0 THEN
BEGIN
! do error handling
END;
@BUFS := @BUF '<<' 1;
! Initialize string pointer.
.
GET_PROCESS_HANDLE_FROM_NAME_
This procedure returns the process handle of a process created by USCODE.
status := GET_PROCESS_HANDLE_FROM_NAME_ ( name:length
i:i
,processhandle );
!
! o
returned value
status
INT:value
indicates the outcome of the call. The value of status is one of the following:
-1
The process handle for name was not found
0
The process handle for name was found
name:length
input:input
STRING .EXT:ref:*, INT:value
supplies the name of the process whose process handle is to be found. The value
of name must be exactly the length in bytes as specified by length.
processhandle
output
INT .EXT:ref:10
is a pointer to a process handle. If the operation is successful, 0 is returned in
status, and processhandle contains the process handle corresponding to the
name supplied by name. If the operation is not successful, 1 is returned in
status, and processhandle contains a null process handle (-1 in each word).
Extended General Device Support (GDSX) Manual—529931-001
8- 38
GET_PROCESS_HANDLES_CPU_
Service Routines
GET_PROCESS_HANDLES_CPU_
This procedure returns the CPU number of a process handle.
cpu := GET_PROCESS_HANDLES_CPU_ ( processhandle );
i
!
returned value
cpu
INT:value
indicates the outcome of the operation. If a valid CPU number is found in the
process handle, the number is returned in cpu, otherwise -1 is returned.
processhandle
input
INT .EXT:ref:10
is a pointer to a process handle.
GET_PROCESS_HANDLES_NODE_
This procedure returns the node number from the passed-in process handle.
node := GET_PROCESS_HANDLES_NODE_ ( processhandle );
i
!
returned value
node
INT(32):value
indicates the outcome of the operation. If a valid node number is found in the
process handle, the number is returned in node; otherwise -1D is returned.
processhandle
input
INT .EXT:ref:10
is a pointer to a process handle.
GET^TASK^NAME
This procedure provides the calling task with the object name of another task’s SU or
LINE. The name is taken from the variable name (SCF object name) in the
dcb^template. Use the ^MYTERM procedure to get the object name of the calling
task’s SU or LINE.
name-length := GET^TASK^NAME ( tcb
i
,name );
o
Extended General Device Support (GDSX) Manual—529931-001
8- 39
!
!
GIVEBREAK
Service Routines
name-length
returned value
INT:value
is the length in bytes of the SCF object name. If the SU or LINE is unconverted,
the value returned is always 24 bytes. If SU or LINE is converted, the value
returned is always the length of the object name, with a maximum of 32 bytes.
input
tcb
INT .EXT:ref
is a pointer to a task’s TCB. The TCB pool can be scanned for the TCB
addresses. See the example for the TCBADDR on page 8-81.
output
name
INT:ref:12
is the SCF object name (not the access name), whether the object was configured
by means of SCF, or the object was not configured explicitly and the object name
was derived by TSCODE from a device name. This SU or LINE name is taken
from the variable name in either the dcb^template or the line^template, depending
on whether the calling task is a DEVICE^HANDLER task or LINE^HANDLER task,
respectively.
GIVEBREAK
A task calls this procedure to give up the break ownership of the terminal it controls.
CALL GIVEBREAK
The following condition code settings are valid
=
CCE indicates that the task successfully released break ownership for its
terminal.
<
CCL indicates one of the following conditions:
•
•
An I/O error occurred on the SETPARAM issued by TSCODE to release
break ownership (the error number can be obtained by calling ^FILEINFO).
The checkpoint semaphore could not be obtained when the backup process
was to be updated with the break ownership information (only applies if
GDSX is run as a process pair).
GIVE^CPSEM
The checkpoint semaphore maintained internally by TSCODE guarantees that only
one task (system or user task) can initiate a checkpoint operation until the semaphore
Extended General Device Support (GDSX) Manual—529931-001
8- 40
INIT^[X]LIST
Service Routines
is released by means of GIVE^CPSEM. This procedure allows a task to release the
checkpoint semaphore.
Caution. After checkpointing data to the backup process, the task owning the checkpoint
semaphore must call GIVE^CPSEM to release the semaphore or else the checkpointing
facilities will be locked up.
CALL GIVE^CPSEM
Consideration
Use the SCF STATS command to see if any tasks are waiting for resources. For
example:
-> STATS PROCESS $GDSX-process-name
INIT^[X]LIST
The INIT^LIST and INIT^XLIST procedures initialize a linked list. INIT^LIST is
intended for use with lists in global memory, while INIT^XLIST is intended for lists in
extended memory.
CALL INIT^[X]LIST ( list );
i
!
input
list
INT:ref
(Use with INIT^LIST)
INT .EXT:ref
(Use with INIT^XLIST)
is a pointer to the header of the list to be initialized.
INIT^SEM
This procedure initializes a semaphore other than the checkpoint semaphore in either
global or extended memory.
The purpose of a semaphore is to ensure the serial access of a shared resource. A
task is considered to have acquired a resource when it owns the semaphore
associated with the resource. TSCODE defines and maintains a checkpoint
semaphore to guarantee that no more than one task is doing a checkpoint at any given
time.
A unique user-defined semaphore should be established for each resource requiring
exclusive access. Three utility procedures are available for managing noncheckpoint
semaphores:
Extended General Device Support (GDSX) Manual—529931-001
8- 41
INIT^SEM
Service Routines
INIT^SEM
PSEM
VSEM
The checkpoint semaphore is defined by TSCODE and managed with the
GET^CPSEM and GIVE^CPSEM procedures.
A semaphore is first initialized with INIT^SEM. The semaphore can be defined in
global or extended memory; however, it is recommended that it is declared in global
memory, within a user private block, for example. If a backup GDSX process exists,
the semaphore must be initialized in both primary and backup GDSX processes. The
semaphore may then be acquired by calls to PSEM and released by calls to VSEM.
A task takes control of a semaphore when a call to PSEM inserts the address of the
task’s TCB (@TCB) into the first element of the semaphore structure (described in the
table below). If the semaphore is already owned, a task requesting ownership has its
TCB address inserted at the end of a linked list of tasks waiting for the same resource
(tasks are linked by tcb.locklink). The linked list is also part of the semaphore
structure, which has three elements.
Variable Name
Description
Contents
sem.semowner
Current owner of
semaphore
0 if semaphore is available; owner’s TCB if
semaphore is owned
sem.semhead
Head of the wait list
Address of SEMHEAD if no tasks are
waiting; otherwise, first waiter’s TCB
address
sem.semtail
Tail of the wait list
Address of SEMHEAD if no tasks are
waiting; otherwise, last waiter’s TCB
address
CALL INIT^SEM ( semaphore );
i
!
input
semaphore
INT:ref:3
(Semaphore in global memory)
INT(32) .EXT:ref
(Pointer to semaphore in extended memory)
is either allocation of the semaphore in global memory, or a pointer to the
semaphore to be allocated in global or extended memory. All three elements of
the semaphore array must be equal to 0 at the time of call.
Caution. In general, the dynamic allocation of extended memory (with an extended pointer, for
example) should be avoided in USCODE because the TAL compiler would allocate such space
in extended segment ID 1024. Segment ID 1024 is reserved for TSCODE.
Extended General Device Support (GDSX) Manual—529931-001
8- 42
INIT^XLIST
Service Routines
Examples
1. This example defines a semaphore my^resource in extended memory:
INT(32) .EXT MY^RESOURCE (SEM^TEMPLATE);
.
!pointer to an extended memory area
@MY^RESOURCE := GETEXTPOOL(10,6)
MY^RESOURCE.SEMOWNER := MY^RESOURCE.SEMHEAD
:= MY^RESOURCE.SEMTAIL := 0D;
CALL INIT^SEM (MY^RESOURCE);
!Initialize semaphore structure which exists in
!local or extended memory
.
.
IF got^resource^sem := PSEM( MY^RESOURCE, 600 ) THEN
!Attempt to acquire the semaphore was successful
.
.
IF got^resource^sem THEN VSEM( MY^RESOURCE ); !release
!semaphore.
.
2. You may wish to define a semaphore to ensure serial I/O to a disk file. This can be
accomplished in the USER^INITIALIZE exit by calls to ^OPEN and INIT^SEM to
open the disk file and initialize a semaphore for the file. See the example in the
considerations for the ^OPEN on page 8-52.
INIT^XLIST
For a description of the INIT^XLIST procedure, see INIT^[X]LIST on page 8-41.
INSERT^[X]ITEM
The INSERT^ITEM and INSERT^XITEM procedures insert an item into a linked list.
INSERT^ITEM is intended for use with lists in global memory, while INSERT^XITEM is
intended for lists in extended memory.
CALL INSERT^[X]ITEM ( address1
i
,address2 );
i
!
!
input
address1
INT:value
(Use with INSERT^ITEM.)
INT(32):value
(Use with INSERT^XITEM.)
is the address of an element on the list. To make an item addressed by address2
the first item on the list, address1 should specify the address of the list header.
Extended General Device Support (GDSX) Manual—529931-001
8- 43
ITC^OPENX
Service Routines
To make an item addressed by address2 the last item on the list, address1 should
specify the second occurrence of the array that specifies the list header
(list^header[1], which contains the address of the last item on the list).
input
address2
INT:value
(Use with INSERT^ITEM.)
INT(32):value
(Use with INSERT^XITEM.)
is the address of the element to be added to the list.
ITC^OPENX
This procedure provides a task with an ITC file number, which allows the task to
receive ITC messages from other tasks.
A task that wants to send messages to another task must have the receiving task’s
FCB address. The sending task obtains the FCB of the receiving task by calling
GET^ITC^FCB.
status := ITC^OPENX ( tcb-address
i
,itc-filenum );
o
!
!
returned value
status
INT:value
indicates the outcome of the call. The value of status is one of the following:
0
An ITC file number was acquired
Nonzero Number
An error condition occurred
tcb-address
input
INT .EXT:ref
is the current TCB address of the user task. See the following example for a way
to specify this address.
itc-filenum
output
INT:value
is the returned ITC file number, which is an index to the FCB table where all the
information for all opened files is stored.
Extended General Device Support (GDSX) Manual—529931-001
8- 44
^LISTEN
Service Routines
Example
The TCB address specified by tcb-address can be obtained by declaring and initializing
code in your user task as shown in the following example. Once the task has an ITC
file number, it uses ^READUPDATE to check for incoming ITC messages.
PROC DEVICE^HANDLER (term^file^num,
internal^term^no,
term^type);
INT .EXT my^dcb (dcb^template) := 0D;
INT .EXT my^tcb (tcb^template) := 0D;
INT itc^filenumber := 0D;
.
.
@my^dcb := dcbtbl[internal^term^no];
@my^tcb := my^dcb.tcbaddr;
error := ITC^OPENX (my^tcb, itc-filenumber)
IF itc^filenumber THEN
BEGIN
^READUPDATE (itc^filenumber);
IF = THEN
CALL ^AWAITIO (itc^filenumber, ...);
^LISTEN
This procedure looks for completed I/O operations for the calling task. Either an IOCB
address or zero is returned to the calling task.
iocb := ^LISTEN ( imsg
i
,i-o-message
i
,itc-flag );
i
!
!
!
returned value
iocb
INT(32):value
indicates the outcome of the operation. If a completed I/O specified by the imsg,
i-o-message, or itc-flag parameter settings was found, iocb contains the IOCB
address for the I/O. If the I/O was not found, iocb is set to 0.
input
imsg
INT:value
is a flag which, if nonzero, causes ^LISTEN to look for requests from $RECEIVE.
Set to zero if you are looking for completions on other files.
i-o-message
input
INT:value
Extended General Device Support (GDSX) Manual—529931-001
8- 45
^LISTEN
Service Routines
indicates where ^LISTEN is to look for completed I/O operations. The value of
i-o-message is one of the following:
-1
^LISTEN looks for all I/Os except intertask requests and
messages from $RECEIVE
0
^LISTEN looks for intertask requests or messages from
$RECEIVE
Positive Number
The file number where ^LISTEN is to look for completed I/Os
input
itc-flag
INT:value
indicates if ^LISTEN is to look for ITC requests. The value of itc-flag is one of the
following:
0
^LISTEN looks for completions on other files
Nonzero Number
^LISTEN looks for ITC requests
Considerations
•
•
The structure of an IOCB is declared in the iocb^template in the DCCBDECS file.
See Appendix C, DCCBDECS and ULHDECSE Listings for a listing of this file.
When receiving an IOCB from ^LISTEN, the address of the buffer used for the I/O
is located in the IOCB. The IOCB STRUCT contains an INT(32) variable bufaddrx,
which is equivalenced to two words, extaddr and bufaddr. When the buffer is in
extended memory, it can be referenced by bufaddrx. When the buffer is in local
memory, extaddr is zero, and the address is held in bufaddr.
To minimize USCODE complexity, you can consistently use either local or
extended memory. If you wish to use buffers in both areas of memory, you can
determine if the buffer address is in local or extended memory by testing
iocb.extaddr or iocb.iocb^info.ext^io. For example:
IF iocb.extaddr THEN
BEGIN ! we have a extended memory buffer address
.
.
END
ELSE
BEGIN !we have a local memory buffer address
.
.
END;
Extended General Device Support (GDSX) Manual—529931-001
8- 46
^LISTEN
Service Routines
•
For a message from $RECEIVE (message-flag is a nonzero value) the IOCB is as
follows:
iocb.syncid
Sync ID of request
iocb.state
5 = I/O pending
iocb.optype
12 = ^READUPDATE operation
iocb.iocnt
Length of request in bytes
iocb.cnt
Maximum reply size
iocb.bufaddrx
Buffer address where request resides. This will be a buffer
parameter to ^READUPDATE(0,..) or GDSX supplied buffer, if
the buffer parameter was omitted.
iocb.histag
Nowait tag from call to ^READUPDATE(0...)
iocb.file
0
iocb.msgtag
Message tag for request
iocb.rcbaddr
Address of requester control block for opener making this
request.
The calling task should perform the requested operation and then call ^REPLY,
passing iocb.msgtag as the tag parameter.
•
For an I/O completion that is not an intertask message or a message from
$RECEIVE (i-o-message is a nonzero value) the IOCB is as follows:
iocb.state
5 = I/O pending
iocb.optype
Type of operation completing
iocb.iocnt
Count transferred from AWAITIO[X]
iocb.bufaddr[x]
Buffer address from AWAITIO[X]
iocb.histag
Nowait tag from when I/O was initiated
iocb.file
File number
iocb.err
Guardian file error
Where multiple I/O operations of this type are outstanding simultaneously on a
LINE file, a loop should be executed as shown in the following example:
WHILE (@IOCB := ^LISTEN(0, LINE, 0)) DO
BEGIN
.
handle I/O completion
.
END;
Extended General Device Support (GDSX) Manual—529931-001
8- 47
^LOCKREC
Service Routines
•
For an intertask message (itc-flag is a nonzero value) the IOCB is as follows:
iocb.state
6 = I/O active
iocb.optype
Type of operation:
1 = CONTROL
2 = SETMODE
3 = WRITE
4 = READ
5 = WRITEREAD
iocb.histag
DEVICE^HANDLER’s nowait tag
iocb.tcbaddr
Address of DEVICE^HANDLER’s TCB
iocb.file
User task’s pseudo-file number
iocb.openid
Open ID assigned by USER^START
If the operation is a CONTROL:
iocb.control^op
CONTROL operation (operation)
iocb.control^param
Value of operation (param)
If the operation is a SETMODE:
iocb.setmode^funct
SETMODE function (function)
iocb.setmode^p1
SETMODE parameter (param1)
iocb.setmode^p2
SETMODE parameter (param2)
If the operation is a WRITE, READ, or WRITEREAD:
iocb.iocnt
Write count if WRITE or WRITEREAD
iocb.cnt
Read count if READ or WRITEREAD
iocb.bufaddr[x]
Address of DEVICE^HANDLER’s buffer
^LOCKREC
This procedure excludes other external openers from accessing a record at the current
position.
The syntax, condition code settings, and considerations regarding this procedure are
the same as the counterpart in the Guardian Procedure Calls Reference Manual.
MAKE_PROCESS_HANDLE_NULL_
This procedure creates a null process handle.
CALL MAKE_PROCESS_HANDLE_NULL_ ( processhandle );
o
Extended General Device Support (GDSX) Manual—529931-001
8- 48
!
^MYTERM
Service Routines
processhandle
output
INT .EXT:ref:10
is a pointer to the buffer to be set to the value of a null process handle (-1 in each
word).
^MYTERM
This procedure provides a task with the object name of its corresponding SU or LINE.
Use the GET^TASK^NAME procedure to get the object name of another task’s SU or
LINE.
To get the name of the home terminal for the GDSX process, call the Guardian
MYTERM procedure. MYTERM does not suspend the calling task.
length := ^MYTERM ( [ object-name ]
o
,[ filenum ] );
o
!
!
returned value
length
INT:value
is the length in bytes of the SCF object name. If the SU or LINE is unconverted,
the value returned is always 24 bytes. If SU or LINE is converted, the value
returned is always the length of the object name, with a maximum of 32 bytes.
object-name
output
INT:ref:12
is the SCF object name (not the access name), whether the object was configured
by SCF, or the object was not configured explicitly and the object name was
derived by TSCODE from a device name. This SU or LINE name is taken from the
variable name in the dcb^template or the lcb^template, depending on whether the
calling task is a DEVICE^HANDLER task or LINE^HANDLER task, respectively.
output
filenum
INT:ref
is the number of the file to which the calling task is associated. This is drawn from
the variable term in tcb^template, and is the same as the terminal file number or
the LINE file number for a DEVICE^HANDLER task or LINE^HANDLER task,
respectively.
^NEWPROCESS
This procedure is used by any GDSX task to create a new process, and optionally, to
assign a symbolic process name to the process. Having USCODE call the TSCODEExtended General Device Support (GDSX) Manual—529931-001
8- 49
NOTIFY^IO^COMPLETION[X]
Service Routines
supported ^NEWPROCESS procedure rather than the Guardian NEWPROCESS
allows GDSX to maintain a table (PCBTBL) of processes for which it is the creator. By
means of this table, stop or abend system messages received by TSCODE can be
routed to the task that created the process being stopped.
If USCODE is converted, TSCODE tracks its created processes with process handles,
and so USCODE tasks cannot call this procedure. If a task within a converted
application calls this procedure, file-system error 29 or 560 is returned. Converted
USCODE must instead call ^CREATE_PROCESS_, the equivalent D-series service
routine.
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as the counterpart in the
Guardian Procedure Calls Reference Manual.
Considerations
•
•
•
•
•
^NEWPROCESS is a waited operation. ^NEWPROCESS cannot be called in a
nowaited mode.
Because the working stack images of tasks are swapped to and from an extended
data segment during I/O operations, I/O must be performed to and from global
buffers.
The name, priority, and processor parameters are required. The Guardian jobid
and errinfo parameters are not supported.
The MAXPROCESSES configuration parameter specifies the maximum number of
processes that can be active simultaneously as a result of GDSX ^NEWPROCESS
calls. (MAXPROCESSES is used to determine the size of the PCB table.) If the
GDSX process is to run as a process pair, then MAXPROCESSES must be at
least 1 to allow for the creation of the backup process.
If a USCODE task calls ^NEWPROCESS, and the created process stops, abends,
or is lost due to CPU failure, TSCODE receives a stop, abend, or CPU fail system
message (type -5, -6, or -2). If sysmsgs^flag of the CONTROLFLAGS
configuration parameter is set to 1, TSCODE forwards the system message to the
USCODE task that created the process. Maximum length of the forwarded
message is 60 words.
NOTIFY^IO^COMPLETION[X]
When the processing for an intertask request from a sending task is completed by the
associated receiving task, a call to NOTIFY^IO^COMPLETION[X] by the receiving task
causes the IOCB to be delinked from the receiving task’s TCB and the sending task is
notified that the I/O request is complete or was canceled.
When a DEVICE^HANDLER task under a LINE initiates an I/O to the LINE, an IOCB is
automatically allocated and linked to the TCB for the task and to the FCB of the ITC file
(intertask communication file) just as it would be for a Guardian file. Also, the IOCB is
Extended General Device Support (GDSX) Manual—529931-001
8- 50
NOTIFY^IO^COMPLETION[X]
Service Routines
linked into the associated LINE^HANDLER task’s ITC request queue (addressed
externally by in^queue^file^num). The intertask I/O initiation is completed by causing a
LINE^HANDLER E^ITC event, assuming that the LINE^HANDLER task has a current
^READUPDATE on its ITC file.
After the LINE^HANDLER task’s call to WAIT^EVENT returns E^ITC, the task calls
^LISTEN (0,0,1). ^LISTEN looks at the task’s ITC request queue. If the queue is not
empty, the first IOCB in the queue is delinked, its state is changed to 6 (active), and its
address is returned.
When the LINE^HANDLER task finishes the request and calls
NOTIFY^IO^COMPLETION[X], the IOCB is delinked from the TCB for the task and
queued on the completed I/O list for the task. Also, the IOCB state is changed to 5
(pending). Finally, the originating (DEVICE^HANDLER) task’s E^IOC event is caused.
This is the same action that takes place when a Guardian I/O operation completes.
CALL NOTIFY^IO^COMPLETION[X] ( iocb
i
,[ buffer] );
i
!
!
input
iocb
INT:ref
(Use with NOTIFY^IO^COMPLETION.)
INT .EXT:ref
(Use with NOTIFY^IO^COMPLETIONX.)
is a pointer to an IOCB representing an intertask request from a
DEVICE^HANDLER task.
If buffer is omitted, no field of the IOCB is changed. However, if buffer is present,
iocbp.bufaddr[x] is set to the address of buffer.
input
buffer
INT:ref
(Use with NOTIFY^IO^COMPLETION.)
INT .EXT:ref
(Use with NOTIFY^IO^COMPLETIONX.)
is a pointer to a buffer. If buffer is omitted, no field of the IOCB is changed.
Consideration
iocb must reference a real IOCB. If its address is 0, then GDSX stops with internal
error 220.
Example
See the LINE^HANDLER Example Code on page 7-13.
Extended General Device Support (GDSX) Manual—529931-001
8- 51
^OPEN
Service Routines
^OPEN
By calling the ^OPEN procedure, one task can establish a communication path
between all user tasks and a file. ^OPEN may be called whether USCODE is
converted or unconverted.
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as the OPEN procedure in the
Guardian Procedure Calls Reference Manual.
Considerations
•
•
•
•
•
Calling ^OPEN in a nowaited mode causes the calling task to be suspended.
Because the working stack images of tasks are swapped to and from an extended
data segment during I/O operations, I/O must be performed to and from global
buffers.
If the flags parameter is supplied and bit 8 is set for a nowaited call, USCODE
should not issue a subsequent ^AWAITIO. TSCODE takes care of issuing an
AWAITIO to Guardian to return the information to the calling task. No additional
user code is necessary to complete the call.
^OPEN does not support PFS buffering; ^FILE_OPEN_ does support PFS
buffering.
When a user task calls ^OPEN, the resulting open may be private to that task or
public to all tasks in the GDSX process. The distinction made by TSCODE is
based on the address of the filenum parameter passed to ^OPEN: if the address is
local to the task or is in the upper 32K words of the user data segment, the open is
considered private; if the address is in user globals or the buffer pool (anywhere
below %73000), the open is considered public.
Caution. When a user task stops, TSCODE automatically closes all of the task’s private
opens but leaves public opens open, because other tasks may be using them.
•
For the purpose of editing input data, it may be desirable to read disk files within
GDSX. Because the maximum nowait depth for disk files is 1, at most one nowait
I/O can be in process on a single open of a disk file. Multiple tasks use a
semaphore to control access to the publicly opened file in this example:
INT
DISKFILE,
.DISKSEM[0:3],
.DISKNAME[0:11];
.
PROC USER^INITIALIZE(PRIMARY);
INT PRIMARY;
BEGIN
DISKSEM[0] := DISKSEM[1] := DISKSEM[2] := 0;
CALL INIT^SEM(DISKSEM);
IF PRIMARY THEN
Extended General Device Support (GDSX) Manual—529931-001
8- 52
^PROCESS_CREATE_
Service Routines
BEGIN
DISKNAME ':=' ["$XYZ
SOME
FILE
CALL ^OPEN(DISKNAME, DISKFILE, ...);
IF < THEN
BEGIN
.
produce suitable error message
.
CALL ^TERMINATE;!Stop GDSX process
END;
END;
"];
END;
^PROCESS_CREATE_
This procedure creates a new process in a waited or nowait manner, and, optionally,
assigns a symbolic process name to it. Having users call the TSCODE-supported
^PROCESS_CREATE_ procedure rather than the Guardian PROCESS_CREATE_
allows GDSX to maintain a table (PCBTBL) of processes for which it is the creator. By
means of this table, stop or abend system messages received by TSCODE can be
routed to the task that created the process being stopped.
If USCODE is unconverted, the USCODE tasks cannot call this procedure.
Unconverted USCODE must instead call ^NEWPROCESS, the equivalent C-series
service routine. If a task within an unconverted application calls this procedure, filesystem error 29 or 560 is returned.
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as the PROCESS_CREATE_
procedure in the Guardian Procedure Calls Reference Manual.
Considerations
•
•
•
Calling ^PROCESS_CREATE_ in a nowaited mode causes the calling task to be
suspended. Nowaited calls are supported only when creating processes on the
same node.
Because the working stack images of tasks are swapped to and from an extended
data segment during I/O operations, I/O must be performed to and from global
buffers.
If you want USCODE to provide calls to ^AWAITIO[X] in order to wait for I/O
completion on ^DEVICEINFO2, ^FILE_GETINFOBYNAME_, and
^PROCESS_CREATE_ service routines, as would be done for typical nowaited
Guardian procedure calls, you must set the PROCNOWAIT configuration
parameter to 1.
If you want TSCODE to supply AWAITIO[X] calls to complete these nowaited I/Os
on behalf of USCODE, you must set PROCNOWAIT to 0. See PROCNOWAIT on
page 2-70 for more information.
Extended General Device Support (GDSX) Manual—529931-001
8- 53
PROCESS_HANDLE_IS_NULL_
Service Routines
•
•
If a USCODE task calls ^PROCESS_CREATE_ to create a new process when the
number of existing processes is equal to the number defined by the
MAXPROCESSES configuration parameter, a new process is not created. Filesystem error 34 is returned from ^PROCESS_CREATE_.
If a USCODE task calls ^PROCESS_CREATE_, and the created process stops,
abends, or is lost due to a CPU failure, TSCODE receives a process deletion
system message (type -101). If sysmsgs^flag of the CONTROLFLAGS
configuration parameter is set to 1, TSCODE forwards the system message to the
USCODE task that created the process. See the Guardian Procedure Errors and
Messages Manual for the format of the D-series process deletion system message.
Maximum length of the passed message is 97 words.
PROCESS_HANDLE_IS_NULL_
This procedure determines whether the passed-in process handle is a null process
handle.
result := PROCESS_HANDLE_IS_NULL_ ( processhandle );
i
!
returned value
result
INT:value
is the result of the operation. The value of result is one of the following:
-1
The process handle is null (each word of the ten-word buffer is equal to -1)
0
The process handle is not null
processhandle
input
INT .EXT:ref:10
is a pointer to the process handle to be tested.
PROCESS_STOP_
This procedure allows USCODE to stop a process it has created and send a process
deletion system message to the mom of the process and to any other process that is
entitled to receive the message. This procedure allows TSCODE to clean up the
GDSX internal process control block (PCB) before stopping the process. This
procedure is a waited operation.
If USCODE is unconverted, the USCODE tasks cannot call this procedure. If a task
within an unconverted application calls this procedure, file-system error 29 or 560 is
returned. Unconverted USCODE calls the Guardian STOP procedure (not a pseudo
Guardian procedure) to stop a low PIN process by passing the process ID of that
process.
Extended General Device Support (GDSX) Manual—529931-001
8- 54
PSEM
Service Routines
Except for the following consideration, the syntax, condition code settings, and
considerations regarding this procedure are the same as given for the Guardian
procedure in the Guardian Procedure Calls Reference Manual.
Consideration
The PROCESS_STOP_ procedure prohibits an attempt by USCODE to stop the GDSX
process within which the task is running.
PSEM
The PSEM procedure acquires a semaphore associated with a shared resource.
PSEM is not used to acquire a checkpoint semaphore. The checkpoint semaphore is
acquired with the GET^CPSEM procedure.
Caution. Tasks may own multiple semaphores simultaneously; however, GDSX provides no
deadlock detection or resolution mechanism. Do not attempt to obtain a semaphore that you
already own. Doing this causes your task to wait forever for the owner to give it up. To avoid
this, you can compare the first element of the semaphore with the address of your TCB. If they
match, you own the semaphore.
Caution. A task is in an unstoppable state while it owns one or more semaphores. If the task
faults while in an unstoppable state, the primary GDSX process stops.
status := PSEM ( semaphore
i
,[ time ] );
i
!
!
returned value
status
INT:value
indicates the outcome of the call. The value of status is one of the following:
0
There was a timeout before the semaphore was obtained
1
The semaphore was obtained
If the semaphore was found to belong to another task, the following events take
place:
•
•
•
The caller’s TCB is linked onto the semaphore’s wait list.
The caller’s tcb.statex.wait^cause is set to 1.
The task waits on DISP^RESOURCE (see WAIT^EVENT).
Extended General Device Support (GDSX) Manual—529931-001
8- 55
PUTEXTPOOL
Service Routines
input
semaphore
INT:ref
(Semaphore in global memory)
INT(32) .EXT:ref
(Pointer to semaphore in extended memory)
is a pointer to the semaphore to be acquired.
input
time
INT(32):value
specifies the maximum number of ticks (10 ms units) to wait to obtain the
semaphore. If this parameter is omitted, the task waits indefinitely.
Consideration
A task calling this procedure may be suspended.
PUTEXTPOOL
This procedure deallocates space obtained from any of the four extended memory
pools by a call to GETEXTPOOL.
For more information, see Memory Pools on page 2-24.
CALL PUTEXTPOOL ( pool
i
,address );
i
!
!
input
pool
INT:value
indicates which pool to deallocate space for. The value of pool is one of the
following:
1
Shared extended pool
2
Private extended pool
10
Extended buffer pool
11
Extended message pool
input
address
INT(32):value
is the relative extended address of the area to be deallocated. This parameter is
passed by value.
Extended General Device Support (GDSX) Manual—529931-001
8- 56
PUTLOCALPOOL
Service Routines
Example
INT .EXT PTR;
.
.
@PTR := GETEXTPOOL(N, WDS);
.
.
CALL PUTEXTPOOL(N, @PTR);
.
PUTLOCALPOOL
This procedure deallocates space obtained from any of the two local memory pools by
a call to GETLOCALPOOL.
For more information, see Memory Pools on page 2-24.
CALL PUTLOCALPOOL ( pool
i
,buffer );
i
!
!
input
pool
INT:value
indicates which local pool to deallocate space for. The value of pool is one of the
following:
0
Local buffer pool
1
Local message pool
input
buffer
INT:ref
is a pointer to the area to be deallocated.
Example
INT .buf;
@buf := GETLOCALPOOL (0, 100);
.
CALL PUTLOCALPOOL (0, buf);
Q^CP[X]
Once a task calls GET^CPSEM to obtain the checkpoint semaphore, the task can call
Q^CP[X] to copy user-defined data to the TSCODE checkpoint buffer in preparation for
a call to DO^CP or ^CHECKPOINT, either of which copies the buffer to the backup
process.
Extended General Device Support (GDSX) Manual—529931-001
8- 57
Q^CP[X]
Service Routines
The Q^CP procedure moves global data within a user’s named or private global data
block to the checkpoint buffer located in extended memory. The Q^CPX procedure
moves extended memory data to the checkpoint buffer. Up to four data areas can be
moved to the checkpoint buffer with a single call to Q^CP[X].
Multiple calls to Q^CP[X] can be done before calling DO^CP or ^CHECKPOINT.
Q^CP[X] queues data until the number of words in the checkpoint buffer, including
three control words per data area copied, exceeds the size set by the MAXCPSIZE
configuration parameter.
Caution. If the checkpoint buffer overflows or the maximum checkpoint size is reached during
a call to Q^CP[X] from a user exit other than USER^BACKUP, the backup process is
terminated and Q^CP[X] returns 0. To prevent this, ensure that MAXCPSIZE is large enough
(the default size is 4,096 words). If the backup process is terminated, it is still the caller’s
responsibility to release the semaphore with GIVE^CPSEM.
If the checkpoint buffer overflows during a call to Q^CP[X] from the USER^BACKUP
exit, TSCODE automatically writes the current checkpoint buffer to the backup
process.
Caution. If a task owning one or more semaphores stops, the primary GDSX process stops.
If a task owning one or more semaphores faults with the noretn parameter of FAULT equal to
1, the primary GDSX process stops.
Caution. It is recommended that you use ^CHECKPOINT(2) instead of Q^CPX and DO^CP to
checkpoint extended memory buffers. Because DO^CP checkpoints directly across to the
backup process, using Q^CPX and DO^CP to checkpoint extended memory buffers works only
for pool areas allocated in exactly the same area of memory in both the primary and the
backup.
status := Q^CP[X] ( data1
i
,bytes1
i
,[ data2 , bytes2 ]
,[ data3 , bytes3 ]
,[ data4 , bytes4 ] );
!
!
returned value
status
INT:value
indicating whether GDSX is running as a process pair. The value of status is one
of the following:
0
GDSX does not have a backup process
1
GDSX has a backup process
If Q^CP[X] is called from a user exit other than USER^BACKUP and the
checkpoint buffer overflows, the backup process is terminated and 0 is returned in
status.
Extended General Device Support (GDSX) Manual—529931-001
8- 58
Q^CP[X]
Service Routines
input
datai
INT:ref
(Use with Q^CP.)
INT .EXT:ref
(Use with Q^CPX.)
is a pointer containing a word address where data copying should begin.
input
bytesi
INT:value
is the length in words of the data to be copied, starting at datai.
Consideration
Q^CPX may be used to queue an area in extended memory. However, USCODE
seldom needs to use this procedure because ^CHECKPOINT (2) checkpoints all
extended memory acquired.
Examples
1. See the description of the USER^BACKUP on page 9-10 for an example showing
how user global checkpointing can be done when a GDSX process pair is
initialized.
2. This example checkpoints a record read from a disk file:
.
BLOCK USER^PRIVATE;
INT FILE^NUM;
INT AREA[0:11];
STRUCT SEM^TEMPLATE(*);
BEGIN
INT OWNER;
INT HEAD;
INT TAIL;
END;
STRUCT SEM(SEM^TEMPLATE);
END BLOCK;
.
.
PROC DEVICE^HANDLER( );
BEGIN
INT flags,t;
INT DISK^NAME [0:11];
INT readcnt := 20,
cnt := 0;
INT GOTSEM := 0;
DISC^NAME ':=' ["$DISK1
SUBVOLA FILEA
"];
flags := 1;
Extended General Device Support (GDSX) Manual—529931-001
8- 59
Q^CP[X]
Service Routines
GOTSEM := PSEM(SEM);
! PREVIOUSLY INITIALIZED
! IN USER^INITIALIZE
CALL ^FILE_OPEN ( DISK^NAME, FILE^NUM, flags);
IF <> THEN
BEGIN
.
.
Call DEBUG;
! DO ERROR HANDLING
END;
CALL ^READ (FILE^NUM, area, readcnt);
IF <> THEN
BEGIN
CALL VSEM(SEM);
Call DEBUG;
RETURN;
END;
! DO ERROR HANDLING
CALL ^Awaitio(FILE^NUM,@area,cnt);
IF <> THEN
BEGIN
CALL VSEM(SEM);
Call DEBUG;
! DO ERROR HANDLING
END;
!
We can only checkpoint user global variables with Q^CP
t := 0;
CALL GET^CPSEM;
t := Q^CP (area,10,FILE^NUM,1); !We checkpoint
!data read from the disk file and
!file number so the backup process
!user globals are in sync with the
!primary
IF t THEN
CALL DO^CP; ! A DO^CP is done to copy data to the
! the backup process.
CALL GIVE^CPSEM;
IF GOTSEM THEN CALL VSEM(SEM);
.
END;
3. Checkpoints including both global data and task stack may be accomplished as
follows:
INT I^GOT^CP^SEM;
.
.
I^GOT^CP^SEM := GET^CPSEM;
CALL Q^CP(...); !As many as required to checkpoint
!global data
IF ^CHECKPOINT( ) THEN
Extended General Device Support (GDSX) Manual—529931-001
8- 60
^READ[X]
Service Routines
BEGIN
I^GOT^CP^SEM := 0;
.
Do takeover Processing
.
END
ELSE
IF I^GOT^CP^SEM THEN
BEGIN
CALL GIVE^CPSEM;
I^GOT^CP^SEM := 0;
END;
^READ[X]
The ^READ and ^READX procedures return data from an open file to the application
process’s data area. Because the working stack images of tasks are swapped to and
from an extended data segment during I/O operations, I/O must be performed to and
from global buffers.
The syntax, condition code settings, and considerations regarding these two
procedures are the same as the counterparts in the Guardian Procedure Calls
Reference Manual.
^READLOCK[X]
The ^READLOCK and ^READLOCKX procedures sequentially lock and read records
in a disk file, exactly like the combination of LOCKREC and READ[X]. Because the
working stack images of tasks are swapped to and from an extended data segment
during I/O operations, I/O must be performed to and from global buffers.
The syntax, condition code settings, and considerations regarding these two
procedures are the same as the counterparts in the Guardian Procedure Calls
Reference Manual.
^READUPDATE[X]
The ^READUPDATE AND ^READUPDATEX procedures are used by
DEVICE^HANDLER tasks to read messages from the pseudo-$RECEIVE file, and by
LINE^HANDLER tasks to read messages from the $RECEIVE-like file.
Except for the following considerations, the syntax, condition code settings, and
considerations regarding these two procedures are the same as the counterparts in the
Guardian Procedure Calls Reference Manual.
Considerations
•
Because the working stack images of tasks are swapped to and from an extended
data segment during I/O operations, I/O must be performed to and from global
buffers.
Extended General Device Support (GDSX) Manual—529931-001
8- 61
^READUPDATE[X]
Service Routines
•
•
•
^READUPDATE[X] and ^CANCEL are the only two operations that a
LINE^HANDLER may call against the pseudo-$RECEIVE file.
^REPLY[X] should be called after ^READUPDATE[X] to release the IOCB used by
^READUPDATE[X].
To minimize buffer requirements, ^READUPDATE[X] operations can be posted on
the pseudo-$RECEIVE without specifying a buffer address or size. For example:
CALL ^READUPDATE(0);
If ^READUPDATE is called, TSCODE attempts to obtain the buffer in the local
buffer pool. If ^READUPDATEX is called, TSCODE attempts to obtain the buffer in
the extended buffer pool. When a buffer is obtained, its address is stored in
iocb.bufaddr[x], and data is moved from the GDSX $RECEIVE buffer to the buffer
addressed by iocb.bufaddr[x]. (Unlike Guardian I/O handling, TSCODE can modify
the buffer at any point after initiation of the I/O, rather than only at the time the I/O
is completed.) The size of this buffer will be the greater of the pseudo-$RECEIVE
message size and the maximum reply size for the request.
If TSCODE receives a -22 system message (TIME SIGNAL) for the task calling
^READUPDATE[X], the buffer is automatically deallocated by TSCODE. In this
case only, USCODE does not have to deallocate the buffer allocated by TSCODE.
If ^AWAITIO[X] is called after the call to ^READUPDATE[X], TSCODE passes the
address of the buffer back in the buffer buffer-addr parameter to ^AWAITIO[X]. If
WAIT^EVENT and ^LISTEN are called after the call to ^READUPDATE[X],
TSCODE passes the address of the buffer in iocb.bufaddr[x].
Except for the case of a -22 system message, all buffers received by a
^READUPDATE on file 0 must eventually be released by a call to
PUTLOCALPOOL with the pool parameter equal to 0 by the task that completes
the I/O. Buffers received by a ^READUPDATEX on file 0 must eventually be
released by a call to PUTEXTPOOL with the pool parameter equal to 10 by the
task that completes the I/O.
•
When a ^READUPDATE[X] on the pseudo-$RECEIVE that was initiated into a
preallocated buffer (CALL ^READUPDATE[X] (0, BUF, ...)) is subsequently
canceled by ^CANCEL(0), an incoming request may already be in the buffer before
^CANCEL is called. In this instance, TSCODE attempts to obtain space in its
extended data segment and move the request data into that space. If space
cannot be obtained, ^CANCEL replies to the request with FENOBUFSPACE (31).
Internally generated $RECEIVE messages, such as the -64 system message,
cause ^CANCEL to set CCL. A subsequent call to ^FILEINFO(0,ERR) returns
FENOBUFSPACE. In all cases, the task’s READUPDATE[X] on $RECEIVE is
canceled.
Extended General Device Support (GDSX) Manual—529931-001
8- 62
^READUPDATELOCK[X]
Service Routines
Example
This example calls ^READUPDATE on the pseudo-$RECEIVE files, checks for a
completion of the I/O with ^AWAITIO, and processes the buffer.
INT .buf,
cnt,
err,
.rcvbuf,
rcvbufaddr = rcvbuf,
f;
CALL ^READUPDATE(0);
IDLE:
f := -1;
CALL ^AWAITIO(f, rcvbufaddr, cnt);
IF <> THEN
CALL ^FILEINFO(f, err)
ELSE
err := 0;
IF NOT err THEN
IF NOT f THEN BEGIN
.
handle pseudo-$RECEIVE message
.
END
ELSE BEGIN
.
handle I/O completion on other open file
END; .
^READUPDATELOCK[X]
The ^READUPDATELOCK[X] procedures are used for random processing of records
in a disk file. Because the working stack images of tasks are swapped to and from an
extended data segment during I/O operations, I/O must be performed to and from
global buffers.
The syntax, condition code settings, and considerations regarding these two
procedures are the same as the counterparts in the Guardian Procedure Calls
Reference Manual.
^RECEIVEINFO
This procedure obtains the 4-word process ID, message tag, error recovery (sync ID),
and request-related (file number, READ count, and I/O type) information associated
with the last message read from the $RECEIVE file.
If converted, TSCODE receives process handle data instead of process ID data, and
so USCODE tasks cannot call this procedure. Converted USCODE must instead call
Extended General Device Support (GDSX) Manual—529931-001
8- 63
^RECLAIMBUFFER
Service Routines
^FILE_GETRECEIVEINFO_. If USCODE is converted and a user task calls this
procedure, a warning is returned via EMS and the process id returned is invalid.
If sysmsgs^flag of the CONTROLFLAGS configuration parameter is set to 1 and you
call ^RECEIVEINFO after a close message is received, the file number returned is
always 0.
With the use of the iotype parameter, it is possible for USCODE to differentiate
between READ, WRITE, and WRITEREAD operations from the application.
The syntax, condition code settings, and considerations regarding this procedure are
the same as the counterpart in the Guardian Procedure Calls Reference Manual.
^RECLAIMBUFFER
When a task has done a type 2 checkpoint (^CHECKPOINT(2)) and the backup takes
over, it is necessary for the task to recover its memory pool buffer images by calls on
^RECLAIMBUFFER. This procedure allows a task to reallocate memory buffers for
any of the six memory pools after a takeover.
Because the user tasks share the memory pools and would overwrite each other’s data
if they were allowed to checkpoint directly across to corresponding memory pool
addresses for the backup process, pool buffers are checkpointed to a section of the
backup process’s extended memory where each task has a separate, TASKCPSIZEsized area for checkpointing. Therefore, in the event of a takeover, any memory pool
buffer addresses that the task has stored in its data stack are no longer valid.
A task recovers its buffer images by calls on ^RECLAIMBUFFER. This procedure is
passed, by reference, the word pointer to the data as it was allocated in the primary
process. The task’s last checkpoint block in the former backup’s extended memory is
searched for an address match. When one is found, space in the specified buffer pool
is allocated and the data image is copied. Finally, the word pointer in the task’s stack
is updated to point to the new location of the data.
Caution. Following a takeover, if a task does not recover all its buffer images before it does a
type 2 checkpoint, those buffers not reclaimed are lost.
Caution. In the USER^TAKEOVER procedure you cannot remap buffers allocated in the
former primary process (which existed before the takeover) by calling ^RECLAIMBUFFER,
because each active user task must reclaim its own buffers, and no user task is active during
execution of USER^TAKEOVER.
CALL ^RECLAIMBUFFER ( buffer
i,o
,[ pool-number ] );
input, output
buffer
INT(32):ref
Extended General Device Support (GDSX) Manual—529931-001
8- 64
!
! i
^RECLAIMBUFFER
Service Routines
on input, is a pointer to a buffer that you specify is to be reallocated after a
takeover. For extended memory buffers, the address of the pointer must be
passed, for example, @BUF. For local buffers, pass the buffer address as
converted by the TAL procedure $XADR. See the examples later in this
subsection.
On return from ^RECLAIMBUFFER this pointer will contain a new address pointing
to the buffer reallocated from the specified memory pool in the new primary
process.
pool-number
input
INT:value
is the pool number. The value of pool-number is one of the following:
0
Local buffer pool (the default value)
1
Local message pool
3
Shared extended pool
4
Private extended pool
10
Extended buffer pool
11
Extended message pool
The following condition code settings are valid:
=
CCE indicates that the buffer has been reallocated.
<
CCL indicates that no buffer was found whose address matches the one
specified in buffer. Either the caller specified an incorrect address or the
task’s most recent checkpoint was not a type 2 checkpoint. In the latter
case, no matching buffer could be found because the most recent
checkpoint did not include any buffers. The result is that upon takeover the
task loses any buffers that were held by the former primary process.
>
CCG indicates that the specified buffer was found but a buffer to reclaim it
could not be allocated. Either the caller specified an invalid pool number in
pool-number or there is not enough space in the specified or default pool to
allocate the new buffer.
Examples
1. In this example an extended buffer pool buffer is reclaimed:
INT .EXT BUFX := 0D;
@BUFX := GETEXTPOOL(10, 500);
.
IF ^CHECKPOINT(2) THEN
BEGIN
CALL ^RECLAIMBUFFER(@BUFX, 10); !Extended buffer pool
Extended General Device Support (GDSX) Manual—529931-001
8- 65
^REPLY[X]
Service Routines
IF <> THEN ! Did not find it, we're in trouble.
BEGIN
.
.
2. In this example buffer pool and message pool buffers are reclaimed:
INT .BUFF1,
.BUFF2;
INT .EXT XBUFF1,
.EXT XBUFF2;
@BUFF1 := GETLOCALPOOL(0, 100);
@XBUFF1 := $XADR(BUFF1);
@BUFF2 := GETLOCALPOOL(1, 100);
@XBUFF2 := $XADR(BUFF2);
.
IF ^CHECKPOINT(2) THEN
BEGIN
CALL ^RECLAIMBUFFER(@XBUFF1, 0); !buffer pool
IF <> THEN ! Did not find it, we're in trouble.
BEGIN
.
.
END
ELSE
BEGIN ! We reset the pointer with the new address
! from ^RECLAIMBUFFER
@BUFF1 := $LADR(XBUFF1);
END;
CALL ^RECLAIMBUFFER(@XBUFF2, 1); !message pool
IF <> THEN ! Did not find it, we're in trouble.
BEGIN
.
.
END
ELSE
BEGIN ! We reset the pointer with the new address
! from ^RECLAIMBUFFER
@BUFF2 := $LADR(XBUFF2);
END;
.
.
END;
! of Primary Failure and recovery.
^REPLY[X]
The ^REPLY and ^REPLYX procedures send reply messages to messages received
earlier in calls to ^READUPDATE[X] on the pseudo-$RECEIVE file.
Except for the following consideration, the syntax, condition code settings, and
considerations regarding these two procedures are the same as the counterparts in the
Guardian Procedure Calls Reference Manual.
Extended General Device Support (GDSX) Manual—529931-001
8- 66
^RESUMETRANSACTION
Service Routines
Consideration
The ^REPLYX procedure differs from the Guardian counterpart in having a sixth input
parameter, iocb-tag. The procedure syntax is:
CALL ^REPLYX ( [
,[
,[
,[
,[
,[
buffer ]
write-count ]
count-written ]
message-tag ]
error-return ]
iocb-tag ] );
The message-tag parameter is for a message tag returned from ^RECEIVEINFO. The
tag associates this reply with a message previously received. When this parameter is
used, iocb-tag must not be used.
The iocb-tag parameter is declared as an INT(32):value. When used, this parameter
holds the address of the IOCB returned when ^SIGNALTIMEOUT or
^SIGNALINTERRUPT was called. When this parameter is used, message-tag must
not be used.
^RESUMETRANSACTION
This procedure suspends or activates the processing of a TMF transaction. For
example, when TSCODE deactivates a user task that has started a TMF transaction, it
calls ^RESUMETRANSACTION with trans-begin-tag set to 0D to suspend the user
task’s transaction. Before activating the user task, TSCODE calls
^RESUMETRANSACTION with trans-begin-tag set to the transid of the transaction to
give the TMF transaction an active status.
A user task can call ^RESUMETRANSACTION too, but it must own the current
transaction. It is the responsibility of the user task to return the suspended transaction
to active status by calling ^RESUMETRANSACTION with trans-begin-tag set to the
transid of the transaction. The transid of the transaction is stored in the variable
transtag of tcb^template.
A trace record is written after a successful call to ^RESUMETRANSACTION if bit 3 of
trace^control^flags in DCCBDECS is set to 1. The trace records contain the calling
task number of the user task and the TMF transaction identifier of the transaction to
become the current transaction. See Tracing GDSX on page 2-80 for more
information.
Except for the following consideration, the syntax, condition code settings, and
considerations regarding this procedure are the same as the counterpart in the
NonStop TMF Application Programmer’s Guide.
Extended General Device Support (GDSX) Manual—529931-001
8- 67
SEND^ITC^MSG[X]
Service Routines
Consideration
Because GDSX does not support multithreaded user tasks that use TMF,
^RESUMETRANSACTION cannot be used to switch back and forth between different
transactions within one user task.
SEND^ITC^MSG[X]
This procedure initiates two-way communication between:
•
•
•
Two DEVICE^HANDLER tasks
A DEVICE^HANDLER task and a LINE^HANDLER task
Two LINE^HANDLER tasks
When calling the SEND^ITC^MSG[X] procedure, the sending task passes a pointer to
an FCB that contains a TCB address for the receiving task. SEND^ITC^MSG[X]
allocates an IOCB, which contains the TCB address of the calling task, and is linked to
the TCB for the calling task and to the FCB whose address is passed in the call. The
IOCB is also linked into the ITC request queue (addressed externally by
in^queue^file^num) for the receiving task. The intertask I/O initiation is completed by
causing an E^ITC event (assuming that the receiving task has a current
^READUPDATE on its in-queue file) for the receiving task.
The receiving task detects an incoming message by first calling ^READUPDATE[X]
and then calling WAIT^EVENT, which returns E^ITC. A call to ^LISTEN(0, 0, 1)
returns the IOCB address. After the message is processed in the receiving task, a call
to NOTIFY^IO^COMPLETION[X] releases the IOCB and completes the communication
to the sending task that originated the request by calling SEND^ITC^MSG[X].
See Appendix E, Intertask Communication Example for an example of using
SEND^ITC^MSG[X] for intertask communication between two DEVICE^HANDLER
tasks.
CALL SEND^ITC^MSG[X] ( fcb
i
,[ message ]
i
,write-count
i
,read-count
i
,[ tag ]
i
,op-code );
i
!
!
!
!
!
!
input
fcb
INT .EXT:ref
Extended General Device Support (GDSX) Manual—529931-001
8- 68
SEND^ITC^MSG[X]
Service Routines
is a pointer to an FCB corresponding to the calling task’s ITC file or to some other
file to which the I/O is to be linked. At the time of call, this FCB must contain the
TCB address for the receiving task in fcb.lhaddr.
When a DEVICE^HANDLER task is sending a message to a LINE^HANDLER task
that it is configured for, obtain the FCB address for the DEVICE^HANDLER task’s
ITC file by indexing into FCBTBL, the FCB table, with the terminal file number.
The terminal file number is passed when the DEVICE^HANDLER task is created.
Then fcb.lhaddr will already be set to the TCB address of the LINE^HANDLER
task.
In the following cases, the FCB of the receiving task is obtained by calling
GET^ITC^FCB once:
•
•
•
•
A DEVICE^HANDLER task is sending a message to a LINE^HANDLER task
that it is not configured for
A DEVICE^HANDLER task is sending a message to another
DEVICE^HANDLER task
A LINE^HANDLER task is sending a message to a DEVICE^HANDLER task
A LINE^HANDLER task is sending a message to another LINE^HANDLER
task
The FCB returned by GET^ITC^FCB is used for fcb in subsequent calls to
SEND^ITC^MSG[X] to send a message to the receiving task.
input
message
INT:ref
(Use with SEND^ITC^MSG)
INT .EXT:ref
(Use with SEND^ITC^MSGX)
is a pointer to a buffer containing a message.
write-count
input
INT:value
is the number of bytes to write.
read-count
input
INT:value
is the number of bytes to read.
input
tag
INT(32):value
is a tag, usually an IOCB address.
Extended General Device Support (GDSX) Manual—529931-001
8- 69
SEND^ITC^MSG[X]
Service Routines
input
op-code
INT:value
is the operation to perform. The value of op-code is one of the following:
0
System message
1
WRITE
2
READ
3
WRITEREAD
4
CONTROL
5
SETMODENOWAIT
6
READUPDATE
7
READLOCK
8
READUPDATELOCK
9
LOCKREC
10
UNLOCKREC
11
OPEN
12
WRITEUPDATE
13
WRITEUPDATEUNLOCK
14
ENDTRANSACTION
15
SIGNALTIMEOUT
16
NEWPROCESS
17
DEVICEINFO2
18
SERVERCLASS_SEND_
19
LOCKFILE
20
UNLOCKFILE
21
SETPARAM
The following condition settings are valid:
=
CCE indicates that the I/O operation was successfully initiated.
<
CCL indicates a file error greater than 9.
>
CCG indicates a file error in the range 0-9.
Extended General Device Support (GDSX) Manual—529931-001
8- 70
^SERVERCLASS_DIALOG_ABORT_
Service Routines
^SERVERCLASS_DIALOG_ABORT_
The ^SERVERCLASS_DIALOG_ABORT_ pseudo context-sensitive Pathway
procedure allows USCODE to abort a specified dialog.
The syntax, condition code settings, and considerations regarding this procedure are
the same as given for the Pathway SERVERCLASS_DIALOG_ABORT_ procedure in
the NonStop TS/MP Pathsend and Server Programming Manual.
^SERVERCLASS_DIALOG_BEGIN_
The ^SERVERCLASS_DIALOG_BEGIN_ pseudo context-sensitive Pathway
procedure allows USCODE to initiate a dialog with a server process in a server class
and to send the first message to it.
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as given for the Pathway
SERVERCLASS_DIALOG_BEGIN_ procedure in the NonStop TS/MP Pathsend and
Server Programming Manual.
Considerations
•
•
•
•
Because the working stack images of tasks are swapped to and from an extended
data segment during I/O operations, the I/O must be performed to and from
extended buffers.
When calling the ^SERVERCLASS_DIALOG_BEGIN_ procedure in the waited
mode, processing is returned to the calling USCODE after a reply is received from
the server. This calling method causes all user tasks to wait until a reply is
received.
When calling the ^SERVERCLASS_DIALOG_BEGIN_ procedure in the nowaited
mode with the PROCNOWAIT configuration parameter set to 0, TSCODE calls
^AWAITIOX to complete the I/O, waits for the reply, and then sends the reply to the
user task. Only the user task that called the ^SERVERCLASS_DIALOG_BEGIN_
procedure waits for the reply. All other user tasks continue processing.
When calling the ^SERVERCLASS_DIALOG_BEGIN_ in the nowaited mode with
the PROCNOWAIT configuration parameter set to 1, USCODE must call
^AWAITIOX instead of ^AWAITIO to complete the I/O. Do not use WAIT^EVENT
and ^LISTEN to complete the I/O.
Calling ^SERVERCLASS_DIALOG_BEGIN_ in the nowaited mode allows
USCODE to continue processing while ^SERVERCLASS_DIALOG_BEGIN_ is
executing.
•
A trace record is written before and after a successful call to
^SERVERCLASS_DIALOG_BEGIN_ if bit 3 of trace^control^flags in DCCBDECS
is set to 1. The trace records contain the calling task number, PATHMON name,
server class name, buffer, server class send operation number and the dialog ID
used with this procedure.
Extended General Device Support (GDSX) Manual—529931-001
8- 71
^SERVERCLASS_DIALOG_END_
Service Routines
^SERVERCLASS_DIALOG_END_
The ^SERVERCLASS_DIALOG_END_ pseudo context-sensitive Pathway procedure
allows USCODE to end a dialog initiated by a previous call to the
^SERVERCLASS_DIALOG_BEGIN_ procedure.
The syntax, condition code settings, and considerations regarding this procedure are
the same as given for the Pathway SERVERCLASS_DIALOG_END_ procedure in the
NonStop TS/MP Pathsend and Server Programming Manual.
^SERVERCLASS_DIALOG_SEND_
The ^SERVERCLASS_DIALOG_SEND_ pseudo context-sensitive Pathway procedure
allows USCODE to communicate directly with server classes in a context-sensitive
manner.
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as given for the Pathway
SERVERCLASS_DIALOG_SEND_ procedure in the NonStop TS/MP Pathsend and
Server Programming Manual.
Considerations
•
•
•
•
Because the working stack images of tasks are swapped to and from an extended
data segment during I/O operations, the I/O must be performed to and from
extended buffers.
When calling the ^SERVERCLASS_DIALOG_SEND_ procedure in the waited
mode, processing is returned to the calling USCODE after a reply is received from
the server. This calling method causes all user tasks to wait until a reply is
received.
When calling the ^SERVERCLASS_DIALOG_SEND_ procedure in the nowaited
mode with the PROCNOWAIT configuration parameter set to 0, TSCODE calls
^AWAITIOX to complete the I/O, waits for the reply, and then sends the reply to the
user task. Only the user task that called the ^SERVERCLASS_DIALOG_SEND_
procedure waits for the reply. All other user tasks continue processing.
When calling the ^SERVERCLASS_DIALOG_SEND_ in the nowaited mode with
the PROCNOWAIT configuration parameter set to 1, USCODE must call
^AWAITIOX instead of ^AWAITIO to complete the I/O. Do not use WAIT^EVENT
and ^LISTEN to complete the I/O.
Calling ^SERVERCLASS_DIALOG_SEND_ in the nowaited mode allows
USCODE to continue processing while ^SERVERCLASS_DIALOG_SEND_ is
executing.
•
A trace record is written before and after a successful call to
^SERVERCLASS_DIALOG_SEND_ if bit 3 of trace^control^flags in DCCBDECS is
set to 1. The trace records contain the calling task number, PATHMON name,
Extended General Device Support (GDSX) Manual—529931-001
8- 72
^SERVERCLASS_SEND_
Service Routines
server class name, buffer, server class send operation number and the dialog ID
used with this procedure.
^SERVERCLASS_SEND_
This procedure allows USCODE to communicate directly with TS/MP server classes
through LINKMON. See Appendix D, Using Pseudo Procedures in a TS/MP
Environment for an example of using this procedure.
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as its counterpart in the NonStop
TS/MP Pathsend and Server Programming Manual.
Considerations
•
•
Because the working stack images of tasks are swapped to and from an extended
data segment during I/O operations, I/O must be performed to and from extended
buffers.
When calling ^SERVERCLASS_SEND_ in the waited mode, processing is
returned to the calling USCODE after a reply is received. The reply is sent from
the server within the specified server class.
This calling method causes all TSCODE and USCODE tasks to wait until a reply is
received from the server, which suspends the processing of the GDSX process.
Because of this dramatic reduction in performance, you should avoid calling
^SERVERCLASS_SEND_ in the waited mode. The best alternative is to call
^SERVERCLASS_SEND_ in the nowaited mode.
•
When calling ^SERVERCLASS_SEND_ in the nowaited mode with the
PROCNOWAIT configuration parameter set to 0, TSCODE calls ^AWAITIOX to
complete the I/O, waits for the reply, and then sends the reply to the user task.
Only the user task that called ^SERVERCLASS_SEND_ waits for the reply. All
other user tasks continue processing.
In this case, the value of the actual-reply-len parameter of
^SERVERCLASS_SEND is returned if you provided this parameter. See the
NonStop TS/MP Pathsend and Server Programming Manual for more information.
•
When calling ^SERVERCLASS_SEND_ in the nowaited mode with the
PROCNOWAIT configuration parameter set to 1, USCODE must call ^AWAITIOX
instead of ^AWAITIO to complete the I/O. Do not use WAIT^EVENT and ^LISTEN
to complete the I/O.
Calling ^SERVERCLASS_SEND_ in the nowaited mode allows USCODE to
continue processing while ^SERVERCLASS_SEND_ is executing.
•
A trace record is written before and after a successful call to
^SERVERCLASS_SEND_ in the waited mode if bit 3 of trace^control^flags in
DCCBDECS is set to 1. (When ^SERVERCLASS_SEND_ is called in the
nowaited mode, no trace record is written for the reply from the server.) The trace
Extended General Device Support (GDSX) Manual—529931-001
8- 73
^SERVERCLASS_SEND_INFO_
Service Routines
records contain the calling task number, PATHMON process name, server class
name, buffer, and server class send operation number used with this procedure.
See Tracing GDSX on page 2-80 for more information.
^SERVERCLASS_SEND_INFO_
This procedure allows USCODE to retrieve information about the last initiated or
completed call to ^SERVERCLASS_SEND_INFO_ directly from TS/MP server classes.
See Appendix D, Using Pseudo Procedures in a TS/MP Environment for an example of
using this procedure.
When the return status of ^SERVERCLASS_SEND_ is 233, indicating an error with the
call, you should can call ^SERVERCLASS_SEND_INFO_ to receive additional
Pathsend and file-system error information.
If the return status of ^SERVERCLASS_SEND_ is 0, the call was successful. If you
call ^SERVERCLASS_SEND_INFO_ in this case, Pathsend and the file system also
return a value of 0.
The syntax, condition code settings, and considerations regarding this procedure are
the same as the counterpart in the NonStop TS/MP Pathsend and Server
Programming Manual.
^SETMODE
This procedure is used to set device-dependent functions.
A call to the SETMODE procedure is rejected with an error indication if nowait
operations are pending on the specified file.
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as the counterpart in the
Guardian Procedure Calls Reference Manual.
Considerations
Because the working stack images of tasks are swapped to and from an extended data
segment during I/O operations, I/O must be performed to and from global buffers.
^SETMODENOWAIT
This procedure sets device-dependent functions in a nowait manner on nowait files.
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as the counterpart in the
Guardian Procedure Calls Reference Manual.
Extended General Device Support (GDSX) Manual—529931-001
8- 74
^SETMYTERM
Service Routines
Considerations
•
•
•
•
Because the working stack images of tasks are swapped to and from an extended
data segment during I/O operations, I/O must be performed to and from global
buffers.
Some applications may require the monitoring of 3270 device status by a call to
^SETMODENOWAIT with function code 53. In this case, the param2 parameter is
not passed on to AM3270. Instead, TSCODE passes the task number of the
caller. Then, when a type -21 system message is received by GDSX, it may route
the message to the proper task.
When a task owns break and a break occurs, the -20 system message is routed to
that task by way of $RECEIVE. The user task must issue ^SETMODENOWAITs to
restore the terminal to break and/or normal access.
Param1 is necessary for ITC files else an error FEMissParam is returned
^SETMYTERM
This procedure allows a task to change the object name of its corresponding SU or
LINE. If the task is converted, the DCB or LINE name and name length is updated in
the control block. If the task is not converted, only the DCB or LINE name is updated.
CALL ^SETMYTERM ( object-name
i
,[ filenum ]
o
,length ] );
i
object-name
!
!
!
input
INT:ref:16
is the SCF object name (not the access name). This SU or LINE name is assigned
to the variable name in the dcb^template or the lcb^template, depending on
whether the calling task is a DEVICE^HANDLER task or LINE^HANDLER task,
respectively.
filenum
output
INT:ref
is the number of the file to which the calling task is associated. This is drawn from
the variable term in tcb^template, and is the same as the terminal file number or
the LINE file number for a DEVICE^HANDLER task or LINE^HANDLER task,
respectively.
Extended General Device Support (GDSX) Manual—529931-001
8- 75
^SETPARAM
Service Routines
input
length
INT:value
(Use when the task is converted)
is the length in bytes of the SCF object name to be set. If the task is converted,
the 16-word buffer must contain a name in external format. If the name is less
than 32 characters, the remaining buffer space must be filled with spaces.
If the task is unconverted, this parameter is not supplied. The length of the object
name is always assumed to be 24 bytes.
The following condition code settings are valid:
=
CCE indicates that the operation was successful.
<
CCL indicates that the object name cannot be changed, or the proposed name is
invalid. This code is returned if the task is converted and the length parameter is
not supplied, or is less than 1 or greater than 32. (If the task is unconverted, this
parameter is not supplied.)
>
CCG does not return from this procedure.
^SETPARAM
This procedure is used to set and fetch various values such as the station
characteristics of network addresses. The operation can be performed in a nowait
manner by use of the nowait-tag parameter and in that case is completed by a call
to AWAITIO[X].
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as the counterpart in the
Guardian Procedure Calls Reference Manual.
Considerations
•
•
•
Because the working stack images of tasks are swapped to and from an extended
data segment during I/O operations, I/O must be performed to and from global
buffers.
When calling ^SETPARAM in nowaited mode with PROCNOWAIT configuration
parameter set to 1, USCODE must call AWAITIOX to complete the I/O.
When calling ^SETPARAM in nowaited mode with PROCNOWAIT configuration
parameter set to 0, TSCODE calls AWAITIOX to complete the I/O.
^SHUTDOWN
This procedure stops the primary and backup GDSX processes after all outstanding
task I/Os from or to external openers have been completed and all external openers
have been closed or terminated. However, SCF is the exceptional case among
Extended General Device Support (GDSX) Manual—529931-001
8- 76
^SIGNALINTERRUPT
Service Routines
external openers. You can issue SCF commands against GDSX during and after the
shutdown process.
CALL ^SHUTDOWN
Considerations
•
When ^SHUTDOWN is called, all active LINEs and SUs are queried to determine
whether they have external openers. If no external openers exist, then the primary
and backup GDSX processes are stopped and an EMS event message is
generated indicating that a shutdown occurred. The message is as follows:
STATUS *1002* GDS NORMAL SHUTDOWN
If there are external openers, the tasks are allowed to complete current I/Os from
or to the openers, and the tasks continue to exist until all external openers are
closed, or until SCF ABORT LINE and/or ABORT SU commands are issued. In
the interim, an EMS event message notifies you that a shutdown is in progress
(pending) and that the GDSX process will be stopped only after all external
openers are closed or terminated. The message is as follows:
STATUS *1006* GDS SHUTDOWN PENDING
During this interval all new open attempts against the GDSX process are rejected,
except those from SCF.
•
•
You can still issue an SCF INFO TASK command on a LINE or SU to determine its
tcb.state.<1> value after ^SHUTDOWN is called. If this bit is set to 1, the task is in
the stop-pending state, meaning that it will die after all its openers are closed.
Once all the openers are closed or terminated, the primary and backup GDSX
processes are stopped.
A call to ^SHUTDOWN is the same as issuing the following SCF STOP command:
STOP PROCESS $GDSX-process-name
•
A call to ^TERMINATE is the same as issuing the SCF STOP command with an
exclamation point:
STOP PROCESS $GDSX-process-name !
^SIGNALINTERRUPT
The ^SIGNALINTERRUPT entry point for the ^SIGNALTIMEOUT procedure sets a
timer to a given number of units of elapsed time. When the time expires, the calling
task receives an indication in the form of a system message on $RECEIVE in the case
of a DEVICE^HANDLER task or on $RECEIVE in the case of a LINE^HANDLER task.
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as the SIGNALTIMEOUT
procedure in the Guardian Procedure Calls Reference Manual.
Extended General Device Support (GDSX) Manual—529931-001
8- 77
^SIGNALTIMEOUT
Service Routines
Considerations
•
•
•
•
Because the working stack images of tasks are swapped to and from an extended
data segment during I/O operations, I/O must be performed to and from global
buffers.
The tag parameter of ^SIGNALINTERRUPT holds the address of the IOCB
allocated when ^SIGNALTIMEOUT or ^SIGNALINTERRUPT was called. It is an
INT(32) variable.
^SIGNALINTERRUPT sets CCL if an IOCB cannot be allocated.
The entry point ^SIGNALINTERRUPT within ^SIGNALTIMEOUT modifies
^SIGNALTIMEOUT’s typical handling of the resultant system message. Suppose
that a signal initiated by ^SIGNALINTERRUPT pops. When the -22 system
message is queued for the task and the task is currently in a timed wait condition
(timeout-value is not equal to -1D), and waiting for some resource (such as buffer
space or an IOCB), the task is prematurely removed from the timed-wait list and
dispatched.
Here is an example:
Time 0:
^SIGNALINTERRUPT is called with timeout-value = 5
seconds.
Time 2
seconds:
GETLOCALPOOL is called to obtain buffer space with
timeout-value = 6 seconds. Space is not currently available.
Time 5
seconds:
Signal pops. The task is redispatched and GETLOCALPOOL
returns 0, indicating a timeout, even though the task had only
waited 3 seconds for buffer space.
At this point, the task may obtain the -22 system message by a call on ^AWAITIO.
^SIGNALTIMEOUT
This procedure sets a timer to a given number of units of elapsed time. When the time
expires, the calling task receives an indication in the form of a system message (-22)
on $RECEIVE for either a DEVICE^HANDLER task or a LINE^HANDLER task.
Caution. When using WAIT^EVENT to detect timeout events resulting from calls to
^SIGNALTIMEOUT, release the IOCB allocated by TSCODE, or the IOCB table may
eventually be exhausted, generating an error 32. See the examples following.
Except for the following considerations, the syntax, condition code settings, and
considerations regarding this procedure are the same as the counterpart in the
Guardian Procedure Calls Reference Manual.
Extended General Device Support (GDSX) Manual—529931-001
8- 78
^SIGNALTIMEOUT
Service Routines
Considerations
•
•
•
•
Because the working stack images of tasks are swapped to and from an extended
data segment during I/O operations, I/O must be performed to and from global
buffers.
The tag parameter of ^SIGNALTIMEOUT holds the address of the IOCB allocated
when ^SIGNALTIMEOUT or ^SIGNALINTERRUPT was called. It is an INT(32)
variable.
^SIGNALTIMEOUT sets CCL if an IOCB cannot be allocated.
The entry point ^SIGNALINTERRUPT within ^SIGNALTIMEOUT may be used to
modify the handling of the resultant system message. See the preceding
description of the ^SIGNALINTERRUPT on page 8-77.
Examples
1. This example uses ^AWAITIO[X] to handle a timeout:
CALL ^READUPDATE ( 0 );
IF <> THEN CALL DEBUG;
! DO ERROR HANDLING
CALL ^SIGNALTIMEOUT ( 100D, , , IOCBADDR );
IF < THEN
BEGIN
! NO IOCB AVAILABLE
END
ELSE IF > THEN
BEGIN
! CODING BUG: TIMEOUT PARAMETER ILLEGAL
END;
! WAIT FOR A COMPLETION ON ANY FILE
F := -1;
CALL ^AWAITIO ( F, @WAIT^BUFFER, CNT );
IF <> THEN
CALL ^FILEINFO ( F, ERR )
ELSE
ERR := 0;
IF NOT F THEN
BEGIN
! handle pseudo-$RECEIVE message
IF WAIT^BUFFER[0] = -22 THEN
BEGIN
! HANDLE SIGNALTIMEOUT
! BUFFER ALLOCATED BY TSCODE NEED NOT BE RELEASED
CALL REPLYX( , , , , , IOCBADDR );
! DO OTHER PROCESSING AS DESIRED
END
! HANDLE SIGNALTIMEOUT
ELSE
! A DIFFERENT $RECEIVE MESSAGE?
.
END
ELSE
! handle I/O completion on other open file
.
Extended General Device Support (GDSX) Manual—529931-001
8- 79
STOP^TASK
Service Routines
2. This example uses WAIT^EVENT to handle a timeout:
CALL ^READUPDATE ( 0 );
IF <> THEN CALL DEBUG;
! DO ERROR HANDLING
CALL ^SIGNALTIMEOUT ( 100D, , , IOCBADDR);
IF < THEN
BEGIN
! NO IOCB AVAILABLE
END
ELSE IF > THEN
BEGIN
! CODING BUG: TIMEOUT PARAMETER ILLEGAL
END;
! WAIT FOR ALL EVENT TYPES FOR 500 TICKS
EVENT := WAIT^EVENT ( -1, 500D );
! ONLY LISTEN FOR $RECEIVE-TYPE REQUESTS
@LOCAL^IOCB := ^LISTEN ( 1, 0, 0 );
@WAIT^BUFFER := LOCAL^IOCB.BUFADDR;
IF EVENT = 0 AND WAIT^BUFFER[0] = -22 THEN
BEGIN
! HANDLE SIGNALTIMEOUT
! BUFFER ALLOCATED BY TSCODE NEED NOT BE RELEASED
CALL REPLYX( , , , , , IOCBADDR );
! DO OTHER PROCESSING AS DESIRED
END;
! HANDLE SIGNALTIMEOUT
! HANDLE OTHER EVENT TYPES
STOP^TASK
Any task can call this procedure to stop itself and deallocate TCB, IOCBs, FCBs and
other resources, such as all of the task’s allocations from the memory pools. Any
devices or processes opened against this task receive a file-system error 66. Any I/O
not yet completed is canceled. The USER^STOP exit is called, allowing you to clean
up any remaining work. If there is a backup process, it is updated.
CALL STOP^TASK
Consideration
If a user task detects an E^STOP event by a call to WAIT^EVENT, the task should call
STOP^TASK.
TAKEBREAK
A task calls this procedure to take break ownership of the terminal it controls. To
release break ownership, call GIVEBREAK.
The BREAKENABLED configuration parameter determines whether user tasks can
take break ownership by the TAKEBREAK procedure. If BREAKENABLED is set to 1,
user tasks can successfully call the TAKEBREAK procedure. Otherwise, calls to
TAKEBREAK return file-system error 99.
Extended General Device Support (GDSX) Manual—529931-001
8- 80
TCBADDR
Service Routines
When a task owns break and a break occurs, the -20 system message is routed to that
task by the pseudo-$RECEIVE file. It is the responsibility of the task to issue
^SETMODENOWAITs to restore the terminal to break access or normal access.
The Guardian break facility does not allow multiple openers in the same process to
pass break ownership back and forth. Therefore, only one task at a time within a
GDSX process may own break for a particular terminal. This may be ensured by
preconfiguring all terminals with the ASSOCIATIVE attribute set or by setting the
ASSOCIATIVE configuration parameter for the GDSX process itself.
CALL TAKEBREAK
Consideration
If GDSX is being run as a process pair, a task calling this procedure will be suspended
if during the execution of the procedure in TSCODE the checkpoint semaphore is not
obtained immediately.
The following condition code settings are valid:
=
CCE indicates that the task now owns break for its terminal.
<
CCL indicates that an I/O error occurred on the SETPARAM 3 issued by
TSCODE to take break ownership. The error number can be obtained by calling
^FILEINFO. Error 99 is returned if the BREAKENABLED configuration
parameter was not equal to 1.
>
CCG indicates that the calling task already owns break.
TCBADDR
Given a task’s TCB number, this procedure returns the address of the TCB. If you do
not have the task’s TCB number, you may find it more efficient to obtain the TCB
address by means of the DCB that corresponds to the task. See the example for the
procedure WRITE^ITC^MESSAGE[X] on page 8-90.
address := TCBADDR ( task-number );
i
!
returned value
address
INT(32):value
is the returned address of the TCB. If task-number is less than 1 or greater than
the value of the MAXTASKS configuration parameter, address is equal to 0.
task-number
input
INT:value
Extended General Device Support (GDSX) Manual—529931-001
8- 81
^TERMINATE
Service Routines
is the TCB number of a task, a value from 1 through the value of MAXTASKS.
Tasks 0 and 1 are always the monitor and listener system tasks.
Note. Specifying a task-number value less than 1 or greater than the value of MAXTASKS
causes the current task to fault with an EMS message.
Example
This code may be used to scan the TCB pool:
t1 := 2;
!We start at 2 because tcb[0] & tcb[1] are always
!system tasks
WHILE (t1 <= MAXTSKS) do
BEGIN
tcb^addr := TCBADDR(t1);
.
Do desired processing here
.
t1 := t1 + 1
END;
^TERMINATE
This procedure stops the primary and backup GDSX processes without waiting for
outstanding task I/Os from or to external openers to be completed and without waiting
for external openers to be closed.
When this procedure is called, all active LINEs and SUs are queried to determine
whether they have external openers. If no external openers exist, the primary and
backup GDSX processes are stopped after an EMS event message is generated
indicating that the GDSX process was terminated by you. The message is as follows:
STATUS *1005* GDS USER TERMINATED
If there are external openers when this procedure is called, an error 66 is returned to
all the openers, indicating that the “device“ has been downed. Then the preceding
EMS message is generated, and the primary and backup GDSX processes are
stopped.
CALL ^TERMINATE
Considerations
•
A call to ^TERMINATE is the same as issuing the SCF STOP command with an
exclamation point:
STOP PROCESS $GDSX-process-name !
•
A call to ^SHUTDOWN is the same as issuing the following SCF STOP command:
STOP PROCESS $GDSX-process-name
Extended General Device Support (GDSX) Manual—529931-001
8- 82
^UNLOCKREC
Service Routines
^UNLOCKREC
This procedure unlocks a record currently locked by the task.
The syntax, condition code settings, and considerations regarding this procedure are
the same as the counterpart in the Guardian Procedure Calls Reference Manual.
USER^CLOSE^TRACE^FILE
This procedure causes TSCODE to close the trace file in extended memory. After the
trace file is closed, TSCODE does not generate trace entries for the file, and USCODE
is not allowed to generate trace entries for the file by calls to ADD^TRACE^DATA or
ADD^TRACE^DATA^INT.
status := USER^CLOSE^TRACE^FILE
returned value
status
INT:value
indicates the outcome of the call. The value of status is one of the following:
-1
The trace file is already closed
0
Successful close
USER^OPEN^TRACE^FILE
This procedure causes TSCODE to allocate an extended segment for a trace file,
which is saved as TRACEP by a primary process or as TRACEB by a backup process.
After the trace file is open, depending on settings of auto^trace^flag of the
DEBUGFLAGS configuration parameter and the trace^control^flags in DCCBDECS,
TSCODE automatically generates trace entries for the file.
You can also generate trace entries by calling ADD^TRACE^DATA or
ADD^TRACE^DATA^INT. Calling USER^CLOSE^TRACE^FILE closes the trace file
and prevents further entries.
Note. TSCODE does not generate trace records until the USER^INITIALIZE exit has been
called, so USER^OPEN^TRACE^FILE need not be called until then.
status := USER^OPEN^TRACE^FILE ( [ record-size ]
i
,[ segment-size ]
i
,[ record-count ] );
i
status
returned value
INT:value
Extended General Device Support (GDSX) Manual—529931-001
8- 83
!
!
!
VSEM
Service Routines
indicates the outcome of the call. The value of status is one of the following:
-1
The trace file could not be opened
0
Successful open
1
The trace file is already open
record-size
input
INT:value
specifies the maximum size of each record added to the trace file. The default is
256 words and the maximum is 16,383 words.
segment-size
input
INT:value
specifies the number of extent pages. Segment-size must be less than or equal to
64. The default is 64.
record-count
input
INT(32):value
specifies the maximum number of records that can be generated for the trace file
before the entries wrap. The default is 4,096D and the maximum is 32,000D.
Example
See the examples included with the description of the procedure ADD^TRACE^DATA
on page 8-7.
VSEM
This procedure releases a noncheckpoint semaphore so that other tasks can use the
associated resource. The checkpoint semaphore is released with the GIVE^CPSEM
procedure.
Any error-handling or special handling after accessing a resource should be done
before calling VSEM. When a task calls VSEM, TSCODE verifies that the caller owns
the semaphore, then checks the semaphore’s wait list. If this list is not empty, the first
task on the list is given the semaphore and an E^RESOURCE event is caused for the
task.
CALL VSEM ( semaphore );
i
Extended General Device Support (GDSX) Manual—529931-001
8- 84
!
WAITED^IO[X]
Service Routines
input
semaphore
INT:ref
(Semaphore in global memory)
INT(32) .EXT:ref
(Pointer to semaphore in extended memory)
is a pointer to the semaphore to be released.
WAITED^IO[X]
The WAITED^IO and WAITED^IOX procedures perform a waited I/O, even if there are
other I/O operations outstanding.
Note. This operation is waited only from the perspective of the calling task—it is not a waited
I/O from the perspective of the GDSX process. In other words, calling this procedure causes
the calling task to be suspended, but other tasks are not suspended as a result of such a call.
WAITED^IO[X] performs a WRITE, READ, or WRITEREAD depending on the values
of writecount and readcount. If writecount is 0 and the file is not a process file, a
READ is done. If readcount is 0 a WRITE is done, otherwise a WRITEREAD is
performed.
CALL WAITED^IO[X] ( file
i
,buffer
i
,writecount
i
,readcount
i
,countxfered
i
,timeout );
i
!
!
!
!
!
!
input
file
INT:value
specifies the file number for the operation.
input
buffer
INT:ref
(use with WAITED^IO.)
INT .EXT:ref
(use with WAITED^IOX.)
is a pointer to the buffer to be transferred.
writecount
input
INT:value
Extended General Device Support (GDSX) Manual—529931-001
8- 85
WAIT^EVENT
Service Routines
specifies the number of bytes to write.
input
readcount
INT:value
specifies the number of bytes to read.
output
countxfered
INT:ref
(use with WAITED^IO.)
INT .EXT:ref
(use with WAITED^IOX.)
is a pointer to the number of bytes transferred. The number of bytes is passed by
AWAITIO[X], which is used to implement this procedure.
input
timeout
INT(32):value
specifies the number of ticks (10 ms) to wait for the I/O to complete.
Consideration
The procedure sets condition codes in the same manner as AWAITIO. ^FILEINFO
may be called to retrieve error information.
WAIT^EVENT
Instead of using ^AWAITIO[X], which tests only for I/O completions, a multithreaded
DEVICE^HANDLER or LINE^HANDLER task uses the WAIT^EVENT procedure to
check for I/O completions and other asynchronous events. When you specify a set of
event types to look for, WAIT^EVENT returns an indication of which of those types of
events has occurred. The ^LISTEN procedure can then be used to get the address of
any associated IOCB, which in turn can be used to locate the message buffer (as was
done in the control block tracing exercise in Section 5, DEVICE^HANDLER Example,
Design). TSCODE does not automatically move data from an IOCB to a message
buffer when WAIT^EVENT is called as it does when ^READUPDATE is called on a
pseudo-$RECEIVE file.
When the WAIT^EVENT procedure is called, control is transferred to TSCODE, which
checks to see if certain events have occurred. The events to be checked are specified
in a bit-encoded mask passed to TSCODE along with a timeout parameter. If one of
these events occurs within the timeout period, TSCODE awakens the calling task and
returns the lowest numbered masked event that has occurred (see the third column of
Table 8-1 on page 8-5). Each call to WAIT^EVENT clears the event returned while
retaining those of lower priority That is, those with higher event numbers.
Extended General Device Support (GDSX) Manual—529931-001
8- 86
WAIT^EVENT
Service Routines
The event descriptions and the global literals (declared in DCCBDECS(ERRORS))
used by TSCODE to define the events are listed in Table 8-2 on page 8-87. Events
having an IOCB associated with them are marked in the fourth column of the table.
Table 8-2. Events Detected With WAIT^EVENT
Literal
Constant
Associate
d IOCB
Event Description
Literal Identifier
No event: timeout occurred
E^TIMEOUT
0
Request that task call STOP^TASK
E^STOP
1
Resume processing
E^CONTINUE
2
Intertask message or I/O canceled
E^CAN
3
X
Message arrived from $RECEIVE
E^IMSG
4
X
Intertask message arrived
E^ITC
5
X
Completion of I/O other than $RECEIVE
and intertask message
E^IOC
6
X
Resource is available
E^RESOURCE
7
Device added, deleted, altered, started, or
stopped
E^CHANGE
8
After TSCODE passes a value to the task to indicate what event occurred, if the event
has an IOCB associated with it, the task can call ^LISTEN to get a pointer to the IOCB.
Caution. Be careful when you are programming tasks that call both WAIT^EVENT and
^AWAITIO[X], because when the two procedures are used together, ^AWAITIO[X] can “lose“
events. For an example, see the caution in the description of ^AWAITIO[X].
event := WAIT^EVENT ( mask
i
,timeout );
i
event
!
!
returned value
INT:value
indicates a timeout or a masked event that was detected. Event is set to 0 if a
timeout occurred; otherwise, it is set to 16 minus the bit number representing the
event which occurred. See the following DISP-list for the bit numbers.
When more than one event occurred, the calling task is notified of the masked
event with the highest bit number. Therefore, when multiple events occur, multiple
calls to WAIT^EVENT are required to handle them. Each call to WAIT^EVENT
clears the event returned while retaining those of lower priority. That is, those with
lower bit numbers.
Extended General Device Support (GDSX) Manual—529931-001
8- 87
WAIT^EVENT
Service Routines
input
mask
INT:value
is a bit mask specifying those events to be detected. Following are global literals
(declared in the errors section of DCCBDECS) that may be used to set bits in the
mask parameter, along with the corresponding event value returned if the event is
detected:
Mask Event Literal
Binary Value
Bit Number
Corresponding event
Value Returned
DISP^STOP
%B1
15
1
DISP^CONTINUE
%B10
14
2
DISP^CANCEL
%B100
13
3
DISP^IMSG
%B1000
12
4
DISP^ITC
%B10000
11
5
DISP^IOC
%B100000
10
6
DISP^RESOURCE
%B1000000
9
7
DISP^CHANGE
%B10000000
8
8
You can define bits 1 through 7 to create other events to be detected. If bit 0 is
turned on, all other bits in the word are considered to be turned on too. If new
events are created in this way, the WAKE^TASK procedure can be used to cause
the events on another task. See the description of the event parameter in
Table 8-2 on page 8-87 for information on what values are returned for created
events.
To determine the mask value, choose the events you wish to test for (see
Table 8-2) and then add together the corresponding literals from the preceding
DISP-list to set the mask parameter, as shown in the following example:
CALL ^READUPDATE(IN^QUEUE^FILE^NUM);
IF (EVENT := WAIT^EVENT(DISP^ITC + DISP^STOP +..)) = E^ITC
OR EVENT = E^STOP THEN
BEGIN
IF EVENT = E^ITC THEN
BEGIN
@IOCB := ^LISTEN(0,0,1);
.
process the request
.
CALL NOTIFY^IO^COMPLETION(IOCB . .);
END
ELSE
IF EVENT = E^STOP THEN
.
When more than one event is detected by WAIT^EVENT, the calling task is notified
of the masked event with the highest bit number from the DISP-list.
Extended General Device Support (GDSX) Manual—529931-001
8- 88
WAKE^TASK
Service Routines
input
timeout
INT(32):value
specifies the number of ticks (10 ms) to wait for any masked event to complete,
after which the E^TIMEOUT event is returned. The value of timeout is one of the
following:
-1D
Task waits indefinitely
-2D
Task waits the time remaining from the previous call to WAIT^EVENT
Consideration
This procedure suspends the calling task.
Examples
See the two calls to WAIT^EVENT, one in the CANCEL^ITC subprocedure and one in
the main entry, in the LINE^HANDLER of USKELEX (see Appendix B, USKELEX and
USKELEXC Listings).
WAKE^TASK
This procedure allows any task to cause an event for any other task that has posted a
WAIT^EVENT.
CALL WAKE^TASK ( tcb
i
,cause );
i
!
!
input
tcb
INT .EXT:ref
is a pointer to the TCB for the task that is to receive the event.
input
cause
INT:value
is the event to be posted. Any of the following events can be posted against the
target task:
Literal
Constant
Event Description
Literal Identifier
No event: timeout occurred
E^TIMEOUT
0
Request that task call STOP^TASK
E^STOP
1
Resume processing
E^CONTINUE
2
Intertask message or I/O canceled
E^CAN
3
Extended General Device Support (GDSX) Manual—529931-001
8- 89
Associate
d IOCB
X
^WRITE[X]
Service Routines
Literal
Constant
Associate
d IOCB
E^IMSG
4
X
Intertask message arrived
E^ITC
5
X
Completion of I/O other than
$RECEIVE and intertask message
E^IOC
6
X
Resource is available
E^RESOURCE
7
Device added, deleted, altered, started,
or stopped
E^CHANGE
8
Event Description
Literal Identifier
Message arrived from $RECEIVE
Events with corresponding constant values from 9-15 can also be defined by you,
and caused for a task with this procedure. Events 9, 10, 11, 12, 13, 14, 15
correspond with WAIT^EVENT mask bits 7, 6, 5, 4, 3, 2, 1, respectively. See the
description of the mask and event variables for the procedure WAIT^EVENT on
page 8-86.
Example
CALL WAKE^TASK(HIS^TCB, E^IOC);
^WRITE[X]
The ^WRITE and ^WRITEX procedures write data from an array to an open file.
Because the working stack images of tasks are swapped to and from an extended data
segment during I/O operations, I/O must be performed to and from global buffers.
The syntax, condition code settings, and considerations regarding these two
procedures are the same as the counterparts in the Guardian Procedure Calls
Reference Manual.
WRITE^ITC^MESSAGE[X]
The WRITE^ITC^MESSAGE and WRITE^ITC^MESSAGEX procedures initiate oneway communication between any two tasks. Because the working stack images of
tasks are swapped to and from an extended data segment during I/O operations, I/O
must be performed to and from global buffers.
When calling this procedure, the sending task passes a pointer to a TCB for the task to
receive the message. The procedure allocates an IOCB, which is linked into the
receiving task’s ITC request queue if the task is a LINE^HANDLER task, or into the
receiving task’s pseudo-$RECEIVE file if the task is a DEVICE^HANDLER task. The
intertask I/O initiation is completed by causing the receiving task’s E^IMSG event
(assuming that, if the task is a DEVICE^HANDLER task, it has a current
^READUPDATE on its pseudo-$RECEIVE file, or if the task is a LINE^HANDLER task,
it has a current ^READUPDATE on its in-queue file).
Note. The sending task does not have to call ^AWAITIO[X] after it calls
WRITE^ITC^MESSAGE[X].
Extended General Device Support (GDSX) Manual—529931-001
8- 90
WRITE^ITC^MESSAGE[X]
Service Routines
If the receiving task is a LINE^HANDLER task, it detects the message by a call to
WAIT^EVENT, which returns E^IMSG. A call to ^LISTEN(1, 0, 0) returns the IOCB
address. After the message is processed, a call to DEALLOCATEIOCB releases the
IOCB.
If the receiving task is a DEVICE^HANDLER task, the message is picked up either with
a call to ^AWAITIO[X], or with a call to WAIT^EVENT, as described previously.
CALL WRITE^ITC^MESSAGE[X] ( tcb
i
,buffer
i
,write-count );
i
!
!
!
input
tcb
INT .EXT:ref
is a pointer to the TCB for the destination task.
input
buffer
INT:ref
(Use with WRITE^ITC^MESSAGE.)
INT .EXT:ref
(Use with WRITE^ITC^MESSAGEX.)
is a pointer to a buffer containing a message.
write-count
input
INT:value
is the number of bytes to write.
The following condition code settings are valid:
=
CCE indicates that the write operation was successfully initiated.
<
CCL indicates either an unsuccessful attempt to allocate an IOCB, or a file error.
Example
This example sends a buffer from one DEVICE^HANDLER task to all other
DEVICE^HANDLER tasks:
INT
INT
INT
INT
INT
.EXT DEST^DCB (DCB^TEMPLATE);
.EXT MY^TCB (TCB^TEMPLATE);
.EXT DEST^TCB (TCB^TEMPLATE);
SIZE;
.BUF;
SIZE := 13;
Extended General Device Support (GDSX) Manual—529931-001
8- 91
^WRITEREAD[X]
Service Routines
@BUF := GETLOCALPOOL(0, SIZE); !Get a buffer.
I := 2; ! TCB #0 and #1 are always the monitor and listener
! tasks, so we start at I=2.
@MY^DCB := DCBTBL[INTERNAL^TERM^NO];
@MY^TCB := MY^DCB.TCBADDR;
! MAXTSKS is a GLOBAL configuration parameter.
WHILE @DEST^TCB := TCBADDR(I) <= MAXTSKS DO
BEGIN
IF @DEST^TCB <> @MY^TCB THEN ! We only want to send
! a buffer to user tasks other
! than ourself
BEGIN
!SEE DCCBDECS file for DEFINES
IF DEST^TCB.STATE.ACTIVE^BIT AND
DEST^TCB.STATE.TASK^TYPE <= 15 THEN
BEGIN ! 0 thru 15 are D^H tasks.
! We don't want L^H tasks either.
BUF ':=' "HELLO, THERE, DEVICE TASK!";
CALL WRITE^ITC^MESSAGE(DEST^TCB, BUF, SIZE*2);
END;
END;
I := I + 1;
END; !of WHILE DO
PUTLOCALPOOL(BUF); !Release buffer.
.
.
^WRITEREAD[X]
The ^WRITEREAD and ^WRITEREADX procedures write data from an array to a file,
and then waits for data to be transferred back from the file. Because the working stack
images of tasks are swapped to and from an extended data segment during I/O
operations, I/O must be performed to and from global buffers.
The syntax, condition code settings, and considerations regarding these two
procedures are the same as the counterparts in the Guardian Procedure Calls
Reference Manual.
^WRITEUPDATE[X]
The ^WRITEUPDATE and ^WRITEUPDATEX procedures transfer data from an array
to an open file.
The syntax, condition code settings, and considerations regarding these two
procedures are the same as the counterparts in the Guardian Procedure Calls
Reference Manual.
Consideration
If the file number is in the ITC range, the ^WRITEUPDATE[X] request is routed to an
associate task by calling the SEND^ITC^MSG[X] procedure.
Extended General Device Support (GDSX) Manual—529931-001
8- 92
^WRITEUPDATEUNLOCK[X]
Service Routines
^WRITEUPDATEUNLOCK[X]
The ^WRITEUPDATEUNLOCK and ^WRITEUPDATEUNLOCKX procedures perform
random processing of records in the disk file.
The syntax, condition code settings, and considerations regarding these two
procedures are the same as the counterparts in the Guardian Procedure Calls
Reference Manual.
Consideration
•
If the file number is in the ITC range, the ^WRITEUPDATEUNLOCK[X] request is
routed to an associate task by calling the SEND^ITC^MSG[X] procedure.
Extended General Device Support (GDSX) Manual—529931-001
8- 93
Service Routines
^WRITEUPDATEUNLOCK[X]
Extended General Device Support (GDSX) Manual—529931-001
8- 94
9
User Exit Descriptions
User exits are the USCODE procedures that are called by TSCODE to allow you to
customize a GDSX process. All GDSX applications need a DEVICE^HANDLER
procedure to provide the application-specific logic. You include stubs, such as those
provided in the USKEL file of the installed subvolume, for all user exits that are not
customized. To prepare a source file with all the user exits, you may modify the
USKELEX, USKELEXC, or USAMPLE example files, or write your code starting with
USKELC.
User Exit Routines
Following is a list of the supported exit routines. After the list there is an alphabetically
ordered reference section containing a description of each user exit.
DEVICE^HANDLER
USER^INITIALIZE
LINE^HANDLER
USER^INIT^CONFIG^PARAMS
PROCESS^ASSIGNS
USER^REPLIES
PROCESS^USER^PARAMS
USER^START
USER^ATTRIBUTES
USER^STOP
USER^BACKUP
USER^TAKEOVER
USER^COMMANDS
USER^VERSION
TSCODE calls user exits in the following order at primary process startup time:
1. USER^INIT^CONFIG^PARAMS
2. PROCESS^ASSIGNS (called only if an ASSIGN command is entered at the TACL
prompt)
3. PROCESS^USER^PARAMS (called only if a USERPARAM command is entered
at the TACL prompt)
4. USER^VERSION
5. USER^INITIALIZE
If GDSX is run as a process pair, the backup process for TSCODE calls the same five
user exits in the same order. In the primary process TSCODE checkpoints data to the
backup and calls USER^BACKUP. Finally, if at some later time the primary process
dies, the new primary, which was formerly the backupprocess, calls
USER^TAKEOVER, followed by USER^BACKUP.
Extended General Device Support (GDSX) Manual—529931-001
9 -1
DEVICE^HANDLER
User Exit Descriptions
DEVICE^HANDLER
This procedure is typically used to modify the communication of each thread between a
requester and another file (often a terminal). Running copies of DEVICE^HANDLER
code are called DEVICE^HANDLER tasks.
A DEVICE^HANDLER task is created by a call to the DEVICE^HANDLER procedure
as follows:
1. When TSCODE receives and processes an SCF START SU command, or when
the first open message is received by TSCODE for an SU, TSCODE opens the file
to which the SU is mapped.
2. The SU file is opened for nowait I/O (the OPEN flags parameter is set to a value
that is greater than or equal to 1).
3. TSCODE assigns the opened file a file number, an actual Guardian file number or
an ITC file number, and passes the file number when calling DEVICE^HANDLER.
Each request sent from a DEVICE^HANDLER task to a subdevice under a LINE does
not go directly to the subdevice. The I/O operation is sent first to the LINE^HANDLER
task associated with the subdevice. Nevertheless, the DEVICE^HANDLER task sends
I/O to the file number, just as it would if there were no LINE^HANDLER. TSCODE
handles the routing of the message to the LINE^HANDLER.
PROC DEVICE^HANDLER ( filenum
i
,internal-number
i
,terminal-type );
i
!
!
!
input
filenum
INT:value
is the file number or ITC file number of the file that the DEVICE^HANDLER task is
to handle. The file is often a terminal. When this user exit is called, TSCODE has
already opened this file with the flags parameter of OPEN set to a value that is
greater than or equal to 1, and assigned filenum, which is the same as the actual
Guardian file number if the corresponding SU is not configured under a LINE.
internal-number
input
INT:value
is the unique GDSX internal number for the file associated with this task. This
number may be used to identify the file in user-generated log messages, and may
also be used as an index into an array of pointers to the DCB table. (The DCB
may be used to access information about the file associated with this task.)
Extended General Device Support (GDSX) Manual—529931-001
9 -2
LINE^HANDLER
User Exit Descriptions
terminal-type
input
INT:value
is the terminal type, which may be used to inform the task of the type of terminal it
is to support or the subset of DEVICE^HANDLER code that the task is to execute.
Use of terminal-type is completely application-dependent. TSCODE does not
use this variable.
The value passed by TSCODE is zero, unless the file to be handled is
preconfigured by an SCF ADD and/or ALTER command with an SUTYPE attribute
specified as a different type. For example, the following SCF command could be
used to add an SU with SU type 3, causing TSCODE to pass 3 as the value of
terminal-type when DEVICE^HANDLER is called:
-> ADD SU $GDSX.#LX.T1, SUTYPE 3
Considerations
•
•
This procedure operates in an infinite loop to process requests.
By setting a DEVICE^HANDLER task’s tcb.statex flag (bits <0:3>) to a nonzero
value, you can make the task unstoppable.
LINE^HANDLER
This procedure is typically used to allow each requester thread to use a shared
resource, often a communications line, without allowing the threads to interfere with
each other. Running copies of LINE^HANDLER code are called LINE^HANDLER
tasks.
A LINE^HANDLER task is created by a call to the LINE^HANDLER procedure as
follows:
1. When TSCODE receives and processes an SCF START LINE command,
TSCODE opens the file associated with the LINE and assigns the actual Guardian
file number to the filenum, to be used by the LINE^HANDLER task to address
the file.
2. TSCODE also creates a $RECEIVE-like file with address receive-number for
the LINE^HANDLER task to use when picking up messages from the
DEVICE^HANDLER tasks mapped to the LINE^HANDLER task.
3. TSCODE then calls the LINE^HANDLER procedure, thereby creating a
LINE^HANDLER task to manage the LINE.
When calling the LINE^HANDLER procedure, TSCODE passes filenum and
receive-number, along with internal-number, which is an index that may be
used to find the LCB for this LINE in the LINE table.
A DEVICE^HANDLER associated with an SU on a LINE directs its I/O to the subdevice
to which it is mapped by using filenum. Recognizing filenum as an ITC file
Extended General Device Support (GDSX) Manual—529931-001
9 -3
LINE^HANDLER
User Exit Descriptions
number, TSCODE pseudo procedures redirect the I/O operations to the in-queue file
for the associated LINE^HANDLER task. A DEVICE^HANDLER task never needs to
know the receive-number.
All I/O with the IOP controlling a LINE is identified by filenum.
PROC LINE^HANDLER ( filenum
i
,internal-number
i
,receive-number );
i
!
!
!
input
filenumr
INT:value
is the Guardian file number for the file managed by this LINE^HANDLER task.
When this procedure is called, TSCODE has already opened this file with the
flags parameter of OPEN set to a value greater than or equal to 1.
internal-number
input
INT:value
is the unique GDSX internal number for the file associated with this task. This
number may be used to identify the file in user-generated log messages, and may
also be used as an index to find this LINE’s LCB in the LINE table.
receive-number
input
INT:value
is a file number for a pseudo-$RECEIVE file used by this LINE^HANDLER task to
receive requests from DEVICE^HANDLER tasks.
Considerations
•
•
•
•
This procedure operates in an infinite loop to process requests.
When starting up, the LINE^HANDLER should call ^READUPDATE against
receive-number.
^READUPDATE[X] and ^CANCEL are the only two operations that a
LINE^HANDLER may issue against receive-number.
The following intertasking communication procedures are commonly used within a
LINE^HANDLER for multithreaded processing of I/O:
^LISTEN
NOTIFY^IO^COMPLETION[X]
WAIT^EVENT
WAKE^TASK
Extended General Device Support (GDSX) Manual—529931-001
9 -4
PROCESS^ASSIGNS
User Exit Descriptions
PROCESS^ASSIGNS
This routine processes ASSIGN messages sent to GDSX at process startup time,
giving you the chance to retrieve information from external ASSIGN commands issued
from the TACL prompt. TSCODE calls this procedure once for each ASSIGN message
in effect at startup time. If there are no ASSIGN messages in effect, it is not called.
The ASSIGN message structure is presented in the Guardian Programmer’s Guide.
PROC PROCESS^ASSIGNS ( message );
i
!
input
message
INT:ref
is a pointer to the ASSIGN system message.
Considerations
•
The USER^INIT^CONFIG^PARAMS, PROCESS^ASSIGNS,
PROCESS^USER^PARAMS, and USER^VERSION user exits are called very
early in the GDSX initialization process. Buffer pools and task and file
management structures have not been initialized. Consequently, within these exits
TSCODE-supported service procedures should not be called, except for the
following:
BIT^MAP
INIT[X]LIST
BIT^RESET
INIT^SEM
BIT^SET
^SHUTDOWN
BIT^TEST
^TERMINATE
Wait until USER^INITIALIZE to call other service routines.
•
•
During execution of PROCESS^ASSIGNS, buffers may be allocated from memory
pools, but when this procedure is exited, the buffers are no longer available.
The TSCODE-supported FAULT procedure cannot be called from this exit because
the monitor task, which handles the EMS messages, does not exist when
PROCESS^ASSIGNS is executing.
PROCESS^USER^PARAMS
This routine allows you to process the PARAM message sent to GDSX at process
startup time, giving you the chance to retrieve information from external PARAM
commands issued at the TACL prompt. This procedure provides a way to process
user-defined parameters. PROCESS^USER^PARAMS is called once for each user
parameter that is defined.
Extended General Device Support (GDSX) Manual—529931-001
9 -5
PROCESS^USER^PARAMS
User Exit Descriptions
A PARAM message received by TSCODE contains a parameter string that is scanned
for configuration parameters. During the scan, each time TSCODE encounters a
parameter name that begins with “USERPARAM,” PROCESS^USER^PARAMS is
called with a pointer to the parameter string byte that indicates the length of the
parameter name. If “USERPARAM” is not encountered when TSCODE scans a
PARAM message, PROCESS^USER^PARAMS is not called.
See the Guardian Programmer’s Guide for more information on the structure of the
PARAM message and its parameter string.
PROC PROCESS^USER^PARAMS ( parameter );
! i
input
parameter
STRING:ref:*
is a pointer to the first byte of the string that contains the user parameter name and
value specified by the USERPARAM command. Offsets within the string are as
follows:
Byte 0
parm-len , the length in bytes of the user
parameter name
Byte 1 for parm-len
User parameter name, any character string
from 1 to 5 bytes long
Byte (parm-len+1)
value-len, the length in bytes of the value
of the user parameter
Byte (parm-len +2) for valuelen
Value given to the user parameter name
Considerations
•
•
The USER^INIT^CONFIG^PARAMS, PROCESS^ASSIGNS,
PROCESS^USER^PARAMS, and USER^VERSION user exits are called very
early in the GDSX initialization process. Buffer pools and task and file
management structures have not been initialized. Consequently, within these exits
TSCODE-supported service procedures should not be called, except for the
following:
BIT^MAP
INIT[X]LIST
BIT^RESET
INIT^SEM
BIT^SET
^SHUTDOWN
BIT^TEST
^TERMINATE
During execution of PROCESS^USER^PARAMS, buffers may be allocated from
memory pools, but when this procedure is exited, the buffers are no longer
available.
Extended General Device Support (GDSX) Manual—529931-001
9 -6
USER^ATTRIBUTES
User Exit Descriptions
•
The TSCODE-supported FAULT procedure may not be called from this exit,
because the monitor task, which handles the EMS messages, does not exist when
this exit is executing.
Example
Suppose the following command is entered at a TACL prompt before GDSX is started:
> PARAM USERPARAMCODE4 44600HW
where the user parameter name is “CODE4” and its value is 44600HW. When
TSCODE scans the parameter string and finds “USERPARAM,”
PROCESS^USER^PARAMS is called. USCODE is passed the address of the string
containing these characters:
14USERPARAMcode4744600HW
and can then process the parameter string.
For another example, see Appendix B, USKELEX and USKELEXC Listings for the
USKELEX PROCESS^USER^PARAMS procedure, which defines a table containing
two user parameters, USERPARM1 and USERPARM2.
USER^ATTRIBUTES
This integer function provides a way you to validate or modify TSCODE-supported
attributes for SCF ADD SU and ALTER SU commands before TSCODE processes the
commands.
USER^ATTRIBUTES is called by TSCODE whenever it receives a message from SCF
indicating that an ADD SU or ALTER SU command was issued with a specification for
one of the following attributes:
ACCESSNAME
NOWAITDEPTH
ASSOCIATIVE
PHYSRECLEN
AUTOSTOP
SUTYPE
DEVICESUBTYPE
USERDATA
DEVICETYPE
This procedure can examine the STRUCT whose address is given by the tokenvalue parameter and validate or modify attribute values. Some or all of these
attributes can be set or reset from USER^ATTRIBUTES instead of from SCF. Only
after USER^ATTRIBUTES processing is complete does TSCODE carry out its
processing for the ADD or ALTER command.
EXTSUSIZE is a configuration parameter that is only modifiable by means of a TACL
PARAM command or an assignment within the user exit
USER^INIT^CONFIG^PARAMS. After USER^INIT^CONFIG^PARAMS is called,
TSCODE allocates memory for the device control blocks, based on the value of
EXTSUSIZE. EXTSUSIZE is then fixed for the life of the process. Modification within
Extended General Device Support (GDSX) Manual—529931-001
9 -7
USER^ATTRIBUTES
User Exit Descriptions
USER^ATTRIBUTES is impossible, because at that point memory for the DCBs has
already been allocated. Also, because SCF messages are picked up only after this
allocation is complete, changing EXTSUSIZE by means of SCF is impossible.
See the SCF Reference Manual for GDSX for more information on these attributes.
status := USER^ATTRIBUTES ( scf-command
i
,su-object-type
i
,request-object-name
i
,token-code
i
,token-value );
i
!
!
!
!
!
returned value
status
INT:value
is the returned value. The value of status is generated by a TAL RETURN
statement in USCODE and is one of the following:
0
The token was anticipated and the token value returned is correct
-1
An error occurred
scf-command
input
INT:value
indicates the SCF command for this request. The value of scf-command is one of
the following:
5003
ADD command
5006
ALTER command
su-object-type
input
INT:value
is the SU object type, and is always equal to 21.
request-object-name
input
INT:ref:12
is the object name for this request, a two- or three-level name specified in the ADD
or ALTER command. For example, $GDSX.#IOP1.TERM1 is the object name in
the following command:
-> ADD SU $GDSX.#IOP1.TERM1
Extended General Device Support (GDSX) Manual—529931-001
9 -8
USER^ATTRIBUTES
User Exit Descriptions
input
token-code
INT(32):value
is the SCF token code. The value of token-code is one of the following:
150929409
ADD SU command
150929411
ALTER SU command
token-value
input
INT:ref
is a pointer to a STRUCT containing attribute values. When this
USER^ATTRIBUTES is called by TSCODE, attribute variables in this STRUCT
contain spaces unless they have been set by means of an SCF ADD or ALTER
command (spaces in INT variables will equal 8224). USER^ATTRIBUTES code
may change the values of the variables except the one associated with the
EXTSUSIZE configuration parameter.
A sample STRUCT is shown later in this subsection.
Considerations
•
•
•
•
The TSCODE-supported FAULT procedure should only be called from the
USER^ATTRIBUTES exit with its noretn parameter equal to 0. See the
description of FAULT on page 8-22.
USER^ATTRIBUTES is an integer function called only by TSCODE, never by
USCODE. USCODE returns function values to TSCODE with the TAL RETURN
statement. The permissible returned function values are described under the
status variable above.
This procedure is called from the monitor task.
Pseudo procedures may be called from this procedure.
Example
Here is an example of a STRUCT pointed to by the value in token-value:
STRUCT TOKEN^VALUE;
BEGIN
STRUCT
Z^ACCESSNAME;
BEGIN
STRUCT
Z^DISC;
BEGIN
STRUCT
Z^VOLUME;
BEGIN STRING BYTE [0:7]; END;
STRUCT
Z^SUBVOLUME;
BEGIN STRING BYTE [0:7]; END;
STRUCT
Z^FILENAME;
BEGIN STRING BYTE [0:7]; END;
Extended General Device Support (GDSX) Manual—529931-001
9 -9
USER^BACKUP
User Exit Descriptions
END;
END;
INT Z^EXT^SU^SIZE;
! NOT USER MODIFIABLE
INT Z^ASSOC;
INT Z^AUTOSTOP;
INT Z^NOWAIT^DEPTH;
INT Z^SUTYPE;
INT Z^USER^DATA[0:127];
END;
USER^BACKUP
USER^BACKUP allows you to checkpoint global data that is required for successful
takeover in the event of failure.
If GDSX is run as a process pair, at startup time the primary GDSX process
checkpoints the following to the backup process:
•
•
•
•
•
•
•
•
Config^params^template of configuration parameters
File control blocks
Task control blocks
Receive control blocks
Line control blocks
Device control blocks
Process control blocks
Logical device control blocks
See Fault Tolerance on page 2-28 for more information on the fault-tolerance
processing at startup time.
After this data is checkpointed, TSCODE’s backup task (task 3) in the primary GDSX
process calls USER^BACKUP, giving you the opportunity to checkpoint your own
global data declared in a named or private global data block.
If at some later time the primary process dies, in the new primary, which was formerly
the backup process, calls USER^TAKEOVER, followed by USER^BACKUP.
The USER^BACKUP procedure is only called once in the life of a GDSX primary
process.
PROC USER^BACKUP
Considerations
•
The TSCODE-supported FAULT procedure should only be called from the
USER^BACKUP exit with its noretn parameter equal to 0. See the description of
the FAULT on page 8-22.
Extended General Device Support (GDSX) Manual—529931-001
9- 10
USER^BACKUP
User Exit Descriptions
•
Pseudo procedures may be called from this procedure.
Example
Here is an example of USER^BACKUP code that checkpoints data input at a terminal.
Obtaining the checkpoint semaphore is not necessary, because TSCODE is not
checkpointing and no user task exists. Also, calling DO^CP is not necessary, because
after exiting USER^BACKUP a DO^CP is done automatically by the backup task.
BLOCK USER^PRIVATE;
INT AREA[0:11];
END BLOCK;
.
PROC USER^BACKUP;
BEGIN
INT t, flags;
INT TRM1 [0:11];
INT .Buffer;
INT writecnt := 20,
cnt := 0;
TRM1 ':=' ["$SURF
",8 * ["
"]];
flags := 1;
CALL ^open ( TRM1, t, flags );
IF <> THEN Call DEBUG;
@buffer := GETLOCALPOOL (0 , 10);
buffer ':=' ["Takeover!>", 5 * ["
! DO ERROR HANDLING
"]];
CALL ^WRITE (t, buffer, writecnt);
IF <> THEN
BEGIN
CALL PUTLOCALPOOL (0,buffer);
Call DEBUG;
RETURN;
END;
CALL ^Awaitio(t, @buffer, cnt);
IF <> THEN
BEGIN
CALL PUTLOCALPOOL (0,buffer);
Call DEBUG;
END;
! DO ERROR HANDLING
! DO ERROR HANDLING
area ':=' buffer for 20; !copy data to user global area
!Note: buffer gotten with GETLOCALPOOL
!is checkpointed with ^checkpoint(2)
!if so desired (not done here).
!
We checkpoint only user global variables with Q^CP!
t := Q^CP (area,10);
! CALL DO^CP is not necessary because after exiting
Extended General Device Support (GDSX) Manual—529931-001
9- 11
USER^COMMANDS
User Exit Descriptions
! USER^BACKUP a DO^CP is done automatically by backup task.
CALL PUTLOCALPOOL (0,buffer);
END;
USER^COMMANDS
This procedure is called from the monitor task when it receives an SPI command with
an unrecognized token from a TACL process or from an external management
application other than SCF. This procedure provides a way for you to define your own
SPI commands.
status := USER^COMMANDS ( iocb
i
,file-error
o
,spi-code );
o
!
!
!
returned value
status
INT:value
is the returned value. The value of status is generated by a TAL RETURN
statement in the user code and can be one of the following:
0
The standard response is all right (that is, the user code does not have any
extra information to return in a response buffer).
1
The user exit formatted the response buffer and there is no need for
TSCODE to supply any response.
input
iocb
INT .EXT:ref
is a pointer to the IOCB containing information about the incoming SPI request,
including iocb.bufaddr[x], the address of the token buffer.
file-error
output
INT:ref
is the returned file-system error code related to this request.
spi-code
output
INT:ref
is the returned SPI error code for this SPI request. Supplying this value is
necessary if you want TSCODE to format the response. A value of -1 means that
this command is invalid.
Extended General Device Support (GDSX) Manual—529931-001
9- 12
USER^COMMANDS
User Exit Descriptions
Considerations
•
•
•
•
•
•
The TSCODE-supported FAULT procedure should only be called from the
USER^COMMANDS exit with its noretn parameter equal to 0. See the
description of the FAULT procedure in FAULT on page 8-22.
USER^COMMANDS is an integer function called only by TSCODE, never by
USCODE. USCODE returns function values to TSCODE with the TAL RETURN
statement. The permissible returned function values are described under the
status variable above.
Pseudo procedures may be called from this procedure.
You should modify the I/O buffer pointed to by iocb.bufaddr[x] only with DSM
procedures (SSPUT, SSGET, and so on). See the SPI Programming Manual.
Other references that may be helpful are:
°
°
°
GDS Management Programming Manual
TACL Reference Manual
Event Management Service (EMS) Manual
If you prepare a response to the SPI command, the address of the response buffer
must be in iocb.bufaddr[x] on return from this procedure.
If required, a DEVICE^HANDLER or LINE^HANDLER can be coded to handle
user-defined SPI tokens and notify other user tasks.
Example
This example sends a broadcast message to a GDSX process by means of the SPI
interface. After GDSX receives the message, it is passed to the USER^COMMANDS
exit, where user-supplied code can handle the message.
The example uses a TACL routine in a file called TELLGDS. (The three files
necessary for running this example—TELLGDS, UTACLIB, and USERDDL—are not
included in the installed subvolume; they are listed following these instructions.)
Before running TELLGDS, UTACLIB, which contains macros and routines invoked by
TELLGDS, must be loaded, the make^segment macro must be executed at a TACL
prompt, and a named GDSX process must be running. Directions for running the
example follow.
The make^segment macro loads in ZSPITACL, ZCOMTACL and a file named
ZGDSTACL for Basic GDS (if you use Extended GDS, change the file name to
ZGDXTACL ). Make sure that these files are correctly qualified in the macro definition
in the UTACLIB file.
Then at the first terminal, called $TERM1 in this example, enter:
> LOAD /KEEP 1/ UTACLIB
> MAKE^SEGMENT
Extended General Device Support (GDSX) Manual—529931-001
9- 13
USER^COMMANDS
User Exit Descriptions
At a second terminal, called $TERM2 in this example, start a GDSX process using
RUND and set a breakpoint at #USER^COMMANDS to view incoming TACL SPI
messages.
> RUND GDSE /NAME $UGDS, NOWAIT/
INSPECT - Symbolic Debugger - T9673C20 - (10JUL89)
Copyright Tandem Computers Incorporated 1983, 1985-1989
INSPECT
077,06,124 $UGDS
#GDS.#1366(SMAIN)
- $UGDS-B #USER^COMMANDS
- $UGDS-SOURCEON
- $UGDS-RESUME
> PAUSE
At $TERM1, run the TACL routine TELLGDS. Enclose the text you want to send to
GDSX in quotation marks as shown in this example:
> RUN TELLGDS $UGDS "anything you want to send to GDSX"
Terminal $TERM2 will show a breakpoint at USER^COMMANDS. You must code your
own message-handling logic in the USER^COMMANDS procedure.
Figure 9-1 shows the listing of the TELLGDS file used in this example.
Extended General Device Support (GDSX) Manual—529931-001
9- 14
USER^COMMANDS
User Exit Descriptions
Example 9-1. Listing of TELLGDS File (page 1 of 4)
?TACL ROUTINE
==
== This TACL routine ("TELLGDS") sends a broadcast message to
== a GDSX process via the SPI interface. It is invoked as follows:
==
==
RUN TELLGDS <GDSX-process-name> "Quoted-string"
==
attach^definitions
#FRAME
#PUSH procname text
SINK [#ARGUMENT/VALUE procname/PROCESSNAME] == Get the arguments
verify^process [procname] == Needed due to bug in #ARGUMENT
SINK [#ARGUMENT/VALUE text/STRING]
SINK [#ARGUMENT END] == NO MORE
#PUSH #USELIST
#PUSH err retcode
#SET #USELIST :GDSX [#USELIST]
#DEF ssid STRUCT LIKE zgds^val^ssid;
#SET ssid [zspi^val^tandem].[zspi^ssn^zgds].[zgds^val^version]
#DEF spibuf STRUCT LIKE zgds^ddl^msg^buffer;
spicmd #SSINIT spibuf [ssid] [ugds^cmd^tell] /OBJECT zcom^obj^null/
spicmd #SSPUT spibuf [zcom^tkn^objname] [_LONGEST [procname]] [procname]
spicmd #SSPUT spibuf [ugds^tkn^text] [text]
spi^open [procname]
spi^send spibuf
spi^close
spicmd #SSPUT spibuf zspi^tkn^reset^buffer zgds^val^buflen
#SETMANY err _ retcode,[#SSGET /INDEX 1/ spibuf zspi^tkn^retcode]
[#IF [err]
|THEN| leave^routine Error [err] on SSGET
]
[#IF (retcode <> zspi^err^ok)
|THEN| leave^routine [gds^error [retcode]]
]
#UNFRAME
The UTACLIB file for this example contains:
?SECTION xeq MACRO
==
== Macro to display and execute whatever was passed
==
#OUTPUT >%*%
%*%
?SECTION spi^error ROUTINE
==
== Routine to return the text of an SPI error
==
Extended General Device Support (GDSX) Manual—529931-001
9- 15
USER^COMMANDS
User Exit Descriptions
Example 9-1. Listing of TELLGDS File (page 2 of 4)
#FRAME
#PUSH err
SINK [#ARGUMENT/VALUE err/NUMBER]
[#RESULT SPI error: [#CASE [err]
|-1| Invalid buffer format
|-2| Illegal parameter value
|-3| Missing parameter
|-4| Illegal parameter address
|-5| Buffer full
|-6| Invalid checksum
|-7| Internal error
|-8| List token not found
|-9| Illegal token code or map
|-10| Invalid subsystem id
|-11| Operation not supported
|-12| Insufficient stack space
|OTHERWISE| Unknown error [err]
]
]
#UNFRAME
?SECTION leave^routine MACRO
== Exit the the current routine with an error message
== Callable only from within a routine
#OUTPUT %*% == Display any message that was passed
#UNFRAME
== Clean up the stack
#RETURN
== Exit to routine's caller
?SECTION gds^error ROUTINE
==
== Routine to return the text of an GDSX error
==
#FRAME
#PUSH err
SINK [#ARGUMENT/VALUE err/NUMBER]
[#RESULT GDSX error: [#CASE [err]
|1| Object name unknown
|2| Object state invalid
|3| Attempt to add too many objects
|4| Attribute value invalid
|5| Attribute value already defined
|6| Modifier given twice
|7| SELECT modifier is invalid
|8| Attempt to delete a line with SU still defined
|9| No Memory space
|10| File-system error on START LINE or START SU
|11| LINE or SU not started
|12| LINE can not be stopped while SU's are open
|13| No backup running
|14| CASE modifier has invalid name
|15| Invalid backup CPU
|16| Trace not started
|17| SELECT option value incorrect
|18| Trace file name missing
|19| Opens already permitted
|20| Opens already prohibitted
|-5| GDSX User Defined command
|OTHERWISE| Unknown error [err]
]
]
#UNFRAME
Extended General Device Support (GDSX) Manual—529931-001
9- 16
USER^COMMANDS
User Exit Descriptions
Example 9-1. Listing of TELLGDS File (page 3 of 4)
==
== The following routines are handy for communicating with an SPI subsystem
==
?SECTION spi^open MACRO
== (p1) = Name of subsystem to open (E.G. $GDS.#ZSPI)
#PUSH err io_err
#PUSH reply request
== Send and reply buffers
#SET err [#REQUESTER/WAIT [zgds^val^buflen]/READ %1%.#ZSPI io_err reply
request]
[#IF [err]
|THEN| leave^routine error [err] opening SPI subsystem
]
#POP err
?SECTION spi^send MACRO
== Send a SPI buffer and wait for the response
#APPENDV request %1%
== Send the request
#EXTRACTV reply %1%
== Get the response
[#IF NOT [#EMPTYV io_err]
|THEN| leave^routine I/O error [io_err] sending SPI request to spi
]
?SECTION spi^close MACRO
== Terminate communication with an SPI subsystem
#PUSH err
#SET err [#REQUESTER CLOSE request]
[#IF [err]
|THEN| leave^routine Error [err] closing SPI subsystem
]
#POP err io_err request reply
?SECTION spicmd MACRO
#PUSH err
#SET err [%*%]
[#IF [err]
|THEN| leave^routine [spi^error [err]]: %*%
]
#POP err
?SECTION attach^definitions MACRO
== Include the SPI & GDSX definitions if not currently defined
[#IF NOT [#VARIABLEINFO/EXISTENCE/:GDSX]
|THEN| attachseg SHARED taclseg :GDSX
]
?SECTION verify^process MACRO
== The following is necessary due to a bug in #ARGUMENT that
== does not enforce that a process name actually exists.
== Due to be fixed in TACL-C20.
[#IF NOT [#PROCESSEXISTS %1%]
|THEN| leave^routine Process does not exists: %1%
]
Extended General Device Support (GDSX) Manual—529931-001
9- 17
USER^INITIALIZE
User Exit Descriptions
Example 9-1. Listing of TELLGDS File (page 4 of 4)
?SECTION make^segment MACRO
== Make a tacl segment containing the SPI,COM, GDSX and USER definitions
xeq DDL/IN userddl/
== Build usertacl
xeq CREATESEG taclseg
xeq ATTACHSEG PRIVATE taclseg :new
xeq #PUSH #HOME result
xeq HOME :new
xeq #LOAD/KEEP 1,LOADED result/zspitacl
xeq #LOAD/KEEP 1,LOADED result/zcomtacl
xeq #LOAD/KEEP 1,LOADED result/zgdstacl
xeq #LOAD/KEEP 1,LOADED result/usertacl
xeq #POP #HOME
xeq DETACHSEG :new
The USERDDL file for this example contains:
?DICT !,NOSAVE
?TACL usertacl !
CONSTANT ugds-cmd-tell
CONSTANT ugds-tnm-text
CONSTANT ugds-tdt-char
DEF ugds-ddl-char50
TOKEN-TYPE ugds-typ-char50
TOKEN-CODE ugds-tkn-text
VALUE 5999.
VALUE 5101.
VALUE 1.
TYPE CHARACTER 50.
VALUE ugds-tdt-char
DEF ugds-ddl-char50.
VALUE ugds-tnm-text
TOKEN-TYPE ugds-typ-char50.
USER^INITIALIZE
This procedure allows you to initialize user data and/or execute special procedures
before the GDSX process is ready to accept open messages.
USER^INITIALIZE is only called once by the monitor task at the beginning of the
GDSX primary process lifecycle and once at the beginning of a backup GDSX process
lifecycle. You can determine if this procedure was called from the primary or backup
process by the value of the variable process, and thus determine whether to execute
code for primary or backup process initialization.
This procedure is called after all the data structures and TSCODE tasks have been
initialized, but before any requester open messages are processed and before the
DEVICE^HANDLER or LINE^HANDLER procedures are called.
You can process parameters captured by the PROCESS^USER^PARAMS and
USER^ASSIGNS procedures, open a disk file to be shared by all user tasks, initialize
user-defined semaphores, or more generally, initialize any user-defined global variable.
In the primary process, data retrieved from external sources, such as files, including
semaphores that are located in a global data block, cannot be checkpointed here
because the backup GDSX process is not running. Checkpointing this type of data
must be deferred until the USER^BACKUP exit is called.
PROC USER^INITIALIZE ( process );
i
Extended General Device Support (GDSX) Manual—529931-001
9- 18
!
USER^INIT^CONFIG^PARAMS
User Exit Descriptions
input
process
INT:value
indicates whether this procedure was called by the primary process or the backup
process. The value of process is one of the following:
0
Called by the backup process
1
Called by the primary process
Considerations
•
•
•
•
•
During execution of this procedure, buffers may be allocated from memory pools,
but when this procedure is exited, the buffers are no longer available.
Initializing semaphores can be done by the primary and backup processes, but
files should be opened only by the primary, because TSCODE’s implementation of
^OPEN and ^FILE_OPEN_ does a Guardian CHECKOPEN of the file to its
backup.
The TSCODE-supported FAULT procedure cannot be called from this exit,
because the monitor task, which handles the EMS messages, does not exist when
this exit is executing.
The pseudo procedures can be called in this user exit.
When GDSX is running as a primary process only, this procedure executes as a
unique temporary task (user task type 17). When this task exits, it is stopped and
deleted.
USER^INIT^CONFIG^PARAMS
This routine provides you the means to set configuration parameters at GDSX process
initialization time, after the process has been started but before memory has been
allocated for the various pools and structures. By assigning parameter values within
this user exit, you can override the TSCODE default values for any static or dynamic
configuration parameters. Values assigned apply to both primary and backup
processes.
USER^INIT^CONFIG^PARAMS is called only once, at startup time, when no system or
user tasks are running. This is the first user exit called by TSCODE.
For a complete description of the configuration parameters, and instructions on the
different ways of setting them, see GDSX Configuration Parameters on page 2-46.
PROC USER^INIT^CONFIG^PARAMS;
Considerations
•
The USER^INIT^CONFIG^PARAMS, PROCESS^ASSIGNS,
PROCESS^USER^PARAMS, and USER^VERSION user exits are called very
Extended General Device Support (GDSX) Manual—529931-001
9- 19
USER^REPLIES
User Exit Descriptions
early in the GDSX initialization process. Buffer pools and task and file
management structures have not been initialized. Consequently, within these exits
TSCODE-supported service procedures should not be called, except for the
following:
BIT^MAP
INIT[X]LIST
BIT^RESET
INIT^SEM
BIT^SET
^SHUTDOWN
BIT^TEST
^TERMINATE
Wait until USER^INITIALIZE to call other service routines.
•
•
The TSCODE-supported FAULT procedure may not be called from this exit,
because the monitor task, which handles the EMS messages, does not exist when
this exit is executing.
During execution of this procedure, buffers may be allocated from memory pools,
but when this procedure is exited, the buffers are no longer available.
USER^REPLIES
This routine is called whenever GDSX receives SPI or SCF INFO or STATS
commands for a valid object type:
•
•
•
•
LINE
PROCESS
SU
TASK
After the TSCODE monitor task has prepared its response, USER^REPLIES is called
so that you can examine or modify the returning information to be displayed within
SCF.
For example, additional response tokens may be placed in the SCF response buffer
through calls to SSPUT (in which case the scf-buffer parameter must be set to
the address of the response buffer).
status := USER^REPLIES ( scf-command
i
,scf-object-type
i
,scf-object-name
i
,scf-buffer ) ;
i
Extended General Device Support (GDSX) Manual—529931-001
9- 20
!
!
!
!
USER^REPLIES
User Exit Descriptions
returned value
status
INT:value
is the returned value. The value of status is generated by a TAL RETURN
statement in USCODE and can be one of the following:
0
Everything is all right
SCF error
number
Error occurred
scf-command
input
INT:value
is the SCF command number. The value of scf-command is one of the following:
3
An INFO request
7
A STATS request
scf-object-type
input
INT:value
is the SCF object type number. The value of scf-object-type is one of the
following:
13
LINE
17
PROCESS
21
SU
24
TASK
scf-object-name
input
INT:value
is the SCF object name. The value is 9287 for all INFO and STATS commands.
scf-buffer
input
INT:ref
is the pointer to the SCF response buffer.
Considerations
•
•
The TSCODE-supported FAULT procedure should only be called from the
USER^REPLIES exit with its noretn parameter equal to 0. See the description of
FAULT on page 8-22.
USER^REPLIES is an integer function called only by TSCODE, never by
USCODE. USCODE returns function values to TSCODE with the TAL RETURN
Extended General Device Support (GDSX) Manual—529931-001
9- 21
USER^START
User Exit Descriptions
statement. The permissible returned function values are described under the
status variable above.
•
•
USER^REPLIES is called from the monitor task.
Users should modify the I/O buffer pointed to by scf-buffer only with DSM
procedures (SSPUT, SSGET, and so on). See the SPI Programming Manual.
Other references that may be helpful are:
°
°
GDS Management Programming Manual
Event Management Service (EMS) Manual
USER^START
When this user exit is called, TSCODE is about to open an SU and start an associated
DEVICE^HANDLER task. USER^START allows you to participate in the configuration
of SUs.
Depending on the setting of the USERSTARTSU parameter, this procedure is called
when the TSCODE monitor task is about to open an SU. Thus USER^START allows
you to initialize or manipulate data, including DCB variable settings, before the file is
opened and an associated DEVICE^HANDLER task is created.
If the USERSTARTSU configuration parameter is equal to 1, whenever the monitor
task is about to open a dynamic or preconfigured SU—whether the SU is under a LINE
or not—the OPEN^MESSAGE procedure will call USER^START.
If USERSTARTSU is not equal to 1, whenever the monitor task is about to open an
SU, OPEN^MESSAGE will call USER^START only if the SU is configured under a
LINE. The default value of USERSTARTSU guarantees that applications converted
from older versions of GDSX can execute as before: USER^START is invoked only for
SUs under a LINE.
When TSCODE calls USER^START for an SU, the processing is as follows:
•
•
•
•
•
TSCODE receives an open message for the SU.
A DCB is assigned and initialized to manage communication between the opener
and the file associated with the SU.
TSCODE calls USER^START, passing a pointer to the DCB.
TSCODE expects USER^START to return the address of the DCB in the openid
parameter.
After USER^START returns, TSCODE opens the SU.
If the SU is not configured under a LINE (determined by the value of zero for
dcb.lineno), TSCODE opens the file associated with the SU, creates a
DEVICE^HANDLER task, stores openid in tcb.openid, and stores the Guardian file
number for the open file in tcb.term.
Extended General Device Support (GDSX) Manual—529931-001
9- 22
USER^STOP
User Exit Descriptions
If the SU is configured under a LINE (determined by a nonzero value for dcb.lineno),
TSCODE creates a DEVICE^HANDLER task, stores openid in tcb.openid, and stores
an ITC file number in tcb.term.
status := PROC USER^START ( dcb
i
,openid );
o
!
!
returned value
status
INT:value
is the returned value. The value of status is one of the following:
0
Everything is all right and the SU open is allowed
File error
A file error occurred during the open of the SU
input
dcb
INT .EXT:ref
is a pointer to the device control block for the file being opened.
output
openid
INT(32):ref
is the returned pointer to the device control block for the file being opened.
USER^START is expected to return this address.
Considerations
•
•
The TSCODE-supported FAULT procedure should only be called from the
USER^START exit with its noretn parameter equal to 0. See the description of
the FAULT on page 8-22.
USER^START is an integer function called only by TSCODE, never by USCODE.
USCODE returns function values to TSCODE with the TAL RETURN statement.
The permissible returned values are described under the status variable above.
USER^STOP
This user exit is called when the TSCODE monitor task is ready to stop a
DEVICE^HANDLER task, dynamic or preconfigured, or a LINE^HANDLER task, and
close the associated file. This occurs under any of the following conditions:
•
•
An SCF STOP SU, ABORT SU, or ABORT LINE command is issued.
A task calls FAULT with its noretn parameter equal to 1.
Extended General Device Support (GDSX) Manual—529931-001
9- 23
USER^STOP
User Exit Descriptions
•
A call to the TSCODE STOP^TASK procedure is made from USCODE or
TSCODE.
USER^STOP allows you to handle housekeeping for associated files before TSCODE
closes them.
PROC USER^STOP ( tcb );
i
!
input
tcb
INT .EXT:ref
is a pointer to the TCB for the task being stopped.
Considerations
•
If your GDSX process is configured with a LINE, the USER^STOP procedure must
be able to handle the termination of the LINE and the SUs under the LINE. This
coding usually requires scanning all DCBs corresponding to a LINE, which can be
accomplished by means of the BIT^TEST procedure and two bit maps maintained
in the LCB for each active or configured LINE. See AMAP and CMAP in the
line^template STRUCT in Appendix C, DCCBDECS and ULHDECSE Listings.
The CMAP array defines those SUs (DCBs) that are configured under this LINE.
The AMAP array defines those SUs under this LINE that are currently active.
These two maps are bit arrays, with bit[i] corresponding to the ith DCB, addressed
by DCBTBL[i]. See Section 5, DEVICE^HANDLER Example, Design for a
discussion of Device Control Blocks.
The BIT^TEST function is evaluated for a LINE’s CMAP array by:
BIT^TEST(CMAP, n)
This returns true if the nth bit is on, meaning that DCBTBL[n] is configured.
The BIT^TEST function is evaluated for a LINE’s AMAP array by:
BIT^TEST(AMAP, n)
This returns true if the nth bit is on, meaning that DCBTBL[n] is active.
The following example scans all terminals configured on LINE X:
INT .EXT DCB(USER^DCB^DEF); ! USER^DCB^DEF is the
! same as the DCB^TEMPLATE
! with possible user
! extensions. See ULHDECS.
INT X;
INT .CUR^LINE(LINE) := @LINETBL[X]; ! LINETBL is a
! GDSX global.
USE DEV; DEV := 0;
Extended General Device Support (GDSX) Manual—529931-001
9- 24
USER^TAKEOVER
User Exit Descriptions
!
MAXTERMS is a global configuration parameter
WHILE (DEV := DEV + 1) <= MAXTERMS DO
IF BIT^TEST (CUR^LINE.CMAP, DEV) THEN
BEGIN
@DCB := DCBTBL[DEV]; ! Configured device
.
! under this current
.
! L^H task.
END;
DROP DEV;
All active terminals under LINE X can be scanned with the same code, except that
CMAP is replaced by AMAP.
•
•
The TSCODE-supported FAULT procedure should only be called from the
USER^STOP exit with its noretn parameter equal to 0. See the description of the
FAULT on page 8-22.
When USER^STOP is called, the current task is the task being stopped, although it
is not active at this time.
USER^TAKEOVER
This routine is called from TSCODE when the backup process is taking over.
TSCODE has completed its takeover housekeeping, and system and user tasks have
been created but are stopped. USER^TAKEOVER can alter memory contents prior to
resumption of normal operation.
When GDSX creates a backup process, it checkpoints each DCB in its entirety. This
can have undesirable side effects if the backup GDSX process has to take over,
because the contents of the user portion of DCBs may contain addresses or other data
that is not valid in the backup (USAMPLE provides an example of this situation).
However, USER^TAKEOVER may scan the DCB table and clear any fields in the usermanaged part of the DCB.
PROC USER^TAKEOVER;
Considerations
•
•
•
Because USER^TAKEOVER runs before normal task dispatching is allowed to
resume, it must not call any pseudo procedure that might cause a wait for a
resource or an I/O completion.
In this procedure you cannot remap buffers allocated in the former primary process
(which existed before the takeover) by calling ^RECLAIMBUFFER, because each
active user task must reclaim its own buffers, and no user task is active at this
point.
The TSCODE-supported FAULT procedure should not be called from the
USER^TAKEOVER exit.
Extended General Device Support (GDSX) Manual—529931-001
9- 25
USER^VERSION
User Exit Descriptions
USER^VERSION
This procedure returns a user code version date to TSCODE.
status := PROC USER^VERSION ( string );
i
!
returned value
status
INT:value
is the returned value. The value of status is generated by a TAL RETURN
statement in USCODE and is one of the following:
0
A version date is not provided
1
A version date is provided
input
string
STRING:ref:6
is the pointer to the six-byte user code version string.
Considerations
The USER^INIT^CONFIG^PARAMS, PROCESS^ASSIGNS,
PROCESS^USER^PARAMS, and USER^VERSION user exits are called very early in
the GDSX initialization process. Buffer pools and task and file management structures
have not been initialized. Consequently, within these exits TSCODE-supported service
procedures should not be called, except for the following:
BIT^MAP
INIT[X]LIST
BIT^RESET
INIT^SEM
BIT^SET
^SHUTDOWN
BIT^TEST
^TERMINATE
Wait until USER^INITIALIZE to call other service routines.
Example
This example shows a version date in the user’s code that is returned to TSCODE by
USER^VERSION:
INT PROC USER^VERSION (version^string);
STRING .version^string;
BEGIN
version^string ':=' "050293"; ! May 2, 1993
RETURN 1;
Extended General Device Support (GDSX) Manual—529931-001
9- 26
A
APPLS Requester Listing
The unconverted requester program APPLS is used in the tutorial and in configuration
examples. It is a TAL application used to send requests to a GDSX process.
The OUT file specified in the RUN command used to start APPL (the name used for
the APPLS object file) is used by APPL to open GDSX. The OUT file always specifies
the name of a GDSX process qualified by LINE and/or subdevice names.
After the application reads the startup message and opens the OUT file, it performs the
following loop:
1. Issues a waited WRITEREAD “CPU, PIN” prompt to the file.
2. Reverses the text string that was input at the prompt.
3. Issues a waited WRITE of the reversed string to the file and delays two seconds.
APPLS Listing
?NOMAP, NOLMAP, NOCODE
?INSPECT, SYMBOLS
LITERAL BUF^WDS = 100;
INT .MSG^BUF[0:BUF^WDS-1], .STARTUP^MSG[0:BUF^WDS-1];
INT .RCV^NAME[0:11] := ["$RECEIVE",8*[" "]];
INT RD^CT, WT^CT, CT^RD, RCV^FILE, MSG^FILE, FERR;
INT PID, CPU, PIN;
STRING .S^MSG^BUF := @MSG^BUF '<<' 1;
STRING .END^OF^TEXT, TEMP;
LITERAL OUTFILE = 21; !WORD OFFSET TO OUTFILE IN STARTUP MESSAGE
?NOLIST
?SOURCE $SYSTEM.SYSTEM.EXTDECS0(OPEN,READUPDATE,REPLY,DEBUG,WRITE,STOP,
?
WRITEREAD,DELAY,MYPID,NUMOUT,CLOSE,FILEINFO)
?LIST
PROC REVERSE^STRING;
BEGIN
INT I;
FOR I := 0 TO ((CT^RD/2)-1) DO
BEGIN
TEMP := S^MSG^BUF[(CT^RD-1)-I];
S^MSG^BUF[(CT^RD-1)-I] := S^MSG^BUF[I];
S^MSG^BUF[I] := TEMP;
END;
END;
PROC REQUESTER^APPL MAIN;
BEGIN
CALL OPEN(RCV^NAME,RCV^FILE,,1);
IF <> THEN CALL DEBUG;
! RCV DEPTH=1
Extended General Device Support (GDSX) Manual—529931-001
A- 1
APPLS Requester Listing
APPLS Listing
CALL READUPDATE(RCV^FILE,STARTUP^MSG,2*BUF^WDS,CT^RD);
IF <> THEN CALL DEBUG;
CALL REPLY(,,,,0);
IF <> THEN CALL DEBUG;
CALL OPEN(STARTUP^MSG[OUTFILE],MSG^FILE,0); ! WAITED I/O
IF <> THEN
BEGIN
CALL FILEINFO(-1,FERR);
CALL DEBUG;
END;
WHILE (-1) DO
BEGIN
PID := MYPID;
CPU := PID.<4:7>;
PIN := PID.<8:15>;
CALL NUMOUT(S^MSG^BUF[0],CPU,10,3);
S^MSG^BUF[3] := ",";
CALL NUMOUT(S^MSG^BUF[4],PIN,10,3);
S^MSG^BUF[7] := "-";
CALL WRITEREAD(MSG^FILE,MSG^BUF,8,70,CT^RD);
CALL FILEINFO(MSG^FILE,FERR);
IF (FERR = 0) THEN
BEGIN
! NORMAL COMPLETION
IF (CT^RD > 0) THEN
BEGIN
CALL REVERSE^STRING;
WT^CT := CT^RD+8;
S^MSG^BUF[CT^RD+7] '=:' S^MSG^BUF[CT^RD-1] FOR CT^RD
& [8*[" "]];
END
ELSE
BEGIN
WT^CT := 12;
S^MSG^BUF[0] ':=' 8*[" "] & ["****"];
END;
CALL WRITE(MSG^FILE,MSG^BUF,WT^CT);
IF <> THEN
BEGIN
! CONTINUE ON GDSX SWITCHOVER
CALL FILEINFO(MSG^FILE,FERR);
IF (FERR <> 210) THEN CALL DEBUG;
END;
END
ELSE IF (FERR = 1) THEN
BEGIN
! USER TYPED CTRL/Y
WT^CT := 28;
S^MSG^BUF ':=' 8*[" "] & ["APPLICATION STOPPING"];
CALL WRITE(MSG^FILE,MSG^BUF,WT^CT);
IF <> THEN CALL DEBUG;
CALL CLOSE(MSG^FILE);
IF <> THEN CALL DEBUG;
CALL STOP;
END
ELSE IF ((FERR = 66) OR (FERR = 201)) THEN
BEGIN
! DEVICE DOWNED (D^H TASK ABORTED OR
! GDSX PROCESS STOPPED)
CALL CLOSE(MSG^FILE);
IF <> THEN CALL DEBUG;
CALL STOP;
END
ELSE IF (FERR = 210) THEN
BEGIN
! OUTFILE SWITCHED TO BACKUP, CONTINUE
Extended General Device Support (GDSX) Manual—529931-001
A- 2
APPLS Requester Listing
WT^CT :=28;
S^MSG^BUF ':=' 8*[" "] & ["PLEASE RE-ENTER DATA"];
CALL WRITE(MSG^FILE,MSG^BUF,WT^CT);
IF <> THEN
BEGIN
! CONTINUE ON GDSX SWITCHOVER
CALL FILEINFO(MSG^FILE,FERR);
IF (FERR <> 210) THEN CALL DEBUG;
END;
END
ELSE
! OTHER ERROR CONDITION
CALL DEBUG;
CALL DELAY(200D);
END;
END;
Extended General Device Support (GDSX) Manual—529931-001
A- 3
APPLS Listing
APPLS Requester Listing
Extended General Device Support (GDSX) Manual—529931-001
A- 4
APPLS Listing
B
USKELEX and USKELEXC Listings
Included in this appendix are listings of the USKELEX and USKELEXC example
programs. USKELEX is the program used in the tutorial in Section 4,
DEVICE^HANDLER Example, Running and Managing through Section 7,
LINE^HANDLER Example, Design. USKELEX is an unconverted program, not using
any of the extended features of D-series systems, and runs only at a low PIN.
The USKELEXC program shows the result of converting the USKELEX application to
take advantage of D-series enhancements. Wherever possible, C-series service
routines in USKELEX are replaced in USKELEXC by D-series service routines. When
compiling or binding this code, remember to set the HIGHPIN object-file attribute so
that you can run the resulting object file at a high PIN.
USKELEXC is intended to be run with d^plus^enabled of the CONTROLFLAGS
configuration parameter set to 1. See Using D-Series Features on page 2-3 for further
information on converted processes. This application is not used in the tutorial, but is
provided for guidance in application conversion.
Caution. The USKELEX and USKELEXC example programs include very little error-handling
logic, because error-handling code depends on the application requirements, and extensive
error-handling code would detract from the overall design focus of the tutorial. Adequate error
handling, however, must be included in applications designed for actual production.
USKELEX Listing
!
! GDSX USCODE Skeleton File
!
?NOMAP, NOLMAP, NOCODE, SYMBOLS, CPU TNS/II
NAME uscode;
BLOCK COMMON^TEMPLATES;
?NOLIST, SOURCE
DCCBDECS (EVENTS)
?LIST
?NOLIST, SOURCE
DCCBDECS (ERRORS)
?LIST
?LIST, SOURCE
DCCBDECS (TCB^LAYOUT)
?LIST
?LIST, SOURCE
DCCBDECS (IOCB^LAYOUT)
?LIST
?LIST, SOURCE
DCCBDECS (FCB^LAYOUT)
?LIST
?LIST, SOURCE
DCCBDECS (RCB^LAYOUT)
?LIST
!===========================================================================
!Comment Users may include their own file to modify DCB and LINE Templates.
!Comment See file ULHDECS that USAMPLE sources in here
?LIST, SOURCE ULHDECSE (TEMPLATES)
!===========================================================================
Extended General Device Support (GDSX) Manual—529931-001
B- 1
USKELEX Listing
USKELEX and USKELEXC Listings
?LIST
END BLOCK;
! COMMON^TEMPLATES
BLOCK CONFIG^PARMS^TEMPLATES;
?NOLIST, SOURCE
DCCBDECS (CONFIG^TEMPLATES)
?LIST
END BLOCK; ! CONFIG^PARMS^TEMPLATES
!
BLOCK CONFIG^PARMS^DATA;
?NOLIST, SOURCE
DCCBDECS (CONFIG^DATA)
?LIST
END BLOCK; ! CONFIG^PARMS^DATA
BLOCK COMMON^DATA;
?NOLIST, SOURCE
DCCBDECS (COMMON^DATA)
?LIST
END BLOCK; ! COMMON^DATA
BLOCK USER^PRIVATE;
LITERAL TRUE = -1, FALSE = 0;
END BLOCK; !USER^PRIVATE
!===========================================================================
!Comment User may include System Procedures desired here.
?NOLIST, SOURCE $SYSTEM.SYSTEM.EXTDECS0(DEBUG, NUMOUT, NUMIN);
!===========================================================================
?LIST
?NOLIST, SOURCE PEXTGDS
?LIST
?PAGE "PROC DEVICE^HANDLER"
PROC DEVICE^HANDLER (TERM^FILE^NUM, INTERNAL^TERM^NO, TERM^TYPE);
INT TERM^FILE^NUM
,
INTERNAL^TERM^NO,
TERM^TYPE
;
! FILE^NUM FOR THIS D^H TASK
! TERM NUMBER FOR THIS D^H TASK
! TERMINAL TYPE
BEGIN
!===========================================================================
!
Comment - USCODE can declare desired Device^Handler Local Variables
!
here
!===========================================================================
INT .EXT MY^DCB(DCB^TEMPLATE);
INT .EXT TERM^BUF;
STRING .EXT S^TERM^BUF;
INT .EXT RCV^BUF;
STRING .EXT S^RCV^BUF;
INT .EXT E^RCV^BUF := 0D;
INT RQSTR^WT^CT;
INT RQSTR^RD^CT;
INT TERM^CT^RD;
INT DOLR^RCV := 0;
INT RQST^TYPE := 0;
INT FERR;
INT TAKE^OVER;
LITERAL WT=1, RD=2, WT^RD=3, CTRL=4, SET^MD=5;
LITERAL BUF^SIZE = 1024;
!===========================================================================
!
Comment - USCODE can add desired Device^Handler Subprocs here
!
SUBPROC ?;
!
BEGIN
!
END;
!===========================================================================
SUBPROC SCAN^BUF;
Extended General Device Support (GDSX) Manual—529931-001
B- 2
USKELEX Listing
USKELEX and USKELEXC Listings
BEGIN
INT I;
STRING LEFT^HALF;
@S^TERM^BUF := @TERM^BUF;
@S^RCV^BUF := @RCV^BUF;
!
!
!
!
!
THIS PROCEDURE PERFORMS DATASTREAM
CONVERSION, CHANGING LOWERCASE
CHARACTERS TO UPPERCASE. IT IS
CALLED ONLY FOR OUTBOUND (TO IOP)
REQUESTS.
FOR I := 0 TO (RQSTR^WT^CT - 1) DO
BEGIN
LEFT^HALF := S^RCV^BUF[I].<8:11>;
IF (LEFT^HALF = 6 OR LEFT^HALF = 7) THEN ! IF LEFT HALF OF BYTE
BEGIN
! IS 6 OR 7 (BASE 10),
S^TERM^BUF[I] := S^RCV^BUF[I] LAND %337; ! CHANGE BIT SO LEFT
END
! HALF OF BYTE IS 4 OR 5,
ELSE S^TERM^BUF[I] := S^RCV^BUF[I];
! ELSE LEAVE IT ALONE.
END;
! FOR
END;
! SUBPROC
?PAGE
!===========================================================================
!
Device^Handler Procedure MAIN ENTRY POINT begins here
!===========================================================================
WHILE (1) DO
BEGIN
@RCV^BUF := GETEXTPOOL(10,BUF^SIZE); ! FROM EXT BUFFER POOL
IF @RCV^BUF = 0D THEN CALL DEBUG;
! (BYTE ADDRESSABLE)
@E^RCV^BUF := @RCV^BUF;
TAKE^OVER := FALSE;
CALL ^READUPDATEX(DOLR^RCV,RCV^BUF,BUF^SIZE);
IF <> THEN CALL DEBUG;
CALL ^AWAITIOX(DOLR^RCV,@RCV^BUF,RQSTR^WT^CT);
IF = THEN
! (CCE) NORMAL COMPLETION
CALL ^RECEIVEINFO(,,,,RQSTR^RD^CT,RQST^TYPE)
ELSE IF > THEN
! (CCG) SYSTEM MSG RECEIVED
BEGIN
IF RCV^BUF[0] = -32 THEN
RQST^TYPE := CTRL
ELSE IF RCV^BUF[0] = -33 THEN
RQST^TYPE := SET^MD
ELSE
CALL DEBUG;
END
ELSE
CALL DEBUG;
! (CCL) ERROR
IF ^CHECKPOINT(2) THEN
BEGIN
TAKE^OVER := TRUE;
CALL ^RECLAIMBUFFER(@E^RCV^BUF, 10);
IF <> THEN CALL DEBUG;
@RCV^BUF := @E^RCV^BUF;
END;
@TERM^BUF := GETEXTPOOL(10,BUF^SIZE);
IF @TERM^BUF = 0D THEN CALL DEBUG;
CASE RQST^TYPE OF
BEGIN
WT^RD -> ! WRITEREAD
BEGIN
IF (NOT TAKE^OVER) THEN
BEGIN
Extended General Device Support (GDSX) Manual—529931-001
B- 3
USKELEX and USKELEXC Listings
USKELEX Listing
CALL SCAN^BUF;
@MY^DCB := DCBTBL[INTERNAL^TERM^NO];
MY^DCB.WT^RD^PEND := TRUE;
! SET FLAG
! FOR USER^STOP PROCEDURE
CALL ^WRITEREADX(TERM^FILE^NUM,TERM^BUF,
RQSTR^WT^CT,RQSTR^RD^CT);
IF <> THEN CALL DEBUG;
CALL ^AWAITIOX(TERM^FILE^NUM,@TERM^BUF,TERM^CT^RD);
CALL ^FILEINFO(TERM^FILE^NUM,FERR);
IF (FERR = 0) THEN
CALL ^REPLYX(TERM^BUF,TERM^CT^RD)
! NORMAL COMPLETION
ELSE
CALL ^REPLYX(,,,,FERR); ! APPL DEALS WITH
! IOP FS ERRORS
MY^DCB.WT^RD^PEND := FALSE;
! CLEAR FLAG
END;
END;
WT -> ! WRITE
BEGIN
CALL SCAN^BUF;
CALL ^WRITEX(TERM^FILE^NUM,TERM^BUF,RQSTR^WT^CT);
IF <> THEN CALL DEBUG;
CALL ^AWAITIOX(TERM^FILE^NUM);
CALL ^FILEINFO(TERM^FILE^NUM,FERR);
CALL ^REPLYX(,,,,FERR);
END;
RD -> ! READ
BEGIN
CALL ^READX(TERM^FILE^NUM,TERM^BUF,RQSTR^RD^CT);
IF <> THEN CALL DEBUG;
CALL ^AWAITIOX(TERM^FILE^NUM,@TERM^BUF,TERM^CT^RD);
CALL ^FILEINFO(TERM^FILE^NUM,FERR);
IF (FERR = 0) THEN
CALL ^REPLYX(TERM^BUF,TERM^CT^RD)
ELSE
CALL ^REPLYX(,,,,FERR);
END;
CTRL -> ! CONTROL
BEGIN
CALL ^CONTROL(TERM^FILE^NUM,RCV^BUF[1],RCV^BUF[2]);
IF <> THEN CALL DEBUG;
CALL ^AWAITIOX(TERM^FILE^NUM);
CALL ^FILEINFO(TERM^FILE^NUM,FERR);
CALL ^REPLYX(,,,,FERR);;
END;
SET^MD -> ! SETMODE
BEGIN
CALL ^SETMODENOWAIT(TERM^FILE^NUM,
RCV^BUF[1],RCV^BUF[2],RCV^BUF[3]);
IF <> THEN CALL DEBUG;
CALL ^AWAITIOX(TERM^FILE^NUM);
CALL ^FILEINFO(TERM^FILE^NUM,FERR);
CALL ^REPLYX(,,,,FERR);
END;
END;
!CASE
CALL PUTEXTPOOL(10,@TERM^BUF);
CALL PUTEXTPOOL(10,@RCV^BUF);
Extended General Device Support (GDSX) Manual—529931-001
B- 4
USKELEX Listing
USKELEX and USKELEXC Listings
END;
END;
!WHILE
!PROC
!===========================================================================
?PAGE "PROC LINE HANDLER"
!===========================================================================
PROC LINE^HANDLER (LINE^FILE^NUM, INTERNAL^LINE^NO, IN^QUEUE^FILE^NUM);
INT LINE^FILE^NUM, INTERNAL^LINE^NO, IN^QUEUE^FILE^NUM;
BEGIN
!===========================================================================
!
Comment - User can declare desired Line^Handler Local Variables here
!===========================================================================
LITERAL DISP^STOP
DISP^ITC
DISP^IOC
WT^OP
WT^RD^OP
=
=
=
=
=
%000001,
%000020,
%000040,
1,
3;
! EVENT MASKS--THESE LITERALS MAY BE
! SOURCED IN FROM DCCBDECS
! IOCB.OPTYPE VALUES
LITERAL LIST^SZ = 15;
! MAX NUMBER OF D^H IOCBS
! WE CAN SAVE
INT (32) .WT^RD^IOCB^LIST[0:LIST^SZ-1]; !ARRAY FOR SAVING IOCBS
! FOR OUTSTANDING WRITEREADS FROM D^H TASKS
INT .EXT DH^IOCB(IOCB^TEMPLATE),
.EXT LINE^IOCB(IOCB^TEMPLATE),
.EXT WT^IOCB(IOCB^TEMPLATE); ! IOCB FOR THE ONE
! OUTSTANDING D^H WRITE
INT OLDEST, NEWEST; ! INDICES FOR WT^RD^IOCB^LIST
INT .EXT MSG^BUF;
INT EVT;
?PAGE
!===========================================================================
!
Comment - User can add desired Line^Handler Subprocs here
!
SUBPROC ?;
!
BEGIN
!
END;
!===========================================================================
SUBPROC INCR^INDEX(I);
INT .I;
BEGIN
IF (I < (LIST^SZ-1)) THEN
I := I + 1
ELSE
I := 0;
END;
SUBPROC STOP^LINE;
BEGIN
CALL PUTEXTPOOL(10,@MSG^BUF);
CALL STOP^TASK;
END;
! TSCODE (EXTERNAL) PROC
?PAGE
SUBPROC WT^TO^LINE;
BEGIN
INT .EXT BUF^PTR;
Extended General Device Support (GDSX) Manual—529931-001
B- 5
USKELEX Listing
USKELEX and USKELEXC Listings
@BUF^PTR := WT^IOCB.BUFADDRX;
! MOVE TEXT INTO TASK'S OWN BUFFER
MSG^BUF ':=' BUF^PTR FOR WT^IOCB.IOCNT BYTES;
CALL ^WRITEX(LINE^FILE^NUM,MSG^BUF,WT^IOCB.IOCNT);
IF <> THEN CALL DEBUG;
END;
SUBPROC WT^RD^TO^LINE;
BEGIN
INT .EXT BUF^PTR, .EXT IOCB(IOCB^TEMPLATE);
WHILE ((WT^RD^IOCB^LIST[OLDEST] = 0D) AND ! SKIP CANCELED REQUESTS
(OLDEST <> NEWEST)) DO
CALL INCR^INDEX(OLDEST);
IF (OLDEST = NEWEST) THEN RETURN; ! NO OUTSTANDING REQUESTS
@IOCB := WT^RD^IOCB^LIST[OLDEST];
@BUF^PTR := IOCB.BUFADDRX;
MSG^BUF ':=' BUF^PTR FOR IOCB.IOCNT BYTES;
CALL ^WRITEREADX(LINE^FILE^NUM,MSG^BUF,IOCB.IOCNT,IOCB.CNT);
IF <> THEN CALL DEBUG;
END;
?PAGE
SUBPROC CANCEL^ITC;
BEGIN
INT X;
INT .EXT Q^IOCB(IOCB^TEMPLATE);
IF (OLDEST = NEWEST) THEN CALL DEBUG;
! SANITY CHECK
X := OLDEST;
WHILE (X <> NEWEST) DO ! SCAN LIST LOOKING FOR CANCELED IOCBS
BEGIN
@Q^IOCB := WT^RD^IOCB^LIST[X];
IF (Q^IOCB.STATE = IO^CANCELED) THEN ! (NOTE SPELLING)
BEGIN
WT^RD^IOCB^LIST[X] := 0D; ! MARK AS "CANCELED"
CALL NOTIFY^IO^COMPLETIONX(Q^IOCB); !For Ext Memory IO
END;
CALL INCR^INDEX(X);
END;
IF (WT^RD^IOCB^LIST[OLDEST] = 0D) THEN
BEGIN
! THE WT^RD OUTSTANDING TO LINE WAS CANCELED
CALL ^CANCEL(LINE^FILE^NUM);
IF <> THEN CALL DEBUG;
MSG^BUF ':=' [" D^H TASK STOPPED "];
CALL ^WRITEX(LINE^FILE^NUM,MSG^BUF,18);
IF <> THEN CALL DEBUG;
CALL WAIT^EVENT(DISP^IOC,-1D); ! WAIT FOR
! ^WRITE TO COMPLETE
@LINE^IOCB := ^LISTEN(0,LINE^FILE^NUM,0);
IF @LINE^IOCB = 0D THEN CALL DEBUG;
CALL DEALLOCATEIOCB(LINE^IOCB);
CALL WT^RD^TO^LINE; ! ADVANCE TO NEXT QUEUED REQUEST (IF ANY)
END;
END;
! SUBPROC
Extended General Device Support (GDSX) Manual—529931-001
B- 6
USKELEX Listing
USKELEX and USKELEXC Listings
?PAGE
SUBPROC PROCESS^DH^REQ;
BEGIN
@DH^IOCB := ^LISTEN(0,0,1);
IF @DH^IOCB = 0D THEN RETURN;
! PICK UP REQUEST FROM D^H
CASE DH^IOCB.OPTYPE OF
BEGIN
WT^RD^OP ->
! PUT A NEW WT^RD REQUEST ON THE LIST
BEGIN
WT^RD^IOCB^LIST[NEWEST] := @DH^IOCB;
IF (OLDEST = NEWEST) THEN
! NO OTHER
! WT^RD IS OUTSTANDING
BEGIN
CALL INCR^INDEX(NEWEST);
CALL WT^RD^TO^LINE;
END
ELSE
CALL INCR^INDEX(NEWEST);
END;
WT^OP ->
BEGIN
@WT^IOCB := @DH^IOCB;
! SAVE IOCB FROM WRITE OP
! (REQUESTER DESIGN ENSURES THAT NO MORE THAN
! ONE WILL BE OUTSTANDING)
CALL WT^TO^LINE;
END;
OTHERWISE ->
CALL DEBUG;
END;
END;
! CASE
! SUBPROC
?PAGE
SUBPROC LINE^IO^CMPLT;
BEGIN
INT .EXT DH^BUF;
INT .EXT LH^BUF;
@LINE^IOCB := ^LISTEN(0,LINE^FILE^NUM,0);
IF @LINE^IOCB = 0D THEN RETURN;
CASE LINE^IOCB.OPTYPE OF
BEGIN
WT^OP ->
! THE SINGLE OUTSTANDING WRITE OP IS FINISHED
BEGIN
WT^IOCB.ERR := LINE^IOCB.ERR; ! PASS I/O
! PROCESS FS ERR BACK
CALL NOTIFY^IO^COMPLETIONX(WT^IOCB);
CALL INCR^INDEX(OLDEST);
! TAKE THIS WT^RD OFF THE LIST
IF (OLDEST <> NEWEST) THEN ! MORE WT^RDS PENDING
CALL WT^RD^TO^LINE;
END;
WT^RD^OP ->
! OLDEST WT^RD ON LIST IS FINISHED
BEGIN
! AND TEXT HAS BEEN READ AT THE PROMPT
@DH^IOCB := WT^RD^IOCB^LIST[OLDEST];
Extended General Device Support (GDSX) Manual—529931-001
B- 7
USKELEX Listing
USKELEX and USKELEXC Listings
@DH^BUF := DH^IOCB.BUFADDRX;
@LH^BUF := LINE^IOCB.BUFADDRX;
IF (LINE^IOCB.ERR = 0) THEN
BEGIN
! NORMAL COMPLETION
DH^BUF ':=' LH^BUF FOR LINE^IOCB.IOCNT BYTES;
DH^IOCB.IOCNT := LINE^IOCB.IOCNT;
DH^IOCB.ERR := 0;
END
ELSE
BEGIN
! PASS I/O PROCESS FS ERR BACK TO APPL
DH^IOCB.IOCNT := 0;
DH^IOCB.ERR := LINE^IOCB.ERR;
END;
CALL NOTIFY^IO^COMPLETIONX(DH^IOCB);
END;
OTHERWISE ->
CALL DEBUG;
END;
! CASE
CALL DEALLOCATEIOCB(LINE^IOCB);
END;
! TSCODE ALLOCATED THIS IOCB
! SUBPROC
? PAGE
!===========================================================================
!
Line^Handler Procedure MAIN ENTRY POINT begins here
!===========================================================================
CALL ^READUPDATEX(IN^QUEUE^FILE^NUM);
IF <> THEN CALL DEBUG;
! GET INTERTASK MESSAGE
OLDEST := NEWEST := 0;
@MSG^BUF := GETEXTPOOL(10,1024); ! FROM EXTENDED BUFFER POOL
IF @MSG^BUF = 0D THEN CALL DEBUG;
WHILE (-1) DO
BEGIN
EVT := WAIT^EVENT((DISP^ITC+DISP^IOC+DISP^CAN+DISP^STOP),-1D);
CASE (EVT) OF
BEGIN
E^ITC ->
! INTERTASK MESSAGE RECEIVED FROM A D^H
BEGIN
CALL PROCESS^DH^REQ;
CALL ^READUPDATEX(IN^QUEUE^FILE^NUM); ! GET NEXT MESSAGE
END;
E^IOC ->
! LINE I/O COMPLETED
CALL LINE^IO^CMPLT;
E^CAN ->
! ITC OPERATION CANCELED
CALL CANCEL^ITC;
CALL ^READUPDATEX(IN^QUEUE^FILE^NUM);
! GET NEXT MESSAGE
E^STOP ->
! TASK STOPPED FROM SCF
CALL STOP^LINE;
OTHERWISE ->
CALL DEBUG;
END;
END;
END;
! CASE
! WHILE
! L^H PROC
Extended General Device Support (GDSX) Manual—529931-001
B- 8
USKELEX and USKELEXC Listings
USKELEX Listing
?PAGE " "
!===========================================================================
?PAGE "USER^START"
!===========================================================================
! CALLED FOR D^H TASKS
INT PROC USER^START (DCBP, OPENID);
INT .EXT DCBP;
INT (32) .OPENID;
BEGIN
! OPENID specified by USER (In this case, pointer to
! DCB) is stored in TCB.OPENID
OPENID := @DCBP;
RETURN 0;
END;
!===========================================================================
?PAGE "USER^STOP"
!===========================================================================
PROC USER^STOP (TCB);
INT .EXT TCB(TCB^TEMPLATE);
BEGIN
INT FILENO;
INT MESSG[0:8] := "D^H TASK STOPPED ";
INT .EXT DCB(DCB^TEMPLATE);
@DCB := TCB.DCBADDR;
IF ((TCB.STATE.<10:15>
<
16 )
! A D^H TASK IS BEING STOPPED
AND
(DCB.WT^RD^PEND = TRUE)) THEN
! WAITING ON A WRITEREAD
BEGIN
! CANCEL OUTSTANDING I/O FROM A D^H TASK
CALL ^CANCEL(TCB.TERM); ! (EITHER FOR DEVICE I/O OR FOR ITC)
IF <> THEN CALL DEBUG;
IF (DCB.LINENO = 0 ) THEN
BEGIN
FILENO := TCB.TERM;
CALL ^WRITE(FILENO, MESSG, 18);
!We don't use writeX because
IF <> THEN CALL DEBUG;
!MESSG is in local stack.
CALL ^AWAITIO(FILENO);
END;
!Mixing local
END;
!and ext memory is reasonable
!and feasible.
END;
!===========================================================================
?PAGE "PROC PROCESS^ASSIGNS"
!===========================================================================
!***************************************************************************
! Function:
!
!
This PROC is used to process user assign parameters as part of
!
startup msg
!
! Input: INT buf; buffer string points to assign parameters
!
! Output: None.
!
!***************************************************************************
PROC PROCESS^ASSIGNS (buf);
INT .buf;
BEGIN
!
!
Any user assign params will be passed to this proc for further processing
Extended General Device Support (GDSX) Manual—529931-001
B- 9
USKELEX Listing
USKELEX and USKELEXC Listings
!
END;
!===========================================================================
?PAGE "PROC PROCESS^USER^PARAMS"
!===========================================================================
!***************************************************************************
! Function: This PROC serves as a way for users to supply their parameters at
!
startup time.
!
!
Whenever a parameter starts with USERPARAM in a startup PARAM message,
!
the rest of buffer containing the parameter message will be passed to
!
this routine for further processing.
!
!
Users can use this procedure to process user defined values for
!
their own startup processing (Not GDSX defined configuration
!
parameters). See GDSX documentation for a list of defined
!
configuration parameters, such as MAXLINES.
!
! Input: STRING .user^param^string.
!
! Output: None. User can process the given param string and assign
!
its corresponding values.
!
! EXAMPLE:
!
! The following gives an EXAMPLE for processing params if the convention is
! the same as the Tandem start CI -- i.e.,
!
!
STRING param^msg[0]
: = "N" : Length of param name
!
param^msg[1] for N
: =
USERPARAMn
!
where n is a number
!
from 1 to 99999
!
!
param^msg[N+1]
: = "V" : Length of param value
!
param^msg[N+2] for V : =
param value
!
! An example: startup PARAM msg is PARAM USERPARAM1 user_value
! startup^msg^buf looks like this: buf[0] = 10, buf[1:10] = "USERPARAM1"
!
buf[11] = 13, buf[12:24]= "uservar-value"
! User^param^buf points to buf.
!***************************************************************************
PROC PROCESS^USER^PARAMS (user^param^buf);
STRING .user^param^buf;
BEGIN
Literal
eof = %377;
STRING
xlate^user^parm^name = 'p' := [
!01234567890123
"USERPARAM1
eof ];
4
",
56789012345678
1, "USERPARAM2
9
",
2,
STRING
.s := @user^param^buf
item^name [0:13]
,
;
use index; index := 0;
WHILE xlate^user^parm^name [index] <> eof
BEGIN
DO
! if within table
Extended General Device Support (GDSX) Manual—529931-001
B -10
USKELEX Listing
USKELEX and USKELEXC Listings
item^name ':=' xlate^user^parm^name [index] for s; ! get table name
IF item^name = s[1] for s THEN ! param name found
BEGIN
@s := @s[s+1] ;
! pt to param value
! assign param value
!set the desired parameter variable to parm value(s[1] FOR s)
goto try^next^param;
END
ELSE
index := index + 15;
! go to next param
END;
drop index;
@s := @s [s+1];
!name not found let us forget it
try^next^param:
!if multiple user parm msgs are in one string
!continue to process, otherwise
!return to TSCODE for further processing
RETURN;
END;
!===========================================================================
?Page "PROC USER^ATTRIBUTES"
!===========================================================================
!***************************************************************************
! Function: This PROC serves as a way for users to add a new ATTRIBUTE for a
!
given SPI command. Unrecognized token for a recognized
!
SPI command will be passed to this PROC for further processing.
!
! Inputs:
sg^cmd, sg^objtye, sg^obname, token^code, token^value
!
! Output:
Return zero if the token is anticipated and token value is right
!
SPI retcode token value for error.
!
!***************************************************************************
INT PROC USER^ATTRIBUTES (sg^cmd, sg^objtype, sg^objname, token^code,
token^value);
INT
sg^cmd
sg^objtype
.sg^objname
.token^value
INT(32) token^code
,
,
,
;
;
!
!
!
!
!
SPI command for
object type for
object name for
SPI token value
SPI token code
this request
this request
this request
for this token
BEGIN
RETURN 0;
END;
!===========================================================================
?PAGE "PROC USER^BACKUP"
!===========================================================================
!***************************************************************************
! Function: This PROC serves as a way for users to pre-process checkpoint
!
information for a fault tolerance-related need.
!
! Input:
None.
! Output:
None.
!
!***************************************************************************
PROC USER^BACKUP;
Extended General Device Support (GDSX) Manual—529931-001
B -11
USKELEX Listing
USKELEX and USKELEXC Listings
BEGIN
END;
!===========================================================================
?Page "PROC USER^COMMANDS"
!===========================================================================
!***************************************************************************
!
! Function: This PROC serves as a way for users to add a new SPI command.
!
Unrecognized SPI commands will be passed to this PROC for
!
further processing.
!
! Input:
IOCB which contains the incoming SPI request
!
! Output:
file^error : return file-system error code related to this I/O
!
sg^error
: return SPI error code for this SPI request.
!
this is important if USCODE wants TSCODE to format
!
response. Note that -1 means invalid command.
!
!
Return 0 if standard response is OK (i.e., USCODE does not
!
have any extra info to return in a response buffer),
!
1 if USCODE format the response buffer and no need
!
for TSCODE to supply any response.
!
!
Note that the following restriction has to follow:
!
1. incoming SPI buffer is pointed to by iocb.bufaddr
!
2. If users prepare SPI response, the response SPI
!
buffer has to be pointed to by iocb.bufaddr when returns
!
!***************************************************************************
INT PROC USER^COMMANDS (iocb, file^error, sg^error) ;
INT .EXT iocb (iocb^template), ! routines for processing
.file^error
, ! user's commands, functions, etc.
.sg^error
;
BEGIN
SG^ERROR := -1;
RETURN 0;
! -1 indicates that this command is unknown
END ;
!===========================================================================
?PAGE "PROC USER^INITIALIZE"
!===========================================================================
!***************************************************************************
! Function: This PROC serves as a way for users to initialize user data
!
and/or special procedure before GDSX is ready to accept opens
!
! Input:
INT primary : Flag to indicate whether the initialization is
!
needed for primary (1), or backup (0).
!
! Output:
None.
!
!***************************************************************************
PROC user^initialize(primary);
INT primary;
BEGIN
END;
!===========================================================================
?PAGE "PROC USER^INIT^CONFIG^PARAMS"
Extended General Device Support (GDSX) Manual—529931-001
B -12
USKELEX Listing
USKELEX and USKELEXC Listings
!===========================================================================
!***************************************************************************
! Function: This PROC serves as a way for users to initialize desired
!
configuration parameter values.
!
! Input:
None.
!
! Output:
None. Assign desired configuration parameter values. This will
!
apply to both primary and backup.
!***************************************************************************
PROC user^init^config^params;
BEGIN
END;
!===========================================================================
?PAGE "PROC USER^REPLIES"
!===========================================================================
!***************************************************************************
!
! Function: This PROC serves as a way for users to participate in processing
!
a SPI inquiry command.
!
! Input:
sg^cmd is the SPI command for the response request.
!
sg^objtype and sg^objname is the object for the response request.
!
sg^buf is the pointer for SPI response buffer.
!
! Output:
users may put as many as response token into SPI response
!
via a call to
!
ssput (sg^buf, desired^user^token^code, user^token^value
!
!
Return zero if every thing is ok
!
Return SPI error number for an error.
!
!***************************************************************************
INT PROC USER^REPLIES (sg^cmd,
INT
sg^cmd
,
sg^objtype
,
sg^objname
,
.sg^buf
;
sg^objtype, sg^objname, sg^buf);
! SPI command for this request
! object type for this request
! object name for this request
! SPI response buffer
BEGIN
RETURN 0;
END ;
!===========================================================================
?PAGE "PROC USER^TAKEOVER"
!===========================================================================
!***************************************************************************
! Function: This PROC serves as a way for users to pre-process after a
!
TAKEOVER in fault tolerance-related processing.
!
! Input:
None.
!
! Output:
None. User could update anything they want (optional).
!
!***************************************************************************
PROC user^takeover;
BEGIN
INT .EXT
dcb(dcb^TEMPLATE) ;
USE d;
Extended General Device Support (GDSX) Manual—529931-001
B -13
USKELEX and USKELEXC Listings
USKELEXC Listing
FOR d := 1 TO MAXTERMS DO
IF BIT^TEST(map.dcbs, d) THEN
BEGIN
@dcb := dcbtbl[d];
END;
DROP d;
END;
!===========================================================================
?PAGE "INT PROC USER^VERSION"
!===========================================================================
!***************************************************************************
! Function: This PROC serves as a way to provide user USCODE version string
!
so that it can be easily identified.
!
! Input:
STRING
version^string
!
! Output:
give 6 bytes of USCODE version string and return 1.
!
! RETURN:
1 : If 6 bytes of user version string is given
!
0 : If no user version string is given
!***************************************************************************
INT PROC user^version (version^string);
STRING .version^string;
BEGIN
version^string ':=' "081589" ; !Aug. 15 1989 User Version
RETURN 1;
END;
USKELEXC Listing
! GDSX USCODE Skeleton File
!
?NOMAP, NOLMAP, NOCODE, SYMBOLS, CPU TNS/II
NAME uscode;
BLOCK COMMON^TEMPLATES;
?NOLIST, SOURCE
DCCBDECS (EVENTS)
?LIST
?NOLIST, SOURCE
DCCBDECS (ERRORS)
?LIST
?LIST, SOURCE
DCCBDECS (TCB^LAYOUT)
?LIST
?LIST, SOURCE
DCCBDECS (IOCB^LAYOUT)
?LIST
?LIST, SOURCE
DCCBDECS (FCB^LAYOUT)
?LIST
?LIST, SOURCE
DCCBDECS (RCB^LAYOUT)
?LIST
!===========================================================================
!Comment Users may include their own file to modify DCB and LINE Templates.
!Comment See file ULHDECS that USAMPLE sources in here
?LIST, SOURCE ULHDECSE (TEMPLATES)
!===========================================================================
?LIST
?LIST, SOURCE ULHDECSE (GETRECEIVEINFO^TEMPLATE)
!dxcd
?LIST
END BLOCK; ! COMMON^TEMPLATES
BLOCK CONFIG^PARMS^TEMPLATES;
?NOLIST, SOURCE
DCCBDECS (CONFIG^TEMPLATES)
?LIST
END BLOCK; ! CONFIG^PARMS^TEMPLATES
Extended General Device Support (GDSX) Manual—529931-001
B -14
USKELEXC Listing
USKELEX and USKELEXC Listings
! Global Data
!
BLOCK CONFIG^PARMS^DATA;
?NOLIST, SOURCE
DCCBDECS (CONFIG^DATA)
?LIST
END BLOCK; ! CONFIG^PARMS^DATA
BLOCK COMMON^DATA;
?NOLIST, SOURCE
DCCBDECS (COMMON^DATA)
?LIST
END BLOCK; ! COMMON^DATA
BLOCK USER^PRIVATE;
LITERAL TRUE = -1, FALSE = 0;
END BLOCK; !USER^PRIVATE
!===========================================================================
!Comment User may include System Procedures desired here.
?NOLIST, SOURCE $SYSTEM.SYSTEM.EXTDECS0(PROCESS_DEBUG_, NUMOUT, NUMIN);
!===========================================================================
?LIST
?NOLIST, SOURCE PEXTGDS
?LIST
?PAGE "PROC DEVICE^HANDLER"
PROC DEVICE^HANDLER (TERM^FILE^NUM, INTERNAL^TERM^NO, TERM^TYPE);
INT TERM^FILE^NUM
,
INTERNAL^TERM^NO,
TERM^TYPE
;
! FILE^NUM FOR THIS D^H TASK
! TERM NUMBER FOR THIS D^H TASK
! TERMINAL TYPE
BEGIN
!===========================================================================
!
Comment - USCODE can declare desired Device^Handler Local Variables here
!===========================================================================
INT .EXT MY^DCB(DCB^TEMPLATE);
INT .get^rcv^info (getreceiveinfo^template);
!dxcd
INT .EXT TERM^BUF;
STRING .EXT S^TERM^BUF;
INT .EXT RCV^BUF;
STRING .EXT S^RCV^BUF;
INT .EXT E^RCV^BUF := 0D;
INT RQSTR^WT^CT;
INT RQSTR^RD^CT;
INT TERM^CT^RD;
INT DOLR^RCV := 0;
INT RQST^TYPE := 0;
INT FERR;
INT TAKE^OVER;
INT RCV^ERROR;
!dxcd
LITERAL WT=1, RD=2, WT^RD=3, CTRL=4, SET^MD=5;
LITERAL BUF^SIZE = 1024;
!===========================================================================
!
Comment - USCODE can add desired Device^Handler Subprocs here
!
SUBPROC ?;
!
BEGIN
!
END;
!===========================================================================
Extended General Device Support (GDSX) Manual—529931-001
B -15
USKELEXC Listing
USKELEX and USKELEXC Listings
SUBPROC SCAN^BUF;
BEGIN
INT I;
STRING LEFT^HALF;
@S^TERM^BUF := @TERM^BUF;
@S^RCV^BUF := @RCV^BUF;
!
!
!
!
!
THIS PROCEDURE PERFORMS DATASTREAM
CONVERSION, CHANGING LOWERCASE
CHARACTERS TO UPPERCASE. IT IS
CALLED ONLY FOR OUTBOUND (TO IOP)
REQUESTS.
FOR I := 0 TO (RQSTR^WT^CT - 1) DO
BEGIN
LEFT^HALF := S^RCV^BUF[I].<8:11>;
IF (LEFT^HALF = 6 OR LEFT^HALF = 7) THEN ! IF LEFT HALF OF BYTE
BEGIN
! IS 6 OR 7 (BASE 10),
S^TERM^BUF[I] := S^RCV^BUF[I] LAND %337; ! CHANGE BIT SO LEFT
END
! HALF OF BYTE IS 4 OR 5,
ELSE S^TERM^BUF[I] := S^RCV^BUF[I];
! ELSE LEAVE IT ALONE.
END;
! FOR
END;
! SUBPROC
?PAGE
!===========================================================================
!
Device^Handler Procedure MAIN ENTRY POINT begins here
!===========================================================================
WHILE (1) DO
BEGIN
@RCV^BUF := GETEXTPOOL(10,BUF^SIZE); ! FROM EXT BUFFER POOL,
IF @RCV^BUF = 0D THEN CALL PROCESS_DEBUG_;
! (BYTE ADDRESSABLE)
@E^RCV^BUF := @RCV^BUF;
TAKE^OVER := FALSE;
CALL ^READUPDATEX(DOLR^RCV,RCV^BUF,BUF^SIZE);
IF <> THEN CALL PROCESS_DEBUG_;
CALL ^AWAITIOX(DOLR^RCV,@RCV^BUF,RQSTR^WT^CT);
IF = THEN ! (CCE) NORMAL COMPLETION !
IF d^plus^enabled THEN
!dxcd
BEGIN
!dxcd
@get^rcv^info := GETLOCALPOOL(0,
!dxcd
($LEN(getreceiveinfo^template)/2));
!dxcd
rcv^error := ^FILE_GETRECEIVEINFO_(get^rcv^info);
!dxcd
IF rcv^error THEN CALL PROCESS_DEBUG_;
!dxcd
RQST^TYPE := get^rcv^info.op;
!dxcd
RQSTR^RD^CT := get^rcv^info.cnt;
!dxcd
CALL PUTLOCALPOOL(0, get^rcv^info);
!dxcd
END
!dxcd
ELSE
!dxcd
BEGIN
CALL ^RECEIVEINFO(,,,,RQSTR^RD^CT,RQST^TYPE);
IF <> THEN CALL PROCESS_DEBUG_;
END
ELSE
IF > THEN
Extended General Device Support (GDSX) Manual—529931-001
B -16
USKELEX and USKELEXC Listings
USKELEXC Listing
!-------------------------------!
! (CCG = 6) SYSTEM MSG RECEIVED !
!-------------------------------!
BEGIN
IF RCV^BUF[0] = -32 THEN
RQST^TYPE := CTRL
ELSE
IF RCV^BUF[0] = -33 THEN
RQST^TYPE := SET^MD
ELSE
!-------------------------------!
! WE RECEIVED A SYSTEM MSG THAT !
! WE ARE NOT YET SUPPORTING
!
!-------------------------------!
CALL PROCESS_DEBUG_;
END
ELSE
!-------------!
! (CCL) ERROR !
!-------------!
CALL PROCESS_DEBUG_;
IF ^CHECKPOINT(2) THEN
BEGIN
TAKE^OVER := TRUE;
CALL ^RECLAIMBUFFER(@E^RCV^BUF, 10);
IF <> THEN CALL PROCESS_DEBUG_;
@RCV^BUF := @E^RCV^BUF;
END;
@TERM^BUF := GETEXTPOOL(10,BUF^SIZE);
IF @TERM^BUF = 0D THEN CALL PROCESS_DEBUG_;
CASE RQST^TYPE OF
BEGIN
WT^RD -> ! WRITEREAD
BEGIN
IF (NOT TAKE^OVER) THEN
BEGIN
CALL SCAN^BUF;
@MY^DCB := DCBTBL[INTERNAL^TERM^NO];
MY^DCB.WT^RD^PEND := TRUE;
! SET FLAG
! FOR USER^STOP PROCEDURE
CALL ^WRITEREADX(TERM^FILE^NUM,TERM^BUF,
RQSTR^WT^CT,RQSTR^RD^CT);
IF <> THEN CALL PROCESS_DEBUG_;
CALL ^AWAITIOX(TERM^FILE^NUM,@TERM^BUF,TERM^CT^RD);
!-----------------------------------------------!
! For File-system error info, USCODE whether
!
! running d^plus^enabled or not, can call either!
! procedure (^FILE_GETINFO_ or ^FILEINFO)
!
!-----------------------------------------------!
IF d^plus^enabled THEN
!dxcd
CALL ^FILE_GETINFO_(TERM^FILE^NUM, FERR)
!dxcd
ELSE
!dxcd
CALL ^FILEINFO(TERM^FILE^NUM,FERR);
IF (FERR = 0) THEN
!-------------------!
! NORMAL COMPLETION !
!-------------------!
CALL ^REPLYX(TERM^BUF,TERM^CT^RD)
ELSE
Extended General Device Support (GDSX) Manual—529931-001
B -17
USKELEX and USKELEXC Listings
USKELEXC Listing
!-------------------------------!
! APPL DEALS WITH IOP FS ERRORS !
!-------------------------------!
CALL ^REPLYX(,,,,FERR);
! CLEAR FLAG !
MY^DCB.WT^RD^PEND := FALSE;
END;
END;
WT -> ! WRITE
BEGIN
CALL SCAN^BUF;
CALL ^WRITEX(TERM^FILE^NUM,TERM^BUF,RQSTR^WT^CT);
IF <> THEN CALL PROCESS_DEBUG_;
CALL ^AWAITIOX(TERM^FILE^NUM);
IF d^plus^enabled THEN
!dxcd
CALL ^FILE_GETINFO_(TERM^FILE^NUM, FERR)
!dxcd
ELSE
!dxcd
CALL ^FILEINFO(TERM^FILE^NUM,FERR);
CALL ^REPLYX(,,,,FERR);
END;
RD -> ! READ
BEGIN
CALL ^READX(TERM^FILE^NUM,TERM^BUF,RQSTR^RD^CT);
IF <> THEN CALL PROCESS_DEBUG_;
CALL ^AWAITIOX(TERM^FILE^NUM,@TERM^BUF,TERM^CT^RD);
IF d^plus^enabled THEN
!dxcd
CALL ^FILE_GETINFO_(TERM^FILE^NUM, FERR)
!dxcd
ELSE
!dxcd
CALL ^FILEINFO(TERM^FILE^NUM,FERR);
IF (FERR = 0) THEN
CALL ^REPLYX(TERM^BUF,TERM^CT^RD)
ELSE
CALL ^REPLYX(,,,,FERR);
END;
CTRL -> ! CONTROL
BEGIN
CALL ^CONTROL(TERM^FILE^NUM,RCV^BUF[1],RCV^BUF[2]);
IF <> THEN CALL PROCESS_DEBUG_;
CALL ^AWAITIOX(TERM^FILE^NUM);
IF d^plus^enabled THEN
!dxcd
CALL ^FILE_GETINFO_(TERM^FILE^NUM, FERR)
!dxcd
ELSE
!dxcd
CALL ^FILEINFO(TERM^FILE^NUM,FERR);
CALL ^REPLYX(,,,,FERR);;
END;
SET^MD -> ! SETMODE
BEGIN
CALL ^SETMODENOWAIT(TERM^FILE^NUM,
RCV^BUF[1],RCV^BUF[2],RCV^BUF[3]);
IF <> THEN CALL PROCESS_DEBUG_;
CALL ^AWAITIOX(TERM^FILE^NUM);
IF d^plus^enabled THEN
!dxcd
CALL ^FILE_GETINFO_(TERM^FILE^NUM, FERR)
Extended General Device Support (GDSX) Manual—529931-001
B -18
USKELEXC Listing
USKELEX and USKELEXC Listings
!dxcd
ELSE
!dxcd
CALL ^FILEINFO(TERM^FILE^NUM,FERR);
CALL ^REPLYX(,,,,FERR);
END;
END;
!CASE
CALL PUTEXTPOOL(10,@TERM^BUF);
CALL PUTEXTPOOL(10,@RCV^BUF);
END;
END;
!WHILE
!PROC
!===========================================================================
?PAGE "PROC LINE HANDLER"
!===========================================================================
PROC LINE^HANDLER (LINE^FILE^NUM, INTERNAL^LINE^NO, IN^QUEUE^FILE^NUM);
INT LINE^FILE^NUM, INTERNAL^LINE^NO, IN^QUEUE^FILE^NUM;
BEGIN
!===========================================================================
!
Comment - User can declare desired Line^Handler Local Variables here
!===========================================================================
LITERAL DISP^STOP
DISP^ITC
DISP^IOC
WT^OP
WT^RD^OP
=
=
=
=
=
%000001,
%000020,
%000040,
1,
3;
! EVENT MASKS--THESE LITERALS MAY BE
! SOURCED IN FROM DCCBDECS
! IOCB.OPTYPE VALUES
LITERAL LIST^SZ = 15;
INT
INT
INT
INT
INT
?PAGE
! MAX NUMBER OF D^H IOCBS
! WE CAN SAVE
(32) .WT^RD^IOCB^LIST[0:LIST^SZ-1]; !ARRAY FOR SAVING IOCBS
! FOR OUTSTANDING WRITEREADS FROM D^H TASKS
.EXT DH^IOCB(IOCB^TEMPLATE),
.EXT LINE^IOCB(IOCB^TEMPLATE),
.EXT WT^IOCB(IOCB^TEMPLATE); ! IOCB FOR THE ONE
! OUTSTANDING D^H WRITE
OLDEST, NEWEST; ! INDICES FOR WT^RD^IOCB^LIST
.EXT MSG^BUF;
EVT;
!===========================================================================
!
Comment - User can add desired Line^Handler Subprocs here
!
SUBPROC ?;
!
BEGIN
!
END;
!===========================================================================
SUBPROC INCR^INDEX(I);
INT .I;
BEGIN
IF (I < (LIST^SZ-1)) THEN
I := I + 1
ELSE
Extended General Device Support (GDSX) Manual—529931-001
B -19
USKELEXC Listing
USKELEX and USKELEXC Listings
I := 0;
END;
SUBPROC STOP^LINE;
BEGIN
CALL PUTEXTPOOL(10,@MSG^BUF);
CALL STOP^TASK;
END;
! TSCODE (EXTERNAL) PROC
?PAGE
SUBPROC WT^TO^LINE;
BEGIN
INT .EXT BUF^PTR;
@BUF^PTR := WT^IOCB.BUFADDRX;
! MOVE TEXT INTO TASKS'S OWN BUFFER
MSG^BUF ':=' BUF^PTR FOR WT^IOCB.IOCNT BYTES;
CALL ^WRITEX(LINE^FILE^NUM,MSG^BUF,WT^IOCB.IOCNT);
IF <> THEN CALL PROCESS_DEBUG_;
END;
SUBPROC WT^RD^TO^LINE;
BEGIN
INT .EXT BUF^PTR, .EXT IOCB(IOCB^TEMPLATE);
WHILE ((WT^RD^IOCB^LIST[OLDEST] = 0D) AND ! SKIP CANCELED REQUESTS
(OLDEST <> NEWEST)) DO
CALL INCR^INDEX(OLDEST);
IF (OLDEST = NEWEST) THEN RETURN; ! NO OUTSTANDING REQUESTS
@IOCB := WT^RD^IOCB^LIST[OLDEST];
@BUF^PTR := IOCB.BUFADDRX;
MSG^BUF ':=' BUF^PTR FOR IOCB.IOCNT BYTES;
CALL ^WRITEREADX(LINE^FILE^NUM,MSG^BUF,IOCB.IOCNT,IOCB.CNT);
IF <> THEN CALL PROCESS_DEBUG_;
END;
?PAGE
SUBPROC CANCEL^ITC;
BEGIN
INT X;
INT .EXT Q^IOCB(IOCB^TEMPLATE);
IF (OLDEST = NEWEST) THEN CALL PROCESS_DEBUG_;
! SANITY CHECK
X := OLDEST;
WHILE (X <> NEWEST) DO ! SCAN LIST LOOKING FOR CANCELED IOCBS
BEGIN
@Q^IOCB := WT^RD^IOCB^LIST[X];
IF (Q^IOCB.STATE = IO^CANCELED) THEN ! (NOTE SPELLING)
BEGIN
WT^RD^IOCB^LIST[X] := 0D; ! MARK AS "CANCELED"
CALL NOTIFY^IO^COMPLETIONX(Q^IOCB);
END;
CALL INCR^INDEX(X);
END;
IF (WT^RD^IOCB^LIST[OLDEST] = 0D) THEN
BEGIN
! THE WT^RD OUTSTANDING TO LINE WAS CANCELED
CALL ^CANCEL(LINE^FILE^NUM);
Extended General Device Support (GDSX) Manual—529931-001
B -20
USKELEXC Listing
USKELEX and USKELEXC Listings
IF <> THEN CALL PROCESS_DEBUG_;
MSG^BUF ':=' [" D^H TASK STOPPED "];
CALL ^WRITEX(LINE^FILE^NUM,MSG^BUF,18);
IF <> THEN CALL PROCESS_DEBUG_;
CALL WAIT^EVENT(DISP^IOC,-1D); ! WAIT FOR
! ^WRITE TO COMPLETE
@LINE^IOCB := ^LISTEN(0,LINE^FILE^NUM,0);
IF @LINE^IOCB = 0D THEN CALL PROCESS_DEBUG_;
CALL DEALLOCATEIOCB(LINE^IOCB);
CALL WT^RD^TO^LINE; ! ADVANCE TO NEXT QUEUED REQUEST (IF ANY)
END;
END;
! SUBPROC
?PAGE
SUBPROC PROCESS^DH^REQ;
BEGIN
@DH^IOCB := ^LISTEN(0,0,1);
IF @DH^IOCB = 0D THEN RETURN;
! PICK UP REQUEST FROM D^H
CASE DH^IOCB.OPTYPE OF
BEGIN
WT^RD^OP ->
! PUT A NEW WT^RD REQUEST ON THE LIST
BEGIN
WT^RD^IOCB^LIST[NEWEST] := @DH^IOCB;
IF (OLDEST = NEWEST) THEN
! NO OTHER
! WT^RD IS OUTSTANDING
BEGIN
CALL INCR^INDEX(NEWEST);
CALL WT^RD^TO^LINE;
END
ELSE
CALL INCR^INDEX(NEWEST);
END;
WT^OP ->
BEGIN
@WT^IOCB := @DH^IOCB;
! SAVE IOCB FROM WRITE OP
! (REQUESTER DESIGN ENSURES THAT NO MORE THAN
! ONE WILL BE OUTSTANDING)
CALL WT^TO^LINE;
END;
OTHERWISE ->
CALL PROCESS_DEBUG_;
END;
END;
! CASE
! SUBPROC
?PAGE
SUBPROC LINE^IO^CMPLT;
BEGIN
INT .EXT DH^BUF;
INT .EXT LH^BUF;
@LINE^IOCB := ^LISTEN(0,LINE^FILE^NUM,0);
IF @LINE^IOCB = 0D THEN RETURN;
CASE LINE^IOCB.OPTYPE OF
BEGIN
WT^OP ->
! THE SINGLE OUTSTANDING WRITE OP IS FINISHED
BEGIN
WT^IOCB.ERR := LINE^IOCB.ERR; ! PASS I/O
! PROCESS FS ERR BACK
Extended General Device Support (GDSX) Manual—529931-001
B -21
USKELEXC Listing
USKELEX and USKELEXC Listings
CALL NOTIFY^IO^COMPLETIONX(WT^IOCB);
CALL INCR^INDEX(OLDEST);
! TAKE THIS WT^RD OFF THE LIST
IF (OLDEST <> NEWEST) THEN ! MORE WT^RDS PENDING
CALL WT^RD^TO^LINE;
END;
WT^RD^OP ->
! OLDEST WT^RD ON LIST IS FINISHED
BEGIN
! AND TEXT HAS BEEN READ AT THE PROMPT
@DH^IOCB := WT^RD^IOCB^LIST[OLDEST];
@DH^BUF := DH^IOCB.BUFADDRX;
@LH^BUF := LINE^IOCB.BUFADDRX;
IF (LINE^IOCB.ERR = 0) THEN
BEGIN
! NORMAL COMPLETION
DH^BUF ':=' LH^BUF FOR LINE^IOCB.IOCNT BYTES;
DH^IOCB.IOCNT := LINE^IOCB.IOCNT;
DH^IOCB.ERR := 0;
END
ELSE
BEGIN
! PASS I/O PROCESS FS ERR BACK TO APPL
DH^IOCB.IOCNT := 0;
DH^IOCB.ERR := LINE^IOCB.ERR;
END;
CALL NOTIFY^IO^COMPLETIONX(DH^IOCB);
END;
OTHERWISE ->
CALL PROCESS_DEBUG_;
END;
! CASE
CALL DEALLOCATEIOCB(LINE^IOCB);
END;
! TSCODE ALLOCATED THIS IOCB.
! SUBPROC
!===========================================================================
!
Line^Handler Procedure MAIN ENTRY POINT begins here
!===========================================================================
CALL ^READUPDATEX(IN^QUEUE^FILE^NUM);
IF <> THEN CALL PROCESS_DEBUG_;
! GET INTERTASK MESSAGE
OLDEST := NEWEST := 0;
@MSG^BUF := GETEXTPOOL(10,1024); ! FROM EXTENDED BUFFER POOL
IF @MSG^BUF = 0D THEN CALL PROCESS_DEBUG_;
WHILE (-1) DO
BEGIN
EVT := WAIT^EVENT((DISP^ITC+DISP^IOC+DISP^CAN+DISP^STOP),-1D);
CASE (EVT) OF
BEGIN
E^ITC ->
! INTERTASK MESSAGE RECEIVED FROM A D^H
BEGIN
CALL PROCESS^DH^REQ;
CALL ^READUPDATEX(IN^QUEUE^FILE^NUM);
! GET NEXT MESSAGE
END;
E^IOC ->
! LINE I/O COMPLETED
CALL LINE^IO^CMPLT;
E^CAN ->
! ITC OPERATION CANCELED
CALL CANCEL^ITC;
CALL ^READUPDATEX(IN^QUEUE^FILE^NUM);
! GET NEXT MESSAGE
Extended General Device Support (GDSX) Manual—529931-001
B -22
USKELEX and USKELEXC Listings
USKELEXC Listing
E^STOP ->
! TASK STOPPED FROM SCF
CALL STOP^LINE;
OTHERWISE ->
CALL PROCESS_DEBUG_;
END;
END;
END;
! CASE
! WHILE
! L^H PROC
?PAGE " "
!===========================================================================
?PAGE "USER^START"
!===========================================================================
! CALLED FOR D^H TASKS
INT PROC USER^START (DCBP, OPENID);
INT .EXT DCBP;
INT (32) .OPENID;
BEGIN
! OPENID specified by USER (In this case, pointer to
! DCB) is stored in TCB.OPENID
OPENID := @DCBP;
RETURN 0;
END;
!===========================================================================
?PAGE "USER^STOP"
!===========================================================================
PROC USER^STOP (TCB);
INT .EXT TCB(TCB^TEMPLATE);
BEGIN
INT FILENO;
INT MESSG[0:8] := "D^H TASK STOPPED ";
INT .EXT DCB(DCB^TEMPLATE);
@DCB := TCB.DCBADDR;
IF ((TCB.STATE.<10:15>
<
16 )
! A D^H TASK IS BEING STOPPED
AND
(DCB.WT^RD^PEND = TRUE)) THEN
! WAITING ON A WRITEREAD
BEGIN
! CANCEL OUTSTANDING I/O FROM A D^H TASK
CALL ^CANCEL(TCB.TERM); ! (EITHER FOR DEVICE I/O OR FOR ITC)
IF <> THEN CALL PROCESS_DEBUG_;
IF (DCB.LINENO = 0 ) THEN
BEGIN
FILENO := TCB.TERM;
CALL ^WRITE(FILENO, MESSG, 18);
!We don't use WRITEX because
IF <> THEN CALL PROCESS_DEBUG_;
!MESSG is in local stack.
CALL ^AWAITIO(FILENO);
END;
END;
END;
!===========================================================================
?PAGE "PROC PROCESS^ASSIGNS"
!===========================================================================
!***************************************************************************
! Function:
!
!
This PROC is used to process user assign parameters as part of
!
startup msg
!
! Input: INT buf; buffer string points to assign parameters
!
! Output: None.
!
Extended General Device Support (GDSX) Manual—529931-001
B -23
USKELEXC Listing
USKELEX and USKELEXC Listings
!***************************************************************************
PROC PROCESS^ASSIGNS (buf);
INT .buf;
BEGIN
!
!
!
Any user assign params will be passed to this proc for further processing
END;
!===========================================================================
?PAGE "PROC PROCESS^USER^PARAMS"
!===========================================================================
!***************************************************************************
! Function: This PROC serves as a way for users to supply their parameters at
!
startup time.
!
!
Whenever a parameter starts with USERPARAM in a startup PARAM message,
!
the rest of buffer containing the parameter message will be passed to
!
this routine for further processing.
!
!
Users can use this procedure to process user defined values for
!
their own startup processing (not GDSX defined configuration
!
parameters). See GDSX documentation for a list of defined
!
configuration parameters, such as MAXLINES.
!
! Input: STRING .user^param^string.
!
! Output: None. User can process the given param string and assign
!
its corresponding values.
!
! EXAMPLE:
!
! The following gives an EXAMPLE for processing params if the convention is
! the same as the Tandem start CI -- i.e.,
!
!
STRING param^msg[0]
: = "N" : Length of param name
!
param^msg[1] for N
: =
USERPARAMn
!
where n is a number
!
from 1 to 99999
!
!
param^msg[N+1]
: = "V" : Length of param value
!
param^msg[N+2] for V : =
param value
!
! An example: startup PARAM msg is PARAM USERPARAM1 user_value
! startup^msg^buf looks like this: buf[0] = 10, buf[1:10] = "USERPARAM1"
!
buf[11] = 13, buf[12:24]= "uservar-value"
! User^param^buf points to buf.
!***************************************************************************
PROC PROCESS^USER^PARAMS (user^param^buf);
STRING .user^param^buf;
BEGIN
Literal
eof = %377;
STRING
xlate^user^parm^name = 'p' := [
!01234567890123
"USERPARAM1
eof ];
4
",
56789012345678
1, "USERPARAM2
9
",
2,
STRING
Extended General Device Support (GDSX) Manual—529931-001
B -24
USKELEXC Listing
USKELEX and USKELEXC Listings
.s := @user^param^buf
item^name [0:13]
,
;
use index; index := 0;
WHILE xlate^user^parm^name [index] <> eof
BEGIN
DO
! if within table
item^name ':=' xlate^user^parm^name [index] for s; ! get table name
IF item^name = s[1] for s THEN ! param name found
BEGIN
@s := @s[s+1] ;
! pt to param value
! assign param value
!set the desired parameter variable to param value(s[1] FOR s)
goto try^next^param;
END
ELSE
index := index + 15;
! go to next param
END;
drop index;
@s := @s [s+1];
!name not found let us forget it
try^next^param:
!if multiple user parm msgs are in one string
!continue to process, otherwise
!return to TSCODE for further processing
RETURN;
END;
!===========================================================================
?Page "PROC USER^ATTRIBUTES"
!===========================================================================
!***************************************************************************
! Function: This PROC serves as a way for users to add a new ATTRIBUTE for a
!
given SPI command. Unrecognized token for a recognized
!
SPI command will be passed to this PROC for further processing.
!
! Inputs:
sg^cmd, sg^objtye, sg^obname, token^code, token^value
!
! Output:
Return zero if the token is anticipated and token value is right
!
SPI retcode token value for error.
!
!***************************************************************************
INT PROC USER^ATTRIBUTES (sg^cmd, sg^objtype, sg^objname, token^code,
token^value);
INT
sg^cmd
sg^objtype
.sg^objname
.token^value
INT(32) token^code
,
,
,
;
;
!
!
!
!
!
SPI command for
object type for
object name for
SPI token value
SPI token code
this request
this request
this request
for this token
BEGIN
RETURN 0;
END;
!===========================================================================
?PAGE "PROC USER^BACKUP"
!===========================================================================
!***************************************************************************
! Function: This PROC serves as a way for users to pre-process checkpoint
!
information for a fault tolerance-related need.
Extended General Device Support (GDSX) Manual—529931-001
B -25
USKELEXC Listing
USKELEX and USKELEXC Listings
!
! Input:
None.
! Output:
None.
!
!***************************************************************************
PROC USER^BACKUP;
BEGIN
END;
!===========================================================================
?Page "PROC USER^COMMANDS"
!===========================================================================
!***************************************************************************
!
! Function: This PROC serves as a way for users to add a new SPI command.
!
Unrecognized SPI commands will be passed to this PROC for
!
further processing.
!
! Input:
IOCB which contains the incoming SPI request
!
! Output:
file^error : return file-system error code related to this I/O
!
sg^error
: return SPI error code for this SPI request.
!
this is important if USCODE wants TSCODE to format
!
response. Note that -1 means invalid command.
!
!
Return 0 if standard response is OK (i.e., USCODE does not
!
have any extra info to return in a response buffer),
!
1 if USCODE format the response buffer and no need
!
for TSCODE to supply any response.
!
!
Note that the following restriction has to follow:
!
1. incoming SPI buffer is pointed to by iocb.bufaddr
!
2. If users prepare SPI response, the response SPI
!
buffer has to be pointed to by iocb.bufaddr when returns
!
!***************************************************************************
INT PROC USER^COMMANDS (iocb, file^error, sg^error) ;
INT .EXT iocb (iocb^template), ! routines for processing
.file^error
, ! user's commands, functions, etc.
.sg^error
;
BEGIN
SG^ERROR := -1;
RETURN 0;
! -1 indicates that this command is unknown
END ;
!===========================================================================
?PAGE "PROC USER^INITIALIZE"
!===========================================================================
!***************************************************************************
! Function: This PROC serves as a way for users to initialize user data
!
and/or special procedure before GDSX is ready to accept opens
!
! Input:
INT primary : Flag to indicate whether the initialization is
!
needed for primary (1), or backup (0).
!
! Output:
None.
!
!***************************************************************************
PROC user^initialize(primary);
INT primary;
BEGIN
END;
Extended General Device Support (GDSX) Manual—529931-001
B -26
USKELEX and USKELEXC Listings
USKELEXC Listing
!===========================================================================
?PAGE "PROC USER^INIT^CONFIG^PARAMS"
!===========================================================================
!***************************************************************************
! Function: This PROC serves as a way for users to initialize desired
!
configuration parameter values.
!
! Input:
None.
!
! Output:
None. Assign desired configuration parameter values. This will
!
apply to both primary and backup.
!***************************************************************************
PROC user^init^config^params;
BEGIN
END;
!===========================================================================
?PAGE "PROC USER^REPLIES"
!===========================================================================
!***************************************************************************
!
! Function: This PROC serves as a way for users to participate in processing
!
a SPI inquiry command.
!
! Input:
sg^cmd is the SPI command for the response request.
!
sg^objtype and sg^objname is the object for the response request.
!
sg^buf is the pointer for SPI response buffer.
!
! Output:
users may put as many as response token into SPI response
!
via a call to
!
ssput (sg^buf, desired^user^token^code, user^token^value
!
!
Return zero if every thing is ok
!
Return SPI error number for an error.
!
!***************************************************************************
INT PROC USER^REPLIES (sg^cmd, sg^objtype, sg^objname, sg^buf);
INT
sg^cmd
,
! SPI command for this request
sg^objtype
,
! object type for this request
sg^objname
,
! object name for this request
.sg^buf
;
! SPI response buffer
BEGIN
RETURN 0;
END ;
!===========================================================================
?PAGE "PROC USER^TAKEOVER"
!===========================================================================
!***************************************************************************
! Function: This PROC serves as a way for users to pre-process after a
!
TAKEOVER in fault tolerance-related processing.
!
! Input:
None.
!
! Output:
None. User could update anything they want (optional).
!
!***************************************************************************
PROC user^takeover;
BEGIN
Extended General Device Support (GDSX) Manual—529931-001
B -27
USKELEX and USKELEXC Listings
USKELEXC Listing
INT
.EXT
dcb(dcb^TEMPLATE) ;
USE d;
FOR d := 1 TO MAXTERMS DO
IF BIT^TEST(map.dcbs, d) THEN
BEGIN
@dcb := dcbtbl[d];
END;
DROP d;
END;
!===========================================================================
?PAGE "INT PROC USER^VERSION"
!===========================================================================
!***************************************************************************
! Function: This PROC serves as a way to provide user USCODE version string
!
so that it can be easily identified.
!
! Input:
STRING
version^string
!
! Output:
give 6 bytes of USCODE version string and return 1.
!
! RETURN:
1 : If 6 bytes of user version string is given
!
0 : If no user version string is given
!***************************************************************************
INT PROC user^version (version^string);
STRING .version^string;
BEGIN
version^string ':=' "022492" ; !Feb. 24 1992 User Version
RETURN 1;
END;
Extended General Device Support (GDSX) Manual—529931-001
B -28
C
DCCBDECS and ULHDECSE
Listings
Included in this appendix are listings for the DCCBDECS and ULHDECSE files for
GDSX. These sections have been regrouped since the D10 version of GDSX. Be
sure to use a SOURCE statement to include them when recompiling GDSX.
DCCBDECS Listing
?Section Config^Data
Struct .Config^Params (Config^Params^Template);
?Section Config^Templates
!******************************************************************************!
!
The following parameters may be set by the user to adjust the default
!
!
sizes of the internal tables and to set other process-control flags
!
!******************************************************************************!
Struct Config^Params^Template (*);
Begin
!0!Int Parms^Type
,
!Type for send to GDSX
Associative^Term ,
!All user tasks are to be
!associative
Breakenabled^Term ,
!if non-zero, break handling for
!terminal files is enabled.
Control^Flags
,
! <0 >
= dynamic session control
! <1 >
= 0 = Control 11 and 12
!
1 = user own mechanism
! <12 >
= high^process if = 1
! <13 >
= auto-restart-control-flag
! <14 >
= statistics control flag
! <15 >
= 1 = send pseudo open &
!
close messages to tasks
Cp^Context^Sz
,
!Number of words in ext seg for
!each task's buffer images
Debug^Flags
,
!<00:07> = debug^error^trap
!<08> = bounds^checking
!<09> = backup^process^saveabEnd
!<10> = backup^process^inspect
!<11> = auto^Trace^Flag
!<12> = uscode^debug^Flag
!<13> = backup^debug^Flag
!<14> = poolcheck^Flag
!<15> = debug^fatal^Flag
Dynamic^Term
,
!if non-zero, temporary DCB's may be
!allocated at TCP open time
!<10> = recovery for dynamic terms
!<11> = autostop for dynamic terms
!<12:15> = nowaitdepth for dynamic terms
Iocb^Wait^Time
,
!Time to wait for IOCBs
Log^Status
,
!if non-zero, log status msgs
Loop^Time
,
!Param for trapping looping tasks
!10!
Trace^Rec^Size
Maximum^Files
Maximum^Iocbs
Maximum^Lines
Maximum^Opens
Maximum^Processes
Maximum^Tasks
Maximum^Terms
Max^Chkpt^Wds
Pool^Size
,
,
,
,
,
,
,
,
,
,
!Trace record size
!Maximum number of open files
!Number of IOCBs
!Number of CP/ENVOY line handler tasks
!Number of opens of GDSX allowed
!Max. processes for which we are the Mom
!Max. # terms supported (+1 for Monitor)
!Maximum number of terminals (subdev
!Largest checkpoint
!Size of shared Extended Pool
Extended General Device Support (GDSX) Manual—529931-001
C- 1
DCCBDECS Listing
DCCBDECS and ULHDECSE Listings
!20!
Receive^Depth
Recvsize
Sg^Security
Task^Pool^Size
Task^Size
Term^Data
Auto^Restart^Time
User^Flags
TMF^Flag,
Buffer^Timeout,
!30!
Ctrl26,
Auto^Stop,
Max^Itc,
Device^Info,
Server^Flg,
Maximum^Links,
User^Start^Su,
D^Series^Error,
Procedure^Nowait,
Segment^Number,
Rfe^01,
Rfe^02;
Int(32) MaxTCBpool^Size
MaxIOCBpool^Size
MaxRCVpool^Size
MaxRCBpool^Size
MaxDCBpool^Size
MaxLDCBpool^Size
MaxLINEpool^Size
MaxPCBpool^Size
MaxFCBpool^size
MaxBUFpool^Size
MaxMSGpool^Size
End;
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
;
!42:43!
!44:45!
!46:47!
!48:49!
!50:51!
!52:53!
!54:55!
!56:57!
!58:59!
!60:61!
!62:63!
!Our receivedepth
!Max length of $RECEIVE message
! <13>
= remote changes allowed
! <14:15> = 0 = Owner
!
1 = Group
!
2 = All
!
3 = Super.Super
!Size of task's private pool
!Size in words of context area for a task
!Words of user-defined terminal data
!delay time for auto-restart
!User defined
!0=no TMF, 1=TMF fe/be, 2= TMF reqstr
!Time allowed for pool wait timeout
!1=support control 26
!GDSX stops after last close
!Max # of ITC files
!Respond correctly to DEVICEINFO
!Act as a server backend process
!Allow LCBS to be set by user
!if 1 force all SU's thru User^Start
!Used for traping specified file err
!Real nowait for procedure that can do so
!Segment number of extended memory
!Reserved for future use
!Reserved for future use
!Task
control block pool size
!IO
control block pool size
!Receive
control block pool size
!Requester
control block pool size
!Device
control block pool size
!Logical Dev control block pool size
!Line
control block pool size
!Process
control block pool size
!File
control block pool size
!Buffer pool size
!Message pool size
Literal
Config^Params^Len
Config^Param^Limit
= ($Len(Config^Params^Template) >> 1) - 1,
= 42;
Define
Parmtype
Associative
Breakenabled
= Config^Params.Parms^Type
#,
= Config^Params.Associative^Term #,
= Config^Params.Breakenabled^Term #,
Controlflags
Dmap^Flag
High^Process
D^Plus^Enabled
Auto^Restart^Flag
Stats^Flag
Sysmsgs^Flag
=
=
=
=
=
=
=
Cpcontextsz
= Config^Params.Cp^Context^Sz
Debugflags
Debug^Error^Trap
Bounds^Checking
Auto^Trace^Flag
Uscode^Debug^Flag
Backup^Debug^Flag
Poolcheck^Flag
Debug^Fatal^Flag
Debug^Error^Trap2
=
=
=
=
=
=
=
=
=
Dynamic
=
Dynamic^Recovery
=
Dynamic^Autostop
=
Dynamic^Nowaitdepth=
Iocbwait
Config^Params.Control^Flags
#,
Config^Params.Control^Flags.<0> #,
Config^Params.Control^Flags.<12>#,
Config^Params.Control^Flags.<12>#,
Config^Params.Control^Flags.<13>#,
Config^Params.Control^Flags.<14>#,
Config^Params.Control^Flags.<15>#,
#,
Config^Params.Debug^Flags
#,
Debugflags.<0:7>
#,!call debug on specific err
Debugflags.<08>
#,!force bounds checking
Debugflags.<11>
#,!turn on trace at startup
Debugflags.<12>
#,!debug Uscode
Debugflags.<13>
#,
Debugflags.<14>
#,!check pools at each dispatch
Debugflags.<15>
#,!call debug on fatal error
Config^Params.D^Series^Error
#,
Config^Params.Dynamic^Term
#,
Config^Params.Dynamic^Term.<10>#,
Config^Params.Dynamic^Term.<11>#,
Config^Params.Dynamic^Term.<12:15># ,
= Config^Params.Iocb^Wait^TIME
#,
Extended General Device Support (GDSX) Manual—529931-001
C- 2
DCCBDECS Listing
DCCBDECS and ULHDECSE Listings
Logstatus
Log^Enabled
= Config^Params.Log^Status
= Config^Params.Log^Status.<15>
#,
#,
Looptime
Tracerecsize
Maxfiles
Maxiocbs
Maxlines
Maxopens
Maxprocesses
Maxtsk
Maxterms
Max^Cp^Wds
Poolsize
Receivedepth
Recvsz
=
=
=
=
=
=
=
=
=
=
=
=
=
Config^Params.Loop^Time
#,
Config^Params.Trace^Rec^Size
#,
Config^Params.Maximum^Files
#,
Config^Params.Maximum^Iocbs
#,
Config^Params.Maximum^Lines
#,
Config^Params.Maximum^Opens
#,
Config^Params.Maximum^Processes#,
Config^Params.Maximum^Tasks
#,
Config^Params.Maximum^Terms
#,
Config^Params.Max^Chkpt^Wds
#,
Config^Params.Pool^Size
#,
Config^Params.Receive^Depth
#,
Config^Params.Recvsize
#,
Security
User^Group
Remote^Change^Flag
Access^Group
=
=
=
=
Config^Params.Sg^Security
<0:7>
<13>
<14:15>
#,
#,
#,
#,
Taskpoolsize
= Config^Params.Task^Pool^Size
#,
Tsksz
= Config^Params.Task^Size
#,
Termdata
= Config^Params.Term^Data
#,
Auto^Restart^Delay^Time
= Config^Params.Auto^Restart^Time#,
Userflags
= Config^Params.User^Flags
#,
Proc^Nowait
= Config^Params.Procedure^Nowait #,!suprt proc nowait
Segment^Id
= Config^Params.Segment^Number
#,!variable seg num
Rfe01
= Config^Params.Rfe^01
#,!Future usage
Rfe02
= Config^Params.Rfe^02
#,!Future usage
MaxBUFpoolsize
= Config^Params.MaxBUFpool^Size #,!Buffer pool size
MaxMSGpoolsize
= Config^Params.MaxMSGpool^Size #,!Message pool size
MaxTCBpoolsize
= Config^Params.MaxTCBpool^Size #,!TCB pool size
MaxIOCBpoolsize
= Config^Params.MaxIOCBpool^Size #,!IOCB pool size
MaxRCVpoolsize
= Config^Params.MaxRCVpool^Size #,!RCV pool size
MaxRCBpoolsize
= Config^Params.MaxRCBpool^Size #,!RCB pool size
MaxDCBpoolsize
= Config^Params.MaxDCBpool^Size #,!DCB pool size
MaxLDCBpoolsize
= Config^Params.MaxLDCBpool^Size #,!LDCB pool size
MaxLINEpoolsize
= Config^Params.MaxLINEpool^Size #,!LINE pool size
MaxPCBpoolsize
= Config^Params.MaxPCBpool^Size #,!PCB pool size
MaxFCBpoolsize
= Config^Params.MaxFCBpool^Size #,!FCB pool size
TMF
= Config^Params.TMF^Flag
#,!TMF flag
Buffertimeout
= Config^Params.Buffer^Timeout
#,!pool time out
Ctrl^26
= Config^Params.Ctrl26
#,!Control 26
Autostop
= Config^Params.Auto^Stop
#,!STOP on last clse
Maxitc
= Config^Params.Max^Itc
#,!Max ITC files
Support^Devinfo
= Config^Params.Device^Info
#,!Rsp correctly
Max^Links
= Config^Params.Maximum^Links
#,!Max Link allocat
Userstartsu
= Config^Params.User^Start^Su
#,!Force User^start
Server
= Config^Params.Server^Flg
#;!Act as BE server
!------------------------------------------------------------------------------!
! Each task has a task control block (TCB) associated with it.
!
! The TCB contains information about the task as described below.
!
!------------------------------------------------------------------------------!
Struct Tcb^Template (*);
!task control block for EXT usage
Begin
Int(32) Locklink[0:1];
!These two words are used to link
!together tasks waiting for some
!resource (pool space, semaphore,
!lock, message logging, etc.).
Int
Taskno,
!Task number of task represented by
!this TCB. We store it here because
!we generally store TCB addresses
!rather than task numbers. By storing
!the task number here, we avoid having
!to do messy address arithmetic to
!derive it.
Events,
!Reason for current dispatch
Mask,
!Wait mask
Savemask,
!The wait mask is saved here when
Extended General Device Support (GDSX) Manual—529931-001
C- 3
DCCBDECS Listing
DCCBDECS and ULHDECSE Listings
Wait^Result,
Lreg;
Int(32) Link[0:1],
Wakeup;
Int
Waitsz;
Int
Trap^S
Filerr,
Deverror,
Pserror,
Rcverror;
Int(32) Iocbh,
Iocbt;
Int
Rcvsz;
Int(32) Rcvbuf,
Rcvtag,
Lastrcviocb,
Qh,
Qt,
Int
Itcqh,
Itcqt;
Faultno,
Stackoffset;
= Waitsz,
!the task is frozen.
!Event which awoke us
!The value of the 'L' register when
!the task gave up control.
!These two words are used to link
!together TCBs for tasks performing
!timed operations. The head of this
!list is ^WAITHEAD.
!When the task initiates a timed
!operation, the expiration time is
!placed here.
!if the task is waiting for pool space
!we store the number of words required
!here. When space is deallocated, we
!may then determine if the task's
!request may now be satisfied.
!S-reg when task trapped.
!Guardian file error for last
!I/O operation completed by task
!Last I/O error on term or line file
!Last error from ^SERVERCLASS_SEND_
!Last error against $rcv for this task
!List header for iocbs owned by
!this task
!Size (in bytes) of $RECEIVE
! READUPDATE
!if = 0, task has no current
! READUPDATE on $RECEIVE
!if > 0, task has current READUPDATE pending
!if < 0, task will queue other $RCV/IO
!Address of task's $RECEIVE buffer
!if = 0, task did not pass buffer
! to READUPDATE
!Task's nowait I/O tag for readupdate
! on $RECEIVE
!if = -1d, task did not pass tag
! to READUPDATE
!Address of IOCB representing last
!$RECEIVE request passed to task.
!List header for message queue
!for task. Message queue holds
!queued $RECEIVE requests as well
!as queued I/O completion messages
!for other files (see ^Q)
!List header for ITC messages
!
!Fault #, if task has faulted
!The number of words that this task
!has overflowed the size of
!TCB.CONTEXT. We need this word
!to output the partial stack.
Int(32) Context,
Cpcontext,
!Ext addr of saved stack image
!Ext Address of Stack Image at last
!checkpoint
Transtag,
!BEGINTRANSACTION tag
Buffers,
!Ext Address of Type-2 buffer images
Taskpool,
!Ext address of Task's private pool
Poolheader,
!Ext address of Task's pool space usage
Pooltailer,
!Ext address of Task's pool space usage
Stats;
!Address of XSTATS block
!**************** Checkpointed part of the TCB ***************************
Int
Term;
!file # of terminal or line managed by this
!task. MUST BE FIRST
!------------------------------------------------------------------------------Int
Iocb^Info,
!Identifies cb^openid as @iocb or @dcb
Cb^Type
= Iocb^Info;!Equivalences to iocb^info
Int(32) Openid;
!Line handler task's openid for this tsk
Int(32) Cb^Openid
= Openid;
!Equivalences to openid
Int
State,
!Current task state(see definitions
Statex,
!below)
Opens,
!Number of openers of this task
Cp^Lreg,
!The value of the 'L' register at the
Extended General Device Support (GDSX) Manual—529931-001
C- 4
DCCBDECS Listing
DCCBDECS and ULHDECSE Listings
!last call to ^CHECKPOINT.
!<13:15>
!
Type of last ^CHECKPOINT by task
!
0 = No current checkpoint
!
1 = Stack checkpoint
!
2 = Stack & Buffer checkpoint
!<12>
!
Tfilesync at last checkpoint
!Transtag at last checkpoint
!Size in words of data at tcb.buffers
!Task to receive Notification if this
!task dies. Also, If owner dies, this
!task dies
!Address of associated device control
!block
!Address of ldcb for break ownership
!For setmodenowait 53 we save user parm2
Cp^Word;
Int(32) Cp^Transtag;
Int
Buffersz;
Int(32) Owner,
Dcbaddr,
Int
End;
Ldcbaddr;
Saved^Parm2;
Literal
TcblenX
Link^OffsetX
= ($Len(TCB^Template)
'+' 1) '>>' 1, !Length in words
= ($Offset(TCB^Template.Link) '+' 1) '>>' 1 ;
Define
!************************** State word ***************************************
Task^Type
= <10:15>#
, !(see below)
Perm^Bit
= <9>#
, !if Set, task does not stop when
!All openers go away
Assoc^Bit
= <8>#
, !if set, all opens for the
!associated terminal go to
!this task
Lh^Bit
= <4:7>#
, !Line number if task is handler
Nomsg^Bit
= <3>#
, !Suppress messages for this task
Stopped^Bit
= <2>#
, !Previously active task
Stop^Pending
= <1>#
, !Stop entered but still had
!openers
Active^Bit
= <0>#
, !Task is active
!*****************************************************************************
!************************** Statex word **************************************
Fault^Bit
= <15>
#,!Task has faulted
Trap^Bit
= <14>
#,!Task has trapped
Transend^Bit
= <13>
#,!Task in ENDTRANSACTION
Tsync^Bit
= <12>
#,!Tfile Sync Info needs checkpt.
Freeze^Pending
= <11>
#,!Task frozen with STOP^bit <>0
Wait^Cause
= <7:10>
#,!Reason for current wait (see below)
New^Bit
= <06>
#,!Task is in ^OPEN^MESSAGE
Takeover^Bit
= <05>
#,!Set when takeover occurs
Itcru^Bit
= <04>
#,!Task has READUPDATE on ITC
Stop^Mode
= <0:3>
#,!when <> 0, task unstoppable
Dont^Stop
= (1 '<<' 12)
#,!set stop mode to 1
!*****************************************************************************
Cp^Tsync
Cp^Type
= Cp^Word.<12> #,
= Cp^Word.<13:15>#,
Io^Iocb
Io^Dcb
Io^Rcv
Io^Ext
=
=
=
=
Iocb^Info.<15>#,!set
Iocb^Info.<14>#,!set
Iocb^Info.<13>#,!set
Iocb^Info.<12>#;!set
Literal
Sem^Wait
Log^Wait
Buffer^Wait
Queue^Wait
Iocb^Wait
=
=
=
=
=
1,
2,
3,
4,
5;
Literal
Device^Handler^Task^Type
Montsk
Line^Handler^Task^Type
User^Initialize^Task^Type
if
if
if
if
openid
openid
msgtag
rcvbuf
contains @iocb
contains @dcb
contains rcvbuf @
is in ext. memory
!Values of wait^cause
!Waiting for semaphore
!Waiting to log
!Waiting for byte buf
!Waiting for word buf
!Waiting for IOCB
!Task types
=
=
=
=
0,
1,
16,
17,
Extended General Device Support (GDSX) Manual—529931-001
C- 5
DCCBDECS Listing
DCCBDECS and ULHDECSE Listings
Monitor^Task^Type
Listener^Task^Type
Createbackup^Task^Type
Downcpu^Task^Type
Netmon^Task^Type
Open^Task^Type
Procdel^Task^Type
Proccreate^Task^Type
Literal
Perm^State
Assoc^State
Nomsg^State
Stopped^State
=
=
=
=
=
=
=
=
32,
33,
34,
35,
36,
37,
38,
39;
=
=
=
=
%000100,
%000200,
%010000,
%020000;
!------------------------------------------------------------------------------!
!
For each outstanding nowait I/O, an IOCB is allocated. The IOCBs
!
!
relating to a given file are linked to the file's FCB. The head of
!
!
this list is FCB.IOCBH; IOCBs in the list are linked via
!
!
IOCB.FCBLINK. This list is maintained so that we can clean up
!
!
the IOCBs for a file if the file is closed with I/Os outstanding.
!
!
Similarly, all IOCBs representing I/O operations for a particular
!
!
task are linked to the task's TCB. The head of this list is
!
!
TCB.IOCBH. This list is kept so that we may cancel all I/O
!
!
initiated by a task when we stop the task. Without doing this, we
!
!
might have a READ operation complete into a buffer that was no
!
!
longer allocated or which had been reallocated to another task.
!
!
When initiating nowait I/Os, we pass the address of the associated
!
!
IOCB as the TAG parameter. In this way, when the I/O completes, we
!
!
can easily identify the task which initiated it. Note that the
!
!
user may still specify an IOTAG in as much as we store the user's
!
!
TAG in the IOCB so that we may return it at I/O completion.
!
!
!
!
IOCBs are also used to implement ^SIGNALTIMEOUT; such an IOCB
!
!
is linked to the initiating task's TCB.IOCBH/IOCBT list and into
!
!
the timed wait list via FCBLINK; the internal wakeup time is
!
!
stored in wakeup.
!
!------------------------------------------------------------------------------!
Struct Iocb^Template (*);
!I/O Control Block
Begin
Int(32) Tcblink[0:1],
!Iocb links for Task owning this io
Fcblink[0:1],
!Iocb links for this file
Lhlink[0:1],
!Iocb links for Line^handler use
Wakeup
= Lhlink,
!Internal wakeup time for
!signaltimeout IOCB
Syncid
= Lhlink;
!Syncid for $receive iocb's
Int
State,
!Iocb state (See Below)
Optype,
!I/O Operation Type
Iocnt,
!I/O count from AWAITIO
Signal^Param1 = Iocnt;
Int(32) Signal^Param2[0:-1];
Int
Cnt;
Int(32) BufaddrX;
Struct Lb = BufaddrX;
Begin
Int Ext^Addr;
Int Buf^Addr;
End;
Int
!Signaltimeout Definitions
!Parameter1 for signaltimeout
!Parameter2 for signaltimeout
!Max reply size from RECEIVEINFO
!EXT Buffer address is quivalenced
!Not used for local buffer address
!Used by local buffer to hold address
!Setmode Definitions
Setmode^Funct = Iocnt,
!Setmode function
Setmode^P1
= Cnt,
!Setmode param1
Setmode^P2
= BufaddrX, !Setmode param2 - POINTS to a INT32
Control^Op
= Iocnt,
Control^Param = Cnt;
Int(32) Histag;
Int(32) Xbufaddr
= Histag;
!Control Definitions!
!Control op
!Control Parameter
!Task's NOWAIT I/O Tag
!When $recieve IOCB is in IO^queued
!then ptr is in EXT MEM
Extended General Device Support (GDSX) Manual—529931-001
C- 6
DCCBDECS Listing
DCCBDECS and ULHDECSE Listings
Int(32) Tcbaddr;
Int
File,
Msgtag;
Struct Iocb^info;
Begin
Unsigned(1) Io^Sysbuf;
!Task requesting this IO
!File #
!$RECEIVE message tag
!if true, $RECEIVE request data is
!in SYSPOOL or SHARED POOL
!Originating CPU for $RECEIVE request
!if true, I/O operation initiated
!by extended I/O procedure
!if true, $RECEIVE IOCB
!if false, File IOCB or DCB
!if true, File DCB
!if false, File IOCB or $RCV
!if true, File IOCB
!if false, $RECEIVE $RCV or DCB
Unsigned(10) Cpu;
Unsigned(1) Ext^Io;
Unsigned(1)
Type^Rcv;
Unsigned(1)
Type^Dcb;
Unsigned(1)
Type^Iocb;
End;
Int
Int(32)
Int(32)
Int(32)
Int
Cb^Type
= Iocb^Info;!Identifies cb^openid->@iocb or @dcb
!and if msgtag is receivedepth
!and if bufaddr in EXT or LOC memory
!Openid of ITC linker or @dcb
= Openid;
!
!$RECEIVE rcb address
!File management error #
!CPU & PIN of requester, $rcv only
Openid;
Cb^Openid
Rcbaddr;
Err,
Pid;
End;
Literal
Tcblink^OffsetX =
Fcblink^OffsetX =
Lhlink^OffsetX =
Define
Iocb^Adr
Dcb^Adr
Rcv^Adr
Extaddr
Bufaddr
=
=
=
=
=
($Offset(Iocb^Template.Tcblink) '+' 1) '>>' 2,
($Offset(Iocb^Template.Fcblink) '+' 1) '>>' 2,
($Offset(Iocb^Template.Lhlink) '+' 1) '>>' 2;
Iocb^Info.Type^Iocb#,!set if openid contains @iocb
Iocb^Info.Type^Dcb #,!set if openid contains @dcb
Iocb^Info.Type^Rcv #,!set if msgtag contains @rcvbuf
Lb.Ext^Addr
#,!Not used for local buffer address
Lb.Buf^Addr
#;!Used by local buffer to hold address
Literal
Io^Avail
Io^Queued
= 0,
= 1,
Io^Itc^Queued
Io^Signal
Io^Breakowner
Io^Pending
=
=
=
=
Io^Active
= 6,
Io^Canceled
Io^Receive
Io^Reply
= 7,
= 8,
= 9;
!IOCB is available
!IOCB is queued for normal file or
!$RECEIVE IOCB in input queue for
!which no READUPDATE has been issued
!IOCB is queued for ITC file
!Signaltimeout in process
!Break ownership IOCB
!IOCB has completed but has
!not yet passed to task via ^Awaitio
!ITC IOCB than has been passed
!to listener but is not yet completed
!for linker
!Canceled ITC IOCB
!$receive requests from temp buf
!$receive that has been passed to task
2,
3,
4,
5,
Literal
Sysmsg^Operation
Control^Operation
Write^Operation
Writeread^Operation
Readlock^Operation
Lockrec^Operation
Open^Operation
Writeupdateunlock^Operation
Signaltimeout^Operation
Deviceinfo2^Operation
Lockfile^Operation
Setparam^Operation
=
=
=
=
=
=
=
=
=
=
=
=
!I/O Operation Types
0,
4!1!, Setmodenowait^Operation
1!3!, Read^Operation
3!5!, Readupdate^Operation
7,
Readupdatelock^Operation
9,
Unlockrec^Operation
11,
Writeupdate^Operation
13,
Endtrans^Operation
15,
Newprocess^Operation
17,
Pathsend^Operation
19,
Unlockfile^Operation
21;
=
=
=
=
=
=
=
=
=
=
5 !2!,
2 !4!,
6,
8,
10,
12,
14,
16,
18,
20,
?Section Dcb^Layout
!******************************************************************************!
! For each device managed by GDS, there is an entry in the DCB-table
!
Extended General Device Support (GDSX) Manual—529931-001
C- 7
DCCBDECS Listing
DCCBDECS and ULHDECSE Listings
! with the following format.
!
!******************************************************************************!
Struct Dcb^Template (*);
!Subdevice table entry (EXT MEM)
Begin
Int(32) Link[0:1];
!For placing device on linked lists
Int
Namelen;
!Length of SU name
Struct Name_;
!Name of subdevice (was 0:11 words)
Begin
String Byte[0:31];
End;
Int
Name = Name_;
Int
Accesslen;
!Length of access name
Struct Accesspoint_;
!Real access name
(was 0:11 words)
Begin
String Byte[0:31];
End;
Int
Accesspoint
= Accesspoint_;
Int
Lineno;
!Line number
Int
Flags;
!Becomes TCB.STATE when device started
Int(32) Tcbaddr;
!Address of opener
Int
Flags1;
!See below
Int(32) Stats;
!Address of XSTATS block
Int
Type;
!
For Deviceinfo support
Int
Subtype;
!
"
Int
Physreclen;
!
"
Int(32) Data[0:-1];
!User-defined terminal data
End;
!******************************************************************************!
! For each line managed by GDS, there is an entry in the line table
!
! with the following format.
!
!******************************************************************************!
Struct Line^Template(*);
!Line table entry
Begin
Int
Namelen;
!Length of LINE name
Struct Name_;
!Name of LINE was [0:7].
Begin
String Byte[0:31];
End;
Int
Name
= Name_;
Int
Accesslen;
!Length of access name
Struct Accesspoint_;
!Real access name (was 0:11)
Begin
String Byte[0:31];
End;
Int
Accesspoint = Accesspoint_;
Int
Lineno;
!Line number
Int(32) Tcbaddr;
!Address of TCB for line handler
Int
Opens;
!Number of active terminals on line
Int
Flags1;
!See below
Int
State;
!Application defined state
Int
Cmap[0:15];
!Bit map of DCBs on this line
Int
Amap[0:15];
!Bit map of Active DCBs on line
Int(32) Stats;
!Address of XSTATS block
End;
Define
Session^Flag
= Flags1.<0>
Session^Control^Flag= Flags1.<1>
#,
#,
Server^Flag
= Flags1.<2>
Server^Control^Flag = Flags1.<3>
#,
#,
Open^State
Temporary
#,
#,
= Flags1.<10>
= Flags1.<11>
!Session Flags
!Session control mechanism
! 0: Control 11/12
! 1: Other means
!Server Flags
!Ways of server is used
! 0: only server requests
! 1: can function as FE/BE
!DCB is in 'open-state'
!Deallocate when closed
Extended General Device Support (GDSX) Manual—529931-001
C- 8
DCCBDECS Listing
DCCBDECS and ULHDECSE Listings
Nowaitdepth^Def
= Flags1.<12:15>#;
!Parameter to open
!------------------------------------------------------------------------------!
! With each file, with the exception of $RECEIVE, opened within the GDS, an
!
! FCB is associated. The FCB serves to store open parameters for the file so !
! that it can be CHECKOPENed automatically by the GDS. In addition, the FCB !
! holds the last file management error occuring on the file as well as the
!
! list header for the chain of IOCBs associated with the file. Also included !
! in the FCB is an OWNER field. FCB.FLAGS.<0> determines whether this file
!
! is opened PRIVATE (address of NUMBER parameter to ^OPEN in swappable
!
! stack or in upper memory) or PUBLIC (NUMBER parameter in GLOBAL storage).
!
! For public files, the OWNER field of the FCB contains the address of the
!
! NUMBER parameter to ^OPEN. For PRIVATE files, the OWNER contains the
!
! address of the TCB for the task opening the file. Files opened in PRIVATE !
! mode are automatically closed when the owning task is stopped.
!
!------------------------------------------------------------------------------!
Struct FCB^Template (*);
Begin
Int
File;
!File #
Int
Error;
!Last file management error #
Int(32) Iocbh,
!List header for iocbs
Iocbt;
! "
tailer
"
!**************** Checkpointed part of the FCB ***************************
Int
Flags;
!Pre-Exceed. For ^OPEN
Int
Access;
!Access Mode
\
Int
Exclusion;
!Exclusion Mode > replaces flags
Int
Nowait;
!Nowait Depth
/
variable
Int
Sync;
!Sync depth
Int(32) Lhaddr;
!Recipient's TCB address (ITC)
Int(32) Owner;
!if private file -> TCB address
!if public file -> Address of variable
!
where file # stored
Int
Options;
!Open Options
Int
Blockbufid;
!Seq Block Buffer id
Int
Blockbuflen;
!Seq Block Buffer len
Int
Public;
!if true, public file
Int
Type[0:4];
!Device Type/subtype/etc. Now 5 words
Int(32) Elections;
!set < 31> bit to Use 64-bit primary keys
End;
!------------------------------------------------------------------------------!
! For each of our openers, a Requester Control Block (RCB) is allocated.
!
!------------------------------------------------------------------------------!
Struct Rcb^Template (*);
Begin
!Non-Checkpointed Part
Int(32) Link[0:1];
!List Links for available RCBs or
!list of RCBs corresponding to
!same hash bucket
Int(32) Iocbh;
!List Header for IOCBs from this
Int(32) Iocbt;
!Requester
!**************** Checkpointed part of the RCB ***************************
Int(32) Tcbaddr;
!Address of TCB for This requester
Int
Pri^Process^Handle[0:9]; !Process Handle for primary
Int
P^Phandle[0:9]= Pri^Process^Handle;
Int
Processid[0:3]= P^Phandle;!Processid Pre^D00 was [0:2]
Int
Bu^Process^Handle[0:9];
!Process Handle for backup
Int
B^Phandle[0:9]= Bu^Process^Handle;
Int
Pfile;
!Primary Requester's file number
Int
Tcp^File
= Pfile;
!TCPs internal file # for this terminal
Int
Bfile;
!Backup Requester's file number
Int
Flags;
!Requester's open options
Int
Syncdepth;
!Opener's <syncdepth> param for open
Int
Owner;
!PROCESSACCESSID of Opener/Requester
Int
Access^Mode;
!Requester's access mode
Int
Exclusion^Mode;
!Requester's exclusion mode
Int
Options;
!Requester's open options
Int
Nowaitdepth;
!Requester's nowaitdepth
Int
Len;
!Length of Process Descriptor
Int
Desc[0:15]; !32 bytes!
!Process Descriptor (may be unnamed)
End;
Define P^Pid = Processid[3]#,
B^Pid = Processid[4]#;
Extended General Device Support (GDSX) Manual—529931-001
C- 9
DCCBDECS Listing
DCCBDECS and ULHDECSE Listings
Define Ppid
Bpid
= Processid[3]#,
= Processid[4]#;
?Section Common^Data
! The TABLE pointers must be initialized to point to the upper memory tables
Int
.EXT Linetbl
(Line^Template),
!GDSX
Line table
for EXT usage
.EXT LinetblX (Line^Template) = Linetbl;
Int(32) .EXT Dcbtbl,
!GDSX
Subdev table for EXT usage
.EXT DcbtblX
= Dcbtbl;
Int Trace^Control^Flags [0:1];
Define
Tscode^Trace
Ext^Req^Trace
Ext^Data^Trace
Int^Req^Trace
Int^Data^Trace
Int^Disp^Trace
Resrce^Cb^Trace
Resrce^Pool^Trace
Ext^Ctrl^Trace
Int^Req^Ctrl^Trace
Int^Task^Ctrl^Trace
Nst^Ctrl^Trace
Err^Ctrl^Trace
Uscode^Trace
Term^Req^Trace
Term^Data^Trace
Term^Intr^Trace
Line^Req^Trace
Line^Data^Trace
Line^Intr^Trace
Sr^Cb^Trace
Sr^Pool^Trace
Sr^Ctrl^Trace
Sr^Misc^Trace
!Trace control flags
=
=
=
=
=
=
=
=
=
=
=
=
=
Trace^Control^Flags[0]
#,
Trace^Control^Flags[0].<0>
#,
Trace^Control^Flags[0].<1>
#,
Trace^Control^Flags[0].<2>
#,
Trace^Control^Flags[0].<3>
#,
Trace^Control^Flags[0].<4>
#,
Trace^Control^Flags[0].<5>
#,
Trace^Control^Flags[0].<6>
#,
Trace^Control^Flags[0].<7>
#,
Trace^Control^Flags[0].<8>
#,
Trace^Control^Flags[0].<9>
#,
Trace^Control^Flags[0].<10>
#,
Trace^Control^Flags[0].<11>
#,
! <12:15> =
! TSCODE TRACE
! GDSX
REQ
! GDSX
DATA
! INTR REQ
! INTR DATA, TMF
! DISP
! CB
! POOL
! SYS MSG CONTROL
! REQ CONTROL
! TASK CONTROL
! NONSTOP CONTROL
! ERR MSG CONTROL
rfe
=
=
=
=
=
=
=
=
=
=
=
Trace^Control^Flags[1]
#,
Trace^Control^Flags[1].<0>
#,
Trace^Control^Flags[1].<1>
#,
Trace^Control^Flags[1].<2>
#,
Trace^Control^Flags[1].<3>
#,
Trace^Control^Flags[1].<4>
#,
Trace^Control^Flags[1].<5>
#,
Trace^Control^Flags[1].<6>
#,
Trace^Control^Flags[1].<7>
#,
Trace^Control^Flags[1].<8>
#,
Trace^Control^Flags[1].<9>
#;
! <10:15> =
! USCODE TRACE
! TERM REQ
! TERM DATA
! TERM INTERNAL
! LINE REQ
! LINE DATA
! LINE INTERNAL
! SR CB
! SR POOL
! SR CONTROL
! SR MISC
RFE
!------------------------------------------------------------------------------!
! to prevent to scan tables, we keep a bitmap for each of the blocks which
!
! are descibed above to indicate which entry we have in use.
!
!------------------------------------------------------------------------------!
Struct .Map;
Begin
Int Tcbs [0:127]; !was [0:15]; 16 * 128 = 2048
Int Rcbs [0:127]; !was [0:31]; 16 * 128 = 2048
Int Fcbs [0:127]; !was [0:15]; 16 * 128 = 2048
Int Pcbs [0:063]; !was [0:15]; 16 * 64 = 1024
Int Dcbs [0:127]; !was [0:31]; 16 * 128 = 2048
Int Ldcbs[0:127]; !was [0:15]; 16 * 128 = 2048
Int Lines[0:003]; !was [0:0];
16 *
4 = 64
End;
!------------------------------------------------------------------------------!
!
Literal Events
!
!------------------------------------------------------------------------------!
Literal
Disp^Stop
= %000001,
!Task has been stopped
Disp^Continue = %000002,
!Continue execution
Disp^Can
= %000004,
!Cancel ITC event
Disp^Imsg
= %000010,
!$Receive message
Disp^Itc
= %000020,
!ITC request
Disp^Ioc
= %000040,
!I/O completion
Disp^Resource = %000100,
!Resource for which task has been
!waiting has been obtained
Disp^Change
= %000200,
!Line Handler's configuration changed
E^Timeout
E^Stop
E^Continue
E^Can
=
=
=
=
0,
1,
2,
3,
Extended General Device Support (GDSX) Manual—529931-001
C -10
DCCBDECS Listing
DCCBDECS and ULHDECSE Listings
E^Imsg
E^Itc
E^Ioc
E^Resource
E^Change
=
=
=
=
=
4,
5,
6,
7,
8;
?Section Errors
! Guardian File Error Codes
!
Literal
FEOk
FEEof
FESysmess
FENotfound
FEBadname
FENotopen
FEBadcount
FEBoundserr
FEToomany
FENolcb
FENopoolspace
FENocbspace
FENoiophysmem
FESecviol
FEOpenstop
FEContinue
FENotransid
FEInvtransid
FEToomanytransbegins
FETransabrtownerdied
FETransabrtnetdown
FETransabrtoprcmd
FEToocheap
FEBreakonly
FELinereset
FEEotreceived
FENodata
FEOwnership
FECpupon
FEScerror
FEPathdown
FEFatpin
!
!
!
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
0
1
6
11
13
16
21
22
28
30
32
34
37
48
61
70
75
78
83
90
92
94
99
110
124
163
187
200
230
233
201
560
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
;
FEInvalop
FEDup
FEInuse
FENosuchdevice
FENoprimary
=
=
=
=
=
2
10
12
14
17
,
,
,
,
,
FENonout
FEmissparm
FENobufspace
FENoiobufspace
FENoiocbspace
FETimedout
FEWrongid
FEDevdown
FEBadreply
FEEndedtransid
FETmfnotrunning
FETmfnotconfigured
FETransabrtbaddbid
FETransabrtaudoflow
FEAbortedtransid
FENotready
FEBreak
FEModemerr
FEPollEnd
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
26
29
31
33
35
40
60
66
74
76
81
84
91
93
97
100
111
140
176
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
FEOwnabort
FEIopon
= 210 ,
= 231 ,
FENetdown
= 250 ,
The following is a list of all the server class errors.
error numbers 900 - 950.
Literal
FSCerror
= 233,
FEScFirstError
FEScInvalidServerClassName
FEScInvalidPathmonName
FEScPathmonConnect
=
=
=
=
900,
900,
901,
902,
FEScPathmonMessage
= 903,
FEScServerLinkConnect
= 904,
FEScNoServerAvailable
FEScNoSendEverCalled
= 905,
= 906,
FEScInvalidSegmentID
= 907,
FEScNoSegmentInUse
= 908,
FEScInvalidFlagsValue
= 909,
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
Pathsend reserves
^Serverclass_Send_ error, call
^Serverclass_Send_Info_
First available Pathsend Error.
Invalid server class name.
Invalid Pathmon process name.
Error with Pathmon
connection (eg. Open, I/O,
etc.).
Unknown message received from
Server Monitor.
Error with Server Link
connection
(eg. Open, I/O, etc. ).
No Server Available.
the user called ^SERVERCLASS_SEND_INFO_
before ever calling ^SERVERCLASS_SEND_.
The caller is using an extended
segment id that is out of range.
The caller supplied a reference
parameter which is an extended
address, but doesn't have an
extended segment in use.
The caller set bits in the flags
parameter that are reserved and
must be 0.
Extended General Device Support (GDSX) Manual—529931-001
C -11
ULHDECSE Listing
DCCBDECS and ULHDECSE Listings
FEScMissingParameter
= 910,
FEScInvalidBufferLength
= 911,
FEScParameterBoundsError
= 912,
FEScServerClassFrozen
FEScUnknownServerClass
= 913,
= 914,
FEScPathmonShutDown
= 915,
FEScServerCreationFailure
= 916,
FEScServerClassTmfViolation
= 917,
FEScOperationAborted
= 918,
FEScInvalidTimeoutValue
= 919,
FEScPFSUseError
= 920,
FEScTooManyPathmons
= 921,
FEScTooManyServerClasses
= 922,
FEScTooManyServerLinks
= 923,
FEScTooManySendRequests
= 924,
FEScTooManyRequesters
= 925,
FEScTooManyTestPointUsers
= 946,
FEScLinkMonConnect
= 947,
FEScRetryOpen
FEScLastError
= 949,
= 950;
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
A required parameter was not
supplied.
One of the buffer length parameters
is invalid.
A reference parameter is out of
bounds.
The server class is frozen.
ServerMonitor does not recognize
Server Class name.
send denied because Pathmon
is shutting down.
send denied by server monitor
because of server creation
failure.
The TMF transaction mode of
the send does not match that
of the server class (eg.
Requester send has a TransId
and the derver class is
configured with TMF OFF).
send operation aborted. See
accompanying Guardian error
for more information.
The caller supplied an invalid
timeout value.
The caller's PFS segment could
not be accessed.
The maximum number of Pathmons
allowed has been exceeded.
The maximum number of server
classes allowed has been exceeded.
The maximum number of allowed
server links has been exceeded.
The maximum number of allowed send
requests has been exceeded.
!
!
!
!
!
!
!
!
!
The maximum number of allowed
requesters has been exceeded.
The maximum number of allowed
test point users has been exceeded.
Error with cink Monitor
connection
(eg. Open, I/O, etc. ).
This is an internal error ONLY.
Last available Pathsend error.
ULHDECSE Listing
! THIS FILE IS AN EDITED COPY OF DCCBDECS (?SECTION LINE^TEMPLATES)
?SECTION TEMPLATES
STRUCT dcb^template (*);
!Subdevice table entry (EXT MEM)
!!dd00
BEGIN
INT(32) link[0:1];
!For placing device on linked lists
!!dd00
INT namelen;
!Length of SU name
!!dxcd
STRUCT name_;
!Name of subdevice (was 0:11 words) !!dxcd
BEGIN
!dxcd
STRING byte[0:31];
!dxcd
END;
!dxcd
INT name = name_;
!dxcd
INT accesslen; !Investigate !!Length of access name
!!dxcd
STRUCT accesspoint_;
!Real access name
(was 0:11 words) !!dxcd
BEGIN
!dxcd
STRING byte[0:31];
!dxcd
END;
!dxcd
INT accesspoint = accesspoint_;
!dxcd
INT
lineno;
!Line number
INT
flags;
!Becomes TCB.STATE when device started
INT(32) tcbaddr;
!Address of opener
!!dd00
INT
flags1;
!User-definable variable
INT(32) stats;
!Address of XSTATS block
Extended General Device Support (GDSX) Manual—529931-001
C -12
ULHDECSE Listing
DCCBDECS and ULHDECSE Listings
INT
INT
INT
INT
END;
type;
subtype;
physreclen;
wt^rd^pend;
! For Deviceinfo support
!
"
!
"
!User-defined terminal data
!!qual
!!qual
!!qual
!!dd00
!******************************************************************************!
! For each line managed by USCODE, there is an entry in the LINETBL
!
! with the following format.
!
!******************************************************************************!
STRUCT line^template(*);
!Ext Memory Struct
!!dd00
BEGIN
INT namelen;
!Length of LINE name
!!dxcd
STRUCT name_;
!Name of LINE
(was 0:7 words) !!dxcd
BEGIN
!dxcd
STRING byte[0:31];
!dxcd
END;
!dxcd
INT name = name_;
!dxcd
INT accesslen; !Investigate !!Length of access name
!!dxcd
STRUCT accesspoint_;
!Real access name
(was 0:11 words) !!dxcd
BEGIN
!dxcd
STRING byte[0:31];
!dxcd
END;
!dxcd
INT accesspoint = accesspoint_;
!dxcd
INT
lineno;
!Line number
INT(32) tcbaddr;
!Address of TCB for line handler !!dd00
INT
opens;
!Number of active terminals on line
INT
flags1;
!User-definable variable
INT
state;
!Application defined state
INT
cmap[0:15];
!Bit map of DCBs on this line
INT
amap[0:15];
!Bit map of Active DCBs on line
INT(32) stats;
!Address of XSTATS block
END;
?SECTION getreceiveinfo^template
!-------------------------------------------------------------------------!
! New getreceiveinfo_ template structure
!
!-------------------------------------------------------------------------!
DEFINE ^getreceiveinfo^fields =
INT
op;
INT
cnt;
INT
msgtag;
INT
file;
INT(32)
syncid;
INT
phandle[0:9];
INT
openid#;
STRUCT getreceiveinfo^template (*);
BEGIN
^getreceiveinfo^fields;
END;
!I/O type
!Reply size
!Message Tag
!Requester's file number
!Syncid
!Phandle
!Open Label ID (by REPLY)
Extended General Device Support (GDSX) Manual—529931-001
C -13
!dxcd
!! "
!! "
!! "
!! "
!! "
!! "
!!dxcd
!dxcd
!dxcd
!dxcd
DCCBDECS and ULHDECSE Listings
Extended General Device Support (GDSX) Manual—529931-001
C -14
ULHDECSE Listing
D
Using Pseudo Procedures in a
TS/MP Environment
This appendix contains an example of converting a GDSX application that
communicates with a TS/MP server through a Pathway/iTS SCREEN COBOL program
and an example of a GDSX application that communicates directly with the server.
The converted program also uses the TMF to protect transactions originating in the
user code portion of GDSX.
The first half of the appendix shows the various steps required to compile, bind,
configure, and start the GDSX application as it was designed without the Pathway/iTS
and TMF pseudo procedures. The second half uses the same GDSX application but
illustrates how it was changed to use the TS/MP and Pathway/iTS procedures to
communicate directly with TS/MP servers and the TMF pseudo procedures to protect
transactions originating in the user code.
GDSX Without Pathway/iTS and TMF
Procedures
The example applications have the following configuration:
•
•
•
Two terminals send transaction data to the GDSX application named $GDSX. The
terminals are named TERM1 and TERM2.
The GDSX application (TSCODE and USCODE1) sends its transactions to a
Pathway/iTS application through a SCREEN COBOL program named
SCOBGDSX. The Pathway/iTS application is named $PWGDS.
SCOBGDSX uses two TS/MP server processes to write and delete data in the
database for the Pathway/iTS application. The two servers are named WRITERO
and DELETERO. The database has a file name of $SKY.LINZ.TSTDAT and is
protected by TMF using TMF procedures called by the Pathway/iTS application.
See Figure D-1 on page 2 for a picture of this configuration and the flow of transactions
from the terminals to the database. Source code listings of SCOBGDSX, WRITER,
DELETER, and the user code USAMPLE1 are given at the end of this subsection.
Extended General Device Support (GDSX) Manual—529931-001
D- 1
Compiling USAMPLE1
Using Pseudo Procedures in a TS/MP Environment
Figure D-1. GDSX Application Without Pathway/iTS and TMF Pseudo Procedures
$GDS
TSCODE
Pathway/iTS
TCP
NonStop TS/MP
Servers
TERM1
SCOBGDSX
WRITERO
USCODE
TERM2
DELETERO
USECODE1
$SKY.LINZ.TST
DAT
VST027.vsd
The following subsections step you through the process of compiling, binding,
configuring, and starting the GDSX and Pathway/iTS applications.
Compiling USAMPLE1
The first step is compiling the user code USAMPLE1. In the following example, the
commands to compile USAMPLE1 were entered in an OBEY file called COMP1:
CLEAR All
PARAM WORKFILE $CRASH
COMMENT
Assign SSV0 to the volume and subvolume for
COMMENT
the GDSX installation subvolume
ASSIGN SSV0, $SKY.LINZ
ASSIGN ZSPITACL, $SKY.ZSPIDEF.ZSPITACL
ASSIGN ZEMSTACL, $SKY.ZSPIDEF.ZEMSTACL
ASSIGN ZGDXTAL, $SKY.LINZ.ZGDXTAL
ASSIGN COPYTAL, $SYSTEM.SYSTEM.COPYTAL
ASSIGN SSV1, $SKY.ZSPIDEF
ASSIGN SSV2, $SYSTEM.SYSTEM
TAL /IN USAMPLE1, SWAP $CRASH, OUT $S.#USAMPL1, MEM 64,&
NOWAIT, CPU 4/ USCODE1; NOMAP, NOCODE, NOICODE
Extended General Device Support (GDSX) Manual—529931-001
D- 2
Using Pseudo Procedures in a TS/MP Environment
Binding
The user code is compiled when this command is entered at the TACL prompt:
> OBEY COMP1
Binding
The second step is binding TSCODE and USCODE1 together into a GDSX object file
named OGDS1. In the following example, the commands to do this were entered in a
file called BIND1:
ADD * FROM $SKY.LINZ.TSCODE
ADD * FROM USCODE1, DELETE
SET DATA 64 PAGES
SET INSPECT ON
SET SAVEABEND ON
SET SUBTYPE 30
BUILD OGDS1 !
CHANGE HIGHPIN ON IN OGDS1
The binding process occurs when a BIND command is entered at the TACL prompt,
specifying the BIND1 file with an IN option:
> BIND /IN BIND1/
Creating the Database
The third step is creating the database file for the TS/MP server:
> FUP PURGE $SKY.LINZ.TSTDAT
> FUP CREATE $SKY.LINZ.TSTDAT, TYPE K, REC 62, KEYLEN 11,
KEYOFF 0, EXT (20,20)
> FUP ALTER $SKY.LINZ.TSTDAT, AUDIT
The FUP ALTER command is necessary to establish the database as a file audited by
the TMF.
Starting NonStop TS/MP
The fourth step is configuring and cold starting the TS/MP application. The following
configuration commands were entered in a file named PATHIN:
SET PATHMON BACKUPCPU 1
SET PATHWAY MAXTCPS 2
SET PATHWAY MAXTERMS 10
SET PATHWAY MAXPROGRAMS 0
SET PATHWAY MAXLINKMONS 1
SET PATHWAY MAXEXTERNALTCPS 1
SET PATHWAY MAXSERVERCLASSES 2
SET PATHWAY MAXSERVERPROCESSES 4
SET PATHWAY MAXSTARTUPS 10
SET PATHWAY MAXPATHCOMS 3
SET PATHWAY MAXASSIGNS 5
SET PATHWAY MAXPARAMS 5
START PATHWAY COLD !
Extended General Device Support (GDSX) Manual—529931-001
D- 3
Using Pseudo Procedures in a TS/MP Environment
Starting NonStop TS/MP
LOG1 PATHLOG, STATUS
RESET TCP
SET TCP
SET TCP PROGRAM $SYSTEM.SYSTEM.PATHTCP2
SET TCP CPUS 0:1
SET TCP MAXTERMS 0
SET TCP MAXSERVERCLASSES 2
SET TCP MAXSERVERPROCESSES 4
SET TCP MAXPATHWAYS 2
SET TCP MAXTERMDATA 10000
SET TCP MAXRREPLY 2000
SET TCP NONSTOP 0
SET TCP PROCESS $GDST
SET TCP INSPECT ON
SET TCP TCLPROG POBJ
ADD TCP GDSX-TCP1
SET TCP CPUS 1:0
SET TCP PROCESS $GDSU
ADD TCP GDSX-TCP2
RESET TERM
SET TERM
SET TERM TCP GDSX-TCP1
SET TERM INITIAL SCOBGDSX
SET TERM TMF ON
SET TERM INSPECT OFF
SET TERM FILE $GDSX.#TERM1
SET TERM TYPE INTELLIGENT
ADD TERM GDSX-TERM1
SET
SET
SET
ADD
TERM
TERM
TERM
TERM
LIKE GDSX-TERM1
TCP GDSX-TCP1
FILE $GDSX.#TERM2
GDSX-TERM2
RESET SERVER
SET SERVER
SET SERVER PROGRAM DELETERO
SET SERVER PROCESS $GDS1
SET SERVER PROCESS $GDS2
SET SERVER CPUS (1:0, 0:1)
SET SERVER MAXSERVERS 2
SET SERVER CREATEDELAY 1 SECS
SET SERVER DELETEDELAY 30 MINS
SET SERVER NUMSTATIC 1
SET SERVER SECURITY "N"
SET SERVER TMF ON
SET SERVER (ASSIGN TSTDAY, $SKY.LINZ.TSTDAT, SHARED)
ADD SERVER DELETER
RESET SERVER
SET SERVER
Extended General Device Support (GDSX) Manual—529931-001
D- 4
Running the GDSX Application
Using Pseudo Procedures in a TS/MP Environment
SET
SET
SET
SET
SET
SET
SET
SET
SET
SET
SET
ADD
SERVER
SERVER
SERVER
SERVER
SERVER
SERVER
SERVER
SERVER
SERVER
SERVER
SERVER
SERVER
PROGRAM WRITERO
PROCESS $GDS3
PROCESS $GDS4
CPUS (0:1, 1:0)
MAXSERVERS 2
CREATEDELAY 1 SECS
DELETEDELAY 20 MINS
NUMSTATIC 1
SECURITY "N"
TMF ON
(ASSIGN TSTDAT, $SKY.LINZ.TSTDAT, SHARED)
WRITER
START TCP *
At the TACL prompt the following commands are entered to start the TS/MP and
Pathway/iTS application:
>
>
>
>
FUP PURGEDATA PATHLOG
ASSIGN PATHCTL, $SKY.LINZ.PATHCTL
PATHMON /NAME $PWGDS, NOWAIT, PRI 150, MEM 64, CPU 0/
PATHCOM /IN PATHIN/ $PWGDS
At this point the application named $PWGDS is configured and started, but the GDSX
application is not running.
Running the GDSX Application
In this step the GDSX object file is run and given the name $GDSX. The commands to
do this and set some GDSX configuration parameters were entered in the TACL macro
file named RUN1:
?TACL MACRO
STOP $GDSX
STOP $GDSX
CLEAR All
PARAM MAXLINES 0
PARAM CONTROLFLAGS 8
PARAM MAXBUFPOOL 50000
PARAM DEVICEINFO 1
RUN OGDS1 /NAME $GDSX/
Run DEVICE^HANDLER only
Run as high PIN
Make pool 10 larger
Support DEVICEINFO calls from Pathway/iTS
The GDSX application is started when the macro name is entered at the TACL prompt:
> RUN RUN1
Configuring and Starting the Terminal Tasks
The last step is configuring the two tasks for the terminals, TERM1 and TERM2, and
starting them with SCF commands. In the following example, TERM1 and TERM2 are
configured with terminals that have access names of $STAR.#PTY9 and
$STAR.#PTY10.
> SCF
-> ADD SU $GDSX.#TERM1, ACCESSNAME $STAR.#PTY9
Extended General Device Support (GDSX) Manual—529931-001
D- 5
Using Pseudo Procedures in a TS/MP Environment
USAMPLE1 Listing
DEVICETYPE 6, DEVICESUBTYPE 4, PHYSRECLEN 80
-> ADD SU $GDSX.#TERM2, ACCESSNAME $STAR.#PTY10
DEVICETYPE 6, DEVICESUBTYPE 4, PHYSRECLEN 80
-> START SU $GDSX.#TERM1
-> START SU $GDSX.#TERM2
USAMPLE1 Listing
1.
!******************************************************************************
2. ! GDSX USCODE Generic DEVICE^HANDLER
!
3. ! Sample program
!
4. !
!
5. ! Writing or deleting records in a database using IDS
!
6.
!******************************************************************************
8. ?NOMAP, NOLMAP, NOCODE, SYMBOLS, CPU TNS/II
9.
10. NAME uscode;
11.
12
13. BLOCK COMMON^TEMPLATES;
14. ?NOLIST, Source
DCCBDECS (ERRORS)
16. ?NOLIST, Source
DCCBDECS (EVENTS)
18. ?NOLIST, Source
DCCBDECS (TCB^LAYOUT)
20. ?NOLIST, Source
DCCBDECS (IOCB^LAYOUT)
22. ?NOLIST, Source
DCCBDECS (FCB^LAYOUT)
24. ?NOLIST, Source
DCCBDECS (RCB^LAYOUT)
26. !===========================================================================
27. !Comment Users may include their own file to modify DCB and LINE Templates.
28. !Comment See file ULHDECS that USAMPLE sources in here
29. ?NOLIST, Source ULHDECSE(Dcb^Template, Line^Template)
32. END BLOCK; ! COMMON^TEMPLATES
33.
34. BLOCK CONFIG^PARMS^TEMPLATES;
35. ?NOLIST, Source
DCCBDECS (CONFIG^TEMPLATES)
37. END BLOCK; ! CONFIG^PARMS^TEMPLATES
38.
39. ! Global Data
40. !
41. BLOCK CONFIG^PARMS^DATA;
42. ?NOLIST, Source
DCCBDECS (CONFIG^DATA)
44. END BLOCK; ! CONFIG^PARMS^DATA
45.
46. BLOCK COMMON^DATA;
47. ?NOLIST, Source
DCCBDECS (COMMON^DATA)
49. END BLOCK; ! COMMON^DATA
50.
51. BLOCK USER^PRIVATE;
52. LITERAL TRUE = -1, FALSE = 0;
53. END BLOCK; !USER^PRIVATE
54.
55. !===========================================================================
56. !Comment User may include System Procedures desired here.
57. ?NOLIST, Source $SYSTEM.SYSTEM.EXTDECS0(Debug,String_Upshift_)
61. ?NOLIST, Source PEXTGDS
63.
65. !===========================================================================
66. Proc Device^Handler (Term^File^Num, Internal^Term^No, Term^Type);
67. !===========================================================================
68.
69. Int Term^File^Num
,
-- file number for this D^H
task
70.
Internal^Term^No,
-- terminal number for this
D^H task
Extended General Device Support (GDSX) Manual—529931-001
D- 6
USAMPLE1 Listing
Using Pseudo Procedures in a TS/MP Environment
71.
72.
73.
74.
75.
76.
77.
78.
79.
80.
81.
82.
83.
84.
85.
86.
87.
88.
89.
90.
91.
92.
93.
94.
Term^Type
;
-- terminal type
Begin
!===========================================================================
! USCODE can declare desired DEVICE^HANDLER Local Variables here
!===========================================================================
Int
Int
Int
Int
.EXT
.EXT
.EXT
.EXT
My^Dcb
RCV^IOCB
Term^IOCB
MY^TCB
Int
String
Int
String
Int
String
.EXT
.EXT
.EXT
.EXT
.EXT
.EXT
Term^Buf
S^Term^Buf
Rcv^Buf
S^Rcv^Buf
Work^Buf
S^Work^Buf
:=
=
:=
=
:=
=
Dolr^Rcv
Evt
:= 0;
:= 0;
Int
Int
(DCB^TEMPLATE);
(IOCB^TEMPLATE);
(IOCB^TEMPLATE);
(TCB^TEMPLATE);
0D;
Term^Buf;
0D;
Rcv^Buf;
0D;
Work^Buf;
96. !===========================================================================
97. !
Initialization procedure
98. !===========================================================================
99. SubProc Initialize^Device^Handler;
100. Begin
101.
102. ! reserve all the buffers we need
103.
@RCV^Buf
:= GetExtPool(11,32);
! from message pool
104.
If @RCV^Buf
= 0D Then
105.
Call Debug;
106.
107.
@Term^Buf
:= GetExtPool(11,32);
! from message pool
108.
If @Term^Buf = 0D Then
109.
Call Debug;
110.
111.
@Work^Buf
:= GetExtPool(10,32);
! from buffer pool
112.
If @Work^Buf = 0D Then
113.
Call Debug;
114.
115.
While 1 Do Begin
116.
-- Read messages from $RECEIVE, until we receive our initialization
messge
117.
Call ^Readupdatex(Dolr^Rcv,Rcv^Buf,64);
118.
119.
Evt := Wait^Event ((Disp^Imsg + Disp^Stop), -1D);
120.
121.
Case Evt of Begin
122.
E^Imsg -> ! from $RECEIVE
123.
Begin
124.
-- let's get the address of the IOCB for the message just
completed
125.
@Rcv^Iocb := ^Listen (1,0,0);
126.
-- get the new bufferaddress
127.
@Work^Buf := Rcv^Iocb.BufaddrX;
128.
-- move the buffer
129.
If Work^Buf[7] = ["Initialization"] Then Begin
130.
-- If we have the init. message, we can exit this loop
131.
-- write the first buffer and wait for the first message
132.
Term^Buf ':=' "Enter your text: xnnnkkkkkkkkkkk.... " &
133.
Term^Buf[18] for 12;
134.
Call ^WriteReadX(Term^File^Num, Term^Buf, 50, 64);
135.
-- return to the main-loop
136.
Return;
137.
End
138.
Else
139.
-- reply to $RECEIVE, but not to the init. message
140.
-- (this is done in the main loop)
141.
Call ^Replyx();
142.
End;
Extended General Device Support (GDSX) Manual—529931-001
D- 7
Using Pseudo Procedures in a TS/MP Environment
USAMPLE1 Listing
143.
E^Stop ->
! task is stopping
144.
Call Stop^Task;
145.
End;
146.
End;
! of While
147.
148. End;
149.
151. !===========================================================================
152. Int SubProc Check^Buffer;
153. !===========================================================================
154. ! we return the value 0, when we detected an error
155. ! we return the value 1, when the buffer is OK
156. !===========================================================================
157. Begin
158.
159. Int S^Error;
160.
161. S^Error := String_Upshift_ (S^Term^Buf[0]:1,S^Term^Buf[0]:1);
162. If S^Error
Or
163.
S^Term^Buf[0] <> ["W"] And
164.
S^Term^Buf[0] <> ["D"] Then Begin
165.
Term^Buf ':=' "wrong function code (x) (must be 'd' or 'w') " &
166.
Term^Buf[22] For 18 Bytes;
167.
Return 0;
168. End;
169.
170. If Not $Numeric(S^Term^Buf[1]) Or
171.
Not $Numeric(S^Term^Buf[2]) Or
172.
Not $Numeric(S^Term^Buf[3]) Then Begin
173.
Term^Buf ':=' "loop-counter (nnn) is not numeric
" &
174.
Term^Buf[17] For 28 Bytes;
175.
Return 0;
176. End;
177.
178. -- everything is OK
179.
Return 1;
180.
181. End;
185. !===========================================================================
186. !
DEVICE^HANDLER Procedure MAIN ENTRY POINT Begins here
187. !===========================================================================
188.
189. ! Find out our own DCB- and TCB-address
190.
@My^Dcb := Dcbtbl[Internal^Term^No];
191.
@My^Tcb := My^Dcb.Tcbaddr;
192.
193.
-- Do the initialization - wait for buffer 'Initialization'
194.
Call Initialize^Device^Handler;
195.
196.
-- Do the Main-Loop
197.
While 1 Do Begin
198.
199.
Evt := Wait^Event ((Disp^Imsg + Disp^Ioc + Disp^Stop), -1D);
200.
201.
Case Evt of Begin
202.
E^Imsg -> ! From $Rcv
203.
Begin
204.
-- let's get the address of the IOCB for the message just
completed
205.
@Rcv^Iocb := ^Listen (1,0,0);
206.
-- get the new address of the new buffer
207.
@Work^Buf := Rcv^Iocb.BufaddrX;
208.
-- move the buffer
209.
Term^Buf ':=' "Rep: " & Work^Buf[1] For
210.
(Rcv^Iocb.Iocnt-2) Bytes;
211.
-- write the buffer to our device
212.
Call ^WriteReadX(Term^File^Num, Term^Buf, 50, 62);
213.
End;
214.
215.
E^Ioc -> ! from our device
216.
Begin
217.
-- let's get the address of the IOCB for the message just
completed
Extended General Device Support (GDSX) Manual—529931-001
D- 8
Using Pseudo Procedures in a TS/MP Environment
218.
219.
220.
221.
222.
223.
224.
225.
226.
227.
228.
229.
230.
231.
232.
233.
234.
235.
236.
237.
238.
239.
240.
241.
242.
243.
244.
245.
246.
247.
248
249.
250.
251.
252.
253.
254.
255.
256.
257.
258.
259.
260.
261.
262.
263.
264.
265.
266.
267.
268.
269.
270.
271.
272.
273.
274.
275.
276.
277.
278.
279.
280.
281.
282.
283
284.
285.
286.
287.
288.
289.
290.
291.
USAMPLE1 Listing
@Term^Iocb := ^Listen (0,-1,0);
-- get the new address of the new buffer
@Work^Buf := Term^Iocb.BufaddrX;
-- clear the buffer, that we send to the IDS requester
RCV^Buf ':=' " " & RCV^Buf for 31;
-- move the buffer that we received from our device
RCV^Buf ':=' 0 & Work^Buf For Term^Iocb.Iocnt Bytes;
If Check^Buffer Then Begin
-- Buffer passed our checks
-- send the buffer that we just received to the IDS requester
Call ^Replyx(S^RCV^Buf, 64, ,Rcv^Iocb.MsgTag);
-- wait for the reply from the IDS requester
Call ^Readupdatex(Dolr^Rcv, RCV^Buf, 64);
End
Else Begin
-- buffer did not pass our checks
-- write the errorsmessage and let the user retry
Call ^WriteReadX(Term^File^Num, Term^Buf, 50, 62);
End;
End;
E^Stop ->
-- task is stopping
Call Stop^Task;
End;
-- of Case Evt
End;
-- of While
End;
-- Proc
!===========================================================================
!
Other User^Exits
!===========================================================================
!===========================================================================
Proc LINE^HANDLER (LINE^FILE^NUM, INTERNAL^LINE^NO, IN^QUEUE^FILE^NUM);
!===========================================================================
Int LINE^FILE^NUM, INTERNAL^LINE^NO, IN^QUEUE^FILE^NUM;
Begin
End;
!===========================================================================
Proc User^Initialize(Primary);
!===========================================================================
Int primary;
Begin
End;
!===========================================================================
Int Proc USER^START (DCBP, OPENID);
!===========================================================================
Int .EXT DCBP;
Int (32) .OPENID;
Begin
! OPENID specified by USER (In this case, pointer to DCB)
! is stored in TCB.OPENID
OPENID := @DCBP;
Return 0;
End;
!===========================================================================
Proc USER^STOP (TCB);
!===========================================================================
Int .EXT TCB(TCB^TEMPLATE);
Begin
End;
!===========================================================================
Proc PROCESS^ASSIGNS (buf);
!===========================================================================
Extended General Device Support (GDSX) Manual—529931-001
D- 9
USAMPLE1 Listing
Using Pseudo Procedures in a TS/MP Environment
292.
293.
294.
295.
296.
297.
298.
299.
300.
301.
302.
303.
304.
305.
306.
307.
308.
309.
310.
313.
314.
315.
316.
317.
318.
found
319.
320.
value
321.
value
322.
323.
324.
325.
326.
param
327.
328.
329.
330.
331.
332.
333.
string
334.
TSCODE
335.
336.
337.
338.
339.
340.
341.
342.
343.
344.
345.
346.
347.
348.
349.
350.
351.
352.
353.
354.
355.
356.
357.
358.
360.
361.
362.
Int .buf;
Begin
End;
!===========================================================================
Proc PROCESS^USER^PARAMS (user^param^buf);
!===========================================================================
String .user^param^buf;
Begin
Literal eof = %377;
STRING
xlate^user^parm^name = 'p' := [
!01234567890123
4
56789012345678
9
"USERPARAM1
", 1, "USERPARAM2
", 2,
eof ];
STRING
.s := @user^param^buf
,
item^name [0:13]
;
use index; index := 0;
While xlate^user^parm^name [index] <> eof
Begin
Do
! If within table
item^name ':=' xlate^user^parm^name [index] for s; ! get table name
If item^name = s[1] for s Then
! param name
Begin
@s := @s[s+1] ;
! point to param
! assign param
! set the desired parameter variable to parm value(s[1] FOR s)
goto try^next^param;
End
Else
index := index + 15;
! go to next
End;
drop index;
@s := @s [s+1];
! name not found let us forget it
try^next^param:
! if multiple user parm messages are in one
! continue to process, otherwise return to
Return;
End;
! for further processing
!===========================================================================
Int Proc USER^ATTRIBUTES (sg^cmd, sg^objtype, sg^objname, token^code,
token^value);
!===========================================================================
Int
sg^cmd
sg^objtype
.sg^objname
.token^value
INT(32) token^code
,
,
,
;
;
!
!
!
!
!
SPI command for
object type for
object name for
SPI token value
SPI token code
this request
this request
this request
for this token
Begin
Return 0;
End;
!===========================================================================
Proc USER^BACKUP;
!===========================================================================
Begin
End;
!===========================================================================
Int Proc USER^COMMANDS (iocb, file^error, sg^error) ;
Extended General Device Support (GDSX) Manual—529931-001
D -10
Using Pseudo Procedures in a TS/MP Environment
SCOBGDSX Listing
363. !===========================================================================
364.
365. Int .EXT iocb (iocb^template), ! routines for processing
366.
.file^error
,
! user's commands, functions, etc.
367.
.sg^error
;
368. Begin
369.
370.
SG^ERROR := -1;
! -1 indicates that this command is unknown
371.
Return 0;
372.
373. END ;
374.
375.
376.
377. !===========================================================================
378. Proc user^init^config^params;
379. !===========================================================================
380. Begin
381. End;
382.
383.
384.
385. !===========================================================================
386. Int Proc USER^REPLIES (sg^cmd, sg^objtype, sg^objname, sg^buf);
387. !===========================================================================
388. Int
sg^cmd
,
! SPI command for this request
389.
sg^objtype
,
! object type for this request
390.
sg^objname
,
! object name for this request
391.
.sg^buf
;
! SPI response buffer
392.
393. Begin
394.
Return 0;
395. End ;
396.
397. !===========================================================================
398
Proc User^Takeover;
399. !===========================================================================
400. Begin
401.
402. End;
403.
404.
405. !===========================================================================
406. Int Proc User^Version (version^string);
407. !===========================================================================
408. String .version^string;
409. Begin
410.
411.
version^string ':=' "011493" ; ! Jan. 14 1993 User Version
412.
Return 1;
413.
414. End;
415.
!***EOF***********************************************************************
SCOBGDSX Listing
1
******************************************************************************
2
* Sample SCREEN COBOL program for communication with GDSX. *
3
******************************************************************************
4
Identification Division.
5
Program-Id.
SCOBGDSX.
6
7
******************************************************************************
8
Environment Division.
9
******************************************************************************
10
Configuration Section.
Extended General Device Support (GDSX) Manual—529931-001
D -11
Using Pseudo Procedures in a TS/MP Environment
SCOBGDSX Listing
11
Source-Computer.
T16.
12
Object-Computer.
T16,
13
Terminal is Intelligent.
14
15
******************************************************************************
16
Data Division.
17
******************************************************************************
18
Working-Storage Section.
19
*
20
01 Ws-Send.
21
05 Ws-Send-Reply-Code
Pic 9(4) Comp.
22
05 Ws-Send-Function-Code
Pic X(01).
23
05 Ws-Send-Loop
Pic 9(03).
24
05 Ws-Send-Key1
Pic X(08).
25
05 Ws-Send-Text
Pic X(50).
26
*
27
01 Ws-Rcvd.
28
05 Ws-Rcvd-Reply-Code
Pic 9(4) Comp.
29
05 Ws-Rcvd-Function-Code
Pic X(01).
30
05 Ws-Rcvd-Loop
Pic 9(03).
31
05 Ws-Rcvd-Key1
Pic X(08).
32
05 Ws-Rcvd-Text
Pic X(50).
33
34
*
35
01 Flags.
36
02 Ws-Exit-Flag
Pic 9(01) Value 0.
37
88 Exit-Program
Value 1.
38
02 Serv-Ok
Pic X(03).
40
******************************************************************************
41
Message Section.
42
******************************************************************************
43
01 Send-Msg.
44
05 Send-Msg-Reply-Code
Pic 9(4) Comp
45
From Ws-Send-Reply-Code.
46
05 Send-Msg-Function-Code
Pic X(01)
47
From Ws-Send-Function-Code.
48
05 Send-Msg-Loop
Pic 9(03)
49
From Ws-Send-Loop.
50
05 Send-Msg-Key-1
Pic X(08)
51
From Ws-Send-Key1.
52
05 Send-Msg-Text
Pic X(50)
53
From Ws-Send-Text.
54
*
55
01 Rcvd-Msg.
56
05 Rcvd-Msg-Reply-Code
Pic 9(4) Comp
57
To
Ws-Rcvd-Reply-Code.
58
05 Rcvd-Msg-Function-Code
Pic X(01)
59
To
Ws-Rcvd-Function-Code.
60
05 Rcvd-Msg-Loop
Pic 9(03)
61
To
Ws-Rcvd-Loop.
62
05 Rcvd-Msg-Key-1
Pic X(08)
63
To
Ws-Rcvd-Key1.
64
05 Rcvd-Msg-Text
Pic X(50)
65
To
Ws-Rcvd-Text.
66
*
67
*******************************************************************************
68
Procedure Division.
69
*******************************************************************************
70
001-Main-Line.
71
Perform 050-Initialize-Data.
72
Perform 100-IDS-Loop until Exit-Program.
73
Perform 999-Exit-Program.
74
*
75
050-Initialize-Data.
76
Move 0
to Ws-Exit-Flag.
77
*
78
Move Space
to Ws-Send-Text.
Extended General Device Support (GDSX) Manual—529931-001
D -12
WRITER Listing
Using Pseudo Procedures in a TS/MP Environment
79
Move "Initialization" to Ws-Send-Text.
80
*
81
100-IDS-Loop.
82
Move Zero
to Ws-Send-Reply-Code.
83
84
Send Message Send-Msg
85
Reply Code 0 Yields Rcvd-Msg
86
On Error Perform 300-Send-Msg-Error.
87
*
88
If Ws-Rcvd-Function-Code = "d" or
89
Ws-Rcvd-Function-Code = "D"
90
Perform 150-Send-to-Delete-Server
91
Else
92
If Ws-Rcvd-Function-Code = "w" or
93
Ws-Rcvd-Function-Code = "W"
94
Perform 200-Send-to-Write-Server.
95
*
96
150-Send-to-Delete-Server.
97
Move "YES" to SERV-OK.
98
Begin-Transaction.
99
100
Send Ws-Rcvd to "Deleter"
101
Reply Code 0 Yields Ws-Send
102
On Error Perform 400-Send-Server-Error.
103
104
If Serv-Ok = "YES"
105
End-Transaction.
106
*
107
200-Send-to-Write-Server.
108
Move "YES" to SERV-OK.
109
Begin-Transaction.
110
111
Send Ws-Rcvd to "Writer"
112
Reply Code 0 Yields Ws-Send
113
On Error Perform 400-Send-Server-Error.
114
115
If Serv-Ok = "YES"
116
End-Transaction.
117
*
118
400-Send-Server-Error.
119
Abort-Transaction.
120
Move "NO" to SERV-OK.
121
*
122
300-Send-Msg-Error.
123
Exit Program.
124
*
125
999-Exit-Program.
126
Exit Program.
127
*
128
***Eof**************************************************************************
WRITER Listing
5
7
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
Identification Division.
Program-Id.
Writer
Environment Division.
Configuration Section.
Source-Computer.
Object-Computer.
Special-Names.
Myterm
Tandem/16.
Tandem/16.
is Tout.
Input-Output Section.
File-Control.
*
Select Message-In
File Status
Assign to $Receive
is Receive-File-Status.
*
Extended General Device Support (GDSX) Manual—529931-001
D -13
WRITER Listing
Using Pseudo Procedures in a TS/MP Environment
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
Select Message-Out
File Status
Assign to $Receive
is Receive-File-Status.
*
Select Tstdat Assign
Organization
Access Mode
Record Key
File Status
to
is
is
is
is
File1
Indexed
Dynamic
Tstdat-Key
File-Stat.
*
Receive-Control.
Table
occurs 3 Times
Syncdepth limit is 1
Reply
contains 64 Characters.
Data Division.
File Section.
FD
Message-In
Label Records are omitted
Record contains 1 to 64 Characters.
01 In-Message.
05 In-Message-Reply-Code
05 In-Message-Function-Code
05 In-Message-Key.
10 In-Message-Loop
10 In-Message-Key-1
05 In-Message-Text
FD
Pic 9(03).
Pic X(08).
Pic X(50).
Message-Out
Label Records are omitted
Record contains 1 to 64 Characters.
01 Out-Message.
05 Out-Message-Reply-Code
05 Out-Message-Function-Code
05 Out-Message-Key.
10 Out-Message-Loop
10 Out-Message-Key-1
05 Out-Message-Text
FD
Pic 9(04) Comp.
Pic X(01).
Pic 9(04) Comp.
Pic X(01).
Pic 9(03).
Pic X(08).
Pic X(50).
Tstdat
Label Records are omitted.
01 Tstdat-Rec.
05 Tstdat-Key.
10 Tstdat-Key-1
10 Tstdat-Loop
05 Tstdat-Text
Pic X(08).
Pic 9(03).
Pic X(50).
Working-Storage Section.
01
Misc-Data.
05 Ok-Message.
10 Filler
10 Ok-Nmbr
10 Filler
05
05
05
05
I
File-Stat
File-Stat-N Redefines File-Stat
88 No-Error
88 File-Error
88 End-of-file
88 Already-Exists
88 Not-Found
88 Dataset-Full
Receive-File-Status.
10 Stat-1
88 Close-From-Requester
Pic X(05) Value Spaces.
Pic 9(03).
Pic X(42)
Value " recs written ".
Pic S9(04) Comp.
Pic X(02).
Pic 9(02).
Value
Zero.
Values 01 Thru 99.
Value
10.
Value
22.
Value
23.
Value
24.
Pic 9(01) Value Zero.
Value
1.
Extended General Device Support (GDSX) Manual—529931-001
D -14
Using Pseudo Procedures in a TS/MP Environment
WRITER Listing
101
10 Stat-2
Pic 9(01) Value Zero.
103
104
********************************************************************************
105
Procedure Division.
106
********************************************************************************
107
Declaratives.
108
109
Ua-Message-In Section.
110
Use after Error Procedure on Message-In.
111
Ua-Message-In-Proc.
112
If Receive-File-Status Not = "10"
113
Display "Mirror " " Error in Message-In file "
114
" Stat-1 = " Stat-1 " Stat-2 = " Stat-2
Upon Tout.
115
116
Ua-Message-Out Section.
117
Use after Error Procedure on Message-Out.
118
Ua-Message-Out-Proc.
119
If Receive-File-Status Not = "10"
120
Display "Mirror " " Error in Message-Out file "
121
" Stat-1 = " Stat-1 " Stat-2 = " Stat-2
Upon Tout.
122
End Declaratives.
124
********************************************************************************
125
*
M A I N - L O G I C
*
126
********************************************************************************
127
128
Main Section.
129
Begin-Cobol-Server.
130
*
Initialization of server
131
Perform A-Init.
132
133
Perform B-Trans until Close-From-Requester.
134
Perform C-Eoj.
135
Stop Run.
136
137
138
A-Init.
139
Open Input Message-In.
140
Open Output Message-Out
Syncdepth 1.
141
Open I-O
TstDat.
142
*
143
B-Trans.
144
*
Initialization
145
*
- of longest Msg
(In-Message)
146
*
- of longest Reply
(Out-Message)
147
Move Space to In-Message, Out-Message.
148
149
*
Read Request from $Receive
150
Read Message-In.
151
*
If not EOF of $Receive goto D-Process-Message
152
If Not Close-From-Requester
153
Perform D-Process-Message.
154
*
155
C-Eoj.
156
Close Message-In,
157
Message-Out,
158
TstDat.
159
*
160
*
161
D-Process-Message.
162
Move 1 to I.
163
Move In-Message
to Out-Message.
164
Move Zeroes
to Out-Message-Reply-Code.
165
166
Move In-Message-Key-1 to Tstdat-Key-1.
167
Move In-Message-Text to Tstdat-Text.
168
Extended General Device Support (GDSX) Manual—529931-001
D -15
DELETER Listing
Using Pseudo Procedures in a TS/MP Environment
169
Move In-Message-Loop to Ok-Nmbr.
170
171
Perform E-Write Varying I From 1 by 1 Until I > In-Message-Loop.
172
173
If I < 9999
174
Move Ok-Message
to Out-Message-Text.
175
176
Write Out-Message.
177
178
179
E-Write.
180
Move I
to Tstdat-Loop.
181
Write Tstdat-Rec.
182
If File-Error
183
If Already-Exists
184
Read Tstdat with Lock
185
If File-Error
186
Move I
to Ok-Nmbr
187
Move 9999
to I
188
Move File-Stat-N
to Out-Message-Loop
189
Move "Error reading tstdat"
to Out-Message-Text
190
Else
191
Rewrite Tstdat-Rec With Unlock
192
If File-Error
193
Move I
to Ok-Nmbr
194
Move 9999
to I
195
Move File-Stat-N
to Out-Message-Loop
196
Move "Error rewriting tstdat" to Out-Message-Text
197
Else
198
Next Sentence
199
Else
200
Move I
to Ok-Nmbr
201
Move 9999
to I
202
Move File-Stat-N
to Out-Message-Loop
203
Move "Error writing tstdat" to Out-Message-Text.
204
*
205
***Eof**************************************************************************
DELETER Listing
5
7
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
Identification Division.
Program-Id.
Deleter.
Environment Division.
Configuration Section.
Source-Computer.
Object-Computer.
Special-Names.
Myterm
Tandem/16.
Tandem/16.
is Tout.
Input-Output Section.
File-Control.
*
Select Message-In
File Status
Assign to $Receive
is Receive-File-Status.
Select Message-Out
File Status
Assign to $Receive
is Receive-File-Status.
*
*
Select Tstdat Assign
Organization
Access Mode
Record Key
File Status
to
is
is
is
is
File1
Indexed
Dynamic
Tstdat-Key
File-Stat.
*
Receive-Control.
Table
occurs 3 Times
Syncdepth limit is 1
Extended General Device Support (GDSX) Manual—529931-001
D -16
Using Pseudo Procedures in a TS/MP Environment
DELETER Listing
40
Reply
contains 64 Characters.
41
42
Data Division.
43
44
File Section.
45
46
FD Message-In
47
Label Records are omitted
48
Record contains 1 to 64 Characters.
49
50
01 In-Message.
51
05 In-Message-Reply-Code
Pic 9(04) Comp.
52
05 In-Message-Function-Code
Pic X(01).
53
05 In-Message-Key.
54
10 In-Message-Loop
Pic 9(03).
55
10 In-Message-Key-1
Pic X(08).
56
05 In-Message-Text
Pic X(50).
58
59
FD Message-Out
60
Label Records are omitted
61
Record contains 1 to 64 Characters.
62
63
01 Out-Message.
64
05 Out-Message-Reply-Code
Pic 9(04) Comp.
65
05 Out-Message-Function-Code
Pic X(01).
66
05 Out-Message-Key.
67
10 Out-Message-Loop
Pic 9(03).
68
10 Out-Message-Key-1
Pic X(08).
69
05 Out-Message-Text
Pic X(50).
70
71
FD Tstdat
72
Label Records are omitted.
73
74
01 Tstdat-Rec.
75
05 Tstdat-Key.
76
10 Tstdat-Key-1
Pic X(08).
77
10 Tstdat-Loop
Pic 9(03).
78
05 Tstdat-Text
Pic X(50).
79
80
81
Working-Storage Section.
82
83
01 Misc-Data.
84
05 Ok-Message.
85
10 Filler
Pic X(05) Value Spaces.
86
10 Ok-Nmbr
Pic 9(03).
87
10 Filler
Pic X(42)
88
Value " recs deleted ".
89
05 I
Pic S9(04) Comp.
90
05 File-Stat
Pic X(02).
91
05 File-Stat-N Redefines File-Stat
Pic 9(02).
92
88 No-Error
Value
Zero.
93
88 File-Error
Values 01 Thru 99.
94
88 End-of-file
Value
10.
95
88 Already-Exists
Value
22.
96
88 Not-Found
Value
23.
97
88 Dataset-Full
Value
24.
98
05 Receive-File-Status.
99
10 Stat-1
Pic 9(01) Value Zero.
100
88 Close-From-Requester
Value
1.
101
10 Stat-2
Pic 9(01) Value Zero.
103
104
********************************************************************************
105
Procedure Division.
106
********************************************************************************
107
Declaratives.
108
109
Ua-Message-In Section.
110
Use after Error Procedure on Message-In.
111
Ua-Message-In-Proc.
112
If Receive-File-Status Not = "10"
113
Display "Mirror " " Error in Message-In file "
Extended General Device Support (GDSX) Manual—529931-001
D -17
DELETER Listing
Using Pseudo Procedures in a TS/MP Environment
114
" Stat-1 = " Stat-1 " Stat-2 = " Stat-2
Upon Tout.
115
116
Ua-Message-Out Section.
117
Use after Error Procedure on Message-Out.
118
Ua-Message-Out-Proc.
119
If Receive-File-Status Not = "10"
120
Display "Mirror " " Error in Message-Out file "
121
" Stat-1 = " Stat-1 " Stat-2 = " Stat-2
Upon Tout.
122
End Declaratives.
123
124
********************************************************************************
125
*
M A I N - L O G I C
*
126
********************************************************************************
127
128
Main Section.
129
Begin-Cobol-Server.
130
*
Initialization of server
131
Perform A-Init.
132
133
Perform B-Trans until Close-From-Requester.
134
Perform C-Eoj.
135
Stop Run.
136
137
138
A-Init.
139
Open Input Message-In.
140
Open Output Message-Out
Syncdepth 1.
141
Open I-O
TstDat.
142
*
143
B-Trans.
144
*
Initialization
145
*
- of longest message
(In-Message)
146
*
- of longest reply
(Out-Message)
147
Move Space to In-Message, Out-Message.
148
149
*
Read Request from $RECEIVE
150
Read Message-In.
151
*
If not end-of-file of $RECEIVE, go to D-Process-Message
152
If Not Close-From-Requester
153
Perform D-Process-Message.
154
*
155
C-Eoj.
156
Close Message-In,
157
Message-Out,
158
TstDat.
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
D-Process-Message.
Move 1 to I.
Move In-Message
Move Zeroes
to Out-Message.
to Out-Message-Reply-Code.
Move In-Message-Key-1 to Tstdat-Key-1.
Move In-Message-Text to Tstdat-Text.
Move
In-Message-Loop to Ok-Nmbr.
Perform E-Delete Varying I From 1 by 1 Until I > In-Message-Loop.
If I < 9999
Move Ok-Message
to Out-Message-Text.
Write Out-Message.
E-Delete.
Move I
Read Tstdat With Lock.
If File-Error
to Tstdat-Loop.
Extended General Device Support (GDSX) Manual—529931-001
D -18
Using Pseudo Procedures in a TS/MP Environment
GDSX With NonStop TS/MP and TMF Procedures
183
If Not-Found
184
Next Sentence
185
Else
186
Move I
to Ok-Nmbr
187
Move 9999
to I
188
Move File-Stat-N
to Out-Message-Loop
189
Move "Error reading tstdat"
to Out-Message-Text
190
Else
191
Delete Tstdat
192
If File-Error
193
Move I
to Ok-Nmbr
194
Move 9999
to I
195
Move File-Stat-N
to Out-Message-Loop
196
Move "Error deleting tstdat" to Out-Message-Text.
197
*
198
***Eof**************************************************************************
GDSX With NonStop TS/MP and TMF
Procedures
The sample GDSX application described in the first part of this appendix
communicated with a Pathway/iTS application through a SCREEN COBOL program.
Also, the transactions originating from the GDSX application were protected by TMF
only after they entered the TS/MP environment.
In this section, the GDSX application is changed in the following ways:
•
•
The GDSX application (TSCODE and USCODE2) uses the
^SERVERCLASS_SEND_ and ^SERVERCLASS_SEND_INFO_ pseudo
procedures to send its transactions directly to the TS/MP servers WRITERO and
DELETEO. The SCREEN COBOL program SCOBGDSX is no longer necessary.
The user code portion of the GDSX application uses the pseudo TMF procedures
to protect the transactions it sends to the TS/MP application.
See Figure D-2 on page 20 for a picture of this configuration and the flow of
transactions from the terminals to the database. The source code listing of the user
code USAMPLE2 is given at the end of this subsection. The code listings for WRITER
and DELETER remain the same; see the previous subsection for their listings.
Extended General Device Support (GDSX) Manual—529931-001
D -19
Compiling USAMPLE2
Using Pseudo Procedures in a TS/MP Environment
Figure D-2. GDSX Application With NonStop TS/MP and TMF Pseudo
Procedures
$GDS
$PWGDS
TSCODE
NonStop TS/MP
Servers
TERM1
WRITERO
USCODE
TERM2
DELETERO
$SKY.LINZ.TSTDAT
USECODE2
VST028.vsd
The following subsections step you through the process of compiling, binding,
configuring, and starting the GDSX and TS/MP applications.
Compiling USAMPLE2
The first step is compiling the user code USAMPLE2. In the following example, the
commands to compile USAMPLE2 were entered in an OBEY file called COMP2:
CLEAR All
PARAM WORKFILE $CRASH
COMMENT
Assign SSV0 to the volume and subvolume for
COMMENT
the GDSX installation subvolume
ASSIGN SSV0, $SKY.LINZ
ASSIGN ZSPITACL, $SKY.ZSPIDEF.ZSPITACL
ASSIGN ZEMSTACL, $SKY.ZSPIDEF.ZEMSTACL
ASSIGN ZGDXTAL, $SKY.LINZ.ZGDXTAL
ASSIGN COPYTAL, $SYSTEM.SYSTEM.COPYTAL
ASSIGN SSV1, $SKY.ZSPIDEF
ASSIGN SSV2, $SYSTEM.SYSTEM
TAL /IN USAMPLE2, SWAP $CRASH, OUT $S.#USAMPL2, MEM 64,&
NOWAIT, CPU 4/ USCODE2; NOMAP, NOCODE, NOICODE
Extended General Device Support (GDSX) Manual—529931-001
D -20
Using Pseudo Procedures in a TS/MP Environment
Binding
The user code is compiled when this command is entered at the TACL prompt:
> OBEY COMP2
Binding
The second step is binding TSCODE and USCODE2 together into a GDSX object file
named OGDS2. The commands to do this were entered in a file called BIND2:
ADD * FROM $SKY.LINZ.TSCODE
ADD * FROM USCODE2, DELETE
SET DATA 64 PAGES
SET INSPECT ON
SET SAVEABEND ON
SET SUBTYPE 30
BUILD OGDS2 !
CHANGE HIGHPIN ON IN OGDS2
The binding process occurs when a BIND command is entered at the TACL prompt,
specifying the BIND2 file with an IN option:
> BIND /IN BIND2/
Creating the Database
The third step is creating the database file for the TS/MP server:
> FUP PURGE $SKY.LINZ.TSTDAT
> FUP CREATE $SKY.LINZ.TSTDAT, TYPE K, REC 62, KEYLEN 11,
KEYOFF 0, EXT (20,20)
> FUP ALTER $SKY.LINZ.TSTDAT, AUDIT
The FUP ALTER command is necessary to establish the database as a file audited by
TMF.
Starting NonStop TS/MP
The fourth step is configuring and cold starting the TS/MP application. The following
configuration commands are entered in a file named PATHIN:
SET PATHMON BACKUPCPU 1
SET PATHWAY MAXTCPS 2
SET PATHWAY MAXTERMS 10
SET PATHWAY MAXPROGRAMS 0
SET PATHWAY MAXLINKMONS 1
SET PATHWAY MAXEXTERNALTCPS 1
SET PATHWAY MAXSERVERCLASSES 2
SET PATHWAY MAXSERVERPROCESSES 4
SET PATHWAY MAXSTARTUPS 10
SET PATHWAY MAXPATHCOMS 3
SET PATHWAY MAXASSIGNS 5
SET PATHWAY MAXPARAMS 5
START PATHWAY COLD !
Extended General Device Support (GDSX) Manual—529931-001
D -21
Using Pseudo Procedures in a TS/MP Environment
Running the GDSX Application
LOG1 PATHLOG, STATUS
RESET SERVER
SET SERVER
SET SERVER PROGRAM DELETERO
SET SERVER PROCESS $GDS1
SET SERVER PROCESS $GDS2
SET SERVER CPUS (1:0, 0:1)
SET SERVER MAXSERVERS 2
SET SERVER CREATEDELAY 1 SECS
SET SERVER DELETEDELAY 30 MINS
SET SERVER NUMSTATIC 1
SET SERVER SECURITY "N"
SET SERVER TMF ON
SET SERVER (ASSIGN TSTDAT, $SKY.LINZ,TSTDAT, SHARED)
ADD SERVER DELETER
RESET SERVER
SET SERVER
SET SERVER PROGRAM WRITERO
SET SERVER PROCESS $GDS3
SET SERVER PROCESS $GDS4
SET SERVER CPUS (0:1, 1:0)
SET SERVER MAXSERVERS 2
SET SERVER CREATEDELAY 1 SECS
SET SERVER DELETEDELAY 20 MINS
SET SERVER NUMSTATIC 1
SET SERVER SECURITY "N"
SET SERVER TMF ON
SET SERVER (ASSIGN TSTDAT, $SKY.LINZ.TSTDAT, SHARED)
ADD SERVER WRITER
At the TACL prompt the following commands are entered to start the TS/MP
application:
>
>
>
>
FUP PURGEDATA PATHLOG
ASSIGN PATHCTL, \SKY.LINZ.PATHCTL
PATHMON /NAME $PWGDS, NOWAIT, PRI 150, MEM 64, CPU 0/
PATHCOM /IN PATHIN/ $PWGDS
At this point the TS/MP application named $PWGDS is configured and started, but the
GDSX application is not running.
Running the GDSX Application
In this step the GDSX object file is run and given the name $GDSX. The commands to
do this and set some GDSX configuration parameters were entered in the TACL macro
file RUN2:
?TACL MACRO
STOP $GDSX
STOP $GDSX
CLEAR All
PARAM MAXLINES 0
PARAM CONTROLFLAGS 8
Run DEVICE^HANDLER only
Run as high PIN
Extended General Device Support (GDSX) Manual—529931-001
D -22
Configuring and Starting the Terminal Tasks
Using Pseudo Procedures in a TS/MP Environment
PARAM
PARAM
PARAM
PARAM
PARAM
MAXBUFPOOL 50000
TASKSIZE 2048
DEVICEINFO 1
TMF 2
PROCNOWAIT 1
Make pool 10 larger
Increase the task size
Support DEVICEINFO calls from Pathway
Use TMF product in user task
Have ^SERVERCLASS_SEND_ run in
nowait mode
RUN OGDS2 /NAME $GDSX, LIB SCPROCS/
The GDSX application is started when the macro name is entered at the TACL prompt:
> RUN RUN2
Configuring and Starting the Terminal Tasks
The last step is configuring the two tasks for the terminals, TERM1 and TERM2, and
starting them with SCF commands. In the following example, TERM1 and TERM2 are
configured with terminals that have access names of $STAR.#PTY9 and
$STAR.#PTY10.
> SCF
-> ADD SU $GDSX.#TERM1, ACCESSNAME $STAR.#PTY9, DEVICETYPE 6,
DEVICESUBTYPE 4, PHYSRECLEN 80
-> ADD SU $GDSX.#TERM2, ACCESSNAME $STAR.#PTY10,
DEVICETYPE 6, DEVICESUBTYPE 4,
PHYSRECLEN 80
-> START SU $GDSX.#TERM1
-> START SU $GDSX.#TERM2
USAMPLE2 Listing
2.
!
GDSX USCODE
3.
!
Sample program
4.
!
Writing or deleting records in a database using Pathsend and TMF
!
!
!
5.
!******************************************************************************
7
?NOMAP, NOLMAP, NOCODE, SYMBOLS, CPU TNS/II
8.
9. Name Uscode;
10.
11. Block Common^Templates;
12. ?NOLIST, Source
DCCBDECS (ERRORS)
14. ?NOLIST, Source
DCCBDECS (EVENTS)
16. ?NOLIST, Source
DCCBDECS (TCB^LAYOUT)
18. ?NOLIST, Source
DCCBDECS (IOCB^LAYOUT)
20. ?NOLIST, Source
DCCBDECS (FCB^LAYOUT)
22. ?NOLIST, Source
DCCBDECS (RCB^LAYOUT)
24. !===========================================================================
25. !Comment Users may include their own file to modify DCB and LINE Templates.
26. !Comment See file ULHDECS that USAMPLE sources in here
27. ?NOLIST, Source ULHDECSE(Dcb^Template, Line^Template)
30. End Block; ! Common^Templates
31.
32. Block Config^Parms^Templates;
33. ?NOLIST, Source
DCCBDECS (CONFIG^Templates)
35
End Block; ! Config^Parms^Templates
36.
37. ! Global Data
38. !
39. Block Config^Parms^DATA;
Extended General Device Support (GDSX) Manual—529931-001
D -23
USAMPLE2 Listing
Using Pseudo Procedures in a TS/MP Environment
40.
42.
43.
44.
45.
47.
48.
49.
50.
51.
52.
53.
54.
55.
56.
57.
58.
59.
60.
61.
62.
63.
64.
65.
66.
67.
68.
69.
70.
71
75.
77.
79.
80.
81.
82.
83.
?NOLIST, Source
DCCBDECS (CONFIG^DATA)
End Block; ! Config^Parms^DATA
Block Common^Data;
?NOLIST, Source
DCCBDECS (Common^Data)
End Block; ! Common^Data
Block USER^PRIVATE;
Literal TRUE = -1,
FALSE = 0;
-- the following variables are global for this GDSX-Application
Int
.Pm^Name[0:23];
String .Spm^Name
:= @Pm^Name '<<' 1;
Int
Pm^Name^Len;
Int
.Sc^Name^W[0:23];
String .Ssc^Name^W
:= @Sc^Name^W '<<' 1;
Int
Sc^Name^Len^W;
Int
.Sc^Name^D[0:23];
String .Ssc^Name^D
:= @Sc^Name^D '<<' 1;
Int
Sc^Name^Len^D;
Int
Sc^Op^Num
END Block; !USER^PRIVATE
:= -1;
!===========================================================================
! User may include System Procedures here
?NOLIST, Source $System.System.Extdecs0(Debug,Numout,String_Upshift_)
?NOLIST, Source PEXTGDS
!===========================================================================
Proc Device^Handler(Term^File^Num, Internal^Term^No, Term^Type);
!===========================================================================
Int Term^File^Num
,
-- File^Num for this D^H task
Internal^Term^No,
-- Term number for this D^H
task
84.
85.
86.
87.
88.
89.
90.
91.
92.
Term^Type
;
-- Terminal type
Begin
!===========================================================================
! USCODE can declare desired DEVICE^HANDLER Local Variables here
!===========================================================================
Int
.EXT My^Dcb
(Dcb^TEMPLATE);
-- internal tables we might
need
93.
Int
.EXT Rcv^Iocb
(Iocb^TEMPLATE);
94.
Int
.EXT Term^Iocb
(Iocb^TEMPLATE);
95.
Int
.EXT My^Tcb
(Tcb^TEMPLATE);
96.
97.
Int
.EXT Term^Buf
:= 0D;
98.
String .EXT S^Term^Buf
= Term^Buf;
99.
Int
.EXT Rcv^Buf
:= 0D;
100.
String .EXT S^Rcv^Buf
= Rcv^Buf;
101.
Int
.EXT Work^Buf
:= 0D;
102.
String .EXT S^Work^Buf
= Work^Buf;
103.
104.
Int
.EXT Replied^Len
:= 0D;
^SERVER_CLASS_SEND_
105.
Int
.EXT Sc^Op^Num
:= 0D;
106.
Int
.EXT Pathsend^Error := 0D;
107.
108.
Int
Ferr
:= 0;
109.
Int
Filenum
:= 0;
110.
Int
Evt
:= 0;
111
112.
String
.Ascii^Result[0:2];
113.
114.
116.
117.
--"---"---"--- various buffers
--"---"---"---"---"--- variables for
--"---"--- file error
-- file number for ^Listen
-- event
-- ASCII buffer for Numout
!===========================================================================
SubProc Initialize^Device^Handler;
Extended General Device Support (GDSX) Manual—529931-001
D -24
USAMPLE2 Listing
Using Pseudo Procedures in a TS/MP Environment
118.
119.
120.
121.
122.
123.
124.
125.
126.
127.
128.
129.
130.
131.
132.
133.
134.
135.
136.
137.
138.
139.
140.
141.
142.
143.
144.
145.
146.
147.
148.
149.
150.
151.
12;
152.
153.
154.
155.
157.
!===========================================================================
Begin
159.
160.
161.
162.
163.
164.
165.
166
167
168.
169.
170.
171.
172.
173.
174.
175.
176.
177.
178.
179.
180.
181.
182.
183.
184.
185.
186.
187.
188.
189.
190.
191.
!===========================================================================
Int SubProc Check^Buffer;
!
!===========================================================================
! we return the value 0, when we detected an error
! we return the value 1, when the buffer is OK
!===========================================================================
Begin
!
!
reserve all the buffers we need
@RCV^Buf
:= GetExtPool(11,32);
If @RCV^Buf
= 0D Then
Call Debug;
! From Message Pool
@Term^Buf
If @Term^Buf
Call Debug;
:= GetExtPool(11,32);
= 0D Then
! From Message Pool
@Work^Buf
If @Work^Buf
Call Debug;
:= GetExtPool(10,32);
= 0D Then
! From Buffer Pool
reserve all buffers for Serverclass_Send_
@Replied^Len
:= GetExtPool(10,1);
If @Replied^Len
= 0D Then
Call Debug;
@Sc^Op^Num
If @Sc^Op^Num
Call Debug;
! From Buffer Pool
:= GetExtPool(10,1);
= 0D Then
! From Buffer Pool
@Pathsend^Error
:= GetExtPool(10,2);
If @Pathsend^Error = 0D Then
Call Debug;
! From Buffer Pool
Replied^Len
Sc^Op^Num
:=
:=
0;
0;
-- write the first buffer and wait for the first message
Term^Buf ':=' "Enter your text: xnnnkkkkkkkkkkk.... " & Term^Buf[18] for
Call ^WriteReadX(Term^File^Num, Term^Buf, 50, 62);
-- let's Return to the main-loop
Return;
End;
Int S^Error;
S^Error := String_Upshift_ (S^Term^Buf[0]:1,S^Term^Buf[0]:1);
If S^Error
Or
S^Term^Buf[0] <> ["W"] And
S^Term^Buf[0] <> ["D"] Then Begin
Term^Buf ':=' "wrong function code (x) (must be 'd' or 'w')
Term^Buf[22] For 18 Bytes;
Return 0;
End;
If Not $Numeric(S^Term^Buf[1]) Or
Not $Numeric(S^Term^Buf[2]) Or
Not $Numeric(S^Term^Buf[3]) Then Begin
Term^Buf ':=' "loop-counter (nnn) is not numeric
Term^Buf[17] For 28 Bytes;
Return 0;
End;
" &
-- everything is OK
Return 1;
End;
Extended General Device Support (GDSX) Manual—529931-001
D -25
" &
Using Pseudo Procedures in a TS/MP Environment
193.
194.
195.
196.
197.
198.
199.
200.
201.
202.
203.
204.
205.
206.
207.
208.
209.
210.
211.
212.
USAMPLE2 Listing
!===========================================================================
SubProc Call^Pathsend;
!===========================================================================
!
Begin
If PROC^NOWAIT Then Begin
If S^Term^Buf[0] = ["W"] Then Begin
-- we do a nowaited ^SERVERCLASS_SEND_ to the write server
Ferr := ^Serverclass_Send_ (Spm^Name,
Pm^Name^Len,
Ssc^Name^W,
Sc^Name^Len^W,
S^Rcv^Buf,
62,
62,
,
,
1,
Sc^Op^Num);
End
213.
214.
215.
216.
217.
218.
219.
220.
221.
222.
223.
224.
225.
226.
227.
228.
229.
230.
231.
232.
233.
234.
235.
236.
237.
238.
239.
240.
241.
242.
243.
244.
245.
246.
247.
248.
249.
250.
251.
252.
253.
254.
255.
256.
257.
258.
259.
261.
Else Begin
-- we do a nowaited ^SERVERCLASS_SEND_ to the delete server
Ferr := ^Serverclass_Send_ (Spm^Name,
Pm^Name^Len,
Ssc^Name^D,
Sc^Name^Len^D,
S^Rcv^Buf,
62,
62,
,
,
1,
Sc^Op^Num);
End;
If Not Ferr Then Begin
-- wait for the completion of the ^SERVERCLASS_SEND_
Call ^AwaitioX (Sc^Op^Num, @Rcv^Buf, Replied^Len,, -1D);
If <> Then
-- set the error (error handling is done in the calling procedure)
Call ^Fileinfo (Sc^Op^Num, Ferr);
End;
End
Else Begin
If S^Term^Buf[0] = ["W"] Then Begin
-- we do a waited ^SERVERCLASS_SEND_ to the write server
Ferr := ^Serverclass_Send_ (Spm^Name,
Pm^Name^Len,
Ssc^Name^W,
Sc^Name^Len^W,
S^RCV^Buf,
62,
62,
Replied^Len);
End
Else Begin
-- we do a waited ^SERVERCLASS_SEND_ to the delete server
Ferr := ^Serverclass_Send_ (Spm^Name,
Pm^Name^Len,
Ssc^Name^D,
Sc^Name^Len^D,
S^RCV^Buf,
62,
62,
Replied^Len);
End;
End;
End;
265.
266.
267.
268.
!===========================================================================
!
DEVICE^HANDLER Procedure begins here
!===========================================================================
! Find out our own DCB- and TCB-address
Extended General Device Support (GDSX) Manual—529931-001
D -26
Using Pseudo Procedures in a TS/MP Environment
269.
270.
271
272
273.
274.
275.
276.
277.
278.
279.
280.
281.
282.
283.
284.
285.
completed
286.
287.
288.
289.
290.
291.
292.
293.
294.
295.
296.
297.
298.
299.
300.
301.
303.
305.
306.
307.
308.
309.
310.
311.
312.
313.
314.
315.
316.
317.
318.
319.
buffer
320.
322.
323.
324.
325.
326.
327.
328.
329.
330.
331.
332.
333.
334.
335.
336.
337.
338.
339.
340.
341.
342.
USAMPLE2 Listing
@My^Dcb := Dcbtbl[Internal^Term^No];
@My^Tcb := My^Dcb.Tcbaddr;
-- Do the initialization
Call Initialize^Device^Handler;
-- Do the Main-Loop
While 1 Do Begin
-- wait for an event to complete (message from device or stop)
Evt := Wait^Event ((Disp^Ioc + Disp^Stop), -1D);
-- an event occured
Case Evt of Begin
E^Ioc ->
-- from our device
Begin
-- let's get the address of the IOCB for the message just
Filenum := -1;
@Term^Iocb := ^Listen (0, Filenum, 0);
-- get the new address for the new buffer
@Work^Buf := Term^Iocb.BufaddrX;
-- clear the buffer that we send to the Server
RCV^Buf ':=' " " & RCV^Buf for 30;
-- move the buffer that we received from our device
RCV^Buf ':=' 0 & Work^Buf For Term^Iocb.Iocnt Bytes;
If Check^Buffer Then Begin
-- buffer passed our checks
-- start a TMF transaction
Ferr := ^Begintransaction;
If Ferr Then
-- we have an error with ^BEGINTRANSACTION - let's die
Call Debug;
-- send the buffer that we just received to the server
Call Call^PathSend;
If Ferr Then Begin
-- ^SERVERCLASS_SEND_ reported an error
-- let's cancel this transaction
Ferr := ^Aborttransaction;
If Ferr Then
-- we have an error with ^ABORTTRANSACTION - let's die
Call Debug;
-- get more info about the error reported by
-- ^SERVERCLASS_SEND_
Ferr := ^Serverclass_Send_Info_ (Pathsend^Error,
Pathsend^Error[1]);
If Ferr Then
-- we have an error with ^SERVERCLASS_SEND_INFO_
Call Debug;
-- move the error from ^SERVERCLASS_SEND_INFO_ into the
S^Term^Buf ':=' "Serverclass_Send_ error ";
S^Term^Buf ':=' "Serverclass_Send_ error " &
"PE:xxx, FS:xxx " &
S^Term^Buf[38] for 11 Bytes;
Call Numout(Ascii^Result, Pathsend^Error,
10, 3);
S^Term^Buf[27] ':=' Ascii^Result for 3 Bytes;
Call Numout(Ascii^Result, Pathsend^Error[1], 10, 3);
S^Term^Buf[35] ':=' Ascii^Result for 3 Bytes;
-- write the response from the server to our device
Call ^WriteReadX(Term^File^Num, Term^Buf, 50, 62);
End
Else Begin
-- ^SERVERCLASS_SEND_ reported no error
-- let's end this transaction
Ferr := ^Endtransaction;
If Ferr Then
-- we have an error with ^ENDTRANSACTION - let's die
Call Debug;
-- move the buffer that we received from ^SERVERCLASS_SEND_
-- to the Terminal^Buffer
Term^Buf ':=' Rcv^Buf[1] For 60 Bytes;
-- write the response from the server to our device
Extended General Device Support (GDSX) Manual—529931-001
D -27
Using Pseudo Procedures in a TS/MP Environment
343.
344.
345.
346.
347.
348.
349.
350.
351.
352.
353.
354.
355.
356.
357.
358.
359.
360.
361
362.
363.
364.
365.
36
367.
368.
369.
370.
371.
372.
373.
374.
375.
376.
USAMPLE2 Listing
Call ^WriteReadX(Term^File^Num, Term^Buf, 50, 62);
End;
End
Else Begin
-- wuffer did not pass our checks
-- Write the error message and let the user retry
Call ^WriteReadX(Term^File^Num, Term^Buf, 50, 62);
End;
End;
E^Stop ->
Call Stop^Task;
End;
End;
End;
-- task is stopping
-- of Case Evt
-- of While
-- Proc
!===========================================================================
Proc USER^INITIALIZE
!===========================================================================
Proc User^Initialize(Primary);
Int primary;
Begin
-- initialize our
Pm^Name
':='
Pm^Name^Len
:=
Sc^Name^W
':='
Sc^Name^Len^W :=
Sc^Name^D
':='
Sc^Name^Len^D :=
End;
global variables
["$PWGDS"];
6;
["WRITER"];
6;
["DELETER"];
7;
!===========================================================================
!
Other User^Exits
!===========================================================================
378.
379.
380. !===========================================================================
381. Proc LINE^HANDLER (LINE^FILE^NUM, INTERNAL^LINE^NO, IN^QUEUE^FILE^NUM);
382. !===========================================================================
383. Int LINE^FILE^NUM, INTERNAL^LINE^NO, IN^QUEUE^FILE^NUM;
384. Begin
385.
386. End;
387.
388.
389. !===========================================================================
390. Int Proc USER^START (DCBP, OPENID);
391. !===========================================================================
392. Int .EXT DCBP;
!gdsx
393. Int (32) .OPENID;
!gdsx
394.
Begin
! OPENID specified by USER (In this case, pointer to DCB)
395.
! is stored in TCB.OPENID
396.
OPENID := @DCBP;
397.
Return 0;
398.
End;
399.
400.
401. !===========================================================================
402. Proc USER^STOP (TCB);
403. !===========================================================================
404. Int .EXT TCB(TCB^TEMPLATE);
!gdsx
405. Begin
406. End;
407.
408.
409. !===========================================================================
410. Proc PROCESS^ASSIGNS (buf);
411. !===========================================================================
412. Int .buf;
413. Begin
Extended General Device Support (GDSX) Manual—529931-001
D -28
USAMPLE2 Listing
Using Pseudo Procedures in a TS/MP Environment
414.
415.
416.
417.
418.
419.
420.
421.
422.
423.
424.
425.
426.
427.
428.
429.
430.
433
434.
435.
436.
437.
438.
439.
440.
441.
442.
443.
444.
445.
446.
447.
448.
449.
450.
451.
452.
453.
string,
454.
455.
456.
457.
458.
459.
460.
461.
462.
463.
464.
465.
466.
467.
468.
469.
470.
471.
472.
473.
474.
475.
476.
477.
478.
479.
480.
481.
482.
483.
484.
485.
486
487
488.
End;
!===========================================================================
Proc PROCESS^USER^PARAMS (user^param^buf);
!===========================================================================
String .user^param^buf;
Begin
Literal eof = %377;
STRING
xlate^user^parm^name = 'p' := [
!01234567890123
4
56789012345678
9
"USERPARAM1
", 1, "USERPARAM2
", 2,
eof ];
STRING
.s := @user^param^buf
,
item^name [0:13]
;
use index; index := 0;
While xlate^user^parm^name [index] <> eof
Begin
Do
! If within table
item^name ':=' xlate^user^parm^name [index] for s; ! get table name
If item^name = s[1] for s Then ! param name found
Begin
@s := @s[s+1] ;
! point to param value
! assign param value
! set the desired parameter variable to parm value(s[1] FOR s)
goto try^next^param;
End
Else
index := index + 15;
! go to next param
End;
drop index;
@s := @s [s+1];
! name not found -- forget it
try^next^param:
! if multiple user parm messages are in one
! continue to process, otherwise return to TSCODE
! for further processing
Return;
End;
!===========================================================================
Int Proc USER^ATTRIBUTES (sg^cmd, sg^objtype, sg^objname, token^code,
token^value);
!===========================================================================
Int
sg^cmd
sg^objtype
.sg^objname
.token^value
INT(32) token^code
,
,
,
;
;
!
!
!
!
!
SPI command for
object type for
object name for
SPI token value
SPI token code
this request
this request
this request
for this token
Begin
Return 0;
End;
!===========================================================================
Proc USER^BACKUP;
!===========================================================================
Begin
End;
!===========================================================================
Int Proc USER^COMMANDS (iocb, file^error, sg^error) ;
!===========================================================================
Int .EXT iocb (iocb^template), ! routines for processing
.file^error
,
! user's commands, functions, etc.
.sg^error
;
Begin
Extended General Device Support (GDSX) Manual—529931-001
D -29
Using Pseudo Procedures in a TS/MP Environment
USAMPLE2 Listing
489.
490.
SG^ERROR := -1;
! -1 indicates that this command is unknown
491.
Return 0;
492.
493. END ;
494.
495.
496.
497. !===========================================================================
498
Proc user^init^config^params;
499. !===========================================================================
500. Begin
501. End;
502.
503.
504.
505. !===========================================================================
506. Int Proc USER^REPLIES (sg^cmd, sg^objtype, sg^objname, sg^buf);
507. !===========================================================================
508. Int
sg^cmd
,
! SPI command for this request
509.
sg^objtype
,
! object type for this request
510.
sg^objname
,
! object name for this request
511.
.sg^buf
;
! SPI response buffer
512.
513. Begin
514.
Return 0;
515. End ;
516.
517. !===========================================================================
518. Proc User^Takeover;
519. !===========================================================================
520. Begin
521.
522. End;
523.
524.
525. !===========================================================================
526. Int Proc User^Version (version^string);
527. !===========================================================================
528. String .version^string;
529. Begin
530.
531.
version^string ':=' "011493" ; ! Jan. 14 1993 User Version
532.
Return 1;
533.
534. End;
535.
!***EOF*************************************************************************
Extended General Device Support (GDSX) Manual—529931-001
D -30
E
Intertask Communication Example
This appendix contains an example of sending and receiving ITC messages between
two DEVICE^HANDLER tasks. The example code, USAMPLE3, is used for both tasks
and illustrates the use of the following procedures:
GET^ITC^FCB
ITC^OPENX
^LISTEN
NOTIFY^IO^COMPLETIONX
^READUPDATEX
SEND^ITC^MSGX
Examples are given for the various steps required to compile, bind, configure, and start
the GDSX application.
Once the application is running, you can use a utility, such as FUP, to send data to one
of the tasks through $RECEIVE. The following steps list the processing flow and
assume you first send input data to TASK1:
1. TASK1 reads the input data from $RECEIVE.
2. TASK1 displays the input on the terminal it is configured for.
3. TASK1 sends the input data to TASK2 in an ITC message.
4. TASK2 displays the input from the ITC message on the terminal it is configured for.
5. TASK2 notifies TASK1 when it has completed processing the ITC message.
6. TASK1 checks $RECEIVE for more incoming data.
The processing flow is the same if you begin by sending data to TASK2.
Running the Example
USAMPLE3 is included with the GDSX software. Running it as a GDSX application
requires the usual steps of compilation, binding, configuration, and so on. If you want
to run USAMPLE3, you need to do these steps as shown by the following examples.
Substitute your volume and subvolumes names for the names shown in the examples.
Compiling USAMPLE3
The first step is compiling the user code USAMPLE3. The following commands are
entered in an OBEY file called COMP3:
CLEAR All
PARAM WORKFILE $CRASH
COMMENT
Assign SSV0 to the volume and subvolume for
COMMENT
the GDSX installation subvolume
Extended General Device Support (GDSX) Manual—529931-001
E- 1
Binding
Intertask Communication Example
ASSIGN SSV0, $SKY.LINZ
ASSIGN ZSPITACL, $SKY.ZSPIDEF.ZSPITACL
ASSIGN ZEMSTACL, $SKY.ZSPIDEF.ZEMSTACL
ASSIGN ZGDXTAL, $SKY.LINZ.ZGDXTAL
ASSIGN COPYTAL, $SYSTEM.SYSTEM.COPYTAL
ASSIGN SSV1, $SKY.ZSPIDEF
ASSIGN SSV2, $SYSTEM.SYSTEM
TAL /IN USAMPLE3, SWAP $CRASH, OUT $S.#USAMPL3, MEM 64,&
NOWAIT, CPU 4/ USCODE3; NOMAP, NOCODE, NOICODE
The user code is compiled when this command is entered at the TACL prompt:
> OBEY COMP3
Binding
The second step is binding TSCODE and USCODE3 together into a GDSX object file
named OGDS3. The commands are entered in a file called BIND3:
ADD * FROM $SKY.LINZ.TSCODE
ADD * FROM USCODE3, DELETE
SET DATA 64 PAGES
SET INSPECT ON
SET SAVEABEND ON
SET SUBTYPE 30
BUILD OGDS3 !
CHANGE HIGHPIN ON IN OGDS3
The binding process occurs when a BIND command is entered at the TACL prompt,
specifying the BIND3 file with an IN option:
> BIND /IN BIND3/
Running the GDSX Application
In this step the GDSX object file is run and given the name $GDSX. The commands to
do this and set some GDSX configuration parameters are entered in the TACL macro
file named RUN3:
?TACL MACRO
STOP $GDSX
STOP $GDSX
CLEAR All
PARAM MAXLINES 0
PARAM CONTROLFLAGS 9
PARAM MAXBUFPOOL 50000
PARAM TASKSIZE 2048
PARAM MAXITC 2
RUN OGDS3 /NAME $GDSX/
Run DEVICE^HANDLER task only
Run as high PIN and send system
message to USCODE
Make pool 10 larger
Increase the task size
Account for two additional ITC files
The GDSX application is started when the macro name is entered at the TACL prompt:
> RUN RUN3
Extended General Device Support (GDSX) Manual—529931-001
E- 2
Intertask Communication Example
Configuring and Starting the Terminal Tasks
Configuring and Starting the Terminal Tasks
The last step is configuring the two tasks for the terminals, TASK1 and TASK2, and
starting them with the following SCF commands. In the following example, TASK1 and
TASK2 are configured with terminals that have access names of $STAR.#PTY7 and
$STAR.#PTY9.
> SCF
-> ALLOW 100 ERRORS
-> ALLOW 100 WARNINGS
-> TIMEOUT 999999
-> ADD SU $GDSX.#TASK1, ACCESSNAME $STAR.#PTY7,&
DEVICETYPE 6, DEVICESUBTYPE 4, PHYSRECLEN 80
-> ADD SU $GDSX.#TASK2, ACCESSNAME $STAR.#PTY9,&
DEVICETYPE 6, DEVICESUBTYPE 4, PHYSRECLEN 80
-> START SU $GDSX.#TASK1
-> START SU $GDSX.#TASK2
USAMPLE3
2.
!******************************************************************************
3. ! GDSX USCODE Generic DEVICE^HANDLER
!
4. ! Sample program for enhanced ITC messages between two DEVICE^HANDLER
tasks. !
5. !
!
6. ! The ONLY use of this example program is for demonstration purpose.
!
7. !
!
8. ! NO error-handling is done.
!
9. !
_______________
!
10. !
Lispproc ------>|
|
!
11. !
(or FUP, ...)
| *********
|
!
12. !
| * Task1 *
|
!
13. !
| *********
|
!
14. !
-----> | Read $RCV
|
!
15. !
|
|
!
16. !
| Msg on device |-----------------> (Term)
!
17. !
|
|
!
18. !
| Msg to Task2 |----\
!
19. !
|
|
|
!
20. !
<----- | Reply to $RCV |
|
!
21. !
|_______________|
|
!
22. !
|
|
|
!
23. !
| *********
|
|
!
24. !
| * Task2 *
|
|
Extended General Device Support (GDSX) Manual—529931-001
E- 3
USAMPLE3
Intertask Communication Example
!
25.
!
|
*********
|
|
26.
!
| Read ITC msg
| <--/
27.
!
|
|
28.
!
| Msg on device |-----------------> (Term)
29.
!
|
30.
!
| NOTIFY^IO^COMP|
31.
!
|_______________|
32.
!
33.
!
This message exchange works the other way too.
34
!
from $RECEIVE as intertask messages to Task1.
!
!
!
!
|
!
!
!
!
Task2 sends its messages
!
!
51.
!******************************************************************************
53. NAME Uscode;
54. BLOCK COMMON^TEMPLATES;
55. ?NOLIST, SOURCE
DCCBDECS (Events)
57. ?NOLIST, SOURCE
DCCBDECS (ERRORS)
59. ?NOLIST, SOURCE
DCCBDECS (TCB^LAYOUT)
61. ?NOLIST, SOURCE
DCCBDECS (IOCB^LAYOUT)
63. ?NOLIST, SOURCE
DCCBDECS (FCB^LAYOUT)
65. ?NOLIST, SOURCE
DCCBDECS (RCB^LAYOUT)
67. !===========================================================================
68. !Comment Users may include their own file to modify DCB and LINE templates.
69. !Comment See file ULHDECS that USAMPLE sources in here
70. ?NOLIST, SOURCE ULHDECSE(DCB^Template, Line^Template)
73. END BLOCK; ! COMMON^TEMPLATES
74.
75. BLOCK CONFIG^PARMS^TEMPLATES;
76. ?NOLIST, SOURCE
DCCBDECS (CONFIG^TEMPLATES)
78. END BLOCK; ! CONFIG^PARMS^TEMPLATES
79.
80. ! Global Data
81. !
82. BLOCK CONFIG^PARMS^DATA;
83. ?NOLIST, SOURCE
DCCBDECS (CONFIG^DATA)
85. END BLOCK; ! CONFIG^PARMS^DATA
86.
87. BLOCK COMMON^DATA;
88. ?NOLIST, SOURCE
DCCBDECS (COMMON^DATA)
90. END BLOCK; ! COMMON^DATA
91.
92. BLOCK USER^PRIVATE;
93. LITERAL TRUE = -1,
94.
FALSE = 0;
95. END BLOCK; !USER^PRIVATE
96.
97. !===========================================================================
98. !
User may include System Procedures desired here.
99. ?NOLIST, SOURCE $SYSTEM.SYSTEM.EXTDECS0(DEBUG, NUMOUT, NUMIN);
101. !===========================================================================
102. ?NOLIST, SOURCE PEXTGDS
104.
106. !***************************************************************************
107. PROC DEVICE^HANDLER (TERM^FILE^NUM, INTERNAL^TERM^NO, TERM^TYPE);
108.
!****************************************************************************
109. INT TERM^FILE^NUM
,
! file number for this D^H task
110.
INTERNAL^TERM^NO,
! terminal number for this D^H task
111.
TERM^TYPE
;
! terminal type
112.
113. BEGIN
114. !===========================================================================
115. !
USCODE can declare desired DEVICE^HANDLER local variables here
116. !===========================================================================
Extended General Device Support (GDSX) Manual—529931-001
E- 4
USAMPLE3
Intertask Communication Example
117.
118.
119.
120.
121.
122.
123.
124.
125.
126.
127.
128.
129.
130.
131.
132.
133.
134.
135.
136.
137.
138.
139.
140.
141.
143.
144.
145.
146.
147.
148.
149.
150.
151.
152.
153.
154.
155.
156.
157.
158.
159.
160.
161.
162.
163.
164.
165.
166.
167.
168.
169.
170.
171.
172.
174.
175
176.
177.
1D);
178.
179.
180.
181.
182.
183.
184.
185.
186.
187.
188.
189.
task
190.
INT
INT
INT
INT
INT
INT
.EXT
.EXT
.EXT
.EXT
.EXT
.EXT
MY^DCB
MY^TCB
RCV^IOCB
ITC^IOCB
DEV^IOCB
Itc^Fcb
INT
STRING
INT
STRING
.EXT
.EXT
.EXT
.EXT
TERM^BUF
S^TERM^BUF
RCV^BUF
S^RCV^BUF
INT
INT
.EXT Buffptr
.EXT ITC^Buf
(DCB^TEMPLATE);
(TCB^TEMPLATE);
(IOCB^TEMPLATE);
(IOCB^TEMPLATE);
(IOCB^TEMPLATE);
(FCB^TEMPLATE);
:=
=
:=
=
0D;
TERM^BUF;
0D;
RCV^BUF;
:= 0D;
:= 0D;
Int
Error
:= 0;
Int
Term^Buf^Len := 0;
Int(32)
W^Fcbaddr
:= -1D;
Int(32)
W^Dcbaddr
:= 0D;
Int
DOLR^RCV
:= 0;
Int
All^Files
:= -1;
Int
.EXT Fcb^Ptr
:= 0D;
Int
EVT
:= 0;
Int
Rcv^ITC^Fnum := 0;
!=====================================================================
!
DEVICE^HANDLER Procedure MAIN ENTRY POINT begins here
!=====================================================================
-- find out who we are
@MY^DCB := DCBTBL[INTERNAL^TERM^NO];
@MY^TCB := MY^DCB.TCBADDR;
-- reserve all the buffers we need
@RCV^BUF
:= GETEXTPOOL(11,66);
IF @RCV^BUF
= 0D THEN
CALL DEBUG;
! from extended message pool
@Term^BUF
:= GETEXTPOOL(11,66);
IF @Term^BUF
= 0D THEN
CALL DEBUG;
! from extended message pool
@ITC^BUF
:= GETEXTPOOL(11,69);
IF @ITC^BUF
= 0D THEN
CALL DEBUG;
! from extended message pool
-- open an ITC file so we can receive ITC messages
If Error := Itc^OpenX (My^Tcb,Rcv^ITC^Fnum) Then
Rcv^ITC^Fnum := -1;
-- do the initial ^READUPDATE on $RECEIVE
CALL ^READUPDATEX(DOLR^RCV,RCV^BUF,132);
-- do the initial ^READUPDATE on our ITC file
If Rcv^ITC^Fnum > 0 Then
Call ^ReadupdateX(Rcv^ITC^Fnum);
-- do the endless loop
While 1 Do Begin
Evt := Wait^Event ((Disp^Imsg + Disp^IOC + Disp^ITC + Disp^Stop), Case Evt of Begin
-----E^IMSG -> ! from $RECEIVE
-----Begin
-- get the address of the IOCB
@Rcv^Iocb := ^Listen (1,0,0);
@BuffPtr := RCV^Iocb.BufaddrX;
If Rcv^Iocb.Err = 6 Or Buffptr = -32 Then Begin
-- this is a system message or a control message to the
Call ^ReplyX();
Extended General Device Support (GDSX) Manual—529931-001
E- 5
USAMPLE3
Intertask Communication Example
191.
192.
193.
194.
195.
196.
197.
198.
199.
200.
201.
202.
203.
204.
205.
206.
207.
208.
209.
210.
211.
212.
213.
214.
215.
216.
217.
218.
219.
220.
221.
222.
223.
224.
225.
226.
227.
228.
229.
230.
231.
232.
233.
234.
235.
236.
237.
238.
239.
240.
241.
242.
244.
245.
246.
247.
248.
249.
250.
251.
252.
253.
254.
255.
256.
257.
258.
259.
260.
261.
262.
263.
264.
-- read the next message
Call ^ReadupdateX(Dolr^RCV,RCV^Buf,132);
End
Else
-- write the data message to our device
Call ^WriteX(Term^File^Num, Buffptr, RCV^Iocb.Iocnt);
End;
----E^ITC -> ! an intertask message
----Begin
-- get the address of the IOCB
@ITC^Iocb := ^Listen (0,0,1);
@BuffPtr := ITC^Iocb.BufaddrX;
-- write the message to our device
Term^Buf ':=' Buffptr for ITC^IOCB.Iocnt Bytes;
Call ^WriteX(Term^File^Num, Term^Buf, ITC^Iocb.Iocnt);
-- tell our partner task that we are finished
Call Notify^IO^CompletionX(ITC^Iocb);
-- do a ^READUPDATE for the next ITC message
Call ^ReadupdateX(Rcv^ITC^Fnum);
End;
----E^IOC -> ! from our device (terminal)
----Begin
-- get the address of the IOCB
@Dev^Iocb := ^LISTEN (0, All^Files, 0);
@BuffPtr := Dev^Iocb.BufaddrX;
If BuffPtr = ["ITC:"] Then Begin
-- our ITC message has been processed; our partner has
-- called NOTIFY^IO^COMPLETIONX so we reply to
-- $RECEIVE and do another ^READUPDATE
-- because the value of LastrcvIOCB is cleared in
-- SEND^ITC^MSGX, we have to provide the tag
-- as the fourth parameter to do a real reply
-- and to deallocate the IOCB
Call ^REPLYX(,,,Dev^IOCB.MsgTAG);
Call ^READUPDATEX(DOLR^RCV,RCV^BUF,132);
End
Else Begin
-- check for our partner task only the first time
If W^Fcbaddr
= -1D Then Begin
-- find our partner task
If My^Dcb.Name = ["$GDSX.#TASK1"] Then
Term^Buf
':=' "$GDSX.#TASK2"
Else
Term^Buf
':=' "$GDSX.#TASK1";
Term^Buf^Len := 12;
W^Fcbaddr
:= 0D;
W^Dcbaddr
:= 0D;
If Error := Get^ITC^FCB(Term^Buf:Term^Buf^Len,
W^Fcbaddr,
W^Dcbaddr) Then
W^Fcbaddr
:= -1D;
End;
If W^Fcbaddr > 0D Then Begin
-- the message that we wrote on our device completed,
-- so write the message to our partner task
ITC^Buf ':=' "ITC: " & Buffptr For Dev^IOCB.IOCNT Bytes;
@Fcb^Ptr := W^Fcbaddr;
Call Send^ITC^MsgX (Fcb^Ptr,
ITC^Buf,
(Dev^IOCB.IOCNT + 6),
0,
-1D,
1); -- write operation
End;
Extended General Device Support (GDSX) Manual—529931-001
E- 6
USAMPLE3
Intertask Communication Example
265.
266.
267.
268.
269.
270.
271.
272.
273.
274.
275.
276.
End;
Call Deallocateiocb(Dev^Iocb);
End;
----E^STOP ->
----Call Stop^Task;
END;
END;
END;
! task is stopping
! of case Evt
! of while 1
! of proc
The remaining code of USAMPLE3 consists of various procedures such as
PROCESS^USER^PARAMS, PROCESS^ASSIGNS, and USER^VERSION.
These procedures are the same as those used in USAMPLE1. See Appendix D, Using
Pseudo Procedures in a TS/MP Environment.
Extended General Device Support (GDSX) Manual—529931-001
E- 7
Intertask Communication Example
Extended General Device Support (GDSX) Manual—529931-001
E- 8
USAMPLE3
Glossary
active task. An existing task that was started and is now executing, or ready to execute, or
waiting for a resource.
backup task. A system task that processes activities related to fault-tolerant functioning.
This task is created only if GDSX is run as a process pair.
converted. An application that has been modified to use an extended feature of the Dseries operating system. TSCODE assumes that USCODE is converted only if
d^plus^enabled of the CONTROLFLAGS configuration parameter is set to 1. A
converted process may or may not be converted with respect to high PIN use.
C-series service routine. A C-series-compatible service routine that can be called on either
a D-series system or a C-series system.
D^H. See DEVICE^HANDLER.
DCB. Device control block. A DCB is the internal representation of an SU object, used to
manage communication between a DEVICE^HANDLER task and a file.
DEVICE^HANDLER. A USCODE procedure typically used to modify the communication of
each thread between a requester and another file (often a terminal). Running copies of
DEVICE^HANDLER code are called DEVICE^HANDLER tasks. DEVICE^HANDLER
is abbreviated D^H in figures. DEVICE^HANDLER tasks are also called term tasks.
dispatch. To wake up and execute a task.
dynamic SU. An SU object not configured through SCF, but created when an external
process opens a file through GDSX. Contrast with preconfigured SU object.
FCB. File control block. Each file opened within GDSX, with the exception of $RECEIVE, is
assigned an FCB that is used to manage the file.
GDSX. Extended General Device Support. A nonprivileged, multitasking process that is
typically used to handle datastream conversion and data communications-related
functions for a business application.
inactive task. A task that is stopped.
in-queue file. A $RECEIVE-like file used by a LINE^HANDLER task to pick up intertask
messages from DEVICE^HANDLER tasks.
IOCB. Input/output control block. TSCODE allocates an IOCB to manage each outstanding
nowait I/O.
IOP. Input/output process. Generally, a communications subsystem that handles the lower
levels of protocol for I/O.
Extended General Device Support (GDSX) Manual—529931-001
Glossary- 1
ITC
Glossary
ITC. Intertask communication. The intertask communication facility permits
DEVICE^HANDLER tasks to have a device-oriented interface to subdevices on a line
or to communicate with other DEVICE^HANDLER tasks without using the Guardian file
and message system.
ITC file. Intertask communication file. A file created by TSCODE to manage
communication from a DEVICE^HANDLER task to an associated LINE^HANDLER
task. When an SU object is configured under a LINE, TSCODE assigns an ITC file
number to term^file^num so that DEVICE^HANDLER task requests are routed to the
associated LINE^HANDLER task, rather than directly to a device.
kernel. The part of TSCODE that coordinates all components of GDSX. The kernel
includes the monitor and listener tasks, and the backup task if GDSX is running as a
process pair.
LCB. Line control block. The internal representation of a LINE object, used to manage a
LINE^HANDLER task’s communication with a file.
LDCB. Logical device control block. A control block used to manage break ownership of a
device by a task.
LINE. With regard to GDSX, this is an SCF object that is managed by a LINE^HANDLER
task and mapped to a file, usually a physical communications line. Represented
internally by an LCB.
L^H. See LINE^HANDLER.
LINE^HANDLER. A USCODE procedure typically used to implement data communications
protocols and to allow each requester thread to use a shared resource (often a
communications line) without allowing the threads to interfere with each other.
Running copies of LINE^HANDLER code are called LINE^HANDLER tasks.
LINE^HANDLER is abbreviated L^H in figures. LINE^HANDLER tasks are also called
LINE tasks.
listener task. A system task that processes system messages and messages not
supported by other tasks.
migration. In this manual, migration refers to taking an application that runs on a C-series
system and changing it so that it runs on a D-series system.
monitor task. A system task that handles EMS messages, management programming
interfaces, and network management activities.
preconfigured SU. An SU object configured with SCF before a requester sends GDSX an
OPEN for the file associated with the SU. Contrast with dynamic SU.
PROCESS. With regard to GDSX, this SCF object type refers to a GDSX process.
Extended General Device Support (GDSX) Manual—529931-001
Glossary- 2
pseudo procedures
Glossary
pseudo procedures. The TSCODE-supported procedures that have Guardian file system,
TS/MP, Pathway/iTS, and TMF procedure counterparts.
RCB. Receive control block. During the processing of a requester OPEN by TSCODE, an
RCB is assigned to represent the communication session with the requester.
SU. Subdevice. With regard to GDSX, this SCF object type is a logical terminal that is
managed by a DEVICE^HANDLER task and mapped to a physical terminal or a
process. An SU object is represented internally by a DCB.
suspend a task. To transfer control from an executing task to TSCODE’s dispatcher, which
may then execute a different task.
system task. A task generated by TSCODE for its own control functions.
TASK. An SCF object referring to either an SU object or a LINE object within GDSX.
task. An independent job entity running within GDSX to perform a specific function. System
tasks are running instances of TSCODE procedures, and user tasks are running
instances of USCODE procedures.
TCB. Task control block. When a task is started, TSCODE assigns a TCB, which is used to
manage the task.
tick. An interval of time equal to .01 second.
TSCODE. Object code for the part of the GDSX subsystem that is supplied by HP.
TSCODE includes generic routines and services that support the development of a
multithreaded, fault-tolerant front-end process.
unconverted. An application that has not been modified to use any of the extended
features of the D-series operating system. TSCODE assumes that USCODE is
unconverted only if d^plus^enabled of the CONTROLFLAGS parameter is set to 0. An
unconverted GDSX application can only run in a low PIN.
USCODE. Object code for the part of GDSX that is developed by the user to provide device
or access-method specifics such as control operations or data-stream translation.
USCODE is bound with TSCODE to produce an operational GDSX process.
user exits. The USCODE procedures that are called by TSCODE to allow the user to
customize a GDSX process.
user task. A DEVICE^HANDLER task or a LINE^HANDLER task started by TSCODE to
handle a message from a requester application.
Extended General Device Support (GDSX) Manual—529931-001
Glossary- 3
user task
Glossary
Extended General Device Support (GDSX) Manual—529931-001
Glossary- 4
Index
A
Abend errors 3-19/3-21
errors less than 100 3-21
error 220 3-21
error 230 2-28, 2-55, 3-21
error 231 2-28, 2-55, 3-21
information to be gathered for 3-28
message format 3-20
ABORT command, SCF
ABORT LINE 9-23
ABORT SU 9-23
example 4-13, 5-19, 6-6
ABORTTRANSACTION
pseudo procedure 8-7
Access methods
function of, with GDSX 1-4
procedures supported by 1-6
supporting direct access of
devices 1-12
supporting indirect access of
devices 1-12
type of, used with GDSX 1-4
ACCESSNAME attribute, SCF 9-7
ADD command, SCF 2-56, 3-15, 9-7
ADD^TRACE^DATA 2-80, 2-83, 2-88, 8-7
ADD^TRACE^DATA^INT 2-80, 2-83, 2-88,
8-9
ALLOCATEIOCB 8-9
ALLOWOPENS command, SCF 3-15
ALTER command, SCF 3-15, 9-7
AM3270 1-12, 3-4
APPL
generating 4-2
processing summary 4-2
running, with GDSX 4-6/4-13, 6-4/6-7
running, without GDSX 4-2/4-3
APPLS
code listing A-1
compiling 4-2
ASSIGN TACL commands 3-2, 9-5
ASSOCIATIVE
attribute, SCF 8-80, 9-7
configuration parameter 2-51, 8-80
ASSUME command, SCF 4-7
ASYNC TERMPROCESS 1-12, 3-4
AUTOSTOP
attribute, SCF 9-7
configuration parameter 2-51
AUTOSTOP attribute, SCF 2-58
AWAITIOX 8-10, 8-86/8-87
B
Back-end network 1-2
Backup process 2-28/2-36
and DEBUG 2-55
startup 2-10
Backup task 2-28/2-31
overview 2-8
startup 2-10
BACKUPCPU configuration
parameter 2-52
Because 2-17
BEGINTRANSACTION 8-12
BINDER 2-41, 2-45
Bit map procedures 8-2
BIT^MAP 8-12
BIT^RESET 8-13
BIT^SET 8-14
BIT^TEST 8-14, 9-24
BOUNDS^CHECK 8-15
Break ownership 2-52
BREAKENABLED configuration
parameter 2-52, 8-80
Break-handling procedures 8-2
Brother
See Backup process
Bufaddr 8-46
Extended General Device Support (GDSX) Manual—529931-001
Index -1
C
Index
Bufaddrx 5-18, 8-46
Buffer pool 2-24, 8-36
BUFFERTIMEOUT configuration
parameter 2-52, 8-37
C
CANCEL 2-12, 8-15
CANCELREQ 2-12, 8-16
CANCELTIMEOUT 2-12, 8-16
CHANGE^BUFF^OWNERX 8-17
CHECKPOINT 2-32/2-33, 8-18
and task suspension 2-13
and user-defined extended
segment 2-19
used in example program 5-21
checkpoint 8-31, 8-34
Checkpoint buffer 2-60, 8-57
Checkpoint semaphore 8-28/8-30, 8-40
Checkpointing
See Fault tolerance
CHECK^BUFFER^BOUNDS 8-17
CLOSE 2-12, 2-53, 8-19
Coding and testing considerations 2-5/2-7
Common^data data block 2-17
Configuration error messages 3-17/3-19
error message 10002 2-27, 3-18
error message 10011 3-18
error message 10012 2-26, 2-27, 3-18
Configuration parameters 2-46/2-75
dynamic 2-46, 2-49/2-51
externally setting 3-13
setting 2-49/2-51
static 2-46/2-48, 2-49/2-51
Configuring a LINE 3-7
Configuring SUs under a LINE 3-7
Console messages 3-16/3-17
CONTROL 2-12
Control block pools
allocation of 2-16/2-24, 3-17/3-19
displaying sizes of 2-24
CONTROLFLAGS configuration
parameter 2-3, 2-52, 5-2
auto^restart^flag 2-53
control^flags 2-53
control^flags. 2-53
d^map 2-53
d^plus^enabled 2-53
stats^flag 2-53
sysmsgs^flag 2-53
Converting applications 2-3, 2-14, 2-15
CP6100 ADCCP/NRM 1-12, 3-4
CP6100 Bisync Multipoint 3-4
CP6100 BISYNC MULTI-POINT 1-12
CSS ASYNC (6100) 1-12, 3-4
CTRL26 configuration parameter 2-54
C-series to D-series migration 2-14
D
Datastream conversion 1-1, 5-7, 5-12
DCB
allocation 5-16
declared in example program 5-9
described 5-15
extending 2-18, 2-58
global 2-16
pool allocation 2-24, 2-60, 2-69
sourcing in template for 2-18, 2-43
Dcbtbl 2-17, 2-61, 5-16
DCCBDECS 2-41/2-43, 4-4/4-6
code listing C-1
DEALLOCATEIOCB 8-10, 8-19
DEBUGFLAGS configuration
parameter 2-54/2-56, 3-19, 3-24
auto^trace^flag 2-55
backup^debug^flag 2-55
bounds^checking 2-55
debug^error^trap 2-54
debug^fatal^flag 2-56
poolcheck^flag 2-55, 8-31, 8-34, 8-37
uscode^debug^flag 2-55
Extended General Device Support (GDSX) Manual—529931-001
Index -2
E
Index
Debugging procedures 8-2
Declarations
See Design and development, data
declarations
DELAY 2-12, 8-19
DELETE command, SCF 3-15
DELETER listing D-16
DELETE^XITEM 2-38, 8-20
Design and development
calling restrictions 2-11/2-14, 7-2
compiling and binding 2-43/2-45
considerations 2-1/2-2
data declarations 2-16/2-19
configuration parameters 2-19
identifiers 2-19
prerequisites 2-1
space usages and limitations 2-19/2-24
tasks listed -xx, -xxii
DEVICEINFO configuration parameter 2-56
DEVICEINFO2 2-12, 2-56, 8-20
DEVICESUBTYPE attribute, SCF 2-56
DEVICETYPE attribute, SCF 2-56
DEVICE^HANDLER example program
design 5-6/5-7
reading and decoding requests 5-10
request processing 5-12
running 4-6/4-13
running APPL with 4-8/4-12
using INSPECT 5-14/5-18
DEVICE^HANDLER procedure 9-2/9-3
design of, for example
program 5-9/5-14
in example program 7-1
DEVICE^HANDLER task
creation 5-1, 9-2
defined 2-9
run-time environment 5-1/5-5
DOWNCPU system message 2-9
DownCPU task 2-9
DO^CP 8-21
and task suspension 2-13
DYNAMIC configuration parameter 2-57
dynamic^autostop 2-58
dynamic^nowaitdepth 2-58
dynamic^recovery 2-58
dynamic^term. 2-58
Dynamic SU 2-58
Dynamic terminal
See Dynamic SU
D-series system
communicating with other
processes 2-4
converted application 2-3
features 2-3
file name structure 2-5
high PIN process 2-4
low PIN process 2-4
open message format 2-54
service routines 2-4
D^plus^enabled 2-3, 2-53
E
EMS
filters 1-7, 2-79/2-80, 3-16
primary collector 3-16
segment file 1-7
template definitions files 1-7
version required by GDSX 1-9
EMS messages 3-16/3-17, 8-22
destination 2-59
event messages 3-24/3-26, 8-77, 8-82
fault messages 3-26/3-28
saving, at abend 3-29
EMS terminal 3-16/3-17
ENDTRANSACTION 8-22
Envoy 1-12, 3-4
EnvoyACP/XF 1-12, 3-4
Error handling in USCODE 5-11, B-1
Error message 3-16
Extended General Device Support (GDSX) Manual—529931-001
Index -3
F
Index
Example GDSX process,
generating 4-4/4-6
Extaddr 7-23, 8-46
Extended buffer pool 2-24, 2-27, 2-59,
8-30, 8-33
Extended GDS (GDSX) 2-15
coding new applications 2-14
communicating with other
processes 2-4
converting applications 2-3
C-series to D-series 2-14, 2-15
file name structure 2-5
hardware and software
requirements 1-9
high PIN process 2-4, 3-1
low PIN process 2-4
open message format 2-54
service routines 2-4
Extended message pool 2-24, 2-27, 2-65,
8-30, 8-33
Extended segments
for control structures 2-21/2-24
for trace files 2-24, 2-88
user-defined 2-19
Extended segment 1025 2-24
EXTSUSIZE configuration parameter 2-58,
4-6, 9-7
E^CAN event 8-87, 8-89
E^CHANGE event 8-87, 8-90
E^CONTINUE event 8-87, 8-89
E^IMSG event 8-87, 8-89, 8-90
E^IOC event 8-51, 8-87, 8-90
E^ITC event 8-68, 8-87, 8-89
E^RESOURCE event 8-84, 8-87, 8-90
E^STOP event 8-80, 8-87, 8-89
E^TIMEOUT event 8-87, 8-89
F
FAULT 2-71, 3-26, 8-22, 9-23
and task suspension 2-13
Fault tolerance 1-5, 2-28/2-36
CHECKPOINT 8-18
checkpointing global data 2-32
in example program 5-19/5-24
level 0 2-28
level 1 2-29
level 2 2-29
procedures 8-2
processing at initialization 2-29/2-31
restart point 8-18
FCB
acquiring for DEVICE^HANDLER
task 8-34
acquiring for ITC messages 8-43
described 2-91
global 2-17
pool allocation 2-21/2-24
sourcing in template for 2-17
used with SEND^ITC^MSGX 8-68
Fcbtbl 2-17
Figure 1-3
File
close 8-19, 8-24
expand file name 8-28
open 8-26
retrieving information 8-24, 8-25
File information, retrieving 8-15, 8-17
File system errors 2-76/2-78, 8-26
error 012 2-77
error 013 2-77
error 014 2-77
error 017 2-77
error 021 2-71, 2-77
error 030 2-78
error 031 2-78
error 032 2-78
error 060 2-78
error 061 2-78
error 066 2-78, 5-19, 8-80, 8-82
error 099 8-80
error 100 2-78
Extended General Device Support (GDSX) Manual—529931-001
Index -4
G
Index
error 210 2-34, 2-78
File sytem interface with GDSX 1-6
FILEINFO 2-12, 8-25
FILE_CLOSE_ 2-12, 8-24
FILE_GETINFOBYNAME_ 2-12, 8-25
FILE_GETINFO_ 2-12, 8-24
FILE_GETRECEIVEINFO_ 2-12, 8-25
sourcing in template for 2-18
FILE_OPEN_ 2-12, 8-26
FILTGDS 2-79
FNAMEEXPAND 2-12, 8-28
G
GDS Management Programming
Manual -xxiv
GDSE object file 4-6
GDSX
architecture 1-3/1-5
COBOL 85 definitions 1-7
DDL definitions 1-7
environments 1-1/1-2
front end for Pathway/TS 1-3/1-5,
1-10/1-16
generation process 2-40/2-45
hardware and software
requirements 1-9
internals 2-89, 2-97
process name qualification 3-4, 3-6
processing overview 2-10/2-11
purpose of 1-1
running an application 3-1/3-11
running as a server 2-73, 3-10
running as a server in NonStop
mode 3-11
running in NonStop mode 2-69
run-time environment 2-7/2-11, 2-46
TACL definitions 1-7
TAL definitions 1-7
two basic configurations 3-4
with a LINE 3-6/3-8
without a LINE 3-4/3-6
using Pathway pseudo procedures D-1
using TMF pseudo procedures D-1
GETEXTPOOL 8-30
GETEXTPOOLX 8-33/8-34
GETLOCALPOOL 2-52, 8-36
GET^CPSEM 8-28
GET^ITC^FCB 8-34, E-1
GET^TASK^NAME 8-39
GET_PROCESS_HANDLES_CPU_ 8-38
GET_PROCESS_HANDLES_NODE_ 8-39
GET_PROCESS_HANDLE_FROM_NAME
_ 8-38
GIVEBREAK 8-40
GIVE^CPSEM 8-40
Guardian procedures
and checkpointing 2-28, 2-31
calling resident 5-3
restrictions on using 5-3
H
Header of linked list 2-38
High PIN process 2-4, 3-1
I
INFO command, SCF 3-15, 9-20
INIT^SEM 2-39, 8-41
INIT^XLIST 2-38, 8-41, 8-43
INSERT^XITEM 2-38, 8-43
INSPECT
and saved memory image file 3-19,
3-24
and USCODE development 1-9
Installed subvolume files 2-41
Internal error
See Abend errors
Internal^line^no 7-13, 7-22
Internal^term^no 5-10, 5-16
Intertask communication 2-14, 2-96/2-97,
7-2, 8-47
Extended General Device Support (GDSX) Manual—529931-001
Index -5
K
Index
example E-1
LINE^HANDLER perspective 7-3/7-7
procedures 8-3
In^queue^file^num 7-1, 7-10, 7-14
IOCB
allocating 8-9
deallocating 8-16, 8-17, 8-19
described 2-89/2-96, 5-18
global 2-16
maintenance procedures 8-3
pool allocation 2-21/2-24, 2-62
sourcing in template for 2-17
waiting for allocation 2-59
IOCBWAITTIME configuration
parameter 2-59, 8-9
Iocnt 5-18
ITC file 2-62, 2-63, 2-96, 7-1, 7-8, 8-50, 9-3
ITC^OPENX 8-43, E-1
I/O involving $RECEIVE 2-93/2-96, 8-46
I/O not involving $RECEIVE 2-89/2-93,
8-47
I/O operation codes 8-70
I/O procedures, using memory pool buffers
with 2-24
I/O process
See Access methods
K
Kernel
functions 2-7
handling of multithreading by 2-11
L
LCB
allocation 7-22
described 7-21
global 2-16
indexed by internal^line^no 7-13
pool allocation 2-21/2-24, 2-64
sourcing in template for 2-18, 2-43
LDCB
pool allocation 2-21/2-24, 2-63
LINE
configuring, in example program 6-3
Line file number 9-3
Linetbl 2-17, 7-22
Line^file^num 7-1, 7-13
LINE^HANDLER example program
CANCEL^ITC procedure 7-19, 7-23
completion of LINE I/O 7-17
decoding events 7-14
design 7-10/7-13
I/O operations to the LINE file 7-16
processing intertask requests 7-15
running 6-2/6-7
running APPL with 6-4/6-7
transaction flow 7-7/7-9
using INSPECT 7-20/7-24
LINE^HANDLER procedure 9-3/9-4
CANCEL^ITC subprocedure 7-19, 7-23
design of, for example
program 7-13/7-20
developing a 5-14
LINE^IO^CMPLT subprocedure 7-17
main entry 7-14
PROCESS^DH^REQ
subprocedure 7-15
when required 1-12, 2-10
WR^RD^TO^LINE subprocedure 7-16
WT^TO^LINE subprocedure 7-16
LINE^HANDLER task
creation 7-1, 9-3
run-time environment 7-1/7-2
Linked lists 2-38/2-39
List manipulation procedures 8-3
LISTEN 8-45, E-1
in LINE^HANDLER 7-3, 7-6
Listener task 2-8, 2-11
startup 2-10
LISTOPENS command, SCF 3-15
Extended General Device Support (GDSX) Manual—529931-001
Index -6
M
Index
LOADFILT 2-79/2-80
Local buffer pool
See Buffer pool
Local message pool
See Message pool
LOCKREC 2-12, 8-48
LOGSTATUS configuration parameter 2-59
LOOPTIME configuration parameter 2-59
Low PIN process 2-4
M
MAKE_PROCESS_HANDLE_NULL_ 8-48
Manual users
doing design and development -xxii
doing operations tasks -xxiii
doing support tasks -xxiv
doing systems analysis -xxi
profile of -xvii
MAXBUFPOOL configuration
parameter 2-27, 2-59, 8-30
MAXCPSIZE configuration parameter 2-31,
2-60, 8-19
MAXDCBPOOL configuration
parameter 2-60
MAXFCBPOOL configuration
parameter 2-61
MAXFILE configuration parameter 2-62
MAXIOCBPOOL configuration
parameter 2-62
MAXIOCBS configuration parameter 2-63
MAXITC configuration parameter 2-63
MAXLDCBPOOL configuration
parameter 2-63
MAXLINEPOOL configuration
parameter 2-64
MAXLINES configuration parameter 2-64
used with example program 6-2
MAXLINKS configuration parameter 2-65
MAXMSGPOOL configuration
parameter 2-27, 2-65, 8-31
MAXOPENS configuration parameter 2-65
MAXPCBPOOL configuration
parameter 2-66
MAXPROCESSES configuration
parameter 2-66, 8-50
MAXRCBPOOL configuration
parameter 2-67
MAXRCVPOOL configuration
parameter 2-67
MAXTASKS configuration parameter 2-68
MAXTCBPOOL configuration
parameter 2-68
MAXTERMS configuration parameter 2-69
Memory management and calling
restrictions 2-13
Memory pools 2-24/2-28
and calling restrictions 2-13
CHANGE^BUFF^OWNERX 8-17
checkpointing 2-27
displaying sizes of 2-25
GETEXTPOOL 8-30/8-32
GETEXTPOOLX 8-33/8-34
GETLOCALPOOL 8-36/8-37
pool checking 2-28, 2-55
PUTEXTPOOL 8-56
PUTLOCALPOOL 8-56
reclaiming buffers 8-64
used with I/O procedures 2-24
Message pool 2-26, 8-36
Message routing
See Message switching
Message switching 1-2
Monitor task 2-8
startup 2-10
Multithreading
handling of, by kernel 2-11
implementation of 5-2
in LINE^HANDLER 7-3, 7-10
MYTERM 2-12, 8-39, 8-48
N
NAMES command, SCF 3-15
Extended General Device Support (GDSX) Manual—529931-001
Index -7
O
Index
Netmon task 2-9
NEWPROCESS 2-12, 2-66, 8-49
NONSTOP configuration parameter 2-69,
3-11
Nonstop mode 2-52
NonStop TS/MP
communicating directly with 8-71, 8-72,
8-73, 8-74
example of using pseudo
procedures D-19
pseudo procedures 1-16, 8-71, 8-72,
8-73, 8-74
running a GDSX application as a
server 3-10
Noretn 8-22/8-23
NOTIFY^IO^COMPLETIONX 7-7, 8-50,
E-1
NOWAITDEPTH attribute, SCF 9-7
O
OGDS USAMPLE object 2-75
OPEN 2-12, 2-53, 8-51
open 2-77
Open task 2-9, 2-11
Opens, public and private 2-2, 8-26, 8-52
Operations tasks -xx, -xxiii
Optype 5-18
OSI/TS 1-16
P
PARAM TACL commands 3-2, 9-5
Pathway/TS
and GDSX startup with a line 1-13,
3-10
and GDSX startup without a line 1-10,
3-9
and GDSX transaction flow 1-11, 1-14
communicating directly with 1-16
function of GDSX with 1-10
GDSX front end for 1-3/1-5, 1-10/1-16
running an application with
GDSX 3-9/3-11
sending an open message to
GDSX 1-11, 1-14
TCP control 26 2-54
terminals supported by 1-10
PCB pool allocation 2-21/2-24, 2-66
PEXTGDS 2-41, 2-43, 4-4
PHYSRECLEN attribute, SCF 2-56
Pool management procedures 8-3
POOLSIZE configuration parameter 2-26,
2-69, 8-30
PRIMARY command, SCF 3-15
Private extended pool 2-24, 2-26, 2-73,
8-30, 8-33
ProcDel task 2-9
Procedures, calling restrictions for
See Design and development, calling
restrictions
Process handle procedures 8-2
PROCESS^ASSIGNS procedure 2-10, 9-5
PROCESS^USER^PARAMS
procedure 2-10, 9-5/9-7
PROCESS_CREATE_ 2-12, 8-53
PROCESS_HANDLE_IS_NULL_ 8-54
PROCESS_STOP_ 2-12, 8-54
PROCNOWAIT configuration
parameter 2-69
PSEM 2-39, 8-55
Pseudo procedure syntax 8-6
Pseudo procedures 8-4, 8-6/8-93
purpose of 1-9, 2-12, 5-3, 7-2
summary 8-1
Pseudo-$RECEIVE files 2-13, 5-2
PTrace 1-9, 2-80, 2-89
PUTEXTPOOL 8-56
PUTLOCALPOOL 8-56
Q
Q^CPX 8-57
Extended General Device Support (GDSX) Manual—529931-001
Index -8
R
Index
R
RCB
global 2-16
pool allocation 2-21/2-24, 2-67
sourcing in template for 2-18
RCV pool allocation 2-21/2-24, 2-67
Readers
See Manual users
READLOCKX 2-12, 8-61
READUPDATELOCKX 2-12, 8-63
READUPDATEX 2-12, 8-61, E-1
READX 2-12, 8-61
RECEIVEDEPTH configuration
parameter 2-70
RECEIVEINFO 2-12, 8-63
RECEIVESIZE configuration
parameter 2-71
RECLAIMBUFFER 2-73, 8-64
used in example program 5-21
Remote device access 3-6, 3-8
REPLYX 2-12, 8-66
Requester application used with example
programs 4-2
Restart point 8-18, 8-21
RESTARTTIME configuration
parameter 2-53, 2-71
RESUMETRANSACTION 8-67
RUN command to start GDSX 3-2
Running as a server process 3-10
S
SAVEABEND dump 3-19
SCAN^BUF procedure 5-12
SCF
commands for GDSX 3-15
conversational interface 1-7, 3-14
general command syntax 3-14
object names for GDSX 3-15, 8-40,
8-48, 8-75
object types for GDSX 3-15
running 3-4/3-10
See also SCF/SPI
sensitive commands 2-71
trace classes 2-80/2-88
used to set configuration
parameters 2-50
version required by GDSX 1-9
SCF Reference Manual for GDSX -xxiv
SCF/SPI 1-6
and Monitor task 2-8
SCOBGDSX listing D-11
SCREEN COBOL 1-16
SECURITY configuration parameter 2-71
access^group 2-72
remote^change^flag 2-72
sg^security. 2-72
user^group 2-72
SEGMENTID configuration parameter 2-72
Semaphore control procedures 8-4
Semaphores 2-39/2-40, 8-27, 8-41, 8-52
SEND^ITC^MSGX 8-34, 8-68, E-1
SERVER configuration parameter 2-73,
3-11
SERVERCLASS_DIALOG_ABORT_ 8-71
SERVERCLASS_DIALOG_BEGIN_ 8-71
SERVERCLASS_DIALOG_END_ 8-72
SERVERCLASS_DIALOG_SEND_ 8-72
SERVERCLASS_SEND_ 8-73, D-19
SERVERCLASS_SEND_INFO_ 8-74, D-19
Service routines 2-69, 8-1
See also Pseudo procedures
See also Utility procedures
Service routines, D-series 2-4
SETMODE 8-74
SETMODENOWAIT 2-12, 8-74, 8-80
SETMYTERM 2-12, 8-75
SETPARAM 8-76
SETPROMPT command, SCF 4-7
SGDXTMPL 1-7
Shared extended pool 2-24/2-26, 2-69,
8-30, 8-33
Extended General Device Support (GDSX) Manual—529931-001
Index -9
T
Index
SHUTDOWN 8-76
SIGNALINTERRUPT 2-12, 8-16, 8-17,
8-77
SIGNALTIMEOUT 2-12, 8-16, 8-17, 8-77,
8-78
SPI
programmatic control 1-7, 3-14
See also SCF/SPI
sensitive commands 2-71
used to set configuration
parameters 2-50
user-defined commands 9-12
START command, SCF 3-15
START LINE 9-3
STARTED state of task 4-11
STATS command, SCF 3-15, 9-20
STATUS command, SCF 3-15
Status message 3-16
STOP command, SCF 3-15
STOP PROCESS 4-13, 6-7, 8-77, 8-82
STOP SU 4-13, 6-6, 9-23
STOPOPENS command, SCF 3-16
STOP^TASK 8-80, 9-23
and task suspension 2-13
Subsystem Control Facility
See SCF
Subsystem Programmatic Interface
See SPI
Support tasks -xx, -xxiv
Suspending a task
See Task, suspension
SUTYPE attribute, SCF 9-3, 9-7
SU/Line, starting with accessname
NONE 1-15
Sync depth 2-34
System linkage control block 2-65
System Procedure Calls Reference
Manual -xxiv
System task
See Task, system
Systems analysis tasks -xxi, -xxii
T
TAKEBREAK 8-80
Takeover processing 2-34/2-36
Task
associative 2-51
defined 1-5
I/O calls 5-2/5-5
maintenance procedures 8-4
scheduling 7-10
suspension 2-13
system 1-5, 2-8/2-9, 2-68
user 1-5, 2-9/2-10
TASKCPSIZE configuration
parameter 2-73
TASKPOOLSIZE configuration
parameter 2-27, 2-73, 8-30
TASKSIZE configuration parameter 2-74
TCB
described 5-17
global 2-16
pool allocation 2-21/2-24, 2-68
sourcing in template for 2-17
TCBADDR 8-81
Tcbaddr 5-18
Tcbtbl 2-17
TELLGDS 9-13/9-15
TERMINATE 8-82
TERMPROCESS and example
programs 4-1, 6-1
Term^file^num 7-1, 9-2
Term^type 2-2, 5-10, 9-3
The 8-71, 8-72
Then 3-9
This 2-77, 8-74, 8-76, D-1
TMF
ABORTTRANSACTION procedure 8-7
BEGINTRANSACTION procedure 8-12
ENDTRANSACTION procedure 8-22
example of using pseudo
procedures D-19
Extended General Device Support (GDSX) Manual—529931-001
Index -10
U
Index
RESUMETRANSACTION
procedure 8-67
TMF configuration parameter 2-37,
2-74
Trace 2-55, 2-80/2-89
automatically generated
records 2-80/2-83
entry type 2-81/2-85, 8-8
saving, at abend 3-28
turning on the 2-85/2-88
user-coded records 2-83/2-85
TRACE command, SCF 2-80, 2-87, 2-89,
3-16
TRACEB 2-24, 2-86, 2-88, 3-28
TRACEP 2-24, 2-86, 2-88, 3-28
TRACERECSIZE configuration
parameter 2-74, 2-83, 2-88
Trace^control^flags 2-80, 8-8
Trap messages 3-23/3-24
format 3-24
TRAPERROR configuration
parameter 2-75
TSCODE
and converted applications 2-3
and nowait execution of service
routines 2-69
and object file generation 2-41, 4-4
and unconverted applications 2-3
components
external interfaces 1-6/1-7
multithreading functions 1-5
support for service routines 1-8/1-9
support for user exits 1-8
defined 1-1
function of 1-4
Type 1 checkpoint 2-33, 8-18
Type 2 checkpoint 2-33/2-34, 8-18, 8-64
U
UBIND 2-41, 2-43/2-45, 4-4
UBINDE 4-4, 4-6
UBINDHI 2-41, 4-4
UBUILD 2-41, 2-43/2-44, 4-4
editing, to compile example
program 4-4/4-6
ULHDECS 2-40
ULHDECSE 2-40
code listing C-12
used to generate example
program 4-4, 5-9
UNLOCKREC 2-12, 8-82
USAMPLE 2-43
DEVICE^HANDLER 2-103/2-105
explanation of 2-97/2-105
LINE^HANDLER 2-99/2-103
sourcing in DCB and LCB
templates 2-19
USER^STOP 2-98
USAMPLE1 listing D-6
USAMPLE2 listing D-23
USAMPLE3 listing E-3
USCODE
and converted applications 2-3
and unconverted applications 2-3
defined 1-1, 2-43
function of 1-4, 1-5
languages used for 2-40
nowaited service routines 2-69
procedure syntax 8-6
User 2-43
User data segment 2-19/2-21
User exits
described 1-5, 1-8, 9-1
listed 9-1
order in which, are called 2-10, 9-1
syntax 9-2/9-26
User task
See Task, user
USERDATA attribute, SCF 9-7
USERDDL 9-13, 9-18
USERFLAGS configuration parameter 2-75
UserInit task 2-9
Extended General Device Support (GDSX) Manual—529931-001
Index- 11
V
Index
USERPARAM 9-5
USERSTARTSU configuration
parameter 2-75, 9-22
USER^ATTRIBUTES procedure 9-7/9-9
USER^BACKUP procedure 2-31, 9-10/9-11
called by TSCODE 2-11
USER^CLOSE^TRACE^FILE 2-88, 8-83
USER^COMMANDS procedure 9-12/9-18
USER^INITIALIZE procedure 2-10,
9-18/9-19
USER^INIT^CONFIG^PARAMS
procedure 2-10, 2-49, 9-19
and configuration parameters 2-46
USER^OPEN^TRACE^FILE 2-83, 2-86,
8-83
User^private data block 2-17
USER^REPLIES procedure 9-20/9-22
USER^START procedure 2-75, 9-22/9-23
USER^STOP procedure 8-9, 9-23/9-25
in example program 5-19, 7-1, 7-20
USER^TAKEOVER procedure 2-35, 9-25
USER^VERSION procedure 2-10, 9-26
USKELDEC 2-40/2-43
USKELDEC file 2-18
USKELEX 2-43
code listing B-1/B-14
derived from USKEL 4-4
explanation of, for DEVICE^HANDLER
example 5-7/5-14
explanation of, for LINE^HANDLER
example 7-13/7-20
sourcing in DCB and LCB
templates 2-18
used to generate example program 4-4
USKELEXC
code listing B-14/B-28
sourcing in DCB and LCB
templates 2-18
UTACLIB 9-13, 9-15/9-18
Utility procedures 8-1/8-4
bit map procedures 8-2
break-handling procedures 8-2
debugging procedures 8-2
fault-tolerance procedures 8-2
intertask communication
procedures 8-3
IOCB maintenance procedures 8-3
list manipulation procedures 8-3
pool management procedures 8-3
process handle procedures 8-2
semaphore control procedures 8-4
task maintenance procedures 8-4
V
VERSION command, SCF 3-16
VSEM 2-39, 8-84
W
WAITED^IO and WAITED^IOX
and task suspension 2-13
WAITED^IOX 8-85
WAIT^EVENT 8-10, 8-68, 8-78, 8-86, 8-90
and task suspension 2-13
events detected by 7-5
in LINE^HANDLER 7-3, 7-5
WAKE^TASK 8-88, 8-89
Warning message 3-16
WRITER listing D-13
WRITEREADX 2-12, 8-92
WRITEUPDATEUNLOCKX 2-12, 8-93
WRITEUPDATEX 2-12, 8-92
WRITEX 2-12, 8-90
WRITE^ITC^MESSAGEX 8-90
X
X25AM 1-12, 3-4
XLB 2-65
Z
ZCOMTACL 9-13
ZEMSTACL 2-79
Extended General Device Support (GDSX) Manual—529931-001
Index -12
Special Characters
Index
ZGDSTACL 9-13
ZGDXCOB 1-7
ZGDXDDL 1-7
ZGDXSEGF 1-7
ZGDXTACL 1-7, 2-79, 9-13
ZGDXTAL 1-7
ZGDXTMPL 1-7
ZSPITACL 2-79, 9-13
Special Characters
* SCF wildcard 6-4
Extended General Device Support (GDSX) Manual—529931-001
Index -13
Special Characters
Index
Extended General Device Support (GDSX) Manual—529931-001
Index -14