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.
Document History Edition Part Number Product Version Published First Second Third 067742 095805 134303 GDSX D10 GDSX D10 GDSX D44 January 1993 June 1993 July 1997 New editions incorporate any updates issued since the previous edition. A plus sign (+) after a release ID indicates that this manual describes function added to the base release, either by an interim product modification (IPM) or by a new product version on a .99 site update tape (SUT).
New and Changed Information This edition of the Extended General Device Support (GDSX) Manual reflects the following changes for the D44.00 release. Pseudo Context-Sensitive Pathsend Procedures Four pseudo context-sensitive Pathsend procedures were added to allow direct communication between GDSX and Pathway servers: • • • • ^SERVERCLASS_DIALOG_BEGIN_ ^SERVERCLASS_DIALOG_SEND_ ^SERVERCLASS_DIALOG_ABORT_ ^SERVERCLASS_DIALOG_END_ These new procedures are described in Section 8.
New and Changed Information Other Changes to This Edition Tandem’s current and future operating system enhancements that further enable open systems and application portability. • Information pertaining to migration from Basic GDS and GDSX C30 to D10 has been removed as this information is not relevant to the D44.00 release.
Contents New and Changed Information iii About This Manual xix Notation Conventions xxix 1.
2. Design and Development (continued) Contents 2.
2. Design and Development (continued) Contents 2.
2. Design and Development (continued) Contents 2.
3. Operations and Support (continued) Contents 3.
5. DEVICE^HANDLER Example, Design (continued) Contents 5. DEVICE^HANDLER Example, Design (continued) 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-17 The USER^STOP Procedure 5-18 Fault-Tolerance Processing 5-19 Testing Failure at a ^WRITEREAD 5-20 Testing Failure at a ^WRITE 5-23 6.
8. Service Routines (continued) Contents 8.
8. Service Routines (continued) Contents 8.
8. Service Routines (continued) Contents 8.
9. User Exit Descriptions Contents 9. User Exit Descriptions User Exit Routines 9-1 DEVICE^HANDLER 9-1 LINE^HANDLER 9-3 PROCESS^ASSIGNS 9-4 PROCESS^USER^PARAMS 9-5 USER^ATTRIBUTES 9-7 USER^BACKUP 9-9 USER^COMMANDS 9-11 USER^INITIALIZE 9-17 USER^INIT^CONFIG^PARAMS 9-18 USER^REPLIES 9-19 USER^START 9-21 USER^STOP 9-22 USER^TAKEOVER 9-24 USER^VERSION 9-24 A. APPLS Requester Listing APPLS Listing A-1 B. USKELEX and USKELEXC Listings USKELEX Listing B-1 USKELEXC Listing B-14 C.
D. Using Pseudo Procedures in a NonStop TS/MP Environment (continued) Contents D. Using Pseudo Procedures in a NonStop TS/MP Environment (continued) Compiling USAMPLE2 D-19 Binding D-19 Creating the Database D-20 Starting NonStop TS/MP D-20 Running the GDSX Application D-21 Configuring and Starting the Terminal Tasks USAMPLE2 Listing D-22 D-22 E.
Figures (continued) Contents Figures (continued) 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.
Tables (continued) Contents Tables (continued) 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.
Contents Extended General Device Support (GDSX) Manual– 134303 xviii
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 Tandem to support multithreaded, fault-tolerant processing.
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.
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.
How to Use This Manual About This Manual Table i.
Systems Analysis About This Manual Table i.
Design and Development About This Manual 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.
Operations About This Manual 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.
Your Comments Invited About This Manual • • • 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.
Your Comments Invited About This Manual detailed response to your message is sent as soon as possible. Be sure to include your name, company name, address, and phone number in your message. If your comments are specific to a particular manual, also include the part number and title of the manual. Many of the improvements you see in Tandem manuals are a result of suggestions from our customers. Please take this opportunity to help us improve future manuals.
Your Comments Invited About This Manual Extended General Device Support (GDSX) Manual– 134303 xxviii
Notation Conventions General Syntax Notation The following list summarizes the notation conventions for syntax presentation in this manual. UPPERCASE LETTERS. Uppercase letters indicate keywords and reserved words; enter these items exactly as shown. Items not enclosed in brackets are required. For example: MAXATTACH lowercase italic letters. Lowercase italic letters indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name [ ] Brackets.
General Syntax Notation Notation Conventions An ellipsis immediately following a single syntax item indicates that you can repeat that syntax item any number of times. For example: "s-char..." Punctuation. Parentheses, commas, semicolons, and other symbols not previously described must be entered as shown. For example: error := NEXTFILENAME ( file-name ) ; LISTOPENS SU $process-name.
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 Tandem, and the interface of GDSX with Pathway.
GDSX Architecture Overview of GDSX Figure 1-2. Communicating With Back-End Network Business Application GDSX Network IOP Business Application Device Device Device CDT018 GDSX is also used to handle message switching, either from terminal devices or from a back-end network, as shown in Figure 1-3. Figure 1-3.
GDSX Architecture Overview of GDSX Figure 1-4.
TSCODE Components Overview of GDSX 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 for a description of all the user exits. TSCODE Components This subsection describes the functional components provided within TSCODE.
External Interfaces Overview of GDSX 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.
Support for USCODE User Exits Overview of GDSX 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).
Support for Service Routines Overview of GDSX 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.
Hardware and Software Requirements Overview of GDSX transparent to USCODE, providing you with a consistent interface to facilities similar to those of the Tandem NonStop Kernel. 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/TS, or NonStop TM/MP procedure counterparts.
Direct Terminal Access Overview of GDSX • 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/TS supports.
Direct Terminal Access Overview of GDSX = SET TERM FILE $GDS.#T2 = ADD TERM TX-2 TERM TYPE specifies the type of terminal that the GDSX process is simulating for Pathway/TS. 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.
Indirect Terminal Access Overview of GDSX 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/TS 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.
Indirect Terminal Access Overview of GDSX 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 START LINE $GDS.
Starting SU/Line With accessname NONE Overview of GDSX Figure 1-8. GDSX With a LINE^HANDLER $GDS TSCODE D^H Task Requester Requester $RECEIVE Requester D^H Task IN^QUEUE^ FILE^NUM L^H Task LINE^ FILE^ NUM IOP D^H Task CDT022 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.
When to Use GDSX Overview of GDSX See Section 8, “Service Routines,” for more information about these procedures and Section D, “Using Pseudo Procedures in a NonStop 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/TS alone can handle the application requirements.
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
Using D-Series Features Design and Development • ° Pathway/TS 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.
Converted Application Features Design and Development 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.
GDSX D44 Features Supported Design and Development • 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.
Coding and Testing Considerations Design and Development returns file-system error 29 or 560. See Section 8 for descriptions of all these procedures. ° In general, if GDSX is run unconverted, only the GDSX pseudo Guardian, Pathway/TS and NonStop TM/MP 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.
Coding the LINE^HANDLER Design and Development 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-19. Most DEVICE^HANDLER procedures are single-threaded.
Run-Time Environment Design and Development 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.
System Tasks Design and Development 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.
User Tasks Design and Development 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).
Overview of GDSX Processing Design and Development 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.
Calling Restrictions Design and Development 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.
Calling Restrictions Design and Development example, ^AWAITIO[X] indicates that the ^AWAITIO and ^AWAITIOX procedures are available.
Memory Management Design and Development 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 for details.
Steps for Coding New Applications and Conversion Design and Development 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.
Design and Development Conversion for Extended Features of D-Series Systems 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-39.
Data Declarations Design and Development 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 Resource maps SPI definitions Some of these declarations are public to USCODE (user code can source them in at compile time).
User Code Declarations Design and Development used. For globals to be updated, semaphore control may be necessary (see "Semaphore Control" on page 2-38). Global Declarations Typically user code has global data blocks, such as common^data and user^private—see the example listings in Appendix B. (The names common^data and user^private are used throughout this manual, although you can use other names for these data blocks.
Space Usages and Limitations Design and Development 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 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.
User Data Segment Design and Development 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.
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 = 0.
Extended Segment for Control Structures Design and Development Figure 2-2.
Extended Segment for Control Structures Design and Development done for the pools. Equations for these calculations are given in Figure 2-2.
Extended Segments for Trace Files Design and Development 10007 10008 10009 10010 10011 10012 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.
Local Pools Design and Development deallocate space from these pools (for additional information about memory pools, see "Space Usages and Limitations" on page 2-18). 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-42). Caution.
Extended Memory Pools Design and Development 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.
Checkpointing Memory Pool Buffers Design and Development 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-42). The default for MAXBUFPOOL is 32,000 bytes, and the maximum is 7.5 megabytes.
Pool Checking Design and Development 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.
Level 1 Fault Tolerance Design and Development 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.
Fault-Tolerance Processing in GDSX Initialization Design and Development • • 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-9.
Checkpointing Design and Development 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.
Checkpointing Design and Development 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 Design and Development 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.
Takeover Processing Design and Development 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.
Takeover Processing Design and Development 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.
Transaction Management Facility Design and Development 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. Caution.
Using the Pseudo Procedures Design and Development See "GDSX Configuration Parameters" on page 2-42 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.
Example Design and Development 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.
Semaphore Control Design and Development 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.
The GDSX Generation Process Design and Development open the disk file and initialize a semaphore for the file. See the example in the considerations for the ^OPEN procedure in Section 8. The GDSX Generation Process Every runnable GDSX process is a combination of code supplied by Tandem 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.
The User Source File Design and Development Figure 2-3. GDSX Generation Process Installed Subvolume DCCBDECS PEXTGDS ?SOURCE ?SOURCE (Optional) TSCODE ?SOURCE User Source File ULHDECS or USKELDEC TAL USCODE BINDER IN File BIND Runnable GDSX Object 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.
Compiling Design and Development • • • • 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.
Binding Design and Development Binding Next you use the UBIND file to bind TSCODE and USCODE. UBIND contains the following commands: add * from tscode add * from USCODE, delete set data 64 pages set inspect on set saveabend on set subtype 30 build OGDS ! 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.
GDSX Configuration Parameters Design and Development 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 2) External Parameter Name Internal DEFINE Name CONFIG^ PARAMS Name Default Value Range BACKUPCPU brother^cpu^no N.A.
GDSX Configuration Parameters Design and Development Table 2-2. Static Parameters (page 2 of 2) External Parameter Name Internal DEFINE Name CONFIG^ PARAMS Name Default Value Range 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.
GDSX Configuration Parameters Design and Development Table 2-3. Dynamic Parameters (page 2 of 3) External Parameter Name Internal DEFINE Name CONFIG^ PARAMS Name Default Value Range 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.
Setting Configuration Parameters Design and Development Table 2-3. Dynamic Parameters (page 3 of 3) External Parameter Name Internal DEFINE Name CONFIG^ PARAMS Name Default Value Range remote^change^flag sg^security.<13> 0 0–1 access^group sg^security.
Descriptions of Configuration Parameters Design and Development 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-51.
AUTOSTOP Design and Development 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.
BUFFERTIMEOUT Design and Development 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 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” in Section 8.
CTRL26 Design and Development 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.
DEBUGFLAGS Design and Development 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.
DEVICEINFO Design and Development 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.
DEVICEINFO Design and Development The GDSX process name must be specified in one of these formats: $GDSX-process-name $GDSX-process-name.#GDS $GDSX-process-name.#GDS.
DYNAMIC Design and Development 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. DYNAMIC This dynamic parameter is bit encoded and is used to set multiple configuration controls.
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).
MAXBUFPOOL Design and Development 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.
MAXFCBPOOL 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 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.
MAXFILES Design and Development 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.
MAXIOCBS Design and Development 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.
MAXLINEPOOL Design and Development 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.
MAXLINKS Design and Development 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.
MAXPROCESSES 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 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.
MAXRCVPOOL Design and Development 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.
MAXTCBPOOL Design and Development 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.
NONSTOP Design and Development NONSTOP This static parameter permits a GDSX application that is run as a NonStop TS/MP server to also run in NonStop mode. The NONSTOP parameter is only checked if the SERVER configuration parameter is set to 1. See "Running GDSX as a NonStop TS/MP Server" on page 3-10 for more information. Internal DEFINE Name CONFIG^PARAMS Name Default Value Range nonstop^param N.A.
RECEIVEDEPTH Design and Development Therefore, in this case, USCODE should not call ^AWAITIO[X] as would be done for a typical nowaited Guardian procedure call. 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.
RESTARTTIME Design and Development 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 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-49.
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.
TASKPOOLSIZE Design and Development 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-64. TASKPOOLSIZE This static parameter specifies the maximum size of the private extended pool allocated for each user task.
TRACERECSIZE Design and Development 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.
USERSTARTSU Design and Development 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.
Notes on Specific Codes Design and Development fenodata feownership fecpupon fescerror fepathdown fefatpin = = = = = = 187 200 230 233 201 560 , , feownabort , feiopon , , fenetdown ; = 210 , = 231 , = 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.
Notes on Specific Codes Design and Development ^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 Design and Development ^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.
Tracing GDSX Design and Development 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.
Selecting Trace Events Supported by TSCODE Design and Development 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.
Selecting Trace Events Supported by TSCODE Design and Development Table 2-4.
User-Coded Trace Calls Design and Development Table 2-4.
User-Coded Trace Calls Design and Development 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.
Turning On the Trace Facility Design and Development Table 2-5.
Turning On the Trace Facility Design and Development common^data section of DCCBDECS) and auto^trace^flag (see "DEBUGFLAGS" on page 2-51). 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.
Turning On the Trace Facility Design and Development 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.
Modifying the Trace Design and Development Table 2-7.
Examining the Trace Design and Development 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.
I/O for Files Other Than $RECEIVE Design and Development 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.
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.
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.
I/O Involving $RECEIVE Design and Development 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.
I/O Involving $RECEIVE Design and Development 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.
I/O Involving $RECEIVE Design and Development 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.
Intertask Communication Design and Development • 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.
Intertask Communication Design and Development 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,..).
USAMPLE Example Program Design and Development 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.
The LINE^HANDLER Procedure Design and Development 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.
Design and Development The LINE^HANDLER Procedure 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).
The LINE^HANDLER Procedure Design and Development 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.
The LINE^HANDLER Procedure Design and Development 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 LINE^HANDLER Procedure Design and Development 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.
The DEVICE^HANDLER Procedure Design and Development 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.
The DEVICE^HANDLER Procedure Design and Development Device Action Description 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).
Design and Development The DEVICE^HANDLER Procedure Extended General Device Support (GDSX) Manual– 134303 2 -101
Design and Development The DEVICE^HANDLER Procedure Extended General Device Support (GDSX) Manual– 134303 2 -102
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-75.
ASSIGN and PARAM Commands Operations and Support 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.
Running a GDSX Process Operations and Support 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 GDSXprocess-name must follow Guardian naming conventions for processes. The process must be named so that application processes and SCF can open GDSX.
Running SCF and Starting Requesters Operations and Support 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.
Running SCF and Starting Requesters Operations and Support 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.
Running SCF and Starting Requesters Operations and Support 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.
Running SCF and Starting Requesters Operations and Support 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.
Running SCF and Starting Requesters Operations and Support 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.
Running a Pathway/TS Application Operations and Support Running a Pathway/TS Application When starting an application using Pathway/TS (and its parent product, NonStop 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.
Running GDSX as a NonStop TS/MP Server Operations and Support 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.
Space Usages and Limitations Operations and Support 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.
User Data Segment Operations and Support 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.
Setting Configuration Parameters Operations and Support 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-42.) 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.
Command Summary Operations and Support 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).
Command Summary Operations and Support 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.
Interpreting Console and EMS Messages Operations and Support 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.
Startup Configuration Error Messages Operations and Support • ° 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 Operations and Support MAXLINEPOOL MAXPCBPOOL (For more information on these parameters see “GDSX Configuration Parameters” on page 2-42.) 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.
Abend Messages Operations and Support 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.
Abend Messages Operations and Support 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 Messages Operations and Support 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.
Abend Messages Operations and Support Table 3-3. Error 220 Message Breakdown (page 2 of 3) TSCODE Procedure/ Subprocedure Executing Description of Event Causing Error 220 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.
Trap Messages Operations and Support Table 3-3. Error 220 Message Breakdown (page 3 of 3) TSCODE Procedure/ Subprocedure Executing Description of Event Causing Error 220 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.
EMS Event Messages Operations and Support 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.
EMS Event Messages Operations and Support Table 3-5 summarizes the EMS event messages that can be sent to an EMS terminal by a GDSX process. Table 3-5.
Fault Messages Operations and Support 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.) Table lists the number ranges for fault messages. Table 3-6.
If GDSX Abends Operations and Support 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.
If GDSX Abends Operations and Support 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.
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.
DEVICE^HANDLER Example, Running and Managing Compiling the Requester 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.
DEVICE^HANDLER Example, Running and Managing Running Two Requesters 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.
DEVICE^HANDLER Example, Running and Managing Compiling File Description USKELEX User 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.
DEVICE^HANDLER Example, Running and Managing Compiling Figure 4-2. Example Generation Process Installed Subvolume DCCBDECS PEXTGDS ?SOURCE TSCODE ?SOURCE USKELEX Source File ?SOURCE TAL UHLDECSE USCODEE UBINDE IN File BIND Runnable GDSE Object 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.
DEVICE^HANDLER Example, Running and Managing Binding 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.
DEVICE^HANDLER Example, Running and Managing Using SCF 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).
DEVICE^HANDLER Example, Running and Managing Running an Application 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.
DEVICE^HANDLER Example, Running and Managing Running an Application Process Figure 4-3. Initial Message Flow $A1 $GDS IOP/Terminal Initialization; READUPDATE $RECEIVE Initialization; OPEN $GDS.
DEVICE^HANDLER Example, Running and Managing Running an Application Process Figure 4-4. Processing an Input String $A1 $GDS 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.
DEVICE^HANDLER Example, Running and Managing Running a Second Application Process 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.
DEVICE^HANDLER Example, Running and Managing Stopping the First Application and GDSX 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.
DEVICE^HANDLER Example, Running and Managing Stopping the First Application and GDSX 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.
DEVICE^HANDLER Example, Running and Managing Stopping the First Application and GDSX Extended General Device Support (GDSX) Manual– 134303 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.
Task I/O Calls DEVICE^HANDLER Example, Design Figure 5-1. DEVICE^HANDLER Task Run-Time Environment $GDS TSCODE Pseudo$RECEIVE File Requester D^H Task TERM^FILE^NUM $RECEIVE Requester D^H Task Pseudo$RECEIVE File TERM^FILE^NUM Monitor Task Listener Task By means of a typical $RECEIVE file, TSCODE accepts incoming messages addressed to subdevices under GDSX ($GDS.#TC1, for example).
DEVICE^HANDLER Example, Design Task I/O Calls 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).
Task I/O Calls DEVICE^HANDLER Example, Design Figure 5-2. DEVICE^HANDLER Example: Sending a Request to a Terminal GDS (TSCODE and USCODE) Application A WRITEREAD with data is sent to GDSX. IOP/Terminal TSCODE checks $RECEIVE for input and identifies the USCODE D^H task that is to handle the WRITEREAD. TSCODE checks to see whether a ^READUPDATE on the task’s pseudo-$RECEIVE has been issued by the task. (Issuing ^READUPDATE makes it possible to receive incoming messages.) NO YES TSCODE queues request.
Task I/O Calls DEVICE^HANDLER Example, Design not have Guardian file-system counterparts, and are not included here. See Section 8, “Service Routines,” for a description of all TSCODE-supported procedures.
Basic Structure of DEVICE^HANDLER Code DEVICE^HANDLER Example, Design WAITED^IO[X], and WAIT^EVENT need to be considered when an analyst determines when a task will be suspended. 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.
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.
USKELEX Example Code DEVICE^HANDLER Example, Design Example 5-1.
The DEVICE^HANDLER Procedure DEVICE^HANDLER Example, Design Table 5-1.
The DEVICE^HANDLER Procedure DEVICE^HANDLER Example, Design Example 5-2.
DEVICE^HANDLER Example, Design The DEVICE^HANDLER Procedure 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.
DEVICE^HANDLER Example, Design The DEVICE^HANDLER Procedure 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.
DEVICE^HANDLER Example, Design The DEVICE^HANDLER Procedure Example 5-4.
DEVICE^HANDLER Example, Design Inspecting the DEVICE^HANDLER Example under “The USER^STOP Procedure” on page 5-18). 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.
DEVICE^HANDLER Example, Design Device Control Blocks 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.
Device Control Blocks DEVICE^HANDLER Example, Design 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.
DEVICE^HANDLER Example, Design Task Control Blocks 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.
DEVICE^HANDLER Example, Design The USER^STOP Procedure 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).
DEVICE^HANDLER Example, Design Fault-Tolerance Processing 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.
Testing Failure at a ^WRITEREAD DEVICE^HANDLER Example, Design 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 TSCODEsupported checkpointing procedures to send stack images or dynamically allocated memory to the backup process.
DEVICE^HANDLER Example, Design Testing Failure at a ^WRITEREAD 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.
Testing Failure at a ^WRITEREAD DEVICE^HANDLER Example, Design Figure 5-6. Fault Tolerance in the DEVICE^HANDLER Example WHILE (1) DO @RCV^BUF := GETEXTPOOL (... TAKEOVER := FALSE ^READUPDATEX (PSEUDO-$RCV, ... ANALYZE REQUEST TYPE ^CHECKPOINT(2) TAKEOVER TAKEOVER := TRUE NORMAL ^RECLAIMBUFFER (@E^RCV^BUF,10) WT WTRD TRUE TAKEOVER? FALSE ^WTX TERM ^WTRDX TERM ^REPLYX CDT011 If ^CHECKPOINT is called with type equal to 1, only the task’s stack image is checkpointed to the backup.
DEVICE^HANDLER Example, Design Testing Failure at a ^WRITE 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.
DEVICE^HANDLER Example, Design Testing Failure at a ^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.
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.
LINE^HANDLER Example, Running and Managing Running the LINE^HANDLER Example Running the LINE^HANDLER Example This example uses the same APPL and GDSE object files generated in Section 4. Although the LINE^HANDLER was not called in the exercises in Sections 4 and 5, a customized LINE^HANDLER procedure is included in the GDSE object file.
LINE^HANDLER Example, Running and Managing Preconfiguring the LINE and Subdevices 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.
LINE^HANDLER Example, Running and Managing Running an Application Process 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.
LINE^HANDLER Example, Running and Managing Running More Application Processes 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 discusses the functioning of the LINE^HANDLER task in this message flow.
Running More Application Processes LINE^HANDLER Example, Running and Managing 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.
LINE^HANDLER Example, Running and Managing Running More Application Processes 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.
LINE^HANDLER Example, Running and Managing Running More Application Processes Extended General Device Support (GDSX) Manual– 134303 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 LINE^HANDLER Example, Design Figure 7-1. LINE^HANDLER Run-Time Environment $GDS TSCODE D^H Task Requester Requester Requester $RECEIVE D^H Task IN^QUEUE^ FILE^NUM L^H Task LINE^ FILE^ NUM D^H Task Monitor Listener 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.
LINE^HANDLER Example, Design Intertask Communication—LINE^HANDLER Perspective 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.
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. D^H Task L^H Task IOP/Terminal TSCODE identifies which D^H task should handle the request. 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.
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 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.
Intertask Communication—LINE^HANDLER Perspective LINE^HANDLER Example, Design Table 7-1.
Transaction Flow LINE^HANDLER Example, Design 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.
LINE^HANDLER Example, Design Transaction Flow 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.
LINE^HANDLER Example, Design Basic Structure of LINE^HANDLER Code 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. Basic Structure of LINE^HANDLER Code A LINE^HANDLER task starts when TSCODE calls the LINE^HANDLER procedure.
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^IOC E^CAN E^STOP @IOCB := ^LISTEN(... @IOCB := ^LISTEN(...
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.
LINE^HANDLER Example, Design E^STOP 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.
LINE^HANDLER Example, Design LINE^HANDLER Procedure 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.
LINE^HANDLER Procedure LINE^HANDLER Example, Design Example 7-2.
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.
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, .
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.
LINE^HANDLER Procedure LINE^HANDLER Example, Design 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.
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, 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.
LINE^HANDLER Example, Design Line Control Blocks 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.
LINE^HANDLER Example, Design The Task Control Block 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.
LINE^HANDLER Example, Design The IOCB 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).
LINE^HANDLER Example, Design Tracing a ^CANCEL 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.
LINE^HANDLER Example, Design Extended General Device Support (GDSX) Manual– 134303 7- 24 Tracing a ^CANCEL
8 Service Routines To help with the development of USCODE routines, the following service routines are supported by TSCODE: • • Utility procedures Pseudo Guardian, NonStop TS/MP, Pathway/TS, 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/TS, or TMF.
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.
Intertask Communication Service Routines 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.
Task Maintenance Service Routines 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.
Pseudo Procedures Service Routines Table 8-1.
Pseudo Procedure Syntax Service Routines Table 8-1.
^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 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.
ADD^TRACE^DATA Service Routines 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-80.
ADD^TRACE^DATA^INT Service Routines 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-77.
^AWAITIO[X] Service Routines 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.
^BEGINTRANSACTION Service Routines ^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 procedure). 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.
BIT^MAP Service Routines 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-77 for more information.
BIT^RESET Service Routines 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.
BIT^SET Service Routines 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).
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-22 for an example. BOUNDS^CHECK This procedure ensures a buffer is in global or extended memory, not in the swappable stack.
^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“ in this section.
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 .
^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.
^CLOSE Service Routines • 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-57 and “TASKCPSIZE” on page 2-70.) ^CLOSE This procedure closes an open file. ^CLOSE can be called whether USCODE is converted or unconverted. This procedure is a waited operation.
DELETE^[X]ITEM Service Routines 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.
DO^CP Service Routines • 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-67 for more information.
^ENDTRANSACTION Service Routines • 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 the Q^CP[X] procedures. See the description of the USER^BACKUP exit for an example showing how user global checkpointing can be done when a GDSX process pair is initialized.
FAULT Service Routines 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.
^FILE_CLOSE_ Service Routines 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.
^FILE_GETRECEIVEINFO_ Service Routines 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.
^FILE_OPEN_ Service Routines ^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.
^FNAMEEXPAND Service Routines 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 .
GET^CPSEM Service Routines 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.
GET^CPSEM Service Routines 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.
GETEXTPOOL Service Routines 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 Service Routines For more information, see “Memory Pools” in Section 2. 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.
GETEXTPOOL Service Routines 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.
GETEXTPOOLX Service Routines . 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.
GET^ITC^FCB 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.
GET^ITC^FCB Service Routines output fcb-address INT(32):ref is the FCB address of the receiving task. output dcb-address 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.
GETLOCALPOOL Service Routines 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.
Service Routines • • GET_PROCESS_HANDLE_FROM_NAME_ 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.
GET_PROCESS_HANDLES_CPU_ Service Routines 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 input:input name:length 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.
GET^TASK^NAME Service Routines 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.
GIVE^CPSEM Service Routines 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).
INIT^SEM Service Routines 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.
INIT^XLIST Service Routines semaphore INT:ref:3 input (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.
INSERT^[X]ITEM Service Routines 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.
^LISTEN Service Routines 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 input tcb-address INT .EXT:ref is the current TCB address of the user task. See the following example for a way to specify this address. output itc-filenum 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.
^LISTEN Service Routines 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.
^LISTEN Service Routines 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; • 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.
^LISTEN Service Routines 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; • For an intertask message (itc-flag is a nonzero value) the IOCB is as follows: iocb.state 6 = I/O active iocb.
^LOCKREC Service Routines ^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 processhandle ! output INT .
^NEWPROCESS Service Routines 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.
NOTIFY^IO^COMPLETION[X] Service Routines 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.
^OPEN Service Routines 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-12. ^OPEN By calling the ^OPEN procedure, one task can establish a communication path between all user tasks and a file.
^PROCESS_CREATE_ Service Routines • 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]; .
PROCESS_HANDLE_IS_NULL_ Service Routines • • 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.
PROCESS_STOP_ Service Routines 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.
PUTEXTPOOL Service Routines 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). 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.
PUTLOCALPOOL Service Routines input address INT(32):value is the relative extended address of the area to be deallocated. This parameter is passed by value. 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.
Q^CP[X] Service Routines 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. 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.
Q^CP[X] Service Routines 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. 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.
Q^CP[X] Service Routines INT flags,t; INT DISK^NAME [0:11]; INT readcnt := 20, cnt := 0; INT GOTSEM := 0; DISC^NAME ':=' ["$DISK1 SUBVOLA FILEA "]; flags := 1; GOTSEM := PSEM(SEM); ! PREVIOUSLY INITIALIZED ! IN USER^INITIALIZE CALL ^FILE_OPEN ( DISK^NAME, FILE^NUM, flags); IF <> THEN BEGIN . .
^READ[X] Service Routines 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 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.
^READUPDATE[X] 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. ^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].
^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; .
^RECLAIMBUFFER Service Routines 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.
^RECLAIMBUFFER Service Routines 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. input pool-number INT:value is the pool number.
^REPLY[X] Service Routines 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 . .
^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.
SEND^ITC^MSG[X] Service Routines 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] Service Routines created. Then fcb.lhaddr will already be set to the TCB address of the LINE^HANDLER task.
^SERVERCLASS_DIALOG_ABORT_ Service Routines is the operation to perform.
^SERVERCLASS_DIALOG_BEGIN_ Service Routines 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.
^SERVERCLASS_DIALOG_SEND_ Service Routines 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.
^SERVERCLASS_SEND_INFO_ Service Routines 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.
^SETMODE Service Routines 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.
^SETMYTERM Service Routines ^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 ! ! ! input object-name INT:ref:16 is the SCF object name (not the access name).
^SETPARAM Service Routines ^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.
^SIGNALINTERRUPT Service Routines • • 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.
^SIGNALTIMEOUT Service Routines 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 Service Routines 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 DIFFER
STOP^TASK Service Routines 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.
TCBADDR Service Routines 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.
^TERMINATE Service Routines ^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.
USER^OPEN^TRACE^FILE Service Routines 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.
VSEM Service Routines input record-count 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 ADD^TRACE^DATA procedure in this section. 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.
WAITED^IO[X] Service Routines 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 .
WAIT^EVENT Service Routines 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.
WAIT^EVENT Service Routines Table 8-2. Events Detected With WAIT^EVENT Literal Constant Event Description Literal Identifier Completion of I/O other than $RECEIVE and intertask message E^IOC 6 Resource is available E^RESOURCE 7 Device added, deleted, altered, started, or stopped E^CHANGE 8 Associated IOCB X 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.
WAIT^EVENT Service Routines 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.
WAKE^TASK Service Routines 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).
^WRITE[X] Service Routines Literal Constant Associated IOCB E^IOC 6 X Resource is available E^RESOURCE 7 Device added, deleted, altered, started, or stopped E^CHANGE 8 Event Description Literal Identifier Completion of I/O other than $RECEIVE and intertask message 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.
WRITE^ITC^MESSAGE[X] Service Routines 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.
^WRITEREAD[X] Service Routines ! 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.
^WRITEUPDATEUNLOCK[X] Service Routines 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.
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.
DEVICE^HANDLER User Exit Descriptions 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.
LINE^HANDLER User Exit Descriptions 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.
PROCESS^ASSIGNS User Exit Descriptions 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.
PROCESS^USER^PARAMS User Exit Descriptions 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.
PROCESS^USER^PARAMS User Exit Descriptions is a pointer to the first byte of the string that contains the user parameter name and value specified by the USERPARAM command.
USER^ATTRIBUTES User Exit Descriptions 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 User Exit Descriptions 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 input scf-command 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.
USER^BACKUP User Exit Descriptions 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-21. 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.
USER^BACKUP User Exit Descriptions • • • • • Receive control blocks Line control blocks Device control blocks Process control blocks Logical device control blocks See “Fault Tolerance” in Section 2 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.
USER^COMMANDS User Exit Descriptions 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: buf
USER^COMMANDS User Exit Descriptions 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 .
USER^COMMANDS User Exit Descriptions • 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.
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.
USER^COMMANDS User Exit Descriptions Example 9-1.
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%.
USER^INITIALIZE User Exit Descriptions Example 9-1.
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.
USER^REPLIES User Exit Descriptions structures have not been initialized. Consequently, within these exits TSCODEsupported 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.
USER^REPLIES User Exit Descriptions 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 input scf-command 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.
USER^START User Exit Descriptions • 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.
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.
USER^STOP User Exit Descriptions 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.
USER^TAKEOVER User Exit Descriptions . . END; DROP DEV; ! under this current ! L^H task. 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 procedure 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^VERSION 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 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.
USER^VERSION User Exit Descriptions Extended General Device Support (GDSX) Manual– 134303 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.
APPLS Listing APPLS Requester 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.
APPLS Listing 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– 134303 A- 3
APPLS Listing APPLS Requester Listing Extended General Device Support (GDSX) Manual– 134303 A- 4
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 Sections 4 through 7. 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.
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 !==========================================
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].
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.
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^Handle
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, .
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.
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.
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.
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.
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,
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.
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.
USKELEX and USKELEXC Listings USKELEXC Listing FOR d := 1 TO MAXTERMS DO IF BIT^TEST(map.
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.
USKELEXC 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].
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 ^RECLAI
USKELEX and USKELEXC Listings USKELEXC Listing ! APPL DEALS WITH IOP FS ERRORS ! !-------------------------------! CALL ^REPLYX(,,,,FERR); ! CLEAR FLAG ! MY^DCB.
USKELEXC Listing USKELEX and USKELEXC Listings 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,
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, .
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(
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.
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) .
USKELEXC Listing USKELEX and USKELEXC Listings !*************************************************************************** PROC PROCESS^ASSIGNS (buf); INT .
USKELEXC Listing USKELEX and USKELEXC Listings .
USKELEXC Listing USKELEX and USKELEXC Listings ! ! Input: None. ! Output: None.
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.
USKELEX and USKELEXC Listings USKELEXC Listing INT .EXT dcb(dcb^TEMPLATE) ; USE d; FOR d := 1 TO MAXTERMS DO IF BIT^TEST(map.
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 release of GDSX. Be sure to use a SOURCE statement to include them when recompiling GDSX. DCCBDECS Listing ?Section Config^Data Struct .
DCCBDECS Listing DCCBDECS and ULHDECSE Listings 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; , , , , , , , , , , , ,
DCCBDECS Listing DCCBDECS and ULHDECSE Listings 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.
DCCBDECS Listing DCCBDECS and ULHDECSE Listings 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 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.
DCCBDECS Listing DCCBDECS and ULHDECSE Listings ! 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.
DCCBDECS Listing DCCBDECS and ULHDECSE Listings Downcpu^Task^Type Netmon^Task^Type Open^Task^Type Procdel^Task^Type Proccreate^Task^Type Literal Perm^State Assoc^State Nomsg^State Stopped^State = = = = = 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.
DCCBDECS Listing DCCBDECS and ULHDECSE Listings Struct Iocb^info; Begin Unsigned(1) Io^Sysbuf; !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) T
DCCBDECS Listing DCCBDECS and ULHDECSE Listings 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.
DCCBDECS and ULHDECSE Listings DCCBDECS Listing ! 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).
DCCBDECS Listing DCCBDECS and ULHDECSE Listings Int(32) .EXT Dcbtbl, .
DCCBDECS Listing DCCBDECS and ULHDECSE Listings ?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 ! ! ! = = = = = = = = = = = =
ULHDECSE Listing DCCBDECS and ULHDECSE Listings FEScUnknownServerClass = 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 FEScL
ULHDECSE Listing DCCBDECS and ULHDECSE Listings ! For each line managed by USCODE, there is an entry in the LINETBL ! ! with the following format.
DCCBDECS and ULHDECSE Listings Extended General Device Support (GDSX) Manual– 134303 C -14 ULHDECSE Listing
D Using Pseudo Procedures in a NonStop TS/MP Environment This appendix contains an example of converting a GDSX application that communicates with a NonStop TS/MP server through a Pathway/TS SCREEN COBOL program and an example of a GDSX application that communicates directly with the server. The converted program also uses the TMF component of NonStop TM/MP to protect transactions originating in the user code portion of GDSX.
Using Pseudo Procedures in a NonStop TS/MP Environment Compiling USAMPLE1 Figure D-1. GDSX Application Without Pathway/TS and TMF Pseudo Procedures $GDSX TSCODE $PWGDS Pathway/TS TCP NonStop TS/MP SERVERS TERM1 SCOBGDSX WRITERO USCODE TERM2 USCODE1 DELETERO $SKY.LINZ.TSTDAT The following subsections step you through the process of compiling, binding, configuring, and starting the GDSX and Pathway/TS applications. Compiling USAMPLE1 The first step is compiling the user code USAMPLE1.
Using Pseudo Procedures in a NonStop TS/MP Environment Creating the Database 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 NonStop TS/MP server: > FUP PURGE $SKY.LINZ.TSTDAT > FUP CREATE $SKY.LINZ.
Using Pseudo Procedures in a NonStop TS/MP Environment SET SET SET ADD TCP TCP TCP TCP Starting NonStop TS/MP PROCESS $GDST INSPECT ON TCLPROG POBJ 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.
Using Pseudo Procedures in a NonStop TS/MP Environment Running the GDSX Application At the TACL prompt the following commands are entered to start the NonStop TS/MP and Pathway/TS 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.
Using Pseudo Procedures in a NonStop TS/MP Environment USAMPLE1 Listing ! 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.
Using Pseudo Procedures in a NonStop TS/MP Environment 93. 94. Int Evt USAMPLE1 Listing := 0; 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.
Using Pseudo Procedures in a NonStop TS/MP Environment 166. 167. 168. 169. 170. 171. 172. 173. 174. 175. 176. 177. 178. 179. 180. 181. USAMPLE1 Listing 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; 185.
Using Pseudo Procedures in a NonStop TS/MP Environment 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. 292. 293. 294. 295. 296. 297. 298. 299. 300. 301. 302. 303. 304. 305. 306. 307. 308. 309. 310. 313. 314. 315.
Using Pseudo Procedures in a NonStop TS/MP Environment 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. 363. 364. 365. 366. 367. 368. 369. 370. 371. 372. 373. 374. 375. 376. 377. 378. 379. 380. 381. 382. 383. 384.
Using Pseudo Procedures in a NonStop TS/MP Environment SCOBGDSX Listing 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.
Using Pseudo Procedures in a NonStop TS/MP Environment 31 32 33 34 35 36 37 38 05 Ws-Rcvd-Key1 05 Ws-Rcvd-Text SCOBGDSX Listing Pic Pic X(08). X(50). * 01 Flags. 02 Ws-Exit-Flag 88 Exit-Program 02 Serv-Ok Pic 9(01) Value 0. Value 1. Pic X(03). 40 ****************************************************************************** 41 Message Section. 42 ****************************************************************************** 43 01 Send-Msg.
Using Pseudo Procedures in a NonStop TS/MP Environment WRITER Listing 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.
Using Pseudo Procedures in a NonStop TS/MP Environment 49 50 51 52 53 54 55 56 57 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 WRITER Listing Pic 9(04) Comp. Pic X(01). Pic 9(03). Pic X(08). Pic X(50). 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).
Using Pseudo Procedures in a NonStop TS/MP Environment 121 Upon Tout. 122 WRITER Listing " Stat-1 = " Stat-1 " Stat-2 = " Stat-2 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.
Using Pseudo Procedures in a NonStop TS/MP Environment DELETER Listing 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.
Using Pseudo Procedures in a NonStop TS/MP Environment DELETER Listing 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.
Using Pseudo Procedures in a NonStop TS/MP Environment 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 DELETER Listing Perform A-Init. Perform B-Trans until Close-From-Requester. Perform C-Eoj. Stop Run. A-Init. Open Input Message-In. Open Output Message-Out Open I-O TstDat. Syncdepth 1. * * * * * * B-Trans. Initialization - of longest message (In-Message) - of longest reply (Out-Message) Move Space to In-Message, Out-Message.
Using Pseudo Procedures in a NonStop TS/MP Environment GDSX With NonStop TS/MP and TMF Procedures GDSX With NonStop TS/MP and TMF Procedures The sample GDSX application described in the first part of this appendix communicated with a Pathway/TS application through a SCREEN COBOL program. Also, the transactions originating from the GDSX application were protected by TMF only after they entered the NonStop TS/MP environment.
Using Pseudo Procedures in a NonStop TS/MP Environment Binding 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.
Using Pseudo Procedures in a NonStop TS/MP Environment Starting NonStop TS/MP 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 ! 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 CREA
Using Pseudo Procedures in a NonStop TS/MP Environment Running the GDSX Application Running the GDSX Application In this step the GDSX object file is run and given the name $GDSX.
Using Pseudo Procedures in a NonStop TS/MP Environment 20. 22. 24. 25. 26. 27. 30. 31. 32. 33. 35 36. 37. 38. 39. 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. USAMPLE2 Listing ?NOLIST, Source DCCBDECS (FCB^LAYOUT) ?NOLIST, Source DCCBDECS (RCB^LAYOUT) !=========================================================================== !Comment Users may include their own file to modify DCB and LINE Templates.
Using Pseudo Procedures in a NonStop TS/MP Environment 104. Int .EXT Replied^Len := ^SERVER_CLASS_SEND_ 105. Int .EXT Sc^Op^Num := 106. Int .EXT Pathsend^Error := 107. 108. Int Ferr := 109. Int Filenum := 110. Int Evt := 111 112. String .Ascii^Result[0:2]; 113. 114. USAMPLE2 Listing 0D; -- variables for 0D; 0D; 0; 0; 0; --"---"--- file error -- file number for ^Listen -- event -- ASCII buffer for Numout 116. 117. 118. 119. 120. 121. 122. 123. 124. 125. 126. 127. 128. 129. 130. 131. 132. 133. 134. 135.
Using Pseudo Procedures in a NonStop TS/MP Environment 177. 178. 179. 180. 181. 182. 183. 184. 185. 186. 187. 188. 189. 190. 191. 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. 243. 244. 245. 246. 247. 248. 249. 250.
Using Pseudo Procedures in a NonStop TS/MP Environment 251. 252. 253. 254. 255. 256. 257. 258. 259. 261. USAMPLE2 Listing Pm^Name^Len, Ssc^Name^D, Sc^Name^Len^D, S^RCV^Buf, 62, 62, Replied^Len); End; End; End; 265. !=========================================================================== 266. ! DEVICE^HANDLER Procedure begins here 267. !=========================================================================== 268. ! Find out our own DCB- and TCB-address 269. @My^Dcb := Dcbtbl[Internal^Term^No]; 270.
Using Pseudo Procedures in a NonStop TS/MP Environment 328. 329. 330. 331. 332. 333. 334. 335. 336. 337. 338. 339. 340. 341. 342. 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.
Using Pseudo Procedures in a NonStop TS/MP Environment 400. 401. 402. 403. 404. !gdsx 405. 406. 407. 408. 409. 410. 411. 412. 413. 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.
Using Pseudo Procedures in a NonStop TS/MP Environment USAMPLE2 Listing 474. !=========================================================================== 475. Proc USER^BACKUP; 476. !=========================================================================== 477. Begin 478. End; 479. 480. 481. !=========================================================================== 482. Int Proc USER^COMMANDS (iocb, file^error, sg^error) ; 483.
Using Pseudo Procedures in a NonStop TS/MP Environment Extended General Device Support (GDSX) Manual– 134303 D -30 USAMPLE2 Listing
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.
Binding Intertask Communication Example 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.
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.
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.
USAMPLE3 Intertask Communication Example 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. 191. INT INT INT INT INT INT .EXT .EXT .EXT .EXT .EXT .
USAMPLE3 Intertask Communication Example 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. 265.
USAMPLE3 Intertask Communication Example 266. 267. 268. 269. 270. 271. 272. 273. 274. 275. 276. 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.
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 D-series operating system. TSCODE assumes that USCODE is converted only if d^plus^enabled of the CONTROLFLAGS configuration parameter is set to 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.
pseudo procedures Glossary pseudo procedures. The TSCODE-supported procedures that have Guardian file system, NonStop TS/MP, Pathway/TS, and TMF (part of NonStop TM/MP) 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.
user task Glossary Extended General Device Support (GDSX) Manual– 134303 Glossary -4
Index A Abend errors 3-19/3-21 errors less than 100 3-20 error 220 3-20 error 230 2-27, 2-52, 3-21 error 231 2-27, 2-52, 3-21 information to be gathered for 3-27 message format 3-19 ABORT command, SCF ABORT LINE 9-22 ABORT SU 9-22 example 4-12, 5-20, 6-6 ABORTTRANSACTION 2-35 pseudo procedure 8-6 Access methods function of, with GDSX 1-3 procedures supported by 1-5 supporting direct access of devices 1-11 supporting indirect access of devices 1-11 type of, used with GDSX 1-3 ACCESSNAME attribute, SCF 9-7 AD
C Index Brother See Backup process Bufaddr 8-44 Bufaddrx 5-19, 8-44 Buffer pool 2-23, 8-35 BUFFERTIMEOUT configuration parameter 2-49, 8-36 C CANCEL 2-11, 8-15 CANCELREQ 2-11, 8-15 CANCELTIMEOUT 2-11, 8-16 CHANGE^BUFF^OWNERX 8-16 CHECKPOINT 2-31/2-32, 8-17 and task suspension 2-12 and user-defined extended segment 2-19 used in example program 5-22 checkpoint 8-30, 8-33 Checkpoint buffer 2-56, 8-55 Checkpoint semaphore 8-27/8-29, 8-39 Checkpointing See Fault tolerance CHECK^BUFFER^BOUNDS 8-17 CLOSE 2-11,
E Index DEBUGFLAGS configuration parameter (continued) debug^error^trap 2-51 debug^fatal^flag 2-52 poolcheck^flag 2-52, 8-31, 8-33, 8-36 uscode^debug^flag 2-52 Debugging procedures 8-2 Declarations See Design and development, data declarations DELAY 2-11, 8-19 DELETE command, SCF 3-15 DELETER listing D-15 DELETE^XITEM 2-36, 8-19 Design and development calling restrictions 2-11/2-14, 7-2 compiling and binding 2-41/2-42 considerations 2-1/2-2 data declarations 2-16/2-18 configuration parameters 2-18 identif
F Index EMS messages (continued) saving, at abend 3-28 EMS terminal 3-16/3-17 ENDTRANSACTION 2-35, 8-21 Envoy 1-11, 3-4 EnvoyACP/XF 1-11, 3-4 Error handling in USCODE 5-12, B-1 Error message 3-16 Example GDSX process, generating 4-3/4-6 Extaddr 7-22, 8-44 Extended buffer pool 2-23, 2-26, 2-56, 8-29, 8-32 Extended GDS (GDSX) 2-15 coding new applications 2-14 communicating with other processes 2-4 converting applications 2-2 C-series to D-series 2-14, 2-15 file name structure 2-5 hardware and software requi
G Index error 021 2-67, 2-73 error 030 2-74 error 031 2-74 error 032 2-74 error 060 2-74 error 061 2-74 error 066 2-74, 5-20, 8-77, 8-79 error 099 8-77 error 100 2-74 error 210 2-33, 2-74 File sytem interface with GDSX 1-5 FILEINFO 2-11, 8-25 FILE_CLOSE_ 2-11, 8-23 FILE_GETINFOBYNAME_ 2-11, 8-24 FILE_GETINFO_ 2-11, 8-23 FILE_GETRECEIVEINFO_ 2-11, 8-24 sourcing in template for 2-17 FILE_OPEN_ 2-11, 8-25 FILTGDS 2-75 FNAMEEXPAND 2-11, 8-27 G GDS Management Programming Manual xxiv GDSE object file 4-6 GDSX
K Index INSPECT and saved memory image file 3-19, 3-23 and USCODE development 1-8 Installed subvolume files 2-39 Internal error See Abend errors Internal^line^no 7-12, 7-21 Internal^term^no 5-11, 5-16 Intertask communication 2-13, 2-92/2-94, 7-2, 8-46 example E-1 LINE^HANDLER perspective 7-3/7-6 procedures 8-3 In^queue^file^num 7-1, 7-9, 7-13 IOCB allocating 8-9 deallocating 8-16, 8-19 described 2-86/2-92, 5-19 global 2-16 maintenance procedures 8-3 pool allocation 2-20/2-23, 2-59 sourcing in template for
M Index when required 1-11, 2-9 WR^RD^TO^LINE subprocedure 7-15 WT^TO^LINE subprocedure 7-15 LINE^HANDLER task creation 7-1, 9-3 run-time environment 7-1/7-2 Linked lists 2-36/2-37 List manipulation procedures 8-3 LISTEN 8-43, E-1 in LINE^HANDLER 7-3, 7-6 Listener task 2-8, 2-11 startup 2-10 LISTOPENS command, SCF 3-15 LOADFILT 2-75/2-76 Local buffer pool See Buffer pool Local message pool See Message pool LOCKREC 2-11, 8-46 LOGSTATUS configuration parameter 2-55 LOOPTIME configuration parameter 2-56 Low
N Index reclaiming buffers 8-61 used with I/O procedures 2-23 Message pool 2-24, 8-35 Message routing See Message switching Message switching 1-2 Monitor task 2-7 startup 2-10 Multithreading handling of, by kernel 2-10 implementation of 5-2 in LINE^HANDLER 7-3, 7-9 MYTERM 2-11, 8-38, 8-47 N NAMES command, SCF 3-15 Netmon task 2-8 NEWPROCESS 2-11, 2-63, 8-48 NONSTOP configuration parameter 2-65, 3-11 NonStop mode 2-48 NonStop TS/MP communicating directly with 8-68, 8-69, 8-70, 8-71 example of using pseudo
Q Index PROCESS_HANDLE_IS_NULL_ 8-52 PROCESS_STOP_ 2-11, 8-52 PROCNOWAIT configuration parameter 2-66 PSEM 2-38, 8-53 Pseudo procedure syntax 8-6 Pseudo procedures 8-4, 8-6/8-89 purpose of 1-8, 2-11, 5-3, 7-2 summary 8-1 Pseudo-$RECEIVE files 2-13, 5-2 PTrace 1-8, 2-76, 2-85 PUTEXTPOOL 8-54 PUTLOCALPOOL 8-55 Q Q^CPX 8-55 R RCB global 2-16 pool allocation 2-20/2-23, 2-63 sourcing in template for 2-17 RCV pool allocation 2-20/2-23, 2-64 Readers See Manual users READLOCKX 2-11, 8-59 READUPDATELOCKX 2-11, 8
T Index SERVER configuration parameter 2-69, 3-11 SERVERCLASS_DIALOG_ABORT_ 8-68 SERVERCLASS_DIALOG_BEGIN_ 8-68 SERVERCLASS_DIALOG_END_ 8-69 SERVERCLASS_DIALOG_SEND_ 8-69 SERVERCLASS_SEND_ 8-70, D-18 SERVERCLASS_SEND_INFO_ 8-71, D-18 Service routines 2-66, 8-1 See also Pseudo procedures See also Utility procedures Service routines, D-series 2-4 SETMODE 8-71 SETMODENOWAIT 2-11, 8-71, 8-77 SETMYTERM 2-11, 8-72 SETPARAM 8-73 SETPROMPT command, SCF 4-7 SGDXTMPL 1-6 Shared extended pool 2-23/2-25, 2-66, 8-29,
U Index global 2-16 pool allocation 2-20/2-23, 2-64, 2-65 sourcing in template for 2-17 TCBADDR 8-78 Tcbaddr 5-19 Tcbtbl 2-16 TELLGDS 9-13/9-14 TERMINATE 8-79 TERMPROCESS and example programs 4-1, 6-1 Term^file^num 7-1, 9-2 Term^type 2-2, 5-11, 9-2 The 8-68, 8-69 Then 3-9 This 2-73, 8-71, 8-73 TMF ABORTTRANSACTION procedure 8-6 BEGINTRANSACTION procedure 8-11 ENDTRANSACTION procedure 8-21 example of using pseudo procedures D-18 RESUMETRANSACTION procedure 8-64 TMF configuration parameter 2-35, 2-70 using
U Index sourcing in DCB and LCB templates 2-18 USER^STOP 2-94 USAMPLE1 listing D-6 USAMPLE2 listing D-22 USAMPLE3 listing E-3 USCODE and converted applications 2-2 and unconverted applications 2-2 defined 1-1, 2-41 function of 1-3, 1-4 languages used for 2-39 nowaited service routines 2-66 procedure syntax 8-6 User 2-41 User data segment 2-18/2-20 User exits described 1-4, 1-7, 9-1 listed 9-1 order in which, are called 2-9, 9-1 syntax 9-1/9-24 User task See Task, user USERDATA attribute, SCF 9-7 USERDDL 9
V Index V Special Character VERSION command, SCF 3-15 VSEM 2-38, 8-81 * SCF wildcard 6-3 W WAITED^IO and WAITED^IOX and task suspension 2-12 WAITED^IOX 8-81 WAIT^EVENT 8-10, 8-65, 8-75, 8-82, 8-87 and task suspension 2-12 events detected by 7-5 in LINE^HANDLER 7-3, 7-5 WAKE^TASK 8-84, 8-85 Warning message 3-16 WRITER listing D-13 WRITEREADX 2-11, 8-88 WRITEUPDATEUNLOCKX 2-11, 8-89 WRITEUPDATEX 2-11, 8-88 WRITEX 2-11, 8-86 WRITE^ITC^MESSAGEX 8-86 X X25AM 1-11, 3-4 XLB 2-61 Z ZCOMTACL 9-13 ZEMSTACL 2-
Special Character Index Extended General Device Support (GDSX) Manual– 134303 Index -14
