Home

AMOS Basic XCALL subs

1. Menem E ae 9 mm m AAA PETERET AANA Sh a TR REEDS BEAR IEE om e m m EE NIE NAAR FOUN e EE be Dat A 2 02 0 0 720 VO EEE EA OO VA VE AAP ADVE Ae Bah Riek del ERE Did you find errors in this manual if so please specify the error and the number of the page on which it occurred we KA sho ret 5 3 5 E ae ay Ki Go Za rf d 15 0 t rt KE n 2 Ki H EE A i EENS E ESAS A A 0 EE EE O SS 5 e st 978 02 AAA 800 03
2. Finally the XCALL SPOOL subroutine can use a floating point variable or expression to set the width measured in characters of the page SPOOL only uses this value if you have specified the HEADER switch 6 the SWITCHES variable WIDTH affects the appearance of the banner which is only printed when using the BANNER switch 0 SWITCHES and the header text it does not affect the number of characters in the print Line When a file is spooled to the printer WIDTH determines how wide the banner is to be by controlling the number of characters that form the banner alphanumerics At the top of each page SPOOL places the header text Part of the header text is a page number which is oriented near the right hand margin That right hand margin 8 determined by WIDTH The actual lines that are printed are not controlled by WIDTH In other words print Lines whose lengths have previously been established are not changed via the WIDTH value As an example of WIDTH to print a file with a banner that fits on an 8 1 2 X 11 page and a header with the page number appearing toward the right of the page you can set WIDTH to FO Your CALL SPOOL program Line should appear something Like this 10 XCALL SPOOL p TEXT LST T1810 17 2 NORMAL 0 or WIDTH can appear as a f gating point variable Like this 10 CHAR PER LINES Q 20 XCALL SPOOL TEXT LST TI8107 81 2 NORMAL
3. CHAR PER LINE In either case WIDTH will not force the file you print out to start printing a new Line at 70 characters Data tar SPOOL FILENAME e PRINTER o SWITCHES COPIES FORM 181 QUPP To use the LPP feature of SPOOL the HEADER switch of the SWITCHES feature must also be peer The floating paint variable or expression included on the XCALL SPOOL Line specifies the number of Lines per page When a full page according to the LPP specification is printed the SPOOL subroutine prints a form feed and then prints the header at the top of the following page To allow 48 Lines on a page counting the header for example LPP should appear something Like this in the program Lime 10 XCALL SPOOL TEXT LAST 1810 8T peg NORMAL 70 48 or LPP can appear as a floating point variable Like this 10 LINES PER PAGE 48 20 XCALL SPOOL TEXT LST T1810 81 2 NORMAL 70 LINES PER PAGE DSs 10008 00 A ru SC m LE e SPOOL XCALL SUBROUTINE FOR SPOOLING FILES TO THE LINE PRINTER Page 6 8 Remember if LPP is the only option you care to use you must have all previous placeholders in place 10 CALL SPOOL TEXT ESTA SS CR 2 5 6 2 SPOOL ERROR MESSAGE The SPOOL subroutine returns only one error message No spooler allocated MOD HO IPT CIAO INIT ITO MSP IOS IOI NOE mon TACO TNS if you see the message above it means that no L
4. THE INTERCONSISTENCY PROBLEM 2 THE FLOCK SUBROUTINE eee ee ee ee 4 5 1 FLOCK Program Requirements AREER FLOCK Calling Sequence 52 4 Action amp Mode 4 5 2 1 Ai E 3032 3 i 3 TE E le File SS FOG HAH EEE 9 e 9 s ee ane oam e d 5 0 5 Record ORONO Ce is A e i 5 0 5 Return Code eG 4 se a sg e zs es a OG m oW m og ueue Block Requirements E OD Pob A 1 D55 310008 00 REY ADO Pag 4 15 7 0 lt A AUR g E Lal Le OP 9 i ES Vi MI Ai VU F 2 3 4 7 ES jw S v f p a A dd Ex ee E ud P oa ny K awe Ze s yaw 6 7 6 8 6 8 Ei a Xx ALPHABASIC XCALL SUBROUTINE USER S MANUAL bot USING FLOCK p 4 6 1 File Open Interlocks EP 4 4 1 1 The Multiple pdate Problem The Interconsis stency Probiem Record Update Interiocks 4 4 2 4 4 2 The Multiple 1 Update Problem 4 4 2 2222 The interconsistency Problem Improved File Interlocks 4 4 3 4 6 5 1 Example 00000000000 6 5 DEADLOCK AND HOW TO PREVENT TE amp 6 SUMMARY vg 6 6 1 Quick Reference Summary of Actions Modes
5. lo Ae Pu nu P Haat Me SANDS cl EN TT NEEN mr 6464006656002400 A et RV EAA RAE Se fe bia deih ahe kb Kafe EEN ENEE EE EE o mmm INDIAS V Mu EARN Vie a St EAN OA E E E EE E ENEE E E E TE NN ESN KENNT tl dei e as H dr Keier e EA AA dA f Kei Kai kb EE 8 HH E f 2 What kinds of manuals wouid you like ta ses in the futura 21017 1 1 lt II AE A A O ae es TIE NT SPE Ro EE 0000 00 DEE EECH EES EE ee Pipase indicate the type Gf reader that vou represent check ail that appiyj Alpha Micro Deaier ar OEM Lol Mori Droge ammer using Aipha Micro computer for Business applications Education applications Seiuientific a rads cientific applications Pu wo Sea ce EE Other piease specify 8 Programmer Di Assembly language 1 Li Higherlevel language a Li Experienced programmer L1 Little programming experience pt M Ae D LJ Student t wt Gthar iplease specify 060 a 0 1 00 0000000000000000 nU e E EE SE ZEIT SR NE NUMBER 11 EE 2 RENTRER
6. Mas ae 4 7 Eu Ke the File Locking subroutine that protects data file from be ng accessed by more than one program in a given moment so that ri file won t be updated by two or more program users concurrently f Sen vs Pu op ri E 900 Ag d S xS i 5 0 5 e napteh 5 88 ALLE the subroutine used to set test and clear ES en gm he pei E NEN e we aye 3 WI geet oe 7 ME or eye sir d V M LOCKS on files and Gevtces 5 subroutine is similar 6 some respects Hoya Dt S ds oa y Toa ug 4M e d wm gu is BO FLOCK discussed in Chapter fi ud g E 110 fu cu 5 e y chapter 6 talks about SPOOL Can acronym for Simultaneous Printer Out put Chan cx Ge Gs 2B Ze ene i a NU Pe n mm ok Aa rk 3 5 PE a 8 M a n T7L1ne the subroutine that inserts or spools a file into a printer SES E e xi Ps s ent S 5 a ANA 5 jo E H sas 2 Se CA 3 2 e 7 i 46 queue Tor immediate or eventual processing outside of the contro of the job un 2x PU M SU an de de om amp i amp ZS y PRM HL Y nagy 6 110 the AL OMSHAS TC co SYM o E A K e EE Das 1 berg do n Chapter discusses XMOUNT the subrout ex ine used to mount a disk from within when a user must ac a RiphaBASIC nro
7. IPRS A 58189 0 23322 S Se E d me z 1 AMS ER pl E FLTCNV PRG are re entrant 8 808 SBR is not so you must not Se i Ed 4 d USING BASORT IN AN ALPHABASIC PROGRAM You may use BASORT to sort both random and sequential files Like all other subroutines discussed in this manual FEL LB E rom the Alpi bouge program using the XCALL keyword Then dd wi de i 5 EN EN Phe parameters of up to three keys you wish to sort AiphaBASIC via the XCALL BASORT command Line c o t s 9 TA Y ei Am A e age ek 5 C using BASORT for random files requires some different parameters than does e USING BASORT for sequential files The next two sections describe the specific methods of using SASORT for both random and sequential fil fated Sorting Random Files When you use BASORT to sort random files BASORT sorts the file onto itself that is it replaces the original unsorted file with a file containing the sorted data Therefore if you wish to retain a backup copy of the unsorted file you must create a Separate copy to be sorted 9 506 XCALL SUBROUTINE FOR SORTING FILES Page 2 3 BASORT for random files is called via variables or constants in this order where the ampersand R means a continuation of the AlohaBASIC Line Statement XCALL BASORT CHANNEL NUMBER RECORD COUNT RECORD SIZE amp KEY
8. OV NAO As with all of the XCALL subroutines callable from AlphaBASIC the SPOOL subroutine must be indicated by the XCALL keyword followed by the name of the subroutine SPOOL The keyword and the subroutine name 3 comma and the filename tas either a string variable or expression to be spooled are mandatary 10 XCALL SPOOL TEXT LST 055 10008 00 REV 400 SPOOL XCALL SUBROUTINE FOR SPOOLING FILES TO THE LINE PRINTER Page 6 5 where TEXT LST is regarded as an expression by the ALphaBASIC program and TEXT LST is the file you want printec Note that the expression is enclosed in quotation marks This et program accomplishes the same thing because SPOOL accepts a string variable designation 5 MAPT FILENAME S 26 10 FILENAME TEXT LST 20 XCALL SPOOL FILENAME Notice in both of the above examples that no options have been specified ALL the parameters are set by default 6 1 1 2 XCALL SPOOL p FILENAME PRINTER A ETI TST OA rien tra AAA Modifying the above examples the XCALL SPOOL command Line may specify a printer via a string variable or an expression S MAP1 PRINTER S 6 10 PRINTER TI810 20 XCALL SPOOL TEXT LST PRINTER Gr 10 XCALL SPOOL TEXT LST T1IS10 where TI810 is the name of a printer defined by the monitor command Note that the string expression TISTO must always be enclosed in quotation marks
9. Search sequence s a s s gt s s Sequential file s a e s a s SET 00000800 s w a way wm A BORE KOY x A di DEP SPOOL acronym s a 55001180 a TILE a eoa wk Na SWITCHES numeric code a a WITCHES ODLION Ae a x gt amp Xx SYSTEM command s s IR s es a SYSTEM memoPy qw xo do gt dm 1 wed j i 4 to 1 2 6 1 1 3 8 a 8 2 Pe ers C 1 E f 1 Qi CS LAB E 2 EI Ei a a a a 2 2 i Laj User memory a Variable a a s o a o 1 73 5 83 Ada Se 2 3 106 006185 5 ERG ESE C d EN FL y 60 00 Du un ue E x ra FL WAIT switch a a a a p a a a a 6 3 WIDTH Opt ton 3 EJ E ES x 2 se 6 4 fo d XCALE uw aoe 2 a cue PEA A 21 XCALL statement a a s s a s ALOGK a de 4 WS we BSS wR A KLOCK MODE ce ce XLOCK record number calculation ALCOCK 8 46378 s Ae E CA DES x AMOUNT uode wy ot RO GR Mee ee AMOUNT ZU Option s a e d i 4 E ege WOR LA 1 i 8068008516 X
10. p zf CU E ns d PS vm eat ave 77 p pe ZA E H i enter customer number RECORDNUM i lease Note Customer ID is just number of that logical recorda D Calculate relative disk block number assumes logical 5 records begin with zero 4 1 a gt ove ZG lt P ji 8 INT CRECORDNUM 10 4 the ia block used by the record m v e Se Rae 4i gene don Ka 3223 a D use E 8 iran Ka i rate Sech eed Sen As 4 ELA 100 LOGICAL RECORD Cu d informations Customer IDE CUST ID Customer nameg s 8 73 D mm yy nn eed vd Aue CO un f um cou gc A c wc ng unc un Ai aS unt O 3 KS Ke 2 te TA Ki 3 e ween 8 7 3 Vi e E A 3 g My poe i t8 90 PRINT Sales contact CONTACT 3 2 g ampi nmm 7 0 n i 1 95 PRINT TABS Phone PHONE 2UD UPDATE 205 INPUT bo you wish to change any info 210 TF UCSOQUERYO PN THEN GOTO LOOP 5 PRINT Customer ID CUST ID Se 090 eel INPUT Enter customer names CUSTOMER ees INPUT Enter sales contact CONTACT 30 INPUT Enter phone number PHONE E WRITE S100 LOGICAL RECORD Force BASIC to bring different disk block into memory If we are in first disk block since blocking factor is
11. 0 THEN EMPLOYEE NOT ON FILE GOTO 6 7 65 XCALL FLOCK 3 4 RET 1002 KEY2 0 1 RET lt gt 1 THEN 55 75 INPUT DO YOU WISH TO WAIT ANSWERS 80 IF UCSCANSWERS lt gt Y AND UCSCANSWERS lt gt YES R THEN EMPLOYEE ENTRY 85 XCALL FLOCK 3 0 RET 1002 KE YZ 90 READ K1000 EMPLOYEE RECORD 98 XCALL FLOCK 5 0 RET 1002 KEY2 100 XCALL FLOCK 5 0 RET 1001 KEY1 105 CALL DISPLAY DISPLAY EMPLOYEE RECORD 110 GOTO EMPLOYEE ENTRY 200 LEAVE 210 CLOSE 1001 CLOSE 41002 220 XCALL FLOCK 1 0 RET 1001 230 XCALL FLOCK 1 0 RET 1002 300 END 400 LOOKUP REMARK SUBROUTINE GOES 499 RETURN 500 DISPLAY REMARK SUBROUTINE GOES HEREx 599 RETURN 4 5 DEADLOCK AND HOW TO PREVENT IT NOTE For the purposes of the following discussion having permission to open a file or use a record is referred to as possessing a resource The possession of a resource by some job XYZ can directly or indirectly cause the execution of other jobs to be delayed It is then possible one of these delayed jobs to possess a resource needed by job XYZ thus causing execution of job XYZ to be delayed also This is known as a DEADLOCK None of the jobs involved can proceed since each requires a resource owned by one of the other jobs involved The situation is permanent because none of the jobs involved can proceed until one of the other jobs proceeds and relinguishes a needed resource PEA BLOCK can only occur if a job request
12. D8 10002 00 dcc 70 If you use an XCALL subroutine that uses the monitor queue vou must be sure that enough queue blocks are available before executing the subroutine If not enough blocks are available when the AlphaBASIC program executes the XCALL subroutine the system could lock up and require manual reset Your AlphaBASIC program can check the number of free queue blocks before you perform the XCALL subroutine by using the WORD function to read the GFREE memory location The program should not continue if the quantity of free queue blocks is insufficient To find the QFREE memory Location for an AMOS System check the current SYS MAC file For AMOS L systems see the SYS M68 file to see the location of GFREE The queue block requirements for each of the XCALL subroutines is discussed in the appropriate chapter 5 5 1 0008 00 REV 0 CHAPTER 2 BASORT XCALL SUBROUTINE FOR SORTING FILES BASORT 65 an external subroutine callable from AlphaBASIC via the XCALL keyword which can sort both random and sequential files A random file is one in which the records are physically grouped together in ane area af the disk and where any point within that file can thus be found immediately by calculating an offset from the file s beginning A sequential filets records are not necessarily contiguous on th disk but are Linked in sequence by pointers in each segment that indicate where on the disk the next segment can be found Far inform
13. E E e Ki E E 3 ALPHABASIC XCALL SUBROUTINE USER S MANUAL index AMSORT SYS aaa e BANNER switch s a a e BAS ersatz name s BASORT s e BASORT error e s gt Binary variable a a e Channel number a o a a Clear lock mode a Clearing a tack a s e COMMON s s a s o Common data s e Common storage as m a COMMON variable length Concurrent 866868385 a Coordinating shared file access i ZS VS 0 m E E COPIES option a a e Data packet n e gt Data tyDe s e gt Deadlock o 4 wo DEL command a a e DELETE switch a s w s Disk block Ki t gt S Bisk based polyphase merge sort Exclusive USO Extension 50 th E x SS PPOBWILOCH amp amp 3 ELE MOCK x xoxo FILE option e e File record w ea File open interlock as a FLOCK 4 amp ACTION parameter a a FILE parameter e MODE parameter s RETURN CODE parameter FLTCNV PRG e s 2 a FORM option a o s Page Index d 65 6 1 1 Co 5 4710 4 15 de 1 E 3 oe 7286 a 98 3 3 f d i 1 Cp APE ASE A o J ma mb E de Do PO UE 7m nf 0 3 to 1 4
14. ONE 1 5 6 WRITE 1 ONE 5 6 CLOSE 41 3 amp END ONE ONE 1 amp amp WRITE 4 ONE amp 6 CLOSE 1 amp END 6 TL STI mm mx men mr DY ven e o E O se O EE UTA LOND GOA TRIE HER OEM e SET E OmU HORE HE MD AY HGR DUC MC QUT A ABO 8 3 IS VU A ee 6 multiple update problems from occurring we need some method to prevent the kind of overlap in READ modify WRITE sequences shared data orn s illustrated above prevent To that D3S 10008 00 REV 0 FLOCK XCALL SUBROUTINE TO COORDINATE MULTI USER FILE ACCESS Page 4 4 6 2 THE INTERCONSISTENCY PROBLEM Consider the following two programs 10 OPEN Z1 FILE RANDOM 6 KEY 20 KEY 1 READ 25 ONE ONE 1 WRITE 1 ONE 30 KEY 2 READ 1 35 ONE ONE 1 WRITE 1 ONE 40 CLOSE 1 END 10 OPEN 1 FILE RANDOM KEY 20 KEY 1 READ 1 0NE 30 KEY 2 READ 2 TWO 40 PRINT ONE TWO 50 CLOSE 1 END If the values in records one and two of FILE are identical then they should continue to be identical if the first program which increments the values in both records by one is executed Hence if the values in records one and two are identical and we execute both of the above programs concurrently we would Like the sec
15. RANDOM KEY 5 5 KEY 1 READ 1 0NE 6 ONE ONE 1 WRITE 1 ONE 32 1 OPEN 1 FILE RANDOM KEY KEY 1 2 READ 1 ONE KEY 2 READ 1 TWO PRINT 08 66 1 CLOSE 1 END 4 9 ZS oo OS OS An VAT V XUI VA QM OCA op Be OS C 5 KEY 2 READ 1 ONE 6 ONE ONE 1 WRITE 1 0NE 4 6 CLOSE 1 END 5 chte TH INE come zeen CSET oC gt gro 4000 QUUM INERT IMEC GA dt om pen lt lt ON JET ESCH Drop ARIE en ork snb ANE 004 CUTE ETT CONS TEED res 9x62 m fh CS un uw The READ WRITE READ WRITE sequence in the first program can be considered as steps in a single update operation To maintain interconsistency that is to eliminate the situation outlined above we need a mechanism to prevent access to a collection of data during any update operation Otherwise the collection of data we retrieve may be only partially updated due to interference from another program which has concurrently accessed that data in actual applications the loss of interconsistency described above can cause you to access nonexistent records through a faulty index file to derive incorrect totals on reports to create i
16. exits so be careful that your program clears any Locks it has set before it exits For more background information on why locks are necessary see Chapter 4 FLOCK XCALL Subroutine to Coordinate Multi user File Access S8 t10008 0D0 REV ADO XLOCK XCALL SUBROUTINE FOR MULTIUSER LOCKS Page 5 2 2 1 LOADING XLOCK INTO SYSTEM MEMORY You must include the DSKO XLOCK SBR 6 in system memory before you can use an AlohaBASIC program implementing XLOCK To load XLOCK SBR into system memory you must have a line in your system initialization command file that performs that function For more information on loading subroutines into system memory during system boot up see the AMOS System Operator s Guide 085 10001 00 or the AMOS L System Operator s Guide DSS 10002 00 va i et au KE EN 6277777 A Ya THE XLOCK SUBROUTINE XCALL XLOCK MODE LOCKT LOCKE Where MODE The function you want to perform These modes are Mode Mode Mode Mode Set lock and return Set lock Wait if already locked then set Clear lock if set by your job Return List of all system locks and the jobs that set them PE Oa Lad fs C RY QS mm See below for a discussion of each mode LOCKT The first digit of the lock code See below LOCKE The second digit of the Lock code See below Use MAP statements at the front of your program to define MODE LOCKT ana LOCKS as
17. must already be granted THe request id 4 in a first came first served queue and the program is delayed until the request can be granted Requests permission to read write all records of File for exclusive use i e prd essing will update and nossibly re create file Permission to open File must already be granted If the request cannot be immediately granted Return Code 1 is returned Informs FLOCK that processing of Record of File for which permission was granted by Action 3 has been completed The record is unlocked If data has been buffered for output it is written to disk FLOCK XCALL SUBROU Action 2 Mode OG Action 3 Mode EE EE Action 3 Mode Action 3 Mode Action 3 Mode Is KE Action 4 Mode 5 e5 Action amp Mode o Action 5 Mode 055 100086 000 REV 06 FLOCK XCALL SUBROUTINE TO COORDINATE MULTI USER FILE ACCESS Page 6 7 Action 6 Mode 0 Informs FLOCK that exclusive processing of File for which permission was granted by Action 4 has been completed The file is unlocked Any succeeding programs which are granted use of File by Actions A or A will automatically reopen File This is done in case exclusive processing of File has caused it to be re created Tf data has been buffered for output it 18 written to disk 4 3 2 2 File File specifies a file channel number File 9 ignored by Action 2 and may
18. 18 record number gt 10 will force in next disk block if LOCKE 1 THEN RECORDNUM 10 ELSE RECORDNUM Q Now bring in different disk blocks READ 100 LOGICAL RECORD Ed EK E E eu AO PO D f a 5 Cu AS Ze a Yo 2 Si La PH i RET GM ait E gm nt C B Ki E Pu YS os Ai PE XLOCK XCALL SUBROUTINE FOR MULTI USER LOCKS Page 5 9 270 Release the lock 275 MODE 2 280 XCALL XLOCK MODE LOCK1 LOCK2 285 LOOP 290 INPUT Do you wish to see info on another customer 295 IF UCSCQUERYO Y THEN GOTO LOOK 300 EXIT 505 PRINT Returning you to Command Level 310 CLOSE 0 315 END 320 FILE ERR Oops File didn t exist 325 PRINT File error Please see System Operator 330 END Jaf SUMMARY XLOCK can both set and test system Locks to help users from conflicting in their attempts to use system resources These locks are not far security they are for the convenience of the users A user may lock a file or a device to prevent any other user from accessing it may test a lock to see if another user has already set a lock and is using the file or device or may clear the Lock sa that the programs of other users may access the file or device Before running any program containing the XCALL subroutine you must include the XLOCK SBR in system memory by using the SYSTEM command within the system initializatio
19. 25 MAPI LOCK B 2 30 MAPT LOCK2 B 2 355 MALT LOCKARRAY 40 MAP LOCKENTRY 25 45 MAPS JOB B 2 50 MAPS 11 B 2 55 MAPS 12 8 2 60 START 65 INPUT MODE LOCKT LOCK MODE LOCKT1 LOCK2 PD PLAG MODE 75 iF MODE 3 GOTO DISPLAY 80 ACALL ALOCK MODE LOCK2 85 PRINT Made MODE 0 TF FLAG AND MODE lt gt O PRINT Lock already set 95 TF FLAG AND MODE 0 PRINT You didn t set that Lock 100 TF FLAG AND MODE f PRINT You cleared the Lock 105 IF FLAG AND MODE gt 1 PRINT You cleared more than one Lock 110 SOTO START 115 DISPLAY 120 XCALL XLOCK MODE LOCKT LOCKARRAY 5 PRINT Your job number is LOCK D PRINT Current Locks in use MODE 1535 iF MODE 0 GOTO LOOP 140 FOR COUNTER 7 TO MODE 145 PRINT SPACES 150 PRINT STRILTCCOUNTEROD U4 STR G2CCOUNTER 3 155 PRINT SPACE PRINT CJob s JOB COUNTER 272 160 NEXT 165 LOOP 470 PRINT SOTO START i to Py n3 XLOCK is often used to lack individual records within a file se that more than one user can update that file at the same time LOCK might contain a number that represents the particular file you want to open for multi user ine rhaos by C containing the filets file channel numben LOCKE ight hold a number that represents the 0 0 record within the file that u want to update aH 0 X yo 2 96 1 Calculating Record Numbers We assume that you will usually be usi
20. EE ORGANICA FONS oos esa EE ea ae 5 ADDRESS SUR 3 Doa Fert ee ee AI a a a e SN rr Bm mm mim H NS NS RENE AV EIA I HE IE 1220000 ANNA m 6 a LN INN CITY STATE ZIP OR COUNTRY E n el et ju VPI monn Auf A BA As O a mre mer m me T mm m mn tm MAR ALONG LINE 1 E C ub Iz uet xc WR SS AE Ces ot NU o Aen EOD em wes SUL ee Sep wem mE dO 9 P 29 AM GG ign die een ent Ze Wenn s eem eg Gees OUS NUM ee GUY ID en foris EN SAU DUM GRAMM 20 Se AMUS E WUIS LORD um UA Vah Vx Ges NOR DA STAPLE STAPLE FOLD FOLD eee ee E 5 8 6 4 9 9 9 e P GO 6 O 9 amp 9 9 amp 8 D O P O Bn DO ee amp 2 P P 6 9 D 4 4 a
21. MAP statements see Chapter 8 Memory Mapping System of the AlphaBASIC User s Manual DWM 00100 01 1 3 USING XCALL SUBROUTINES There are several things you should keep in mind before beginning to use XCALL subroutines 1 Aii XCALL subroutines must have a SBR extension The subroutines supplied with your system software reside in account 7 6 of the system Disk Whenever a subroutine is requested AlphaBASIC follows a specific pattern in looking for the requested subroutine The search sequence is as follows where CP designates the Project programmer number that specifies your account 8 System memory D User memory C Default disk fUser P pni d Default disk f User 07 e 258 17 26 Notice that AlphaBASIC checks first system then user memory If a subroutine is to be called a large number of times it is wise to load it into memory to avoid the overhead of fetching the subroutine from disk If the subroutine is not in memory AlphaBASIC attempts to load the subroutine from the disk following steps c through e of the search sequence above If an AlphaBASIC program fetches a subroutine from disk AlphaBASIC Loads it into memory oniy for the duration of its executiong afterward it is removed from memory if it is loaded via this automatic procedure NOTE Subroutines Loaded into system or user memory via the LOAD command remain in memory until you reset the system or until you use the monitor command DEL to
22. Mode File and Record are all either floating point expressions which evaluate to positive integer values or string exoressions which represent positive integer values 2 Return Code is a 6 byte floating point variable hs 2621 Actian amp Mode Action modified by mode specifies the action to be performed by FLOCK A auick reference summary of the actions and their modes is in Section 4 6 1 The actions and their modes Action 0 Mode 0 Requests permission to open File for non exclusive use that is other users can access the file The request is placed in a first come first served queue and the program is delayed until the request can be granted Action 0 Mode 2 Requests permission to open File for exclusive use The request is placed in a first come firsteserved queue and the program is delayed until the request can be granted Action O Mode 4 Requests permission to open File for noncexcilusive use If the request cannot be immediately granted Return Code f is returned Action 0 Mode 6 Requests permission to open File for exclusive use if the request cannot Ge immediately granted Return Code 1 is returned Action 1 Mode 0 Informs FLOCK that File has been closed Unlocks the file implicitly informs FLOCK that any processing of records in file has been completed i e Actions 5 ar 6 are performed automatically as necessanry 0S8 10008 00 REV 0 TINE TO COORDINATE MULTI USER FIL
23. S Ra e e m osa ap m EAR e d e o Ki 1 1 1 n SAMPLE PROGRAMS 1 E cq e se zs a a e om e o RGF Pm MR o e oa 8 a SS e e 1 2 1 3 USING XCALL SUBROUTINES 0 EENEG ho CHAPTER 2 BASORT XCALL SUBROUTINE FOR SORTING FILES LOADING BASORT INTO MEMORY ORNA 7 USING BASORT IN AN ALPHABASIC PROGRAM 2 2 1 Sorting Random Files 2 2 1 1 An Example of using BASORT on a Random File 2 2 2 Sorting Sequential Files RA Calal t An Example of Using BASORT on a Sequential File 5 885087 ERROR MESSAGES ARRA AA D SUMMARY SE ae RON GE NOR RON ROANOKE CR OR E ROCA RR Ru a 2 Es Za PO a Tu 1 d PND A f Os p P j jw PG PRO d PR CHAPTER 3 COMMON XCALL SUBROUTINE TO PROVIDE COMMON VARIABLE STORAGE La 5 LOADING COMMON INTO USER OR SYSTEM MEMORY USING COMMON EROM WITHIN AN ALPHABASIC PROGRAM ed 1 O72 3 2 1 Defining Variables i 5 2 2 The XCALL COMMON Command Line seau wn 373 5 AN EXAMPLE OF COMMON amp SUMMARY ee AM i a Pad eh 25 3 CHAPTER 4 FLOCK XCALL SUBROUTINE TO COORDINATE MULTI USER FILE ACCESS i THE MULTIPLE UPDATE PROBLEM a
24. Xe p ir v A M y 8 5 z Lo 7 5 1 zT 3 de 3 RFRAIGHTY in an AiphaBASIC program that performs a kind of simple animation i 04 ATEOS d TL MAP 1 DIRECTION E A 4 YO Y yx E IHR RANDOM DIRECTIA RAS 9y gn age Ug 5 3 E 5 A MEE 1863 1 TAT 5 HRA LEP FF K E ELS 2 Posa 3 nx Ans GR ON DIRECTION GOSUR UM DOWN STRAIGHT 41 E ft We K ea JUN 2 5 c 3 ue i 30 GUTO RANDOM DIRECTION TUM PRA ram pase opis rd E OOO UP PRINT 5 1884 1 s RETURN a Am 47v ot F a a A d 2s EN i f n E y 5 CUOU DOWN PRINT PARC TGP TN RETURN MH STRAIGHT gt PE INT WE TURN 3 4 7 g mys D55 10008 00 REV ADD INTRODUCTION Page 1 3 In the pages of this manual you will be seeing a number of program examples that use labels Notice that iine 10 of the above program example is a level 1 MAP statement we map the variable DIRECTION as a floating point variable F5 AlphaBASTC provides you with the ability to specify the pattern in which variables of ail kinds floating point string and binary are allocated in memory mapping variables at different levels you may define whole groups of related information and reference single elements or an entire group aS you choose You will see MAP statements in many of the examples within this manual For Further information on interpreting and using
25. access Then afterward we detail how you can use FLOCK from an 6 program to coordinate shared file access and processing and offer you some schemes to imolement FLOCK in your AlphaBASIC programs Finally we discuss the hazards of Deadlock and haw FLOCK conquers that too 4 1 THE MULTIPLE UPDATE PROBLEM Consider the following program 10 OPEN 1 FILE RANDOM 6 KEY 20 KEY 1 30 READ 1 ONE 40 ONE ONE 1 SO WRITE 1 0NE 60 CLOSE 1 70 END The purpose of this program is to increment record 1 of FILE by one If two users execute this program concurrently we wish the value in record one to be incremented by two thus 088 1 0008 00 REV 0 4 to be users i 1 OM OS AA two FLOCK XCALL SUBROUTINE TO COORDINATE MULTI USER FILE ACCESS ONE USER 1 REC 1 USER 2 OPEN FILE RANDOM 6 KEY 5 gt KEY 1 5 S READ 1 ONE 5 ONE ONE 1 3 6 WRITE 3 ONE 6 6 CLOSE 1 6 amp END 6 T 6 OPEN 1 1 8 RANDOM KEY e 6 KEY 1 6 READ 1 ONE 6 ONE ONE 1 WRITE 1 ONE CLOSE 1 fF END NOTE In 9 000 the value in record t TS lt no However under some circumstances it is possible for record incremented by only 1 rather than 2 after being accessed by concurrently ONE USER 1 REC 1 USER Ze OPEN 1 EE 6 KEY 5 KEY 1 5 5 READ 1 ONE 5 5 5 OPEN 1 FILE RANDOM 6 KEY 5 5 KEY Y 5 gt READ 41 ONE 5 5 ONE
26. delete them 055 10008 00 REV AGO y s INTRODUCTION Page 1 ad You will invoke a particular subroutine via the ALphaBASIC XCALL statement and will usually need specify several control parameters on that statement Line A typical XCALL statement Line might Look Like this where COMMON is the name of the subroutine YOU want to invoke and SEND MSGNAM and WRITE OUT are variables that specify information to the COMMON subroutine 100 XCALL COMMON SEND MSGNAM WRITE OUT 3 You will need to use MAP statements to define many of the control variables you specify on the XCALL statement Line This is because only by way of MAP statements can you define binary variables For information on MAP statements refer to the AlphaBASIC User s Manual DWM 00100 01 MRSS IVAW Many of the XCALL subroutines require that you pre load special files For example you must load the file DSKO COMMON SARE 6 into user or system memory before running an AlohaBASIC program that makes use of the COMMON subroutine For each XCALL subroutine the documentation that follows will let you know what files need to be pre loaded To load a file into user memory i e your own partition enter either of the following from AMOS or AMOS L command Level LOAD DSKO Filename 7 26 RET fe js GP LOAD BAS Filename SBR RET where Filename is the name of the subroutine Y
27. east and so on for the streets to the south and west We use a sequential file for this data because as new streets are Laid out and named we can later add those to our sequential file and then resort the file for future maps we have gathered the existing street names and their relative positions from city plans The file we have put the unsorted List of all the streets in is called STREET DAT The extension PAT indicates to us that this 3 the raw data file we want to record the sorted alphabetic List of all the streets in a file called 51866 15 The street names sorted according to direction we l piace in a file called ENSW LST We choose an extension of LST to remind that these are files we can orint when we want to Here is the list of street names and directions we ve gathered from city 4 5 2 2 2 885087 XCALL SUBROUTINE FOR SORTING FILES Page 2 8 Sinbad St Jonn Silver Rd Marco Polo Ave Robinson Crusoe Dr Nimrod Cr William Tell Ln Achilles Dr Pontiac Ln Fremont St Kublai Khan Cr Constantine Rd sancho Panza Cr Balboa Dr John Carter Ln Hamer Aye William Taft Aye Edward Teach St Cisco Kid Rd Michael Fink Dr Herman Melville Ln E xL to n LO m zm X om wn X amp v om The first thing we need to do is load AMSORT SYS and FLTCNV PRG for an AMOS system in user memory We do that at AMOS or AMOS L command level this WAY L
28. names the specific packet because several can be 2 2080 in memory via COMMON at one time Finally the value of the variable INF from Line 100 is placed in common memory under the name defined as PACKET Then of course the program ends in Life 130 When the program is run at this point the packet is in common memory Yo retrieve the packet under the name you input defined as the string variable PACKET which is now residing in common memory yOu may use a routine Like the following 10 MAPT RECEIVE 20 MAP2 F RCV B 1 1 50 MAP RCVFLG B 1 0 40 MAPI RETRIEVE S 150 30 MAPI PACKET S 6 T00 INPUT Enter name of data packet CePACKET 110 XCALL COMMON RECEIVE PACKET RETRIEVE 120 IF RCVFLGZO PRINT Message not found amp ELSE PRINT Message is IRETRIEVE 150 END Line 310 of the retrieving program is a level 1 MAP statement The subsequent MAP2 statements pertain to it when the variable RECEIVE is Looked at the associated information in Lines 20 and 30 are automatically accepted as well BSS TOOO8 00 REV 400 COMMON XCALL SUBROUTINE TO PROVIDE COMMON VARIABLE STORAGE Page 5 5 Line 20 defines the binary variable F RCV as one which later will tell COMMON to receive rather than send Line 30 contains RCVFLG another binary byte This one can be tested by the program following the XCALL to the COMMON subroutine If this binary variable equals zero the program can determine that for some reason COMMON did not find the de
29. or expression FORM A string variable or expression that specifies the farm on which the file is to be printed If you omit FORM or it is anull string the Line printer spooler uses the NORMAL form If you want FORM to use the default form of the line printer spooler and want to use subsequent options WIDTH or LPP enter the null 8 on im place of the FORM variable or expression WIDTH A floating point variable or expression that specifies the width Cin characters of the page SPOOL only uses this value if you have specified the HEADER switch in the SWITCHES variable WIDTH does not affect the number of characters in the print Line E only affects the text in the banner if any and the header based on the width you specify If you omit WIDTH the spooler program uses the defauit value for the specified printer If you want to omit WIDTH but di to use 3 in place of the WIDTH variable or Esq LPP A floating point variable or expression 1 cifies the number of Lines per page SPOOL only uses this value if you have specified ane HEADER switch in the SWITCHES variable If you omit LPP the spooler program uses the default value for the specified printer 2 ep 8 6 1 7 Some Examples using SPOOL ng examples are intended to be various modifications of the same Line programs Each modification will affect the orinting of The follow ta 811 fferent way One or Ww 31 pls ELES TF 8 CH ACALL SPOOL FILENAME
30. problem if Action 4 is used it dis necessary to use Action 3 Mode 0 or 4 before reading individual records which won t be used for updating This is because a user who has exclusive use of a file can re create it which requires that all other users with the file open must then reopen it Action 3 performs the necessary reopenings 4 5 5 1 Example Here are two partial programs which illustrate the use of improved file interlocks 10 I REORGANIZATION PROGRAM 15 XCALL FLOCK 0 0 RET 1001 20 XCALL FLOCK 0 0 RET 1002 25 OPEN 41001 INDEX RANDOM S12 KEY1 30 OPEN 1002 DATA RANDOM 512 KEY2 35 XCALL FLOCK 4 2 RET 1001 40 XCALL FLOCK 4 2 RET 1002 45 CALL REORGANIZE REORGANIZE INDEXED DATA FILE 50 XCALL FLOCK O RET 1002 55 XCALL FLOCK 6 0 RET 1001 60 CLOSE 7007 CLOSE 72 65 XCALL FLOCK 1 0 RET 1001 70 XCALL FLOCK 1 0 RET 1002 75 END 100 REORGANIZE 110 REMARK SUBROUTINE GOES HERE 120 RETURN 655 1 0008 00 REV 0 FLOCK XCALL SUBROUTINE TO COORDINATE MULTI USER FILE ACCESS Page 4 15 10 INGUIRY PROGRAM 15 XCALL FLOCK 0 0 RET 1001 eO XCALL FLOCK OLO RET 1002 25 OPEN 1001 INDEX RANDOM 512 KEY1 30 OPEN 81002 DATA RANDOM 512 KEY2 35 EMPLOYEE ENTRY 40 INPUT EMPLOYEE EMPLOYEES 45 IF EMPLOYEES THEN LEAVE 50 CALL LOOKUP LOCATE EMPLOYEES IN INDEX FILE amp RETURN EMPLOYEE REC IN KEY A 55 IXCALL FLOCK 0 0 RET KEY1 15 IN EFFECT 5 WHEN LOOKUP RETURNS 60 IF KEY2
31. program has no provisions for the user typing Cl or far other errors occurring which will abort execution This can be corrected by further rewriting the program as follows 5 ON ERROR GOTO ABORT 40 XCALL FLOCK 0 2 RET 1000 20 OPEN 41000 FILE RANDOM 6 KEY 30 KEY 1 40 READ 7000 ONE 50 ONE ONE 1 60 WRITE 1000 ONE 70 CLOSE 0 AQ XCALL FLOCK 1 O RET 1000 90 END 100 ABORT 110 XCALL FLOCK 2 0 RET 120 ON ERROR GOTO 4 4 1 2 The Interconsistency Problem Here is how the programs of Section 4 1 3 can be rewritten to incorporate file open interlocks The first program pSS 10008 00 REV 0 FLOCK XCALL SUBROUTINE TO COORDINATE MULTI USER FILE ACCESS Page 4 11 10 ON ERROR GOTO ABORT 20 XCALL FLOCK 0 2 RET 1000 30 OPEN 000 1765 RANDOM 6 An KEY 1 READ 81000 ONE SQ ONE ONE 1 WRITE 50 KEY 2 READ 41000 0NE 70 ONE ONE 1 WRITE 7000 0NE 20 CLOSE 1000 90 XCALL FLOCK 1 0 RET 1000 100 END 110 ABORT 120 XCALL FLOCK 2 0 RET 130 ON ERROR GOTO D The second program 10 ON ERROR GOTO ABORT 20 XCALL FLOCK 0 0 RET 1000 50 OPEN 21 000 FILE RANDOM KEY 40 KEY 4 READ 85000 6 50 KEY 2 READ 1000 TWO 60 PRINT ONE TWO ZU CLOSE 7000 89 KCALL FLOCK 1 0 RET 1000 90 END 100 ABORT 110 XCALL FLOCK 2 0 RET 120 ON ERROR GOTO Q oH The above programs will now function correctly in a concurrent environment While the first prog
32. the number of the job that set the lock A job number is assigned to each job in the order that the jobs were defined in the JOBS command in the system initialization command file For example the first job defined in the JOBS command Line is Job 1 The SYSTAT command Lists the jobs in this order the Lock does not already exist XLOCK creates it and returns with a zero in MODE You ve now set the Lock 5 4 2 MODE f Lock and Wait His XLOCK mode is identical to MODE 0 except that if the lock already sista XLOCK tells the system to put your job to sleep until the lock is Leared That means that your job will be in an inactive state except for waking at every clock tick to test the status of the lock until the ob t originally set the lock clears it If you use this mode take inte consideration the fact that another user may be waiting for the same iock it s possible that the Lock might be cleared and then grabbed up either by the same or another job before your job wakes up A 2 5 35 MODE 2 Clear Lock ALOCK clears the Lock specified by LOCKT and LOCKE and pe to your program A zero returned in MODE indicates that the Lock you tried to clear wasn t set by your job a one returned indicates that vou sucessfully cleared one lock a number greater than one indicates that vou cleared more ti Lock which means that LOCKT or LOCK2 were originally set to zeroe the wildcard value You may never use XLOCK to clear a lock that wa
33. 0 and 220 close our input and two output files The program prints us a reminder of the file names then ends 5 3 7 of all the streets contained in the file WOULG appear Like STREET LST the sorted version STREET LST this Achiiies Or Balboa Dr Cisco Kid Rd Constantine Rd Edward Teach St Fremont St Herman Melville in Homer Ave John Carter Ln John Silver Rd Kublai Khan Cr Marco Polo Ave Michael Fink Dr Nimrod Cr Pontiac Ln Robinson Crusoe Dr sancho Panza Cr Sinbad St William Taft Ave William Tell in Y 5 The file ENSW LST which is the streets first sorted according to their Location relative to town center then sorted alphabetically would appear Like this BASORT XCALL SUBROUTINE FOR SORTING FILES Page 2 11 Edward Teach St Fremont St Homer Aye Marco Polo Ave Sancho Panza Cr Balboa Dr John Carter Ln Michael Fink br Pontiac Ln Sinbad St Cisco Kid Rd Kublai Khan Cr Nimrod Cr Robinson Crusoe Dr William Taft Ave Achilles Dr Constantine Rd Friday Or Herman Melville Ln John Silver Rd William Tell Ln amp Roin ZZzzzmmmmm Remember if you choese not to assign a third key or perhaps even a second key you still must place zeros in the size position and order variables of the kevs you omit 2 3 BASORT ERROR MESSAGES TAMSORT SYS not found in memory ty rout ine AMSORT SYS must be load
34. 00100 01 The MAP statements vou see below will be sufficient for all but the most exotic programs using COMMON iG E d o send a packet of data to common Memory you must define a variable we ll CALL Tt SEND which must appear in the XCALL COMMON program iine when you are sending as W n SEND 8 1 0 seul Sp is DP sends derbyte binary variable always contains zero the Flag telling COMMON SE D E Yo receive a packet of data from common Hemory you must define a two byte binary variabile call it RECEIVE which must appear in the XCALL COMMON program Line when YOU are receiving to communicate two pieces of information to COMMON The first byte must be a 1 which is the flag to D33 10008 00 REV ADO COMMON XCALL SUBROUTINE TO PROVIDE COMMON VARIABLE STORAGE Page 3 3 COMMON that you are going to receive a packet from memory well name that The second byte which we ll call ROVFLG is a flag vou can Dyte F RCVO test after the XCALL COMMON subroutine is executed to see of you did in fact receive the packet That two byte binary variable is defined like this MAPT RECEIVE MAP F RCV B 1 1 MAP2 RCVFLG B 1 0 Again F RCV always contains a one the flag telling COMMON to receive RCVFLG functions as a flag ta indicate whether or not COMMON finds the requested packet of information If COMMON does not find that packet if zero im this byte otherwise it is non zero will retu
35. 3 4 5 2 Po d weed ATE ENG b d an E 7 9 4 13 q i 1 j E E VET VE Za P PO i oed 6 2 a 5 R ALPHABASIC XCALL SUBROUTINE USER S MANUAL HEADER switch a a a input channel a a interconsistency problem KO M uu ao we wih c 8 OS UR POG a x o ow Siow ce Position nr MEI a ES TYDE e ee 2 ESOC ow vw ARA COLUI de a Rhode List lock mode a LOAD command a e Lock and wait mode Logical record gt ew e EPP 001106 a Wo amp a Machine Language MAP Statement s a s a a Memory based heap sort a MODE lC Monitor queue s e a s Mounting a disk Multi user file access Multiple update problem NOBANNER switch s s e e NODELETE switch a 2 a NOFF SWIECI e lx NOHEADER switch a Mon exclusive use a u Output channel Ka 0 KE Preventina deadlock PRINTER option Program chaining d KE a R 5 fe 2 Queue block a s u a Random file Record count o e a 866000512 a k oco Record update interlock Reserved file channel number Retunrn code a a M ALPHABASIC XCALL SUBROUTINE USER S MANUAL Page Index 3 i
36. 6 program that performed the XCALL SPOOL subroutine waits too and nothing else can be done until that request is inserted inte the queue Each switch you can use has a numeric code associated with it see below for example the BANNER switch code is 1 the DELETE switch code is 4 Set control switches by putting the sum of the appropriate switch codes into the SWITCHES variable For example if you want to use the BANNER and DELETE switches to tell the Line printer spooler program to print a banner page and delete the file after printing it load SWITCHES with 5 BANNER code DELETE codel If you omit SWITCHES SPOOL uses the default switches for the selected printer tf vou do not wish to use SWITCHES but want to use one or more of the subsequent options COPIES FORM etc replace the SWITCHES variable or expression with the null designation UU Switch codes BANNER 1 NOGANNER d DELETE fy NODELETE 8 HEADER 16 NOHEADER 32 EP 64 NOFF 128 WAIT 256 DSS 10008 00 REV ADO SPOOL XCALL SUBROUTINE FOR SPOOLING FILES TO THE LINE PRINTER Page 6 4 COPIES A floating paint variable or expression that specifi the number of copies to be printed If vou omit COPI or it is zero the Line printer spooler program prints one copy If you want COPIES to print the default number of copies of the Line printer spooler and want to use subsequent options FORM WIDTH etc d enter the null designation UUM dn place of the COPIES variable
37. CALL Subroutine User s Manual AE DEN TECHNICAL PUBLICATIONS FILE REFERENCE et A IA REA YR PINTADA PA AR BE A A AI II BINAR BN EOL NH II TECHNICAL PUBLICATIONS READERS COMMENTS We appreciate your halp in evaluating our documentation efforts Please feel free to attach additional comments if you reciuire amp written response check here NOTE This form is for comments on documentation oniy To submit reports on software problems use Software Performance Meparts SPRS available fram Aloha Micra rH 2 Le en Z a 7 i x E Piease comment on the usefulness organization and siarity of this manual A IN CN eme A s o o E 1 1 111000001111011 4 y s em nn y ed By MEA ep t RYAN NN AW MEAN PPP AN VAL d d AA SARI T enn m E M esc v M M II WAI VIVIA WI VASA AS AS AA SEATS e emm Anm nmm rmm rmn quee VAE VIV NY Y IVAR IV AA Auf EA EU E m M MS MM TE 3 a
38. CHAPTER 5 KLOCK XCALL SUBROUTINE FOR MULTI USER LO 2 P gt Gei EI ra gt 1 LOADING XLOCK INTO SYSTEM MEMORY THE XLOCK SUBROUTINE SUR eee E ad 2 5 THE LOCKS id AAA RA AA 4 THE MODES ARCA SIRS SSeS 2 4 1 MODE 0 Lock and Return 2 4 2 MODE 1 Lock and Wait 2 4 5 MODE 2 Clear Lock ROLE 3 4 6 MODE 3 List Locks ERS 8 100 81 0 E eae PROGRAMMING EXAMPLES 2 6 1 Calculating Record Numbers 6 2 Sample Program to Illustrate File Record Locking 00 0 5 7 SUMMARY KC Cu dO 1 AAA 880090 2 KJ EU 0 CO iun 274 Ss A D rm TER 6 SPOOL XCALL SUBROUTINE FOR SPOOLING TO THE LINE PRINTER s p PT 6 1 USING THE XCALL SPOOL SUBROUTINE eee 6 1 1 Some using SPOOL XCALL SPOOL FILENAME parano XCALL SPOOL FILENAME PRINTER era 6 1 1 3 XCALL SPOOL FILENAME PRINTER SWITCHES Gale XCALL SPOOL FILENAME PRINTER SWITCHES COPIES have 6 17143 XCALL SPOOL FILENAME PRINTER SWITCHES COPIES BUDE EE 0 1 1 6 XCALL SPOOL FILENAME 5 PRINTER SWITCHES COPIES FORM WIDTH Gu Ty 1 LS O Be T SF RS e e oe e HY e 4 005 6 1 1 7 XCALL SPOOL FILED NAME PRINTER SWITCHES COPIES FORM WID
39. E 6 Exclusive RETURN CODE 1 if not free EE ACTION TELLS FLOCK THAT FILE TS CLOSED RELEASES THE LOCK ACTIONS 5 AND 6 PERFORMED AS NECES 2ARY P 42 ACTION YELLS FLOCK THAT A PROGRAM ABORT IS ABOUT TO OCCUR RELEASES ALL LOCKS ON ALL FILES BY PERFORMING ACTION 1 AS NECESSARY i RD ACTION REQUEST TO READ RECORD MODE 0 Nonvexclusives delay if not free Action O must already have been granted MODE 2 Exclusive delay if not free Action 0 must already have been granted MODE Non exclusiver RETURN CODE 1 if not free Action 0 must already have been granted MODE 6 Exclusive RETURM CODE 1 if not free Action 8 must already have been granted ACTION 4 REQUEST TO READ WRITE ALL RECORDS MODE 2 Exclusive delay if not free Action must already have been granted MODE 6 Exclusives RETURN CODE 1 if not free Action D must already have been granted ACTION 5 TELLS FLOCK THAT YOU HAVE FINISHED PROCESSING THE RECORD REQUESTED BY A PREVIOUS ACTION 3 CALL ANY BUFFERED DATA IS OUTPUT TO DISK ACTION 6 ELLS FLOCK THAT YOU HAVE FINISHED PROCESSING THE FILE REQUESTED af A PREVIOUS ACTION 4 CALL ANY BUFFERED DATA IS OUTPUT TO DISK 055 10008 00 REV AOQ BE vt t CHAPTER 5 XLOCK XCALL SUBROUTINE FOR MULTIUSER LOCKS XLOCK is an external subroutine that your AlphaBASIC program can call to set and test locks A lock is a
40. E ACCESS Page 4 4 Informs FLOCK that abnormal program termination is about to occur G during ah error handliria routine Releases all locks on att files by performing Action as necessary 7 ieot 35i Requests permission to read Record of Filet for non exclusive use i e record will not be used to update file Permission to open File must already be ranted The request is piaced in 8 d z first come first Served queue and the program is delayed until the request can be granted Requests permission to read Record of Fle for exclusive use i e record will be used to update file Permission ta open File must already be granted The request is placed in a first come first served queue and the program is delayed until the request can be granted Requests permission to read Record of Filet far non exclusive use isea record will not be used to update file Permission to open File must already be granted If the request cannot be immediately granted Return Code f is returned Requests permission te read Record of File for exclusive use i e record will be used to update file Permission to open File must already be granted 1 the request cannot be me ately granted Return Code f is returned Requests permission to read write all records of File for exclusive use i e processing will update and possibly re create file Permission to open File
41. END 70 ABORT 71 XCALL FLOCK 2 0 KEY f ON ERROR GOTO D 4 10 ON ERROR GOTO ABORT 20 XCALL FLOCK O O RET 1000 21 OPEN 81000 FILE RANDOM O 50 XCALL FLOCK 3 0 RET 10005 31 XCALL FLOCK 23 0 RET 1000 2 KE KEY 1 READ 1000 ONE 35 KEY 2 READ 1000 TWO 34 XCALL FLOCK 5 0 RET 1000 2 35 XCALL FLOCK 5 0 RET 1000 1 4t PRINT ONE TWO 50 CLOSE 7000 51 XCALL FLOCK 1 0 RET 1000 60 END F0 ABORT 71 XCALL FLOCK 2 0 KEY ON ERROR GOTO 6 4 4 35 Improved File Inter locks in Section 4 2 2 we said that file open interlocks can incur Long delays upon any users trying to access a file after one user has opened it and therefore Locked them out Nevertheless it is sometimes necessary to lock an entire file for exclusive use For example if file XYZ is becoming full you might wish to copy the file XYZ into a new Larger file TEMP and then delete XYZ and rename TEMP to XYZ Or as another example you might wish to reorganize an index and data file Obviously during these mManeuverS YOU want assurance that no other user can access the file 255 10008 00 REV ADO FLOCK XCALL SUBROUTINE TO COORDINATE MULTI USER FILE ACCESS Page 4 14 Action 4 obtains exclusive access to a file by obtaining exclusive access to all the records of that file Exclusive access is relinquished by using Action 6 Action 3 Mode 0 or 4 is necessary before reading a sequence of records in order to avoid the interconsistency
42. IT uu 9 E AAA feisty ie INANIS PERE uz AE E ANI PENIS af 2 PAN Ex NAGS RS ET AVE AINT BEM A as GNSS E SE RB EE Ee ER SERS TANTAS H ij EE ANT Ita ENVIAR RENE RRS SIDE AAS MUN O y Ee TAR dx v A AAI SEES KEE ZS EE GE 2 FIRST EDITION June AAA REVISIC RR SE E ETS ONS INCORPORATED Saha RN Uo ES Ma DE REVIS SION DATE AGO June 1982 1982 ALPHA MICROSYSTEMS TRE INFORMATION CONTAINED IN THIS MANUAL IS BELIEVED TO BE ACCURATE AND RELIABLE HOWEVER NO RESPONSIBILITY FOR THE ACCURACY COMPLETENESS OR USE OF THIS INFORMATION IS ASSUMED BY Al PHA MICRO This document reflects AMOS versions 4 6 and later and AMOS L versions 1 0 and later THE FOLLOWING ARE TRADEMARKS OF ALPHA MICROSYSTEMS IRVINE Ca 92714 Aipha Micro AMOS AiphaBASIC AphaPASCAL 7 AlphaVUE AlphaSERV Alpha ACCOUNTING ALPHA MICROSYSTEMS 17881 Sky Park North vine CA 92714 ALPHABASIC XCALL SUBROUTINE USER S MANUAL Page 111 Table of Contents CHAPTER 1 INTRODUCTION 1 T MANUAL ORGANIZATION
43. NEL RECORD TOTAL RECORD SIZE 52 1 ASCENDING S 36 amp ASCENDING 7 44 ASCENDING STRING STRING STRING PRINT We will sort on name purchase date and purchase order number FOR RECORD NUMBER D TO 11 READ 100 CUSTOMER INFO PRINT NAME PRINT PURCHASE DATE PRINT PURCHASE ORDER NEXT CLOSE 100 mato na WI ZS 3 Ee we 5 ost pU Le wy ee um d Kl Ld d oy ey zn 8 URS Y uc gt Tag A 5 i4 eg De ISS m ld e D 3 Note that Line 120 opens the file POINFO DAT Line 140 is the XCALL BASORT line where the variables defined in the MAP statements of Lines 15 rough 532 define the BASORT parameters The file is sorted back on itself at that point Then it is printed as a result of Lines 160 through 210 The resuiting printout when running the above program iss Now sorting We will sort on name purchase dete and purchase order number DE SOTO HORSE GROOMING EQUIPMENT CO 4 7 81 1836 DE SOTO HORSE GROOMING EQUIPMENT CO 4 9 81 1895 EVANS CLASSIC t INC 1 20 81 K798 FG EVANS CLASSIC AUTOMOBILES INC 9 11 81 L98467 HONEST DAVE S CHEAP CAR PARTS 9 11 81 AQ0 526 K A L ENTERPRISES 12 7 81 1207 MARTIN MICHAEL LAVELLE CONSULTANT 6 12 81 78729 ROBIN GOOD PUBLICATIONS 1 3 81 49130 ROBIN 6008 PUBLICATIONS 2 14 81 49201 KOBIN GOOD PUBLICATION
44. OAD DSKO AMSORT SYSLT 4 GED or LOAD DSKO AMSORT SYSE1 4 GED LOAD DSKO FLTONV PRGC1 4 Now we create the AlphaBASIC program The first thing we have to remember to do is open the file channel for the file that we want to sort and two more file channels and files where we want to put the sorted data into We could name the same file in both Lines 110 and 120 or 110 and 130 below to write one of the sorted files right over the original unsorted data Our program might look Like this 508 XCALL SUBROUTINE FOR SORTING FILES Page 2 9 10 i SAMPLE PROGRAM TO SORT SMALL SEQUENTIAL DATA FILE 100 START 110 OPEN 81 STREET DAT INPUT 115 OPEN 2 STREET LST OUTPUT 120 OPEN amp 3 ENSW LST OUTPUT 125 PRINT Now sorting all streets alphabetically 130 XCALL BASORT 1 2 50 25 1 0 1 35 0 0 0 0 155 CLOSE 1 140 PRINT Now sorting according to direction from town center 145 OPEN 1 STREET D I INPUT 150 XCALL BASORT 1 5 50 1 33 0 25 1 0 0 0 0 155 PRINT ALL done See STREET LST and ENSW LST for sorted files 00 CLOSE 1 210 CLOSE 2 220 CLOSE 3 amp 50 END Line 110 opens file channel 1 and the file called STREET DAT for input Line 115 opens file channel 2 and the file called STREET LST for output Line 120 opens file channel 43 for output also Line 130 performs the first XCALL BASORT subroutine Immediately following the word BASORT and the delimiting comma we indicate the file cha
45. OCK will not occur if program 2 requests permission to open files 1001 and 1002 for exclusive use in the same order as program 1 For DEADLOCK to occur program f must be granted permission to open file 1001 for exclusive use but be delayed permission to open file 1002 for exclusive USE However if program 1 is granted permission to open file 1001 for exclusive use the corrected program 2 a duplicate of program 1 will not be allowed to execute lines 21 990 thus it will be unable to obtain permission to open file 1002 for exclusive use DEADLOCK cannot occur DSS5 10008 00 REV ADD FLOCK XCALL SUBROUTINE TO COORDINATE MULTI USER FILE ACCESS Page 4 17 amp 6 SUMMARY The FLOCK SBR program is an external XCALL subroutine which is callable from BASIC FLOCK Locks files and can lock records within files to prevent concurrent access by other users running programs that access the same files FLOCK may also be used to coordinate shared file access and pracessing aded into system memory via the ial ization command file SYSTEM command in the system init ystem FLOCK also requires that DSK SYSTEM 18181 If you have an AMOS you have FLTCNV PRG in system memory FLOCK only functions properly if it is io x 5 4 0 1 Quick Reference Summary of Actions Modes ACTION 0 REQUEST TO OPEN FILE MODE G Nan exclusives delay until free MODE Exclusives delay until free MODE 4 Non exclusives RETURN CODE 1 if not free MOD
46. Ou are requesting f Fa 5 E da a A 9 16 COMMON BASORT etc Note the use of the ersatz name BASI which indicates account 61 of the System Disk After you see the monitor prompt yOu may run an AlphaBASIC program that uses the 5 0 Subcoroutne To ioad an XCALL subroutine into system memory the Syste e ust use the SYSTEM command within the system initialization command file For mare information on Loading files including subroutines into system memory during system boot up see the AMOS System era Eie Guide DSS 10001 00 or the AMOS L System Operator s Guide B55 T0002 00 oa teen el AA Teno 3 Some XCALL subroutines namely FLOCK XLOCK and SPOOL use Ene monitor queue The monitor queue is a list of blocks n system memory which are linked ta each other in a etwa chain Each queue Black is currently eight words 16 bytes in size this vatue may change with the next release of the m ystem Pur ing f F D zt Es X 5 un 9 HE D i normal monitor operations various functions use these queue blacks INTRODUCTION Page 1 5 to perform certain tasks The monitor initially contains 20 blacks in the available queue List This quantity is established in the system initialization command file For information on increasing the number of available monitor queue blocks see the AMOS System Operator s Guide DSS 10001 00 or the AMOS L System Operator s Guide
47. RDA E Ee Now we ll add the SWITCHES option to our examples If you have an AMOS system then before you can run an AlphaBASIC program using the XCALL SPOOL subroutine and the SWITCHES option you must load FLTCNV PRG into system or user memory The nine available switches each have a unique numeric code assigned to them Add the numeric value of the various codes that you want to use For example say we wish to have a BANNER and a HEADER and throw a farmfeed when our file is done printing Those codes 1 16 and 64 add up to 81 Our sample program s XCALL SPOOL command Line should read 10 XCALL SPOOL TEXT LST TIS10 81 88 1 0008 00 REV AGO SPOOL XCALL SUBROUTINE FOR SPOOLING FILES TO THE LINE PRINTER Page 6 6 6 1 1 4 XCALL SPOOL FILENAME PRINTER SWITCHES COPIES Say we want to spool two copies te the printer queue We would add the dul ES floating point variable or expression to the XCALL SPOOL Line in a ay something Like this 10 XCALL SPOOL TEXT LST nn o or Like this 10 COPIESz2 eu XCALL SPOOLS TEAT LST DT COPIES NOTE In the above examples the PRINTER string variable or expression and the SWITCHES floating point variable or expression have been replaced by place holding Hulls C You must always remember to add a place holding null in the XCALL SPOOL program Line if you are not going to use the option that goes in that place but are going to use one or more subsequent options
48. S 2 08 81 49393 ROBIN GOOD PUBLICATIONS 2 28 81 49397 8 8 5 81 14101 8 508 XCALL SUBROUTINE FOR SORTING FILES Page 2 6 4 2 2 Sorting Sequential Files When you sort a sequential file YOu must specify both an input and an Output file If you wish to sort a file back onto itself you may specify the same file for both input and output IMPORTANT NOTE Before BASORT is c alled the file must be opened for input BASORT leaves th file open for output Cali BASORT for sequential files via XCALLE BASORT INPUT CHANNEL OUTPU CHANNEL RECORD SIZE KEYT SIZE R N KEYT ORDER KEY2 SIZE KEY2 POSITION KEY2 ORDER KEYS SIZE KEYS POSITION KEYS ORDER Wheres INPUT CHANNEL The file channel on which the input file is open OUTPUT CHANNEL The file channel on which the output file is open RECORD SIZE The size in bytes of the Largest record in the file including the terminating carriage return iinefeed characters NOTE Too small a value results in truncation of data records KEYT SIZE The size in bytes of sort key 1 Give the size of the Largest instance of key 1 fise if sort key 1 is the customer s name find the Longest name in any record or perhaps allow for a very long one KEY1 POSITION The first cha aracter position occupied by key El If the KEYT POSITION variable given is Us for example BASORT will fit the characters beginning at the fiftieth byte in the record into the sequen
49. System Operator s Guide pSS 10002 00 ch PALA Le AAN 61 500 AAN ee eh CEA SLES hiss E VITIA YA YY P EAE AINAR I DSS 10008 00 REY 400 FLOCK XCALL SUBROUTINE TO COORDINATE MULTI USER FILE ACCESS Page 4 9 NOTE You may use the QUEUE command at monitor Level to determine your system s use of queue blocks The system will respond with the current number of free queue blocks in the available queue List For example QUEUE RED 20 Queue blocks available TANIA HANI SP DANONE TTL TT bes USING FLOCK There are three levels of increasing complexity with which FLOCK subroutine calls may be incorporated inte a program system 1 Use Actions 0 through 2 to implement file open interlocks see Section 4 2 12 2 Use Actions O through 2 to implement file open interlocks and use Actions 3 and 5 to implement individual record update interlocks see Section alalla 3 Use Actions O through 2 4 and 6 to implement complete file interlocks and use Actions 3 and 5 to implement individual record processing interlocks see Section 4 2 3 The problems outlined in Sections 4 1 2 and 4 1 3 can be solved by using FLOCK to any of the above levels of complexity In your design you are free to trade off complexity for performance so long as you use 8 single Level af complexity consistently for any given data file bate File Open Interlocks Using ju
50. T SIZE KEYT POSITION KEYI ORDER 8 KEY2 SIZE KEYZ POSITION KEY2 ORDER amp KEYS SIZE KEYS POSITION KEYS ORDER 8 KEYT TYPE KEY2 TYPE KEY3 TYPE E ba tj m ri x2 CHANNEL NUMBER File channel on which file to be sorted is open for random Processing RECORD COUNT Number of records in the random file you are sorting Unlike sequential files the programmer must know the precise number of records in a random file RECORD SIZE size of the longest record in the file yOu are sorting The size of a record is its byte count including characters spaces etc Again for a random file you must be sure of the record ize KEYT SIZE The size in bytes of sort key 1 Give the size of the largest instance of key El i e if sort key 1 is the customer s name find the Longest name in any record ar perhaps allow for a very long one KEYT POSITION The first character position occupied by key 1 Tf the KEYT POSITION variable given is 50 for example BASORT will fit the characters beginning at the fiftieth byte in the record into the sequence it is creating KEYT ORDER sort order of key 1 Enter the digit 0 to indicate that you want key 1 of each record to be sorted in ascending sequence or enter the digit 1 to indicate descending seqeuence NOTE The order is determined using ASCII collating sequence e 8 all upper case Letters come before lower case letters C ei KEYZ SIZE The size in byte
51. TH kd ud E 6 0 SPOOL ERROR MESSAGE VEO DER GL Es H gt n Zo si ae Se EK RSM Re e Boo e mm Re a e wg 5 5 SUMMARY Joe nu xS d 5 TOS eR SP RH MO E E E SS eH s soo o ALPHABASIC XCALL SUBROUTINE USER S MANUAL Page v CHAPTER 7 XMOUNT XCALL SUBROUTINE TO MOUNT A DISK fal THE XMOUNT SUBROUTINE WOW age ane RRR ee RED 7 1 1 Some Examples Using XMOUNT 7 2 rae SUMMAR Y NON di I AAA A DOCUMENT HISTORY INDEX DSS 10008 00 REV A00 T s e M T CHAPTER 1 INTRODUCTION AlphaBASIC the Aloha Micro BASIC Language Processor is a powerfully enhanced version of BASIC AlohaBASIC has the ability to access external machine language subroutines using a keyword called XCALL Several machine Language subroutines ones that perform complex and yet frequently required tasks are provided on your System Disk These external subroutines their features abilities and restrictions are the subject of this manual Because these external subroutines are machine Language programs they are much smaller and faster than equivalent AlphaBASIC programs Machine Language programs work closely with hardware and the operating system which ALphaBASIC cannot do in some applications it is important to note here that whereas you can write your own machine Language subroutines and access t
52. US GAS is the ersatz name for ppn 7 67 of the system disk After you see AMOS or AMOS L prompt you may run an ALphaBASIC program that uses the Pd COMMON subrouti re TO Load COMMON SBR into system memory you must have a Line in your system initials zation file that performs that function For more information on 801 subroutines into system memory during system boot up see the AMOS stem Operator s Guide D35 10001 00 or the AMOS L System Operator s Lo IWIN WEI MASINI 62 eere BLADE 7 7 T D ET somme E 97 8 A frag z a 8 1 Dune DES T0000 cl 3 4 USING COMMON FROM WITHIN AN ALPHABASIC PROGRAM There are two things that the AlphaBASIC program itself must ac compl ish order to use the COMMON subroutine The program must define certain variables that COMMON will 01 and it must contain an XCALL command 4 using the name COMMON and certain parameter specifications 3 2 1 Defining Variables 56 COMMON from within an 8 8 516 program you must first define certain binary variables that tell COMMON to send a packet to memor Y or ta e one from memory and if set to receive to set a flag if the packet 18 1n fact received wc Y m te EI ai CH Wong You define these binary variables by using MAP statements MAP statements gt discussed at Length in Chapter 8 Memory Mapping System af the LphaBASIC User s Manual DWM
53. ater and at various times be retrieved by other AiphaBASIC programs The AlphaBASIC program assigns a name to a packet of data by using the BASIC keyword XCALL and then the name of the external subroutine COMMON On the same Line the AlphaBASIC program must indicate whether 1t is sending a variable to or retrieving a variable from user or system memory Following that on the same Line the program must give either string variable or a string Literal the name must be six characters or fewer to be the name of the data packet Finally still on the same iine the name af the numeric or string variable containing the data of the packet which can be up to 150 bytes in Length is specified 5 1 LOADING COMMON INTO USER OR SYSTEM MEMORY Yo insure proper results you must load the COMMON subroutine into memory before you use it from within an AlphaBASIC program You may load COMMON into either system or user memory If you load COMMON into a user s memory partition only that user can access the data stored by COMMON Tf you load COMMON into system memory making the data accessibie to all users be sure that you assign a unique name for each packet of gata D 5 10008 00 REV COMMON SUBROUTINE TO PROVIDE COMMON VARIABLE STORAGE Page 32 To Load COMMON S ch USEF memory enter either of the following from AMOS or AMOS 4 command Level LOAD 5 0 COMMON SBRL7 6 GED KL veer LOAD BAS COMMON SBR REN e
54. ation on creating and using files from within AlphaBASIC refer to Chapter 15 of the AlphaBASIC User s Manual DWM 00100 07 SS ME KM E ee ODIO e You can use BASORT to sort a file into numeric order a list of names or words into alphabetic order and so on 8 85087 permits up to three Keys or elements of the data records you wish to base your sort on For example Say you have a list of customer names each with an associated order date code and a purchase order number The first key might be the customer name If a particular customer has ordered more than once the second key comes into play to determine which record of that customer s should go first You can sort that customer s orders chronologically based on the date code And if that customer has placed two or more orders in the same day the third key will determine the final sorting placement of that customer s records based on his purchase order numbers An example of this kind of sort is in section 2 2 1 1 below BASORT combines two sorting methods to make it a relatively fast sort utility that can still handle very Large files If your memory partition is Large enough to contain the entire file that is to be sorted BASORT performs a memory based heap sort That means it sifts through and rearranges the heap of data in memory to bring the data into the order you specify in the BASORT command Line If there is not enough room in user memory for the entire file BASORT does a dis
55. be omitted if Record is also omitted The file specified may be either RANDOM or SEQUENTIAL for Actions 0 and 1 but must be a RANDOM Tile for al other actions IMPORTANT NOTE In order for FLOCK to function properly 16 14 numbers should denote specific and unique files This means you must systematically assign file channel numbers to your files when designing applications programs being careful to assign the same numbers to the same files and different numbers to different files File channel numbers 1 through 999 have been reserved for use by Alpha Micra software Although there is nothing to prevent your programs from using these numbers we advise you not to do so in conjunction with FLOCK so that na conflict can arise between your application programs and any present or future Aloha Micro software on your system a ELA Record TNT Record specifies a Lagical record number For Actions 0 through 2 4 and amp record is ignored and may be omitted Ao A d bh Return Code tA Tr m ANN mid HAGA AAA E Return Code denotes a variable in which FLOCK places a number that indicates the success or failure of an action Code 0 Successful ALL actions Code 1 Resource unavailable Actions 0 3 4 Code 2 Open request has already been granted Action 0 Code 3 Permission to open must first be granted Actions 1 4 4 Code 4 Duplicate request for use of some record in file Actions 3 Code 6 Permission to use so
56. ce it is creating KEYT ORDER rt of key H1 Enter the digit 0 to dicate that you want key 1 of each record to Se in ascending sequence or enter the igit f to indicate descending segeuence NOTE The order is determined using ASCII callating sequence fe all upper case letters come before lower case Letters SR in e EE 4 cq KEYZ SIZE The size in bytes of sort key 2 KEY POSITION The first character position occupied by key 2 KEYZ ORDER sort order of key 2 Enter a or a 6 See KEYT ORDER above 885087 XCALL SUBROUTINE FOR SORTING FILES Page 2 7 KEYS SIZE The size in bytes of sort key 3 KEYS POSITION The first character position occupied by key f 5 KEYS ORDER sort order af key 3 Enter a or a 1 See KEYT ORDER above NOTE Sequential files contain only ASCII data For that reason when you sort sequential files you do not have to specify the data type of the sort keys 885087 knows that all keys in a sequential file are strings 2 2221 An Example of Using BASORT on a Sequential File The following is the contents of an unsorted sequential file that we want to sort Pretend this time that we are cartographers making a map of a new suburb just being built We want to compile an alphabetic index of all the street names laid out and defined so far but then we want to compile an alphabetic List of the streets to the north of tawn center oniy then one of the streets to the
57. e XMOUNT subroutine provides vou with the ability to mount a disk without Leaving an AiphaBASIC program It is used when a new disk has been inserted in a disk drive and must be mounted in order for the bitmap to be updated XMOUNT may also be used to unmount a disk from within an AlphaBASIC program XMOUNT also provides the volume I0 of the disk as an option if the program user needs to identify the disk just mounted ALPHABASIC XCALL SUBROUTINE USER S MANUAL Page History 1 DOCUMENT HISTORY AMOS Release 4 6 and 4 Release 1 0 Printed 6 82 FIAR ITIER TIS WAPO 2222 RACE The ratio Tacluded In this manual was Gip contained as separate documents in the BASIC Programmer Information section of the AMOS Software ee Documentation Packet The contents of this are updated to ef lect advancements in software and th inclusion of AMOS L system information Also the ton in this manual has been expanded and clarified in response to user requests Dd Revision AQU A MUT ai Page Index 1 i Lin i E 1 m e eh d TAS Ai i db ME rrt mm zech 3 to 6 5 d i a A d AJ 1 TT T EU xh Qe Pri LA oem d SE 1 D pi De o m K gt T m E d ES i 3 d BK Uu cl p dq AAA iD
58. e to the right of the SWITCHES option are available even if the SWITCHES option is not desired by placing a nuli argument 0 in the SWITCHES position However even if SWITCHES is null FLTCNV PRG must be loaded in system or user memory if its position on the program Line is used 0 35 1 0008 00 REY ADO CHAPTER 7 AMOUNT XCALL SUBROUTINE TO MOUNT A DISK XMOUNT is an XCALL subroutine that allows you To mount 4 disk from within an AlphaBASIC program without leaving AlphaBASIL You should call it whenever you change a disk and your AlphaBASIC program is going to sort files or create new files on the newly changed disk You must always mount a disk after you ve changed it and before you write to itz otherwise the system will think that the old disk is still in the drive When it comes time to write information out to the new disk the disk s bitmap will be wrong and the system will try to write to the new disk as if it had the same 5 free as the old one Besides bringing into memory the proper bitmap XMOUNT also loads in the alternate track table if any for the specified device IMPORTANT NOTE NEVER mount or unmount a disk while someone is accessing that disk Doing so may corrupt the data on the disk It is not necessary to load the XMOUNT subroutine into system ar user memory However the XMQUNT subroutine is fully re entrant so far increased access speed you may load it into system memory via the SYSTEM command in your system ini
59. ed into user or system memory before calling BASORT SBR Bad channel number in XCALL BASORT Re channel number you passed to BASORT was invalid This error can occur if the file is not open or if the value given as channel is not an integer File improperly open in XCALL BASORT When you call GASORT the file vou wish to sort must be open for INPUT or RANDOM processing PPLTCNV PRG nat found in memory For an AMOS system the floating point conversion module FLTCNV PRG must be loaded into user or system memory before calling 0885087 SBR Illegal value in XCALL BASORT One of the arguments to the BASORT call was invalid Check the key sizes and positions to make sure they fit into the record size which you specified Also make sure that you have given valid key types Read file error in XCALL BASORT 2 17 ooo An error occurred during a read operation while sorting your file 845087 XCALL SUBROUTINE FoR SORTING FILES Page 2 12 Write file error in XCALL BASORT mi ND a 7 zz PORES Senet 5 5 o a3 n error occurnec during 8 write operation while sorting your file Wrong record size im XCALL ne record size you specified when calling BASORT does not match the record size you specified when you OPENed the file e SUMMARY 585087 can sort both random and sequential files whether or not th
60. en at one time and the number of records open Tor each fiie Currently at any given moment during the use of FLOCK the number of queue blocks being used equals twice the number of different files open using FLOCK plus the number of different records open using FLOCK plus the number of jobs with files open using FLOCK plus the total number of FLOCK opens i e number of Action Os that haven t been closed plus the total number of record uses 3 e number of Action 3 That haven t been released eue if The last two factors of this equation anticipate circumstances where the same file and or the same record is being accessed by more than one job at a time If two jobs are reading the same ile that is two opens or two Action Os 5 voti r If FLOCK changes in the future the above formula may also require modification NOTES g The monitor is initially generated with 20 free blocks in the available queue You may modify the system initialization command file to allocate more queue Blacks by adding the GUEUE nnn command anywhere in the system initialization command file prior to the final SYSTEM command When the QUEUE nnn command 1s executed nnn more quewe blocks will be allocated for general use For more information on modi fying the system initi 4 ton command file see the AMOS 5 Lem Operator s Guide PS S71 0007 60 OF the RA DIARIA AMOS L
61. ge 3 4 AN EXAMPLE OF COMMON Let s create a pair of elementary 6 programs and put a packet into user memory then retrieve it We assume that after you write and compile these programs vou will Load the COMMON subroutine into user memory before running them as we discussed in Section 5 1 above fo send a data packet to common memoPvY you may use a routine Like this 10 MAP SEND 8 1 0 20 MAP1 INFO S 150 30 MAP PACKET S 6 100 INPUT Enter message maximum of 150 characters 110 INPUT Now enter name of data packet up to 6 characters PACKET 120 XCALL COMMON SEND PACKET INFO 130 END Line 70 defines the binary variable SEND as a zero Line 20 defines the Variable INFO as a string variable up to 150 characters in Length the maximum COMMON can handle Line 30 defines a string variable called PACKET which can be up to six characters in Length Line 100 accepts a value and assigns it to the variable INFO which will make up the data in the packet you ll store in common memory Line 110 accepts an input string that becomes the name of the packet Line 120 begins with the SASIC keyword XCALL which means the program is going to access one of the external subroutines on the system COMMON is the name of the specific subroutine to be accessed SEND is the variable name for the binary byte that because it tells COMMON to write into common memory PACKET is the string Fiable just entered that
62. gram as cess 8 new disk during the Course of a multi disk file update event You mount a disk after you have changed a hard disk cartridge or a floppy dis kette in order to inform the system that the disk in that drive has a different bitmap or index of free and used storage areas There are a number of sample programs in this manual ranging in complexity 195 one to several dozen program Lines Remember that these samples are Ly to demonstrate the use of the AiphaBASIC XCALL subroutines and are not intended as examples of the best or most elegant techniques to oy E i SG iA o Stan E EN ES r EE pl 2 B A AX T C GY m am XM Ya GitOw WSOP cnheats A ML i pd gt ie fr rt 131 mg 16 quickly grasp the point of these examples remember that 7 ermit the lo as i 7 k mit Ze EK 5 e D K j PEN Se sy Hi cub Li Z oe SR E CR 4 E v TE 4 ES E Ze ES M Re m Line numbers to identify Locations in a program program Label is composed of one or more alphanumeric characters which are not separated by a space or other delimiter The first character is always an uer case or Lower case letter A label must be the first item on a line after the line number and must be terminated by a colon 23 The following is an example of labels RANDOM DIRECTION UP DOWN and 2 m ip K gt e Mes gv amp i 5 A 3 UA T n
63. he numbers you choose are up to you You may choose to assign some meaning to the numbers for example the first number might be the file channel number of the file you want to lock and the second number might be the number of the record within that file that you want to Lock Since both numbers in the Lock may range from 1 to 65535 the actual possible number of unique locks is 65535 65555 But every time you create a lock the system sets aside a block in the monitor queue in system memory for that lock which ts not returned to the available List until the Lock 3s released by the job that has it Locked Since there are initially only 20 queue blocks available it s a good idea to keep the number of locks to a minimum A good rule is that a program should not have more than two or three locks active at any one time As you clear a tock that queue block becomes available again So in essence every time vou set a lock you create it and every time you clear a lock you destroy it 2 64 THE MODES The MODE argument in the XLOCK call line can contain one of four values 0 5 which selects one of the four possible locking modes 0558 1 0008 00 REV 60 XLOCK XCALL SUBROUTINE FOR MULTI USER LOCKS Page 5 4 5 5 1 MODE Lock and Return Thi is mode tells XLOCK to create a lock with the value LOCKT LOCK2 If the ock already exists 7 some other job is accessing the iie or device vn want to use XLOCK returns with MODE equal to
64. hem via XCALL this manual does not discuss how those machine Language subroutines can be written This manual instead restricts iself to a discussion of the existing external subroutines named BASORT COMMON FLOCK XLOCK SPOOL and MOUNT You will find this manual useful if you are already somewhat familiar with AiphaBASIC and wish te understand and then access these external subroutines You may also find this manual to be useful later as a reference guide to the various existing subroutines Please refer to the ALphaBASIC User s Manual DWM 00100 01 for further information about the XCALL keyword and any other topic dealing with ALDhaBASIC itself 1 1 MANUAL ORGANIZATION This manual is arranged in chapters You are reading the introductory chapter Chapter 1 Chapters 2 through 7 discuss the XCALL subroutines themselves how when where and why to use them and what special features they provide Chapter 2 talks about BASORT the ALphaBASIC Sort subroutine BASORT sorts the kinds of files called Random files and sequential files There is also a list of the error messages the BASORT subroutine may return 055 10008 00 REV ANO WTA INTRODUCTION Page 1 2 Chapter 5 discusses COMMON the externai subroutine that enables data to 0 ransferred into a common storage area of memory for example to pas age variables between chained programs Sas E nib Au poe CN A 3 EH 0 we GE pH E zs i E Verre Sei D
65. ine printer spooler program is currently running on the system note of caution Each use of SPOOL in your AlphaBASIC program places the filename specified in the XCALL SPOOL program Line into the monitor queue The system is protected so that a certain number of monitor queue blocks currently 15 are left unoccupied by SPOOL or by the monitor command PRINT However if the total of monitor queue blocks being occupied at a given moment by all the jobs running on the system including your AlphaBASIC program using SPOOL exceed the total allocated the system will Lock up and require a manual reset No error message will be generated 6 5 SUMMARY SPOOL inserts a file into your system s printer queue after which your ALphaBASIC program can continue to do other things The file spooled into the queue waits its turn to be printed SPOOL has a number of options that are very similar in both function and use to the options available using the PRINT command from AMOS or AMOS L command level The options each have specific positions on the XCALL SPOOL program Line If an option is not desired but a subsequent option is the preceding option must be replaced by a placehotding null string enclosed in ek quotes i 1 For AMOS systems but not AMOS L systems one option the SWITCHES command equires that FLTCNV PRG be in system or user memory TS gh 3 Subsequent options those whose positions an the XCALL SPOOL program Line ar
66. k based polyphase merge sort That is the data is brought into memory in small groups where it is sorted and rewritten to the disk then the several groups are merged together on the disk Po BASORT XCALL SUBROUTINE FOR SORTING FILES Page E DW 2 1 LOADING BASORT INTO MEMORY The BASORT package consists of three modules or two modules on AMOS L systems BASORT GBR AMSORT SYS and FLTCNV PRG FLTCNV is omitted on 80571 Systems These modules must be in memory when BASORT is used When the XCALL BASORT command is used in an 28 51 program the ALPhaBASIC program automatically Loads BASORT SBR into user memory However AMSORT SYS and FLTCNV PRG for AMOS systems must be Loaded into either system or user memory prior to running an AlphaBASIC program usina BASORT load SORT SYS and i i To 8 Cand FLTCNV PRG for AMOS systems into user memory enter the following from AMOS or AMOS L command Level LOAD DSKO AMSORT SYS 1 4 GEN or LOAD DSKO AMSORT SYSDT 4 RET LOAD DSKO FLTCNV PRG 1 47 RET RE ANM 5 To Load AMSORT SYS and FLTCNV PRG into system memory you must have twa Lines in your system initialization command file thet perform those functions For more information on Loading subroutines into system memory during system boot up see the AMOS System Operator s Guide D55 10001 00 or the AMOS L System Operator s Guide DSS 10006 00 A ON NADA ARNO
67. me record in file must first be granted Actions 5 6 Code 100 Unimpiemented Action Code 101 File channel number is not open in AlphaBASIC for RANDOM processing Actions 5 6 D35 10008 00 REV ADO FLOCK XCALL SUBROUTINE TO COORDINATE MULTIUSER FILE ACCESS Page 4 8 gt Code 102 File channei is already open in AlphaBASIC for an ISAM indexed file Code 105 For actions 0 3 and 4 Less than 15 queue blocks are available or calls to FLOCK which do not use modes 4 or 6 vou should use the A Return Code greater than 1 is an indication of some programming error For following statement while debugging vour program LF Return fode gt THEN PRINT FLOCK Error STOP For calis which use modes 4 or 6 Return Code 1 should be checked to determine if FLOCK was able to immediately satisfy the request Modes 4 and 6 are generally used in this way to allow the user to cancel a request which may involve a Lengthy delay 4 352 353 Queue Block Requirements The FLOCK subroutine builds its dynamic tables out of monitor queue blocks The moniter queue is a List of blocks of system memory which are Linked ta each other in a forward chain It is very important before running any AlphaBASIC program using FLOCK to ensure that the monitor is configured to make an adeguate number of these queue blocks available The number of queue blocks FLOCK uses varies with the number of jobs accessing files the number of files op
68. mer names in is called POINFO DAT containinc the purchase order information of the specific printed business form we re pretending they ordered from us ROBIN GOOD PUBLICATIONS 1 3 84 49130 K A L ENTERPRISES 12 7 81 1207 EVANS CLASSIC AUTOMOBILES Inc 1 20 81 KZA ROBIN GOOD PUBLICATIONS 2 14 81 49201 DE SOTO HORSE GROOMING EQUIPMENT Co 4 7 81 1836 VIDCOM 2 3 81 14101 ROBIN GOOD PUBLICATIONS 2 28 81 49393 MARTIN MICHAEL LAVELLE CONSULTANT 6 12 81 78729 HONEST DAVE S CHEAP CAR PARTS 9 11 81 A00326 DE SOTO HORSE GROOMING EQUIPMENT Co 4 9 81 1895 ROBIN GOOD 2 28 81 49397 EVANS CLASSIC AUTOMOBILES Inc 9 11 81 L98467 BASORT XCALL SUBROUTINE FOR SORTING FILES Page 2 5 The program that we will use to sort the above file Looks like this 3 SAMPLE PROGRAM TO SORT SMALL KANDOM DATA FILE 10 1 aoe DEFINITION OF RECORD 15 627 NAME 2922 55 BYTES MAXIMUM 20 MAP PURC HAS UATE S l 8 BYTES MAXIMUM PURCHASE ORDER 8 7 l f BYTES MAXIMUM 30 MAP RECORD SIZE F 6 50 RECORD IS TOTAL OF 50 BYTES 55 MAPT RECORD NUMBER F 6 0 START WITH RECORD 0 40 MAPI CHANNEL Ee 200 FILE IS OPEN ON CHANNEL 100 43 MAPT RECORD TOTAL F 6 12 TOTAL OF 12 RECORDS IN FILE 50 1 650 SORT IN ASCENDING ORDER 35 MAPI STRING F 6 0 ALL KEYS ARE OF TYPE STRING 100 START 120 OPEN 100 POINFO DAT RANDOM RECORD SIZE RECORD NUMBER 150 PRINT Now sorting 140 KCALL BASORT CHAN
69. mp amp QD RA ONU VEMM Se geg Ap ep A HH O O SN ah A dean ORA QUK AUD cms ee SEA SR zt coto St HS GS OS GEM es e CH seu ez AN PLACE S AMP HERE n INT BA fm Sr HIT TY Maa ENIM a A EN TOMA TOI EAN Cum A NA 1 MOL NAH HHH II AH AE Add A Al ERA eeng Et etre AA IIIA EOD MV nena I m alpha micro A PATA aet TEETAN 3300 rer eneen T2 0 1 Sky Park North 17881 7 PO Box 92714 irvine California RETF ON PRIN A IO PT y ONTO 170844066 een 4 STI A RTS WS 2 22 IMO gtt AAA dd DD TCE OO EEE IS ATTN TECHNICAL PUBLICATIONS RORY HHO MANION UR 5 8 9 9 Bow 4 NOR RR 9 9 B 8 6 M 5 GE 9 9 lt FOLD FOLD
70. n command file 553 1 0008 00 REV 6 T ae NL 5 CHAPTER 6 SPOOL XCALL SUBROUTINE FOR SPOOLING FILES TO THE LINE PRINTER SPOOL is an XCALL subroutine that you can call from AlphaBASIC to spool a disk file to the Line printer SPOOL is actually an acronym meaning Simultaneous Printer Output On line To spool a file is to insert it into the printer queue after which you can continue to do other things while your file waits im the queue for its turn to be printed You can specify to SPOOL which printer you want the file to be printed on the number of copies to print the form to print on the width measured in characters of a page and the lines per page Also you can specify any combination of switches to turn on or off the banner option the delete option which deletes the file from the printer queue after printing the header option the formfeed option or the wait option You do not have to load the SPOOL subroutine into system or user memory in order to access it from an AlphaBASIC program However if you have an 5 system rather than an AMOS L system and if you are going to use the SWITCHES feature of SPOOL you must Load FLTCNV PRG into either user or system memory before you run an AlphaBASIC program containing the XCALL SPOOL program Line To load FLTCNV PRG into user memory enter the following from AMOS command Levels To load FLTCNV PRG into system memory of your AMOS sys
71. n the program to close then reopen file channel 1 and the file STREET DAT If those two lines are omitted the new file ENSW LST though created would be BASORT XCALL SUBROUTINE FOR SORTING FILES Page 10 empty because no further date would be found in the file STREET DAT These two Lines Cause the BASORT subroutine to look at the beginning of the file rather than the end Line 150 is the second XCALL BASORT program Line in the AlphaBASIC program This iine is different than the first Line 130 because we are now specifying the direction byte Ne 5 E or W as Key 1 and the street name as Key He The size of key 1 is always just 7 byte im size so on the XCALL BASORT program line after the delimiting comma following the subroutine name we enter a l The position of Key 1 is the thirty third byte column 33 0 we next enter a 35 We must specify a or a 1 to flag whether we want to sort Key 1 in ascending or descending order ASCII sequence puts E first then N then S and which is fine with us We ll enter a here Key 2 this time is the street name That is the size of Key 2 in this case is 25 The position of Key 2 is column or record byte number 1 We want the street names within the four direction groups alphabetically ordered so we specify ascending order or 0 Again we don t have a Key 3 so we specify K y 5 size position and order as 0 0 and 0 respectively 1 Lines 200 21
72. nconsistent reports and so fortha 4 5 THE FLOCK SUBROUTINE PLOCK exists to prevent multiple update problems interconsistency flaws ana other file access hazards that may occur if you are not the only user on your system FLOCK provides a way to synchronize attempts at accessing files and devices so that you and the other users can avoid partially updating or scrambling data amp 2 1 FLOCK Program Requirements FLOCK only functions properly if it is Loaded into system memory FLOCK resides in account DSKO0 L7 61 and has a SBR extension If you have an AMOS system rather than an AMOS L system FLOCK also requires that you have FLTCNV PRG in system memory FLTCNV PRG resides in account DISKO ET phla IMPORTANT NOTE You must load FLOCK into system memory onlyz 3t wili appear to work if vou load it into user memory but no file Locking will actually OCCUnP FLOCK XCALL SUBROUTINE TO COORDINATE MULTI USER FILE ACCESS Page 4 5 To load FLOCK SBR Cand FLTCNV PRG for an AMOS system into system memory you must have Lines in your system initialization command file that perform those functions For more information on Loading subroutines into system memory during system boot up see the AMOS system Operator s Guide 055 1 0001 00 or the AMOS L System Operator s Guide 055 1000200 4 3 2 FLOCK Calling Sequence The calling sequence for FLOCK in ALphaBASIC 18 KC ALL FLOCK ACTION MODE RETURN CODE FILE RECORD Where 1 Action
73. ng XLOCK to control multi user 0 af random files For information on random files see Chapter 15 of the AlphaBASIC User Manual DWM 00700 07 If you are going to be T ETN MBN TNA Locking a specific file 2 EE you need to understand the relationship between disk blocks and file records A record sometimes called a Logical record is a grouping of data that vou define you also define the length of that record Just as an example let s define a file record that contains 6 bytes for a customer ID number 24 bytes for a customer name 10 ee 55 1 0008 09 REV 6 XLOCK XCALL SUBROUTINE FOR MULTI USER LOCKS Page 5 7 bytes for the name of the customer s sales contact and 10 bytes for the customer phone number This file record would then contain 50 bytes A disk block is a physical grouping of data on the disk that is always bytes long The monitor always transfers disk information in this 512 byte block amp lphaBASIC unblocks a disk block into smaller groups your logical records For example one disk block 512 bytes would contain 10 of the Logical records we defined above 50 10 S00 with 12 bytes left over No Logical record is ever larger than a disk block NOTE You specify the size of your Logical record in the OPEN statement for the file The reason for our explanation above is this if you want the LOCK2 value to contain the number of the record you are updating 1t m
74. nnel open for input Then we indicate the output file channel 2 where we want the file sorted the first way Note that in the unsorted file above a recard the data of a single street name 1s confined to one line That makes it easy to judge the approximate size of the longest record 30 being liberal we round it up to a record size of 50 The size of key H1 is never more than 25 bytes in size so next on the XCALL 085087 Line we enter a 25 The position of Key 1 is the first byte in the record column 1 as it happens so we enter a 1 Next we must specify a U or a 1 to flag whether we want to sort Key 1 in ascending or descending order Our street index is alphabetically ordered starting at A and ending at Z so we enter a here to choose ascending order Key 2 is our direction N S 6 or W The size of Key 2 in this case is always 1 The position of Key 2 in our file STREET DAT is column Lor record byte number 33 We don t really care whether our directions are ascending or descending yet but we ll enter a 6 to indicate ascending arder We don t have a Key 3 so we specify Key 3 size position and order as f 0 and 0 respectively Note that we do not specify the data type of keys 1 H2 and 3 for a sequential file because they are always ASCII data which 885087 knows After Line 150 is executed the file STREET LST is created and the data in STREET DAT is rewritten in alphabetical order Lines 135 and 65 are i
75. oan ee ae XCALL SPOOL LENAME PRINTER SWITCHES COPIES FORM The FORM option of the XCALL SPOOL command Line may specify a form that vou want mounted on the printer The FORM may be either a string variable or an expression 5 MAPT 6 10 FORM PAYROL 20 XCALL SPOOL FILENAME PRINTER SWITCHES COPIES FORM CT 10 XCALL SPOOL FILENAME PRINTER SWITCHES COPIES PAYROLL where PAYROL is the name of a form defined by the monitor TRMDEF command Note that 8 string expression identifying the form to use must always be 3 enclosed 3n quotation marks When SPOOL sends a file to the printer queue if the FORM option is selected and the form specified is different than the one mounted on the printer the file will not print Instead the file will simply remain in TuS queue until the monitor SET command is used and the form is changed to match the ane used in the XCALL SPOOL program Line See the SET reference she et in the AMOS System Commands Reference Manual DWM D0O100 69 or the AMOS L System Commands Reference Manual DSS T0004 00 for more information on Setting the form for the printer to use D358 10008 00 REV ADD SPOOL XCALL SUBROUTINE FOR SPOOLING FILES TO THE LINE PRINTER Page 6 7 6 1 1 6 XCALL SPOOL FILENAME PRINTER SWITCHES COPIES FORM WIDTH i LPP dive EREECHEN NRA IM IITIN AE PROP REFERS DNE EEN REESEN EE ORES
76. ond program to print zero thus ONE USER 1 REC 1 2 USER 2 ONE TWO 2 gt mm TAM Soe cote EEN cle TAM ONS er ODS EES ES G t GRY 2 ege oom D ORE AURA MOD NIS OT UNO OM vid COND gn HE Ce HON co erg cbt ET ANA Cem cents dunk PASA Dr NUT ere arr OPEN H1 FILE RANDOM 6 KEY 5 5 5 KEY 1 READ 1 0NE 5 5 6 ONE ONE 1 3 WRITE 1 0 6 6 5 5 KEY 2 READ 1 ONE 6 85 6 ONE ONE 1 WRITE 1 0NE 6 6 6 CLOSE 1 END 6 6 6 6 OPEN 1 FILE RANDOM 6 KEY 6 6 KEY 1 READ 1 0NE G 6 KEY 2 READ 6 6 6 6 PRINT ONE TWO 6 6 0 6 6 CLOSE 1 END 6 6 FREE AE QM Ve MAD GNU MES OUO HIRT AE AEN COMER One CEE onem nci VEY cce mde ir ANE TEMA REE Ae quic ci cdd VE DR THO GRRE ACEN uy EEN CRX nce rid PRAY HIIN AMO Cem ET d MEM idum ont debe er uk NY TARE ne coor cen D35 10008 00 REV 00 FLOCK XCALL SUBROUTINE TO COORDINATE MULTI USER FILE ACCESS Page 4 4 However under some circumstances it is possible for the second program to print 1 rather than 0 ONE USER 1 REC 41 2 USER 2 ONE TWO OPEN 41 FILE
77. one EF Consider an example of application in which you and several other users are interactively updating an employee record file Assume files are kept open only where required Once you display an employee s record it is necessary that aii the other users wait for you to finish making changes to that record before they can in turn access itz otherwise two users might concurrently attempt to update the same employee record This results in the multiple update problem described in Section 4 1 2 In other words all other users must wait for one user to enter chariges to the employee s record before any other user can access and modify that record This is called a record update interlock and is a far less severe restriction to all the users accessing a file than a file open interlock is NOTE You should remember when performing a record update interlock that FLOCK converts Logical record numbers into physical block numbers Ail record Locking operations are performed on physical blocks not togical records If both you and user attempt to lock two separate Logical records within the same physical block vou will see the error message Record already Locked Actions 3 and 5 of FLOCK permit control of concurrent access to individual Action 3 Mode 0 or 4 is used before reading a sequence of records which will not be used for updating in order to prevent interconsistency errors see Section 4 1 3 Action 5 is used afte
78. ose files can fit entirely into user memory The data to be sorted must already be in 8 format where the BASORT execution Line within an AlphaBASIC program can Specify the position and size of up to three sort KEYS The data can be 0 60 in ascending or descending order each key being independent of the fat haps Me TUS Ge m Because BASORT combines as needed two sort techniques called a memory based heap sort and disk based polyphase merge sort it is a relatively fast sort utility subroutine CHAPTER 5 COMMON XCALL SUBROUTINE TO PROVIDE COMMON VARIABLE STORAGE COMMON is an external subroutine that allows you to place data into a common storage area of either user memory or system memory The data can be numeric variables or string variables of up to 150 bytes in length When this data is in user memory it may be accessed by separate ALphaBASIC programa as when chaining from one program to a8 second that requires variable information defined in the first program When it is in user memory the data is only common to programs run by the particular job that olaced them in memory When in system memory this common data can be used Lo pass messages between jobs or for any other function that requires a data area that is accessible to more than one person The common data is placed in either user or system memory via an program The idea is to assign a name to one or several packets of data which can L
79. ou may similarly unmount a disk by making the U switch part of the same expression or string variable 10 XCALL XMOUNT HWK13 ZU or 5 MAPI DEVICE S 9 10 DEVICEZ HWKT U 20 XCALL XMOUNT DEVICE The only option available when using XMOUNT other than the U switch to K unmount a disk is the ability to store the volume ID of the newly mounted disk within a string variable perhaps to be displayed immediately after using the XMOUNT subroutine so the program user is Sure he or she put the right disk in the drive XMOUNT recognizes this option when it sees a string variable following the device specification string or expression Cand separated from it by a comme a XMOUNT returns the volume ID of the disk as that variable which then may be displayed or tested For example XMOUNT XCALL SUBROUTINE TO MOUNT 8 DISK Page 7 3 5 MAPI VOLUME ID S 10 10 MOUNTING XCALL XMOUNT VOLUME ID 20 PRINT VOLUME ID is mounted 30 IF VOLUME ID lt gt ARCHIVE THEN GOTO WRONG DISK 40 GOTO CONTINUING 100 WRONG PISK PRINT This is not the ARCHIVE disk 110 PRINT You may abort the program or place the correct 120 PRINT disk in the drive To abort type Control C STOP 130 GOTO MOUNTING 200 CONTINUING sas If the volume ID string variable is omitted or is too small or if a follows the device specification string variable or expression the volume ID variable is ignored and returns a null string f SUMMARY Th
80. r the sequence of reads Action 3 Mode 2 or 6 is used before reading records which will be used for updating Action 5 is used again after rewriting the records amp 6 d 1 The Multiple Update Problem STASIS TUTE NOONE BORER TE Here is how the program of Section 4 1 7 can be rewritten to incorporate tecord Update interlocks 5 ON ERROR GOTO ABORT 10 XCALL FLOCK 0 0 RET 1000 20 OPEN 1000 FILE RANDOM 6 KEY 0 KEY 1 40 XCALL FLOCK 3 2 RET 1000 KEY 50 READ 1000 ONE 60 ONE ONE 1 70 WRITE 1000 ONE 80 XCALL FLOCK 5 0 RET 1000 KEY 90 CLOSE 1000 100 XCALL FLOCK 1 0 RET 1000 110 END 4 130 XCALL FLOCK 2 O RET 140 ON ERROR GOTO D 058 1 0008 00 REV AO FLOCK XCALL SUBROUTINE TO COORDINATE MULTI USER FILE ACCESS Page 4 13 6 6 2 2 The Interconsistency Problem Here is how the programs of Section 4 1 3 can be rewritten to incorporate Record Unpdate interlocks 10 ON ERROR GOTO ABORT 20 FLOCK 0 0 RET 1000 21 OPEN 1000 FILE RANDOM 6 KEY 30 KEY 1 31 XCALL FLOCK 3 2 RET 1000 KEY Se READ 1000 O0NE ONE ONE 1 WRITE 41000 ONE 25 XCALL FLOCK 5 0 RET 1000 KEY 40 KEY d 41 XCALL FLOCK 3 2 RET 1000 KEY 42 READ 1000 0NE ONE ONE 1 WRITE 21000 ONE 45 XCALL FLOCK 5 0 RET 1000 50 CLOSE 7000 51 XCALL FLOCK 1 0 RET 1000 60
81. ram is updating FILE other programs can have FILE open This prevents the second program from reading FILE when it is in a partially updated state Since the second program does not update FILE it requests permission to open it using Mode 0 with Action 0 This enables other pragrams which read but do not update FILE to open and process simultaneously A A Recorduliodate Inter locks Most programs open files when the programs begin and close those files when they end The programs may not actually need the files to be open throughout execution but by not repeatedly opening and closing the files the programs avoid many undesirable delays File open interlocks that are set lock out the entire files if a file is open throughout the run of a program and thus unavailable to programs run by other users serious or annoying delays can resuit Although file open interlocks de prevent concurrency problems they generally reduce concurrency far more than 1s necessary Typically file open interlocks lock out the entire file to prevent access to the Dp5S 10008 00 REV ADO FLOCK XCALL SUBROUTINE TO COORDINATE MULTI USER FILE ACCESS Page 4 12 single record Locking out an entire file to prevent access to a single record is like using a sledge hammer to drive a push pin ALL that actually necessary is to delay any other user attempting to modify the record until the usec originaliy accessing the record is d
82. rn a 5 2 20 The XCALL COMMON Command Line You call COMMON to send data to the common area via XCALL COMMON SEND MSGNAM INFO You call COMMON to receive data from the common area via ACALL COMMON RECEIVE MSGNAM INFO A onerbyte binary variable that contains zero A tworbyte binary variable where the first byte must be set to one and the second byte functions as a flag that indicates whether or not COMMON found the requested packet of information If COMMON did not find that packet it returns a zero in this byte otherwise it is non zero IMPORTANT NOTE Once you use COMMON fo retrieve a data packet that data packet is gone from memory and cannot be read again string containing from one to six characters that specifies the name of the packet to be sent or received Note that string literal must be enclosed in quotation marks COMMON also can handle a string variable here Le 0 e XC ALL COMMON SEND PACKET INFOJ A string variable of course must be defined earlier in the programe The variable to hold the data to be sent or received The variable must represent data that is less than 151 bytes Long RECEIVE MSGNAM INFO if you load COMMON into system memory making the data accessible to ait users be sure the f to character name is unique for each packet D8 10008 00 REV 06 COMMON XCALL SUBROUTINE TO PROVIDE COMMON VARIABLE STORAGE Pa
83. s of sort key 2 KEY2 POSITION The first character position occupied by key 2 KEYZ ORDER sort order of key 2 Enter a or a 1 Sea KEYT ORDER above KEYS SIZE The size in bytes of sort key 3 885087 XCALL SUBROUTINE FOR SORTING FILES Page 2 4 KEYS POSITION The first character position occupied by key 3 KEYS ORDER sort order of key 3 Enter a or a 1 See KEYT ORDER above KEYT TYPE The data type of key 81 Key types are QO String Floating Point 2 Binary KEYE TYPE The data type of key 2 See KEYT TYPE above KEYS TYPE The data type of key 3 See KEYT TYPE above Remember keys are the elements of the data records yOu wish to base your sort on i e customer name order number etca If you want to use Less than three keys all entries im the XCALL command Line for the unused keys must be zero If the key types are omitted BASORT assumes string data CYPE ALL arguments in the XCALL command Line are numeric but may be passed as either floating point or string values For example 99 is a valid entry Arguments must not be in binary format The first character in a record is considered position 1 H 2 fee Z i 1 1 An Example of using BASORT on a Random File O are A KEE SVE STS The following is the contents of an unsorted file that we ll pretend we want sorted The file we have gathered the following custo
84. s more than one resource simultaneously There is a simple way to prevent DEADLOCK a method which in most cases is feasible to implement The method is ALWAYS request resources in the same order 055 1 0008 00 REY ADD FLOCK XCALL SUBROUTINE TO COORDINATE MULTI USER FILE ACCESS Page 4 16 Here is a simple illustration of the principle First we consider what can happen if resources are requested in differing order in two programs 40 PROGRAM 1 20 XCALL FLOCK 0 2 RET 1001 21 XCALL FLOCK 0 2 RET 1002 100 REMARK aa BODY OF PROGRAM 990 XCALL FLOCK 1 0 RET 1002 991 XCALL FLOCK 1 0 RET 1001 992 END 16 PROGRAM 2 20 XCALL FLOCK 0 2 RET 1002 21 XCALL FLOCK 0 2 RET 1001 100 REMARK BODY OF PROGRAM 990 XCALL FLOCK 0 2 RET 1001 991 XCALL FLOCK 0 2 RET 1002 992 END Consider the following sequence of execution 1 Program 1 executes Lines 10 and 20 obtaining exclusive permission to open file 1001 2 Program 2 executes Lines 10 and 20 obtaining exclusive permission to open file 31002 It then executes Line 21 and must be delayed because Program 1 already has exclusive permission to open file 1001 3 Program f executes Line 21 and must be delayed because Program c already has exclusive permission to open fite 1002 At this point programs 1 and 2 have both been delayed Since no other programs are present the reasons for their delays will remain unchanged DEADLOCK has occurred But DEADL
85. s not set by your job NOTE If you attach your terminal to another job XLOCK considers you a new job B 2 4 5 MODE 3 List Locks MODE 3 returns a complete List of all the locks set on the system and the numbers of the jobs that set them When vou use MODE 3 LOCKE must represent a mapped array Large enough to hold the expected data When XLOCK t from a MODE 3 cali MODE contains the number of loeks that are set on the system LOCK contains your job number LOCK2 contains one three word ry for each lock that is set on the system You must set up this entry as three binary words in a MAP statement The first two bytes hold the job the second and third words hold the actual LOCKT and LOCKE values of ified lock The following is an example of how to set up the MAP nt for a MODE 5 call 551 0008 00 REV 400 XLOCK XCALL SUBROUTINE FOR MULTI USER LOCKS Page 5 5 10 MAPT MODE B 2 20 MAPT MYJOB B 2 40 MAPT LISTARRAY 40 MARE LOCKENTRY 25 50 MAPS JOBNUMBER B d 60 MAPS Li B 2 FO MAPS L2 B d SO Start of Program goes here 100 MODE 5 110 XCALL XLOCK MODE MYJOB LISTARRAY 120 Rest of program goes here A system lock consists of two numbers the values of LOCKT and LOCKE If either of these two numbers is a zero that number is a wildcard and number between T and 65555 will match it A wildcard is a symbol that is matched by any other symbol You can use wildcards for various reasons For example suppo
86. se that you decide that the LOCK1 value is going to represent a particular file and that the LOCK2 value will represent a particular record in that file If you want to stop all references to that file while your program is accessing TE you would set the lock with a zero in LOCK2 arid the number representing your file in LOCK1 Anyone who tries to set a Lock that has the same LOCKT value as your Lock won t be able to do so the system will tell him that that Lock already exists since your wildcard in LOCK2 will match any number he may try in that position No one including yourself will be able to set a Lock with the same LOCK value until you clear the lock Note that setting a lock with beth numbers zero will prevent anyone from setting a lock since the system will say that all possible locks are already set 5 6 PROGRAMMING EXAMPLES The following is a small sample demonstration program that you may want to use to experiment with XLOCK and to get a feeling for how it works Tt asks you for the values of MODE LOCK1 and LOCKE and then reports back on the results of the Locking operation vou asked for Remember MODE 0 sets a lock MODE 1 sets the Lock after waiting for it to be cleared MODE d clears the Lock and MODE 3 displays the locks set 53 8 1 0008 00 REV A00 XLOCK XCALL SUBROUTINE FOR MULTI USER LOCKS Page 576 5 i Sample Program to Illustrate File Locking tO MAPI FLAG F 15 MAF COUNTER F ZO MAPI MODE B
87. se the SWITCHES argument The switches that SPOOL uses are the same as the switches of the same names used by the monitor PRINT command See the AMOS System Commands Reference Manual DWM 00100 49 or the AMOS L System Commands RK Reference Manual 88 10004 00 for Information on PRINT 7 The switches are 1 BANNER To print a banner identifying page at the front of the printout NOBANNER So a banner will not be printed 5 DELETE To delete a file after it is printed NODELETE So a file is not de eted after it is printed 3 HEADER To print a page header at the top of every page of the printout Page headers give the name of the file being printed the date wheres PRINTER SWITCHES 055 10008 00 REV ADO SPOOL XCALL SUBROUTINE FOR SPOOLING FILES TO THE LINE PRINTER Page 6 3 and the current page number 6 NOHEADER So a page header is not printed on each page of the printout 7 FF To do a formfeed after a file is printed 8 NOFF Supresses formfeed after a file 8 printed 9 WAIT To wait until previous entries into the printer queue are finished printing SO that the print request is not discarded if the printer queue is temporarily full If the file has to wait to be printed the job running the 8100898857
88. signated packet A non zero means it did find it Line 40 defines RETRIEVE as a string variable of up to 150 characters in Length Line 50 defines PACKET as a string variable of up to six characters in Length Line 100 asks the program user for the name of the packet in common memory that he or she wants to retrieve Line 110 begins with the BASIC keyword XCALL which means the program is going to access one of the external subroutines on the system COMMON is the name of the specific subroutine to be accessed RECEIVE is the variable name for the binary byte that because it is a 1 tells COMMON to find a data packet in common memory PACKET is the string variable that takes the string the user enters at Line 100 and uses it to name the specific packet that COMMON is to find ignoring any others that may be in memory Finaliy the variable RETRIEVE is assigned the value of the data found in that packet Line 3120 tests the binary flag to see if the packet was found and displays the appropriate message on your terminal If the packet is found its contents are displayed also Then the program ends sample runs of the sample programs above could be RUN FIRST RET Enter message maximum of 150 characters TEMPUS FUGIT ET Now enter name of data packet up to 6 characters MESAG1 RET TOT OCONEE TTY FAO AERE DA A CICERO Ee RA TA a ARDON ande RUN SECOND RET tnter name of da
89. sk block force the system to write that record by reading 3 Logical record that falls outside of that disk block NOTE You may also use the RANDOM FORCED mode in your OPEN statement to force AlphaBASIC to perform 8 disk read or a disk write every time you acc ss the file See Chapter 5 of the AlphaBASIC User s Manual for more information The sample program selow may help to last few paragraphs 055 10008 00 REV AQQ XLOCK XCALL SUBROUTINE FOR MULTI USER LOCKS Page 5 8 5 6 2 Sample Program to Illustrate File Record Locking D Sample Program to Illustrate File Record Locking Remember to load XLOCK SBR before running 20 MAPT MODE B 2 Define locking variables 25 MAPT LOCK B 2 30 MAPT LOCK2 8 2 55 MAPT LOGTCAL RECORD Define logical record 40 MAP CUST ID i contents 50 bytes 45 MAPS CUSTOMER 26 i of customer info 0 MAP CONTACT En Customer ID is actually 55 MAP2 PHONE 8 10 Logical record number 60 MAPI RECORD SIZE F 50 65 Scratch variables 70 MAP1 RECORDNUM F Logical record number 75 MAPI FLAG F 80 MAPI QUERY S 1 85 Begin program OD START LOOKUP CUSTID DAT FLAG If file doesn t exist TF FLAG D THEN GOTO FILE ERR report error and exit OPEN 700 CUSTID DAT RANDOM RECORD SIZE RECORONUM LOCK 100 i 400 represents CUSTID file PRINT Welcome to the Customer Maintenance Program LOOK INPUT Pier 5 ei KI A gt e amb 4
90. st Actions 0 through 2 it is possible to implement a very simple file access coordination scheme which solves the problems of Sections 4 7 2 and 4 1 3 Action 0 Mode 0 or 4 is used before opening a file for input only that is opening a file for RANDOM processing upon which only READS will be performed Action 0 Mode 2 or 6 is used before opening a file for output e g a file open for RANDOM processing upon which REAPS or WRITES will be performed or a file which may be re created Finally Action 1 is used after closing any file and Action 2 3s used before any abnormal termination points in the program 4 4 1 1 The Multiple Update Problem a AENEA IEAA OONA E EEA TO a ANN T Here is how the program of Section 4 1 2 can be rewritten to incorporate file open interlocks 055 100008 000 REV 0 FLOCK XCALL SUBROUTINE TO COORDINATE MULTI USER FILE ACCESS Page 4 10 10 XCALL FLOCK 0 2 RET 1000 20 OPEN 1000 FILE RANDOM 6 KEY 30 KEY 1 40 READ 1000 0NE 506 ONE ONE 1 60 WRITE 1000 ONE 70 CLOSE 1000 80 XCALL FLOCK 1 0 RET 1000 90 END The program now will function correctly in a concurrent environment If any other programs have FILE open when line 10 is executed Cand have informed FLOCK of the fact with Action 0 FLOCK will make the above program wait until the other program closes FILE Furthermore no more programs will be allowed to open FILE until the above program reaches line 30 The above
91. ta packet MESAGT RET Message is TEMPUS FUGIT ET OEY ENN etr i DIA ATTE T When running the second program above if you were to enter a message name that does not represent a packet in COMMON Memory you would see the message from Line 420 of the program saying Message not found D55 10008 00 REV ADO COMMON XCALL SUBROUTINE TO PROVIDE COMMON VARIABLE STORAGE Page 3 6 3 4 SUMMARY COMMON is an external subroutine that allows you to place data inte a cammon storage area in memory This is useful for passing data between chained programs passing messages between Jobs or any other function that requires a data area accessible to more than one program or person Sy assigning a name to each packet of information within the common area you can have Several of these packets in common storage ready to be retrieved by other 56 5 or programs at various times 055 10008 00 REV 0 CHAPTER 4 FLOCK XCALL SUBROUTINE TO COORDINATE MULTI USER FILE ACCESS The name FLOCK is an acronym for File Locking FLOCK is an external subroutine that is callable from AlphaBASIC and is used in a program that accesses files when it is necessary to protect a file or files from concurrent access by another user In other words FLOCK prevents one user from accessing information that another user is updating at the same time Below we describe in some detail the potential problems of multi user file
92. tem you must have a Line in your system initialization command file that performs that function For more information on Loading subroutines into system memory during system boot up see the AMOS System Operator s Guide DSS 10001 00 or the AMOS L System Operators Guide 955 10002700 055 10008 00 REV 800 SPOOL XCALL SUBROUTINE FOR SPOOLING FILES TO THE LINE PRINTER Page 6 2 6 1 USING THE XCALL SPOOL SUBROUTINE subroutine from within an AlphaBASIC program vias Cali the SPOOL XCALL SPOOL FILE PRINTER SWITCHES COPIES FORM WIDTH LPP A string variable or expression that gives the specification of the file you want print If you specify a file which does not exist SPOOL doesn t tell you that it can t find the file but of course doesn t print anything A string variable or expression that gives the name of the printer you want to send the file to Tf PRINTER ig omitted or is a null string SPOOL uses the default printer If you want to use the default printer and also wish to use one or more of subsequent features SWITCHES COPIES eto piace a null string designation UU in the PRINTER position of the program Line Ce g XCALL SPOOL DATA TXT 55 A floating point variable or expression that specifies various control switches and flags that affect the printing of the file if you have a AMOS system as opposed to an system e GU must load FLTCNV PRG into system or user memory i you are going to u
93. tialization command file See the AMOS System Operator s Guide D5 10001 00 or the AMOS L System Operator s Guide 055 100 fit ill for information on the system initialization command file 2 THE XMOUNT SUGROUTINE You can call XMOUNT to mount a disk vias XCALL XMOUNT DEVICE VOLUME 1D Wheres DEVICE String variable or expression that represents a device specification e g BSKT You may optionally follow the device specification with U to unmount the device te g DSK S U S XMOUNT XCALL SUBROUTINE TO MOUNT A DISK Page Z VOLUME 5 String variabie in which the volume ID of the mounted device will be returned This variable must be 10 bytes Long If it is not specified the Labels block will not oe read This variable is ignored if the U option jis used Tf you specify the unmount option the U must be uppercase When you unmount a disk vou prevent AlphaBASIC and most system programs from accessing that device fot Some Examples Using XMOUNT As with all the XCALL subroutines callable from ALphaBASIC the program Line must begin with the keyword XCALL and the name of the subroutine XMOUNT The XMOUNT subroutine further requires a string variable or expression Co represent the specification of the device to be mounted or unmounted which is separated by a comma from the word XMOUNT For example TO XCALL XMOUNT HWKT 3 LAT MAPT DEVICE S 9 EVICES HWKT 3 10 D 20 XCALL XMOUNT DEVICE Y
94. tool to help you synchronize attempts to access devices and files You can imagine the problems that result when you have two users trying to update the same record of the same file at the same time A Lock is am entity created by a program ta help it keep track of whether a certain device file etc is in use at the specific time that the program wants to access it The general way that the Locking system works is this 1 When you want to prevent access to something a file a device etc while your program accesses it you create that is set a system lock on that resource 2 Whenever you want to access a device or file your program tries to set the lock associated with that item if it is already set you know that another user s program is using the device or file 3 When you are finished accessing a device or file you destroy that is clear the lock so that other programs can now access the resource Note that a svstem lock is NOT a security device it s a convenience tf a program wants to allow its users to write to a file without checking to see if another user is there first it can do so and run the risk of creating chaos A system lock simply provides a convenient way to help a program keep its users from conflicting in their attempts to use system resources The only job that can clear a lock is the job that originally set the lock ALphaBASIC does not automatically clear locks when a program
95. twocbyte binary variables They may not be floating point or string variables Far example MAP1 MODE B 2 MAPT LOCKT BR 2 MAPT LOCK2 8 2 Before you call KLOCK your AlphaBASIC program must first set up the correct values for MODE LOCKT and LOCK IMPORTANT NOTE XLOCK parameters must be defined on even byte boundaries in memory That is the variables must begin on word boundaries Variable structures defined at a MAP level always begin on a word boundary Therefore the easiest way to ensure that XLOCK arguments begin on 8 word boundary is to define them in MAPI statements as in the example above If you do define XLOCK parameters in deeper level MAP statements e g MAP2 or MAP3 make sure that the variables begin on a word boundary by keeping the number of bytes defined an even number For example this definition DS3 10008 00 REV 400 XLOCK XCALL SUBROUTINE FOR MULTIUSER LOCKS Page 5 3 MAP1 PARAMETERS MAP2 FILL 1 MAP 11 B 2 MAP2 2 B 2 MAP2 MODE B 2 will cause XLOCK to fail however removing the definition for FILL which pushed the XLOCK parameters onto an odd byte boundary will correct the problem 2 2 THE LOCKS A system lock is a two level numeric lock the number representing either level may be from 1 to 65535 CA value of zero in either position acts as a wildcard That is any number will match in that position when it comes clearing or setting that lock Some typical locks are T
96. ust contain the relative number of the disk block being used and not the logical record number When ALphaBASIC unblocks a disk block into logical records it brings the entire disk block into your memory partition Even if you are only updating one logical record in that disk block the entire disk block remaing im your memory area until you either close the file or read 3 Logical record that is in a different disk block What this means is that more than one user could try to write out the same disk block at the same time even though they are updating different Logical records So you must prevent access not only to the logical record that you are updating but to the entire disk block that contains it You must calculate the relative disk block number yourself by dividing the Logical record number by the blocking factor The blocking factor is the number of logical records that can fit in one disk block In the example above where we had logical records 50 bytes long the blocking factor is 10 Remember that each disk block is 512 bytes Long and will be blocked to contain as many Logical records as will fit If one of your Lock digits is the disk block number you can prevent access to the entire disk block no one can access any of the Logical records in the disk block until vou clear the lock REMEMBER The Lock wildcard symbol is a zero so calculate your disk blocks beginning with one instead of zero Before you unlock the Lack on a di

AMOS Basic XCALL subs

Contents

Download Pdf Manuals

Related Search

Related Contents