---- - - - - --_.- ----- Series/1 GC34-0328-0 File N. S1-34 LICENSED MATERIAL IBM Series/1 Event Driven Exeutive Versin 1.1 Planning Guide Prgram Numbers: 5719-XS1 5719-UT3 5719-XX2 5719-LM5 5719-LM2 5719-MS1 (Multiple Terminal Manager) 5719-AM3 (Indexed Aess Methd)
---- - - - - ----- --_.- Series/1 GC34-0328-0 File N. 51-34 LICENSED MATERIAL IBM Series/1 Event Driven Exeutive Versin 1.1 Planning Guide Prgram Numbers: 5719-XS1 5719-UT3 5719-XX2 5719-LM5 5719-LM2 5719-MS1 (Multiple Terminal Manager) 5719-AM3 (Indexed Aess Methd) 1
First Editin (July 1979) Use this publiatin nly fr the purpse stated in the Prefae. Changes are peridially made t the infrmatin herein; befre using this publiatin in nnetin with the peratin f IBM systems, refer t the latest IBM Series/l Graphi Bibligraphy, GA34-0055, fr the editins that are appliable and urrent. Publiatins are nt stked at the address given belw. Requests fr pies f IBM publiatins shuld be made t yur IBM representative r the IBM branh ffie serving yur lality. This publiatin uld ntain tehnial inauraies r typgraphial errrs. A frm fr reader'~ mments is prvided at the bak f this publiatin. If the frm has been remved, address yur mments t IBM Crpratin, Systems Publiatins, Department 27T, P.O. Bx 1328, Ba Ratn, Flrida 33432. IBM may use and distribute any f the infrmatin yu supply in any way it believes apprpriate withut inurring any bligatin whatever. Yu may, f urse, ntinue t use the infrmatin yu supply. e) Cpyright IBM Crpratin 1979 ii Versin 1.1 Planning Guide
PREFACE This publiatin is t be used fr planning purpses nly. Any infrmatin ntained herein is subjet t hange. Fr final infrmatin nerning any tpi disussed in this publiatin, nsult the Versin 1.1 manuals listed belw when they beme available. This publiatin prvides the infrmatin required t design appliatins that use Versin 1.1 f the Event Driven Exeutive, the Multiple Terminal Manager, and the Indexed Aess Methd. HOW THIS MANUAL IS ORGANIZED Part 1 desribes Versin 1.1 f the Event Driven Exeutive and pints ut the enhanements it prvides ver Versin 1.0. Part 2 desribes the Multiple Terminal Manager, whih yu an use t simplify the definitin f transatin-riented appliatins. Part 3 desribes the Indexed Aess Methd, whih yu an use t aess and maintain yur data in a keyed (indexed) rganizatin. ( ".~ / Befre reading this manual, yu shuld be familiar with the Event Driven Exeutive. See the list belw fr publiatins that an help yu. RELATED PUBLICATIONS: The fllwing publiatins are nw available fr Versin 1.0 f the Event Driven Exeutive. The Versin 1.1 publiatins will be released in Otber, 1979, under the same numbers and titles (exept as nted). IBM Series/1 System Summary, GC34-0285. IBM Series/l Event Driven Exeutive System Guide, SC34-0312. IBM Series/l Event Driven Exeutive Utilities, Operatr Cmmands, and Prgram Preparatin, SC34-0313. Nte. The Versin 1.1 release f this dument will be titled: IBM Series/l Event Driven Exeutive utilities, Cmmands, Pr9ram Preparatin and Messages and Cdes, SC34-0313. IBM Series/l Event Driven Exeutive language Referene, SC34-0314. IBM Series/l Event Driven Exeutive Mar Assembler, SC34-0317. Prefae iii
IBM Series/1 Event Driven Exeutive Cmmuniatins Guide, SC34-0316. Nte. The Versin 1.1 release f this dument will be: IBM Series/1 Event Driven Exeutive Cmmuniatins and Terminal Appliatins Guide, SC34-0316. iv Versin 1.1 Planning Guide
CONTENTS Part 1: Event Dr;ven Exeut;ve Intrdutin Address Translatr Supprt Versin 1.0 Versin 1.1 Cmpatibility Sure Prgram Cmpatibility Appliatin Prgram Interfaes Data Set Cmpatibility.... Funtinal Cntent Cmpatibility Strage Si zes Multi-Partitin Extensins Diagnsti and Revery Imprvements I/O Errr Rerding Task Errr Exit System Area Prtetin Prgram Exeptin Trae st rage Dump.... Speial Cnsideratins Referenes t System Area Data Invking Prgrams That Reside in the System Area User-Written Supervisr Extensins Virtual Terminals... Sensr I/O Appl i ati ns... Use f Attentin Lists (ATTNLIST) Prgram (Header) r TCB Dependenies &SYSCOM Usage..... Part 2: EDX Hult;ple Term;nal Manager Overv i ew.... Multiple Terminal Manager Cnepts Hardware Sftware Prgram Operat in.... Multiple Terminal Manager Initializatin Prgram Terminal Server Prgrams Appliatin Prgram Manager Prgram Management....... ACTION - Feth Operatr Respnse LINK - Lad and Exeute Prgram LINKON...... CYCLE - Suspend Current Terminal Appliatin MENU - Return t Multiple Terminal Manager Cntrl WRITE - Output t an Asynhrnus Terminal Terminal/Sreen Management.... SETPAN - Frmat the Input and Output Buffers SETCUR - Mve Cursr t Speified Psitin BEEP - Set Audi ble Alarm... CHGPAN............. Fi Ie Management FILEIO...... 1 1 2 2 2 3 5 6 7 7 7 8 8 8 9 9 9 9 9 10 10 11 11 12 12 13 13 15 15 15 17 21 21 21 22 22 23 24 24 24 25 26 26 26 27 27 27 27 29 29 Cntents v
Indexed File Request Types Di ret Fi Ie Request Types.. Multiple Terminal Manager Utilities Appliatin Design Infrmatin Prgramming Cnsideratins. Multiple Terminal Manager Data Set Requirements MTMS TORE...... Terminal.... Sreen Frmat Vlume - SCRNS. User Appliatin Prgram Vlume - PRGRMS Si gn-on Fi Ie - SIGNONFl.. Operatr Interfae Multiple Terminal Manager Initializatin Sign-n Prgram Initiatin and Terminatin Disnnet Rennet... Prgrams Reprt Terminal Ativity Reprt Sreen Pri nt... Distributin and Installatin Prgram Preparatin Perfrmane Infrmatin Part 3: EDX Indexed Aess Methd Overview.... Indexed Data Set Features Data Prtetin Devies Supprted Cmpnents Funt ins... Indexed data Sets Prgram Operatin Appliatin Prgram Preparatin Appliatin Design Infrmatin Prepari ng the Data. Defining the Key... Seleting the Blk Size Est i mat i ng Free Spae.. Building The Indexed Data Set Determi ni ng Si ze and Frmat....... Defining and Creating the Indexed Data Set... Cnneting and Disnneting the Indexed Data Set ladi ng Base Rerds...... Pressing... Di ret Readi ng Diret Updating Sequential Reading Sequential Updating Inserting Deleting Extrating Handling Errrs Errr Exit Rutine System Funtin Return Cdes 30 31 31 31 32 32 33 33 34 34 35 35 35 36 36 37 37 38 38 38 38 40 40 43 43 43 44 44 44 45 48 49 50 51 51 51 52 54 56 56 57 58 58 59 60 60 61 62 62 63 64 64 64 64 ~,"'," (1,\ ".'1 1 '~ vi Versin 1.1 Planning Guide
Data Set Shut Dwn Deadlks..... Exeuting the Appliatin Prgram Maintaining the Indexed Data Set Bakup and Revery Revery Withut Bakup Rerganizatin Dumping Deleting Data Set Frmat Blks FCB Index Blk Data Blk The Index Prime Index Blks Send-Level Index Blk Higher Level Index Blk Index Example Cluster Free Spae Free Rerds Free Blks Reserve Blks Reserve Index Entries The last Cluster... Sequential Chaining Free Pl Strage and Perfrmane Infrmatin Strage Requirements Indexed File Size Perfrmane Infrmatin Summary f Calulatins Index 65 65 66 68 68 68 69 69 70 70 70 72 72 72 73 73 75 75 76 77 78 79 80 80 80 81 81 82 83 83 83 84 84 91 Cntents vii
/---\ <,~ vi i i Versi n 1.1 Planni ng Gui de
PART 1: EVENT DRIVEN EXECUTIVE INTRODUCTION Versin 1.1 f the Event Driven Exeutive, available in Otber 1979, expands the spe f the data pressing slutins pssible with the Event Driven Exeutive. Imprvements inlude: Supprt fr 128KB f strage n the 4952 Appliatins prgrams up t 64KB Crss-partitin mmuniatin apability Diagnsti and revery imprvements The hanges that make this pssible are desribed in this planning guide. / Versin 1.1 f the Event Driven Exeutive system inludes servie releases f eah f the fllwing liensed prgrams: Basi Supervisr and Emulatr (5719-XSl) Utilities (5719-UT3) Prgram Preparatin Faility (5719-XX2) Mar Assembler (5719-ASA) Mar Library (5719-lM5) Mar Library/Hst (5740-LM2) COBOL Cmpiler and Resident library (S719-CB3) COBOL Transient Library (S719-CB4) FORTRAN IV Cmpiler and Objet library Versin 2 (S719-F02) Srt/Merge (S719-SM2) Mathematial (S719-LM3) and Funtinal Subrutine Library The fllwing new liensed prgrams have als been annuned fr use with Versin 1.1 f the system and will be available in Otber 1979. Part 1: Event Driven Exeutive 1
Indexed Aess Methd (S719-AM3) Multiple Terminal Manager CS719-MS1) These new prgrams are als desribed in this planning guide. ADDRESS TRANSLATOR SUPPORT VERSION 1.0, The Event Driven Exeutive CEDX) perating system fr the Series/l urrently supprts the address translatr feature f the 4952 and 4955 pressrs. The prgrams exeuting in eah strage partitin have diret aess t the funtins and data areas in the supervisr, in muh the same way as a prgram exeuting in a nn-address translated, single partitin system. Althugh this mehanism ffers the advantages f neptual simpliity and mpatibility with earlier versins f the perating system, it has tw drawbaks. First, segmentatin registers are used t map the system area int eah partitin defined by the user. In systems with pressr strage apprahing 128K bytes and tw sets f segment registers, the result may be an inadequate number f segmentatin registers t map the entire strage area. Thus, pressr strage an exist whih annt be aessed by either user r system tasks. Send, the user appliatin may be size-nstrained by the neessity t leave 20-32KB r mre fr the system area in eah 64KB partitin. The system requires that tw failities be available t user prgrams and system utilities regardless f the addressing mehanism used. These are the ability t invke supervisr funtins thrugh Series/l assembler language instrutins r the Event Driven language and the ability t referene system data areas, again in either a diret r indiret.fashin. As nted abve, the urrent versin f EDX prvides these funtins by lgially mapping the supervisr int eah partitin. VERSJON 1.1 Versin 1.1 f EDX prvides a supervisr that resides nly in partitin 1, thus making it pssible t supprt appliatin prgrams up t 64K bytes in length in the ther partitins. Eliminatin f redundant mappings f the sys- 2 Versi n 1.1 Planni ng Gui de
tem area frees mre f the pressr's segmentatin registers fr use in addressing unique physial strage, thus inreasing the amunt f strage that an be effetively put t use n pressrs suh as the 4952. The abillty t ptinally map a prtin f the system area int eah partitin prvides the apability fr shared strage areas (suh as $SYSCOM) withut wasting large amunts f appliatin spae n ther ntrl prgram mdules as well. Figure 1 illustrates sme f the strage nfiguratins nw pssible with Versin 1.1. Anther advantage f the new strage map is that it prvides inreased prtetin f the system area frm aidental mdifiatin by appliatins. Previusly, a prgram errr uld aidentally damage the system and affet all prgrams and partitins. Beause the Versin 1.1 system area resides in partitin 1 nly, the hane f aidental mdifiatin by prgrams in ther partitins is nsiderably redued. ( """, ~"/ T mplement the strage map imprvement the enhaned address translatr supprt inludes several extensins t system funtins fr the multi-partitin envirnment. These extensins make it pssible t mve data and signal events and manage resures arss partitin bundaries, thus making multiple partitin appliatins easier t design and implement. These failities are desribed in mre detail under the heading "Multi-Partitin Extensins." Versin 1.1 als ntains imprved diagnsti and revery apability. Optinal failities inlude I/O errr lgging, a task errr revery exit, a prgram exeptin trae, and a strage dump. These failities are desribed in mre detail under the heading "Diagnsti and Revery Imprvements." COMPATIBILITY Versin 1.1 preserves all the standard Event Driven Exeutive appliatin prgram interfaes and as many f the appliatin implementatin tehniques as pssible. Versin 1.1 is mpatible with Versin 1.0 in terms f sure prgrams, data sets and funtinal ntent. Eah f these is explained mre fully belw. In general, yu may expet that appliatins written t run n Versin 1.0 will run n Versin 1.1 after rempilatin. Sine mst appliatins written fr the Event Driven Exeutive FDP Versin 2 wuld als run n Versin 1.0 f the liensed prgram, the infrmatin in this guide is als appliable t them. Part 1: Event Driven Exeutive 3
EDX Supervisr 32KB Appliatin 64KB 96KB 4955 large single appliatin, $SYSCOM 4KB EDX SUPERVISOR 24KB Appliatin 1 14KB $SYSCOM Appliatin 2 54KB 96KB 4952 2 appliatin spaes Shared ($SYSCOM) area EDX Supervisr 26KB Indexed Aess Methd 16KB COBOL Appliatin 128KB 4952 r 4955 large COBOL appliatin using Srt and Indexed Aess Methd Send COBOL appliatin als utilizing Indexed Aess Methd Indexed Aess Methd whih serves bth COBOL appliatins plus - Srt/Merge (buffer spae expanded by 2K bytes) COBOL Appliatin 22KB 48KB SORT/MERGE 16KB Figure 1. Pssible Strage Cnfiguratins 4 Versi n 1.1 Planni ng GUt de
SOURCE PROGRAM COMPATIBILITY COBOL and FORTRAN prgrams are mpletely sure mpatible and require nly that they be rempiled using Versin 1.1 f the COBOL r FORTRAN mpiler. An additinal mdule f less than 200 bytes will be autmatially inluded (by Autall) during link-edit. Exeutin f COBOL prgrams will require Versin 1.1 f the COBOL Transient Library. Versin 1.1 f COBOL and FORTRAN will be available nurrent with Versin 1.1 f supervisr and will be autmatially shipped t existing liensees. Event Driven Language (EDL) and Series/1 Assembler Language prgrams that use standard appliatin interfaes are sure mpatible. Refer t the tpi belw titled "Appliatin Prgram Interfaes" fr a list f sure mpatible interfaes. Hwever, any prgrams with expliit dependenies n aess t the system area may: 1. Be required t exeute in partitin 1 nly s that unrestrited aess t the system area is pssible. 2. Require that the ptin t map sme r all f the system area int eah partitin be used t prvide the ability t referene system area ntrl blks. 3. Require sure mdifiatin t utilize the rss address spae apabilities added t varius funtins in Versin 1.1. Rempilatin f the Event Driven Language r assembler language prgrams requires Versin 1.1 f the apprpriate prgram preparatin vehile. All these releases will be available nurrent with Versin 1.1 f the Supervisr and Emulatr and will be autmatially shipped t existing liensees. The fllwing prgram preparatin vehiles may be used: 1. Prgram Preparatin ($EDXASM) Versin 1.1 (fr prgrams nsisting exlusively f Event Driven Language statements). 2. Mar Library Versin 1.1 and Mar Assembler Versin 1.1. If it is desired t mpile prgrams n Versin 1.0 fr later exeutin n a Versin 1.1 system, the Versin 1.1 Mar Library an als be used with the Versin 1.0 Mar Assembler. 3. Mar Library/Hst Versin 1.1 and any urrent release f the Series/1 370 Hst Assembler. Appliatin prgrams that ntain Series/1 assembler language instrutins will require 1-3 additinal mdules t be link-edited with the appliatin. These mdules are Part 1: Event Driven Exeutive 5
prvided with the Versin 1.1 supervisr fr the purpse f handling the speial interfae used by assembler language rutines under EDX. Mst assembler language appliatins will require nly the basi RETURN interfae mdule (abut 40 bytes) but sme appliatins may require additinal mdules that supprt the speial interfaes SVC, SETBUSY and SUPEXIT. The interfae mdules ttal apprximately 200 bytes and an be autmatially inluded where needed with the AUTOCAll faility f $link if EXTRN statements fr the desired mdules are inluded with the prgram. See the "Speial Cnsideratins" tpi fr mre infrmatin. APPLICATION PROGRAM INTERFACES The primary appliatin prgram interfae is dumented in the Event Driven Exeutive language Referene manual. Users f COBOL r FORTRAN may als view their respetive language referene manuals and users guides as their interfae. In additin t these, ertain ther interfaes and data areas are available fr referene and use by appliatin prgrams. These are the fllwing: The Branh interfaes named RETURN, SETBUSY, SUPEXIT and SVC and their respetive parameter lists. The CAll interfae fr DSOPEH, inluding its parameters and data area. The CAll interfae fr SETEOD inluding its parameter list and data area. The fllwing interfaes as desribed Cmmuniatins Guide: BSCOPEN, BSCClOSE, BSCWRITE, BSCIOB, and TP (all funtins). in the BSCREAD, The first tw wrds f the Task Cntrl Blk (TCB) system data area. The first tw wrds f the Data Set Cntrl Blk (DSCB). Prgrams shuld use nly the abve interfaes s that they wi 11 be sure-statement mpati ble arss releases f EDX. 6 Versin 1.1 Planning Guide
DATA SET COMPATIBILITY Data sets reated r updated using Versin 1.0 an be used n Versin 1.1 withut hange. FUNCTIONAL CONTENT COMPATIBILITY All the funtins defined in the Language Referene Manual, the Utilities Operatr Cmmands and Prgram Preparatin and the Cmmuniatins Guide fr Versin 1.0 are als supprted by Versin 1.1. STORAGE SIZES Versin 1.1 f the Supervisr and Emulatr is slightly larger than Versin 1.0. Fr planning purpses yu may assume that the system area f idential nfiguratins will inrease by apprximately 5% fr a nfiguratin with 64KB r less and by apprximately 10% fr nfiguratins with mre than 64KB f strage. Atual inreases will depend n the partiular funtins inluded in eah system. Systems installed n a 4952 pressr with 128KB f strage will gain the use f up t 32KB f additinal strage in return fr the 2-4KB inrease in ntrl prgram size. Users f the 4955 pressr with greater than 64KB will als find that the inrease is ffset by appliatin imprvements made pssible by the availability f larger appliatin spaes and the new multi-partitin extensins. Ptential benefits inlude the ability t avid the need fr mplex verlays r appliatins that must be split apart s they an be exeuted in separate partitins, and the ability t keep mre data in strage instead f spilling it t disk t save spae. Changes in prgram size are expeted t be minimal fr mst appliatins written in the Event Driven Language. A straightfrward prgram with a single task and n attentin lists (ATTNLIST) will inrease abut 50 bytes. Eah attentin list will expand abut 120 bytes (see "Speial Cnsideratins" fr mre infrmatin n ATTNLIST). Prgrams ntaining Series/l assembler language de (inluding all COBOL and FORTRAN prgrams) will require an additinal 50 t 200 bytes beause f the inlusin f the interfae mdules desribed in the setin n "Sure Prgram Cmpatibility." Part 1: Event Driven Exeutive 7
MULTI-PARTITION EXTENSIONS As part f the hanges in the address translatr supprt several system funtins have been altered t ammdate the new envirnment. These hanges remve many f the restritins f the Versin 1.0 address translatr and allw appliatins written in the Event Driven Language r assembler language t take maximum advantage f the multi-partitin envirnment. With the Versin 1.1 address translatr supprt it is pssible t: Mve data diretly frm the exeuting prgram's partitin t anther, r vie versa, using the MOVE instrutin. Enqueue r dequeue (ENQ/DEQ) n a resure (QCB) in anther partitin withut the use f a mmn area ($SYSCOM). LOAD a prgram in anther partitin and pass parameters t it r wait fr its mpletin. READ r WRITE using a buffer in a partitin ther than the exeuting prgram's. ATTACH a task in anther partitin. WAIT r POST an event (ECB) in a partitin ther than the invker's and withut a mmn area ($SYSCOM). (~~, \ 1\'1~"=J') Late a prgram by name and determi ne its address and partitin. This allws independently laded prgrams t find eah ther at exeutin time withut using a mmn area ($SYSCOM). DIAGNOSTIC AND RECOVERY IMPROVEMENTS I/O ERROR RECORDING Inluded in Versin 1.1 is the ptinal ability t lg the urrene f hardware errrs n a data set. This faility, whih is used by EDX devie servies and is available t user-written devie handlers and EXIO users, prvides errr data t assist in the detetin and rretin f hardware errrs. A utility t print the ntents f the lg data set is inluded. 8 Versi n 1.1 Planni ng Gui de
TASK ERROR EXIT Appliatin prgrams an elet t press errrs themselves instead f relying n standard system atins. This enables diagnsti and revery atins t be tailred t eah user's appliatin envirnment. Eah task an identify a rutine t reeive ntrl if a pressr malfuntin r prgram exeptin urs during the exeutin f the task. If an errr urs, exeutin f the task is resumed at the task errr exit rutine in lieu f the standard system atin f terminating the task. SYSTEM AREA PROTECTION Islatin f the system area frm all but ne appliatin partitin nstrains mst appliatin errrs t a single partitin instead f allwing impat t the entire mahine thrugh damage t the system area. C' ~ PROGRAM EXCEPTION TRACE Prgram exeptin data an be aptured in an in-strage table, prviding a hrnlgial histry f exeptinal nditins fr use in debugging. STORAGE DUMP A strage dump utility prvides the ability t stp n prgram exeptins and rerd the ntents f the strage in a data set. A send utility prints the dump data set. SPECIAL CONSIDERATIONS Certain interfaes and implementatin tehniques have been affeted by the Versin 1.1 address translatr hanges. Appliatin prgrams that use any f the interfaes r tehniques desribed in this setin will require review t determine if hanges will be neessary r desirable in the new exeutin envirnment prvided by Versin 1.1. These nsideratins are in additin t thse listed under "Cmpatibility." Part 1: Event Driven Exeutive 9
REFERENCES TO SYSTEM AREA DATA Appliatins that depend n expliit referene t data (ntrl blks) in the system area are definitely affeted by the new multi-partitin envirnment beause the system area is nt addressable by the prgram unless speial atin is taken. Data areas suh as the DDB (disk), CCB (terminal) and CMDTABLE (mmand Table) are nt generally aessible in a multi-partitin system. There are three apprahes that an be used t mve appliatins with this dependeny nt a multiple partitin Versin 1.1 system. n V 1. Exeute the appliatin in partitin 1 nly. Sine the system area als resides in partitin 1, the appliatin will have unrestrited aess t it withut the need fr any hanges. 2. Map sme r all f the system area int every partitin s that the desired data areas are aessible frm every partitin. This requires generatin f a system using a new, ptinal parameter n the SYSTEM statement, but it requires n hanges t the appliatin prgram. 3. Alter the appliatin t use the new multi-partitin funtins t btain the desired data. Sme appliatins may be able t use the new funtins exlusively instead f depending n diret use f the system area. This is remmended where pssible beause the ntent and frmat f the system area are subjet t hange. In additin, it shuld be pssible t eliminate the need fr $SYSCOM frm many appliatins. INVOKING PROGRAMS THAT RESIDE IN THE SYSTEM AREA Certain prgrams that reside in the system area may be branh-entered by assembler language appliatin prgrams. Only the fllwing fur entry pint names are supprted: RETURN, SVC, SETBUSY and SUPEXIT. T use these entry pints in a Versin 1.1 system it will be neessary t link-edit ($LINK) additinal mdule(s) with the appliatin prgram. N sure de mdifiatins are required. The additinal mdules, whih are prvided with the Versin 1.1 supervisr and emulatr, are abut 200 bytes in ttal size. Only the mdulecs) required fr the partiular entry pintcs) in the prgram need be inluded. Mapping the system area int all partitins des nt eliminate the requirement t use the linkage mdule. 10 Versin 1.1 Planning Guide
USER-WRITTEN SUPERVISOR EXTENSIONS In general, user-written extensins t the supervisr will require areful review fr dependenies n addressing data in the appliatin's partitin. The keybard task will always exeute with address key 0 beause it physially resides in partitin 1. Change Partitin ($CP) will n lnger hange the pressr address key register; instead the new partitin value will be plaed in a TCB field, TCBADS. System funtins must use this field t determine the atual partitin in use. The TCBAKR field shuld nt be used fr this purpse. VIRTUAL TERMINALS ( \ ~/ Appliatins that use virtual terminals may require mdifiatin if the TERMINAL statement defining the virtual terminal is ntained in the appliatin prgram rather than in the system nfiguratin mdule ($EDXDEFS). Cmmening with Versin 1.1, all TERMINAL statements must be in partitin 1 and appliatin prgrams in ther partitins must use an IOCB statement t gain aess t the virtual terminal. T help prvide sure mpatibility, TERMINAL statements ded in appliatin prgrams will autmatially be nverted t IOCB statements during assembly. Hwever, TERMINAL statements with the same names and parameters as thse in the appliatin prgram must be added t the system nfiguratin mdule ($EDXDEFS). The fllwing example, whih is explained in the "Advaned Tpis" setin, the Versin 1.0 System Guide, illustrates a typial use f virtual terminals: A B TERMINAL DEVICE=VIRT,ADDRESS=B,SYNC=YES TERMINAL DEVICE=VIRT,ADDRESS=A,END=YES ENQT B LOAD $TERMUT1,LOGMSG=NO,END=ENDWAIT ENQT A The result is a virtual hannel between $TERMUT1 and the prgram that laded it. In Versin 1.1 the TERMINAL statements in the example abve will atually generate the fllwing tw IOCB statements: Part 1: Event Driven Exeutive 11
A IOCB A B IOCB B The IOCB statements that replae the appliatin's TERMI NAL statements must pint t TERMINAL statements in the system nfiguratin mdule ($EDXDEFS). Therefre, fr this sample t wrk the fllwing tw statements must be added t the system nfiguratin mdule: A B TERMINAL DEVICE=VIRT,ADDRESS=B,SYNC=YES TERMINAL DEVICE=VIRT,ADDRESS=A,END=YES The effet f this hange is t inrease the size f the system area by abut 700 bytes and t derease the size f the virtual terminal appliatin by abut 640 bytes. Sine multiple prgrams an share the virtual terminal definitins (using ENQT) when they are part f the system nfiguratin, this may result in an verall derease in strage requirements. Hwever, prgrams that use the same virtual terminal pair an nt exeute at the same time. SENSOR I/O APPLICATIONS Appliatins using the speialized sensr I/O apabilities f EDX may be affeted by hanges in timing that ur in Versin 1.1. The speial press interrupt interfae (IODEF SPECPI) is slightly faster than in Versin 1.0 if the appliatin is exeuted in partitin 1 but is estimated t be 25-30 mirsends slwer (n a 4955 pressr) if exeuted in sme ther partitin. Prgrams with extreme time sensitivity shuld therefre use SPECPI TYPE=GROUP and be exeuted in partitin 1. The methd f return frm the SPECPI exit t the supervisr may als require mdifiatin. Fr SPEePI TYPE=GROUP there is n hange, but fr SPECPI TYPE=BIT a new return statement, SPECPIRT, is prvided. The Versin 1.0 tehnique, whih used register 7, is valid nly in partitin 1. The new statement, SPECPIRT will wrk in any partitin. USE OF ATTENTION LISTS (ATTNLIST) Prgrams that use ATTNlIST exits t prvide new mmands r interept existing system mmands may be affeted by a hange in the methd f exeuting attentin rutines. In Versin 1.0 the ATTNlIST rutine was exeuted diretly frm the keybard task fr the terminal in use. In Versin 12 Versin 1.1 Planning Guide
1.1, the keybard task is always exeuted in partitin 1 while the attentin exits themselves are exeuted in whatever partitin the exit prgram resides in. Therefre, the keybard task will ATTACH a speial ATTHlIST TCB t exeute the attentin exit. This speial TCB is autmatially reated when a prgram ntaining an ATTHlIST statement is assembled, inreasing prgram size by apprximately 120 bytes. The attentin rutine is exeuted in the partitin it resides in and therefre des nt have diret aess t the system area. If the attentin exit needs t referene the system area, refer t the setin n "Referenes T System Area Data." PROGRAM (HEADER) OR TCB DEPENDENCIES The PROGRAM header and TCB's that reside within the users' appliatin prgram have hanged slightly in size and frmat. Prgrams that referene r mdify these ntrl blks exept fr the first tw wrds f a TCB r a DSn (DSCB) may require sure de mdifiatin. While mst fields have hanged nly in ffset within the data area, n assumptins shuld be made abut mpatibility. In partiular, use f any reserved fields r fields that ntain address keys indiates that a hange wuld be required. IBM remmends against any dependeny n these data areas. &SYSCOM USAGE Appliatins that use a $SYSCOM shared area shuld nt require hange. Hwever, yu may wish t ntrl the plaement f the $SYSCOM CSECT t minimize the amunt f strage shared arss partitins. All strage latins frm 0 t the bundary speified in a new SYSTEM statement parameter are shared (mapped) by all partitins. Therefre it is usually advisable t inlude the $SYSCOM CSECT near the beginning f the supervisr lad mdule rather than at the high end. Part 1: Event Driven Exeutive 13
14 Versin 1.1 Planning Guide
PART 2: EDX MULTIPLE TERMINAL MANAGER OVERVIEW MULTIPLE TERMINAL MANAGER CONCEPTS The Series/l Multiple Terminal Manager (5719-MS1) is an appliatin prgram that perates under the Series/l Event Driven Exeutive. It prvides a set f high-level funtins that simplify the definitin f transatin-riented appliatins suh as inquiry, file update, data lletin, and rder entry. Transatin-riented means that prgram exeutin is driven by peratr atins, typially, respnses t prmpts frm the system. ( ~ / This prmpt-respnse-press yle between the prgram and the terminal peratr is the basi priniple fr the design f appliatins using the Multiple Terminal Manager. The Multiple Terminal Manager prvides the apability t define transatins and manage the prgrams whih supprt thse transatins. It als prvides management f multiple terminals as needed t supprt these transatins and their varius appliatin prgrams. The mpnents f the Multiple Terminal Manager are: A prgram/strage manager, whih ntrls the exeutin and flw f the appliatin prgrams within a single prgram area. A terminal/sreen manager, whih ntrls the presentatin f sreens and mmuniatins between terminals and appliatin prgrams. A file handling mehanism, whih simplifies the strage and retrieval f data n the bulk strage devies. The terminal manager simplifies suh transatins by: Autmatially prviding input and utput buffers fr the appliatin prgram. Perfrming I/O peratins t aess fixed sreen frmats frm the sreen file. Here, the term sreen refers t the image that is displayed n the sreen f an IBM 4979 r IBM 4978 Display Statin. Fixed-sreen frmats nsist f unmdifiable text and definitins Part 2: EDX Multiple Terminal Manager 15
f pssible areas fr data input. Sreens are built using the $IMAGE system utility. Returning ntrl t the user prgram t allw mdifiatin f the input buffer ntaining the sreen if desired. Perfrming the set f I/O peratins invlved in writing the sreen t the terminal, filling in unprteted fields with user-defined utput data, and reading the data entered by the peratr befre returning ntrl t the appliatin prgram that requested the atin. The terminal manager assumes that eah atin request invlves bth utput and input peratins, thus eliminating the need fr the appliatin prgram t make separate requests. In additin, the Multiple Terminal Manager prvides strage, file, and prgram management servies, terminal transatin statistis, the apability fr sign-n prgrams fr passwrd validatin, and errr revery fr I/O and prgram hek nditins. Multiple Terminal Manager appliatins an be written in the Event Driven language, Series/1 Assembler language, COBOL r FORTRAN IV. Disk I/O an be perfrmed by an appliatin prgram using indexed r diret aess methds. Terminal supprt is prvided fr lally attahed IBM 4979 and 4978 Display Statins and remte Teletype l ASR 33/35 mpatible terminals attahed using a single-line r multiline asynhrnus mmuniatin adapter. /'--\ \'=) The disk I/O funtin prvides the fllwing fr disk and diskette files: Indexed Aess Methd file supprt Diret file supprt Strage nservatin thrugh autmati pen and lse funtins. The TERMINAL file desribes the terminals t run with the terminal man~ger. In this file, yu speify the terminal type, the name f the terminal, the sreen t be used as the primary m~nu sreen, whether r nt sign-n is required, and fr asynhrnus terminals, the length f the input buffer. This flexibility allws yu t add r delete terminals withut rebuilding the terminal manager. 1 Trademark f the Teletype Crpratin. 16 Versin 1.1 Planning Guide
, C ' ',,;},1 Yur appliatin prgrams an be exeuted by way f a seletin frm the terminal menu r by a prgram. Only the prgram name is required. The Multiple Terminal Manager perfrms the peratins neessary t lad the prgram and ntrl its exeutin. Sreen frmats are used by appliatin prgrams and the Multiple Terminal Manager itself. Eah sreen is a data set in a vlume that defines prteted fields and ptinally defaults fr unprteted fields. Three sreens are predefined: The initial prgram lad (IPl) sreen that played when the Multiple Terminal Manager starts. is task disset The sign-n sreen (displayed if a sign-n predure is speified fr the terminal). A sample primary menu sreen fr prgram seletin. Hwever, yu an selet any sreen as a menu sreen. These sreens are prvided as samples and an be mdified t suit individual requirements. (Yu an define additinal sreens using the $IMAGE sreen build utility). The Multiple Terminal Manager respnds t an interrupt frm a terminal by lading the requested prgram speified by prgram name r prgram funtin key seletin. The terminal manager rutes subsequent peratr entries t the assiated prgram. Tw prgram funtin keys are reserved: PF3 - signals the Multiple Terminal Manager t terminate the urrent prgram and display the menu sreen PF6 - signal an still be defined t print the ntents f the urrent sreen n the system printer. HARDWARE The mlnlmum hardware nfiguratin required fr the Multiple Terminal Manager is as fllws: Ser;es/! pressr (either 4952 r 4955) with 96KB strage C,, '", ' Disk strage devie (either 4962 r 4963) An Event Driven Exeutive $SYSlOG devie. It is remmended but nt mandatry that this be a nn-multiple Terminal Manager terminal fr reeiving any system Part 2: EDX Multiple Terminal Manager 17
exe messages during the Multiple Terminal Manager utin. Display statin (either 4978 r 4979) Printer - IBM 4973 r IBM 4974 (t define a $SYSPRTR fr errr messages). The fllwing ptinal hardware is supprted: Additinal 4978 r 4979 terminal devies Teletype 2 devies nneted t an ACCA adapter Printers as supprted by EDX Versin 1.1 Additinal diret aess devies (disk r diskette) as supprted by EDX Versin 1.1 Additinal strage as supprted by EDX Versin 1.1. 2 Trademark f the Teletype Crpratin. 18 Versin 1.1 Planning Guide
/ / / --/--/--/ / / / / RJE EDl EDX lam Appli- Super- atins visr SORT/ --- MERGE t--- / 8 / COBOL Transatin Prgrams MTM Appli- - atin area 28K 14K 22K <----------ASO------------> -------- 48K 16K / <------------AS1--/------> / / 4978 Hardware: Pressr - 4952 Strage - 128K Printer - 4974 Disk - 4962-4 Diskette - 4964 Displays (5) - 4978 4978 Sftware: Event Dri ven -Exeut i ve V 1.1 Indexed Aess Methd (lam) COBOL library Multiple Terminal Manager (MTM) Remte Jb Entry (RJE) Event Driven language (EDl) Figure 2. Transatin Oriented System Part 2: EDX Multiple Terminal Manager 19
4978 A I I I I I I 64K I I I I I I I I v Supervisr 28K lam 14K RJE 16K ASO / / / /EP / / COBOL Transatin Prgrams 20K MTM 16K AS1 / / / - / - COBOL Cmpiler 32K 4978 AS2 / / / 4978 4979 Hardware: Pressr - 4955 Strage - 128K Printer - 4973 Diskette - 4964 Disk - 4963 BSC single line - 12074 Displays (5) - 4978 Sftware: Event Driven Exeutive Indexed Aess Methd (lam) COBOL Cmpiler COBOL Library Multiple Terminal Manager (MTM) Remte Jb Entry (RJE) Figure 3. Transatin Oriented/Prgram Develpment System 20 Versin 1.1 Planning Guide
SOFTWARE The mlnlmum sftware requirements fr exeuting the Multiple Terminal Manager under EDX are: EDX Supervisr Versin 1.1 (5719-XSl) EDX Utilities (S719-UT3). Prgram Preparatin Failities (5719-XX2), required fr prgram preparatin and installatin f Multiple Terminal Manager appliatins Additinal sftware supprted by Manager inludes: the Multiple Terminal EDX Indexed Aess Methd (5719-AM3) if indexed I/O will be used EDX FORTRAN (5719-F02) if FORTRAN appliatins are t be exeuted C'" \ PROGRAM OPERATION EDX COBOL (5719-CB3 and 5719-CB4) if COBOL appliatins are t be exeuted. The Multiple Terminal Manager is invked using the $l mmand. This will ause the Multiple Terminal Manager prgram manager t be laded int strage and ativated. The first prgram ativated by the prgram manager is the initializatin rutine. MULTIPLE TERMINAL MANAGER INITIALIZATION PROGRAM This prgram determines the number f terminals that are being ntrlled and prepares the tables and in-strage ntrl blks t supprt thse terminals. The initializatin rutine lads and initializes a terminal server fr eah terminal that is t be ntrlled by the Multiple Terminal Manager. When initializatin is mplete, ntrl is returned t the prgram manager. Part 2: EDX Multiple Terminal Manager 21
TERMINAL SERVER PROGRAMS The terminal server prgrams perfrm all input/utput and interrupt handling funtins fr thse terminal devies perating under the ntrl f the Multiple Terminal Manager. There is ne terminal server prgram fr eah terminal assigned t the Multiple Terminal Manager. () When a server prgram is first ativated by the initializatin prgram, it will display a base Multiple Terminal Manager message sreen and wait fr an interrupt frm the peratr. If a sign-n predure is required fr this terminal, the server will invke the sign-n predure and wait until an peratr has signed n prperly. After prper sign-n, the server will perfrm I/O peratins as needed t satisfy the requirements f peratr dialgues and the assiated appliatin prgram. The terminal servers use ENQ/DEQ and WAIT/POST mehanisms fr interfaing with the prgram manager. APPLICATION PROGRAM MANAGER The appliatin prgram manager prvides the Multiple Terminal Manager prgram management failities required t satisfy peratr requests. The prgram manager ntrls the ntents f the prgram area and the initializatin f prgrams within the area. The Multiple Terminal Manager is a transatin pressing subsystem whih exeutes as an appliatin prgram under the Event Driven Exeutive. The Multiple Terminal Manager transatins are initiated by a terminal peratr using a transatin seletin menu (als referred t as a prgram seletin menu). Prgrams an request single r multiple peratr prmpts, press the input, and then request additinal input r terminate. The Multiple Terminal Manager appliatins are autmatially nneted t a terminal when a transatin begins. The Multiple Terminal Manager in turn presses terminal I/O fr the these appliatins. The appliatins exeute within the managed prgram area, and are prvided prgram, terminal, sreen and file management servies thrugh alls t the Multiple Terminal Manager. Fr exampl~, a prgram exeuting under ntrl f the Multiple Terminal Manager displays a menu sreen ffering the peratr a hie f funtins. Based n the peratr's seletin, the appliatin prgram then perfrms pressing peratins, suh as reading infrmatin frm a data file, displaying the data at the terminal, and waiting fr the next respnse. 22 Versin 1.1 Planning Guide
PROGRA" "ANAGE"ENT The prgram management failities prvide the apability fr the ntrl f appliatin prgrams while perfrming their respetive transatinal presses within a single prgram area. Beause all f the Multiple Terminal Manager appliatin prgrams perate in the same prgram area, the Multiple Terminal Manager prgram management failities ntain the supprt needed t allw multiplex peratin and sharing f the prgram area. The appliatin prgrams using these prgram/strage management failities will always have the fllwing fur items assiated with them: 1. The appliatin prgram itself. This is the user-written de that perfrms the transatin pressing as required by the user. It will reside in the prgrams file and be laded int the in-strage prgram area by the manager. 2. The "swap ut" data set. This data set is used by the manager t save prgrams and data arss alls t ACTION, LINK, LINKON, CYCLE, and WRITE. 3. The input buffer. This buffer ntains the data that was last entered by the peratr when the urrent segment f the appliatin prgram is entered. This buffer als ntains the prteted haraters f the sreen display that the appliatin prgram is preparing fr the next dialgue with the peratr. Refer t Figure 4 fr additinal infrmatin. This buffer is autmatially allated by the Multiple Terminal Manager and is 1920 bytes lng. 4. The utput buffer. This buffer ntains the unprteted haraters f the sreen display that the urrent appliatin prgram is preparing fr the next dialgue with the peratr. These unprteted haraters an either be default values r the respnse t an peratr query. Refer t Figure 4 fr additi~nal infrmatin. This buffer is autmatially allated by the Multiple Terminal Manager and is 1024 bytes lng. The appliatin prgrams will interfae with these failities using the allable funtins desribed in the fllwi ng paragraphs. Part 2: EDX Multiple Terminal Manager 23
ACTION - Feth Operatr Respnse The ACTION funtin prvides the appliatin prgram with the ability t display a sreen and then t btain the peratr's input t a display n the terminal sreen. This all funtin shuld be preeded by ne f the alls t frmat the display buffer. When this funt~n is alled, the manager saves the infrmatin needed t return t the next sequential prgram instrutin when the ACTION funtin is mplete. The manager then mmuniates with the peratr at the prper terminal and nstruts the buffer t be returned t the alling prgram. While the manager is perfrming this peratin fr the alling prgram, the strage spae ntaining the alling prgram might be plaed (by the manager) with ne f the ther appliatin prgrams, thus allwing the sharing f the strage resure amng several appliatin prgrams. When the requested ACTION funtin has been mpleted and the strage has been freed by anther appliatin prgram, the manager will relad the alling appliatin prgram and return ntrl t that prgram at its next sequential instrutin. Figure 4 shws the status f the input and utput buffers when this funti n 1 s alled. LINK - Lad and Exeute Prgram The LINK funtin enables an appliatin prgram t mplete its wn exeutin by lading and exeuting sme ther appliatin prgram. One an appliatin perfrms a CALL LINK, that prgram will nt be returned t frm the manager, unless the manager detets an errr in the alling sequene t the LINK funtin; nsequently, instrutins fllwing a CALL LINK must be inluded t handle this prblem. Refer t Figure 5 fr mre infrmatin. Als, Figure 4 shws the status f the in~ut and utput buffers when this funtin is alled. LIHKON The LIHKOH funtin is a mbinatin f the funtins prvided by the ACTION and LINK funtins; that ls, it requests an peratr atin and, when this atin is mplete, lads and exeutes sme ther appliatin prgram. Figure 4 shws the status f the input and utput buffers when this funtin is alled. 24 Ver,sin 1.,1 Planning Guide
Buffer ntents upn Input buffer Output buffer return frm - Terminal peratr Data entered Blanks (X'40') by peratr - CAll link Blanks (X'40') Unhanged frm alling prgram - CAll linkon Data entered Blanks (X' 40' ) by peratr - CAll CYCLE Blanks (X'40') Unhanged - CAll SETPAN Prteted data Unprteted data frm new frm new sreen sreen panel panel ~ 1\ C I ;' Buffer ntents upn Input buffer Output buffer prgram exit by - CAll ACTION Write prteted Satter written data if CAll int unprteted SETPAN issued fields n sreen - CAll LINKON Same as by Same as by CALL CALL ACTION ACTION - CALL LINK Write prteted if CALL SETPAN issued Saved - CALL CYCLE Same as by Same as by CALL CAll LINK LINK Figure 4. Buffer ntents and usage during ntrl f the Multiple Terminal Manager prgram/strage manager. CYCLE - Suspend Current Terminal Appliatin The CYCLE funtin prvides an appliatin prgram with the apability f suspending itself t allw ther appli- Part 2: EDX Multiple Terminal Manager 25
atins r terminals t beme ative. After ther appliatins have had an pprtunity t exeute, the manager will relad the alling prgram and return ntrl t it at the next sequential instrutin after the all t CYCLE. Refer t Figure 4 fr mre infrmatin. MENU - Return t Multiple Terminal Manager Cntrl The MENU funtin prvides the appliatin prgrams with the apability f abrting their wn peratin and returning t the ntrl f the Multiple Terminal Manager base prgram with the peratr seletin menu displayed n the terminal. The peratr at a terminal an perfrm this same funtin with the PF3 key n his terminal. WRITE - Output t an Asynhrnus Terminal The WRITE funtin is prvided fr thse appliatins that use asynhrnus terminals suh as the Teletype 3 ASR 33. It auses the speified buffer ntents t be displayed n the speifi~d terminal. After the display has been written n the terminal, the appliatin prgram must then perfrm a CAll ACTION t reeive respnses bak frm the peratr. This funtin exeutes in a similar fashin t the funtins desribed under "Strage/Prgram Management" in that the appliatin prgram des nt remain in strage while the buffer is being written. Terminal/Sreen Management The terminal sreen management failities prvide yu with a simplified methd f perfrming the terminal handling funtins that yur appliatin prgram may require. In additin t prviding the means f perating with the Series/1 keybard/crt devies, the terminal/sreen manager als prvides failities fr handling ~synhrnus terminal devies. Appliatin prgrams using keybard/crt terminals may interfae t the terminal/sreen management failities thrugh fur allable funtins, while the interfaes with asynhrnus terminals will use nly ne allable funtin. Trademark f the Teletype Crpratin. 26 Versin 1.1 Planning Guide
SETPAN - Frmat the Input and Output Buffers The SETPAN funtin prvides the appliatin prgram with the ability t request that a speified sreen be retrieved frm the sreens file and laded int the input buffer. The sreen images in the sreens file will have been built using the $IMAGE utility. The ntents f this input buffer will then be displayed n the next all t ACTION, LINK, r LINKON. The sreen will be written n the terminal display with all psitins write-prteted exept thse in whih nulls (X'OO~) were defined. When this funtin is alled, ne f the parameters will speify the name f the sreen t be retrieved. SETCUR - Mve Cursr t Speified Psitin The SETCUR funtin prvides the appliatin prgram with the ability t identify the harater psitin at whih the terminal/sreen manager will display the ursr when the sreen is displayed. BEEP - Set Audible Alarm The BEEP funtin prvides the appliatin prgram with the ability f ativating the audible alarm n the next CALL ACTION as a signal t the terminal peratr. This funtin is ignred fr thse terminals that d nt have an audible alarm apability. CHGPAN The CHGPAN funtin is used t ntify the terminal manager f hanges t the number f prteted/unprteted haraters f a sreen panel in the input buffer s that the terminal manager will knw hw many unprteted data haraters t write n the next utput yle. Figure 5 is an example f an appliatin prgram that perfrms MTM funtins t nverse with an peratr, t allw ther appliatins t run, and t link t anther appliatin prgram. Part 2: EDX Multiple Terminal Manager 27
ENTRY--> * Start CALL SETPAN (1) CALL ACTION (2) * Press input buffer CALL CYCLE (3) * link t new prgram CALL LINK (4) * If LINK returns, it * was unsuessful * ERROR HANDLER (5) CALL MENU (6) Figure 5. Sample Appliatin Prgram 1. Read sreen image frm data set. Prteted data ges int the input buffer and unprteted data ges int the utput buffer. 2. The ACTION funtin writes prteted data frm the input buffer, and writes unprteted data frm the utput buffer. It then reads peratr inputs int the input buffer. 3. The CALL CYCLE suspends the prgram t allw thers t exeute. 4. The last all in this appliatin prgram terminates the prgram and starts the next ne. 5. An errr handling rutine in the event that the manager detets ~n errr in the all i ng sequene fr the LINK funtin. 6. The CALL MENU within the errr handling rutine terminates the urrent prgram and returns t the Multiple Terminal Manager with the basi menu displayed. 28 Versi n 1.1 Planni ng Gui de
File Management The file management failities prvide mmn, easy-t-use supprt fr all disk data transfer peratins as needed fr the appliatin prgrams. These failities prvide supprt fr bth indexed and diret files under the ntrl f a single allable funtin FILEIO (Perfrm Disk I/O) The FIlEIO funtin perfrms read and write peratins n the disk using either indexed r diret aessing f the infrmatin. Yu speify the desired peratin t the prgram using a file ntrl area. This is a allable funtin, and the alling prgram will remain in strage while the peratin is taking plae. FIlEIO ( ~ J FIlEIO prvides the faility t aess previusly reated files using the all interfae desribed earlier. These files must have been previusly defined and laded using an ffline user-written utility. Figure 6. FIlEIO CAll FIlEIO,(FCA),(BUFFER),(RETURN CODE) The alling parameters are: File Cntrl Area (FCA) - Address f a table with the parameters desribing the requested peratins: BUFFER - Address f the user prgram I/O buffer. This is in the user prgram spae. FIlEIO and Indexed Aess Methd have their wn buffers. RETURN CODE - Address f the 2-byte field t ntain the return de passed bak by FIlEIO. This an be a FIlEIO return de, r it an be passed thrugh frm the Indexed Aess Methd. Part 2: EDX Multiple Terminal Manager 29
Request type Data set name Key relatin peratr r number f rerds Key length Key lati~ r lgial EOD rerd number Relative rerd number Vlume name Figure 7. File Cntrl Area Indexed File Request Types REtS REtR PUTU PUTD Funtin Release frm sequential pressing mde Release frm randm pressing mde Put peratin, update mde Put peratin, delete mde /-----\ \".J PUTN GETD GETS IDEt lets GTRU Put peratin, new mde-adds a rerd t fi Ie Get peratin, diret read Get peratin, sequential read Delete peratin Clse an indexed data set Diret get, update mde the GTSU Sequential get, update mde 30 Versi n 1.1 Planni ng Gui de
Djret File Request Types Funtin READ WRIT SEOD Read the rerd defined by the RRN field f the FCA int the user-prvided buffer. Write the rerd defined by the RRN field f the FCA int the majr user-prvided buffer. Set the system-maintained EOD pinter t the rerd number prvided in the relative rerd number field f the FCA. Multiple Terminal Manager utilities The utility prgram supprt nsists f peratr servie funtins that assist yu in the peratin f the Multiple Terminal Manager system. Terminal Ativity Reprt. This reprt utility enables yu t display the names and urrent status f the terminals under ntrl f the system. Terminal Cnnetin Failities. Prvides the peratr with the failities t disnnet and rennet terminals during the nrmal Multiple Terminal Manager peratin. These servies are perfrmed by the tw peratr mmands! Disnnet - Turn Off Speified Terminals. This faility prvides the peratr with a means f shutting dwn individually-speified, r all terminals, n the Multiple Terminal Manager system. If the peratr requests that a terminal that is urrently invlved in a transatin is t be disnneted, that terminal will be allwed t mplete its assiated transatin befre being disnneted. Rennet - Turn On Speified Terminals. This faility prvides the peratr with a means f restring a disnneted terminal bak int peratin. Prgrams Reprt. Prints infrmatin abut available prgrams. Part 2: EDX Multiple Terminal Manager 31
,, APPLICATION DESIGN INFORMATION PROGRAMMING CONSIDERATIONS The Multiple Terminal Manager appliatins are pressed as initial tasks f a prgram whih exeute within the prgram manager's verlay area. On the first exeutin f a prgram during a transatin, the prgram is brught int the verlay area by a LOAD. Then, when the prgram returns t the Multiple Terminal Manager thrugh a CALL ACTION, WRITE, CYCLE, MENU, LINK r LINKON, the Multiple Terminal Manager dequeues the prgram frm the system using DETACH. Als, if the prgram returned using a CAll ACTION, WRITE r CYCLE, the Multiple Terminal Manager writes the prgram ut t the MTMSTORE data set. The verlay area is then free fr use by ther prgrams. When the Multiple Terminal Manager is ready t reexeute that prgram fr subsequent pressing f the transatin, the prgram manager reads the prgram int the verlay area and requeues that prgram t the system using ATTACH. 0,... 11 1 ' Thus, the Multiple Terminal Manager transatin prgrams shuld adhere t the fllwing nventins: N subtasks shuld be ative arss alls t the Multiple Terminal Manager N system-wi de resures shuld be enqueued arss alls t the Multiple Terminal Manager Transatin prgrams annt use verlays Transatin prgrams shuld be written as main prgrams with the expetatin f reeiving fur parameters at initiatin Transatin prgrams shuld use the Multiple Terminal Manager fr all terminal and disk I/O All ther I/O shuld be mplete arss alls t the Multiple Terminal Manager Transatin prgrams shuld terminate nly with alls t the Multiple Terminal Manager and shuld nt issue any PROGSTOP, ENDTASK, r DETACH instrutins Errr handling rutines shuld terminate with a CALL MENU. 32. Versin 1.1 Planning Guide
MULTIPLE TERMINAL MANAGER DATA SET REQUIREMENTS MTMSTORE the Multiple Terminal Manager wrk file, n MTMSTORE, tains: The Multiple Terminal Manager prgram table The Multiple Terminal Manager sreen table A prgram and buffer save area fr eah terminal defined in the TERMINALS speifiatins file. The size f the MTMSTORE file an be alulated as fllws: Allw 10 bytes per sreen in the SCRNS vlume; rund up t the nearest setr Allw 12 bytes per prgram in the PRGRMS vlume; rund up t the nearest setr Allw per terminal: 1. Enugh setrs t hld a py f the largest prgram in the PRGRMS vlume 2. Fur additinal setrs fr full sreen devies. This data set is in the vlume MTMSTR. TERMINAL This file is built with the $FSEDIT system utility. It ntains ne rerd/terminal ntaining the speifiatin f a terminal. Dvtp~Termname~Menusrn~Y/N Dvtp Type f terminal. Enter: Termname Menusrn 4979 IBM 4979 full sreen 4978 IBM 4978 full sreen 3335 ASR 33/35 line at a time 1- t 8-harater name f a terminal. This name must be idential with the devie name speified n the EDX TERMINAL statement at SYSGEN. This name shuld nt be the $SYSLOG devie. The data set name f the sreen t be displayed after an peratr exits a transatin r signs n. Fr asynhrnus terminals, this field is Part 2: EDX Multiple Terminal Manager 33
Y/M ignred. Y = Thi s t,ermi na'l is requi red t use the SIGN-ON and SIGNOFF prgrams. If a user prgram named SIGH-ON des nt appear in the prgram library, this terminal is nt usable. N = This terminal is always si gned n. Cmment rerds are aeptable in thi s fi Ie as well as mments fllwing speifiatin rerds. Cmment rerds must have an * in psitin 1. An example f this file wuld be: 4979,DISPLAYl,MENUSCRN,n 4978,DIS49780,MENUSCRN,y 3335,ACCA1,MENUSCRN,y /* End f speifiatins must be indiated with a /* rerd. Befre pressing eah rerd during task set startup, the rerd is listed n $SYSPRTR. When startup is mplete, all terminals will have the Multiple Terminal Manager IPL sreen displayed. The terminal data set is in the vlume PRGRMS. Sreen Frmat Vlume - SCRNS This vlume ntains sreen panel data sets fr full sreen images built using the $IMAGE system utility. These sreens must have been built with a 24x80 dimensin size. User Appliatin Prgram Vlume - PRGRMS All prgrams laded by the Multiple Terminal Manager are laded using the names f the data sets n this vlume. The terminal file is als in this vlume. Appliatin prgrams are stred in this vlume as the utput f the $UPDATE utility. The names f the prgrams are the names used by the peratr frm the MENU mde t invke prgrams and an als be used as the prgram parameter n a CALL LINK frm ne prgram segment t anther. When the Multiple Terminal Manager is initiated, a prgram table is 'built ntaining the name f eah prgram data set in the PRGRMS vlume. 34 Versi n 1.1 Planni ng Gui de
Eah prgram is heked t determine if it is t big fr the prgram area in the Multiple Terminal Manager. If this urs, the user shuld split the prgram int segments using LINK r inrease the size f the prgram area. Sign-On File - SIGNONFL This file ntains sign-n rerds fr use by the SIGN-ON prgram. The frmat f the file is: Field Name Psitins Cntents EMPLOYEE 1-08 Emplyee number PASSWORD 9-12 Passwrd USERID 13-16 User ID USER CLASS 17-20 User lass NAME 21-32 Emplyee name This file is built by using the $FSEDIT EDX utility. This fi Ie is in the vlume PRGRMS. A /* in lumns 1 and 2 dente the end f the file. OPERATOR INTERFACE Multiple Terminal Manager Initializatin The Multiple Terminal Manager an be initiated frm any terminal defined t the system by entering the $L $MTM,PRGRMS mmand. The $L $MTM mmand will ause the Multiple Terminal Manager prgram manager t be initiated. The prgram manager will then initiate a terminal server fr eah terminal speified in the TERMINAL file. Upn mpletin f initiatin, the IPL sreen, IPLSCRN, will be displayed at eah f the Multiple Terminal Manager terminals. IPLSCRN will speify that the peratr press the enter key in rder t display either the sign-on r menu sreen. The data set IPLSCRN is displayed n eah full sreen terminal after the Multiple Terminal Manager ;s started. It requests that the peratr press the enter key t nnet the terminal t the Multiple Terminal Manager. It shuld nt be displayed again. Part 2: EDX Multiple Terminal Manager 35
Fr exeutin VOL ID Data set name Size 0 SwalJ data set MTMSTR MTMSTORE See MTM data Prgram manager PRGRMS CDMPGMGR 36 Setrs 4978/4979 term server PRGRMS CDMFlSCR 6 Setrs TTY term server PRGRMS CDMTTY 6 Setrs MTM initializatin PRGRMS CDMINIT 22 Setrs Terminal speifiatins PRGRMS TERMINAL 4 Setrs (appx) User appliatin pgms PRGRMS (User speified)??? set reqm'ts Sreen frmats SCRNS (User speified) 4 Setrs SCREENS Per sreen Sign-n file PRGRMS SIGNONFl 4 Setrs (appx) Fr prgram preparatin MTM stub (User speified) 8 Setrs MTM aut all list (User speified) 2 Setrs Fr rebuilding MTM MTM Sure (User speified) 2500 Setrs Nte: MTMSTR,PRGRMS,SCRNS must be defined at SYSGEN time as lgial vlumes. This may neessitate a remapping f the disk n whih they will reside. Figure 8. Summary f Multiple Terminal Manager Data Set Requirements. SIGN-ON If sign-n was speified fr the terminal, then the si gn-n sreen, si gn-n, wi 11 be di splayed fil OWl ng the IPl sreen. The sign-n sreen will require that the peratr enter a user-id and passwrd. After sign-n pressing has been mpleted, then the menu sreen will be displayed. PROGRAM INITIATION AND TERMINATION After the Multiple Terminal Manager initiatin and si gn-n pressi ng have been mpleted, then the menu sreen is displayed. The menu sreen is the sreen frm 36 Versi n 1.1 Plann; ng Gui de
whih the peratr an initiate transatins. A transatin is initiated by the peratr entering either a prgram name r pressing a PF key when the menu sreen is displayed. A PF key will initiate prgram PFOn where n reflets the number f the PF key pressed. If data is entered, the Multiple Terminal Manager will nsider the first eight bytes t be a prgram name. After a transatin is initiated, the peratr an terminate it by pressing the PF3 key. Upn terminatin f the transatin, the menu sreen will be redisplayed. Subsequently pressing the PF3 key frm the menu sreen will ause the sign-n sreen t be redisplayed if sign-n was speified fr that terminal. Otherwise, PF3 will be a n-p and the menu sreen will remain displayed. DISCONNECT Terminals an be disnneted frm the Multiple Terminal Manager r the Multiple Terminal Manager an be terminated via the DISCONNECT faility. DISCONNECT is invked frm the menu sreen by keying in either DISCONNECT,termname r DISCONNECT,ALL. If a referened terminal is in a transatin, that transatin is allwed t mplete. When the terminal returns t MENU state, it is autmatially signed ff and displays the YOU ARE DISCONNECTED message. Terminals in MENU state are signed ff immediately. If ALL is speified, all terminals are disnneted. When the last terminal is truly disnneted, whether using ALL r separate disnnets, the manager task is stpped. T enter ~his mmand frm a menu sreen, the sreen must ntain at least nineteen unprteted haraters. While a terminal ntinues in a transatin with disnnet pending, the audible alarm is sunded after every interatin t tell the peratr that a disnnet is pending. RECONNECT If the referened terminal is disnne~ted, it is renneted in a signed-ff status if appliable. If it is nt disnneted, the mmand is ignred. Part 2: EDX Multiple Terminal Manager 37
PROGRA"S REPORT This reprt displays data frm the prgram table abut eah available prgram. It is intended mainly fr debugging during develpment f the manager but is inluded as a wrking example fr pssible use. The prgram name fr this prgram is PGMRPT. TER"INAL ACTIVITY REPORT This prgram displays the names and status f all terminals n the system. If mre than 22 terminals are attahed, the peratr must press ENTER t page t suessive grups f 22 lines. The prgram name fr this prgram is REPORT. SCREEN PRINT Terminal displays an be printed n the system printer using the PF6 key t invke the system's print sreen faility. EDX print sreen faility. This entails pressi ng the PF6 key. DISTRIBUTION AND INSTALLATION The Multiple Terminal Manager will be distributed as a liensed prgram and will nsist f the fllwing items: Prebuilt Multiple Terminal Manager - This will be a ready t lad prgram nsisting f a prgram manager, file manager, terminal servers and sample prgrams. Multiple Terminal Manager sure - This will be the mplete set f the Multiple Terminal Manager sure de fr the user wh wants t tailr his Multiple Terminal Manager envirnment. Appliatin Stub - This will be the Multiple Terminal Manager stub in bjet frmat that the user must inlude with his appliatin prgrams at link time. 38 Versin 1.1 Planning Guide
Appliatin Stub AUTOCALL List - This 15 the aut list that the user will use at link time t ause the appliatin stub t be appended t his prgram. Sreen Frmats - This will be a set f sreens t supprt the default Multiple Terminal Manager and sample prgrams. Terminal File - This will be a set f misellaneus terminal statements t supprt the default system. The user must reate the fllwing vlumes n his system disk: PRGRMS - This vlume is fr the Multiple Terminal Manager prgrams, user appliatin prgrams and the terminal speifiatins file. SCRNS - This vlume is fr the sreen frmats used by the Multiple Terminal Manager and user appliatins. MTMSTR - Cntains nly the MTMSTORE data set. This the Multiple Terminal Manager swap file. After the vlumes have been reated, the user an then py the prebuilt Multiple Terminal Manager, sreen frmats and terminal file frm the shipped diskettes t disk. This will install the default Multiple Terminal Manager and establish the fllwing data sets. Data sets within the PRGRMS Vlume: CDMPGMGR CDMSVR89 CDMSVR33 Multiple Terminal Manager prgram manager Multiple Terminal Manager full sreen, 4978 and 4979, terminal server Multiple Terminal Manager TTY terminal server CDMINIT Multiple rutine Terminal Manager initializatin TERMINAL Multiple Terminal Manager terminal speifiatin file ther Misellaneus data sets needed fr the sample prgrams Data sets within the SCRNS Vlume: 0 ',,'I IPLSCRN SIGN-ON The initial Multiple Terminal Manager sreen The sign-n sreen started Part 2: EDX Multiple Terminal Manager 39
MENUSCRN ther The default menu sreen Misellaneus sreen data sets needed fr the sample prgrams If the user wants t tailr his Multiple Terminal Manager, then he an re-assemble, re-build and replae the hanged Multiple Terminal Manager mpnents. The user an then mdify his terminal speifiatins file t math his system envirnment by using the $FSEDIT system utility. He an als add sreen frmats t the SCRNS vlume using the $IMAGE system utility. Befre exeuting the Multiple Terminal Manager, the user has t reate the MTMSTORE data set; refer t Figure 8 fr the MTMSTORE requirements. PROGRAM PREPARATION During prgram preparatin, the user must ensure that the link phase inludes the Multiple Terminal Manager shipped AUTOCAll list and appliatin stub in rder t reslve CAlls t the Muftiple Terminal Manager funtin rutines. After linking his appliatin prgrams with the Multiple Terminal Manager appliatin stub, the user then must stre the prepared prgram in the PRGRMS vlume using $UP DATE. PERFORMANCE INFORMATION The infrmatin shwn in Figure 9 may be used fr perfrmane planning purpses. The basis fr the infrmatin is frm mdelling the Multiple Terminal Manager system. While the mdelling results prvide sme general guidelines as t the perfrmane f the system, it shuld be nted that the mdels are nly partially validated fr the wrklads mdelled. Other wrklad assumptins may prvide a different set f perfrmane results. As a general guideline t Multiple Terminal Manager perfrmane, the mean expeted respnse time shuld be less than r equal t 3 sends with 1 t 4 terminals. The perfrmane may exeed this range. Mean expeted respnse time is the average respnse time experiened frm when the user presses the enter key until the first harater f the respnse is displayed. ~ Versin 1.1 Planning Guide
3.0 CII "'0 C 0 (,) OJ CII C 2.5 2.0 OJ E.;::; 1.5 OJ CII 0 0. CII. 0: OJ 1.0..... (Simple file update with lam) (Simple file inquiry 0.5 withut lam) 2 3 4 5 6 7 8 9 10 C: Number f terminals Figure 9. Multiple Terminal Manager Perfrmane Trends Figure 9 shws the respnse time results fr eah f the transatins. The highest set f respnse times was ahieved under a mplex file update transatin and the lwest was with a nn-indexed Aess Methd simple file inquiry. With all these ases the respnse time was under 2 sends. A key variable t respnse time results is the think plus key-in-time assiated with a set f terminals. When this variable is very shrt, the system resures may be stressed and an result in higher respnse times. When this variable is inreased, the mean respnse time will be smaller. Refer t Figure 10 fr a definitin f the transatins used in the mdel. The think mean plus key-in-time fr the mdelling was 20 sends. Part 2: EDX Multiple Terminal Manager 41
Prgram lam Number f Number f appliatin 0 ll!.e.g size Database disk I/O instrutins exeuted Simple 22K GETD 4 27.8K inquiry Simple file 22K GETD, 5 28.7K inquiry/ PUTU update Simple file 15.6K 2 15.6K inquiry (nn-lam) Cmplex file 48K GETD, 10 41.9K update GETD, PUTU Figure 10. Transatin Desriptin The fllwing were the mdelling assumptins: Cnfiguratin Wrklad -4955 (translated) -4963 (1 unit) -4978 display terminals -Adequate strage -Indexed Aess Methd -Transatin rate f 3 per minute per terminal -20 sends (expnential) think plus key-in-time -COBOL and Indexed Aess Methd appliatin 42 Versi n 1.1 Planni ng Gui de
PART 3: EDX INDEXED ACCESS METHOD OVERVIEW The Indexed Aess Methd Liensed Prgram (5719-AM3) is a data management system that perates under the IBM Series/l Event Driven Exeutive. It prvides yu with an Event Driven Language allable interfae t build and maintain an indexed data set and t aess, by key r sequentially, yur rerds in that data set. In an indexed data set, eah f yur rerds is identified by the ntents f a predefined field alled a key. The Indexed Aess Methd builds int the data set an index f keys that prvides fast aess t yur rerds. INDEXED DATA SET FEATURES Fr yur appliatins using indexed data sets, the Indexed Aess Methd ffers several useful features: Diret and sequential pressing. Multiple levels f indexing are used fr diret aess, and sequene haining f data blks is used fr sequential aess. Supprt fr high insert and delete ativity withut signifiant perfrmane degradatin. Free spae is distributed thrughut the data set and in a free pl at the end s that inserts an be made in plae; spae prvided by deletes an be immediately relaimed. Aess t a. single data set by several requests nurrently. These requests an exeute frm the same r different prgrams. Data integrity is maintained by a file-, blk-, and rerd-level lking system that prevents aess t that prtin f the file that is being mdified. Implementatin as a separate task. A single py f the Indexed Aess Methd exeutes and rdinates all requests. The buffer pl supprts all requests and ptimizes the spae required fr physial I/O; in the user prgram the nly buffer required is the ne fr the rerd urrently being pressed. An Indexed Aess Methd utility prgram ($IAMUTl) whih exeutes as a user prgram, and allws yu t reate, frmat, lad, unlad, and rerganize an indexed data set. Part 3: EDX Indexed Aess Methd 43
DATA PROTECTION The Indexed Aess Methd perfrms all input/utput perat~ns by using system funtins. Therefre, all data prtetin failities ffered by the system als apply t the indexed data sets. The fllwing additinal data prtetin is prvided by the Indexed Aess Methd: Exlusivity ptin. As a user f the Indexed Aess Methd, yu speify n the PROCESS r LOAD request that the data set is fr use exlusively. This allws yu t impse additinal ntrl where needed. Rerd lking. The Indexed Aess Methd ially prevents tw users frm using the rerd at the same time. Immediate write-bak. This ptinal feature prvides the apability f having all updated rerds written immediately t the data set. autmatsame data Aidental key mdifiatin. If yu attempt t mdify the key field in ne f yur data rerds, the Indexed Aess Methd prevents the mdifiatin frm urring. This helps ensure that yur index and data math. DEVICES SUPPORTED The Indexed Aess Methd supprts indexed data sets n these diret-aess devies: IBM 4962 Disk Strage Unit IBM 4963 Disk Subsystem IBM 4964 Diskette Strage Unit IBM 4966 Diskette Magazine Unit COMPONENTS The Indexed Aess Methd nsists f the fllwing mpnents: A lad mdule that supprts the exeutin f yur prgrams, whih ntain the Indexed Aess Methd requests. Indexed Aess Methd funtins are initi- 44 Versin 1.1 Planning Guide
ated by yur prgrams thrugh a CAll interfae. A set f bjet mdules that yu may use t generate a ustmized Indexed Aess Methd lad mdule (a read nly system, fr example). If yu use the supplied lad mdule, yu d nt need the bjet mdules. An bjet mdule, alled a link mdule, whih yu inlude with yur prgram t prvide the interfae t the Indexed Aess Methd. This link mdule is smetimes alled a stub. A set f py de mdules. Yu an referene these mdules frm yur prgrams t define symbli labels used in Indexed Aess Methd requests. A lad mdule fr the Indexed Aess Methd utility prgram. FUNCTIONS Yu request the servies f the Indexed Aess Methd thrugh a all interfae. (CAllIAM,+FUNC,IACB,(PARM3),(PARM4),+PARMS). The fllwing funtins an be invked: PROCESS LOAD GET GETSEQ Builds an indexed aess ntrl blk (IACB) and nnets it t an indexed data set fr reading, updating, inserting, and deleting rerds. Yu an then use the IACB t issue requests t that data set. A prgram an issue multiple PROCESS funtins and btain multiple IACBs fr the same data set s that the data set an be aessed by several requests nurrently. Similar t PROCESS but allws lading r extending the initial lletin f rerds. Diretly retrieves a single rerd frm the data set. If yu speify the update mde, the rerd is lked (made unavailable t ther requests) and held fr pssible mdifiatin r deletin. Sequentially retrieves a single rerd frm the data set. If yu speify the update mde, the rerd is lked (made unavailable t ther requests) and held fr pssible mdifiatin r deletin. Part 3: EDX Indexed Aess Methd 45
PUT PUTUP PUTDEL RELEASE DELETE ENDSEQ Lads r inserts a new rerd depending n hw the data set was nneted: LOAD r PROCESS. Replaes a rerd that is being held fr update. Deletes a rerd that is being held fr update. Releases a rerd that is being held fr update. Deletes a single rerd, identified by its key, frm the data set. Terminates sequential pressing. EXTRACT Prvides infrmatin abut the file ntrl blk). (file DISCONN Disnnets an lacs frm an indexed data set, thereby releasing any lks held by that IACB, writing ut all buffers assiated with the data set, and releasing the strage used by the IACB. These funtins prvide yu the supprt neessary t build an indexed data set and t perfrm diret r sequential pressing n that data set. Rutines using these servies are written in Event Driven Language and an be inluded in prgrams written in any language that supprts the alling f Event Driven Language rutines. In additin, the Indexed Aess Methd utility prgram ($IAMUTl) prvides a set f mmands whih help yu manage yur indexed data sets. The fllwing mmands are prvided by the Indexed Aess Methd utility prgram: CR DF The reate funtin allws yu t allate spae fr yur data set in a vlume by internally invking the $DISKUTI system utility. When the reate mmand is entered n a terminal, the $DISKUTI prgram is laded and yu an then use the AL mmand f $DISKUTI t allate a data set; any ther $DISKUT1 funtin an als be perfrmed. Cmmtiniatin t the $DISKUTI utility ~tinues until the end mmand (EN) is entered, at whih time mmuniatin t the Indexed Aess Methd utility prgram is restred. Infrmatin n the $DISKUTI utility an be fund in the Utilities, Operatr Cmmands and Prgram Preparatin manual. The define mmand f the Indexed Aess Methd ut iii ty prgram uses an ex i st i ng data set and user-speified infrmatin t define an indexed file. when the define mmand is entered, yu are prmpted fr the immediate write-bak ptin and fr the vlume and data set names f the data 46 Versin 1.1 Planning Guide
set t be frmatted. The define funtin perfrms size alulatins and frmats the data set. The size alulatin infrmatin is returned t yur terminal at the mpletin f the define funtin. Prir t entering the define mmand, yu must use the SE mmand t set up parameters that determine the size and frmat f the indexed data set. DX EC EN LO RO SE UN The display mmand allws yu t display the urrent saved values fr the define mmand, as desribed abve. The eh mmand allws yu t set r reset eh mde. When eh mde is n, the input and utput f the urrent utility sessin is lgged n the $SYSPRTR devie. Eh mde remains n until either the urrent utility sessin is ended r it is reset by the EC mmand. When the Indexed Aess Methd utility is laded, eh mde is initially ff. Nte: Output frm the $DISKUTI prgram will nt be lgged sine the terminal input/utput is handled diretly by the $DISKUTI utility (nt $IAMUTl). The end mmand ends the sessin. urrent utility The lad mmand lads an indexed data set frm a sequential data set. The rerganize mmand lads an empty indexed data set frm an existing indexed data set. The setparms mmand prmpts yu fr parameters that determine the struture and size f the indexed data set, and sets these values in a parameter list. Size alulatins are perfrmed using the parameters yu speify and are returned t yur terminal. The setparms mmand shuld be entered prir t using the define mmand t d the atual data set frmatting. All values that yu speify fr parameters f the setparms mmand are saved (until the end f the sessin) fr later invatins f the setparms mmand and the define mmand. Yu an display these values by entering the DI mmand. The unlad mmand unlads an indexed data set t a sequential data set. Fr eah f these utility funtins, yu are prmpted fr the vlume and data set names f the input and/r utput data sets. Part 3: EDX Indexed Aess Methd 47
INDEXED DATA SETS Yu an rganize a lletin f data int an indexed data set if the data nsists f fixed-length rerds and eah rerd is uniquely identified by the ntents f a single predefined field. This identifier is alled the key. Rerds are arranged in an indexed data set in asending rder by key. Sme reserved spae an be distributed thrughut the data set s that rerds an be inserted in their key psitin during pressing. This spae is alled free spae. The Indexed Aess Methd puts rerds int an data set in either f tw ways: indexed 1. In LOAD mde, rerds are presented in asending rder by key and are laded int the data set sequentially, skipping any free spae. These rerds are alled the base rerds. Eah rerd laded must have a new high key; that is, it must have a key higher than any key already in the data set. 2. In PROCESS mde, rerds are inserted in their prper key psitin relative t rerds already in the data set. Rerds an be inserted using the free spae skipped during lading r, if a rerd has a new high key, in the unused spae after the last laded rerd. Yu nnet an indexed data set t yur appliatin prgram with the LOAD r PROCESS request. The ttal number f base rerds that an be laded is set using the define mmand f the Indexed Aess Methd utility prgram when the indexed data set is built. It is nt neessary, hwever, t lad all the base rerds befre pressing an begin. The data set an be nneted fr lading sme f the base rerds, nneted fr pressing inluding inserts, and later nneted fr lading mre base rerds. Figure 11 illustrates this sequene. The ttal amunt f free spae fr inserts is speified by the define mmand f the Indexed Aess Methd utility prgram when the indexed data set is built. This free spae is distributed thrughut the data set in the frm f free rerds in eah data blk, free blks in eah blk gruping, and/r in a free pl at the end f the data set. An indexed data set ntains spae allated fr base rerds and insertins and fr a multilevel index and the ntrl infrmatin required t use the index and the free spae. This type f infrmatin is useful fr planning, diagnstis, and a general understanding f the Indexed Aess Methd. See "Data Set Frmat" n page 70 fr a desriptin f the frmat f the indexed data set. 48 Versin 1.1 Planning Guide
r-----------.. <--Fi rst rerd has lwest key <---... Step 1. lad a prtin f the base rerds High key after step 1. Step 3. lad mre base rerds. High key after step 3. < l I < L <----I <----I <----t--- Step 2. Insert new <----4 rerds. <----4 <----' l > J Unused spae. High key after step 2. Figure 11. lading and Inserting Rerds in an Indexed Data Set PROGRAM OPERATION The Indexed Aess Methd mpri ses f a lad mdule and a link mdule. The link mdule is inluded in a user's prgram at link-edit time as an autall mdule. The Indexed Aess Methd perfrms I/O peratins using standard data management requests. The Indexed Aess Methd perates under Versin 1.1 f the Event Driven Exeutive. A single py f the Indexed Aess Methd serves the entire system. The Indexed Aess Methd an be laded autmatially at IPl time thrugh the $INITIAl feature f the system, r it an be laded manually by using the $l (lad) mmand. The Indexed Aess Methd des nt need t Part 3: EDX Indexed Aess Methd 49
be laded befre it is used by any prgram. The name f the Indexed Aess Methd fr lading purpses is $IAM. One laded, the Indexed Aess Methd remains in strage until anelled. 0, "~I ~ " The Indexed Aess Methd an be laded int any address spae, inluding address spae zer. It an be invked (thrugh the link mdule) frm any address spae, inluding the address spae it is in. Figure 12 shws an example f a system ntaining the Indexed Aess Methd. Address spae 0 Address spae 1 Address spae 2 - Appliatin prgram EJ Cntrl blks and buffer pl - - - - - - - - - Indexed Aess Methd Event Driven Exeutive Appliatin prgram EJ Appliatin prgram EJ Appliatin prgram EJ Eah appliatin prgram ntains a py f the link mdule, whih prvides the interfae t the single py f the Indexed Aess Methd. Figure 12. Example System Envirnment APPLICATION PROGRAM PREPARATION Appliatin prgrams that issue Indexed requests are prepared as fllws: Aess Methd 50 Versin 1.1 Planning Guide
1. Prgrams are assembled by any f these assemblers: The EDX assembler, $EDXASM, frm the EDX Prgram Preparatin Faility (S798-XX2). The EDX mar assembler $SIASM (S719-AMA) The Ser;es/l mar assembler supplied by the System/370 Prgram Preparatin Faility fr the Series/l C5798-HHQ). 2. Use the linkage editr, $lihk, t mbine bjet mdules prdued by any f the abve assemblers, alng with the IBM-supplied link bjet mdule, int a single mdule. 3. Use the nversin prgram, $UPDATE r $UPDATEH, t nvert yur mdule int ladable frm. APPLICATION DESIGN INFORMATION CI This hapter prvides guidelines fr designing appliatins that use the Indexed Aess Methd. It desribes: Preparing and maintaining data Designing an indexed data set Using the funtins prvided PREPARING THE DATA The fllwing setins desribe hw yu an design an indexed data set that uses spae effiiently and prvides ptimum perfrmane. Defining the Key Define a single key field fr eah indexed data set by speifying its size and psitin in the rerd when the data set is built by the define mmand f the Indexed Aess Methd utility prgram. The lnger the key, the l~rger the index ntained in the indexed data set. Therefre the key shuld nt be lnger than neessary. Hwever, the key must be lng enugh t ensure uniqueness. Part 3: EDX Indexed Aess Methd 51
Ensuring Uniqueness f the Key. In rder t identify eah rerd in an indexed data set, eah key must be unique. If key dupliatin is pssible, the key field shuld be expanded. Custmer name is a gd example f a key with whih dupliatins an ur. One way t avid dupliatin is t lengthen the key field t inlude ther haraters suh as part f the ustmer address r the aunt number. Sine the haraters 'in the key must be ntiguus, this slutin an invlve rearranging the fields in the rerd. Anther way t eliminate dupliatin is t mdify new rerds dynamially whenever a dupliatin urs during lading r pressing. A psitin at the end f the key field an be reserved fr a suffix de. Whenever a dupliate urs, yu an add a value t the suffix and make anther attempt t add the rerd t the data set. The result an be a data set that ntains a sequene f keys suh as Smith, Smith 1, Smith 2, and s frth. If yu add a suffix, yu must use the entire unique key t aess a speifi rerd. prviding Aess by Hre Than One Key. T prvide gd perfrmane with bth diret and sequential aess, eah indexed data set is indexed by a single key. At times, hwever, it may be useful t late rerds by a sendary key. Fr example, in a ustmer file indexed by aunt number, yu might want t late a rerd by ustmer name. One way f prviding aess by a sendary key is t build a send indexed data set mpsed f shrt rerds that ntain nly the sendary and primary keys. Using the sendary key t aess this data set, the assiated primary key an be determined. The primary key an then be used t late the desired rerd in the first data set. Where there are multiple keys t a data set, ensure high perfrmane by seleting as primary key the ne that is used mst ften r the ne with whih yu plan t d sequential pressing. Seleting the Blk Size Rerds an be blked in an indexed data set. The blk si.ze must be a multiple f 256. Blking redues I/O ativity; it als allws fr free rerds t be interspersed amng base rerds t prvide spae fr inserts. Free rerds are ne kind f free spae; free blks inluded at the end f eah blk gruping, r at the end f the data set, are thers. 52 Versin 1.1 Planning Guide
Speify rerd size and blk size when building the data set by the setparms mmand f the Indexed Aess Methd utility prgram. Eah blk has a 16-byte header. Therefre, the number f rerds per blk is: (blk size - 16) rerd size The result is trunated; that is, any remainder is drpped. A remainder represents the number f unused bytes in the blk. Seletin f a blk size is largely dependent n rerd size, but the blk size must be a multiple f 256. Other fatrs t nsider are insert ativity and buffer spae. Insert At;v;ty. Eah blk ntains allated rerd areas int whih base rerds an be laded and an ntain free rerd areas int whih rerds an be inserted during pressing. The rati f allated rerds t free rerds in a blk shuld be lse t the rati f estimated base rerds t estimated inserts in the data set. Ideally, blk size shuld be large enugh t ammdate enugh rerds t apprximate this rati. Buffer spae. A large blk size is advantageus in that it minimizes the read/write ativity, but it is stly in terms f the read/write buffer spae required frm the buffer pl. Sme pressing requires a buffer large enugh fr tw blks. Examples. A data set nsists f 1000 base rerds with an estimate f 500 rerds t be inserted and a rerd size f 70 bytes. Selet a blk size and a number f free rerds per blk t build an indexed data set. 1. Seleting a blk size f 256 with 1 free rerd per blk implies (256-16)/70 = 3 rerds per blk, with a remainder f 30 bytes. The rati f 2 allated rerds and 1 free rerd aurately reflets the insert ativity. Buffer size is minimized. Sme spae is wasted n the disk (30 bytes per setr). Designing ao-byte rerds and 256-byte blks fr this data set effetively uses these 30 bytes. 2. Seleting a blk size f 512 with 2 free rerds per blk implies (512-16)/70 = 7 rerds per blk, with a remainder f 6 bytes. The rati f 5 allated rerds t 2 free rerds underestimates the insert ativity. The larger blk size requires a larger buffer but inreases I/O effiieny. Fewer bytes are wasted n the disk (6 bytes in 2 setrs). Part 3: EDX Indexed Aess Methd 53
Estimating Free Spae Speify free spae fr inserts using the setparms mmand f the Indexed Aess Methd utility prgram. An exat alulatin t estimate free spae is nt neessary. Experiene an be yur best guide; if the need fr file rerganizatin is signalled (n spae fr an insert) befre a majr prtin f the free spae is utilized, yu knw yu must adjust the mix f free rerds and free blks, reserve blks, and reserve index blks. As a general apprah, estimate nt nly the number f inserts but als their distributin thrughut the data set. Fr example, nsider a data set with 5 rerds per blk, and 10 data blks per luster.4 Suppse that the data set nsists f 300 base rerds and 200 inserts. If the inserts are distributed evenly thrughut the data set, the pattern f inserts is: Blks Inserts With this kind f distributin yu an speify 2 free rerds per blk t absrb the inserts; n free blks are needed. Of urse inserts d nt usually ur in suh an even pattern. Free blks help t absrb a nentratin f inserts. The mre uneven the expeted distributin, the greater the free blk speifiatin shuld be. Suppse the same number f inserts are distributed in this pattern: Blks Inserts. With this distributin yu must speify either 3 free rerds per blk, r 20~ free blks with 2 free rerds per blk. Hw suppse the distributin were mre uneven: I 4 A luster is a grup f blks; the extent f the grup being determined by the struture f the index. This is mre fully desribed in "Data Set Frmat" n page 70. 54 Versin 1.1 Planning Guide
Blks Inserts In this ase a satisfatry mix f free spae is 1 free rerd per blk and 40~ free blks. If the antiipated insert ativity is nfined t nly a few lusters, it is better t use a free pl. A free pl is a grup f blks, at the end f an indexed data set, that are available t be used wherever they are needed within the file. Hwever, in rder t use blks frm the free pl, the data set must be strutured s that they an be lgially nneted where they are needed. This struture is speified with the RSVBlK and RSVIX parameters f the define mmand f the Indexed Aess Methd utility prgram. Use the RSVBlK parameter t indiate the perentage by whih a luster an grw, by taking data blks frm the free pl. The struturing is amplished by leaving reserve entries in the lwest level index blks. These reserve entries are nt riginally used, but an be used later t pint t data blks taken frm the free pl. Use the RSVIX parameter t indiate the perentage by whih a luster gruping an grw by adding new lusters. This struturing is amplished by leaving reserve entries in the send-level index blks. These reserve entries are nt riginally used, but an be used later t pint t new lwest-level index blks taken frm the free pl. This lwest-level index blk is the seed fr a new luster and an ultimately grw int a full-sized luster as data blks are taken frm the free pl. As an example f the advantage f a free pl, assume that a data set ntains 50 lusters f 10 data blks eah and 40% f the blks in the luster are free blks. There are 200 free blks in the data set. If mst f the inserts int the data set will fall int a relatively small key range and d nt nrmally require mre than 50 blks, 150 blks are saved by speifying n free blks and a 40% RSVBlK. 0 ', ~ A 25% FPOOl parameter prvides the 50 blks in the free pl t be used where the inserts are required. The result is that the data set still aepts all the antiipated inserts and 150 blks are saved. Part 3: EDX Indexed Aess Methd 55
If insert ativity int the data set is antiipated t be relatively even, the spae fr inserts shuld be reserved as free rerds and free blks. This results in the best respnse time frm the Indexed Aess Methd. If, hwever, insert ativity int the data set is t be primarily int ne r mre areas r key ranges, the spae fr inserts shuld be reserved as reserve blks and/r reserve indexes. This results in the mst effiient use f spae in the data set. The spae fr inserts an be divided between free rerds, free blks, reserve blks, and reserve indexes t suit yur requirements. T determine hw many blks are required fr an indexed data set with a given mbinatin f free rerds, free blks, reserve blks, reserve index blks, and free pl size, use the SE mmand f the Indexed Aess Methd utility prgram (see "Determining Size and Frmat"). BUILDING THE INDEXED DATA SET The SE and DF mmands f the Indexed Aess Methd utility prgram allw yu t speify the size and frmat f yur indexed data set and t d the atual data set frmatting. Use the SE mmand t enter thse values that determine the size f the indexed data set and t reeive size alulatin infrmatin. Use the DF mmand t ause the atual data set frmatting t ur, using the values previusly speified n the SE mmand. Determining Size and Frmat The design f the data set is determined by these parameters f the SE mmand: BlKSIZE - Blk size RECSIZE - Rerd size KEYSIZE - Key size BASEREC - Estimated number f base rerds FREEREC - Number f free rerds per blk FREEBlK - Perentage f free blks S6 Versin 1.1 Planning Guide
0 RSVBLK - Perentage f reserved data blks RSVIX - Perentage f reserved primary index blks FPOOL - Perentage f free pl DElTHR - Perentage delete threshld The define (DF) mmand fixes the size f the data set. Therefre, BASEREC, FREEREC, FREEBlK, RSVBLK, RSVIX, and FPOOL shuld be large enugh t ammdate the maximum number f rerds planned fr the data set. T alulate the size f the data set fr a given mbinatin f the define parameters, use the SE mmand. The DF mmand allws yu t selet the immediate writebak ptin. With this ptin yu an ause mdifiatins t the indexed data set t be written t the file immediately. This ntributes t the integrity f the file, but inreases respnse time. Defining and Creating the Indexed Data Set The setparms (SE) mmand allws yu t reeive the size alulatin infrmatin withut atually perfrming the data set frmatting. The size f the data set and ther relevant infrmatin are returned t yur terminal by the utility. The alulatins perfrmed by the setparms funtin are desribed in "Data Set Frmat" n page 70 and are summarized in "Summary f Calulatins" n page 84. Use the DF mmand t atually frmat the data set. Yu are prmpted fr the vlume and data set names, and fr the immediate write-bak ptin, f the data set t be frmatted. (Nte: the data set must be previusly reated using the CR mmand f the Indexed Aess Methd utility prgram and/r the Al mmand f the $DISKUTI utility.) This data set is nneted and then frmatted by the define funtin. If the data set des nt ntain suffiient spae t supprt the speified frmat, the amunt f spae required is returned t yu. Knwing the available spae and using the SE mmand, yu an vary the define parameters t design a data set that fits. If the speified data set des nt exist, a nnet errr will ur and yu are given the ptin t retry. If yu indiate t retry, yu are prmpted fr the vlume and data set names f the data set t be frmatted and the funtin is attempted again. Part 3: EDX Indexed Aess. Methd 57
Cnneting and Disnneting the Indexed Data Set When yu prepare t use an indexed file by the Indexed Aess Methd, yu must issue a LOAD r PROCESS request t nnet it t yur prgram. A LOAD r PROCESS builds an indexed aess ntrl blk (IACB) that is assiated with an indexed data set. The IACB nnets a request t the data set. Only ne LOAD ~an be nneted t the data set. Hwever, pressing an take plae nurrently with lading. N LOAD r PROCESS is suessful until the file has been frmatted using the define mmand f the Indexed Aess Methd utility prgram. Multiple IACBs an be assiated with the same data set. Data integrity is maintained by a lking system that allates file, rerd, r blk lks t the requesting IACB in rder t prevent nurrent mdifiatin f index r data rerds by ther requests. An IACB an hld nly ne lk at a time; therefre, if yur appliatin requires nurrent exeutin f funtins that btain lks (diret update r sequential update - see "Pressing" n page 59 fr a desriptin f these funtins), yu must issue multiple PROCESSes t prvide multiple IACBs. The Indexed Aess Methd retains infrmatin abut these requests in the IACB. A DISCONN disnnets an IACB frm the data set, releases the strage fr that IACB, releases lked blks r rerds being held by that IACB, and writes ut blks t the data set that are being held in the buffer. The DISCONN request an be made any time during lading r pressing. There 1S n autmati DISCONN n task terminatin. It is very imprtant that yu disnnet yur indexed data sets prir t terminating yur task; failing t d s may prevent resures allated t yur task frm being allated t ther tasks and updates frm being written bak frm the buffer t yur data set. LOADING BASE RECORDS Base rerds must be laded in asending rder by key. Initiate lading f base rerds with a LOAD request. Then lad the rerds with a PUT fr eah rerd. When the desired number f rerds has been laded, issue a DISCONN request t terminate the lad predure. The nly valid 58 Versin 1.1 Planning Guide
requests that an fllw a LOAD request are: PUT EXTRACT DISCOHH Yu need nt lad all the base rerds at ne. A data set that ntains sme rerds an be renneted fr lading mre rerds. The ~ey f eah new rerd must be higher than any key already in the data set. Als, the limit n base rerds as speified n the define mmand f the Indexed Aess Methd utility prgram annt be exeeded. If an attempt is made t lad a rerd after the last allated rerd area has been filled, an end-f-file nditin is returned. Only ne user an have a data set nneted fr LOAD at any time. Other pressing requests an nurrently be made t a data set that is being laded. Hwever, an attempt t retrieve a rerd frm a data blk being laded an result in a n-rerd-fund nditin. Yu an lad an indexed file frm a sequential data set by using the lad mmand (LO) f the Indexed Aess Methd utility prgram PROCESSING Initiate the pressing f an indexed data set with a PROCESS,request. After the PROCESS, any f the fllwing funtins an be requested. Nte that the update funtins require mre than ne request. Diret reading - Retrieval f a single rerd independent f any previus request Sequential reading - Retrieval f the next lgial rerd frm the pint f the previus request Diret updating - Retrieval f a single rerd fr the purpse f updating that rerd; subsequent mpletin f the update by replaing r deleting the riginal rerd. Sequential updating - Retrieval f the next lgial rerd fr the purpse f updating that rerd; subsequent mpletin f the update by replaing r deleting the riginal rerd Part 3: EDX Indexed Aess Methd 59
Inserting - Plaement f a single rerd in its lgial key sequene in the indexed data set Deleting - Diret remval f a single rerd frm the indexed data set Extrating - extrat data desribing the data set When the funtin is mplete, anther funtin an be requested, exept that a sequential funtin an be fllwed nly by anther sequential funtin until the sequene is ended. At any time, yu terminate the pressing by issuing a DISCONN. Diret Reading Use the GET request t read a rerd using diret aess. The KEY parameter is required and must be the address f a field f full key length regardless f the KlEN (key length) speifiatin. The rerd retrieved is the first rerd in the data set that satisfies the searh argument defined by the KEY, KlEN, and KREL (key relatin) parameters. The key field is updated t reflet the key in the rerd that satisfied the searh. If KLEN is speified as less than full key length, nly part f the key field is used fr mparisn when searhing the data set. Fr example, suppse the keys in the data set are AAA, AAB, ABA, and ABB and suppse the key field ntains ABO and KREL (key relatin) is EQ. If KlEN is zer, the searh argument is the full key (default) ABO and a 'rerd nt fund' de is returned. If the KLEN speifiatin is 2, the searh argument is AB, and the third rerd is read. If the KLEN speifiatin is 1, the searh argument is A, and the first rerd is read. Diret Updating T update a rerd using diret aess: 1. Retrieve the rerd with a GET request with ne f the update MODE/KREL parameters speified. 2. Mdify the rerd in yur buffer as desired. Hwever, d nt hange the key field in the rerd. Return the updated rerd t the data set with a PUTUP request. 60 Versin 1.1 Planning Guide
Alternatively, yu an delete the rerd with PUTDEL, r leave it unhanged by mpleting the update with a RELEASE request. A diret update, like a diret read, requires that the KEY parameter be speified as the address f a field f full key length. This field must nt be mdified during the update. The nly valid requests, ther than DISCONN and EXTRACT, that an fllw GET fr diret update are the requests that mplete the update: PUT UP PUT DEL RELEASE During the update, the subjet rerd is lked; that is, the rerd is unavailable t any ther request until the update is mplete. Even if n ther atin is taken after the GET, the RELEASE is required t release the lk n the rerd. Sequential Reading Use thegetseq request t read a rerd using sequential aess. After a sequene has been initiated by a sequential retrieval, nly sequential funtins an be requested until the sequene is mpleted with an end-fdata nditin r an ENDSEQ request. At any time in the sequene, pressing an be terminated with a DISCONN. Als, the sequene is terminated if any errr r warning IS returned while in sequential mde. Start;ng the Sequene. T begin the sequene with the first rerd in the data set, set the KEY address t zer. T start the sequene with any ther rerd, speify a searh argument as fr a diret read. If yu speify the searh argument when yu start the sequene, the key field is mdified t reflet the key fund as a result f the retrieval f the first rerd. Intermed;ate Retr;evals. After the first retrieval, a GETSEQ retrieves the next sequential rerd regardless f any KEY, KREL, r KLEN speifiatin. Therefre, yu an use the same GETSEQ statement in a lp t read all the rerds in the sequene. If yu speify a searh argument n intermediate retrievals, it is ignred and the key field is nt mdified n intermediate retrievals. Part 3: EDX Indexed Aess Methd 61
Ending the Sequene. T end the sequene befre the end f data is reahed, speify ENDSEQ. The sequene is ended autmatially at the end f data. An end-f-data nditin urs when an attempt is made t retrieve a rerd after the last rerd in the data set. If yu speify the EODEXIT parameter in the PROCESS, it is nt neessary t test fr the end-f-data return de. When the end-f-data nditin urs, ntrl transfers t yur end-f-data rutine. Sequential Updating T update a rerd using sequential aess, retrieve the rerd with a GETSEQ request with ne f the update MODE/KREL parameters speified. The sequential retrieval fr update is the same as the sequential read. A searh argument is used nly n the first retrieval f a sequene and is nt speified if the sequene is t begin with the first rerd in the data set. The sequene is terminated with an EHDSEQ r with an end-f-data nditin. The sequential update is mpleted in the same way as a diret update. The key in the rerd annt be mdified. The rerd an be returned t the data set with a PUTUP, deleted with a PUTDEL, r left unhanged by speifying RELEASE. When the update is mplete, anther sequential read r update an be requested. It is valid t terminate the sequene with ENDSEQ, r terminate pressing with a DISCONN either befre r after mpleting the update. Figure 13 summarizes the prtl fr sequential pressing. Inserting T insert'a new rerd in a data set nneted fr pressing, speify PUT. The Indexed Aess Methd uses the key within the rerd in yur buffer t insert the rerd -in prper key rder in the data set. The key f the inserted rerd must be different frm any key in the data set; therwise a dupliate key errr urs. The key an be higher than any key in the data set; that is, it is permissible t insert a rerd with a new high key. 62 Versin 1.1 Planning Guide
A request fr sequential update: GET fr update an be fllwed by: 1. A request t end pressing: DISCONN 2. An end-f-data nditin: autmati end-f-sequene and transfer f ntrl t EODEXIT rutine 3. A request t end the sequene: ENDSEQ End-f-sequene an be fllwed by: 1. A request t end pressing: DISCONN 2. Any pressing funtin: GET, PUT, DELETE A request t mplete the update: The mpleted update an be fllwed by: 4. PUTUP 1. A request t end pressing: 5. PUTDEL DISCONN 6. RELEASE 2. A request t end the sequene: ENDSEQ 3. A sequential request: GETSEQ Figure 13. Prtl fr Sequential Updating If there is n free spae in the area assiated with the insert r n blks in the free pl, a n-mre-spae nditin urs. The n-mre-spae nditin des nt mean the data set is fulli there an be free spae in unrelated blks. It indiates a need fr data set rerganizatin. This predure is desribed in "Rerganizatin" n page 69. Use DELETE t delete a rerd frm the data set. The full key f the rerd must be speified.. If there is n rerd with that key, a negative return de gives a warning. Deletin ;s als perfrmed as part f updating by fllwing a GET fr update with a PUTDEL request. Part 3: EDX Indexed Aess Methd 63
Extrating Yu an extrat infrmatin abut a data set frm the file ntrl blk (FCB). This inludes infrmatin suh as key length, key displaement, blk size, rerd size, and ther detailed data regarding the data set struture. This data is requested by EXTRACT. Exeutin f this funtin auses pying f the file ntrl blk t the speified user area. Yu must prvide the strage int whih the data is pied. The data set must be nneted by LOAD r PROCESS. HANDLING ERRORS All exeuted Indexed Aess Methd requests return a signed number, alled a return de, in the task de wrd (referred t by task name) f the TCB. The return de reflets the nditin f the requested funtin. Return des are gruped in three ategries: -1 - Suessful mpletin Psitive - Errr Negative - Warning Errr Exit Rutine In PROCESS and LOAD requests, the address f an errr exit rutine an be speified by the ERREXIT parameter. If speified, this rutine is exeuted whenever this request r any subsequent Indexed Aess Methd request fr the duratin f this PROCESS r LOAD terminates with a psitive return de. If the address f an ~rrr exit rutine is nt speified, the next sequential instrutin after the request is exeuted regardle~s f the value f the return de. System Funtin Return Cdes If a system funtin alled by an Indexed Aess Methd request terminates with a psitive return de, the return de is plaed in a latin reserved by the PROCESS r 64 Versin 1.1 Planning Guide
LOAD request. This is used by any subsequent request until a DISCONN is issued. Fr example, GET uses the read funtin. If the read terminates with a psitive return de, that return de is saved in the latin reserved fr the system funtin return de in the PROCESS assiated with the GET. The GET als terminates with a psitive return de in the task ntrl wrd that indiates a read errr. The ause f the read errr is determined frm the system funtin return de. Data Set Shut Dwn Smetimes an I/O errr that is nt assiated with a speifi request urs. Fr example, Task A issues a GET n data set X. In rder t seure buffer spae, the Indexed Aess Methd writes ut a blk t data set Yand, in the press, an errr urs. Data set Y is damaged but there is n requesting prgram t aept an errr return de. The errr is rerded by setting the data-set-shut-dwn nditin fr data set Y. When this nditin exists, n requests ther than a DISCONN are aepted fr this data set. Later, if Task B issues a GET n data set Y, the request is terminated with a data-set-shut-dwn return de. Task B shuld issue a DISCONN and use revery predures t renstrut the data set. An initial prgram lad CIPL) anels the data-set-shut-dwn nditin. Deadlks Sine the Indexed Aess Methd uses rerd and blk lks t preserve file integrity, deadlk nditins are pssible. A deadlk is a nditin where tw r mre tasks interat in suh a way that ne r mre resures beme permanently lked and further prgress is nt pssible. A deadlk an als ur when tw IACBs frm the same task request a lk n the same rerd r a lk n the same blk in sequential mde. In this setin, the term deadlk refers nt nly t a true deadlk, but als t an apparent deadlk, in whih a task hlds 8 resure fr an unreasnably lng perid f time. Part 3: EDX Indexed Aess Methd 6S
Appliatin tasks shuld nt use the Indexed Aess Methd in suh a way that a rerd r blk remains lked fr a lng perid f time, sine ther tasks may attempt t use the same rerd r blk. In a terminal riented system, make every effrt t ensure that a rerd r blk is nt lked during peratr "think" time. Speifially, yu shuld attempt t fllw these rules: D nt retrieve a rerd fr update, display the rerd at the terminal, then wait fr the peratr t mdify it befre mpleting the update. D nt retrieve a rerd in sequential mde, display the rerd at the terminal, then wait fr an peratr respnse befre ntinuing the sequential peratin. In bth f these ases, a rerd r blk is lked during peratr "think" time and uld be held fr minutes r hurs. Every effrt shuld be made t avid a deadlk situatin. There is n way t break a deadlk exept t release the lks that are being waited n~ Even terminating the tasks invlved might nt break the deadlk beause terminatin pressing annt ur until any utstanding requests issued by a terminating task have mpleted. EXECUTING THE APPLICATION PROGRAM Appliatin prgrams that use the Indexed Aess Methd are exeuted the same as ther appliatin prgrams. Beause the Indexed Aess Methd and the indexed data sets are resures available t all tasks, delays an ur under heavy system usage. Speifially, with mre than ne task using the Indexed Aess Methd there an be ntentin between tasks fr any f these resures: Entire indexed file Index blk in the data set Data blk in the data set Data rerd in the data set Buffer spae frm the system buffer pl Fr example, during the exeutin f a request frm Task A, sme buffer spae an be required and an index blk r data blk r rerd an be lked (made unavailable t ther requests). If a request frm Task B requires mre buffer spae than remains available r if it requires a 66 Versin 1.1 Planning Guide
lked blk r rerd, that request is delayed until the required resure is freed. In general, resures required by the Indexed Aess Methd are allated nly fr the duratin f that request. There are tw exeptins: During an update, when ntrl returns t the task after a GET r GETSEQ fr update, the subjet rerd is lked. The lk is released when the update is mpleted with a PUTUP, PUTDEL, RELEASE, r by a DISCONN. During sequential pressing, when ntrl returns t the task after a GETSEQ, the blk ntaining the subjet rerd is lked and held in the buffer. Subsequent GETSEQ requests pik up rerds diretly frm the buffer; sequential pressing is fast beause n searh is required. When a GET requires a rerd frm the next blk, the urrent blk and buffer are released. Pending requests fr buffer area are satisfied and the next blk is lked and held in the buffer. Exept fr mmentary release f the buffer area between blks, ne blk and buffer are lked fr the entire sequene. The sequene is terminated by an end-f-data nditin, by an ENDSEQ, r by a DISCONN. The update and the sequene shuld be mpleted prmptly. Use the fllwing guidelines t avid prblems with these resures. 1. Disnnet all indexed data sets befre task terminatin. The DISCONN releases lked rerds r blks and writes ut buffers fr that data set that have nt already been written. 2. With multiple Indexed Aess Methd users n the system, use diret aess rather than sequential aess t retrieve a sequene f rerds interatively. A suggested methd is: a. Retrieve the first rerd by key. b. Extrat the key frm that rerd and save it fr the next retrieval.. Retrieve the next rerd using the saved key and a greater-than key relatin. d. Repeat the send and third steps fr the duratin f the sequene. Part 3: EDX Indexed Aess Methd 67
MAINTAINING THE INDEXED DATA SET The Indexed Aess Methd des nt prvide speifi prgrams t perfrm indexed data set bakup and revery, nr des it inlude servies t delete the data set r dump t the printer. These predures are readily prvided by a mbinatin f EDX and Indexed Aess Methd servies as suggested belw. The Indexed Aess Methd utility prgram prvides servies t help yu rerganize yur data set as desribed belw. 0. ', I Bakup and Revery T prtet against the destrutin f data, at regular intervals yu shuld make a py f the indexed data set (r the lgial vlume in whih the data set exists> using the system COPY utility. During the interval between pies, yu shuld keep a jurnal file f all transatins made against the indexed data set. The jurnal file an be a nseutive data set ntaining rerds that desribe the type f transatin and the pertinent data. A damaged indexed data set an be revered by updating the bakup py frm the jurnal file. Fr example, suppse an indexed data set named REPORT is lst beause f physial damage t the disk. The nditin that aused the errr has been repaired and the data set must be revered. Delete REPORT and py the bakup versin f REPORT t the desired vlume. If a data set shut dwn nditin exists, IPL again. Then issue a PROCESS t the REPORT data set and, using the jurnal file, rereate the transatins that urred sine the bakup py was made. Revery Withut Bakup If yu d nt'use the bakup predures utli~ed abve and yu enunter a prblem with yur data set, yu still may be able t rereate yur file. Hwever, the status f requests made prir t the prblem is unertain. T rereate yur data set, fllw the steps given belw as a methd f rerganizing yur data set. After rereating the data set, verify the status f requests made at the time the prblem urred. 68 Versin 1.1 Planning Guide
Rerganizatin An indexed data set must be rerganized when required inserts fail beause f lak f spae. This nditin des nt imply that there is n mre spae in the data set; it means that there is n spae in the area where inserts must be made. Therefre, yu an rerganize withut inreasing the size. The fllwing steps prvide a methd f perfrming a rerganizatin: 1. Ensure that all utstanding requests against the data set have been mpleted; issue a DISCONN fr every urrent lacs. 2. Use the define mmand (DF) f the Indexed Aess Methd utility prgram t define a new indexed data set. Carefully estimate the number f base rerds and the amunt and mix f free spae in rder t minimize the need fr future rerganizatins. Guidelines fr making these estimates appear at the beginning f this hapter. 3. Use the rerganize mmand (RO) f the Indexed Aess Methd utility prgram t lad the new indexed data set frm the indexed data set t be rerganized. Alternatively, yu an use the unlad mmand (UN) f the Indexed Aess Methd utility prgram t transfer the data frm an indexed data set t a sequential data set, then use the lad mmand (LO) t lad it bak int the indexed data set. The result is a rerganized indexed data set. 4. Use system utilities t perfrm any desired husekeeping peratins. The ld data set an be deleted, and the new data set an subsequently be renamed t the name f the ld data set. Dumping 0,,,,I ~ T print user rerds, retrieve the rerds sequentially and print them. Use the DP mmand f the $DISKUT2 utility fr a hexadeimal dump f the entire data set inluding ntrl infrmatin, index blks, and data blks. Infrmatin n the $DISKUT2 utility an be fund in the Utilities, Operatr Cmmands and Prgram Preparatin manual. Part 3: EDX Indexed Aess Methd 69
Delating Delete an indexed data set in the same manner in whih yu delete any data set. Frm yur terminal, use the DE mmand f the $DISKUTI utility (see the Utilities, Operatr Cmmands and Prgram Preparatin manual). DATA SET FORMAT The define mmand f the Indexed Aess Methd utility prgram frmats and reates the indexed data set. The infrmatin required t determine the frmat and the number f blks in the data set is prvided by ten parameters. These parameters are speified using the setparms mmand. Examples in this hapter use the fllwing values fr the parameters: Parameter Name BlKSIZE RECSIZE KEYSIZE BASEREC FREEREC FREEBlK RSVBlK RSVIX FPOOl DELTHR Value Addressed by Parameter Blk size = 256 bytes Rerd size = 80 bytes Key size = 28 bytes Number f base rerds = 1000 Number f free rerds per blk = 1 Perentage f free blks = 10 Perentage f reserved blks = 10 Perentage f reserved index = 10 Perentage f free pl = 50 Perentage f blks t retain when deleting rerds; this value is allwed t default. BLOCKS The indexed data set is mpsed f a number f fixed length blks. The blk is the unit f data transferred by the Indexed Aess Methd, and is a multiple f 256. A blk is addressed by its relative blk number (RBN) suh that the first blk in the data set is lated at RBN. 70 Versin 1.1 Planning Guide
Nte that the RBN is a blk number used nly in indexed data sets, by the Indexed Aess Methd. A blk as used in the Indexed Aess Methd differs frm an EDX rerd in the fllwing ways: 1. The size f a blk is nt limited t 256 bytes. Its length an be a multiple f 256 bytes. 2. The RBN f the first blk in an indexed data set is. The rerd number f the first EDX rerd in a data set is 1. The size, in 256-byte rerds, f the data set is alulated by the define mmand f the Indexed Aess Methd utility prgram and returned t the terminal. There are three kinds f blks in an indexed data set: a file ntrl blk (FeB), index blks, and data blks. These blks are all the same length, as defined by BLKSIZE, but they ntain different kinds f infrmatin: ntrl infrmatin, index entries, and data rerds. The ntrl infrmatin is ntained in blk headers and the FeB; fr a desriptin f ntrl infrmatin, see Figure 14. Figure 14 shws examples f the three blk types. Header Header Cntrl infrmatin RBN RBN Key Key Data rerd RBN Key Unused RBN RBN RBN RBN Key Key Key Key Data rerd Data rerd Unused File ntrl blk Index blk Data blk Figure 14. Indexed Data Set Blk Types Part 3: EDX Indexed Aess Methd 71
The file ntrl blk (FeB) is the first blk in the data set (RBH 0). It ntains a fixed amunt f ntrl infrmatin. Index Blk An index blk ntains a header fllwed by a number f index entries. Eah index entry is a key-pinter pair. The key is the highest key assiated with a blk; the pinter is the RBN f that blk. The number f entries ntained in eah index blk depends n blk size and key size. The header f the blk is 16 bytes. The RBH field in eah entry is 4 bytes. The key field in eah entry must be an even number f bytes in length; if key size is dd then the field is padded with ne byte t make key entry even. The number f i,n,dex entri es in an index blk is: blk size - 16 4 + key length The result is trunated; any remainder represents the number f unused bytes in the blk. Fr example, if blk size is 256 and key size is 28, then eah index entry is 32 bytes, there are 7 entries in a blk, and the last 16 bytes f the blk are/unused. Data Blk A data blk ntai ns a header fllwed by a number f data rerd areas. The number f rerds that an be ntained in a data blk depends n blk size and rerd size. The header f the blk is 16 bytes. The number f rerd areas in the blk is: blk size - 16 rerd size The resul tis tr~inated; any remai nder represents the number f unused bytes in the blk. Fr example, if blk size is 256 and rerd size is 80, there an be 3 rerds in a data blk. In this example, there is n unused area. The key field f the last rerd slt in a data blk indiates the high key fr the data blk. If all rerds f the data b~k are nt urrently used, the key field f the last re/rd slt is nrmally the same as the key fi eld f the last used rerd in the blk. Hwever, it is ps- 72 Versin 1.1 Planning Guide
sible fr the key field f the last rerd slt t ntain a key higher than that f any rerd in the blk. This an ur if the last rerd f the blk has been deleted. Thus, deletin f a rerd des nt redue the key range fr the blk. The Index The index f an indexed data set is nstruted in several levels s that, given a key, there is arsingle path (ne index blk per level) asading thrugh the index levels that leads t the data blk assiated with that key. The index is built frm the bttm up. At the lwest level are the prime index blks. At the send level are index blks ntaining entries that pint t the prime index blks. There are enugh levels s that the highest level nsists f a single index blk. Prime Index Blks Entries in a prime index blk pint t data blks. Eah entry in a prime index blk is ne f three pssible types: Allated (used) entry. This type f entry pints t an ative data blk. The key prtin f the entry is initialized t binary l's (all bits n). The key prtin f the entry ntains the highest key frm the data blk. The pinter prtin ntains the RBN f the data blk. Allated entries are the first entries in the index blk. The number f index entries initially allated when the indexed data set is laded is alulated as the ttal number f entries per index blk, less the number f entries f the ther tw types (free blk entry and reserve blk entry) (see Figure 15). Free blk entry. This type f entry pints t a free data blk. The key prtin f the entry ntains binary zers. The pinter prtin ntains the RBN f the free blk. Free blk entries fllw the allated entries in the index blk. The number f index entries initially frmatted as free entries when the indexed data set is laded is the speified perentage (FREEBLK) f the ttal number f e~tries, with the result runded up if there is a remainder. Part 3: EDX Indexed Aess Methd 73
Header RBN Key l RBN Key > Allated entries J RBN RBN RBN Key Key Key RBN 0 Free blk entry 0 0 Reserve blk entry Unused Figure 15. Example f Prime Index Blk 'Reserve blk entry. This type f entry des nt pint t a blk. It is reserved fr later use as a pinter t a data blk whih an be taken frm the free pl. Bth the key and pinter prtins f a reserve blk entry are binary zers. Reserve blk entries are at the end f the index blk. When a reserve blk entry is nverted t a used entry, the index blk is refrmatted t mve the entry t the allated entry area f the blk. The number f index entries initially frmatted as reserve blk entries is the speified perentage (RSVBlK) f the ttal number f entries, with the result runded up if there is a remainder. Hwever, if the number f free blk entries and the number f reserve blk entries tgether require all index entries, the number f reserve blk entries is redued by 1. This prvides at least ne allated entry per index blk. In rder t alulate the number f prime index blks in an indexed data set, yu must first knw the initial number f data blks allated in the indexed data set. The initial number f data blks is alulated as the speified number f base rerds (BASEREC) divided by the number f allated (nt free) rerds in a data blk, with the result runded up if there is a remainder. The number f prime index blks an then be alulated as the initial number f allated data blks divided by the number f allated entries per prime index blak, with the result runded up if there is a remainder. ~-) ~- 74 Versin 1.1 Planning Guide
Sand-Lavel Index Blk Entries in a sand-ievel indax blk pint t prime index blks. Eah entry in a send-level indax blk is ne f tw pssibla types: Allated (used) entry. This typa f entry pints t an existing prime index blk. The key prtin f the entry is initialized t binary l's (all bits n). The key prtin f the entry ntains the highest key frm the prime index blk. The pinter prtin ntains the RBN f the prime index blk. Allated entries are the first entries in the index blk. The number f index entries initially allated when the indexed data set is laded is alulated as the ttal number f entries per index blk, less the number f reserve index entries. Reserve index entry. This type f entry des nt pint t a blk. It is reserved fr later use as a pinter t a prime index blk that an be taken frm the free pl. Bth the key and pinter prtins f a reserve index entry are binary zers. Reserve index entries are at the end f the index blk. The number f index entries initially frmatted as reserve index entries is the speified perentage (RSVIX) f the ttal number f entries, with the result runded up if there is a remainder. Hwever, if the number f reserve index entries is the same as the ttal number f entries in an index blk, the number f reserve index entries is redued by 1. This prvides at least ne allated entry per send-level index blk. The number f send-level index blks is alulated as the number f prime index blks divided by the number f allated entries per send-level index blk, with the result runded up if there is a remainder (see Figure 16). Higher Level Index Blk Entries in a higher level index blk pint t index blks at the next lwer level. All entries in higher level index blks are allated (used) entries. The key prtin f the entry ntains the highest key frm the next lwer level index blk. The pinter prtin ntains the RBN f the next lwer level index blk. The number f blks at any higher index level is alulated as the Part 3: EDX Indexed Aess Methd 75
Header () RBN RBN RBN RBN RBN RBN Key Key Key Key Key Key > Allated entries 0 0 Reserve index entry Unused Figure 16. Example f Send-level Index Blk number f index blks at the next lwer level divided by the ttal number f entries per index blk, with the result runded up if there is a remainder (see Figure 17). (~ \V If the number f index blks at any level is ne, that level is the tp level f the index. Althugh the Indexed Aess Methd is apable f supprting 17 levels f index, any given indexed data set is frmatted with nly as many index levels as are required fr the speified number f rerds. If an indexed data set has nt been fully laded, it is pssible that ne r mre higher index levels are nt yet required, even thugh they exist in the file struture. In this ase, the unneessary higher levels are nt used. Index Example In the sample data set desribed at the beginning f this hapter, 500 data blks are initially allated t the data set. Eah prime index blk ntains ne free blk entry, ne reserve blk entry, and five allated entries; therefre, the ttal number f prime index blks is 100. Eah send-level index blk ntains ne reserve index entry and six allated entries; therefre, the number f send-level index blks is 17. The number f 76 Versin 1.1 Planning Guide
Header RBN RBN RBN Key Key Key RBN Key > Allated index entries RBN RBN RBN Key Key Key Unused Figure 17. Example f Higher-Level Index Blk entries in higher level index blks is seven. This results in three index blks at the third level and ne at the furth level. Therefre the sample data set ntains a ttal f 121 index blks. Of these blks, 100 are prime index and the remaining 21 are high-level index blks. This distintin is imprtant beause, as shwn later in this hapter, high-level index blks are lated ntiguusly at the beginning f the data set (after the FeB), while prime index blks are sattered thrughut the file with the data blks. Figure 18 shws the struture f the high-level index blks. Cluster Data rerds are laded int the data blks in asending rder by key. Eah data blk is pinted t by a prime index blk entry that ntains the high key f the data blk (that is, the key frm the last rerd slt in the data blk). Prime index blks and data blks are stred tgether in the data set in grups alled lusters. Eah luster begins with a prime index blk fllwed by as many data Part 3: EDX Indexed Aess Methd 77
Furth (tp) level index (.~. j Third level index Send level index Figure 18. High-Level Index Blk Struture blks as there are allated r free entries in the index blk. Data blks an be f tw types: allated data blks and free data blks. The prime index blk an als ntain unused slts fr reserved blks. Fr example, if there are seven entries in an index blk, there are eight blks in a luster: ne prime index blk fllwed by up t 7 data blks. If there are reserve blks speified, even thugh the luster an expand t eight blks, the blks represented by the reserve blk entries are nt inluded until insert ativity has taken plae and the required blks have been btained frm the free pl. Fr example, if there are seven entries in an index blk, and ne f the entries is a reserve blk entry, then there wuld nly be seven blks in the luster initially (ne index blk and six data blks). This is illustrated by the fllwing diagram. Prime index Data Data Data Data Data - Data blk blk blk blk blk blk blk FREE SPACE When an indexed data set ;s laded with data rerds, free spae is reserved fr rerds that may be inserted during pressing. There are fur kinds f free spae: free rerds, free blks, reserve blks, and reserve index blks. 78 Versi n 1.1 Planni ng Gui de
Free Rerds Free rerds are areas reserved at the end f eah data blk. The FREEREe parameter f define mmand f the Indexed Aess Methd utility prgram speifies the number f free rerds that are reserved in eah data blk. The remaining rerd areas are alled allated rerds. Fr example, if a blk ntains three data rerd areas and yu speify ne free rerd per blk, then there are tw allated rerds per blk. See Figure 19. When rerds are laded, the allated rerds are filled, and the free rerds are skipped ver. During pressing, a rerd an be inserted in a blk that ntains a free rerd. Header Allated rerd Allated rerd Free rerd Figure 19. Example f a data blk Part 3: EDX Indexed Aess Methd 79
Free Blks Free blks fllw the allated data blks within eah luster. Fr example, if the luster ntains six data blks and yu speify 10 as the perentage f free blks, then there are five allated blks and ne free blk in eah luster. Prime All. All. All. All. All. Free index data data data data data data blk blk blk blk blk blk blk When rerds are laded, the allated rerd areas in the allated data blks are filled, and the free blks are skipped ver. During pressing, as data blks beme full, a free blk an be inluded in the lgial blk sequene t prvide spae fr mre insertins. Reserve Blks Reserve blks d nt exist in the luster. When all data blks in a luster are used and anther data blk is needed, a data blk an be reated frm the free pl, prvided the prime index blk ntains a reserve blk entry. In this ase, the reserve blk entry in the prime index blk pints t the blk, and the data blk bemes a nrmal used data blk. Reserve Index Entries Reserve index entries in send-level index blks allw the index struture t be expanded by adding new prime index blks. These, in turn, an have data blks assiated with them, thus frming new lusters. This press f frming a new luster is smetimes alled a luster split. The initial number f allated data blks in the data set an be alulated as the speified number f base rerds (BASEREC) divided by the number f allated (nt free) rerds in a data blk, with the result runded up if there is a remainder. The number f lusters in the data set an be alulated as the initial number f allated data blks divided by the number f allated entries in eah prime index blk, with the result runded up if there is a remainder.,80 Versin 1.1 Planning Guide
The ttal number f free blks in the data set (nt inluding the free pl) is alulated as the number f lusters in the data set multiplied by the number f free entries in eah prime index blk. The last Cluster The last luster in the data set may be different frm the ther lusters. It ntains the same number f free blks as the ther lusters but nly enugh allated blks t ammdate the rerds that yu have speified with the parameter BASEREC. Fr example, suppse yu intend t lad 1000 rerds in an indexed data set that is frmatted fr tw allated rerds and ne free rerd per blk and five allated blks and ne free blk per luster. The number f allated blks in a data set is: number f base rerds number f allated rerds per blk The number f allated blks in this example is 1000/2 r 500 blks. The number f lusters in a data set is: number f allated blks number f allated blks per luster The number f lusters in this example is 500/5 r 100 lusters. Nte that in bth these alulatins, if the qutient is nt an i~teger, it must be runded up (rather than trunated) in rder t ammdate all f the base rerds. Thus, in the last allated blk, there an be a few mre allated rerds than required. Hwever, the last luster an be a shrt luster beause it will have nly the required number f allated blks. In this example, the number f allated blks divided by the number f allated blks per luster (500/5) equals 100 with n remainder. If there is remainder it represents the number f allated entries in the prime index blk fr the last luster, thus the number f allated data blks in that luster. Unused entries in the last prime index blk are treated as reserve blk entries. Sequential Chaining Data blks in an indexed data set are'hained tgether by frward pinters lated in the headers f data blks. Part 3: EDX Indexed Aess Methd 81
Only allated data blks are inluded in this sequential hain. Free blks are skipped ver. This prvides effiient sequential pressing f the "data set with n need t referene the index. When a free blk is nverted t an allated blk, it is inluded in the hain. Free Pl If yu speify that yu want a free pl (by the FPOOL parameter f define mmand f the Indexed Aess Methd utility prgram), yur indexed data set ntains a pl f free blks at the end. The file ntrl blk ntains a pinter t the first blk f the free pl, and all blks in the free pl are hained tgether by frward pinters. A blk an be taken frm the free pl hain t beme either a data blk r a prime index blk. When this is dne, the blk is taken frm the beginning f the hain, and its address (RBN) is plaed in the apprpriate prime index blk (if the new blk is t beme a data blk) r in the send level index blk (if the new blk is t beme a prime index blk). Any blk in the free pl an be used as either a data blk r as a prime index blk. When a data blk bemes empty beause f rerd deletins, it is smetimes pssible t return it t the free pl (depending n the delete threshld (DELTHR) parameter). When this is dne, referene t the blk is remved frm the pr i me index blk, and the blk is plaed n the beginning f the free pl hain. Index blks are never returned t the free pl. The alulatin f the initial size f the free pl nsists f several steps, as fllws: Eah reserve blk entry in a prime index blk represents a pssible use f a data blk frm the free pl. The number f data blks that an be assigned t initial lusters is the number f prime index blks times the number f reserve blk entries in eah prime index blk. Eah reserve index entry in a send-level index blk represents a pssible use f a prime index blk frm the free pl. The number f prime index blks that an be assigned frm the free pl is the number f send-level index blks times the number f reserve index entries in eah send-level index blk. 82 Verst n 1.1 Plann; ng Gui de
Eah prime index blk taken frm the free pl nsists entirely f empty (reserve blk> entries. Hew data blks an then be taken frm the free pl fr these entries in the new prime index blk. The ttal number f suh data blks is the ttal number f entries per index blk times the number f new prime index blks (alulated in the previus step). The maximum number f blks that an neivably be taken frm the free pl is the sum f the abve three alulatins. This is the maximum pssible free pl. The atual number f blks in the free pl is the speified perentage (FPOOl) f the maximum pssible free pl, with the result runded up if there is a remainder. STORAGE AND PERFORMANCE INFORMATION STORAGE REQUIREMENTS The mlnlmum amunt f strage required by the Indexed Aess Methd t perfrm all funtins is abut 14K-B, nt inluding the link mdule r the user errr exit rutine. This is based n the fllwing assumptins: A maximum blk size f 256 bytes fr any indexed data set. Sine the buffer must be large enugh fr tw blks, we have assumed a 512 byte buffer. If yur maximum blk size is larger, yu shuld subtrat the 512 and add in duble yur blk size. Yu an imprve perfrmane by making the buffer larger. One user nneted t an indexed fi Ie at a time. If yu will have mre than ne user nneted, yu shuld add abut 625 bytes per additinal user. The IBM-supplied link mdule is inluded in yur appliatin prgram (see Figure 12). Its size is abut 250 bytes. INDEXED FILE SIZE The struture f an indexed file is highly dependent n parameters yu speify when yu reate the file. This is desribed in "Data Set Frmat" n page 70. The alulatins presented there are summarized in "Summary f Calulatins" n page 84. Part 3: EDX Indexed Aess Methd 83
PERFORMANCE INFORMATION Perfrmane f the Indexed Aess Methd is primarily determined by the struture f the indexed data set being used. This struture is determined by parameters yu spei fy when yu reate the data set. Thi sis desr i bed in "Data Set Frmat" n page 70. Perfrmane is affeted by file struture in the fllwing ways: File size. A large file spans mre ylinders f the diret aess devie, s the average seek t get the the rerd yu want is lnger. Humber f index levels. A file with many index levels requires mre aesses t get t the desired data rerd, thus degrades perfrmane. Fatrs whih influene the number f index levels are: Humber f rerds in data set. Amunt and type f free spae. Blk size. Key size. Data rerd size. /,f-\ I~_) T get a feeling fr the affet f the varius parameters n the file struture, yu shuld alulate several examples. Refer t "Summary f Calulatins." In additin t file struture, the fllwing fatrs als influene perfrmane: 1. Buffer size. If yu prvide a large buffer when yu install the Indexed Aess Methd, it is mre likely that blks (espeially high-level index blks) needed are already in strage and need nt be realled frm the data set. Cntentin. If many tasks are nurrently using the Indexed Aess Methd, interferene an result, and perfrmane is degraded. SUMMARY OF CALCULATIONS The fllwing alulatins are used t struture an indexed data set. In the alulatins requiring divisin, results with nn-zer remainders are either: 84 Versi n 1.1 Planni ng Gui de
trunated 0. r runded up G. T trunate is t drp the remainder; t rund up is t add ne (nly if the remainder is nn-zer), and trunate. Data Blk Rerds per data blk = blk size minus 16, divided by rerd size; result trunated. Free rerds per blk. G = (BlKSIZE-16)/RECSIZE 0 G = FREEREC CI 0 " " Allated rerds per data blk = Rerds per blk minus free rerds per blk. Index Blk (General) G Index entry size = key length plus 4; must be even -- add 1 if dd. Ttal entries per index blk = blk size minus 16, divided by index entry size; result trunated. Index Blk (PIXB) Free entries per primary index blk (PIXB) = speified perentage f ttal entries per index blk; result runded up. Reserve entries per PIXB = speified perentage f ttal entries per index blk; result runded up. If free entries per PIXB and reserve entries per PIXB require all PIXB entries, subtrat ne frm reserve entries per PIXB. G = KEYSIZE + 4 (+1 if dd) G = (BlKSIZE-16) / G 0 G = FREEBlK 1( f G G G = RSYBlK 1( f G G Part 3: EDX Indexed Aess Methd 85
Allated entries per PIXB = ttal entries per index blk minus free entries per PIXB, minus reserve entries per PIXB. Index Blk (SIXB) Reserve entries per sendary index blk (SIXB) = speified perentage f ttal entries per index blk; result runded up. If reserve entries per SIXB require all SIXB entries, subtrat ne. Allated entries per SIXB = ttal entries per lndex blk mlnus reserve entries per SIXB. G = RSVIX l: f G G (-1 if G = Gl 0=G-G Delete Threshld The number f blks t 11 retaln in luster O (delete threshld) is alulated in ne f three ways: a. If the RSVBlK parameter was nt speified: Humber f blks t retain in luster = ttal entries per index blk. b. If the RSVBlK parameter was speified, but the DElTHR parameter was nt speified: Humber f blks t retain in luster = allated entries per PIXB, plus ne-half f free entries per PIXB; result runded up. r r 86 Versin 1.1 Planning Guide
. If the RSVBlK parameter was speified, and the DElTHR parameter was speified: Humber f blks t retain in luster = speified perentage f ttal entries per index blk; result runded up. If the result is zer, set it t 1. Data in Data Set Initial allated data blks = base rerds divided by allated rerds per data blk; result runded up. Humber f lusters in data set = initial allated data blks, divided by allated entries per PIXB; result runded up. Ttal number f free blks in data set = number f lusters in data set, times free entries per PIXB. Indexes in Data Set Humber f primary index blks (PIXBs) = number f lusters in data set. Humber f sendary index blks (SIXBs) = number f PIXBs, divided by allated entries per SIXB; result runded up_ = DEL THR " f G 0 (If 0,!let 0 t 1) G = BASEREC / G 0 Part 3: EDX Indexe~ Aess Methd 87
Calulate the number f index blks fr levels 3 t n. Nte that levels 1 (PIXB) and 2 (SIXB) have already been alulated. When the number f index blks at a level is 1, n has been reahed and the alulatin is finished. Number f index blks at level i (i =3 t n) = number f index blks at next lwer level, divided by ttal entries per index blk; result runded up. Ttal number f index blks = sum f index blks at eah level until a level ntaining a single index blk is attained. Free Pl Number f new data blks that an be assigned t existing lusters = reserve entries per PIXB, times number f PIXBs. Number f new lusters (PIXBs) that an be reated = reserve entries per SIXB, times number f SIXBs. Number f new data blks that an be assigned t new lusters = ttal entries per index blk, times number f new lusters that an be reated. + (Sum f all G~l () 88 Versin 1.1 Planning Guide
C pl = number f new = + + G Maximum pssible free G data blks that an G 0 0 be assigned t existing lusters, plus number f new lusters (PIXBs) that an be reated, pl'js number f new data blks. that an be assigned t new lusters. G Atual number f free pl blks = speified perentage f maximum pssible free POOli result runded up. G = FPOOl " f 0 G (" '."\.J.->"/ Size f Data Set 0 Ttal number f blks file ntrl blk), plus ttal number f 0 0 G 0 G in data set = 1 (fr = 1 + + index blks, plus + + initial allated data blks, plus ttal number f free blks in data set, plus atual number f free pl blks. Part 3: EDX Indexed Aess Methd 89
90 Versin 1.1 Planning Guide
$SYSCOM usage 13 ativity reprt, terminal 38 ACTION - feth peratr respnse 24 address translatr supprt 2 appliatin design infrmatin indexed aess methd 51 indexed aess methd alulatins 84 multiple terminal manager 32 appliatin prgram exeuting 66 interfaes 6 manager 22 preparatin 50 vlume, user (PRGRMS) 34 attentin list, use f 12 ATTNlIST, use f 12 audible alarm, BEEP 27 bakup and revery 68 base rerds, lading 58 BEEP - set audible alarm 27 blk size seletin 52 blks 70 data 72 FeB 72 free 80 higher level 75 index 72 index example 76,77,prime index 73 reserve 80 send-level index 75 buffer spae 53 building the indexed data set 56 Index 91
haining, sequential 81 CHGPAN 27 luster 77 luster, last 81 mpatibility appliatin prgram interfaes 6 data set 7,funtinal ntent 7,sure prgram 5 strage sizes 7 mpnents f indexed aess methd 44 mpnents f multiple terminal manager 15 nepts, multiple terminal manager 15 nneting and disnneting the indexed data set 58 reating the indexed data set 57 CYCLE - suspend urrent terminal appliatin 26 data blk 72 data prtetin 44 data set mpatibility 7 frmat 70 indexed 48 requirements, multiple terminal mgr. 33 shut dwn 65 deadlks 65 defining and reating the indexed data set 57 defining the key 51 deleting rerds 63 indexed data sets 70 determining size and frmat 56 designing the indexed data set 51 devies supprted 44 diagnsti and revery imprvements 8 diret file request types 31 reading 60 updatlng 60 DISCONN 45,58 disnnet 37 disnneting the indexed data set 58 distributin and installatin 38 dumping 69 dupliate key 52 92 Versin 1.1 Planning Guide
entries, reserve index 80 errr exit rutine 64 errr exit, task 9 errr handling 64 errr rerding, I/O 8 estimating free spae 54 exeuting the appliatin prgram 66 exit rutine, errr 64 extensins, multi-partitin 8 extrating 64 FCB 72 features, indexed data set 43 feth peratr respnse, ACTION 24 file ntrl blk (FeB) 72 file management 29 FILEIO 29 frmat and size determinatin 56 frmat, data set 70 frmat the input and utput buffers, SETPAN 27 free blks 80 pl 82 rerds 79 spae 78 funtins f indexed aess methd 45 funtinal ntent mpatibility 7 handling errrs 64 hardware 17 higher level index blk 75 I/O errr rerding 8 Index 93
index blk 72 blk, higher level blk, send-level blks, prime 73 example 76,77 f an indexed data indexed data set building data set, defining data set features 75 75 set 73 56 and building 43 data set maintaining 68 data sets 48 file request types 30 file size 83 indexed aess methd mpnents 44 data prtetin 43 devies supprted 44 funtins 45 indexed data set features 43 indexed data sets 48 verview 43 initializatin, multiple terminal manager 35 initializatin prgram, multiple terminal manager 21 initiatin and terminatin, prgram 37 insert ativity 53 inserting 62 installatin and distributin 38 interfae, peratr 35 interfaes, appliatin prgram 6 intermediate retrievals, sequential reading 61 invking prgrams that reside in the system area 10 57 key, defining 51 key, dupliate 52 last luster 81 LINK - lad and exeute prgram 24 LINKON 24 lad and exeute prgram, LINK 24 lading base rerds 58 94 Versi n 1.1 Planni ng Gui de
maintaining the indexed data set 68 MENU - return t multiple terminal manager ntrl 26 MTMSTORE 33 mve ursr t speified psitin, SETCUR 27 multi-partitin extensins 8 multiple terminal manager nepts 15 mpnents 15 data set requirements 33 hardware 17 initializatin 35 initializatin prgram 21 verview 15 prgram peratin 21 sftware 21 utilities 31 peratr interfae 35 utput t an asynhrnus terminal, WRITE 26 perfrmane infrmatin indexed aess methd 83 multiple terminal management 40 planning the indexed data set 51 PRGRMS, user appliatin prgram vlume 34 PGMRPT (prgrams reprt) 38 prime index blks 73 prgram exeptin trae 9 (header) r TCB dependenies 13 initiatin and terminatin 37 management 23 manager (appliatin prgrams) 22 peratin (indexed aess methd) 49 peratin (multiple terminal mgr) 21 preparatin 40 reprt (PGMRPT) 38 Index 95
prgramming nsideratins 32 prtetin data 44 system area 9 f) reading, diret 60 reading, sequential 61 rerds delli!ting 63 free 79 inserting 62 lading base 58 reading diret 60 reading sequential 61 updating diret 60 updating sequential 62 revery and diagnsti imprvements 8 revery, bakup and 68 revery withut bakup 68 rennet 38 referenes t system area data 10 rerganizatin 69 REPORT - terminal ativity reprt 38 request types, diret file 31 request types, indexed file 30 reserve blks 80 reserve index entries 80 return des, system funtin 64 return t multiple terminal manager ntrl, MENu 26 sreen frmat vlume - SCRNS 34 sreen print 38 SCRNS - sreen frmat vlume 34 send-level index blk 75 seleting the blk size 52 sensr i/ appliatins 12 sequential haining 81 reading 61 updating 62 set audible alarm, BEEP 27 SETCUR - mve ursr t speified psitin 27 96 Versi n 1.1 P lann i ng Gu fde
SETPAH - frmat the input and utput buffers 27 shut dwn, data set 65 sign-n 36 sign-n file - SIGNONFl 35 SIGHONFL, sign-n file size and frmat determinatin 56 size, indexed file 83 sure prgram mpatibility 5 spae, estimating free 54 speial nsideratins 9 strage dump 9 perfrmane infrmatin 83 requirements 83 sizes 7 supervisr extensins, user-written 11 suspend urrent terminal appliatin, CYCLE 26 system area, invking prgrams frm 10 area prtetin 9 data area, referenes t 10 funtin return des 64 task ~rrr exit 9 TCB dependenies r prgram (header) 13 terminal 33 terminal/sreen management 26 terminal ativity reprt 38 terminal server prgrams 22 terminatin, prgram 37 trae, prgram exeptin 9 updating, diret 60 updating, sequential 62 utilities, multiple terminal manager 31 use f attentin lists (ATTNLIST) 12 user appliatin prgram vlume - PRGRMS 34 user-written supervisr extensins 11 using &SYSCOM 13 virtual terminals 11 Index 97
0 WRITE - utput t an asynhrnus terminal 26 98 Versin 1.1 Planning GUlde
READER'S COMMENT FORM IBM Series/1 Event Driven Exeutive Versin 1.1 Planning Guide G C34-0328-0 Yur mments assist us in imprving the usefulness f ur publ iatins; they are an imprtant part f the input used in preparing updates t the publ iatins. I BM may use and distribute any f the infrmatin yu supply in any way it bel ieves apprpriate withut inurring any bligatin whatever. Yu may, f urse, ntinue t use the infrmatin yu supply. Please d nt use this frm fr tehnial questins abut the system r fr requests fr additinal publiatins; this nly delays the respnse. Instead, diret yur inquiries r requests t yur I BM representative r the I BM branh ffie serving yur lality. Crretins r larifiatins needed: Page Cmment (") S... " 0:» 0" :::s t : :::s (1) Please indiate yur name and address in the spae belw if yu wish a reply. Thank yu fr yur peratin. N pstage stamp neessary if mailed in the U.S.A. (Elsewhere, an IBM ffie r representative will be happy t frward yur mments.)
Reader's Cmment Frm Fld and tape Please D Nt Staple Fld and tape I II II I NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATES BUSINESS REPLY MAIL FIRST CLASS PERMIT NO. 40 ARMONK, NEW YORK POSTAGE WILL BE PAID BY ADDRESSEE I BM Crpratin Systems Pu bl iatins, Dept 27T P.O. Bx 1328 Ba Ratn, Flrida 33432 Fld and tape Please D Nt Staple Fld and tape ---- --- - = =-= =..= ----- - - - --- Internatinal Business Mahines Crpratin General Systems Divisin 4111 Nrthside Parkway N. W. P.O. Bx 2150, Atlanta, Gergia 30301 (U.S.A. nly) General Business Grup/Internatinal 44 Suth Bradway White Plains, New Yrk 10601 (I nternati 0 na I) G C34-0328-0 Printed in U.S.A.
READER'S COMMENT FORM IBM Series!1 Event Driven Exeutive Versin 1.1 Planning Guide GC34-0328-O Yur mments assist us in imprving the usefulness f ur publiatins; they are an imprtant part f the input used in preparing updates t the publiatins. I BM may use and distribute any f the infrmatin yu supply in any way it believes apprpriate withut inurring any bligatin whatever. Yu may, f urse, ntinue t use the infrmatin yu supply. Please d nt use this frm fr tehnial questins abut the system r fr requests fr additinal publiatins; this nly delays the respnse. I nstead, diret yur inquiries r requests t yur I BM representative r the I BM branh ffie serving yur lality. Crretins r larifiatins needed: Page Cmment :... ~ " :» 5" :::3 r :;. CD Please indiate yur name and address in the spae belw if yu wish a reply. Thank yu fr yur peratin. N pstage stamp neessary if mailed in the U.S.A. (Elsewhere, an IBM ffie r representative will be happy t frward yur mments.)
Reader's Cmment Frm Fld and tape Please D Nt Staple Fld and tape IIIII NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATES BUSINESS REPLY MAIL FIRST CLASS PERMIT NO. 40 ARMONK, NEW YORK POSTAGE WILL BE PAID BY ADDRESSEE I BM Crpratin Systems Pu bl iatins, Dept 27T P.O. Bx 1328 Ba Ratn, Flrida 33432 Fld and tape Please D Nt Staple Fld and tape ---- ----- --- - ---- - - --_.- --- I nternatinal Business Mahines Crpratin General Systems Divisin 4111 Nrthside Parkway N. W. P.O. Bx 2150, Atlanta, Gergia 30301 (U.S.A. nly) General Business Grup/Internatinal 44 Suth Bradway White Plains, New Yrk 10601 (I nternatinal) G C34-0328-0 Printed in U.S.A.
- ---- ----- - - - --_.- Internatinal Business Mahines Crpratin General Systems Divisin 4111 Nrthside Parkway N.W. P. O. Bx 2150 Atlanta, Gergia 30301 (U.S.A. nly) f General Business Grup/Internatinal 44 Suth Bradway White Plains, New Yrk 10601 (Internatinal) GC34-0328-0 Printed in U.S.A.