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 Part Number Product Version Published 067742 GDSX D10 January 1993 095805 GDSX D10 June 1993 134303 GDSX D44 July 1997 529931-001 GDSX D44 March 2005
Extended General Device Support (GDSX) Manual Glossary Index What’s New in This Manual xv Manual Information xv New and Changed Information Examples Figures xv About This Manual xvii Audience xvii What’s in This Manual xviii How to Use This Manual xix Related Manuals xxiv Notation Conventions xxv 1.
Contents 2.
2.
2.
3. Operations and Support Contents The LINE^HANDLER Procedure 2-99 The DEVICE^HANDLER Procedure 2-104 3.
5. DEVICE^HANDLER Example, Design Contents Running a Second Application Process 4-11 Stopping the First Application and GDSX 4-13 5.
8. Service Routines Contents Tracing a ^CANCEL 7-23 8.
8.
8.
9. User Exit Descriptions Contents ^WRITEUPDATEUNLOCK[X] 8-93 9. User Exit Descriptions User Exit Routines 9-1 DEVICE^HANDLER 9-2 LINE^HANDLER 9-3 PROCESS^ASSIGNS 9-5 PROCESS^USER^PARAMS 9-5 USER^ATTRIBUTES 9-7 USER^BACKUP 9-10 USER^COMMANDS 9-12 USER^INITIALIZE 9-18 USER^INIT^CONFIG^PARAMS 9-19 USER^REPLIES 9-20 USER^START 9-22 USER^STOP 9-23 USER^TAKEOVER 9-25 USER^VERSION 9-26 A. APPLS Requester Listing APPLS Listing A-1 B.
E. Intertask Communication Example Contents WRITER Listing D-13 DELETER Listing D-16 GDSX With NonStop TS/MP and TMF Procedures D-19 Compiling USAMPLE2 D-20 Binding D-21 Creating the Database D-21 Starting NonStop TS/MP D-21 Running the GDSX Application D-22 Configuring and Starting the Terminal Tasks D-23 USAMPLE2 Listing D-23 E.
Tables Contents Figure 1-2. Figure 1-3. Figure 1-4. Figure 1-5. Figure 1-6. Figure 1-7. Figure 1-8. Figure 2-1. Figure 2-2. Figure 2-3. Figure 4-1. Figure 4-2. Figure 4-3. Figure 4-4. Figure 5-1. Figure 5-2. Figure 5-3. Figure 5-4. Figure 5-5. Figure 5-6. Figure 6-1. Figure 7-1. Figure 7-2. Figure 7-3. Figure 7-4. Figure D-1. Figure D-2.
Contents Table 3-1. Table 3-2. Table 3-3. Table 3-4. Table 3-5. Table 3-6. Table 3-7. Table 5-1. Table 7-1. Table 8-1. Table 8-2.
Contents Extended General Device Support (GDSX) Manual—529931-001 xiv
What’s New in This Manual Manual Information Extended General Device Support (GDSX) Manual Abstract This is a reference manual for GDSX. GDSX is a nonprivileged, multitasking process used to handle datastream conversion and data communications-related functions for a business application. This manual provides information on how to design and code the user-supplied part of a GDSX process, and how to compile, bind, debug, and run GDSX.
What’s New in This Manual • • • • • • New and Changed Information The details for DCCBDEC2, PEXTGDS2, and TSCODE2 are added to Installed Subvolume Files on page 2-41. The details about accessing format 2 files of size greater than 4 GB is added to The User Source File on page 2-42. The example in Compiling on page 2-43 has been changed. The first sentence and the commands below the first sentence have been modified in Binding on page 2-45.
About This Manual This manual describes the operation of the Extended General Device Support (GDSX) product. GDSX is used to help you develop either a back-end process for message switching or a front-end process for implementation or modification of data communications protocols or support of nonstandard terminal devices. GDSX code contains the following: • • A set of generic service routines that are supplied by HP to support multithreaded, fault-tolerant processing.
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 References See Section 1 for an overview of GDSX, including its general purpose, the range of GDSX applications, hardware and software requirements, a description of the functional components of the GDSX code supplied by HP, and the interface of GDSX with TS/MP and Pathway/iTS. Depending on how detailed your understanding of GDSX needs to be, you may wish to use the tutorial in Sections 4 through 7 to learn more about GDSX.
Operations About This Manual References See Section 1 for an overview of GDSX. Unless you are already very familiar with GDSX, it will probably be helpful to do the tutorial in Sections 4 through 7. If your application has or will have a DEVICE^HANDLER only, you need only Sections 4 and 5. If your DEVICE^HANDLER is or will be multithreaded, you might find Sections 6 and 7 helpful.
Support About This Manual See the SCF Reference Manual for GDSX for more information on managing GDSX using SCF. Support Readers responsible for support of the GDSX product might need to perform any or all of the tasks listed under the “Systems Analysis,” “Design and Development,” “Operations,” and “Support” headings.
Notation Conventions About This Manual • • • • • • Introduction to NonStop Transaction Processing Introduction to NonStop Transaction Manager (TM/MP) PTrace Reference Manual Subsystem Control Facility (SCF) Reference Manual TAL Reference Manual NonStop TMF Application Programmer’s Guide Notation Conventions Hypertext Links Blue underline is used to indicate a hypertext link within text. By clicking a passage of text with a blue underline, you are taken to the location described.
General Syntax Notation About This Manual [ ] Brackets. Brackets enclose optional syntax items. For example: TERM [\system-name.]$terminal-name INT[ERRUPTS] A group of items enclosed in brackets is a list from which you can choose one item or none. The items in the list can be arranged either vertically, with aligned brackets on each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines. For example: FC [ num ] [ -num ] [ text ] K [ X | D ] address { } Braces.
Notation for Messages About This Manual Item Spacing. Spaces shown between items are required unless one of the items is a punctuation symbol such as a parenthesis or a comma. For example: CALL STEPMOM ( process-id ) ; If there is no space between two items, spaces are not permitted. In this example, no spaces are permitted between the period and any other items: $process-name.#su-name Line Spacing.
Notation for Messages About This Manual Bold Text. Bold text in an example indicates user input typed at the terminal. For example: ENTER RUN CODE ?123 CODE RECEIVED: 123.00 The user must press the Return key after typing the input. Nonitalic text. Nonitalic letters, numbers, and punctuation indicate text that is displayed or returned exactly as shown. For example: Backup Up. lowercase italic letters. Lowercase italic letters indicate variable items whose values are displayed or returned.
Notation for Management Programming Interfaces About This Manual % Percent Sign. A percent sign precedes a number that is not in decimal notation. The % notation precedes an octal number. The %B notation precedes a binary number. The %H notation precedes a hexadecimal number.
About This Manual Notation for Management Programming Interfaces Extended General Device Support (GDSX) Manual—529931-001 xxx
1 Overview of GDSX This section contains introductory material useful for a high-level understanding of GDSX, including an explanation of the purpose for which GDSX is used, typical GDSX applications, hardware and software requirements, a description of the functional components of the GDSX code supplied by HP, and the interface of GDSX with Pathway.
Communicating With User’s Devices Overview of GDSX GDSX interfaces with standard application software, such as Pathway, for communication with a back-end network, such as a banking network as shown in Figure 1-2. Figure 1-2. Communicating With Back-End Network Business Application GDSX IOP Network Business Application Device Device Device VST002.vsd GDSX is also used to handle message switching, either from terminal devices or from a back-end network, as shown in Figure 1-3.
GDSX Architecture Overview of GDSX Figure 1-3. Handling Message Switching Device Business Application GDSX IOP Device Device IOP Device Network Business Application Device Device VST003.vsd GDSX Architecture Figure 1-4 depicts the architecture of a GDSX process that is serving as a front end for a Pathway application.
GDSX Architecture Overview of GDSX Figure 1-4. Application With GDSX and Pathway/iTS GDSX Process SPI/SCF Kernel Service Routines USCODE (Pseudo Calls) (Utility Routines) IOP (such as CP6100) Management Programming Interfaces TACL Macros or User Application Pathway/iTS TCP Event Report POBJ File User's Business Program (SCREEN COBOL) Communication Line IDS or 6530 or $0 Event Collector Conversati onal Control 3270 Run Unit SCF VST004.
TSCODE Components Overview of GDSX USCODE consists of a number of procedures, called user exits, that are called by TSCODE to handle data manipulation, protocol conversion, and/or message routing. Two of the user exits are called the DEVICE^HANDLER and the LINE^HANDLER. USCODE is typically written in TAL, compiled separately, and bound with TSCODE to produce a functional GDSX front-end process. See Section 9, User Exit Descriptions for a description of all the user exits.
External Interfaces Overview of GDSX is restarted at the instruction following the last type 2 checkpoint call, and all its memory pool data is preserved. External Interfaces There are three standard external interfaces provided by GDSX: • • • The file system interface between TSCODE and business application processes. The file system interface between TSCODE and the IOPs. The SCF/SPI interface.
External Interfaces Overview of GDSX • Management programming control by means of a user-written management application program that uses the Subsystem Programmatic Interface (SPI). The interactive SCF interface includes generic commands used to configure and manage SU, LINE, TASK, and PROCESS objects; control the tracing facility; and display statistics on object status and resource allocation.
Support for USCODE User Exits Overview of GDSX Support for USCODE User Exits USCODE consists of 14 user exits called by TSCODE to allow you to implement application-specific data manipulation, protocol conversion, and message switching. All GDSX applications require the use of a DEVICE^HANDLER procedure, whether user-customized or copied from an example program.
Hardware and Software Requirements Overview of GDSX Pseudo Procedures TSCODE provides you with a set of pseudo procedure calls that, with some exceptions, have the same parameters, syntax, meaning, and resultant capabilities as their Guardian file system, Pathway/iTS, and TMF counterparts.
GDSX and Pathway/iTS Overview of GDSX GDSX and Pathway/iTS The Pathway/iTS transaction processing software, together with its parent product, TS/MP, provides an easy-to-use, powerful, and effective means of implementing online transaction processing (OLTP) applications. Pathway/iTS was designed to support the following terminals: • • • 6510, 6520, 6530, 6540, and IBM 3270 terminals operating in block mode.
Direct Terminal Access Overview of GDSX example, if a GDSX application is designed to use SCF to preconfigure SUs T1 and T2 using devices $T1 and $T2, the following commands could be issued: -> SCF -> ADD SU $GDS.#T1 -> ADD SU $GDS.#T2 Note how the device names $T1 and $T2 become #T1 and #T2, respectively, when combined with the GDSX process name in these commands.
Indirect Terminal Access Overview of GDSX the I/O process. When the I/O completes, the message is picked up by the DEVICE^HANDLER task and passed back to the requester. Figure 1-6. GDSX Without a LINE^HANDLER $GDS Requester Pseudo$RECEIVE File D^H Task $RECEIVE D^H Task Requester Pseudo$RECEIVE File VST006.vsd This type of direct interface between DEVICE^HANDLER tasks and I/O processes requires the terminal to have a unique Guardian file name that can be opened directly by TSCODE.
Indirect Terminal Access Overview of GDSX individual devices on the line do not.
Indirect Terminal Access Overview of GDSX Using PATHCOM, you configure SUs that Pathway/iTS is to open through GDSX. For example, if a Pathway/iTS requester is to communicate through a GDSX process named $GDS with a subdevice DEV2 configured under line $LINE1, the file name $GDS.#LINE1.DEV2 is used in the following PATHCOM commands: = = = = = SET SET SET SET ADD TERM TERM TERM TERM TERM TCP TCP-X TYPE T16-6530:0 INITIAL LOGON-SCREEN FILE $GDS.#LINE1.
Starting SU/Line With accessname NONE Overview of GDSX Figure 1-8. GDSX With a LINE^HANDLER $GDS TSCODE Requester D^H Task Requester $RECEIVE D^H Task IN^QUEUE^FI LE^NUM D^H Task Requester L^H Task IOP LINE^FILE^NUM VST008.vsd When the I/O operation(s) completes, the data is picked up by the LINE^HANDLER task, sent through TSCODE to the DEVICE^HANDLER task, and then passed back to the requester.
Communicating Directly With a NonStop TS/MP Server Overview of GDSX Communicating Directly With a NonStop TS/MP Server In general, you do not need a SCREEN COBOL program to handle the data transmissions with terminals. You can use the TS/MP pseudo procedure ^SERVERCLASS_SEND_ to send terminal data from GDSX directly to a TS/MP server. Another pseudo procedure, ^SERVERCLASS_SEND_INFO_, can be used when an error occurs to retrieve more information about the failed call to ^SERVERCLASS_SEND_.
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
Design and Development • • • Design Considerations Determine which D-series features will be used, including whether GDSX will run at a low PIN or a high PIN. For information on using these features, see Using DSeries Features on page 2-3.
Design and Development • Using D-Series Features Specify any necessary access method control details. Using D-Series Features A converted application is one that has been modified to use some extended feature of the D-series operating system. An unconverted application uses no extended features of the D-series operating system. TSCODE assumes that USCODE is converted if and only if d^plus^enabled of the CONTROLFLAGS configuration parameter is set to 1.
Design and Development • • • • • GDSX D44 Features Supported TSCODE maintains control blocks using the C-series format for internal data (for example, process ID). TSCODE assumes that any process identifier used by USCODE is a C-series process ID. TSCODE stores file name information in a 12-word format (as in GDSX C30). GDSX can be opened only by low PIN processes (except $ZNET); GDSX can open any process except an unnamed, high PIN process.
Design and Development • Coding and Testing Considerations D-series service routines, which are procedures that are new in the D44 RVU, as well as C-series service routines, which are C-series compatible procedures that can be called on either a D-series system or a C-series system. See Section 8, Service Routines for descriptions of all these procedures.
Design and Development • • Coding the DEVICE^HANDLER See Section 9, User Exit Descriptions for details on customizing other user exits and providing stubs for the remaining user exits. If possible, test DEVICE^HANDLER tasks by themselves, or with dummy LINE^HANDLERs. Coding the DEVICE^HANDLER • • • • • • • See Section 4, DEVICE^HANDLER Example, Running and Managing and Section 5, DEVICE^HANDLER Example, Design of the tutorial and the USAMPLE example program for examples.
Design and Development Debugging Your GDSX Application supports a set of pseudo Guardian procedures that correspond to the D-series Guardian procedures and a set of pseudo Guardian procedures that map to the Cseries Guardian procedures. • Any USCODE fault number must be greater than 100. Use only fault numbers from 301–500 for a LINE^HANDLER. Debugging Your GDSX Application • • • • • You can use a filter to display EMS messages. See EMS Filters and GDSX on page 2-79.
System Tasks Design and Development • The kernel is waiting for an internal resource or an I/O completion and no other tasks are ready to dispatch. A task is a running instance of either a TSCODE procedure or a USCODE procedure. A TSCODE task is called a system task, and a USCODE task is called a user task. A task has its own data stack, calls TSCODE procedures, and usually executes in a infinite loop. Generally, a user task manages exactly one terminal, line, or process.
Design and Development User Tasks Backup Task If GDSX is run as a process pair, TSCODE creates a backup task (task 3) during GDSX primary process initialization, which in turn creates a GDSX backup process and checkpoints data to the backup process. There is only one backup task per GDSX process, and it is always active after it is started. UserInit Task This task exists temporarily upon startup of a GDSX process.
Design and Development Overview of GDSX Processing LINE^HANDLER Task A LINE^HANDLER is an optional USCODE procedure typically used to implement data communications protocols and to allow each requester thread to use a shared resource (often a communications line) without allowing the threads to interfere with each other. Running copies of LINE^HANDLER code are called LINE^HANDLER tasks. These tasks are separate entities although they all use the same LINE^HANDLER procedure code.
Design and Development Overview of GDSX Processing 11. If GDSX is run as a process pair, the backup task starts the backup process, and in the backup process TSCODE calls user exits in the following order: a. USER^INIT^CONFIG^PARAMS b. USER^VERSION c. USER^INITIALIZE 12. If GDSX is run as a process pair, in the primary process TSCODE checkpoints data to the backup, then calls USER^BACKUP.
Calling Restrictions Design and Development Calling Restrictions User code is compiled to produce an object file that is bound with TSCODE, so there are restrictions to which user code must conform. Multithreaded operation would not be possible within GDSX if user tasks called Guardian I/O procedures in a waited manner.
Memory Management Design and Development * ^DELAY ^SERVERCLASS_DIALOG_BEGIN_ * ^DEVICEINFO2 ^SERVERCLASS_DIALOG_END_ ** ^ENDTRANSACTION ^SERVERCLASS_DIALOG_SEND_ ** ^FILE_CLOSE_ ^SERVERCLASS_SEND_ ** ^FILE_GETINFO_ ^SERVERCLASS_SEND_INFO_ * ^FILE_GETINFOBYNAME_ ^SETMODE ** ^FILE_GETRECEIVEINFO_ ^SETMODENOWAIT ^FILEINFO ^SETMYTERM ^FILE_OPEN_ ^SETPARAM ^FNAMEEXPAND ^SIGNALINTERRUPT ^LOCKREC ^SIGNALTIMEOUT ^MYTERM ^UNLOCKREC ** ^NEWPROCESS ^WRITE[X] * ^OPEN ^WRITEREAD[X]
Intertask Communication Design and Development USCODE, TSCODE provides local memory pools and extended data segment memory pools, as well as the following memory pool management procedures: GETEXTPOOL GETEXTPOOLX GETLOCALPOOL PUTEXTPOOL PUTLOCALPOOL In order to be consistent with TSCODE, when managing the available global memory pools, USCODE should use these procedures rather than another means.
Design and Development Steps for Coding New Applications and Conversion Steps for Coding New Applications and Conversion Whether you are developing new applications or converting an existing application, this subsection describes the sequence of steps involved in (1) coding a new GDSX D44 application and (2) converting a GDSX D44 application to use extended D-series features.
Design and Development Conversion for Extended Features of D-Series Systems 6. Run GDSX. See Running a GDSX Application on page 3-1. Ensure that d^plus^enabled of the CONTROLFLAGS configuration parameter is set to 1. Conversion for Extended Features of D-Series Systems Follow these steps when converting your application to use the extended features of the D-series systems: 1. Ensure that d^plus^enabled of the CONTROLFLAGS configuration parameter is set to 1. There are several ways to do this.
Design and Development • • User Code Declarations Resource maps SPI definitions Some of these declarations are public to USCODE (user code can source them in at compile time).
User Code Declarations Design and Development block can be referenced and updated by both TSCODE and USCODE, while global data within the user^private data block can be referenced and updated only by USCODE tasks. In all GDSX applications, user code must source in the three sections of the DCCBDECS file listed on the first line of Table 2-1. These sections define the IOCB, TCB, and FCB control structures shared by TSCODE and USCODE.
Design and Development Space Usages and Limitations scratchpad variables or user-defined attributes that are specific to a class of devices.) To do this, you modify the USKELDEC file as desired and source in its templates section at compile time. Caution. Although the DCB template is user-modifiable, the LCB template is not.
Design and Development User Data Segment 1025) and one for various control and data structures. The latter segment ID (ext^data^pool^seg^id) is 1024 by default, but can be specified by you with the SEGMENTID configuration parameter. For further information, see the description of the parameter later in this section. Although it is generally not advisable, USCODE can use its own extended segment through calls to ALLOCATESEGMENT and USESEGMENT. The segment IDs available to USCODE range from 0 to 1023.
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.
Extended Segment for Control Structures Design and Development Figure 2-2.
Design and Development Extended Segment for Control Structures allocations done for the pools. Equations for these calculations are given in Figure 2-2.
Design and Development 10005 10006 10007 10008 10009 10010 10011 10012 Extended Segments for Trace Files maxRCBpool or previous pools too large maxFCBpool or previous pools too large maxDCBpool or previous pools too large maxLDCBpool or previous pools too large maxLINEpool or previous pools too large maxPCBpool or previous pools too large Sum of all max***pools are > 16777216d Sum of final EXT.
Design and Development Local Pools memory pools within the user data segment—the buffer pool and the message pool— and two pools in an extended segment (by default, segment ID 1024)—the shared extended pool and the private extended pool—along with procedures to allocate and deallocate space from these pools (for additional information about memory pools, see Space Usages and Limitations on page 2-19).
Design and Development Extended Memory Pools Message Pool The message pool (also called the local message pool) is used primarily for queuing purposes. If data is received by GDSX but no recipient has been identified, the data is temporarily stored in this pool. This pool is in the upper 32K of the user data segment and contains approximately 32,000 words (see User Data Segment on page 2-20). Memory allocated from this pool is only word addressable.
Design and Development Checkpointing Memory Pool Buffers Before issuing a call to GETEXTPOOL[X] for space in this pool, the maximum size of the private extended pool is established by setting the TASKPOOLSIZE configuration parameter (see GDSX Configuration Parameters on page 2-46). TASKPOOLSIZE specifies the maximum pool size (in words) that each user task is allowed to acquire privately.
Design and Development Pool Checking extended memory where each task has a separate, TASKCPSIZE-sized area for checkpointing. Buffer images are copied, but to different addresses. Therefore, in the event of a takeover, any memory pool buffer addresses that the task has stored in its data stack are no longer valid. A task recovers its buffer images via calls on ^RECLAIMBUFFER. This procedure is passed (by reference) the word pointer to the data as it was allocated in the primary.
Design and Development • • • Level 1 Fault Tolerance The initial values for all globals, except those in user-named or private global data blocks The changing values for control block variables, except task control block variables The changing state of each configured task The backup process monitors the status of the primary GDSX process and takes over in case of primary process failure, restarting from the beginning the tasks that were active at the time of failure and were not doing any checkpointing
Design and Development • • • • • • Fault-Tolerance Processing in GDSX Initialization Calls the USER^VERSION user exit. Allocates memory for control blocks, memory pools, stack images, checkpointed buffers, EMS log message, and so on. Initializes monitor and listener system tasks. Starts the listener task. If GDSX was run as a process pair, a backup task is started. There is only one backup task per GDSX process, and it is always active after it is started.
Checkpointing Design and Development running and that checkpointing of significant events is required. The backup task then proceeds to bring brother up-to-date. (This process is similar to that involved in reviving a mirrored volume.) The backup task makes a pass through the primary’s data structures, including all the control blocks, checkpointing them to the backup. When the backup task has completed its work, it sets the global variable backup^process^flag to one and checkpoints it to brother.
Checkpointing Design and Development Each checkpoint record is structured as: Word 0 Size of checkpoint record in words (m) Word 1 Type of checkpoint record Word 2 Address of entity being checkpointed Words 3–m-1 Checkpoint data For example, to checkpoint a file, TSCODE uses the following record: Word 0 23 Word 1 Word 2 Words 3–10 Words 11–22 3 Address of associated FCB FCB File name Upon receiving this checkpoint message, brother compares the message with its FCB.
Design and Development Checkpointing to send the data to the backup process. The call to ^CHECKPOINT establishes a restart point at the instruction following the call. Note that this example synchronizes the checkpointed globals with the state of the calling task, but does not guarantee that the globals will be synchronized with the states of other tasks. Synchronization of the globals with other tasks depends on the application’s design.
Takeover Processing Design and Development The format of this area is: cpbuffer.size Total size of the checkpoint record cpbuffer.task Task number of checkpointer cpbuffer.data Buffer pool images Each pool image is formatted as: size Size of checkpointed data xaddr Address of data in the primary buffer pool data Buffer pool data image The last pool entry is a dummy and has a size of zero. 3. The area just constructed is moved to the next available word in the checkpoint buffer.
Design and Development Takeover Processing redirected to the backup GDSX process. Instead, GDSX emulates data communications I/O processes: any outstanding requester I/O operation is terminated with file-system error 210 (device ownership changed). For WRITEREADs and READs, no data is returned to the requester. All I/O that the previously active tasks had outstanding is canceled by TSCODE, and any semaphores that were held by those tasks (including the checkpoint semaphore) are released.
Design and Development Takeover Processing this attempt fails, another attempt will be made after 15 seconds. This process continues, with the time between attempts increasing to 30 seconds, then 45 seconds, then 60 seconds, and so on, until the time between attempts reaches 10 minutes where it remains until a backup is successfully created. (If the backup process fails for some reason, the same process occurs as the primary attempts to create a new backup.
Design and Development Transaction Management Facility Transaction Management Facility TMF protects transactions originating from the user tasks of a GDSX application. GDSX supports four pseudo TMF procedures: • • • • ^ABORTTRANSACTION ^BEGINTRANSACTION ^ENDTRANSACTION ^RESUMETRANSACTION Except for ^BEGINTRANSACTION, these pseudo procedures have the same syntax and function as their TMF counterparts.
Linked Lists Design and Development by calling ^RESUMETRANSACTION with trans-begin-tag set to 0D. The user task subsequently calls ^RESUMETRANSACTION with trans-begin-tag set to the transid of the suspended transaction to change its status from pending to active. An example of a GDSX application using the TMF pseudo procedures is given in Appendix D, Using Pseudo Procedures in a TS/MP Environment.
Design and Development Example Example This example shows how TSCODE handles a linked list of IOCBs associated with a task (a TCB). Each item in this list uses two doublewords. ! initialize tcb queue header CALL INIT^XLIST (tcb.qh); ! As a result, the header points to itself. ! The following gives possible content. ! ! Address Content ! ! tcb.qh 588362 588362 ! tcb.qt 588366 588362 ! ! put iocb onto tcb queue CALL INSERT^XITEM (tcb.qt, @iocb ); ! As a result, the iocb is linked to the header.
The GDSX Generation Process Design and Development A semaphore is first initialized with INIT^SEM. The semaphore may be defined either in global or extended memory; however, it is recommended that it be declared in global memory, within a user private block, for example. If a backup GDSX process exists, the semaphore must be initialized in both primary and backup GDSX processes. The semaphore may then be acquired by calls to PSEM and released by calls to VSEM.
Installed Subvolume Files Design and Development supplied declarations may also be sourced in from ULHDECS, ULHDECSE, USKELDEC, or a user-supplied declaration file with a different name. See User Code Declarations on page 2-17 for more information on files used during source code compilation. The object code file resulting from the compilation, named USCODE in Figure 2-3 on page 2-42, is then bound with TSCODE, the object code file supplied by HP. A BINDER IN file is commonly used for this step.
The User Source File Design and Development Figure 2-3. GDSX Generation Process Installed Subvolume DCCBDECS ?SOURCE ?SOURCE (Optional) TSCODE PEXTGDS ?SOURCE User Source File ULHDECS or TAL USKELDEC USCODEE BINDER IN File BIND Runnable GDSX Object VST011.vsd The User Source File The user source code file must contain all the user exits (procedures) called by TSCODE.
Design and Development Compiling User code must source in certain sections of the DCCBDECS and EXTDECS0 files, as well as the PEXTGDS file. (See User Code Declarations on page 2-17 for details.) To access format 2 files greater than 4 GB, the user code must source in sections of the DCCBDEC2 and PEXTGDS2 file. User code must also source in the DCB and LCB control structures.
Compiling Design and Development For example, you could create the following UBUILD file: Comment********************************************************* Comment * UBUILD Build Example USCODE from USAMPLE (16Mar93) * Comment * Aded a compilation step to create USCODE2 (03Feb05) * Comment********************************************************* Clear Comment Comment All Assign SSV1 TO GDSX volume.subvolume for ULHDECS, DCCBDECS, ZGDXTAL, PEXTGDS and USAMPLE Assign SSV1,< vol>.
Binding Design and Development Binding Next you use the UBIND file to bind TSCODE and USCODE and TSCODE2 with USCODE2.
GDSX Configuration Parameters Design and Development GDSX Configuration Parameters GDSX uses configuration parameters to control memory allocation and numerous aspects of the run-time environment (RTE). Some configuration parameters are called static, because once their values are determined at process creation time. They cannot be changed for that process. The other configuration parameters are called dynamic, because their values can be changed after the process has been initialized.
GDSX Configuration Parameters Design and Development Table 2-2.
GDSX Configuration Parameters Design and Development Table 2-2.
Setting Configuration Parameters Design and Development Table 2-3. Dynamic Parameters (page 2 of 2) External Parameter Name Internal DEFINE Name CONFIG^ PARAMS Name Default Value Range backup^debug^flag debug^flags.<13> 0 (OFF) 0–1 poolcheck^flag debug^flags.<14> 1 (ON) 0–1 debug^fatal^flag debug^flags.<15> 0 (OFF) 0–1 DEVICEINFO support^devinfo device^info 0 (OFF) 0–1 DYNAMIC dynamic dynamic^term %21 (ON) N.A. dynamic^recovery dynamic^term.
Design and Development Setting Configuration Parameters For example, to specify the restart time delay, assign a value to the name auto^restart^delay^time: PROC USER^INIT^CONFIG^PARAMS; BEGIN auto^restart^delay^time := 10000; To turn on the trace facility, assign 1 to the name auto^trace^flag: PROC USER^INIT^CONFIG^PARAMS; BEGIN auto^trace^flag := 1; 2. Before running GDSX, use TACL PARAM commands to assign values to external parameter names. This method may be used with static or dynamic parameters.
Descriptions of Configuration Parameters Design and Development Or, to turn off the trace facility, assign the following within USCODE: auto^trace^flag := 0; Methods 1 and 2 can be used to set either dynamic or static parameters, while methods 3 through 5 can be used only with dynamic parameters (SCF and SPI interfaces are established only after all parameters have been initialized). Method 2 will override settings made using method 1.
BACKUPCPU Design and Development BACKUPCPU This static parameter is used to specify a backup processer when a GDSX application is run in NonStop mode. You must specify a backup processor that is different from the primary processor. When a GDSX application designed for NonStop mode is configured to run as a TS/MP server, you do not use the BACKUPCPU configuration parameter to specify a backup processor. For this case, the specification of the primary and backup processors is always assigned by TS/MP.
CONTROLFLAGS Design and Development Internal DEFINE Name CONFIG^PARAMS Name Default Value Range auto^restart^flag control^flags.<13> 0 (OFF) 0–1 stats^flag control^flags.<14> 1 (ON) 0–1 sysmsgs^flag control^flags.<15> 0 (OFF) 0–1 Dmap^flag Dmap^flag is not used by TSCODE. It is used by the USAMPLE example program to establish dynamic session control (dynamic mapping). The value of this parameter may be displayed with the SCF INFO, DETAIL command on the GDSX process.
CTRL26 Design and Development Sysmsgs^flag Sysmsgs^flag determines whether TSCODE sends system messages to user tasks. If this flag is set, TSCODE forwards system messages to USCODE. Open message formats may be found in the Guardian Procedure Errors and Messages Manual. Maximum length of the D-series message forwarded is 81 words. The close message format is: INT type; ! = -104 INT processhandle[0:9]; ! = Requester process handle INT file; ! = file TSCODE allocates an IOCB for each open and close message.
Design and Development DEBUGFLAGS Debug^error^trap Debug^error^trap is used to indicate a file error number, which when detected by TSCODE will cause TSCODE to take one of two actions: • • Invoke DEBUG, which is done in case uscode^debug^flag is set to 1 Send a warning message with the file error number to the home terminal, in case uscode^debug^flag is set to 0 If you want TSCODE to trap file errors with numbers greater than 255, use the TRAPERROR configuration parameter with uscode^debug^flag.
DEVICEINFO Design and Development Poolcheck^flag Poolcheck^flag is used to indicate whether memory pools should be checked when tasks are dispatched. If poolcheck^flag is set, each time a task is dispatched TSCODE checks the buffer pool, message pool, extended buffer pool, and extended message pool for corruption. This pool checking is in addition to that always done when the GETLOCALPOOL and GETEXTPOOL procedures are called. If corruption is detected, GDSX stops with abend error 230 or 231.
DEVICEINFO Design and Development Reply with (57, 0, 132) Is DEVICEINFO parameter = 1? Yes No Is DEVICETYPE specified? Return record length and type and subtype of process (0, 0) Yes No Return DEVICETYPE, DEVICESUBTYPE,a nd PHYSRECLEN Return values from DEVICEINFO2 call on access name device If GDSX receives a DEVICEINFO message specifying a file other than the GDSX process, and if DEVICEINFO is equal to 1, then TSCODE determines whether the DEVICETYPE attribute is specified (by means of an SCF A
DYNAMIC Design and Development DYNAMIC This dynamic parameter is bit encoded and is used to set multiple configuration controls. Any nonzero value for dynamic signals TSCODE that dynamic SUs can be created. If dynamic equals zero, all SUs must be preconfigured. Internal DEFINE Name CONFIG^PARAMS Name Default Value Range dynamic dynamic^term %21 (ON) N.A. dynamic^recovery dynamic^term.<10> 0 (OFF) 0–1 dynamic^autostop dynamic^term.<11> 1 (ON) 0–1 dynamic^nowaitdepth dynamic^term.
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 looptime ticks without transferring control, it is presumed to be in a loop and is suspended with a fault. Internal DEFINE Name CONFIG^PARAMS Name Default Value Range looptime loop^time 200 ticks 0–32,767 ticks MAXBUFPOOL This static parameter can be used to specify the maximum size of the extended buffer pool. Internal DEFINE Name CONFIG^PARAMS Name Default Value Range maxbufpoolsize maxbufpool^size 32K bytes Up to 7.
MAXDCBPOOL Design and Development MAXDCBPOOL This static parameter can be used to override the calculation of DCB pool space done automatically by TSCODE during process initialization. In general, you should not need to set this parameter.
MAXFCBPOOL Design and Development MAXFCBPOOL This static parameter may be used to override the calculation of FCB pool space done automatically by TSCODE during process initialization. In general, you should not need to set this parameter.
MAXIOCBPOOL Design and Development MAXIOCBPOOL This static parameter can be used to override the calculation of IOCB pool space done automatically by TSCODE during process initialization. In general, you should not need to set this parameter.
MAXLDCBPOOL Design and Development To calculate the actual number for MAXITC, TSCODE first chooses the minimum value between the value you supply and 1,020.
MAXLINES Design and Development The size that TSCODE calculates for the pool can be overridden by using a TACL PARAM command to assign a value to the external name MAXLINEPOOL, or by assigning a value to the internal parameter name in the USER^INIT^CONFIG^PARAMS user exit. TSCODE uses the user-specified setting unless it is determined that the pool size would be insufficient, in which case TSCODE uses the value that it calculated.
MAXMSGPOOL Design and Development MAXMSGPOOL This static parameter can be used to specify the maximum size of the extended message pool. Internal DEFINE Name CONFIG^PARAMS Name Default Value Range maxmsgpoolsize maxmsgpool^size 32K bytes Up to 7.
MAXPROCESSES Design and Development TSCODE allocates the process control block (PCB) pool from extended memory. (See pcb^template in the DCCBDECS file in Appendix C.) The size in bytes of the PCB pool is calculated as follows: PCB pool size = $LEN(PCB^TEMPLATE) * MAXPROCESSES MAXPROCESSES This static parameter specifies the maximum number of processes that can be active simultaneously as a result of GDSX calls to the pseudo Guardian ^PROCESS_CREATE_ procedure.
MAXRCVPOOL Design and Development MAXRCVPOOL This static parameter may be used to override the calculation of RCV pool space done automatically by TSCODE during process initialization. In general, you should not need to set this parameter.
MAXTCBPOOL Design and Development MAXTCBPOOL This static parameter can be used to override the calculation of TCB pool space done automatically by TSCODE during process initialization. In general, you should not need to set this parameter.
POOLSIZE Design and Development See Running GDSX as a TS/MP Server on page 3-10 for more information. Internal DEFINE Name CONFIG^PARAMS Name Default Value Range nonstop^param N.A. 0 (OFF) 0–1 POOLSIZE This static parameter specifies the maximum size of the shared extended pool allocated for all user tasks.
RECEIVEDEPTH Design and Development If PROCNOWAIT is set to 1, a call to one of the procedures by any USCODE task does not cause TSCODE to suspend the task and assumes USCODE will call ^AWAITIO[X] on the pseudo-$RECEIVE file to wait for I/O completion. When the I/O completes, TSCODE returns the requested information in the output parameters of the ^AWAITIO[X] procedure and wakes up the calling task.
SECURITY Design and Development of the call to FAULT must be equal to 1). This parameter is only meaningful when auto^restart^flag is set on. See CONTROLFLAGS on page 2-52. Internal DEFINE Name CONFIG^PARAMS Name Default Value Range auto^restart^delay^time auto^restart^time 6000 ticks 0–65,535 ticks SECURITY This dynamic parameter is bit encoded and is used to set multiple configuration controls. $ZNET SCP program is usually owned by the super ID (255,255).
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 The size of the pool in bytes allocated by TSCODE for all user and system tasks is: (TASKCPSIZE * 2) * (MAXTASKS + 5) MAXTASKS specifies the total number of user tasks that may be active simultaneously, and TSCODE adds five to MAXTASKS for all the system tasks. See the explanation under MAXTASKS on page 2-68. TASKPOOLSIZE This static parameter specifies the maximum size of the private extended pool allocated for each user task.
TRACERECSIZE Design and Development If TMF is set to 1, TSCODE does not permit any TMF processing from a user task; however, it will pass a TMF transaction from an external process to another process. If TMF is set to 2, TSCODE permits TMF processing from a user task, but it will not pass a TMF transaction from an external process to another process. TRACERECSIZE This dynamic parameter specifies the maximum size of each record added to the trace file.
USERSTARTSU Design and Development If running OGDS (the USAMPLE object file), set userflags.<0> to 1, which is the default. USERSTARTSU This dynamic parameter indicates whether the USER^START exit is to be called whenever the TSCODE monitor task is about to open a file associated with an SU.
Notes on Specific Codes Design and Development fetoocheap febreakonly felinereset feeotreceived fenodata feownership fecpupon fescerror fepathdown fefatpin = = = = = = = = = = 99 110 124 163 187 200 230 233 201 560 , , , , , , , , , ; fenotready febreak femodemerr fepollend = = = = 100 111 140 176 , , , , feownabort feiopon = 210 , = 231 , fenetdown = 250 , The DEBUGFLAGS and TRAPERROR configuration parameters are used to indicate file error numbers, which when detected by TSCODE cause TSCODE
Design and Development Notes on Specific Codes Febadcount, Error 21 This error is returned when the size of an external process’s request exceeds the smaller value of RECEIVESIZE and the task’s READUPDATE on $RECEIVE. Femissparm, Error 29 If GDSX is run converted, only the GDSX pseudo Guardian procedures that correspond to the D-series Guardian procedures are available to USCODE (except for ^OPEN, ^CLOSE, ^FILEINFO, and ^FNAMEEXPAND).
Design and Development EMS Filters and GDSX Feownabort, Error 210 This error is returned when there has been a takeover by the backup process since the last request by this opener. Fefatpin, Error 560 If GDSX is run converted, only the GDSX pseudo Guardian procedures that correspond to the D-series Guardian procedures are available to USCODE (except for ^OPEN, ^CLOSE, ^FILEINFO, and ^FNAMEEXPAND). If other calls are attempted, TSCODE returns file-system error 29 or 560.
Design and Development Running the Filter POP X EMF /IN FILTGDS/ FGDS EMSDIST COLLECTOR $0, TYPE P, FILTER FGDS, TEXTOUT $term-name Running the Filter To run this filter, edit the LOADFILT file so that the ZSPITACL, ZEMSTACL, and ZGDXTACL files are properly qualified. (These files are often kept in the ZSPIDEF subvolume.) Change $vol and subvol to the appropriate volume and subvolume names; change $term-name to the name of the device where you want the messages to be displayed.
Selecting Trace Events Supported by TSCODE Design and Development 4. When GDSX processing is done, stop the trace session: -> TRACE PROCESS $GDSX, STOP -> EXIT 5. Run the PTrace utility to display all records in the file TRCFILE: > ? ? ? PTRACE FROM TRCFILE OCTAL ON RECORD ALL Selecting Trace Events Supported by TSCODE The first step in tracing a GDSX process is to decide what events you want to trace. Then determine from Table 2-4 which of these events TSCODE automatically generates trace records.
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 or by setting the maximum in a call to USER^OPEN^TRACE^FILE (see Section 8, Service Routines). Trace entries are differentiated from each other by a trace entry type. Type values from 0–127 are reserved for TSCODE events. Values from 128–255 are used for USCODE events.
User-Coded Trace Calls Design and Development Table 2-5.
Turning On the Trace Facility Design and Development Table 2-5. USCODE Trace Classes and Entry Types (page 3 of 3) SCF Trace Class Keyword Literal Name for Entry Type Literal Value Events Traced by USAMPLE Example Program SRMISC SR^MISC^REQ 200 Miscellaneous requests from USCODE SR^MISC^RSP 201 Miscellaneous responses to USCODE None 202-207 None Turning On the Trace Facility There are four ways to turn on the trace facility.
Design and Development Turning On the Trace Facility The trace facility is turned on in four different ways: 1. Enter the following PARAM command at the TACL prompt: > PARAM DEBUGFLAGS 16 The PARAM command should be entered before creating the GDSX process. This traces all TSCODE events described in Table 2-6 as well as all USCODE-defined events. Note. DEBUGFLAGS is a bit-encoded configuration parameter—see GDSX Configuration Parameters on page 2-46 for details. 2.
Modifying the Trace Design and Development Table 2-7.
Design and Development Examining the Trace entries wrap is 4096. Calls to ADD^TRACE^DATA and ADD^TRACE^DATA^INT can change the maximum number of records that can be generated for the TRACE file before the entries wrap. The TRACERECSIZE dynamic configuration parameter specifies the maximum size of each record added to the trace file. The default for this size is 256 words. The maximum record size can also be specified in a call to USER^OPEN^TRACE^FILE.
GDSX Internals Design and Development For more information, see the PTrace Reference Manual. GDSX Internals This subsection describes task I/O internals, including I/O involving $RECEIVE and I/O for files other than $RECEIVE, and the internals of intertask communication. I/O for Files Other Than $RECEIVE Two tables are used by the GDSX I/O procedures: the IOCB table and the FCB table. TSCODE allocates an IOCB to manage each outstanding nowait I/O. Among the entries in the IOCB are the following: iocb.
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.
Design and Development I/O for Files Other Than $RECEIVE IOCB is deleted from the list with head at tcb.iocbh and linked onto the end of a completed I/O list with header at tcb.qh. The IOCB is also deleted from the FCB list and its state is changed to 5 (pending). • At some time, the task initiating the I/O calls either ^AWAITIO or WAIT^EVENT. Assume that ^AWAITIO is called. Then TSCODE first determines if an I/O matching the file parameter has already completed by calling ^LISTEN.
I/O Involving $RECEIVE Design and Development I/O Involving $RECEIVE For task I/O involving $RECEIVE, GDSX uses the IOCB and TCB tables described previously and an additional table, the receive control block (RCB) table. An RCB is associated with each GDSX opener. When the TSCODE dispatcher is passed a new $RECEIVE request from Guardian AWAITIO, it calls RECEIVEINFO (or FILE_GETRECEIVEINFO_) to obtain the process ID (assigned to rcb.processid) and file number (assigned to rcb.tcp^file) of the requester.
I/O Involving $RECEIVE Design and Development iocb.msgtag Message tag from RECEIVEINFO iocb.rcbaddr Address of requester control block iocb.err 0 or FESYSMESS The DEVICE^HANDLER Task Calls ^READUPDATE At this point in time, the DEVICE^HANDLER task to receive the request may or may not have a ^READUPDATE posted on its pseudo $RECEIVE. When a DEVICE^HANDLER task calls ^READUPDATE(0,...
Design and Development • ° I/O Involving $RECEIVE An E^IMSG event is posted against the receiving task. Rcvtbl[iocb.msgtag] is set to @IOCB. The DEVICE^HANDLER Task Calls ^AWAITIO After the DEVICE^HANDLER task’s call to ^READUPDATE, when the task calls ^AWAITIO with the file parameter 0 or -1: • If an IMSG event for a task has occurred, ^LISTEN is called to look for IOCBs on the task’s completed I/O list with iocb.file equal to 0.
Design and Development • Intertask Communication The IOCB is deallocated. Intertask Communication The intertask communication (ITC) facility was implemented to enable DEVICE^HANDLER tasks to have a device-oriented interface to subdevices on a line or to communicate with other DEVICE^HANDLER or LINE^HANDLER tasks without using the Guardian file and message system. ITC communication is also possible between LINE^HANDLER tasks.
USAMPLE Example Program Design and Development When the task finishes processing the request and calls NOTIFY^IO^COMPLETION, the IOCB is delinked from the DEVICE^HANDLER task’s TCB and the ITC file’s FCB and is queued on the DEVICE^HANDLER task’s completed I/O list. Also, the IOCB’s state is changed to 5 (pending). Finally, the DEVICE^HANDLER task’s IOC event is posted. This is the same action that takes place when a Guardian I/O operation completes.
Design and Development USER^STOP Opens are associated with devices by the simple expediency of assigning an openid equal to the address of the associated DCB. Consequently, the procedure USER^START merely sets openid to @DCB, clears dcb.link and dcb.iocbaddr, and returns. USER^STOP The procedure USER^STOP must be able to handle the termination of both LINE^HANDLER tasks and DEVICE^HANDLER tasks; the subprocedures STOP^LINE and STOP^DEVICE^HANDLER handle these cases.
Design and Development The LINE^HANDLER Procedure First, a call is made to ^CHECKPOINT(1) to checkpoint the task stack. This is the only call to ^CHECKPOINT in the LINE^HANDLER and merely serves to speed up takeover after a failure. Next LINE^HANDLER^BODY posts ^READUPDATE operations on $RECEIVE and IN^QUEUE^FILE^NUM and calls the subprocedure LINE^STATE^MACHINE to start the line.
The LINE^HANDLER Procedure Design and Development request’s IOCB. Next, a test is made to determine if this is a WRITE (or WRITEREAD) request. If it is a WRITE, a call is made to INSERT^WRITE^QUEUE; otherwise, READ^DEVICE is called. INSERT^WRITE^QUEUE determines whether the write queue is empty. If the queue is empty, INSERT^WRITE^QUEUE calls CHECK^HALT^POLL. CHECK^HALT^POLL maintains a flag named polled^halting in LINE^HANDLER’s locals.
Design and Development The LINE^HANDLER Procedure Entries in the state transition table (line^state^table) contain four bytes, as follows: • • • • Byte 0: Current state Byte 1: Result of previous action Byte 2: Next action Byte 3: Next state The line state machine consists of an indefinite loop in which: 1. The result of the previous line action is evaluated and stored in the local variable rslt. This evaluation is done by a CASE FORM expression with the case index being the current line state.
Design and Development The LINE^HANDLER Procedure on the slow poll list are placed back on the poll list by a CHANGELIST(.., -2,..) call. As the line is now idle, a call is made to CHECK^CANCELS to get rid of any canceled IOCBs. Note. If this LINE^HANDLER is to be used in a production environment, handling of the slow poll list should be improved. If no error occurred on the READ operation, some subdevice responded to the poll.
The DEVICE^HANDLER Procedure Design and Development As a final step, CONTINUATION^READ deallocates the IOCB associated with the Envoy READ operation and returns: 0 Error occurred 1 EOT received 2 Text received When a WRITE or WRITEREAD operation is initiated on a line, the subprocedure WRITE^ACTION is called. Before this call, the subprocedure LOOK has set adcb to point to the DCB for the subdevice targeted for the write. WRITE^ACTION verifies that adcb has a current WRITE or WRITEREAD request.
The DEVICE^HANDLER Procedure Design and Development Device State Description 12 - d^preread2 READ posted on terminal; READUPDATE posted on $RECEIVE. 13 - d^preread3 READ posted on terminal; READUPDATE posted on $RECEIVE. 14 - d^reset1 A -20 system message has been received. A SETMODENOWAIT is in process to set the access mode for the terminal to break access. 15 - d^reset2 A zero-length write is in process to position the cursor to column 1 of the next row on the terminal.
Design and Development The DEVICE^HANDLER Procedure Extended General Device Support (GDSX) Manual—529931-001 2 -106
3 Operations and Support This section contains information about: • • • • • • Running a GDSX application Managing a GDSX application with SCF Using the code and data spaces Setting GDSX configuration parameters Dealing with a GDSX abend Interpreting console and EMS messages Running a GDSX Application Running a GDSX application can involve six steps: 1. Running a filter to display EMS messages. This is optional. For instructions on writing and running a filter, see EMS Filters and GDSX on page 2-79. 2.
Operations and Support ASSIGN and PARAM Commands In all other cases, the operating system runs GDSX at a low PIN. Even if all the above conditions are true, if a high PIN is not available, GDSX runs at a low PIN. For information on setting the HIGHPIN object file attribute or the TACL #HIGHPIN built-in variable, see the Guardian Application Conversion Guide.
Operations and Support Running a GDSX Process GDSX-object-file is the name of the GDSX object file. run-option-list is a list of one or more Guardian run options separated by commas. Only the NAME option is required. The options that are significant for running GDSX are the following: NAME $GDSX-process-name designates the symbolic name to be assigned to the GDSX process. The GDSX-process-name must follow Guardian naming conventions for processes.
Operations and Support Running SCF and Starting Requesters 2. Running GDSX as a process pair named $GDSX. The execution priority is 150, the primary process is to run in CPU 2, and the backup is to run in CPU 3: > RUN GDSE /NAME $GDSX, NOWAIT, PRI 150, CPU 2/ 3 Running SCF and Starting Requesters A GDSX application is usually designed either to never run with a LINE or to always run with one or more LINEs.
Operations and Support Running SCF and Starting Requesters The simplest GDSX configuration has no LINE and only dynamic SUs. Here are commands for a configuration that does I/O by means of a device $TC1: > RUN GDSE /NAME $GDSX, NOWAIT/ > RUN APPL /NAME $A1, OUT $GDSX.#TC1, NOWAIT/ The default for the configuration parameter MAXLINES (the maximum number of LINE^HANDLER tasks) is 0, so this parameter value is not entered.
Operations and Support Running SCF and Starting Requesters The last example can also be done with an SU having object name D1 and an access name, which is used to specify the file to be accessed through GDSX: > RUN GDSE /NAME $GDSX, NOWAIT/ -> SCF -> ADD SU $GDSX.#D1, ACCESSNAME $TC1.#C11 > RUN APPL /NAME $A1, OUT $GDSX.#D1, NOWAIT/ When GDSX is opened by requester $A1, the name of the file to be opened is not derived as in the above examples but is taken from the name given by the ACCESSNAME attribute.
Operations and Support Running SCF and Starting Requesters An example of how Pathway/iTS requesters may be used in a GDSX application is provided in Running a Pathway/iTS Application on page 3-9 The configuration parameter with external parameter name MAXLINES is used to specify the maximum number of LINEs that may be configured for the GDSX process. The default for the parameter is zero.
Operations and Support Running SCF and Starting Requesters > RUN APPL /NAME $A1, OUT $GDSX.#LINE1.D1, NOWAIT/ > RUN APPL /NAME $A2, OUT $GDSX.#LINE1.D2, NOWAIT/ When the LINE is started in SCF, GDSX opens $IOP1. When requester $A1 runs, GDSX opens SU D1, establishing a thread from $A1 through $GDSX to $IOP1.#DEV1. When requester $A2 runs, GDSX opens SU D2, establishing a thread from $A2 through $GDSX to $IOP1.#DEV2.
Running a Pathway/iTS Application Operations and Support When requester $A1 starts up, the file $IOP1.#DEV1 will be accessed on node \NY. Running a Pathway/iTS Application When starting an application using Pathway/iTS (and its parent product, TS/MP) and GDSX, the GDSX process is started first. For example, the following command may be issued to run a GDSX object named $GDSX: > RUN GDSE /NAME $GDSX, NOWAIT/ The configuration either involves a LINE or does not involve a LINE.
Running GDSX as a TS/MP Server Operations and Support Pathway/iTS Applications With a LINE Suppose that an application using Pathway/iTS and GDSX has a LINE. When starting such an application, the GDSX process is run first. For example, the following command can be issued to run a GDSX object named $GDSX: > PARAM MAXLINES 1 > RUN GDSE /NAME $GDSX, NOWAIT/ The MAXLINES configuration parameter indicates to GDSX that there is to be a maximum of one line in the configuration.
Operations and Support • • Running GDSX as a TS/MP Server If the GDSX server is not running in NonStop mode and it fails, TS/MP automatically restarts the GDSX server if the server is configured with the TS/MP AUTORESTART parameter set to a value equal to or greater than 1. A GDSX server is affected by the PATHCOM commands that deal with servers, such as THAW and START. (The PATHCOM commands FREEZE or STOP affect a GDSX server when only Pathway/iTS requesters have opened GDSX.
Space Usages and Limitations Operations and Support = SET SERVER PARAM PROCNOWAIT 1 Run in nowait mode = SET SERVER PARAM SERVER 1 Run as a server = SET SERVER PARAM NONSTOP 1 Run in NonStop mode = ADD SERVER GDSX-SERVER = START SERVER GDSX-SERVER Name of server class Start the GDSX server Space Usages and Limitations Because USCODE is bound with TSCODE to become a GDSX runnable unit, there are limitations in code space and data space in user code.
Operations and Support GDSX Configuration Parameters If the specified trace file does not exist, the GDSX process creates and uses the file. If the default subvolume already has a file with the name specified and the file has not been opened by another process, the GDSX process opens the file. If the specified trace file is in use by any other process, the GDSX process will not initiate the trace.
Management With SCF Operations and Support For example, to turn off the trace facility, enter the following SCF command: -> TRACE PROCESS $GDSX, STOP Methods 2 and 3 are of equal priority; they both override settings made with method 1.
Command Summary Operations and Support The typical command syntax is: command object-type object-name [ modifier ] , ... For example: -> START LINE $XGDS.
Interpreting Console and EMS Messages Operations and Support Table 3-1. GDSX Subsystem-Specific SCF Commands Object Type Command PROCESS PRIMARY X TASK START LINE SU X X STATS X X X X STATUS X X X X STOP X X X STOPOPENS X TRACE X VERSION X Interpreting Console and EMS Messages Messages generated by GDSX can be classified according to severity: Status messages Report a state change within a GDSX process. Some examples of status messages are startup, open, and close messages.
Operations and Support Types of Messages Generated EMS Terminal GDSX processes send tokenized event messages to the Event Management Service (EMS) primary collector ($0) process. The collector stores these messages in the current EMS log file. EMS distributor processes select messages from the log file and deliver them to consumers. A distributor process can use a filter to limit the types of events passed to a consumer.
Operations and Support FCB File control block DCB Device control block LDCB Logical device control block LCB LINE control block PCB Process control block Startup Configuration Error Messages Generally, it is not necessary to override the size that TSCODE calculates for a pool, but it can be overridden either by using a TACL PARAM command to assign a value to the configuration parameter’s external name, or by assigning a value to a configuration parameter’s internal name in the USER^INIT^CONFIG^P
Operations and Support 10010 10011 10012 10013 10014 10015 10016 10017 Abend Messages maxPCBpool or previous pools too large Sum of all max***pools are > 16777216d Sum of final EXT.
Abend Messages Operations and Support GDSX problem reports should be accompanied by a SAVEABEND dump (if a dump was generated) and the object code file (with SYMBOLS) running at the time of the failure. Following is the format of an abend error message: process-name: INTERNAL ERROR #number AT %ee.address Save file created: vol.subvol.filename ABENDED: process-name number is the abend error number ee is the code space ID address is the value of the P register For example: $GDSX: INTERNAL ERROR #020 AT %00.
Abend Messages Operations and Support Table 3-2. Abend Error Messages Abend Number Literal for Error Number Description of Event Causing Abend 310 error^unexpected^case Case statement error 320 error^wrong^case Case statement error 500 error^q^cp Fault-tolerance processing problems Errors Less Than 100 An abend error number less than 100 usually indicates that the system does not have enough space to run a GDSX process. To recover, use a disk that has more free space.
Abend Messages Operations and Support Table 3-3. Error 220 Message Breakdown (page 1 of 2) TSCODE Procedure/ Subprocedure Executing Description of Event Causing Error 220 ALLOCATETCBX A task is being created, and the state of the allocated TCB is not 0. ^AWAITIOX No event is found for waking up a task, or no valid buffer address was returned from procedure ^LISTEN. BACKUP^LISTENERX (MAIN) The backup process receives a file error that is not a system message (6).
Trap Messages Operations and Support Table 3-3. Error 220 Message Breakdown (page 2 of 2) TSCODE Procedure/ Subprocedure Executing Description of Event Causing Error 220 DISPATCHX/ IO^COMPLETION An I/O completed on some file other than $RECEIVE but the file did not have an outstanding I/O. FAULT The procedure was called for a system task. GETEXTPOOL A user task tried to get space from the system pool, which is reserved for TSCODE. INSERT^ITEM The linked list is corrupted.
EMS Event Messages Operations and Support When the operating system encounters a trap, the GDSX trap handler is called. The trap handler in turn calls the procedure DIE. If debug^fatal^flag of the DEBUGFLAGS configuration parameter is set, DIE calls DEBUG. Regardless of the value of DEBUGFLAGS, the process will calls ABEND, so that if SAVEABEND is set for the process (at bind time), a memory image file will be created for later investigation using INSPECT.
EMS Event Messages Operations and Support hh is hour mi is minute ss is second mm is month dd is day yy is year name is process name EMS event messages generated by converted GDSX processes always show the PIN with a value of 255.
Fault Messages Operations and Support Table 3-5.
Fault Messages Operations and Support hh is hour mi is minute ss is second mm is month dd is day yy is year name is process name Fault messages generated by converted GDSX processes always show the PIN with a value of 255. Here is an example of a fault message: 09:23:00 04/10/91 $GDSX (06,37) error - TERM 01 ($GDSX.#T27B) Fault # 104 P = %00.047502 Table 3-7 contains a summary of the fault messages issued by TSCODE. Fault numbers 0-4 and 10-13 are usually generated by the GDSX trap handler. Table 3-7.
If GDSX Abends Operations and Support Table 3-7. TSCODE Fault Messages Fault Number Description 16 Task tried to close $RECEIVE. 17 Task called INIT^SEM passing a nonzero semaphore. 18 Task attempted to obtain an uninitialized semaphore. 19 Task attempted to release a semaphore it did not own. 20 Task passed an invalid task number to get a TCB address.
Operations and Support • • • • • • If GDSX Abends If a problem occurs with a GDSX process that was running a trace, save the trace file because subsequent GDSX runs might write over data in the file. The default name for the primary process trace file is TRACEP; the default name for the backup process trace file is TRACEB. For more information on the trace facility, see Tracing GDSX on page 2-80. If the problem involves SCF or SPI, record the version procedures for SCF and SCP.
Operations and Support Extended General Device Support (GDSX) Manual—529931-001 3- 30 If GDSX Abends
4 DEVICE^HANDLER Example, Running and Managing The typical purpose of a DEVICE^HANDLER is to modify the communication of each thread between a requester and another file. The GDSX program demonstrated in this section, called the DEVICE^HANDLER example, includes a DEVICE^HANDLER procedure that modifies communication between multiple requesters and the terminals to which they are mapped. Figure 4-1 shows an overview of the processing done in this unconverted example program.
DEVICE^HANDLER Example, Running and Managing Running an Application Process Running an Application Process In the tutorials on both the DEVICE^HANDLER example and the LINE^HANDLER example in Section 4, DEVICE^HANDLER Example, Running and Managing through Section 7, LINE^HANDLER Example, Design, a simple unconverted TAL application is used to send requests to the GDSX process. (FUP may also be used as a requester.
DEVICE^HANDLER Example, Running and Managing Running Two Requesters 2. Reverse the text string that was input at the prompt. 3. Issue a waited WRITE of the reversed string to the file and delay two seconds. Later in this section the APPLS application is used similarly to communicate with a terminal, but with an intermediate GDSX process doing datastream conversion, changing all lowercase text sent to the terminal to uppercase text.
DEVICE^HANDLER Example, Running and Managing Compiling LINE^HANDLER Example, Running and Managing and Section 7, LINE^HANDLER Example, Design), use the following files from a GDSX installed subvolume: File Description DCCBDECS Source file containing global variables and other common declarations Source file containing declarations specific to the example program Another source file containing external declarations for procedures within TSCODE U ser source code file containing all the user exits (proced
DEVICE^HANDLER Example, Running and Managing Compiling Figure 4-2. Example Generation Process Installed Subvolume DCCBDECS ?SOURCE ?SOURCE (Optional) ULHDECS TSCODE PEXTGDS ?SOURCE USKELEX Source File TAL USCODEE UBINDE IN File BIND Runnable GDSX Object VST013.
DEVICE^HANDLER Example, Running and Managing Binding COMMENT ZSPITAL location ASSIGN SSV3, $SYSTEM.ZSPI TAL /IN USKELEX, MEM 64, OUT $S.#USKELEX/ USCODEE; & SYMBOLS, INSPECT, NOCODE, NOICODE, NOMAP CLEAR ALL EXIT After creating UBUILD, issue the command OBEY UBUILD to compile the source code file and produce the object file USCODEE. The HIGHPIN object-file attribute is not set on, because this example is an unconverted application that cannot run at a high PIN.
DEVICE^HANDLER Example, Running and Managing Using SCF This is necessary because of example-specific changes made to the device control block declaration. (For more information, see the description for EXTSUSIZE on page 2-59.) Then run your new GDSX process: > RUN GDSE /NAME $GDS, NOWAIT/ This GDSX process includes a DEVICE^HANDLER that does datastream conversion on messages passed from multiple requesters to different asynchronous terminals.
DEVICE^HANDLER Example, Running and Managing Running an Application Process The VERSION command displays the version level and date for the GDSX process. Enter: PROCESS $GDS # -> INFO The INFO command gives you current attribute and configuration parameter values for the GDSX process. Enter: PROCESS $GDS # -> INFO, DETAIL The INFO, DETAIL command gives the same data as INFO, plus additional attribute values.
DEVICE^HANDLER Example, Running and Managing Running an Application Process Figure 4-3 illustrates the processing that occurred up to this point. The GDSX process, named $GDS, performed its initialization processing and issued a READUPDATE on $RECEIVE. Then the application program, named $A1, performed its initialization processing and issued a call to OPEN $GDS.#TC1. $GDS received the open message and in turn issued an OPEN $TC1, which was processed by the IOP. Figure 4-3.
DEVICE^HANDLER Example, Running and Managing Running an Application Process At the first application terminal, enter a short text string followed by a carriage return. The string of characters should then be displayed in reverse order. In addition, lowercase alphabetic characters should now appear as uppercase, indicating that the intermediate GDSX process has done its datastream conversion. Figure 4-4 illustrates the message flow for this transaction. Figure 4-4.
DEVICE^HANDLER Example, Running and Managing Running a Second Application Process and the IOP displayed the uppercase reversed string. After checking the condition code for its WRITE, $GDS REPLYs to $A1, which then sends another prompt to the terminal by means of GDSX. Now at the TACL terminal, enter the following command at the SCF prompt: -> ASSUME SU $GDS.#TC1 The new prompt includes the name of the SU. Enter an INFO command: SU $GDS.
DEVICE^HANDLER Example, Running and Managing Running a Second Application Process From the TACL prompt (you may need to use the Break key again to interrupt SCF), you can enter: > STATUS *, TERM to see whether the process has started and what the CPU number and PIN are. The CPU number and PIN should be the same as the numbers that now appear in the prompt on the second application terminal. Then pause the TACL process at the TACL terminal to allow SCF to regain control.
DEVICE^HANDLER Example, Running and Managing Stopping the First Application and GDSX Stopping the First Application and GDSX At the SCF prompt, enter: -> STOP SU You should see the following message, indicating that the SU has an opener ($A1), and therefore cannot be stopped: -> GDS E00011 STOP failed: Object is currently active Then issue the following command for the same subdevice: -> ABORT SU At the first application terminal, after the CPU number and PIN prompt, you should see the message: D^H TASK
DEVICE^HANDLER Example, Running and Managing Stopping the First Application and GDSX Extended General Device Support (GDSX) Manual—529931-001 4- 14
5 DEVICE^HANDLER Example, Design The previous section described how to run and manage a simple DEVICE^HANDLER example program. This section contains a description of the environment of an executing DEVICE^HANDLER task, and an analysis of the design of the DEVICE^HANDLER example, including the typical structure used by a DEVICE^HANDLER for input, processing, and output to the IOP.
Task I/O Calls DEVICE^HANDLER Example, Design Figure 5-1. DEVICE^HANDLER Task Run-Time Environment $GDS Pseudo$RECEIVE File Requester TSCODE D^H Task $RECEIVE D^H Task Requester Pseudo$RECEIVE File Monitor Task Listener Task VST016.vsd By means of a typical $RECEIVE file, TSCODE accepts incoming messages addressed to subdevices under GDSX ($GDS.#TC1, for example).
DEVICE^HANDLER Example, Design • Task I/O Calls You would no longer have access to nowait I/O tags for application-specific purposes. Therefore, in designing GDSX an additional layer of TSCODE software was placed between USCODE and the Guardian file system, TS/MP server classes, and the TMF product. This layer of software (called pseudo procedures) allows GDSX to monitor every I/O operation that is initiated and ensures that each I/O can be properly handled at completion time.
Task I/O Calls DEVICE^HANDLER Example, Design Figure 5-2. DEVICE^HANDLER Example: Sending a Request to a Terminal Application A WRITEREAD with data is sent to GSDX GDS (TSCODE and USCODE) T S C O D E c h e c k s $ R E C E IV E fo r i np u t a n d id e n t if ie s t h e U S C O D E D ^ H t a s k th a t i s t o h a n d le th e W R IT E R E A D IOP/Terminal TSCODE checks to see whether a ^R E A D U P D A T E o n th e t a s k ' s p s e u d o $ R E C E IV E h a s b e e n is s u e d b y th e ta s k .
Task I/O Calls DEVICE^HANDLER Example, Design Guardian file-system counterparts, and are not included here. See Section 8, Service Routines for a description of all TSCODE-supported procedures.
Basic Structure of DEVICE^HANDLER Code DEVICE^HANDLER Example, Design Basic Structure of DEVICE^HANDLER Code A DEVICE^HANDLER task starts when TSCODE calls the DEVICE^HANDLER procedure. After any necessary initialization processing, the task runs in a continuous loop, reading from the pseudo-$RECEIVE file and sending output to and receiving input from its device, never doing a RETURN to TSCODE. This structure is shown in Figure 5-3. Figure 5-3.
DEVICE^HANDLER 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 Within the main loop of the DEVICE^HANDLER (see Example 5-3 and Example 5-6), a buffer of size buf^size is requested from the byte-addressable extended buffer pool. The buffer holds a message read from the pseudo-$RECEIVE file. Because tasks are swapped in and out, I/O cannot be done from buffers within a task’s data stack. Instead of declaring local variables for message buffers, I/O buffer space is obtained from the global memory pools.
DEVICE^HANDLER Example, Design The DEVICE^HANDLER Procedure If the condition code is > (CCG), a system message was received. The first character of rcv^buf is examined to determine what kind of system message this is. The only kind allowed for by this code is CTRL or SET^MD, -32 or -33, respectively. For anything else, DEBUG is called. Request Processing Next in the source file is a section of code dealing with fault-tolerance processing, to be discussed later in this section.
DEVICE^HANDLER Example, Design The DEVICE^HANDLER Procedure Example 5-4.
DEVICE^HANDLER Example, Design Inspecting the DEVICE^HANDLER Example to see whether there is an outstanding ^WRITEREAD to be canceled (this is discussed under The USER^STOP Procedure on page 5-19). Any file-system error is passed back to the requester application. The processing for WRITE and for READ is similar. Incoming datastream conversion could be implemented by a procedure called immediately before ^REPLY when processing READ and WRITEREAD requests.
DEVICE^HANDLER Example, Design Device Control Blocks At the TACL terminal, bring your GDSX process under the control of Inspect by entering: > DEBUG $GDS, TERM $TC2 To make the source code visible under Inspect, in high-level Inspect at the Inspect terminal, enter: - SOURCE ON - SCOPE #DEVICE^HANDLER - SOURCE Enter a few carriage returns until you see the CASE RQST^TYPE statement. Set a breakpoint at this line: - BREAK #line-num Then press “R” to resume execution of your program.
Device Control Blocks DEVICE^HANDLER Example, Design Storage for DCBs is declared at run time by TSCODE and is contained in extended memory. The size of a DCB for a GDSX process depends on the EXTSUSIZE configuration parameter, which can be supplied at startup time. Therefore, storage for DCBs cannot be determined at compile time.
Task Control Blocks DEVICE^HANDLER Example, Design Figure 5-5. Control Block Pointer Tracing TCB DCBs IOCB BUFFER IOCNT BUFADDR [X] TEXT TCBADDR LASTRCVIOCB VST020.
DEVICE^HANDLER Example, Design I/O Control Blocks I/O Control Blocks Now examine the I/O control block (IOCB) representing the last $RECEIVE request (a WRITE) passed to the task. TSCODE allocates an IOCB to manage each outstanding nowait I/O. All IOCBs representing I/O operations for a particular task are linked to the task’s TCB.
DEVICE^HANDLER Example, Design The USER^STOP Procedure The USER^STOP Procedure In an exercise in the previous section, an SU was stopped with an SCF ABORT command. The abort message was sent to TSCODE, which then stopped the DEVICE^HANDLER task. When the task was stopped, the USER^STOP user exit was called by TSCODE, as shown in Example 5-5. Because the stopped task, whose TCB address is passed in the call to USER^STOP, was waiting on a ^WRITEREAD (dcb.
Testing Failure at a ^WRITEREAD DEVICE^HANDLER Example, Design support of fault-tolerant applications. Depending on the degree to which USCODE implements these features, various levels of fault tolerance can be achieved. Persistent operation is possible without checkpointing by USCODE if a backup CPU is specified when the GDSX process is started. In this case TSCODE: • • • • Starts the backup process and monitors for failures. Checkpoints global information such as control structures.
Testing Failure at a ^WRITEREAD DEVICE^HANDLER Example, Design but do not enter a carriage return. The requester and the DEVICE^HANDLER task now have pending WRITEREADs. At the TACL terminal, simulate a GDSX process failure by entering: > STOP primary-cpu, primary-pin At the application terminal, after the CPU and PIN prompt and the text that you entered, in approximately half a minute you should see the following message: PLEASE RE-ENTER DATA followed by a new CPU and PIN prompt.
Testing Failure at a ^WRITEREAD DEVICE^HANDLER Example, Design had been no ^CHECKPOINT call, the task would have been restarted from its main entry point. Figure 5-6. Fault Tolerance in the DEVICE^HANDLER Example WHILE (1) DO @RCV^BUF := GETEXTPOOL (... TAKEOVER := FALSE ^READUPDATEX (PSEUDO-$RCV,... ANALYZE REQUEST TYPE TAKEOVER ^CHECKPOINT(2) TAKEOVER := TRUE NORMAL ^RECLAIMBUFFER (@E^RCV^BUF, 10) WT WTRD TRUE TAKEOVER? ^WTX TERM FALSE ^WTX TERM ^REPLYX VST021.
DEVICE^HANDLER Example, Design Testing Failure at a ^WRITE backup process. Therefore, because this example calls ^CHECKPOINT(2), after takeover the receiving buffer (rcv^buf) allocated from the buffer pool will be available. In the event of a takeover, however, any memory pool buffer addresses that the task has stored in its data stack are no longer valid. A task must recover its buffer images by making calls on ^RECLAIMBUFFER.
DEVICE^HANDLER Example, Design Testing Failure at a ^WRITE When the GDSX primary process was stopped, the requester received file-system error 210 on its WRITE and completed its transaction processing loop as if the WRITE had been completed normally. The requester is designed to let the DEVICE^HANDLER retry the WRITE.
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 This section of the tutorial requires three terminals designated the TACL terminal, the SCF terminal, and the application terminal. It is assumed that the terminals will be accessed by way of the TERMPROCESS IOP. Running the LINE^HANDLER Example This example uses the same APPL and GDSE object files generated in Section 4, DEVICE^HANDLER Example, Running and Managing.
LINE^HANDLER Example, Running and Managing Preconfiguring the LINE and Subdevices After the ASSUME command executes, the SCF prompt includes the object type and process name. Now enter a STATUS command: PROCESS $GDS # -> STATUS The STATUS command tells you that there are two TSCODE system tasks running, and no USCODE user tasks running. Now ADD a LINE object (a logical LINE) called $GDS.#LX with an access name of the device name of your application terminal.
LINE^HANDLER Example, Running and Managing Running an Application Process The STATUS command tells you that there are two TSCODE system tasks, and one USCODE user LINE task. Enter: PROCESS $GDS # -> STATUS SU T1, DETAIL The task number is 0, indicating that a DEVICE^HANDLER task has not yet been created to manage the T1 subdevice preconfigured. Enter: PROCESS $GDS # -> STATUS SU *, DETAIL The wild-card character (*) directs the STATUS command to give information about all SU objects under the LINE object.
LINE^HANDLER Example, Running and Managing Running More Application Processes The GDSX process, named $GDS, did its initialization processing and issued a READUPDATE on $RECEIVE. Then the application program, named $A1, did its initialization processing and issued a call to OPEN $GDS.#LX.T1. After TSCODE received the OPEN, the SU T1 was opened, a DEVICE^HANDLER task was created to manage communication to T1, and the LINE^HANDLER task was notified that the SU was opened.
Running More Application Processes LINE^HANDLER Example, Running and Managing All four user tasks are started. The SU objects have one open each and the LINE object has three opens, one for each SU. At the application terminal, enter at least three more text strings and observe the rotation sequence of the prompts. The three requesters direct their output to logical subdevices T1, T2, and T3, all of which are mapped to physical device $TC1 under logical LINE $GDS.#LX.
LINE^HANDLER Example, Running and Managing Running More Application Processes The STATUS command display should show that one SU and the LINE object are open and started, and Tn and Tm are stopped with no opens. At the application terminal you may verify that only one requester process is sending prompts to the terminal. Then press CTRL/Y to stop this process. You can press the Break key to get a TACL prompt at the application terminal.
LINE^HANDLER Example, Running and Managing Running More Application Processes Extended General Device Support (GDSX) Manual—529931-001 6 -8
7 LINE^HANDLER Example, Design The previous section described how to run and manage a LINE^HANDLER example program. This section contains a description of the environment of an executing LINE^HANDLER task and an analysis of the design of the LINE^HANDLER example, including the typical structure used by a LINE^HANDLER task for communication with the DEVICE^HANDLER tasks and the IOP.
Environment of an Executing LINE^HANDLER Task LINE^HANDLER Example, Design Figure 7-1. LINE^HANDLER Run-Time Environment $GDS TSCODE D^H Task Requester Requester $RECEIVE D^H Task IN^QUEUE^ FILE^NUM L^H Task 0 LINE^ FILE^ NUM Requester D^H Task Monitor Listener VST023.vsd ITC file numbers are not actual Guardian file numbers, but values assigned by TSCODE to DEVICE^HANDLER tasks whose messages are to be routed to associated LINE^HANDLER tasks.
LINE^HANDLER Example, Design Intertask Communication—LINE^HANDLER Perspective The layer of software called pseudo procedures Section 4, DEVICE^HANDLER Example, Running and Managing and Section 5, DEVICE^HANDLER Example, Design on the DEVICE^HANDLER example is also used with LINE^HANDLER tasks.
Intertask Communication—LINE^HANDLER Perspective LINE^HANDLER Example, Design Figure 7-2. Sending a WRITEREAD Through a LINE^HANDLER (page 1 of 2) Application A WRITEREAD is sent to GDSX. L^H Task D^H Task TSCODE identifies which D^H task should handle the request.. IOP/Terminal TSCODE checks to see whether a ^READUPDATE has been issued by the D^H task. ( The issuing of ^READUPDATE makes it possible to receive incoming messages.) NO YES TSCODE queues this request.
Intertask Communication—LINE^HANDLER Perspective LINE^HANDLER Example, Design Figure 7-2. Sending a WRITEREAD Through a LINE^HANDLER (page 2 of 2) Application D^H Task L^H Task IOP/Terminal The L^H task detects the intertask request and then issues a ^WRITEREAD to send the data to the terminal (line). The L^H task can continue to process other requests, but checks for the I/O completion event.
Intertask Communication—LINE^HANDLER Perspective LINE^HANDLER Example, Design The event descriptions and the global literals (declared in DCCBDECS (EVENTS)) used by TSCODE to define the events are given in Table 7-1. Events having an IOCB associated with them are marked in the fourth column. Table 7-1.
LINE^HANDLER Example, Design Transaction Flow NOTIFY^IO^COMPLETION[X] is a procedure commonly used to complete I/O operations in a task. A task calls this procedure to notify a DEVICE^HANDLER task that an intertask request is complete. All DEVICE^HANDLER tasks may have intertask requests outstanding at the same time. The LINE^HANDLER task must manage communication of these requests to a shared file (a terminal in this example) so that the threads do not interfere with each other.
Transaction Flow LINE^HANDLER Example, Design Figure 7-3. LINE^HANDLER Example Message Flow D^H Task ITC File $RECEIVE Pseudo$RECEIVE IN^QUEUE^FIL E^NUM/E^ITC L^H Task T1 D^H Task $A1 Pseudo$RECEIVE #LX E^IOC T2 E^TIMEOUT D^H Task $A2 Pseudo$RECEIVE ITC File WT^IOCB E^STOP T3 ITC File $A3 E^CAN WT^RD^IOCB ^LIST E^IMSG Listener VST025.
LINE^HANDLER Example, Design Transaction Flow at the prompt, are transferred to the original dh^iocb, and the task then calls NOTIFY^IO^COMPLETION, which sends a message to the DEVICE^HANDLER task that sent the request, notifying it of the completion. (This message looks like a standard Guardian I/O completion to the DEVICE^HANDLER task.) Then the LINE^HANDLER task calls DEALLOCATEIOCB to release the LINE object IOCB that was allocated by TSCODE.
LINE^HANDLER Example, Design Basic Structure of LINE^HANDLER Code Basic Structure of LINE^HANDLER Code A LINE^HANDLER task starts when TSCODE calls the LINE^HANDLER procedure. After any necessary initialization processing, the task runs in a continuous loop, reading from its $RECEIVE-like queue, never doing a RETURN to TSCODE, as shown in Figure 7-4. TSCODE uses a nonpreemptive type of task scheduling so USCODE must voluntarily give up control before TSCODE switches to the next ready task.
Basic Structure of LINE^HANDLER Code LINE^HANDLER Example, Design Figure 7-4. Basic Structure of LINE^HANDLER Code INIT PROCESSING ^READUPDATE (IN^Q^FILE) WHILE (1) DO CASE WAIT^EVENT E^ITC E^CAN E^IOC @IOCB : = ^LISTEN (... Send I/O To Line ^READUPDATE (IN^Q^FILE) E^STOP Find Cancelled IOCB @IOCB : = ^LISTEN (... CALL STOP^TASK Process I/O Completion CALL NOTIFY^IO^ COMPLETION CALL NOTIFY^IO^ COMPLETION Cancel Line Operation Release Line IOCB ^READUPDATE (IN^Q^FILE) VST026.
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 task an E^CAN event, indicating that an intertask request has been marked as canceled. The E^CAN event is detected by this example’s call to WAIT^EVENT. The CANCEL^ITC SUBPROC is then called.
LINE^HANDLER Example, Design LINE^HANDLER Procedure The second parameter is internal^line^no. Each LINE^HANDLER task has exactly one line control block (LCB) associated with it. The value of internal^line^no is an index used to find this task’s LCB in the array of LCBs. This is discussed further in the Inspect exercise later in this section.
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 other threads. When the ^WRITE completes, the IOCB is removed from the queue by incrementing the oldest index. Caution. Although TSCODE handles deallocation of IOCBs for intertask communication completed with NOTIFY^IO^COMPLETION, it will not deallocate LINE IOCBs. If the LINE IOCB is not deallocated, eventually the GDSX process runs out of IOCBs. The default for the maximum number of IOCBs is 128.
LINE^HANDLER Example, Design Other Procedure Declarations A ^CANCEL on a ^WRITEREAD outstanding to the LINE file does not suspend the task and is not completed by an ^AWAITIO. A message is sent with a ^WRITE to indicate what happened to the prompt. In an exercise in Section 6, LINE^HANDLER Example, Running and Managing, an SU was stopped with the SCF ABORT command. The abort message is sent to TSCODE, which then stops the DEVICE^HANDLER task.
LINE^HANDLER Example, Design Inspecting the LINE^HANDLER Example At the TACL terminal, use CLEAR ALL if necessary to clear any previously set parameter values, and then issue commands as given in Section 6, LINE^HANDLER Example, Running and Managing to run a LINE^HANDLER example process: > PARAM MAXLINES 1 > PARAM EXTSUSIZE 1 > RUN GDSE /NAME $GDS, NOWAIT/ Configure a LINE object and three SU objects, and start the LINE: > SCF -> ADD LINE $GDS.#LX, ACCESSNAME $TC1 -> ADD SU $GDS.#LX.T1 -> ADD SU $GDS.#LX.
LINE^HANDLER Example, Design Line Control Blocks Line Control Blocks Now the line control block (LCB) for the LINE file can be examined. An LCB is the internal representation of a LINE and is used to manage a LINE^HANDLER task’s communication with a file. When SCF was used to configure the LINE, TSCODE assigned an LCB to manage the terminal. When the LINE object was started, TSCODE created a LINE^HANDLER task that mapped to the LCB.
LINE^HANDLER Example, Design The IOCB You can display the contents of the LINE^HANDLER’s TCB with the DISPLAY command: - DISPLAY (tcb-address) AS TCB^TEMPLATE Now display the values of the local variables oldest and newest: - DISPLAY OLDEST - DISPLAY NEWEST These are the indexes to the queue of pending ^WRITEREAD IOCBs from DEVICE^HANDLER tasks. Display the contents of this local array: - DISPLAY WT^RD^IOCB^LIST The IOCB Record the IOCB address indicated by oldest (old-iocb).
LINE^HANDLER Example, Design Tracing a ^CANCEL At the TACL terminal, enter SCF and stop the SU whose prompt currently appears on the application terminal: > SCF -> ABORT SU $GDS.#LX.Tn At the Inspect terminal, you should see that the program encountered the breakpoint at the CALL ^CANCEL statement. Display the value of tcb.term (the ITC file number that the DEVICE^HANDLER task uses for intertask communication): - DISPLAY TCB.TERM Resume program execution.
8 Service Routines To help with the development of USCODE routines, the following service routines are supported by TSCODE: • • Utility procedures Pseudo Guardian, TS/MP, Pathway/iTS, and TMF procedures By calling one of these routines a user task transfers control to the TSCODE kernel. TSCODE either carries out the requested processing internally, or passes the procedure call to the operating system, Pathway/iTS, or TMF.
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_HANDLE_FROM_NAME_ GET_PROCESS_HANDLES_CPU_ GET_PROCESS_HANDLES_NODE_ MAKE_PROCESS_HANDLE_NULL_ PROCESS_HANDLE_IS_NULL_ Intertask Communication TSCODE provides a set of procedures to support communication between TSCODE and USCODE, as well as communication among user tasks. These procedures make it possible for a DEVICE^HANDLER task to communicate with a device on a line as if there were no LINE^HANDLER task involved.
Semaphore Control Service Routines Semaphore Control The purpose of a semaphore is to ensure the serial access of a shared resource. A task is considered to have acquired a resource when it owns the semaphore associated with the resource. A unique user-defined semaphore should be established for each resource requiring exclusive access. The following procedures are available for managing semaphores other than the checkpoint semaphore.
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, Using Pseudo Procedures in a TS/MP Environment for an example of using this procedure. A trace record is written after a successful call to ^ABORTTRANSACTION if bit 3 of trace^control^flags in DCCBDECS is set to 1.
ADD^TRACE^DATA Service Routines input type INT:value is the entry type, which indicates the type of data to be copied. The values for type are: 0-127 Reserved for TSCODE events 128-255 Used for USCODE events Except for these restrictions, use of this parameter is completely user-dependent. Whatever value is assigned to type is passed through to the trace records.
ADD^TRACE^DATA^INT Service Routines CALL PUTLOCALPOOL (0, MBUF); END; END; If the global sr^misc^trace flag (which is the same as trace^control^flags[1].<9>, as defined in the common^data section of DCCBDECS), is set to 1 before the preceding code is executed, in addition to the preceding user-defined entries, TSCODE generates a standard trace entry with a type of sr^misc^req whenever a user exit is called. For more information on these globals, see the tables in Tracing GDSX on page 2-80.
^AWAITIO[X] Service Routines Example In this example an IOCB is allocated by USCODE and then deallocated when it is no longer needed. INT .EXT IOCB (IOCB^TEMPLATE); !<- Now an INT .
^AWAITIO[X] Service Routines CALL ^AWAITIO(F2); !Complete write to F2 . . CALL WAIT^EVENT(DISP^IOC); !Wait for F1 write to complete . . If the ^WRITE to file F1 completes before the ^WRITE to F2, TSCODE’s implementation of ^AWAITIO calls WAIT^EVENT(DISP^IOC .. ) and awakens on the resulting IOC event for F1, but, not finding an I/O completion for F2 (by a call to ^LISTEN), will proceed to call WAIT^EVENT(DISP^IOC .. ) again.
^BEGINTRANSACTION Service Routines BEGIN CALL ^FILEINFO (......); IF error = 26 THEN . . ^BEGINTRANSACTION This procedure initiates a new TMF transaction. See Appendix D, Using Pseudo Procedures in a TS/MP Environment for an example of using this procedure. A trace record is written after a successful call to ^BEGINTRANSACTION if bit 3 of trace^control^flags in DCCBDECS is set to 1. The trace records contain the calling task number and the TMF transaction identifier.
BIT^RESET Service Routines returned value index INT:value is the index value for the first available bit (equal to 0) that is in the specified range. input table INT:ref (Use for global memory reference.) INT .EXT:ref (Use for extended memory reference.) is a pointer to the bit map table. input minimum INT:value is the index for the first bit in the range to be tested. This parameter must be greater than or equal to 0.
BIT^SET Service Routines input index INT:value is the index for the bit to be set to 0 (available). The range for this parameter is specified by: 0 <= index < 32, 768. BIT^SET This procedure sets to 1 the ith bit of a bit map table in either global or extended memory. Caution. You must not reset TSCODE-defined map bits. CALL BIT^SET ( table i ,index ); i ! ! input table INT:ref (Use for global memory reference.) INT .EXT:ref (Use for extended memory reference.
BOUNDS^CHECK Service Routines input tbl INT:ref (Use for global memory reference.) INT .EXT:ref (Use for extended memory reference.) is a pointer to the bit map table. input index INT:value is the index for the bit to be tested. The range for this parameter is specified by: 0 <= index < 32, 768. Example See USER^STOP on page 9-23 for an example. BOUNDS^CHECK This procedure ensures a buffer is in global or extended memory, not in the swappable stack.
^CANCELREQ Service Routines Except for the following considerations, the syntax, condition code settings, and considerations regarding this procedure are the same as the counterpart in the Guardian Procedure Calls Reference Manual. Considerations • • ^READUPDATE and ^CANCEL are the only two operations that a LINE^HANDLER can issue against the in-queue file. For information about using ^CANCEL to cancel a ^READUPDATE on a pseudo$RECEIVE file, see the considerations under ^READUPDATE[X] on page 8-61.
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 • • After a takeover, memory pool buffers must be allocated by a call to ^RECLAIMBUFFER. If the checkpoint buffer overflows, the backup process is deleted. To prevent this, ensure that the MAXCPSIZE configuration parameter is large enough. The default size is 4096 words. (For restrictions imposed by MAXCPSIZE and TASKCPSIZE, see MAXCPSIZE on page 2-60 and TASKCPSIZE on page 2-73) ^CLOSE This procedure closes an open file.
DELETE^[X]ITEM Service Routines Except for the following considerations, the syntax, condition code settings, and considerations regarding this procedure are the same as the counterpart in the Guardian Procedure Calls Reference Manual. Considerations • • When called with a time-period parameter value greater than 0, the ^DELAY procedure causes the calling task to be suspended. However, the GDSX process remains active and other tasks can run.
DO^CP Service Routines Considerations • • Because the working stack images of tasks are swapped to and from an extended data segment during I/O operations, I/O must be performed to and from global buffers. If you want USCODE to provide calls to ^AWAITIO[X] in order to wait for I/O completion on ^DEVICEINFO2, ^FILE_GETINFOBYNAME_, and ^PROCESS_CREATE_ service routines, as would be done for typical nowaited Guardian procedure calls, you must set the PROCNOWAIT configuration parameter to 1.
^ENDTRANSACTION Service Routines indicates the outcome of the call. The value of status is one of the following: 0 The checkpoint failed 1 The data queued in checkpoint buffer was successfully checkpointed to the backup process Considerations • • DO^CP causes the calling task to be suspended. If GDSX is run as a process pair, TSCODE automatically calls DO^CP upon the return from the USER^BACKUP user exit so that the primary and backup processes are synchronized at startup.
FAULT Service Routines • • • USER^INIT^CONFIG^PARAMS USER^INITIALIZE USER^VERSION During execution of these five exits, the monitor task, which handles the EMS messages, has not been created. If a task is to be restarted (noretn is equal to 1), TSCODE calls the USER^STOP exit, with the suspended calling task as the current task.
^FILE_CLOSE_ Service Routines The value of noretn is one of the following: 0 The user exit or task is not to be restarted. Control is given back to the calling process. This is the default. 1 The user exit or task is to be restarted. FAULT can be called with the noretn parameter equal to 0 from any user exit or task. input tcb INT .EXT:ref is a pointer containing the calling task’s TCB address. input p-reg INT:value contains the contents of the P register when FAULT is called.
^FILE_GETINFOBYNAME_ Service Routines • If TSCODE is unconverted, then it is recommended that USCODE call ^FILEINFO. When TSCODE is unconverted and USCODE calls ^FILE_GETINFO, the following should be noted regarding the returned information: • • • Filename uses the C-series internal expanded format. Filename-length is always returned with a value of 24. Type-info is returned in a buffer of 5 words of which only the first word is relevant.
^FILEINFO Service Routines ^FILEINFO This procedure obtains error and characteristic information about a file. ^FILEINFO may be called whether USCODE is converted or unconverted. The ^FILE_GETINFO_ procedure provides only a subset of the functions available with ^FILEINFO. Except for the following consideration, the syntax, condition code settings, and considerations regarding this procedure are the same as the counterpart in the Guardian Procedure Calls Reference Manual.
^FILE_OPEN_ Service Routines • ^Open is called in the primary process; hence, it is optional to provide the following parameters: ° ° ° ° primary file_id primary process_id primary block buffer primary block length Caution. When a user task stops, TSCODE automatically closes all of the task’s private opens but leaves public opens open, because other tasks may be using them. • For the purpose of editing input data, it may be desirable to read disk files within GDSX.
^FNAMEEXPAND Service Routines CALL VSEM(DISKSEM); END ELSE BEGIN !UNABLE TO GET THE LOCK .!WITHIN 2 SECONDS . END; ^FNAMEEXPAND This procedure expands a partial file name from the compacted external form to the 12-word internal form usable by other file-system procedures. ^FNAMEEXPAND may be called whether USCODE is converted or unconverted.
GET^CPSEM Service Routines Global data may be checkpointed concurrently with the task’s stack image and memory pool buffers. See the example in the description of the Q^CP[X] on page 8-57. Caution. While a task owns one or more semaphores, it is in an unstoppable state; if the task faults while in this state, the primary GDSX process stops. status := GET^CPSEM returned value status INT:value indicates the outcome of the call.
GETEXTPOOL Service Routines CALL P1; CALL Q^CP(.....); . . IF P2^GOT^CP^SEM THEN BEGIN CALL DO^CP; CALL GIVE^CPSEM; END; END; The procedure that acquires the semaphore is responsible for sending the accumulated checkpoint buffer to the backup. Assume that the caller of P2 does not own the checkpoint semaphore. When P2 is called, the initialization of p2^got^cp^sem thus acquires the semaphore and p2^got^cp^sem is set to 1.
GETEXTPOOL Service Routines the taskpoolsize variable within the USER^INIT^CONFIG^PARAMS user exit. TASKPOOLSIZE specifies the maximum pool size in words that each user task is allowed to acquire privately. TSCODE allocates an extended memory area of total size (TASKPOOLSIZE * 2) multiplied by MAXTASKS bytes for all the private extended pools. The default for TASKPOOLSIZE is 128 words.
GETEXTPOOL Service Routines Considerations • • • No mechanism for queuing of allocation requests or timeout is provided. For private storage such a facility has no purpose because each task has its own individual pool. A call to ^CHECKPOINT(2) checkpoints all local and extended memory pools acquired by the calling task.
GETEXTPOOLX Service Routines WDS := 100; @GLOBAL^SHARED^PTR := GETEXTPOOL(1, WDS); GLOBAL^SHARED^PTR ':=' "+ Let all tasks see this !+"; END; . END; ! of USER^START; PROC DEVICE^HANDLER(.......); INT .EXT WORK^PTR; INT WDS, N; . . @WORK^PTR := @GLOBAL^SHARED^PTR; IF WORK^PTR = "+" THEN !All user tasks can see !this data BEGIN WORK^PTR ':=' " "; !Spaces on first time thru !Allocate a second buffer of 100 words. @TASK^SHARED^PTR := GETEXTPOOL(1, 100); TASK^SHARED^PTR ':=' "5"; . .
GET^ITC^FCB Service Routines is the relative extended address of area allocated, unless space was not available, in which case a zero is returned. input pool INT:value is the pool to allocate space for. The values of pool are as follows: 1 Shared extended pool 2 Private extended pool 10 Extended buffer pool 11 Extended message pool input size INT(32):value indicates the number of words to allocate. Considerations • • • No mechanism for queuing of allocation requests or timeout is provided.
GET^ITC^FCB Service Routines To send an ITC message, the sending task calls SEND^ITC^MSG[X], using the FCB address in that call to identify the receiving task. status := GET^ITC^FCB ( buffer:length i:i ,fcb-address ,[ dcb-address ] ); ! ! o ! o returned value status INT:value indicates the outcome of the call.
GETLOCALPOOL Service Routines Example In this example a task will send ITC messages to TERM1, which was configured with an SU name of $GDSX.#SU00l.TERM0001. The task calls GET^ITC^FCB to obtain the FCB address of TERM1. After it has the FCB address, the task can use SEND^ITC^MSG[X] as many times as necessary to send messages to TERM1. The example shows one instance of sending a message with SEND^ITC^MSGX: @buffer^pointer := GETEXTPOOL(10, 8); buffer^pointer ':=' ["$GDSX.#SU001.
GETLOCALPOOL Service Routines defines which local pool to allocate memory for. The value for pool is one of the following: 0 Local buffer pool 1 Local message pool input size INT:value is the number of words to allocate. input timeout INT(32):value is the maximum number of ticks (10 ms) to wait for space to be allocated. If this parameter is omitted, the calling task waits the number of ticks defined by the BUFFERTIMEOUT configuration parameter.
GET_PROCESS_HANDLE_FROM_NAME_ Service Routines STRING .BUFS; !String pointer ! Note that a string pointer will ! not work for the ! message pool (pool 1) STRUCT .STRCT(SOME^STRUCT) = BUF; ! Point user structure to ! address returned. . . TICKS := 300; ! Wait maximum of 3 seconds. @BUF := GETLOCALPOOL(0, BUFSZ, TICKS); ! Get local buffer ! pool address ! (lower data stack). IF @BUF = 0 THEN BEGIN ! do error handling END; @BUFS := @BUF '<<' 1; ! Initialize string pointer. .
GET_PROCESS_HANDLES_CPU_ Service Routines GET_PROCESS_HANDLES_CPU_ This procedure returns the CPU number of a process handle. cpu := GET_PROCESS_HANDLES_CPU_ ( processhandle ); i ! returned value cpu INT:value indicates the outcome of the operation. If a valid CPU number is found in the process handle, the number is returned in cpu, otherwise -1 is returned. processhandle input INT .EXT:ref:10 is a pointer to a process handle.
GIVEBREAK Service Routines name-length returned value INT:value is the length in bytes of the SCF object name. If the SU or LINE is unconverted, the value returned is always 24 bytes. If SU or LINE is converted, the value returned is always the length of the object name, with a maximum of 32 bytes. input tcb INT .EXT:ref is a pointer to a task’s TCB. The TCB pool can be scanned for the TCB addresses. See the example for the TCBADDR on page 8-81.
INIT^[X]LIST Service Routines is released by means of GIVE^CPSEM. This procedure allows a task to release the checkpoint semaphore. Caution. After checkpointing data to the backup process, the task owning the checkpoint semaphore must call GIVE^CPSEM to release the semaphore or else the checkpointing facilities will be locked up. CALL GIVE^CPSEM Consideration Use the SCF STATS command to see if any tasks are waiting for resources.
INIT^SEM Service Routines INIT^SEM PSEM VSEM The checkpoint semaphore is defined by TSCODE and managed with the GET^CPSEM and GIVE^CPSEM procedures. A semaphore is first initialized with INIT^SEM. The semaphore can be defined in global or extended memory; however, it is recommended that it is declared in global memory, within a user private block, for example. If a backup GDSX process exists, the semaphore must be initialized in both primary and backup GDSX processes.
INIT^XLIST Service Routines Examples 1. This example defines a semaphore my^resource in extended memory: INT(32) .EXT MY^RESOURCE (SEM^TEMPLATE); . !pointer to an extended memory area @MY^RESOURCE := GETEXTPOOL(10,6) MY^RESOURCE.SEMOWNER := MY^RESOURCE.SEMHEAD := MY^RESOURCE.SEMTAIL := 0D; CALL INIT^SEM (MY^RESOURCE); !Initialize semaphore structure which exists in !local or extended memory . . IF got^resource^sem := PSEM( MY^RESOURCE, 600 ) THEN !Attempt to acquire the semaphore was successful . .
ITC^OPENX Service Routines To make an item addressed by address2 the last item on the list, address1 should specify the second occurrence of the array that specifies the list header (list^header[1], which contains the address of the last item on the list). input address2 INT:value (Use with INSERT^ITEM.) INT(32):value (Use with INSERT^XITEM.) is the address of the element to be added to the list.
^LISTEN Service Routines Example The TCB address specified by tcb-address can be obtained by declaring and initializing code in your user task as shown in the following example. Once the task has an ITC file number, it uses ^READUPDATE to check for incoming ITC messages. PROC DEVICE^HANDLER (term^file^num, internal^term^no, term^type); INT .EXT my^dcb (dcb^template) := 0D; INT .EXT my^tcb (tcb^template) := 0D; INT itc^filenumber := 0D; . . @my^dcb := dcbtbl[internal^term^no]; @my^tcb := my^dcb.
^LISTEN Service Routines indicates where ^LISTEN is to look for completed I/O operations. The value of i-o-message is one of the following: -1 ^LISTEN looks for all I/Os except intertask requests and messages from $RECEIVE 0 ^LISTEN looks for intertask requests or messages from $RECEIVE Positive Number The file number where ^LISTEN is to look for completed I/Os input itc-flag INT:value indicates if ^LISTEN is to look for ITC requests.
^LISTEN Service Routines • For a message from $RECEIVE (message-flag is a nonzero value) the IOCB is as follows: iocb.syncid Sync ID of request iocb.state 5 = I/O pending iocb.optype 12 = ^READUPDATE operation iocb.iocnt Length of request in bytes iocb.cnt Maximum reply size iocb.bufaddrx Buffer address where request resides. This will be a buffer parameter to ^READUPDATE(0,..) or GDSX supplied buffer, if the buffer parameter was omitted. iocb.histag Nowait tag from call to ^READUPDATE(0...
^LOCKREC Service Routines • For an intertask message (itc-flag is a nonzero value) the IOCB is as follows: iocb.state 6 = I/O active iocb.optype Type of operation: 1 = CONTROL 2 = SETMODE 3 = WRITE 4 = READ 5 = WRITEREAD iocb.histag DEVICE^HANDLER’s nowait tag iocb.tcbaddr Address of DEVICE^HANDLER’s TCB iocb.file User task’s pseudo-file number iocb.openid Open ID assigned by USER^START If the operation is a CONTROL: iocb.control^op CONTROL operation (operation) iocb.
^MYTERM Service Routines processhandle output INT .EXT:ref:10 is a pointer to the buffer to be set to the value of a null process handle (-1 in each word). ^MYTERM This procedure provides a task with the object name of its corresponding SU or LINE. Use the GET^TASK^NAME procedure to get the object name of another task’s SU or LINE. To get the name of the home terminal for the GDSX process, call the Guardian MYTERM procedure. MYTERM does not suspend the calling task.
NOTIFY^IO^COMPLETION[X] Service Routines supported ^NEWPROCESS procedure rather than the Guardian NEWPROCESS allows GDSX to maintain a table (PCBTBL) of processes for which it is the creator. By means of this table, stop or abend system messages received by TSCODE can be routed to the task that created the process being stopped. If USCODE is converted, TSCODE tracks its created processes with process handles, and so USCODE tasks cannot call this procedure.
NOTIFY^IO^COMPLETION[X] Service Routines linked into the associated LINE^HANDLER task’s ITC request queue (addressed externally by in^queue^file^num). The intertask I/O initiation is completed by causing a LINE^HANDLER E^ITC event, assuming that the LINE^HANDLER task has a current ^READUPDATE on its ITC file. After the LINE^HANDLER task’s call to WAIT^EVENT returns E^ITC, the task calls ^LISTEN (0,0,1). ^LISTEN looks at the task’s ITC request queue.
^OPEN Service Routines ^OPEN By calling the ^OPEN procedure, one task can establish a communication path between all user tasks and a file. ^OPEN may be called whether USCODE is converted or unconverted. Except for the following considerations, the syntax, condition code settings, and considerations regarding this procedure are the same as the OPEN procedure in the Guardian Procedure Calls Reference Manual.
^PROCESS_CREATE_ Service Routines BEGIN DISKNAME ':=' ["$XYZ SOME FILE CALL ^OPEN(DISKNAME, DISKFILE, ...); IF < THEN BEGIN . produce suitable error message . CALL ^TERMINATE;!Stop GDSX process END; END; "]; END; ^PROCESS_CREATE_ This procedure creates a new process in a waited or nowait manner, and, optionally, assigns a symbolic process name to it.
PROCESS_HANDLE_IS_NULL_ Service Routines • • If a USCODE task calls ^PROCESS_CREATE_ to create a new process when the number of existing processes is equal to the number defined by the MAXPROCESSES configuration parameter, a new process is not created. Filesystem error 34 is returned from ^PROCESS_CREATE_. If a USCODE task calls ^PROCESS_CREATE_, and the created process stops, abends, or is lost due to a CPU failure, TSCODE receives a process deletion system message (type -101).
PSEM Service Routines Except for the following consideration, the syntax, condition code settings, and considerations regarding this procedure are the same as given for the Guardian procedure in the Guardian Procedure Calls Reference Manual. Consideration The PROCESS_STOP_ procedure prohibits an attempt by USCODE to stop the GDSX process within which the task is running. PSEM The PSEM procedure acquires a semaphore associated with a shared resource. PSEM is not used to acquire a checkpoint semaphore.
PUTEXTPOOL Service Routines input semaphore INT:ref (Semaphore in global memory) INT(32) .EXT:ref (Pointer to semaphore in extended memory) is a pointer to the semaphore to be acquired. input time INT(32):value specifies the maximum number of ticks (10 ms units) to wait to obtain the semaphore. If this parameter is omitted, the task waits indefinitely. Consideration A task calling this procedure may be suspended.
PUTLOCALPOOL Service Routines Example INT .EXT PTR; . . @PTR := GETEXTPOOL(N, WDS); . . CALL PUTEXTPOOL(N, @PTR); . PUTLOCALPOOL This procedure deallocates space obtained from any of the two local memory pools by a call to GETLOCALPOOL. For more information, see Memory Pools on page 2-24. CALL PUTLOCALPOOL ( pool i ,buffer ); i ! ! input pool INT:value indicates which local pool to deallocate space for.
Q^CP[X] Service Routines The Q^CP procedure moves global data within a user’s named or private global data block to the checkpoint buffer located in extended memory. The Q^CPX procedure moves extended memory data to the checkpoint buffer. Up to four data areas can be moved to the checkpoint buffer with a single call to Q^CP[X]. Multiple calls to Q^CP[X] can be done before calling DO^CP or ^CHECKPOINT.
Q^CP[X] Service Routines input datai INT:ref (Use with Q^CP.) INT .EXT:ref (Use with Q^CPX.) is a pointer containing a word address where data copying should begin. input bytesi INT:value is the length in words of the data to be copied, starting at datai. Consideration Q^CPX may be used to queue an area in extended memory. However, USCODE seldom needs to use this procedure because ^CHECKPOINT (2) checkpoints all extended memory acquired. Examples 1.
Q^CP[X] Service Routines GOTSEM := PSEM(SEM); ! PREVIOUSLY INITIALIZED ! IN USER^INITIALIZE CALL ^FILE_OPEN ( DISK^NAME, FILE^NUM, flags); IF <> THEN BEGIN . .
^READ[X] Service Routines BEGIN I^GOT^CP^SEM := 0; . Do takeover Processing . END ELSE IF I^GOT^CP^SEM THEN BEGIN CALL GIVE^CPSEM; I^GOT^CP^SEM := 0; END; ^READ[X] The ^READ and ^READX procedures return data from an open file to the application process’s data area. Because the working stack images of tasks are swapped to and from an extended data segment during I/O operations, I/O must be performed to and from global buffers.
^READUPDATE[X] Service Routines • • • ^READUPDATE[X] and ^CANCEL are the only two operations that a LINE^HANDLER may call against the pseudo-$RECEIVE file. ^REPLY[X] should be called after ^READUPDATE[X] to release the IOCB used by ^READUPDATE[X]. To minimize buffer requirements, ^READUPDATE[X] operations can be posted on the pseudo-$RECEIVE without specifying a buffer address or size.
^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 ^FILE_GETRECEIVEINFO_. If USCODE is converted and a user task calls this procedure, a warning is returned via EMS and the process id returned is invalid. If sysmsgs^flag of the CONTROLFLAGS configuration parameter is set to 1 and you call ^RECEIVEINFO after a close message is received, the file number returned is always 0. With the use of the iotype parameter, it is possible for USCODE to differentiate between READ, WRITE, and WRITEREAD operations from the application.
^RECLAIMBUFFER Service Routines on input, is a pointer to a buffer that you specify is to be reallocated after a takeover. For extended memory buffers, the address of the pointer must be passed, for example, @BUF. For local buffers, pass the buffer address as converted by the TAL procedure $XADR. See the examples later in this subsection. On return from ^RECLAIMBUFFER this pointer will contain a new address pointing to the buffer reallocated from the specified memory pool in the new primary process.
^REPLY[X] Service Routines IF <> THEN ! Did not find it, we're in trouble. BEGIN . . 2. In this example buffer pool and message pool buffers are reclaimed: INT .BUFF1, .BUFF2; INT .EXT XBUFF1, .EXT XBUFF2; @BUFF1 := GETLOCALPOOL(0, 100); @XBUFF1 := $XADR(BUFF1); @BUFF2 := GETLOCALPOOL(1, 100); @XBUFF2 := $XADR(BUFF2); . IF ^CHECKPOINT(2) THEN BEGIN CALL ^RECLAIMBUFFER(@XBUFF1, 0); !buffer pool IF <> THEN ! Did not find it, we're in trouble. BEGIN . .
^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 Consideration Because GDSX does not support multithreaded user tasks that use TMF, ^RESUMETRANSACTION cannot be used to switch back and forth between different transactions within one user task.
SEND^ITC^MSG[X] Service Routines is a pointer to an FCB corresponding to the calling task’s ITC file or to some other file to which the I/O is to be linked. At the time of call, this FCB must contain the TCB address for the receiving task in fcb.lhaddr. When a DEVICE^HANDLER task is sending a message to a LINE^HANDLER task that it is configured for, obtain the FCB address for the DEVICE^HANDLER task’s ITC file by indexing into FCBTBL, the FCB table, with the terminal file number.
SEND^ITC^MSG[X] Service Routines input op-code INT:value is the operation to perform.
^SERVERCLASS_DIALOG_ABORT_ Service Routines ^SERVERCLASS_DIALOG_ABORT_ The ^SERVERCLASS_DIALOG_ABORT_ pseudo context-sensitive Pathway procedure allows USCODE to abort a specified dialog. The syntax, condition code settings, and considerations regarding this procedure are the same as given for the Pathway SERVERCLASS_DIALOG_ABORT_ procedure in the NonStop TS/MP Pathsend and Server Programming Manual.
^SERVERCLASS_DIALOG_END_ Service Routines ^SERVERCLASS_DIALOG_END_ The ^SERVERCLASS_DIALOG_END_ pseudo context-sensitive Pathway procedure allows USCODE to end a dialog initiated by a previous call to the ^SERVERCLASS_DIALOG_BEGIN_ procedure. The syntax, condition code settings, and considerations regarding this procedure are the same as given for the Pathway SERVERCLASS_DIALOG_END_ procedure in the NonStop TS/MP Pathsend and Server Programming Manual.
^SERVERCLASS_SEND_ Service Routines server class name, buffer, server class send operation number and the dialog ID used with this procedure. ^SERVERCLASS_SEND_ This procedure allows USCODE to communicate directly with TS/MP server classes through LINKMON. See Appendix D, Using Pseudo Procedures in a TS/MP Environment for an example of using this procedure.
^SERVERCLASS_SEND_INFO_ Service Routines records contain the calling task number, PATHMON process name, server class name, buffer, and server class send operation number used with this procedure. See Tracing GDSX on page 2-80 for more information. ^SERVERCLASS_SEND_INFO_ This procedure allows USCODE to retrieve information about the last initiated or completed call to ^SERVERCLASS_SEND_INFO_ directly from TS/MP server classes.
^SETMYTERM Service Routines Considerations • • • • Because the working stack images of tasks are swapped to and from an extended data segment during I/O operations, I/O must be performed to and from global buffers. Some applications may require the monitoring of 3270 device status by a call to ^SETMODENOWAIT with function code 53. In this case, the param2 parameter is not passed on to AM3270. Instead, TSCODE passes the task number of the caller.
^SETPARAM Service Routines input length INT:value (Use when the task is converted) is the length in bytes of the SCF object name to be set. If the task is converted, the 16-word buffer must contain a name in external format. If the name is less than 32 characters, the remaining buffer space must be filled with spaces. If the task is unconverted, this parameter is not supplied. The length of the object name is always assumed to be 24 bytes.
^SIGNALINTERRUPT Service Routines external openers. You can issue SCF commands against GDSX during and after the shutdown process. CALL ^SHUTDOWN Considerations • When ^SHUTDOWN is called, all active LINEs and SUs are queried to determine whether they have external openers. If no external openers exist, then the primary and backup GDSX processes are stopped and an EMS event message is generated indicating that a shutdown occurred.
^SIGNALTIMEOUT Service Routines Considerations • • • • Because the working stack images of tasks are swapped to and from an extended data segment during I/O operations, I/O must be performed to and from global buffers. The tag parameter of ^SIGNALINTERRUPT holds the address of the IOCB allocated when ^SIGNALTIMEOUT or ^SIGNALINTERRUPT was called. It is an INT(32) variable. ^SIGNALINTERRUPT sets CCL if an IOCB cannot be allocated.
^SIGNALTIMEOUT Service Routines Considerations • • • • Because the working stack images of tasks are swapped to and from an extended data segment during I/O operations, I/O must be performed to and from global buffers. The tag parameter of ^SIGNALTIMEOUT holds the address of the IOCB allocated when ^SIGNALTIMEOUT or ^SIGNALINTERRUPT was called. It is an INT(32) variable. ^SIGNALTIMEOUT sets CCL if an IOCB cannot be allocated.
STOP^TASK Service Routines 2. This example uses WAIT^EVENT to handle a timeout: CALL ^READUPDATE ( 0 ); IF <> THEN CALL DEBUG; ! DO ERROR HANDLING CALL ^SIGNALTIMEOUT ( 100D, , , IOCBADDR); IF < THEN BEGIN ! NO IOCB AVAILABLE END ELSE IF > THEN BEGIN ! CODING BUG: TIMEOUT PARAMETER ILLEGAL END; ! WAIT FOR ALL EVENT TYPES FOR 500 TICKS EVENT := WAIT^EVENT ( -1, 500D ); ! ONLY LISTEN FOR $RECEIVE-TYPE REQUESTS @LOCAL^IOCB := ^LISTEN ( 1, 0, 0 ); @WAIT^BUFFER := LOCAL^IOCB.
TCBADDR Service Routines When a task owns break and a break occurs, the -20 system message is routed to that task by the pseudo-$RECEIVE file. It is the responsibility of the task to issue ^SETMODENOWAITs to restore the terminal to break access or normal access. The Guardian break facility does not allow multiple openers in the same process to pass break ownership back and forth. Therefore, only one task at a time within a GDSX process may own break for a particular terminal.
^TERMINATE Service Routines is the TCB number of a task, a value from 1 through the value of MAXTASKS. Tasks 0 and 1 are always the monitor and listener system tasks. Note. Specifying a task-number value less than 1 or greater than the value of MAXTASKS causes the current task to fault with an EMS message. Example This code may be used to scan the TCB pool: t1 := 2; !We start at 2 because tcb[0] & tcb[1] are always !system tasks WHILE (t1 <= MAXTSKS) do BEGIN tcb^addr := TCBADDR(t1); .
^UNLOCKREC Service Routines ^UNLOCKREC This procedure unlocks a record currently locked by the task. The syntax, condition code settings, and considerations regarding this procedure are the same as the counterpart in the Guardian Procedure Calls Reference Manual. USER^CLOSE^TRACE^FILE This procedure causes TSCODE to close the trace file in extended memory.
VSEM Service Routines indicates the outcome of the call. The value of status is one of the following: -1 The trace file could not be opened 0 Successful open 1 The trace file is already open record-size input INT:value specifies the maximum size of each record added to the trace file. The default is 256 words and the maximum is 16,383 words. segment-size input INT:value specifies the number of extent pages. Segment-size must be less than or equal to 64. The default is 64.
WAITED^IO[X] Service Routines input semaphore INT:ref (Semaphore in global memory) INT(32) .EXT:ref (Pointer to semaphore in extended memory) is a pointer to the semaphore to be released. WAITED^IO[X] The WAITED^IO and WAITED^IOX procedures perform a waited I/O, even if there are other I/O operations outstanding. Note. This operation is waited only from the perspective of the calling task—it is not a waited I/O from the perspective of the GDSX process.
WAIT^EVENT Service Routines specifies the number of bytes to write. input readcount INT:value specifies the number of bytes to read. output countxfered INT:ref (use with WAITED^IO.) INT .EXT:ref (use with WAITED^IOX.) is a pointer to the number of bytes transferred. The number of bytes is passed by AWAITIO[X], which is used to implement this procedure. input timeout INT(32):value specifies the number of ticks (10 ms) to wait for the I/O to complete.
WAIT^EVENT Service Routines The event descriptions and the global literals (declared in DCCBDECS(ERRORS)) used by TSCODE to define the events are listed in Table 8-2 on page 8-87. Events having an IOCB associated with them are marked in the fourth column of the table. Table 8-2.
WAIT^EVENT Service Routines input mask INT:value is a bit mask specifying those events to be detected.
WAKE^TASK Service Routines input timeout INT(32):value specifies the number of ticks (10 ms) to wait for any masked event to complete, after which the E^TIMEOUT event is returned. The value of timeout is one of the following: -1D Task waits indefinitely -2D Task waits the time remaining from the previous call to WAIT^EVENT Consideration This procedure suspends the calling task.
^WRITE[X] Service Routines Literal Constant Associate d IOCB E^IMSG 4 X Intertask message arrived E^ITC 5 X Completion of I/O other than $RECEIVE and intertask message E^IOC 6 X Resource is available E^RESOURCE 7 Device added, deleted, altered, started, or stopped E^CHANGE 8 Event Description Literal Identifier Message arrived from $RECEIVE Events with corresponding constant values from 9-15 can also be defined by you, and caused for a task with this procedure.
WRITE^ITC^MESSAGE[X] Service Routines If the receiving task is a LINE^HANDLER task, it detects the message by a call to WAIT^EVENT, which returns E^IMSG. A call to ^LISTEN(1, 0, 0) returns the IOCB address. After the message is processed, a call to DEALLOCATEIOCB releases the IOCB. If the receiving task is a DEVICE^HANDLER task, the message is picked up either with a call to ^AWAITIO[X], or with a call to WAIT^EVENT, as described previously.
^WRITEREAD[X] Service Routines @BUF := GETLOCALPOOL(0, SIZE); !Get a buffer. I := 2; ! TCB #0 and #1 are always the monitor and listener ! tasks, so we start at I=2. @MY^DCB := DCBTBL[INTERNAL^TERM^NO]; @MY^TCB := MY^DCB.TCBADDR; ! MAXTSKS is a GLOBAL configuration parameter. WHILE @DEST^TCB := TCBADDR(I) <= MAXTSKS DO BEGIN IF @DEST^TCB <> @MY^TCB THEN ! We only want to send ! a buffer to user tasks other ! than ourself BEGIN !SEE DCCBDECS file for DEFINES IF DEST^TCB.STATE.ACTIVE^BIT AND DEST^TCB.STATE.
^WRITEUPDATEUNLOCK[X] Service Routines ^WRITEUPDATEUNLOCK[X] The ^WRITEUPDATEUNLOCK and ^WRITEUPDATEUNLOCKX procedures perform random processing of records in the disk file. The syntax, condition code settings, and considerations regarding these two procedures are the same as the counterparts in the Guardian Procedure Calls Reference Manual. Consideration • If the file number is in the ITC range, the ^WRITEUPDATEUNLOCK[X] request is routed to an associate task by calling the SEND^ITC^MSG[X] procedure.
Service Routines ^WRITEUPDATEUNLOCK[X] Extended General Device Support (GDSX) Manual—529931-001 8- 94
9 User Exit Descriptions User exits are the USCODE procedures that are called by TSCODE to allow you to customize a GDSX process. All GDSX applications need a DEVICE^HANDLER procedure to provide the application-specific logic. You include stubs, such as those provided in the USKEL file of the installed subvolume, for all user exits that are not customized.
DEVICE^HANDLER User Exit Descriptions DEVICE^HANDLER This procedure is typically used to modify the communication of each thread between a requester and another file (often a terminal). Running copies of DEVICE^HANDLER code are called DEVICE^HANDLER tasks. A DEVICE^HANDLER task is created by a call to the DEVICE^HANDLER procedure as follows: 1.
LINE^HANDLER User Exit Descriptions terminal-type input INT:value is the terminal type, which may be used to inform the task of the type of terminal it is to support or the subset of DEVICE^HANDLER code that the task is to execute. Use of terminal-type is completely application-dependent. TSCODE does not use this variable. The value passed by TSCODE is zero, unless the file to be handled is preconfigured by an SCF ADD and/or ALTER command with an SUTYPE attribute specified as a different type.
LINE^HANDLER User Exit Descriptions number, TSCODE pseudo procedures redirect the I/O operations to the in-queue file for the associated LINE^HANDLER task. A DEVICE^HANDLER task never needs to know the receive-number. All I/O with the IOP controlling a LINE is identified by filenum. PROC LINE^HANDLER ( filenum i ,internal-number i ,receive-number ); i ! ! ! input filenumr INT:value is the Guardian file number for the file managed by this LINE^HANDLER task.
PROCESS^ASSIGNS User Exit Descriptions PROCESS^ASSIGNS This routine processes ASSIGN messages sent to GDSX at process startup time, giving you the chance to retrieve information from external ASSIGN commands issued from the TACL prompt. TSCODE calls this procedure once for each ASSIGN message in effect at startup time. If there are no ASSIGN messages in effect, it is not called. The ASSIGN message structure is presented in the Guardian Programmer’s Guide.
PROCESS^USER^PARAMS User Exit Descriptions A PARAM message received by TSCODE contains a parameter string that is scanned for configuration parameters. During the scan, each time TSCODE encounters a parameter name that begins with “USERPARAM,” PROCESS^USER^PARAMS is called with a pointer to the parameter string byte that indicates the length of the parameter name. If “USERPARAM” is not encountered when TSCODE scans a PARAM message, PROCESS^USER^PARAMS is not called.
USER^ATTRIBUTES User Exit Descriptions • The TSCODE-supported FAULT procedure may not be called from this exit, because the monitor task, which handles the EMS messages, does not exist when this exit is executing. Example Suppose the following command is entered at a TACL prompt before GDSX is started: > PARAM USERPARAMCODE4 44600HW where the user parameter name is “CODE4” and its value is 44600HW. When TSCODE scans the parameter string and finds “USERPARAM,” PROCESS^USER^PARAMS is called.
USER^ATTRIBUTES User Exit Descriptions USER^ATTRIBUTES is impossible, because at that point memory for the DCBs has already been allocated. Also, because SCF messages are picked up only after this allocation is complete, changing EXTSUSIZE by means of SCF is impossible. See the SCF Reference Manual for GDSX for more information on these attributes.
USER^ATTRIBUTES User Exit Descriptions input token-code INT(32):value is the SCF token code. The value of token-code is one of the following: 150929409 ADD SU command 150929411 ALTER SU command token-value input INT:ref is a pointer to a STRUCT containing attribute values. When this USER^ATTRIBUTES is called by TSCODE, attribute variables in this STRUCT contain spaces unless they have been set by means of an SCF ADD or ALTER command (spaces in INT variables will equal 8224).
USER^BACKUP User Exit Descriptions END; END; INT Z^EXT^SU^SIZE; ! NOT USER MODIFIABLE INT Z^ASSOC; INT Z^AUTOSTOP; INT Z^NOWAIT^DEPTH; INT Z^SUTYPE; INT Z^USER^DATA[0:127]; END; USER^BACKUP USER^BACKUP allows you to checkpoint global data that is required for successful takeover in the event of failure.
USER^BACKUP User Exit Descriptions • Pseudo procedures may be called from this procedure. Example Here is an example of USER^BACKUP code that checkpoints data input at a terminal. Obtaining the checkpoint semaphore is not necessary, because TSCODE is not checkpointing and no user task exists. Also, calling DO^CP is not necessary, because after exiting USER^BACKUP a DO^CP is done automatically by the backup task. BLOCK USER^PRIVATE; INT AREA[0:11]; END BLOCK; .
USER^COMMANDS User Exit Descriptions ! USER^BACKUP a DO^CP is done automatically by backup task. CALL PUTLOCALPOOL (0,buffer); END; USER^COMMANDS This procedure is called from the monitor task when it receives an SPI command with an unrecognized token from a TACL process or from an external management application other than SCF. This procedure provides a way for you to define your own SPI commands.
USER^COMMANDS User Exit Descriptions Considerations • • • • • • The TSCODE-supported FAULT procedure should only be called from the USER^COMMANDS exit with its noretn parameter equal to 0. See the description of the FAULT procedure in FAULT on page 8-22. USER^COMMANDS is an integer function called only by TSCODE, never by USCODE. USCODE returns function values to TSCODE with the TAL RETURN statement. The permissible returned function values are described under the status variable above.
USER^COMMANDS User Exit Descriptions At a second terminal, called $TERM2 in this example, start a GDSX process using RUND and set a breakpoint at #USER^COMMANDS to view incoming TACL SPI messages. > RUND GDSE /NAME $UGDS, NOWAIT/ INSPECT - Symbolic Debugger - T9673C20 - (10JUL89) Copyright Tandem Computers Incorporated 1983, 1985-1989 INSPECT 077,06,124 $UGDS #GDS.#1366(SMAIN) - $UGDS-B #USER^COMMANDS - $UGDS-SOURCEON - $UGDS-RESUME > PAUSE At $TERM1, run the TACL routine TELLGDS.
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 early in the GDSX initialization process. Buffer pools and task and file management structures have not been initialized. Consequently, within these exits TSCODE-supported service procedures should not be called, except for the following: BIT^MAP INIT[X]LIST BIT^RESET INIT^SEM BIT^SET ^SHUTDOWN BIT^TEST ^TERMINATE Wait until USER^INITIALIZE to call other service routines.
USER^REPLIES User Exit Descriptions returned value status INT:value is the returned value. The value of status is generated by a TAL RETURN statement in USCODE and can be one of the following: 0 Everything is all right SCF error number Error occurred scf-command input INT:value is the SCF command number. The value of scf-command is one of the following: 3 An INFO request 7 A STATS request scf-object-type input INT:value is the SCF object type number.
USER^START User Exit Descriptions statement. The permissible returned function values are described under the status variable above. • • USER^REPLIES is called from the monitor task. Users should modify the I/O buffer pointed to by scf-buffer only with DSM procedures (SSPUT, SSGET, and so on). See the SPI Programming Manual.
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 • A call to the TSCODE STOP^TASK procedure is made from USCODE or TSCODE. USER^STOP allows you to handle housekeeping for associated files before TSCODE closes them. PROC USER^STOP ( tcb ); i ! input tcb INT .EXT:ref is a pointer to the TCB for the task being stopped. Considerations • If your GDSX process is configured with a LINE, the USER^STOP procedure must be able to handle the termination of the LINE and the SUs under the LINE.
USER^TAKEOVER User Exit Descriptions ! MAXTERMS is a global configuration parameter WHILE (DEV := DEV + 1) <= MAXTERMS DO IF BIT^TEST (CUR^LINE.CMAP, DEV) THEN BEGIN @DCB := DCBTBL[DEV]; ! Configured device . ! under this current . ! L^H task. END; DROP DEV; All active terminals under LINE X can be scanned with the same code, except that CMAP is replaced by AMAP. • • The TSCODE-supported FAULT procedure should only be called from the USER^STOP exit with its noretn parameter equal to 0.
USER^VERSION User Exit Descriptions USER^VERSION This procedure returns a user code version date to TSCODE. status := PROC USER^VERSION ( string ); i ! returned value status INT:value is the returned value. The value of status is generated by a TAL RETURN statement in USCODE and is one of the following: 0 A version date is not provided 1 A version date is provided input string STRING:ref:6 is the pointer to the six-byte user code version string.
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 Requester Listing APPLS Listing CALL READUPDATE(RCV^FILE,STARTUP^MSG,2*BUF^WDS,CT^RD); IF <> THEN CALL DEBUG; CALL REPLY(,,,,0); IF <> THEN CALL DEBUG; CALL OPEN(STARTUP^MSG[OUTFILE],MSG^FILE,0); ! WAITED I/O IF <> THEN BEGIN CALL FILEINFO(-1,FERR); CALL DEBUG; END; WHILE (-1) DO BEGIN PID := MYPID; CPU := PID.<4:7>; PIN := PID.
APPLS Requester Listing WT^CT :=28; S^MSG^BUF ':=' 8*[" "] & ["PLEASE RE-ENTER DATA"]; CALL WRITE(MSG^FILE,MSG^BUF,WT^CT); IF <> THEN BEGIN ! CONTINUE ON GDSX SWITCHOVER CALL FILEINFO(MSG^FILE,FERR); IF (FERR <> 210) THEN CALL DEBUG; END; END ELSE ! OTHER ERROR CONDITION CALL DEBUG; CALL DELAY(200D); END; END; Extended General Device Support (GDSX) Manual—529931-001 A- 3 APPLS Listing
APPLS Requester Listing Extended General Device Support (GDSX) Manual—529931-001 A- 4 APPLS Listing
B USKELEX and USKELEXC Listings Included in this appendix are listings of the USKELEX and USKELEXC example programs. USKELEX is the program used in the tutorial in Section 4, DEVICE^HANDLER Example, Running and Managing through Section 7, LINE^HANDLER Example, Design. USKELEX is an unconverted program, not using any of the extended features of D-series systems, and runs only at a low PIN. The USKELEXC program shows the result of converting the USKELEX application to take advantage of D-series enhancements.
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 SUBPROC SCAN^BUF; BEGIN INT I; STRING LEFT^HALF; @S^TERM^BUF := @TERM^BUF; @S^RCV^BUF := @RCV^BUF; ! ! ! ! ! THIS PROCEDURE PERFORMS DATASTREAM CONVERSION, CHANGING LOWERCASE CHARACTERS TO UPPERCASE. IT IS CALLED ONLY FOR OUTBOUND (TO IOP) REQUESTS. FOR I := 0 TO (RQSTR^WT^CT - 1) DO BEGIN LEFT^HALF := S^RCV^BUF[I].
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 BEG
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 !dxcd ELSE !dxcd CALL ^FILEINFO(TERM^FILE^NUM,FERR); CALL ^REPLYX(,,,,FERR); END; END; !CASE CALL PUTEXTPOOL(10,@TERM^BUF); CALL PUTEXTPOOL(10,@RCV^BUF); END; END; !WHILE !PROC !=========================================================================== ?PAGE "PROC LINE HANDLER" !=========================================================================== PROC LINE^HANDLER (LINE^FILE^NUM, INTERNAL^LINE^NO, IN^QUEUE^FILE^NUM); INT LINE^FILE^NUM, INTERNAL^LI
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 version 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 !20! Receive^Depth Recvsize Sg^Security Task^Pool^Size Task^Size Term^Data Auto^Restart^Time User^Flags TMF^Flag, Buffer^Timeout, !30! Ctrl26, Auto^Stop, Max^Itc, Device^Info, Server^Flg, Maximum^Links, User^Start^Su, D^Series^Error, Procedure^Nowait, Segment^Number, Rfe^01, Rfe^02; Int(32) MaxTCBpool^Size MaxIOCBpool^Size MaxRCVpool^Size MaxRCBpool^Size MaxDCBpool^Size MaxLDCBpool^Size MaxLINEpool^Size MaxPCBpool^Size MaxFCBpool^size MaxBUFpool^Size MaxMS
DCCBDECS Listing DCCBDECS and ULHDECSE Listings Logstatus Log^Enabled = Config^Params.Log^Status = Config^Params.Log^Status.<15> #, #, Looptime Tracerecsize Maxfiles Maxiocbs Maxlines Maxopens Maxprocesses Maxtsk Maxterms Max^Cp^Wds Poolsize Receivedepth Recvsz = = = = = = = = = = = = = Config^Params.Loop^Time #, Config^Params.Trace^Rec^Size #, Config^Params.Maximum^Files #, Config^Params.Maximum^Iocbs #, Config^Params.Maximum^Lines #, Config^Params.Maximum^Opens #, Config^Params.
DCCBDECS Listing DCCBDECS and ULHDECSE Listings Wait^Result, Lreg; Int(32) Link[0:1], Wakeup; Int Waitsz; Int Trap^S Filerr, Deverror, Pserror, Rcverror; Int(32) Iocbh, Iocbt; Int Rcvsz; Int(32) Rcvbuf, Rcvtag, Lastrcviocb, Qh, Qt, Int Itcqh, Itcqt; Faultno, Stackoffset; = Waitsz, !the task is frozen. !Event which awoke us !The value of the 'L' register when !the task gave up control. !These two words are used to link !together TCBs for tasks performing !timed operations.
DCCBDECS Listing DCCBDECS and ULHDECSE Listings !last call to ^CHECKPOINT. !<13:15> ! Type of last ^CHECKPOINT by task ! 0 = No current checkpoint ! 1 = Stack checkpoint ! 2 = Stack & Buffer checkpoint !<12> ! Tfilesync at last checkpoint !Transtag at last checkpoint !Size in words of data at tcb.buffers !Task to receive Notification if this !task dies.
DCCBDECS Listing DCCBDECS and ULHDECSE Listings Monitor^Task^Type Listener^Task^Type Createbackup^Task^Type Downcpu^Task^Type Netmon^Task^Type Open^Task^Type Procdel^Task^Type Proccreate^Task^Type Literal Perm^State Assoc^State Nomsg^State Stopped^State = = = = = = = = 32, 33, 34, 35, 36, 37, 38, 39; = = = = %000100, %000200, %010000, %020000; !------------------------------------------------------------------------------! ! For each outstanding nowait I/O, an IOCB is allocated.
DCCBDECS Listing DCCBDECS and ULHDECSE Listings Int(32) Tcbaddr; Int File, Msgtag; Struct Iocb^info; Begin Unsigned(1) Io^Sysbuf; !Task requesting this IO !File # !$RECEIVE message tag !if true, $RECEIVE request data is !in SYSPOOL or SHARED POOL !Originating CPU for $RECEIVE request !if true, I/O operation initiated !by extended I/O procedure !if true, $RECEIVE IOCB !if false, File IOCB or DCB !if true, File DCB !if false, File IOCB or $RCV !if true, File IOCB !if false, $RECEIVE $RCV or DCB Unsigned(1
DCCBDECS Listing DCCBDECS and ULHDECSE Listings ! with the following format.
DCCBDECS Listing DCCBDECS and ULHDECSE Listings Nowaitdepth^Def = Flags1.<12:15>#; !Parameter to open !------------------------------------------------------------------------------! ! With each file, with the exception of $RECEIVE, opened within the GDS, an ! ! FCB is associated. The FCB serves to store open parameters for the file so ! ! that it can be CHECKOPENed automatically by the GDS.
DCCBDECS Listing DCCBDECS and ULHDECSE Listings Define Ppid Bpid = Processid[3]#, = Processid[4]#; ?Section Common^Data ! The TABLE pointers must be initialized to point to the upper memory tables Int .EXT Linetbl (Line^Template), !GDSX Line table for EXT usage .EXT LinetblX (Line^Template) = Linetbl; Int(32) .EXT Dcbtbl, !GDSX Subdev table for EXT usage .
DCCBDECS Listing DCCBDECS and ULHDECSE Listings E^Imsg E^Itc E^Ioc E^Resource E^Change = = = = = 4, 5, 6, 7, 8; ?Section Errors ! Guardian File Error Codes ! Literal FEOk FEEof FESysmess FENotfound FEBadname FENotopen FEBadcount FEBoundserr FEToomany FENolcb FENopoolspace FENocbspace FENoiophysmem FESecviol FEOpenstop FEContinue FENotransid FEInvtransid FEToomanytransbegins FETransabrtownerdied FETransabrtnetdown FETransabrtoprcmd FEToocheap FEBreakonly FELinereset FEEotreceived FENodata FEOwnership FE
ULHDECSE Listing DCCBDECS and ULHDECSE Listings FEScMissingParameter = 910, FEScInvalidBufferLength = 911, FEScParameterBoundsError = 912, FEScServerClassFrozen FEScUnknownServerClass = 913, = 914, FEScPathmonShutDown = 915, FEScServerCreationFailure = 916, FEScServerClassTmfViolation = 917, FEScOperationAborted = 918, FEScInvalidTimeoutValue = 919, FEScPFSUseError = 920, FEScTooManyPathmons = 921, FEScTooManyServerClasses = 922, FEScTooManyServerLinks = 923, FEScTooManySendReque
ULHDECSE Listing DCCBDECS and ULHDECSE Listings INT INT INT INT END; type; subtype; physreclen; wt^rd^pend; ! For Deviceinfo support ! " ! " !User-defined terminal data !!qual !!qual !!qual !!dd00 !******************************************************************************! ! For each line managed by USCODE, there is an entry in the LINETBL ! ! with the following format.
DCCBDECS and ULHDECSE Listings Extended General Device Support (GDSX) Manual—529931-001 C -14 ULHDECSE Listing
D Using Pseudo Procedures in a TS/MP Environment This appendix contains an example of converting a GDSX application that communicates with a TS/MP server through a Pathway/iTS SCREEN COBOL program and an example of a GDSX application that communicates directly with the server. The converted program also uses the TMF to protect transactions originating in the user code portion of GDSX.
Compiling USAMPLE1 Using Pseudo Procedures in a TS/MP Environment Figure D-1. GDSX Application Without Pathway/iTS and TMF Pseudo Procedures $GDS TSCODE Pathway/iTS TCP NonStop TS/MP Servers TERM1 SCOBGDSX WRITERO USCODE TERM2 DELETERO USECODE1 $SKY.LINZ.TST DAT VST027.vsd The following subsections step you through the process of compiling, binding, configuring, and starting the GDSX and Pathway/iTS applications. Compiling USAMPLE1 The first step is compiling the user code USAMPLE1.
Using Pseudo Procedures in a TS/MP Environment Binding The user code is compiled when this command is entered at the TACL prompt: > OBEY COMP1 Binding The second step is binding TSCODE and USCODE1 together into a GDSX object file named OGDS1. In the following example, the commands to do this were entered in a file called BIND1: ADD * FROM $SKY.LINZ.
Using Pseudo Procedures in a TS/MP Environment Starting NonStop TS/MP LOG1 PATHLOG, STATUS RESET TCP SET TCP SET TCP PROGRAM $SYSTEM.SYSTEM.
Running the GDSX Application Using Pseudo Procedures in a TS/MP Environment SET SET SET SET SET SET SET SET SET SET SET ADD SERVER SERVER SERVER SERVER SERVER SERVER SERVER SERVER SERVER SERVER SERVER SERVER PROGRAM WRITERO PROCESS $GDS3 PROCESS $GDS4 CPUS (0:1, 1:0) MAXSERVERS 2 CREATEDELAY 1 SECS DELETEDELAY 20 MINS NUMSTATIC 1 SECURITY "N" TMF ON (ASSIGN TSTDAT, $SKY.LINZ.
Using Pseudo Procedures in a TS/MP Environment USAMPLE1 Listing DEVICETYPE 6, DEVICESUBTYPE 4, PHYSRECLEN 80 -> ADD SU $GDSX.#TERM2, ACCESSNAME $STAR.#PTY10 DEVICETYPE 6, DEVICESUBTYPE 4, PHYSRECLEN 80 -> START SU $GDSX.#TERM1 -> START SU $GDSX.#TERM2 USAMPLE1 Listing 1. !****************************************************************************** 2. ! GDSX USCODE Generic DEVICE^HANDLER ! 3. ! Sample program ! 4. ! ! 5. ! Writing or deleting records in a database using IDS ! 6.
USAMPLE1 Listing Using Pseudo Procedures in a TS/MP Environment 71. 72. 73. 74. 75. 76. 77. 78. 79. 80. 81. 82. 83. 84. 85. 86. 87. 88. 89. 90. 91. 92. 93. 94. Term^Type ; -- terminal type Begin !=========================================================================== ! USCODE can declare desired DEVICE^HANDLER Local Variables here !=========================================================================== Int Int Int Int .EXT .EXT .EXT .
Using Pseudo Procedures in a TS/MP Environment USAMPLE1 Listing 143. E^Stop -> ! task is stopping 144. Call Stop^Task; 145. End; 146. End; ! of While 147. 148. End; 149. 151. !=========================================================================== 152. Int SubProc Check^Buffer; 153. !=========================================================================== 154. ! we return the value 0, when we detected an error 155. ! we return the value 1, when the buffer is OK 156.
Using Pseudo Procedures in a TS/MP Environment 218. 219. 220. 221. 222. 223. 224. 225. 226. 227. 228. 229. 230. 231. 232. 233. 234. 235. 236. 237. 238. 239. 240. 241. 242. 243. 244. 245. 246. 247. 248 249. 250. 251. 252. 253. 254. 255. 256. 257. 258. 259. 260. 261. 262. 263. 264. 265. 266. 267. 268. 269. 270. 271. 272. 273. 274. 275. 276. 277. 278. 279. 280. 281. 282. 283 284. 285. 286. 287. 288. 289. 290. 291.
USAMPLE1 Listing Using Pseudo Procedures in a TS/MP Environment 292. 293. 294. 295. 296. 297. 298. 299. 300. 301. 302. 303. 304. 305. 306. 307. 308. 309. 310. 313. 314. 315. 316. 317. 318. found 319. 320. value 321. value 322. 323. 324. 325. 326. param 327. 328. 329. 330. 331. 332. 333. string 334. TSCODE 335. 336. 337. 338. 339. 340. 341. 342. 343. 344. 345. 346. 347. 348. 349. 350. 351. 352. 353. 354. 355. 356. 357. 358. 360. 361. 362. Int .
Using Pseudo Procedures in a TS/MP Environment SCOBGDSX Listing 363. !=========================================================================== 364. 365. Int .EXT iocb (iocb^template), ! routines for processing 366. .file^error , ! user's commands, functions, etc. 367. .sg^error ; 368. Begin 369. 370. SG^ERROR := -1; ! -1 indicates that this command is unknown 371. Return 0; 372. 373. END ; 374. 375. 376. 377. !=========================================================================== 378.
Using Pseudo Procedures in a TS/MP Environment SCOBGDSX Listing 11 Source-Computer. T16. 12 Object-Computer. T16, 13 Terminal is Intelligent. 14 15 ****************************************************************************** 16 Data Division. 17 ****************************************************************************** 18 Working-Storage Section. 19 * 20 01 Ws-Send. 21 05 Ws-Send-Reply-Code Pic 9(4) Comp. 22 05 Ws-Send-Function-Code Pic X(01). 23 05 Ws-Send-Loop Pic 9(03).
WRITER Listing Using Pseudo Procedures in a TS/MP Environment 79 Move "Initialization" to Ws-Send-Text. 80 * 81 100-IDS-Loop. 82 Move Zero to Ws-Send-Reply-Code. 83 84 Send Message Send-Msg 85 Reply Code 0 Yields Rcvd-Msg 86 On Error Perform 300-Send-Msg-Error. 87 * 88 If Ws-Rcvd-Function-Code = "d" or 89 Ws-Rcvd-Function-Code = "D" 90 Perform 150-Send-to-Delete-Server 91 Else 92 If Ws-Rcvd-Function-Code = "w" or 93 Ws-Rcvd-Function-Code = "W" 94 Perform 200-Send-to-Write-Server.
WRITER Listing Using Pseudo Procedures in a TS/MP Environment 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 Select Message-Out File Status Assign to $Receive is Receive-File-Status. * Select Tstdat Assign Organization Access Mode Record Key File Status to is is is is File1 Indexed Dynamic Tstdat-Key File-Stat. * Receive-Control.
Using Pseudo Procedures in a TS/MP Environment WRITER Listing 101 10 Stat-2 Pic 9(01) Value Zero. 103 104 ******************************************************************************** 105 Procedure Division. 106 ******************************************************************************** 107 Declaratives. 108 109 Ua-Message-In Section. 110 Use after Error Procedure on Message-In. 111 Ua-Message-In-Proc.
DELETER Listing Using Pseudo Procedures in a TS/MP Environment 169 Move In-Message-Loop to Ok-Nmbr. 170 171 Perform E-Write Varying I From 1 by 1 Until I > In-Message-Loop. 172 173 If I < 9999 174 Move Ok-Message to Out-Message-Text. 175 176 Write Out-Message. 177 178 179 E-Write. 180 Move I to Tstdat-Loop. 181 Write Tstdat-Rec.
Using Pseudo Procedures in a TS/MP Environment DELETER Listing 40 Reply contains 64 Characters. 41 42 Data Division. 43 44 File Section. 45 46 FD Message-In 47 Label Records are omitted 48 Record contains 1 to 64 Characters. 49 50 01 In-Message. 51 05 In-Message-Reply-Code Pic 9(04) Comp. 52 05 In-Message-Function-Code Pic X(01). 53 05 In-Message-Key. 54 10 In-Message-Loop Pic 9(03). 55 10 In-Message-Key-1 Pic X(08). 56 05 In-Message-Text Pic X(50).
DELETER Listing Using Pseudo Procedures in a TS/MP Environment 114 " Stat-1 = " Stat-1 " Stat-2 = " Stat-2 Upon Tout. 115 116 Ua-Message-Out Section. 117 Use after Error Procedure on Message-Out. 118 Ua-Message-Out-Proc. 119 If Receive-File-Status Not = "10" 120 Display "Mirror " " Error in Message-Out file " 121 " Stat-1 = " Stat-1 " Stat-2 = " Stat-2 Upon Tout. 122 End Declaratives.
Using Pseudo Procedures in a TS/MP Environment GDSX With NonStop TS/MP and TMF Procedures 183 If Not-Found 184 Next Sentence 185 Else 186 Move I to Ok-Nmbr 187 Move 9999 to I 188 Move File-Stat-N to Out-Message-Loop 189 Move "Error reading tstdat" to Out-Message-Text 190 Else 191 Delete Tstdat 192 If File-Error 193 Move I to Ok-Nmbr 194 Move 9999 to I 195 Move File-Stat-N to Out-Message-Loop 196 Move "Error deleting tstdat" to Out-Message-Text.
Compiling USAMPLE2 Using Pseudo Procedures in a TS/MP Environment Figure D-2. GDSX Application With NonStop TS/MP and TMF Pseudo Procedures $GDS $PWGDS TSCODE NonStop TS/MP Servers TERM1 WRITERO USCODE TERM2 DELETERO $SKY.LINZ.TSTDAT USECODE2 VST028.vsd The following subsections step you through the process of compiling, binding, configuring, and starting the GDSX and TS/MP applications. Compiling USAMPLE2 The first step is compiling the user code USAMPLE2.
Using Pseudo Procedures in a TS/MP Environment Binding The user code is compiled when this command is entered at the TACL prompt: > OBEY COMP2 Binding The second step is binding TSCODE and USCODE2 together into a GDSX object file named OGDS2. The commands to do this were entered in a file called BIND2: ADD * FROM $SKY.LINZ.
Using Pseudo Procedures in a TS/MP Environment Running the GDSX Application LOG1 PATHLOG, STATUS RESET SERVER SET SERVER SET SERVER PROGRAM DELETERO SET SERVER PROCESS $GDS1 SET SERVER PROCESS $GDS2 SET SERVER CPUS (1:0, 0:1) SET SERVER MAXSERVERS 2 SET SERVER CREATEDELAY 1 SECS SET SERVER DELETEDELAY 30 MINS SET SERVER NUMSTATIC 1 SET SERVER SECURITY "N" SET SERVER TMF ON SET SERVER (ASSIGN TSTDAT, $SKY.
Configuring and Starting the Terminal Tasks Using Pseudo Procedures in a TS/MP Environment PARAM PARAM PARAM PARAM PARAM MAXBUFPOOL 50000 TASKSIZE 2048 DEVICEINFO 1 TMF 2 PROCNOWAIT 1 Make pool 10 larger Increase the task size Support DEVICEINFO calls from Pathway Use TMF product in user task Have ^SERVERCLASS_SEND_ run in nowait mode RUN OGDS2 /NAME $GDSX, LIB SCPROCS/ The GDSX application is started when the macro name is entered at the TACL prompt: > RUN RUN2 Configuring and Starting the Terminal T
USAMPLE2 Listing Using Pseudo Procedures in a TS/MP Environment 40. 42. 43. 44. 45. 47. 48. 49. 50. 51. 52. 53. 54. 55. 56. 57. 58. 59. 60. 61. 62. 63. 64. 65. 66. 67. 68. 69. 70. 71 75. 77. 79. 80. 81. 82. 83. ?NOLIST, Source DCCBDECS (CONFIG^DATA) End Block; ! Config^Parms^DATA Block Common^Data; ?NOLIST, Source DCCBDECS (Common^Data) End Block; ! Common^Data Block USER^PRIVATE; Literal TRUE = -1, FALSE = 0; -- the following variables are global for this GDSX-Application Int .Pm^Name[0:23]; String .
USAMPLE2 Listing Using Pseudo Procedures in a TS/MP Environment 118. 119. 120. 121. 122. 123. 124. 125. 126. 127. 128. 129. 130. 131. 132. 133. 134. 135. 136. 137. 138. 139. 140. 141. 142. 143. 144. 145. 146. 147. 148. 149. 150. 151. 12; 152. 153. 154. 155. 157. !=========================================================================== Begin 159. 160. 161. 162. 163. 164. 165. 166 167 168. 169. 170. 171. 172. 173. 174. 175. 176. 177. 178. 179. 180. 181. 182. 183. 184. 185. 186. 187. 188. 189. 190. 191.
Using Pseudo Procedures in a TS/MP Environment 193. 194. 195. 196. 197. 198. 199. 200. 201. 202. 203. 204. 205. 206. 207. 208. 209. 210. 211. 212.
Using Pseudo Procedures in a TS/MP Environment 269. 270. 271 272 273. 274. 275. 276. 277. 278. 279. 280. 281. 282. 283. 284. 285. completed 286. 287. 288. 289. 290. 291. 292. 293. 294. 295. 296. 297. 298. 299. 300. 301. 303. 305. 306. 307. 308. 309. 310. 311. 312. 313. 314. 315. 316. 317. 318. 319. buffer 320. 322. 323. 324. 325. 326. 327. 328. 329. 330. 331. 332. 333. 334. 335. 336. 337. 338. 339. 340. 341. 342. USAMPLE2 Listing @My^Dcb := Dcbtbl[Internal^Term^No]; @My^Tcb := My^Dcb.
Using Pseudo Procedures in a TS/MP Environment 343. 344. 345. 346. 347. 348. 349. 350. 351. 352. 353. 354. 355. 356. 357. 358. 359. 360. 361 362. 363. 364. 365. 36 367. 368. 369. 370. 371. 372. 373. 374. 375. 376.
USAMPLE2 Listing Using Pseudo Procedures in a TS/MP Environment 414. 415. 416. 417. 418. 419. 420. 421. 422. 423. 424. 425. 426. 427. 428. 429. 430. 433 434. 435. 436. 437. 438. 439. 440. 441. 442. 443. 444. 445. 446. 447. 448. 449. 450. 451. 452. 453. string, 454. 455. 456. 457. 458. 459. 460. 461. 462. 463. 464. 465. 466. 467. 468. 469. 470. 471. 472. 473. 474. 475. 476. 477. 478. 479. 480. 481. 482. 483. 484. 485. 486 487 488.
Using Pseudo Procedures in a TS/MP Environment USAMPLE2 Listing 489. 490. SG^ERROR := -1; ! -1 indicates that this command is unknown 491. Return 0; 492. 493. END ; 494. 495. 496. 497. !=========================================================================== 498 Proc user^init^config^params; 499. !=========================================================================== 500. Begin 501. End; 502. 503. 504. 505. !=========================================================================== 506.
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 SSV0, $SKY.LINZ ASSIGN ZSPITACL, $SKY.ZSPIDEF.ZSPITACL ASSIGN ZEMSTACL, $SKY.ZSPIDEF.ZEMSTACL ASSIGN ZGDXTAL, $SKY.LINZ.ZGDXTAL ASSIGN COPYTAL, $SYSTEM.SYSTEM.COPYTAL ASSIGN SSV1, $SKY.ZSPIDEF ASSIGN SSV2, $SYSTEM.SYSTEM TAL /IN USAMPLE3, SWAP $CRASH, OUT $S.
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 117. 118. 119. 120. 121. 122. 123. 124. 125. 126. 127. 128. 129. 130. 131. 132. 133. 134. 135. 136. 137. 138. 139. 140. 141. 143. 144. 145. 146. 147. 148. 149. 150. 151. 152. 153. 154. 155. 156. 157. 158. 159. 160. 161. 162. 163. 164. 165. 166. 167. 168. 169. 170. 171. 172. 174. 175 176. 177. 1D); 178. 179. 180. 181. 182. 183. 184. 185. 186. 187. 188. 189. task 190. INT INT INT INT INT INT .EXT .EXT .EXT .EXT .EXT .
USAMPLE3 Intertask Communication Example 191. 192. 193. 194. 195. 196. 197. 198. 199. 200. 201. 202. 203. 204. 205. 206. 207. 208. 209. 210. 211. 212. 213. 214. 215. 216. 217. 218. 219. 220. 221. 222. 223. 224. 225. 226. 227. 228. 229. 230. 231. 232. 233. 234. 235. 236. 237. 238. 239. 240. 241. 242. 244. 245. 246. 247. 248. 249. 250. 251. 252. 253. 254. 255. 256. 257. 258. 259. 260. 261. 262. 263. 264.
USAMPLE3 Intertask Communication Example 265. 266. 267. 268. 269. 270. 271. 272. 273. 274. 275. 276. End; Call Deallocateiocb(Dev^Iocb); End; ----E^STOP -> ----Call Stop^Task; END; END; END; ! task is stopping ! of case Evt ! of while 1 ! of proc The remaining code of USAMPLE3 consists of various procedures such as PROCESS^USER^PARAMS, PROCESS^ASSIGNS, and USER^VERSION. These procedures are the same as those used in USAMPLE1. See Appendix D, Using Pseudo Procedures in a TS/MP Environment.
Intertask Communication Example Extended General Device Support (GDSX) Manual—529931-001 E- 8 USAMPLE3
Glossary active task. An existing task that was started and is now executing, or ready to execute, or waiting for a resource. backup task. A system task that processes activities related to fault-tolerant functioning. This task is created only if GDSX is run as a process pair. converted. An application that has been modified to use an extended feature of the Dseries operating system. TSCODE assumes that USCODE is converted only if d^plus^enabled of the CONTROLFLAGS configuration parameter is set to 1.
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, TS/MP, Pathway/iTS, and TMF procedure counterparts. RCB. Receive control block. During the processing of a requester OPEN by TSCODE, an RCB is assigned to represent the communication session with the requester. SU. Subdevice. With regard to GDSX, this SCF object type is a logical terminal that is managed by a DEVICE^HANDLER task and mapped to a physical terminal or a process.
user task Glossary Extended General Device Support (GDSX) Manual—529931-001 Glossary- 4
Index A Abend errors 3-19/3-21 errors less than 100 3-21 error 220 3-21 error 230 2-28, 2-55, 3-21 error 231 2-28, 2-55, 3-21 information to be gathered for 3-28 message format 3-20 ABORT command, SCF ABORT LINE 9-23 ABORT SU 9-23 example 4-13, 5-19, 6-6 ABORTTRANSACTION pseudo procedure 8-7 Access methods function of, with GDSX 1-4 procedures supported by 1-6 supporting direct access of devices 1-12 supporting indirect access of devices 1-12 type of, used with GDSX 1-4 ACCESSNAME attribute, SCF 9-7 ADD com
C Index Bufaddrx 5-18, 8-46 Buffer pool 2-24, 8-36 BUFFERTIMEOUT configuration parameter 2-52, 8-37 C CANCEL 2-12, 8-15 CANCELREQ 2-12, 8-16 CANCELTIMEOUT 2-12, 8-16 CHANGE^BUFF^OWNERX 8-17 CHECKPOINT 2-32/2-33, 8-18 and task suspension 2-13 and user-defined extended segment 2-19 used in example program 5-21 checkpoint 8-31, 8-34 Checkpoint buffer 2-60, 8-57 Checkpoint semaphore 8-28/8-30, 8-40 Checkpointing See Fault tolerance CHECK^BUFFER^BOUNDS 8-17 CLOSE 2-12, 2-53, 8-19 Coding and testing considerat
E Index Debugging procedures 8-2 Declarations See Design and development, data declarations DELAY 2-12, 8-19 DELETE command, SCF 3-15 DELETER listing D-16 DELETE^XITEM 2-38, 8-20 Design and development calling restrictions 2-11/2-14, 7-2 compiling and binding 2-43/2-45 considerations 2-1/2-2 data declarations 2-16/2-19 configuration parameters 2-19 identifiers 2-19 prerequisites 2-1 space usages and limitations 2-19/2-24 tasks listed -xx, -xxii DEVICEINFO configuration parameter 2-56 DEVICEINFO2 2-12, 2-5
F Index Example GDSX process, generating 4-4/4-6 Extaddr 7-23, 8-46 Extended buffer pool 2-24, 2-27, 2-59, 8-30, 8-33 Extended GDS (GDSX) 2-15 coding new applications 2-14 communicating with other processes 2-4 converting applications 2-3 C-series to D-series 2-14, 2-15 file name structure 2-5 hardware and software requirements 1-9 high PIN process 2-4, 3-1 low PIN process 2-4 open message format 2-54 service routines 2-4 Extended message pool 2-24, 2-27, 2-65, 8-30, 8-33 Extended segments for control str
G Index error 210 2-34, 2-78 File sytem interface with GDSX 1-6 FILEINFO 2-12, 8-25 FILE_CLOSE_ 2-12, 8-24 FILE_GETINFOBYNAME_ 2-12, 8-25 FILE_GETINFO_ 2-12, 8-24 FILE_GETRECEIVEINFO_ 2-12, 8-25 sourcing in template for 2-18 FILE_OPEN_ 2-12, 8-26 FILTGDS 2-79 FNAMEEXPAND 2-12, 8-28 G GDS Management Programming Manual -xxiv GDSE object file 4-6 GDSX architecture 1-3/1-5 COBOL 85 definitions 1-7 DDL definitions 1-7 environments 1-1/1-2 front end for Pathway/TS 1-3/1-5, 1-10/1-16 generation process 2-40/2-4
K Index example E-1 LINE^HANDLER perspective 7-3/7-7 procedures 8-3 In^queue^file^num 7-1, 7-10, 7-14 IOCB allocating 8-9 deallocating 8-16, 8-17, 8-19 described 2-89/2-96, 5-18 global 2-16 maintenance procedures 8-3 pool allocation 2-21/2-24, 2-62 sourcing in template for 2-17 waiting for allocation 2-59 IOCBWAITTIME configuration parameter 2-59, 8-9 Iocnt 5-18 ITC file 2-62, 2-63, 2-96, 7-1, 7-8, 8-50, 9-3 ITC^OPENX 8-43, E-1 I/O involving $RECEIVE 2-93/2-96, 8-46 I/O not involving $RECEIVE 2-89/2-93, 8
M Index LOADFILT 2-79/2-80 Local buffer pool See Buffer pool Local message pool See Message pool LOCKREC 2-12, 8-48 LOGSTATUS configuration parameter 2-59 LOOPTIME configuration parameter 2-59 Low PIN process 2-4 M MAKE_PROCESS_HANDLE_NULL_ 8-48 Manual users doing design and development -xxii doing operations tasks -xxiii doing support tasks -xxiv doing systems analysis -xxi profile of -xvii MAXBUFPOOL configuration parameter 2-27, 2-59, 8-30 MAXCPSIZE configuration parameter 2-31, 2-60, 8-19 MAXDCBPOOL
O Index Netmon task 2-9 NEWPROCESS 2-12, 2-66, 8-49 NONSTOP configuration parameter 2-69, 3-11 Nonstop mode 2-52 NonStop TS/MP communicating directly with 8-71, 8-72, 8-73, 8-74 example of using pseudo procedures D-19 pseudo procedures 1-16, 8-71, 8-72, 8-73, 8-74 running a GDSX application as a server 3-10 Noretn 8-22/8-23 NOTIFY^IO^COMPLETIONX 7-7, 8-50, E-1 NOWAITDEPTH attribute, SCF 9-7 O OGDS USAMPLE object 2-75 OPEN 2-12, 2-53, 8-51 open 2-77 Open task 2-9, 2-11 Opens, public and private 2-2, 8-26,
R Index R RCB global 2-16 pool allocation 2-21/2-24, 2-67 sourcing in template for 2-18 RCV pool allocation 2-21/2-24, 2-67 Readers See Manual users READLOCKX 2-12, 8-61 READUPDATELOCKX 2-12, 8-63 READUPDATEX 2-12, 8-61, E-1 READX 2-12, 8-61 RECEIVEDEPTH configuration parameter 2-70 RECEIVEINFO 2-12, 8-63 RECEIVESIZE configuration parameter 2-71 RECLAIMBUFFER 2-73, 8-64 used in example program 5-21 Remote device access 3-6, 3-8 REPLYX 2-12, 8-66 Requester application used with example programs 4-2 Restart
T Index SHUTDOWN 8-76 SIGNALINTERRUPT 2-12, 8-16, 8-17, 8-77 SIGNALTIMEOUT 2-12, 8-16, 8-17, 8-77, 8-78 SPI programmatic control 1-7, 3-14 See also SCF/SPI sensitive commands 2-71 used to set configuration parameters 2-50 user-defined commands 9-12 START command, SCF 3-15 START LINE 9-3 STARTED state of task 4-11 STATS command, SCF 3-15, 9-20 STATUS command, SCF 3-15 Status message 3-16 STOP command, SCF 3-15 STOP PROCESS 4-13, 6-7, 8-77, 8-82 STOP SU 4-13, 6-6, 9-23 STOPOPENS command, SCF 3-16 STOP^TASK
U Index RESUMETRANSACTION procedure 8-67 TMF configuration parameter 2-37, 2-74 Trace 2-55, 2-80/2-89 automatically generated records 2-80/2-83 entry type 2-81/2-85, 8-8 saving, at abend 3-28 turning on the 2-85/2-88 user-coded records 2-83/2-85 TRACE command, SCF 2-80, 2-87, 2-89, 3-16 TRACEB 2-24, 2-86, 2-88, 3-28 TRACEP 2-24, 2-86, 2-88, 3-28 TRACERECSIZE configuration parameter 2-74, 2-83, 2-88 Trace^control^flags 2-80, 8-8 Trap messages 3-23/3-24 format 3-24 TRAPERROR configuration parameter 2-75 TSC
V Index USERPARAM 9-5 USERSTARTSU configuration parameter 2-75, 9-22 USER^ATTRIBUTES procedure 9-7/9-9 USER^BACKUP procedure 2-31, 9-10/9-11 called by TSCODE 2-11 USER^CLOSE^TRACE^FILE 2-88, 8-83 USER^COMMANDS procedure 9-12/9-18 USER^INITIALIZE procedure 2-10, 9-18/9-19 USER^INIT^CONFIG^PARAMS procedure 2-10, 2-49, 9-19 and configuration parameters 2-46 USER^OPEN^TRACE^FILE 2-83, 2-86, 8-83 User^private data block 2-17 USER^REPLIES procedure 9-20/9-22 USER^START procedure 2-75, 9-22/9-23 USER^STOP proced
Special Characters Index ZGDSTACL 9-13 ZGDXCOB 1-7 ZGDXDDL 1-7 ZGDXSEGF 1-7 ZGDXTACL 1-7, 2-79, 9-13 ZGDXTAL 1-7 ZGDXTMPL 1-7 ZSPITACL 2-79, 9-13 Special Characters * SCF wildcard 6-4 Extended General Device Support (GDSX) Manual—529931-001 Index -13
Special Characters Index Extended General Device Support (GDSX) Manual—529931-001 Index -14
