NetRexx 2

22nd May 2009

Mike Cowlishaw
IBM UK Laboratories mfc@uk.ibm.com

Version 2.00

Copyright Mike Cowlishaw 1979, 2009. Parts Copyright IBM Corporation 199 , 2000. !ll rights reser"ed.

Table of Contents
Introduction 7 Language objectives 7 Language concepts 10 Acknowledgements 15 NetRexx Overview 17 Net e!! programs 18 "!pressions and variables 19 Control instructions 21 Net e!! arithmetic 22 #oing things with strings 23 $arsing strings 24 Inde!ed strings 25 Arra%s 26 &hings that aren't strings 27 "!tending classes 29 &racing 31 Binar% t%pes and conversions 33 "!ception and error handling 35 NetRexx Language Definition 37 Notations 38 Characters and "ncodings 39 (tructure and )eneral (%nta! 40 Blanks and *hite (pace 40 Comments 40 &okens 41 Implied semicolons and continuations 44 &he case o+ names and s%mbols 44 ,e!adecimal and binar% numeric s%mbols 45 &%pes and Classes 46 &erms 48 "valuation o+ terms 49 Methods and Constructors 53 Method call instructions 53 Method resolution -search order. 54 Method overriding 55 Constructor methods 56
Version 2.00 3

&%pe conversions 58 "!pressions and /perators 61 /perators 61 Numbers 65 $arentheses and operator precedence Clauses and Instructions 68 Assignments and 0ariables 69 Inde!ed strings and Arra%s 73 Arra%s 74 Ke%word Instructions 77 Class instruction 78 #o instruction 82 "!it instruction 84 I+ instruction 85 Import instruction 87 Iterate instruction 89 Leave instruction 90 Loop instruction 91 Method instruction 98 Nop instruction 103 Numeric instruction 104 /ptions instruction 106 $ackage instruction 110 $arse instruction 111 $roperties instruction 112 eturn instruction 114 (a% instruction 115 (elect instruction 116 (ignal instruction 119 &race instruction 120 $rogram structure 124 $rogram de+aults 125 Minor and #ependent classes 127 Minor classes 127 #ependent classes 128 estrictions 129 (pecial names and methods 130 (pecial names 130 (pecial methods 132 $arsing templates 133 Introduction to parsing 133 $arsing de+inition 134 Numbers and Arithmetic 140 Introduction 140 #e+inition 141 Binar% values and operations 149 "!ceptions 152 Methods +or Net e!! strings 155 &he built1in methods 156
4

66

Version 2.00

Appendix A A Sample NetRexx Program Appendix B JavaBean Support Indirect properties 176
175

171

Appendix !"e netrexx#lang Pac$age 179 "!ception classes 180 &he e!! class 181 e!! constructors 181 e!! arithmetic methods 182 e!! miscellaneous methods 184 &he e!!/perators inter+ace class 185 &he e!!(et class 186 $ublic properties 186 Constructors 186 Methods 187 Index
189

Version 2.00

Introduction
Net e!! is a general1purpose programming language inspired b% two ver% di++erent programming languages2 e!! and 3ava45 It is designed +or people2 not computers5 In this respect it +ollows e!! closel%2 with man% o+ the concepts and most o+ the s%nta! taken directl% +rom e!! or its object1 oriented version2 /bject e!!5 6rom 3ava it derives static t%ping2 binar% arithmetic2 the object model2 and e!ception handling5 &he resulting language not onl% provides the scripting capabilities and decimal arithmetic o+ e!!2 but also seamlessl% e!tends to large application development with +ast binar% arithmetic5 &he re+erence implementation o+ Net e!! produces classes +or the 3ava 0irtual Machine2 and in so doing demonstrates the value o+ that concrete inter+ace between language and machine7 Net e!! classes and 3ava classes are entirel% e8uivalent 9 Net e!! can use an% 3ava class -and vice versa. and inherits the portabilit% and robustness o+ the 3ava environment5 &his document is in three parts7 :5 &he objectives o+ the Net e!! language and the concepts underl%ing its design2 and acknowledgements5 ;5 An overview and introduction to the Net e!! language5 <5 &he de+inition o+ the language5 Appendices include a sample Net e!! program2 a description o+ an e!perimental +eature2 and some details o+ the contents o+ the netrexx.lang package5

Language objectives
&his document describes a programming language2 called Net e!!2 which is derived +rom both e!! and 3ava5 Net e!! is intended as a dialect o+ e!! that can be as e++icient and portable as languages such as 3ava2 while preserving the low threshold to learning and the ease o+ use o+ the original e!! language5

Features of Rexx
&he e!! programming language: was designed with just one objective7 to make programming easier than it was be+ore5 &he design achieved this b% emphasi=ing readabilit% and usabilit%2 with a minimum o+ special notations and restrictions5 It was consciousl% designed to make li+e easier +or its users2 rather than +or its implementers5 /ne important +eature o+ e!! s%nta! is keyword sa#ety5 $rogramming languages invariabl% need to
: Cowlishaw2 M5 652 !"e R%&& Language -second edition.2 I(BN >1:<1?@>AB:1B2 $rentice1,all2 :CC>5 Introduction 7

Version 2.00

evolve over time as the needs and e!pectations o+ their users change2 so this is an essential re8uirement +or languages that are intended to be e!ecuted +rom source5 Ke%words in e!! are not globall% reserved but are recogni=ed onl% in conte!t5 &his language attribute has allowed the language to be e!tended substantiall% over the %ears without invalidating e!isting programs5 "ven so2 some areas o+ e!! have proved di++icult to e!tend 9 +or e!ample2 ke%words are reserved within instructions such as do5 &here+ore2 the design +or Net e!! takes the concept o+ ke%word sa+et% even +urther than in e!!2 and also improves e!tensibilit% in other areas5 &he great strengths o+ e!! are its human1oriented +eatures2 including simplicit% coherent and uncluttered s%nta! comprehensive string handling case1insensitivit% arbitrar% precision decimal arithmetic5 Care has been taken to preserve these5 Conversel%2 its interpretive nature has alwa%s entailed a lack o+ e++icienc%7 e!cellent e!! compilers do e!ist2 +rom IBM and other companies2 but cannot o++er the +ull speed o+ staticall%1scoped languages such as C ; or 3ava5 <

Influence of Java
&he s%stem1independent design o+ e!! makes it an obvious and natural +it to a s%stem1independent e!ecution environment such as that provided b% the 3ava 0irtual Machine -30M.5 &he 30M2 especiall% when enhanced with Djust1in1timeE b%tecode compilers that compile b%tecodes into native code just be+ore e!ecution2 o++ers an e++ective and attractive target environment +or a language like e!!5 Choosing the 30M as a target environment does2 however2 place signi+icant constraints on the design o+ a language suitable +or that environment5 6or e!ample2 the semantics o+ method invocation are in several wa%s determined b% the environment rather than b% the source language2 and2 to a large e!tent2 the object model -class structure2 et$.. o+ the 3ava environment is imposed on languages that use it5 Also2 3ava maintains the C concept o+ primitive datat%pesF t%pes -such as int2 a <;1bit signed integer. which allow e++icient use o+ the underl%ing hardware %et do not describe true objects5 &hese t%pes are pervasive in classes and inter+aces written in the 3ava languageF an% language intending to use 3ava classes e++ectivel% must provide access to these t%pes5 "8uall%2 the e%$eption -error handling. model o+ 3ava is pervasive2 to the e!tent that methods must check certain e!ceptions and declare those that are not handled within the method5 &his makes it di++icult to +it an alternative e!ception model5 &he constraints o+ sa+et%2 e++icienc%2 and environment necessitated that Net e!! would have to di++er in some details o+ s%nta! and semantics +rom e!!F unlike /bject e!!2 it could not be a +ull% upwards1compatible e!tension o+ the language5 G &he need +or changes2 however2 o++ered the opportunit% to make some signi+icant simpli+ications and enhancements to the language2 both to
; < G Kernighan2 B5 *52 and itchie2 #5 M52 !"e Programming Language -second edition.2 I(BN >1:<1::><A;1@2 $rentice1 ,all2 :C@@5 )osling2 35 A52 et al. !"e Java Language Specification2 I(BN >1;>:1A<GB:1:2 Addison1*esle%2 :CCA5 Nash2 (5 C52 O'(ect)Oriented R%&& in )oldberg2 )2 and (mith2 $5 ,5 III2 !"e Rexx *and'oo$2 pp::B1:;B2 I(BN >1 >?1>;<A@;1@2 Mc)raw1,ill2 Inc52 New Hork2 :CC;5 Introduction Version 2.00

improve its ke%word sa+et% and to strengthen other +eatures o+ the original e!! design5B (ome additions +rom /bject e!! and AN(I e!! A are also included5 (imilarl%2 the concepts and philosoph% o+ the e!! design can pro+itabl% be applied to avoid man% o+ the minor irregularities that characteri=e the C and 3ava language +amil%2 b% providing suitable simpli+ications in the programming model5 6or e!ample2 the Net e!! looping construct has onl% one +orm2 rather than three2 and e!ception handling can be applied to all blocks rather than re8uiring an e!tra construct5 Also2 as in e!!2 all Net e!! storage allocation and de1allocation is implicit 9 an e!plicit new operator is not re8uired5 6urther2 the human1oriented design +eatures o+ e!! -case1insensitivit% +or identi+iers2 t%pe deduction +rom conte!t2 automatic conversions where sa+e2 tracing2 and a strong emphasis on string representations o+ common values and numbers. make programming +or the 3ava environment especiall% eas% in Net e!!5

A hybrid or a whole?
As in other mi!tures2 not all blends are a successF when +irst designing Net e!!2 it was not at all obvious whether the new language would be an improvement on its parents2 or would simpl% re+lect the worst +eatures o+ both5 &he +ulcrum o+ the design is perhaps the wa% in which datat%ping is automated without losing the static t%ping supported b% 3ava5 &%ping in Net e!! is most apparent at inter+aces 9 where it provides most value 9 but within methods it is subservient and does not obscure algorithms5 A simple concept2 &inary $lasses2 also lets the programmer choose between robust decimal arithmetic and less sa+e -but +aster. binar% arithmetic +or advanced programming where per+ormance is a primar% consideration5 &he DseamlessE integration o+ t%pes into what was previousl% an essentiall% t%peless language does seem to have been a success2 o++ering the advantages o+ strong t%ping while preserving the ease o+ use and speed o+ development that e!! programmers have enjo%ed5 &he end result o+ adding 3ava t%ping capabilities to the e!! language is a single language that has both the e!! strengths +or scripting and +or writing macros +or applications and the 3ava strengths o+ robustness2 good e++icienc%2 portabilit%2 and securit% +or application development5

B A

(ee Cowlishaw2 M5 652 !"e %arl+ *i,tor+ of R%&&2 I''' !nnals o# the (istory o# Co)p*ting2 I((N :>B@1A:@>2 0ol :A2 No5 G2 *inter :CCG2 pp:B1;G2 and Cowlishaw2 M5 652 !"e -uture of Rexx2 Pro$eedings o# +inter 199, Meeting-.(!/' 002 0olume II2 p5;?>C2 (,A " Inc52 Chicago2 :CC<5 (ee American National Standard for Information !ec"nolog+ Programming Language R%&&2 I<5;?G1:CCA2 American National (tandards Institute2 New Hork2 :CCA5 Introduction 9

Version 2.00

Language concepts
As described in the last section2 Net e!! was created b% appl%ing the philosoph% o+ the e!! language to the semantics re8uired +or programming the 3ava 0irtual Machine -30M.5 #espite the assumption that the 30M is a Dtarget environmentE +or Net e!!2 it is intended that the language not be environment1dependentF the essentials o+ the language do not depend on the 30M5 "nvironment1 dependent details2 such as the primitive t%pes supported2 are not part o+ the language speci+ication5 &he primar% concepts o+ e!! have been described be+ore2 in 1he /e%% 2ang*age2 but it is worth repeating them and also indicating where modi+ications and additions have been necessar% to support the concepts o+ staticall%1t%ped and object1oriented environments5 &he remainder o+ this section is there+ore a summar% o+ the principal concepts o+ Net e!!5

Readability
/ne concept was central to the evolution o+ e!! s%nta!2 and hence Net e!! s%nta!7 reada&ility -used here in the sense o+ perceived legibilit%.5 eadabilit% in this sense is a somewhat subjective 8ualit%2 but the general principle +ollowed is that the tokens which +orm a program can be written much as one might write them in *estern "uropean languages -"nglish2 6rench2 and so +orth.5 Although Net e!! is more +ormal than a natural language2 its s%nta! is le!icall% similar to ever%da% te!t5 &he structure o+ the s%nta! means that the language is readil% adapted to a variet% o+ programming st%les and la%outs5 &his helps satis+% user pre+erences and allows a le!ical +amiliarit% that also increases readabilit%5 )ood readabilit% leads to enhanced understandabilit%2 thus %ielding +ewer errors both while writing a program and while reading it +or in+ormation2 debugging2 or maintenance5 Important +actors here are7 :5 $unctuation and other special notations are re8uired onl% when absolutel% necessar% to remove ambiguit% -though punctuation ma% o+ten be added according to personal pre+erence2 so long as it is s%ntacticall% correct.5 *here notations are used2 the% +ollow established conventions5 ;5 &he language is essentiall% case1insensitive5 A Net e!! programmer ma% choose a st%le o+ use o+ uppercase and lowercase letters that he or she +inds most help+ul -rather than a st%le chosen b% some other programmer.5 <5 &he classical constructs o+ structured and object1oriented programming are available in Net e!!2 and can undoubtedl% lead to programs that are easier to read than the% might otherwise be5 &he simplicit% and small number o+ constructs also make Net e!! an e!cellent language +or teaching the concepts o+ good structure5 G5 Loose binding between the ph%sical lines in a program and the s%nta! o+ the language ensures that even though programs are a++ected b% line ends2 the% are not irrevocabl% so5 A clause ma% be spread over several lines or put on just one lineF this +le!ibilit% helps a programmer la% out the program in the st%le +elt to be most readable5

Natural data typing and decimal arithmetic

D(trong t%pingE2 in which the values that a variable ma% take are tightl% constrained2 has been an attribute o+ some languages +or man% %ears5 &he greatest advantage o+ strong t%ping is +or the inter+aces between program modules2 where errors are eas% to introduce and di++icult to catch5 "rrors within modules that would be detected b% strong t%ping -and which would not be detected +rom conte!t. are much rarer2 certainl% when compared with design errors2 and in the majorit% o+ cases do
10 Introduction Version 2.00

not justi+% the added program comple!it%5 Net e!!2 there+ore2 treats t%pes as unobtrusivel% as possible2 with a simple s%nta! +or t%pe description which makes it eas% to make t%pes e!plicit at inter+aces -+or e!ample2 when describing the arguments to methods.5 B% de+ault2 common values -identi+iers2 numbers2 and so on. are described in the +orm o+ the s%mbolic notation -strings o+ characters. that a user would normall% write to represent those values5 &his natural datat%pe +or values also supports decimal arithmetic +or numbers2 so2 +rom the user's perspective2 numbers look like and are manipulated as strings2 just as the% would be in ever%da% use on paper5 *hen dealing with values in this wa%2 no internal or machine representation o+ characters or numbers is e!posed in the language2 and so the need +or man% data t%pes is reduced5 &here are2 +or e!ample2 no +undamentall% di++erent concepts o+ integer and realF there is just the single concept o+ n*)&er5 &he results o+ all operations have a de+ined s%mbolic representation2 and will there+ore act consistentl% and predictabl% +or ever% correct implementation5 &his concept also underlies the BA(IC ? languageF indeed2 Kemen% and Kurt='s vision +or BA(IC included man% o+ the +undamental principles that inspired e!!5 6or e!ample2 &homas "5 Kurt= wrote7 D egarding variable t%pes2 we +elt that a distinction between J+i!ed' and J+loating' was less justi+ied in :CAG than earlier 555 to our potential audience the distinction between an integer number and a non1integer number would seem esoteric5 A number is a number is a number5E@ 6or e!!2 intended as a scripting language2 this approach was idealF s%mbolic operations were all that were necessar%5 6or Net e!!2 however2 it is recogni=ed that +or some applications it is necessar% to take +ull advantage o+ the per+ormance o+ the underl%ing environment2 and so the language allows +or the use and speci+ication o+ binar% arithmetic and t%pes2 i+ available5 A ver% simple mechanism -declaring a class or method to be &inary. is provided to indicate to the language processor that binar% arithmetic and t%pes are to be used where applicable5 In this case2 as in other languages2 e!tra care has to be taken b% the programmer to avoid e!ceeding limits o+ number si=e and so on5

Emphasis on symbolic manipulation

Man% values that Net e!! manipulates are -+rom the user's point o+ view2 at least. in the +orm o+ strings o+ characters5 $roductivit% is greatl% enhanced i+ these strings can be handled as easil% as manipulating words on a page or in a te!t editor5 Net e!! there+ore has a rich set o+ character manipulation operators and methods2 which operate on values o+ t%pe Rexx -the name o+ the class o+ Net e!! strings.5 Concatenation2 the most common string operation2 is treated speciall% in Net e!!5 In addition to a conventional concatenate operator -D||E.2 the novel &lank operator +rom e!! concatenates two data strings together with a blank in between5 6urthermore2 i+ two s%ntacticall% distinct terms -such as a string and a variable name. are abutted2 then the data strings are concatenated directl%5 &hese operators make it especiall% eas% to build up comple! character strings2 and ma% at an% time be combined with the other operators5
? @ Kemen%2 35 )5 and Kurt=2 &5 "52 BASI programming2 3ohn *ile% K (ons Inc52 New Hork2 :CA?5 Kurt=2 &5 "52 BASI in *e!elblat2 5 L5 -"d.2 *i,tor+ of Programming Language,2 I(BN >1:;1?GB>G>1@2 Academic $ress2 New Hork :C@:5 Introduction 11

Version 2.00

6or e!ample2 the say instruction consists o+ the ke%word say +ollowed b% an% e!pression5 In this instance o+ the instruction2 i+ the variable n has the value D6E then
say 'Sorry,' n*100/50'% were rejected'

would displa% the string

Sorry, 12% were rejected

Concatenation has a lower priorit% than the arithmetic operators5 &he order o+ evaluation o+ the e!pression is there+ore +irst the multiplication2 then the division2 then the concatenate1with1blank2 and +inall% the direct concatenation5 (ince the concatenation operators are distinct +rom the arithmetic operators2 ver% natural coercion -automatic conversion. between numbers and character strings is possible5 6urther2 e!plicit t%pe1 casting -conversion o+ t%pes. is e++ected b% the same operators2 at the same priorit%2 making +or a ver% natural and consistent s%nta! +or changing the t%pes o+ results5 6or e!ample2
i=int 100/7

would calculate the result o+ 100 divided b% 72 convert that result to an integer -assuming int describes an integer t%pe. and then assign it to the variable i5

Nothing to declare
Consistent with the philosoph% o+ simplicit%2 Net e!! does not re8uire that variables within methods be declared be+ore use5 /nl% the propertiesC o+ classes 9 which ma% +orm part o+ their inter+ace to other classes 9 need be listed +ormall%5 *ithin methods2 the t%pe o+ variables is deduced staticall% +rom conte!t2 which saves the programmer the menial task o+ stating the t%pe e!plicitl%5 /+ course2 i+ pre+erred2 variables ma% be listed and assigned a t%pe at the start o+ each method5

Environment independence
&he core Net e!! language is independent o+ both operating s%stems and hardware5 Net e!! programs2 though2 must be able to interact with their environment2 which implies some dependence on that environment -+or e!ample2 binar% representations o+ numbers ma% be re8uired.5 Certain areas o+ the language are there+ore described as being de+ined b% the environment5 *here environment1independence is de+ined2 however2 there ma% be a loss o+ e++icienc% 9 though this can usuall% be justi+ied in view o+ the simplicit% and portabilit% gained5 As an e!ample2 character string comparison in Net e!! is normall% independent o+ case and o+ leading and trailing blanks5 -&he string D Hes E )eans the same as D%esE in most applications5. ,owever2 the in+luence o+ underl%ing hardware has o+ten subtl% a++ected this kind o+ design decision2 so that man% languages onl% allow trailing blanks but not leading blanks2 and insist on e!act case matching5 B% contrast2 Net e!! provides the human1oriented rela!ed comparison +or strings as de+ault2 with optional Dstrict comparisonE operators5

Limited span syntactic units

&he +undamental unit o+ s%nta! in the Net e!! language is the clause2 which is a piece o+ program te!t terminated b% a semicolon -usuall% implied b% the end o+ a line.5 &he span o+ s%ntactic units is
C 12 Class variables and instance variables5 Introduction Version 2.00

there+ore small2 usuall% one line or less5 &his means that the s%nta! parser in the language processor can rapidl% detect and locate errors2 which in turn means that error messages can be both precise and concise5 It is di++icult to provide good diagnostics +or languages -such as $ascal and its derivatives. that have large +undamental s%ntactic units5 6or these languages2 a small error can o+ten have a major or distributed e++ect on the parser2 which can lead to multiple error messages or even misleading error messages5

Dealing with reality

A computer language is a tool +or use b% real people to do real work5 An% tool must2 above all2 be reliable5 In the case o+ a language this means that it should do what the user e!pects5 User e!pectations are generall% based on prior e!perience2 including the use o+ various programming and natural languages2 and on the human abilit% to abstract and generali=e5 It is di++icult to de+ine e!actl% how to meet user e!pectations2 but it helps to ask the 8uestion DCould there be a high astonish)ent #a$tor associated with this +eatureLE5 I+ a +eature2 accidentall% misused2 gives apparentl% unpredictable results2 then it has a high astonishment +actor and is there+ore undesirable5 Another important attribute o+ a reliable so+tware tool is $onsisten$y5 A consistent language is b% de+inition predictable and is o+ten elegant5 &he danger here is to assume that because a rule is consistent and easil% described2 it is there+ore simple to understand5 Un+ortunatel%2 some o+ the most elegant rules can lead to e++ects that are completel% alien to the intuition and e!pectations o+ a user who2 a+ter all2 is human5 &hese constraints make programming language design more o+ an art than a science2 i+ the usabilit% o+ the language is a primar% goal5 &he problems are +urther compounded +or Net e!! because the language is suitable +or both scripting -where rapid development and ease o+ use are paramount. and +or application development -where some programmers pre+er e!tensive checking and redundant coding.5 &hese con+licting goals are balanced in Net e!! b% providing automatic handling o+ man% tasks -such as conversions between di++erent representations o+ strings and numbers. %et allowing +or DstrictE options which2 +or e!ample2 ma% re8uire that all t%pes be e!plicit2 identi+iers be identical in case as well as spelling2 and so on5

Be adaptable
*herever possible Net e!! allows +or the e!tension o+ instructions and other language constructs2 building on the e!perience gained with e!!5 6or e!ample2 there is a use+ul set o+ common characters available +or +uture use2 since onl% small set is used +or the +ew special notations in the language5 (imilarl%2 the rules +or ke%word recognition allow instructions to be added whenever re8uired without compromising the integrit% o+ e!isting programs5 &here are no reserved ke%words in Net e!!F variable names chosen b% a programmer alwa%s take precedence over recognition o+ ke%words5 &his ensures that Net e!! programs ma% sa+el% be e!ecuted2 +rom source2 at a time or place remote +rom their original writing 9 even i+ in the meantime new ke%words have been added to the language5 A language needs to be adaptable because it $ertainly will &e *sed #or appli$ations not #oreseen &y the designer5 Like all programming languages2 Net e!! ma% -indeed2 probabl% will. prove inade8uate +or certain +uture applicationsF room +or e!pansion and change is included to make the language more adaptable and robust5

Version 2.00

Introduction

13

Keep the language small

Net e!! is designed as a small language5 It is not the sum o+ all the +eatures o+ e!! and o+ 3avaF rather2 unnecessar% +eatures have been omitted5 &he intention has been to keep the language as small as possible2 so that users can rapidl% grasp most o+ the language5 &his means that7 the language appears less +ormidable to the new user documentation is smaller and simpler the e!perienced user can be aware o+ all the abilities o+ the language2 and so has the whole tool at his or her disposal there are +ew e!ceptions2 special cases2 or rarel% used embellishments the language is easier to implement5 Man% languages have accreted DneatE +eatures which make certain algorithms easier to e!pressF anal%sis shows that man% o+ these are rarel% used5 As a rough rule1o+1thumb2 +eatures that simpl% provided alternative wa%s o+ writing code were added to e!! and Net e!! onl% i+ the% were likel% to be used more o+ten than once in +ive thousand clauses5

No defined size or shape limits

&he language does not de+ine limits on the si=e or shape o+ an% o+ its tokens or data -although there ma% be implementation restrictions.5 It does2 however2 de+ine a +ew )ini)*) re8uirements that must be satis+ied b% an implementation5 *herever an implementation restriction has to be applied2 it is recommended that it should be o+ such a magnitude that +ew -i+ an%. users will be a++ected5 *here arbitrar% implementation limits are necessar%2 the language re8uires that the implementer use +amiliar and memorable decimal values +or the limits5 6or e!ample ;B> would be used in pre+erence to ;BB2 B>> to B:;2 and so on5

14

Introduction

Version 2.00

Acknowledgements
Much o+ Net e!! is based on earlier work2 and I am indebted to the hundreds o+ people who contributed to the development o+ e!!2 /bject e!!2 and 3ava5 In the :CC>s I gained man% insights +rom the deliberations o+ the members o+ the I<3:@ technical committee2 which2 under the remarkable chairmanship o+ Brian Marks2 led to the :CCA AN(I (tandard +or e!!5 Man% o+ the committee's suggestions are incorporated in Net e!!5 "8uall% important have been the comments and +eedback +rom the pioneering users o+ Net e!!2 and all those people who sent me comments on the language either directl% or in the Net e!! mailing list or +orum5 I would especiall% like to thank Ian Brackenbur%2 Barr% 6eigenbaum2 #avis 6oulger2 Norio 6urukawa2 #ion )illard2 Martin La+ai!2 Ma! Marsiglietti2 and &revor &urton +or their insight+ul comments and encouragement5 I also thank IBMF m% appointment as an IBM 6ellow made it possible to make the implementation o+ Net e!! a realit% in months rather than %ears5 6inall%2 this document has relied on old but trusted technolog% +or its creation7 its )ML markup was processed using macros originall% written b% Bob /',ara2 and +ormatted using (C I$&M0(2 the IBM #ocument Composition 6acilit%5 )eo++ Bartlett provided critical advice on character sets and +onts +or the Net e!! book5 &his version2 +or Net e!! ;2 uses a set o+ e!! programs that convert that same )ML markup into /pen/++ice #ocument &e!t +ormat -IML +iles.5 Mike Cowlishaw, 1997 and 2009

Version 2.00

Introduction

15

NetRexx Overview
&his part o+ the document summari=es the main +eatures o+ Net e!!2 and is intended to help %ou start using the language 8uickl%5 It is assumed that %ou have some knowledge o+ programming in a language such as e!!2 C2 BA(IC2 or 3ava2 but a knowledge o+ Dobject1orientedE programming is not needed5 &his is not a complete tutorial2 however 9 think o+ it more as a DtasterEF it covers the main points o+ the language and shows some e!amples %ou can tr% or modi+%5 6or +ull details o+ the language2 consult the third part o+ this document2 the 3et/e%% 2ang*age 4e#inition -see page <?.5

Version 2.00

NetRexx Overview

17

NetRexx programs
&he structure o+ a Net e!! program is e!tremel% simple5 &his sample program2 DtoastE2 is complete2 documented2 and e!ecutable as it stands7
/* This wishes you the best of health. */ say 'Cheers!'

&his program consists o+ two lines7 the +irst is an optional comment that describes the purpose o+ the program2 and the second is a say instruction5 say simpl% displa%s the result o+ the e!pression +ollowing it 9 in this case just a literal string -%ou can use either single or double 8uotes around strings2 as %ou pre+er.5 &o run this program using the re+erence implementation o+ Net e!!2 create a +ile called toast.nrx and cop% or paste the two lines above into it5 Hou can then use the NetRexxC 3ava program to compile it7
java COM.ibm.netrexx.process.NetRexxC toast

-this should create a +ile called toast.class.2 and then use the java command to run it7
java toast

Hou ma% also be able to use the netrexxc or nrc command to compile and run the program with a single command -details ma% var% 9 see the installation and user's guide document +or %our implementation o+ Net e!!.7
netrexxc toast -run

/+ course2 Net e!! can do more than just displa% a character string5 Although the language has a simple s%nta!2 and has a small number o+ instruction t%pes2 it is power+ulF the re+erence implementation o+ the language allows +ull access to the rapidl% growing collection o+ 3ava programs known as $lass li&raries2 and allows new class libraries to be written in Net e!!5 &he rest o+ this overview introduces most o+ the +eatures o+ Net e!!5 (ince the econom%2 power2 and clarit% o+ e!pression in Net e!! is best appreciated with use2 %ou are urged to tr% using the language %oursel+5

18

NetRexx Overview

Version 2.00

Expressions and variables

Like say in the DtoastE e!ample2 man% instructions in Net e!! include e%pressions that will be evaluated5 Net e!! provides arithmetic operators -including integer division2 remainder2 and power operators.2 several concatenation operators2 comparison operators2 and logical operators5 &hese can be used in an% combination within a Net e!! e!pression -provided2 o+ course2 that the data values are valid +or those operations.5 All the operators act upon strings o+ characters -known as 3et/e%% strings.2 which ma% be o+ an% length -t%picall% limited onl% b% the amount o+ storage available.5 Nuotes -either single or double. are used to indicate literal strings2 and are optional i+ the literal string is just a number5 6or e!ample2 the e!pressions7
'2' + '3' '2' + 3 2 + 3

would all result in '5'5 &he results o+ e!pressions are o+ten assigned to "aria&les2 using a conventional assignment s%nta!7
var1=5 var2=(var1+2)*10 /* sets var1 to '5' */ /* sets var2 to '70' */

Hou can write the names o+ variables -and ke%words. in whatever mi!ture o+ uppercase and lowercase that %ou pre+erF the language is not case1sensitive5 &his ne!t sample program2 DgreetE2 shows e!pressions used in various wa%s7
/* greet.nrx -- a short program to greet you. */ /* First display a prompt: */ say 'Please type your name and then press Enter:' answer=ask /* Get the reply into 'answer' */ /* If no name was entered, then use a fixed /* greeting, otherwise echo the name politely. if answer='' then say 'Hello Stranger!' else say 'Hello' answer'!' */ */

A+ter displa%ing a prompt2 the program reads a line o+ te!t +rom the user -DaskE is a ke%word provided b% Net e!!. and assigns it to the variable answer5 &his is then tested to see i+ an% characters were entered2 and di++erent actions are taken accordingl%F +or e!ample2 i+ the user t%ped DFredE in response to the prompt2 then the program would displa%7
Hello Fred!

As %ou see2 the e!pression on the last say -displa%. instruction concatenated the string DHelloE to the value o+ variable answer with a blank in between them -the blank is here a valid operator2 meaning Dconcatenate with blankE.5 &he string D!E is then directl% concatenated to the result built up so +ar5 &hese unobtrusive operators -the &lank operator and abuttal. +or concatenation are ver% natural and eas% to use2 and make building te!t strings simple and clear5 &he la%out o+ instructions is ver% +le!ible5 In the DgreetE e!ample2 +or instance2 the if instruction could be laid out in a number o+ wa%s2 according to personal pre+erence5 Line breaks can be added at either side o+ the then -or +ollowing the else.5

Version 2.00

NetRexx Overview

19

In general2 instructions are ended b% the end o+ a line5 &o continue a instruction to a +ollowing line2 %ou can use a h%phen -minus sign. just as in "nglish7
say 'Here we have an expression that is quite long,' 'so it is split over two lines'

&his acts as though the two lines were all on one line2 with the h%phen and an% blanks around it being replaced b% a single blank5 &he net result is two strings concatenated together -with a blank in between. and then displa%ed5 *hen desired2 multiple instructions can be placed on one line with the aid o+ the semicolon separator7
if answer='Yes' then do; say 'OK!'; exit; end

-man% people +ind multiple instructions on one line hard to read2 but sometimes it is convenient.5

20

NetRexx Overview

Version 2.00

Control instructions
Net e!! provides a selection o+ $ontrol instructions2 whose +orm was chosen +or readabilit% and similarit% to natural languages5 &he control instructions include if555 then555 else -as in the DgreetE e!ample. +or simple conditional processing7
if ask='Yes' then say "You answered Yes" else say "You didn't answer Yes" select555 when555 otherwise555 end +or selecting +rom a number o+ alternatives7 select when a>0 then say 'greater than zero' when a<0 then say 'less than zero' otherwise say 'zero' end select when when when end case i+1 1 then say 'one' 1+1 then say 'two' 3, 4, 5 then say 'many'

do555 end +or grouping7 if a>3 then do say 'A is greater than 3; it will be set to zero' a=0 end

and loop555 end +or repetition7

/* repeat 10 times; I changes from 1 to 10 */ loop i=1 to 10 say i end i

&he loop instruction can be used to step a variable to some limit2 by some increment2 for a speci+ied number o+ iterations2 and while or until some condition is satis+ied5 loop forever is also provided2 and loop over can be used to work through a collection o+ variables5 Loop e!ecution ma% be modi+ied b% leave and iterate instructions that signi+icantl% reduce the comple!it% o+ man% programs5 &he select2 do2 and loop constructs also have the abilit% to DcatchE e!ceptions -see page <B. that occur in the bod% o+ the construct5 All three2 too2 can speci+% a finally instruction which introduces instructions which are to be e!ecuted when control leaves the construct2 regardless o+ how the construct is ended5

Version 2.00

NetRexx Overview

21

NetRexx arithmetic
Character strings in Net e!! are commonl% used +or arithmetic -assuming2 o+ course2 that the% represent numbers.5 &he string representation o+ numbers can include integers2 decimal notation2 and e!ponential notationF the% are all treated the same wa%5 ,ere are a +ew7
'1234' '12.03' '-12' '120e+7'

&he arithmetic operations in Net e!! are designed +or people rather than machines2 so are decimal rather than binar%2 do not over+low at certain values2 and +ollow the rules that people use +or arithmetic5 &he operations are completel% de+ined b% the AN(I I<5;?G standard +or e!!2 so correct implementations alwa%s give the same results5 An unusual +eature o+ Net e!! arithmetic is the numeric instruction7 this ma% be used to select the ar&itrary pre$ision o+ calculations5 Hou ma% calculate to whatever precision that %ou wish -+or +inancial calculations2 perhaps.2 limited onl% b% available memor%5 6or e!ample7
numeric digits 50 say 1/7

which would displa%

0.14285714285714285714285714285714285714285714285714

&he numeric precision can be set +or an entire program2 or be adjusted at will within the program5 &he numeric instruction can also be used to select the notation -s$ienti#i$ or engineering. used +or numbers in e!ponential +ormat5 Net e!! also provides simple access to the native binar% arithmetic o+ computers5 Using binar% arithmetic o++ers man% opportunities +or errors2 but is use+ul when per+ormance is paramount5 Hou select binar% arithmetic b% adding the instruction7
options binary

at the top o+ a Net e!! program5 &he language processor will then use binar% arithmetic -see page <<. instead o+ Net e!! decimal arithmetic +or calculations2 i+ it can2 throughout the program5

22

NetRexx Overview

Version 2.00

Doing things with strings

A character string is the +undamental datat%pe o+ Net e!!2 and so2 as %ou might e!pect2 Net e!! provides man% use+ul routines +or manipulating strings5 &hese are based on the +unctions o+ e!!2 but use a s%nta! that is more like 3ava or other similar languages7
phrase='Now is the time for a party' say phrase.word(7).pos('r')

&he second line here can be read +rom le+t to right as7 take the variable phrase2 +ind the seventh word2 and then +ind the position o+ the +irst DrE in that word5 &his would displa% D3E in this case2 because DrE is the third character in DpartyE5 -In e!!2 the second line above would have been written using nested +unction calls7
say pos('r', word(phrase, 7))

which is not as eas% to readF %ou have to +ollow the nesting and then backtrack +rom right to le+t to work out e!actl% what's going on5. In the Net e!! s%nta!2 at each point in the se8uence o+ operations some routine is acting on the result o+ what has gone be+ore5 &hese routines are called )ethods2 to make the distinction +rom +unctions -which act in isolation.5 Net e!! provides -as methods. most o+ the +unctions that were evolved +or e!!2 including7 changestr -change all occurrences o+ a substring to another. copies -make multiple copies o+ a string. lastpos -+ind rightmost occurrence. left and right -return le+tmostMrightmost character-s.. pos and wordpos -+ind the position o+ string or a word in a string. reverse -swap end1to1end. space -pad between words with +i!ed spacing. strip -remove leading andMor trailing white space. verify -check the contents o+ a string +or selected characters. word2 wordindex2 wordlength2 and words -work with words.5 &hese and the others like them2 and the parsing described in the ne!t section2 make it especiall% eas% to process te!t with Net e!!5

Version 2.00

NetRexx Overview

23

Parsing strings
&he previous section described some o+ the string1handling +acilities availableF Net e!! also provides string parsing2 which is an eas% wa% o+ breaking up strings o+ characters using simple pattern matching5 A parse instruction +irst speci+ies the string to be parsed5 &his can be an% term2 but is o+ten taken simpl% +rom a variable5 &he term is +ollowed b% a te)plate which describes how the string is to be split up2 and where the pieces are to be put5

Parsing into words

&he simplest +orm o+ parsing template consists o+ a list o+ variable names5 &he string being parsed is split up into words -se8uences o+ characters separated b% blanks.2 and each word +rom the string is assigned -copied. to the ne!t variable in turn2 +rom le+t to right5 &he +inal variable is treated speciall% in that it will be assigned a cop% o+ whatever is le+t o+ the original string and ma% there+ore contain several words5 6or e!ample2 in7
parse 'This is a sentence.' v1 v2 v3

the variable v1 would be assigned the value DThisE2 v2 would be assigned the value DisE2 and v3 would be assigned the value Da sentence.E5

Literal patterns
A literal string ma% be used in a template as a pattern to split up the string5 6or e!ample
parse 'To be, or not to be?' w1 ',' w2 w3 w4

would cause the string to be scanned +or the comma2 and then split at that pointF each section is then treated in just the same wa% as the whole string was in the previous e!ample5 &hus2 w1 would be set to DTo beE2 w2 and w3 would be assigned the values DorE and DnotE2 and w4 would be assigned the remainder7 Dto be?E5 Note that the pattern itsel+ is not assigned to an% variable5 &he pattern ma% be speci+ied as a variable2 b% putting the variable name in parentheses5 &he +ollowing instructions7
comma=',' parse 'To be, or not to be?' w1 (comma) w2 w3 w4

there+ore have the same e++ect as the previous e!ample5

Positional patterns
&he third kind o+ parsing mechanism is the numeric positional pattern5 &his allows strings to be parsed using column positions5

24

NetRexx Overview

Version 2.00

Indexed strings
Net e!! provides inde!ed strings2 adapted +rom the compound variables o+ e!!5 Inde!ed strings +orm a power+ul Dassociative lookupE2 or di$tionary2 mechanism which can be used with a convenient and simple s%nta!5 Net e!! string variables can be re+erred to simpl% b% name2 or also b% their name 8uali+ied b% another string -the inde%.5 *hen an inde! is used2 a value associated with that inde! is either set7
fred=0 fred[3]='abc' -- initial value -- indexed value

or retrieved7
say fred[3] -- would say "abc"

in the latter case2 the simple -initial. value o+ the variable is returned i+ the inde! has not been used to set a value5 6or e!ample2 the program7
bark='woof' bark['pup']='yap' bark['bulldog']='grrrrr' say bark['pup'] bark['terrier'] bark['bulldog']

would displa%
yap woof grrrrr

Note that it is not necessar% to use a number as the inde!F an% e!pression ma% be used inside the bracketsF the resulting string is used as the inde!5 Multiple dimensions ma% be used2 i+ re8uired7
bark='woof' bark['spaniel', 'brown']='ruff' bark['bulldog']='grrrrr' animal='dog' say bark['spaniel', 'brown'] bark['terrier'] bark['bull'animal]

which would displa%

ruff woof grrrrr

,ere's a more comple! e!ample using inde!ed strings2 a test program with a +unction -called a stati$ )ethod in Net e!!. that removes all duplicate words +rom a string o+ words7
/* justonetest.nrx -- test the justone function. */ say justone('to be or not to be') /* simple testcase */ exit /* This removes duplicate words from a string, and /* shows the use of a variable (HADWORD) which is /* indexed by arbitrary data (words). method justone(wordlist) static hadword=0 /* show all possible words as new outlist='' /* initialize the output list loop while wordlist\='' /* loop while we have data /* split WORDLIST into first word and residue parse wordlist word wordlist if hadword[word] then iterate /* loop if had word hadword[word]=1 /* remember we have had this word outlist=outlist word /* add word to output list end return outlist /* finally return the result */ */ */ */ */ */ */ */ */ */ */

unning this program would displa% just the +our words DtoE2 DbeE2 DorE2 and DnotE5
Version 2.00 NetRexx Overview 25

Arrays
Net e!! also supports +i!ed1si=e arrays5 &hese are an ordered set o+ items2 inde!ed b% integers5 &o use an arra%2 %ou +irst have to construct itF an individual item ma% then be selected b% an inde! whose value must be in the range 0 through n-12 where n is the number o+ items in the arra%7
array=String[3] -- make an array of three Strings array[0]='String one' -- set each array item array[1]='Another string' array[2]='foobar' loop i=0 to 2 -- display the items say array[i] end

&his e!ample also shows Net e!! line $o))entsF the se8uence D--E -outside o+ literal strings or D/*E comments. indicates that the remainder o+ the line is not part o+ the program and is commentar%5 Net e!! makes it eas% to initiali=e arra%s7 a term which is a list o+ one or more e!pressions2 enclosed in brackets2 de+ines an arra%5 "ach e!pression initiali=es an element o+ the arra%5 6or e!ample7
words=['Ogof', 'Ffynnon', 'Ddu']

would set words to re+er to an arra% o+ three elements2 each re+erring to a string5 (o2 +or e!ample2 the instruction7
say words[1]

would then displa% Ffynnon5

26

NetRexx Overview

Version 2.00

Things that arent strings

In all the e!amples so +ar2 the data being manipulated -numbers2 words2 and so on. were e!pressed as a string o+ characters5 Man% things2 however2 can be e!pressed more easil% in some other wa%2 so Net e!! allows variables to re+er to other collections o+ data2 which are known as o&5e$ts5 /bjects are de+ined b% a name that lets Net e!! determine the data and methods that are associated with the object5 &his name identi+ies the t%pe o+ the object2 and is usuall% called the $lass o+ the object5 6or e!ample2 an object o+ class /blong might represent an oblong to be manipulated and displa%ed5 &he oblong could be de+ined b% two values7 its width and its height5 &hese values are called the properties o+ the /blong class5 Most methods associated with an object per+orm operations on the objectF +or e!ample a size method might be provided to change the si=e o+ an /blong object5 /ther methods are used to construct objects -just as +or arra%s2 an object must be constructed be+ore it can be used.5 In Net e!! and 3ava2 these $onstr*$tor methods alwa%s have the same name as the class o+ object that the% build -D/blongE2 in this case.5 ,ere's how an /blong class might be written in Net e!! -b% convention2 this would be written in a +ile called Oblong.nrxF implementations o+ten e!pect the name o+ the +ile to match the name o+ the class inside it.7
/* Oblong.nrx -- simple oblong class */ class Oblong width -- size (X dimension) height -- size (Y dimension) /* Constructor method to make a new oblong */ method Oblong(newwidth, newheight) -- when we get here, a new (uninitialized) object -- has been created. Copy the parameters we have -- been given to the properties of the object: width=newwidth; height=newheight /* Change the size of an Oblong */ method size(newwidth, newheight) returns Oblong width=newwidth; height=newheight return this -- return the resized object /* Change the size of an Oblong, relatively */ method relsize(relwidth, relheight)returns Oblong width=width+relwidth; height=height+relheight return this /* 'Print' what we know about the oblong */ method print say 'Oblong' width 'x' height

&o summari=e7 :5 A class is started b% the class instruction2 which names the class5 ;5 &he class instruction is +ollowed b% a list o+ the properties o+ the object5 &hese can be assigned initial values2 i+ re8uired5 <5 &he properties are +ollowed b% the methods o+ the object5 "ach method is introduced b% a
Version 2.00 NetRexx Overview 27

method instruction which names the method and describes the arguments that must be supplied

to the method5 &he bod% o+ the method is ended b% the ne!t method instruction -or b% the end o+ the +ile.5 &he Oblong.nrx +ile is compiled just like an% other Net e!! program2 and should create a $lass #ile called Oblong.class5 ,ere's a program to tr% out the /blong class7
/* tryOblong.nrx -- try the Oblong class */ first=Oblong(5,3) -- make an oblong first.print -- show it first.relsize(1,1).print -- enlarge and print again second=Oblong(1,2) second.print -- make another oblong -- and print it

when tryOblong.nrx is compiled2 %ou'll notice -i+ %our compiler makes a cross1re+erence listing available. that the variables first and second have t%pe Oblong5 &hese variables re+er to /blongs2 just as the variables in earlier e!amples re+erred to Net e!! strings5 /nce a variable has been assigned a t%pe2 it can onl% re+er to objects o+ that t%pe5 &his helps avoid errors where a variable re+ers to an object that it wasn't meant to5

Programs are classes, too

It's worth pointing out2 here2 that all the e!ample programs in this overview are in +act classes -%ou ma% have noticed that compiling them with the re+erence implementation creates xxx.class +iles2 where xxx is the name o+ the source +ile.5 &he environment underl%ing the implementation will allow a class to run as a stand1alone appli$ation i+ it has a static method called main which takes an arra% o+ strings as its argument5 I+ necessar% -that is2 i+ there is no class instruction. Net e!! automaticall% adds the necessar% class and method instructions +or a stand1alone application2 and also an instruction to convert the arra% o+ strings -each o+ which holds one word +rom the command string. to a single Net e!! string5 &he automatic additions can also be included e!plicitl%F the DtoastE e!ample could there+ore have been written7
/* This wishes you the best of health. */ class toast method main(argwords=String[]) static arg=Rexx(argwords) say 'Cheers!'

though in this program the argument string2 arg2 is not used5

28

NetRexx Overview

Version 2.00

Extending classes
It's common2 when dealing with objects2 to take an e!isting class and e!tend it5 /ne wa% to do this is to modi+% the source code o+ the original class 9 but this isn't alwa%s available2 and with man% di++erent people modi+%ing a class2 classes could rapidl% get over1complicated5 Languages that deal with objects2 like Net e!!2 there+ore allow new classes o+ objects to be set up which are derived +rom e!isting classes5 6or e!ample2 i+ %ou wanted a di++erent kind o+ /blong in which the /blong had a new propert% that would be used when printing the /blong as a rectangle2 %ou might de+ine it thus7
/* charOblong.nrx -- an oblong class with character */ class charOblong extends Oblong printchar -- the character for display /* Constructor to make a new oblong with character */ method charOblong(newwidth, newheight, newprintchar) super(newwidth, newheight) -- make an oblong printchar=newprintchar -- and set the character /* 'Print' the oblong */ method print loop for super.height say printchar.copies(super.width) end

&here are several things worth noting about this e!ample7 :5 &he Dextends OblongE on the class instruction means that this class is an e!tension o+ the /blong class5 &he properties and methods o+ the /blong class are inherited b% this class -that is2 appear as though the% were part o+ this class.5 Another common wa% o+ sa%ing this is that DcharOblongE is a s*&$lass o+ DOblongE -and DOblongE is the s*per$lass o+ DcharOblongE.5 ;5 &his class adds the printchar propert% to the properties alread% de+ined +or /blong5 <5 &he constructor +or this class takes a width and height -just like /blong. and adds a third argument to speci+% a print character5 It +irst invokes the constructor o+ its superclass -/blong. to build an /blong2 and +inall% sets the printchar +or the new object5 G5 &he new char/blong object also prints di++erentl%2 as a rectangle o+ characters2 according to its dimension5 &he print method -as it has the same name and arguments 9 none 9 as that o+ the superclass. replaces -overrides. the print method o+ /blong5 B5 &he other methods o+ /blong are not overridden2 and there+ore can be used on char/blong objects5 &he charOblong.nrx +ile is compiled just like Oblong.nrx was2 and should create a +ile called charOblong.class5

Version 2.00

NetRexx Overview

29

,ere's a program to tr% it out7

/* trycharOblong.nrx -- try the charOblong class */ first=charOblong(5,3,'#') first.print first.relsize(1,1).print -- make an oblong -- show it -- enlarge and print again

second=charOblong(1,2,'*') -- make another oblong second.print -- and print it

&his should create the two char/blong objects2 and print them out in a simple Dcharacter graphicsE +orm5 Note the use o+ the method relsize +rom /blong to resi=e the char/blong object5

Optional arguments
All methods in Net e!! ma% have optional arguments -omitted +rom the right. i+ desired5 6or an argument to be optional2 %ou must suppl% a de+ault value5 6or e!ample2 i+ the char/blong constructor was to have a de+ault value +or printchar2 its method instruction could have been written7
method charOblong(newwidth, newheight, newprintchar='X')

which indicates that i+ no third argument is supplied then 'X' should be used5 A program creating a char/blong could then simpl% write7
first=charOblong(5,3) -- make an oblong

which would have e!actl% the same e++ect as i+ 'X' were speci+ied as the third argument5

30

NetRexx Overview

Version 2.00

Tracing
Net e!! tracing is de+ined as part o+ the language5 &he +low o+ e!ecution o+ programs ma% be traced2 and this trace can be viewed as it occurs -or captured in a +ile.5 &he trace can show each clause as it is e!ecuted2 and optionall% show the results o+ e!pressions2 et$. 6or e!ample2 the trace results in the program Dtrace1.nrxE7
trace results number=1/7 parse number before '.' after say after'.'before

would result in7

--- trace1.nrx 2 *=* number=1/7 >v> number "0.142857143" 3 *=* parse number before '.' after >v> before "0" >v> after "142857143" 4 *=* say after'.'before >>> "142857143.0" 142857143.0

where the line marked with D---E indicates the conte!t o+ the trace2 lines marked with D*=*E are the instructions in the program2 lines with D>v>E show results assigned to local variables2 and lines with D>>>E show results o+ un1named e!pressions5 6urther2 trace methods lets %ou trace the use o+ all methods in a class2 along with the values o+ the arguments passed to each method5 ,ere's the result o+ adding trace methods to the /blong class shown earlier and then running tryOblong7
--- Oblong.nrx 8 *=* method Oblong(newwidth, newheight) >a> newwidth "5" >a> newheight "3" 26 *=* method print Oblong 5 x 3 20 *=* method relsize(relwidth, relheight)21 *-* returns Oblong >a> relwidth "1" >a> relheight "1" 26 *=* method print Oblong 6 x 4 10 *=* method Oblong(newwidth, newheight) >a> newwidth "1" >a> newheight "2" 26 *=* method print Oblong 1 x 2

where lines with D>a>E show the names and values o+ the arguments5 It's o+ten use+ul to be able to +ind out when -and where. a variable's value is changed5 &he trace var instruction does just thatF it adds names to or removes names +rom a list o+ monitored variables5 I+ the name o+ a variable in the current class or method is in the list2 then trace results is turned on +or an% assignment2 loop2 or parse instruction that assigns a new value to the named variable5 0ariable names to be added to the list are speci+ied b% listing them a+ter the var ke%word5 An% name ma% be optionall% pre+i!ed b% a - sign52 which indicates that the variable is to be removed +rom the list5
Version 2.00 NetRexx Overview 31

6or e!ample2 the program Dtrace2.nrxE7

trace var a b -- now variables a and b will be traced a=3 b=4 c=5 trace var -b c -- now variables a and c will be traced a=a+1 b=b+1 c=c+1 say a b c

would result in7

--3 *=* >v> 4 *=* >v> 8 *=* >v> 10 *=* >v> 4 5 6 trace2.nrx a=3 a "3" b=4 b "4" a=a+1 a "4" c=c+1 c "6"

32

NetRexx Overview

Version 2.00

Binary types and conversions

Most programming environments support the notion o+ +i!ed1precision DprimitiveE binar% t%pes2 which correspond closel% to the binar% operations usuall% available at the hardware level in computers5 6or the re+erence implementation2 these t%pes are7 &yte, short, int, and long 9 signed integers that will +it in @2 :A2 <;2 or AG bits respectivel% #loat and do*&le 9 signed +loating point numbers that will +it in <; or AG bits respectivel%5 $har 9 an unsigned :A1bit 8uantit%2 holding a Unicode character &oolean 9 a :1bit logical value2 representing 0 or 1 -D+alseE or DtrueE.5 /bjects o+ these t%pes are handled speciall% b% the implementation Dunder the coversE in order to achieve ma!imum e++icienc%F in particular2 the% cannot be constructed like other objects 9 their value is held directl%5 &his distinction rarel% matters to the Net e!! programmer7 in the case o+ string literals an object is constructed automaticall%F in the case o+ an int literal2 an object is not constructed5 6urther2 Net e!! automaticall% allows the conversion between the various +orms o+ character strings in implementations:> and the primitive t%pes5 &he Dgolden ruleE that is +ollowed b% Net e!! is that an% automatic conversion which is applied must not lose in+ormation7 either it can be determined be+ore e!ecution that the conversion is sa+e -as in int to String. or it will be detected at e!ecution time i+ the conversion +ails -as in String to int.5 &he automatic conversions greatl% simpli+% the writing o+ programsF the e!act t%pe o+ numeric and string1like method arguments rarel% needs to be a concern o+ the programmer5 6or certain applications where earl% checking or per+ormance override other considerations2 the re+erence implementation o+ Net e!! provides options +or di++erent treatment o+ the primitive t%pes7 :5 options strictassign 9 ensures e!act t%pe matching +or all assignments5 No conversions -including those +rom shorter integers to longer ones. are applied5 &his option provides stricter t%pe1checking than most other languages2 and ensures that all t%pes are an e!act match5 ;5 options binary 9 uses implementation1dependent +i!ed precision arithmetic on binar% t%pes -also2 literal numbers2 +or e!ample2 will be treated as binar%2 and local variables will be given DnativeE t%pes such as int or String2 where possible.5 Binar% arithmetic currentl% gives better per+ormance than Net e!! decimal arithmetic2 but places the burden o+ avoiding over+lows and loss o+ in+ormation on the programmer5 &he options instruction -which ma% list more than one option. is placed be+ore the +irst class instruction in a +ileF the binary ke%word ma% also be used on a class or method instruction2 to allow an individual class or method to use binar% arithmetic5

Explicit type assignment

Hou ma% e!plicitl% assign a t%pe to an e!pression or variable7

:> In the re+erence implementation2 these are String2 char2 char[] -an arra% o+ characters.2 and the Net e!! string t%pe2 Rexx5 Version 2.00 NetRexx Overview 33

i=int 3000000 j=int 4000000 k=int say i*j k=i*j

------

'i' is an 'int' with value 3000000 'j' is an 'int' with value 4000000 'k' is an 'int', with no initial value multiply and display the result multiply and assign result to 'k'

&his e!ample also illustrates an important di++erence between options nobinary and options binary5 *ith the +ormer -the de+ault. the say instruction would displa% the result D1.20000000E+13E and a conversion over+low would be reported when the same e!pression is assigned to the variable k5 *ith options binary2 binar% arithmetic would be used +or the multiplications2 and so no error would be detectedF the say would displa% D-138625024E and the variable k takes the incorrect result5

Binary types in practice

In practice2 e!plicit t%pe assignment is onl% occasionall% needed in Net e!!5 &hose conversions that are necessar% +or using e!isting classes -or those that use options binary. are generall% automatic5 6or e!ample2 here is an DAppletE +or use b% 3ava1enabled browsers7
/* A simple graphics Applet */ class Rainbow extends Applet method paint(g=Graphics) -- called to repaint window maxx=size.width-1 maxy=size.height-1 loop y=0 to maxy col=Color.getHSBColor(y/maxy, 1, 1) -- new colour g.setColor(col) -- set it g.drawLine(0, y, maxx, y) -- fill slice end y

In this e!ample2 the variable col will have t%pe Color2 and the three arguments to the method getHSBColor will all automaticall% be converted to t%pe float5 As no over+lows are possible in this e!ample2 options binary ma% be added to the top o+ the program with no other changes being necessar%5

34

NetRexx Overview

Version 2.00

Exception and error handling

Net e!! doesn't have a goto instruction2 but a signal instruction is provided +or abnormal trans+er o+ control2 such as when something unusual occurs5 Using signal raises an e%$eptionF all control instructions are then DunwoundE until the e!ception is caught b% a control instruction that speci+ies a suitable catch instruction +or handling the e!ception5 "!ceptions are also raised when various errors occur2 such as attempting to divide a number b% =ero5 6or e!ample7
say 'Please enter a number:' number=ask do say 'The reciprocal of' number 'is:' 1/number catch RuntimeException say 'Sorry, could not divide "'number'" into 1' say 'Please try again.' end

,ere2 the catch instruction will catch an% e!ception that is raised when the division is attempted -conversion error2 divide b% =ero2 et$..2 and an% instructions that +ollow it are then e!ecuted5 I+ no e!ception is raised2 the catch instruction -and an% instructions that +ollow it. are ignored5 An% o+ the control instructions that end with end -do2 loop2 or select. ma% be modi+ied with one or more catch instructions to handle e!ceptions5

Version 2.00

NetRexx Overview

35

NetRexx Language Definition

&his part o+ the document describes the Net e!! language2 version ;5>>5 0ersion ; includes the original Net e!! language:: together with additions made +rom :CC? through ;>>> and previousl% published in the 3et/e%% 2ang*age .*pple)ent5 &he language is described +irst in terms o+ the characters +rom which it is composed and its low1level s%nta!2 and then progressivel% through more comple! constructions5 6inall%2 special sections describe the semantics o+ the more complicated areas5 (ome +eatures o+ the language2 such as options ke%words and binar% arithmetic2 are implementation1 dependent5 ather than leaving these important aspects entirel% abstract2 this description includes summaries o+ the treatment o+ such items in the re#eren$e i)ple)entation o+ Net e!!5 &he re+erence implementation is based on the 3ava environment and class libraries5 Paragraphs that re#er to the re#eren$e i)ple)entation, and are there#ore not stri$tly part o# the lang*age de#inition, are shown in itali$s, like this one.

:: &he Net e!! Language2 M5 65 Cowlishaw2 I(BN >1:<1@>A<<;1I2 $rentice1,all2 :CC? Version 2.00 NetRexx Language Definition 37

Notations
In this part o+ the document2 various notations such as changes o+ +ont are used +or clarit%5 *ithin the te!t2 a sans1seri+ bold +ont is used to indicate keywords2 and an italic +ont is used to indicate te$hni$al ter)s5 An italic +ont is also used to indicate a re+erence to a te$hni$al ter) de#ined elsewhere or a word in a s%nta! diagram that names a segment o+ s%nta!5 (imilarl%2 in the s%nta! diagrams in this document2 words -s%mbols. in the sans1seri+ bold +ont also denote ke%words or sub1ke%words2 and words -such as e%pression. in italics denote a token or collection o+ tokens de+ined elsewhere5 &he brackets O and P delimit optional -and possibl% alternative. parts o+ the instructions2 whereas the braces Q and R indicate that one o+ a number o+ alternatives must be selected5 An ellipsis -.... +ollowing a bracket indicates that the bracketed part o+ the clause ma% optionall% be repeated5 /ccasionall% in s%nta! diagrams -e.g.2 +or inde!ed re+erences. brackets are DrealE -that is2 a bracket is re8uired in the s%nta!F it is not marking an optional part.5 &hese brackets are enclosed in single 8uotes2 thus7 '[' or ']'5 Note that the ke%words and sub1ke%words in the s%nta! diagrams are not case1sensitive7 the s%mbols DI6E DI+E and Di6E would all match the ke%word shown in a s%nta! diagram as if5 Note also that most o+ the clause delimiters -D;E. shown can usuall% be omitted as the% will be implied b% the end o+ a line5

38

NetRexx Language Definition

Version 2.00

Characters and Encodings

In the de+inition o+ a programming language it is important to emphasi=e the distinction between a $hara$ter and the $oded representation:; -encoding. o+ a character5 &he character DAE2 +or e!ample2 is the +irst letter o+ the "nglish - oman. alphabet2 and this meaning is independent o+ an% speci+ic coded representation o+ that character5 #i++erent coded character sets -such as2 +or e!ample2 the A(CII:< and "BC#IC:G codes. use 8uite di++erent encodings +or this character -decimal values AB and :C<2 respectivel%.5 "!cept where stated otherwise2 this document uses characters to conve% meaning and not to impl% a speci+ic character code -the e!ceptions are certain operations that speci+icall% convert between characters and their representations.5 At no time is Net e!! concerned with the gl%ph -actual appearance. o+ a character5

Character Sets
$rogramming in the Net e!! language can be considered to involve the use o+ two character sets5 &he +irst is used +or e!pressing the Net e!! program itsel+2 and is the relativel% small set o+ characters described in the ne!t section5 &he second character set is the set o+ characters that can be used as character data b% a particular implementation o+ a Net e!! language processor5 &his character set ma% be limited in si=e -sometimes to a limit o+ ;BA di++erent characters2 which have a convenient @1bit representation.2 or it ma% be much larger5 &he 6ni$ode:B character set2 +or e!ample2 allows +or ABB<A characters2 each encoded in :A bits5 Usuall%2 most or all o+ the characters in the second -data. character set are also allowed within a Net e!! program2 but onl% within commentar% or immediate -literal. data5 &he Net e!! language e!plicitl% de+ines the +irst character set2 in order that programs will be portable and understandableF at the same time it avoids restrictions due to the language itsel+ on the character set used +or data5 ,owever2 where the language itsel+ manipulates or inspects the data -as when carr%ing out arithmetic operations.2 there ma% be re8uirements on the data character set -+or e!ample2 numbers can onl% be e!pressed i+ there are digit characters in the set.5

:; &hese terms have the meanings as de+ined b% the International /rgani=ation +or (tandardi=ation2 in I(/ ;<@; 4ata pro$essing 7 Vo$a&*lary5 :< American (tandard Code +or In+ormation Interchange5 :G "!tended Binar% Coded #ecimal Interchange Code5 :B 1he 6ni$ode .tandard8 +orldwide Chara$ter 'n$oding2 0ersion :5>5 0olume :2 I(BN >1;>:1BA?@@1:2 :CC:2 and 0olume ;2 I(BN >1;>:1A>@GB1A :CC;2 Addison1*esle%2 eading2 MA5 Version 2.00 NetRexx Language Definition 39

Structure and General Syntax

A Net e!! program is built up out o+ a series o+ $la*ses that are composed o+7 =ero or more blanks -which are ignored.F a se8uence o+ tokens -described in this section.F =ero or more blanks -again ignored.F and the delimiter D;E -semicolon. which ma% be implied b% line1ends or certain ke%words5 Conceptuall%2 each clause is scanned +rom le+t to right be+ore e!ecution and the tokens composing it are resolved5 Identi+iers -known as s%mbols. and numbers are recogni=ed at this stage2 comments -described below. are removed2 and multiple blanks -e!cept within literal strings. are reduced to single blanks5 Blanks adjacent to operator characters -see page G<. and special characters -see page G<. are also removed5

Blanks and White Space

Blanks -spaces. ma% be +reel% used in a program to improve appearance and la%out2 and most are ignored5 Blanks2 however2 are usuall% signi+icant within literal strings -see below. between two tokens that are not special characters -+or e!ample2 between two s%mbols or ke%words. between the two characters +orming a comment delimiter immediatel% outside parentheses -D(E and D)E. or brackets -D[E and D]E.5 6or implementations that support tabulation -tab. and +orm +eed characters2 these characters outside o+ literal strings are treated as i+ the% were a single blankF similarl%2 i+ the last character in a Net e!! program is the "nd1o+1+ile character -"/62 encoded in A(CII as decimal ;A.2 that character is ignored5

Comments
Commentar% is included in a Net e!! program b% means o+ $o))ents5 &wo +orms o+ comment notation are provided7 line $o))ents are ended b% the end o+ the line on which the% start2 and &lo$k $o))ents are t%picall% used +or more e!tensive commentar%5 2ine $o))ents A line comment is started b% a se8uence o+ two adjacent h%phens -D--E.F all characters +ollowing that se8uence up to the end o+ the line are then ignored b% the Net e!! language processor5 %xample.
i=j+7 -- this line comment follows an assignment

Blo$k $o))ents

A block comment is started b% the se8uence o+ characters D/*E2 and is ended b% the same se8uence reversed2 D*/E5 *ithin these delimiters an% characters are allowed -including 8uotes2 which need not be paired.5 Block comments ma% be nested2 which is to sa% that D/*E and D*/E must pair correctl%5 Block comments ma% be an%where2 and ma% be o+ an% length5 *hen a block comment is +ound2 it is treated as though it were a blank -which ma% then be removed2 i+ adjacent to a special character.5 %xample.
/* This is a valid block comment */

40

NetRexx Language Definition

Version 2.00

&he two characters +orming a comment delimiter -D/*E or D*/E. must be adjacent -that is2 the% ma% not be separated b% blanks or a line1end.5 Note. It is recommended that Net e!! programs start with a block comment that describes the program5 Not onl% is this good programming practice2 but some implementations ma% use this to distinguish Net e!! programs +rom other languages5 Implementation minimum. Implementations should support nested block comments to a depth o+ at least :>5 &he length o+ a comment should not be restricted2 in that it should be possible to Dcomment outE an entire program5

Tokens
&he essential components o+ clauses are called tokens5 &hese ma% be o+ an% length2 unless limited b% implementation restrictions2:A and are separated b% blanks2 comments2 ends o+ lines2 or b% the nature o+ the tokens themselves5 &he tokens are7 2iteral strings A se8uence including an% characters that can sa+el% be represented in an implementation:? and delimited b% the single 8uote character -'. or the double18uote -".5 Use "" to include a " in a literal string delimited b% "2 and similarl% use two single 8uotes to include a single 8uote in a literal string delimited b% single 8uotes5 A literal string is a constant and its contents will never be modi+ied b% Net e!!5 Literal strings must be complete on a single line -this means that unmatched 8uotes ma% be detected on the line that the% occur.5 An% string with no characters -i.e.2 a string o+ length >. is called a n*ll string5 %xample,.
'Fred' 'A' "Don't Panic!" ":x" 'You shouldn''t' ''

/* Same as "You shouldn't" */ /* A null string */

*ithin literal strings2 characters that cannot sa+el% or easil% be represented -+or e!ample Dcontrol charactersE. ma% be introduced using an es$ape se9*en$e5 An escape se8uence starts with a &a$kslash -D\E.2 which must then be +ollowed immediatel% b% one o+ the +ollowing -letters ma% be in either uppercase or lowercase.7
t n r f "

the escape se8uence represents a tabulation -tab. character the escape se8uence represents a new1line -line +eed. character the escape se8uence represents a return -carriage return. character the escape se8uence represents a +orm1+eed character the escape se8uence represents a double18uote character

:A *herever arbitrar% implementation restrictions are applied2 the si=e o+ the restriction should be a number that is readil% memorable in the decimal s%stemF that is2 one o+ :2 ;B2 or B multiplied b% a power o+ ten5 B>> is pre+erred to B:;2 the number ;B> is more DnaturalE than ;BA2 and so on5 Limits e!pressed in digits should be a multiple o+ three5 :? (ome implementations ma% not allow certain Dcontrol charactersE in literal strings5 &hese characters ma% be included in literal strings b% using one o+ the escape se8uences provided5 Version 2.00 NetRexx Language Definition 41

' \ 0 xhh

the escape se8uence represents a single18uote character the escape se8uence represents a backslash character the escape se8uence represents a DnullE character -the character whose encoding e8uals =ero.2 used to indicate continuation in a say instruction -=ero. the escape se8uence represents a DnullE character -the character whose encoding e8uals =ero.F an alternative to \the escape se8uence represents a character whose encoding is given b% the two he!adecimal digits -DhhE. +ollowing the DxE5 I+ the character encoding +or the implementation re8uires more than two he!adecimal digits2 the% are padded with =ero digits on the le+t5

uhhhh the escape se8uence represents a character whose encoding is given b% the +our he!adecimal digits -DhhhhE. +ollowing the DuE5 It is an error to use this escape

i+ the character encoding +or the implementation re8uires +ewer than +our he!adecimal digits5 ,e!adecimal digits +or use in the escape se8uences above ma% be an% decimal digit ->9 C. or an% o+ the +irst si! alphabetic characters -a9+.2 in either lowercase or uppercase5 %xample,.
'You shouldn\'t' '\x6d\u0066\x63' '\\\u005C' /* Same as "You shouldn't" */ /* In Unicode: 'mfc' */ /* In Unicode, two backslashes */

Implementation minimum. Implementations should support literal strings o+ at least :>> characters5 -But note that the length o+ string e!pression results2 et$.2 should have a much larger minimum2 normall% onl% limited b% the amount o+ storage available5. .y)&ols (%mbols are groups o+ characters selected +rom the oman alphabet in uppercase or lowercase -A9S2 a9=.2 the Arabic numerals ->9C.2 or the characters underscore2 dollar2 and euro:@ -DTUVE.5 Implementations ma% also allow other alphabetic and numeric characters in s%mbols to improve the readabilit% o+ programs in languages other than "nglish5 &hese additional characters are known as e%tra letters and e%tra digits5:C %xample,.
DanYrOgof minx lan $Virtual3D

A s%mbol ma% include other characters onl% when the +irst character o+ the s%mbol is a digit ->9C or an e!tra digit.5 In this case2 it is a n*)eri$ sy)&ol 9 it ma% include a period -D.E. and it must have the s%nta! o+ a number5 &his ma% be si)ple n*)&er2 which is a se8uence o+ digits with at most one period -which ma% not be the +inal character o+ the se8uence.2 or it ma% be a he%ade$i)al or &inary n*)eri$ sy)&ol -see page GB.2 or it ma% be a number e!pressed in e%ponential notation5 A number in e!ponential notation is a simple number +ollowed immediatel% b% the
:@ Note that onl% U&6@1encoded source +iles can currentl% use the euro character5 :C It is e!pected that implementations o+ Net e!! will be based on Unicode or a similarl% rich character set5 ,owever2 portabilit% to implementations with smaller character sets ma% be compromised when e!tra letters or e!tra digits are used in a program5 42 NetRexx Language Definition Version 2.00

se8uence DEE -or DeE.2 +ollowed immediatel% b% a sign -D+E or D-E.2;> +ollowed immediatel% b% one or more digits -which ma% not be +ollowed b% an% other s%mbol characters.5 %xample,.
1 1.3 12.007 17.3E-12 3e+12 0.03E+9

*hen e%tra digits are used in numeric s%mbols2 the% must represent values in the range =ero through nine5 *hen numeric s%mbols are used as numbers2 an% e!tra digits are +irst converted to the corresponding character in the range >1C2 and then the s%mbol +ollows the usual rules +or numbers in Net e!! -that is2 the most signi+icant digit is on the le+t2 et$..5 In the re#eren$e i)ple)entation, the e%tra letters are those $hara$ters :e%$l*ding !;<, a; =, and *nders$ore> that res*lt in 1 when tested with java.lang.Character.isLetter. .i)ilarly, the e%tra digits are those $hara$ters :e%$l*ding 0;9> that res*lt in 1 when tested with java.lang.Character.isDigit. &he meaning o+ a s%mbol depends on the conte!t in which it is used5 6or e!ample2 a s%mbol ma% be a constant -i+ a number.2 a ke%word2 the name o+ a variable2 or identi+% some algorithm5 It is recommended that the dollar and euro onl% be used in s%mbols in mechanicall% generated programs or where otherwise essential5 Implementation minimum. Implementations should support s%mbols o+ at least B> characters5 -But note that the length o+ its value2 i+ it is a string variable2 should have a much larger limit5. ?perator &he characters + - * / % | & = \ > < are used -sometimes in combination. to $hara$ters indicate operations -see page A:. in e!pressions5 A +ew o+ these are also used in parsing templates2 and the e8uals sign is also used to indicate assignment5 Blanks adjacent to operator characters are removed2 so2 +or e!ample2 the se8uences7
345>=123 345 >=123 345 >= 123 345 > = 123

are identical in meaning5 (ome o+ these characters ma% not be available in all character sets2 and i+ this is the case appropriate translations ma% be used5 Note. &he se8uences D--E2 D/*E2 and D*/E are comment delimiters2 as described earlier5 &he se8uences D++E and D\\E are not valid in Net e!! programs5 .pe$ial &he characters . , ; ) ( ] [ together with the operator characters have $hara$ters special signi+icance when +ound outside o+ literal strings2 and constitute the set o+ spe$ial $hara$ters5 &he% all act as token delimiters2 and blanks adjacent to an% o+ these -e!cept the period. are removed2 e!cept that a blank adjacent to the outside o+ a parenthesis or
;> &he sign in this conte!t is part o+ the s%mbolF it is not an operator5 Version 2.00 NetRexx Language Definition 43

bracket is onl% deleted i+ it is also adjacent to another special character -unless this is a parenthesis or bracket and the blank is outside it2 too.5 (ome o+ these characters ma% not be available in all character sets2 and i+ this is the case appropriate translations ma% be used5 &o illustrate how a clause is composed out o+ tokens2 consider this e!ample7
'REPEAT' B + 3;

&his is composed o+ si! tokens7 a literal string2 a blank operator -described later.2 a s%mbol -which is probabl% the name o+ a variable.2 an operator2 a second s%mbol -a number.2 and a semicolon5 &he blanks between the DBE and the D+E and between the D+E and the D3E are removed5 ,owever one o+ the blanks between the 'REPEAT' and the DBE remains as an operator5 &hus the clause is treated as though written7
'REPEAT' B+3;

Implied semicolons and continuations

A semicolon -clause end. is implied at the end o+ each line2 e!cept i+7 :5 &he line ends in the middle o+ a block comment2 in which case the clause continues at the end o+ the block comment5 ;5 &he last token was a h%phen5 In this case the h%phen is +unctionall% replaced b% a blank2 and hence acts as a $ontin*ation $hara$ter5 &his means that semicolons need onl% be included to separate multiple clauses on a single line5 Note,. :5 A comment is not a token2 so there+ore a comment ma% +ollow the continuation character on a line5 ;5 (emicolons are added automaticall% b% Net e!! a+ter certain instruction ke%words when in the correct conte!t5 &he ke%words that ma% have this e++ect are else2 finally2 otherwise2 thenF the% become complete clauses in their own right when this occurs5 &hese special cases reduce program entr% errors signi+icantl%5

The case of names and symbols

In general2 Net e!! is a $ase;insensiti"e language5 &hat is2 the names o+ ke%words2 variables2 and so on2 will be recogni=ed independentl% o+ the case used +or each letter in a nameF the name DSwildonE would match the name DswilDonE5 Net e!!2 however2 uses names that ma% be visible outside the Net e!! program2 and these ma% well be re+erenced b% case1sensitive languages5 &here+ore2 an% name that has an e!ternal use -such as the name o+ a propert%2 method2 constructor2 or class. has a de+ined spelling2 in which each letter o+ the name has the case used +or that letter when the name was +irst de+ined or used5 (imilarl%2 the lookup o+ e!ternal names is both case1preserving and case1insensitive5 I+ a class2 method2 or propert% is re+erenced b% the name DFooE2 +or e!ample2 an e!act1case match will +irst be tried at each point that a search is made5 I+ this succeeds2 the search +or a matching name is complete5 I+ it is does not succeed2 a case1insensitive search in the same conte!t is carried out2 and i+ one item is +ound2 then the search is complete5 I+ more than one item matches then the re+erence is ambiguous2
44 NetRexx Language Definition Version 2.00

and an error is reported5 Implementations are encouraged to o++er an option that re8uires that all name matches are e!act -case1 sensitive.2 +or programmers or house1st%les that pre+er that approach to name matching5

Hexadecimal and binary numeric symbols

A he%ade$i)al n*)eri$ sy)&ol describes a whole number2 and is o+ the +orm nXstring5 ,ere2 n is a simple number with no decimal part -and optional leading insigni+icant =eros. which describes the e++ective length o+ the he!adecimal string2 the X -which ma% be in lowercase. indicates that the notation is he!adecimal2 and string is a string o+ one or more he!adecimal characters -characters +rom the ranges Da9+E2 DA96E2 and the digits D>9CE.5 &he string is taken as a signed number e!pressed in n he!adecimal characters5 I+ necessar%2 string is padded on the le+t with D0E characters -note2 not Dsign1e!tendedE. to length n characters5 I+ the most signi+icant -le+t1most. bit o+ the resulting string is =ero then the number is positiveF otherwise it is a negative number in twos1complement +orm5 In both cases it is converted to a Net e!! number which ma%2 there+ore2 be negative5 &he result o+ the conversion is a number comprised o+ the Arabic digits >9C2 with no insigni+icant leading =eros but possibl% with a leading D-E5 &he value n ma% not be less than the number o+ characters in string2 with the single e!ception that it ma% be =ero2 which indicates that the number is alwa%s positive -as though n were greater than the the length o+ string.5 %xample,.
1x8 2x8 2x08 0x08 0x10 0x81 2x81 3x81 4x81 04x81 16x81 4xF081 8xF081 0Xf081 == == == == == == == == == == == == == == -8 8 8 8 16 129 -127 129 129 129 129 -3967 61569 61569

A &inary n*)eri$ sy)&ol describes a whole number using the same rules2 e!cept that the identi+%ing character is B or b2 and the digits o+ string must be either 0 or 12 each representing a single bit5 %xample,.
1b0 1b1 0b10 0b100 4b1000 8B1000 == == == == == == 0 -1 2 4 -8 8

Note. ,e!adecimal and binar% numeric s%mbols are a purel% s%ntactic device +or representing decimal whole numbers5 &hat is2 the% are recogni=ed onl% within the source o+ a Net e!! program2 and are not e8uivalent to a literal string with the same characters within 8uotes5

Version 2.00

NetRexx Language Definition

45

Types and Classes

$rograms written in the Net e!! language manipulate values2 such as names2 numbers2 and other representations o+ data5 All such values have an associated type -also known as a signat*re.5 &he t%pe o+ a value is a descriptor which identi+ies the nature o+ the value and the operations that ma% be carried out on that value5 A t%pe is normall% de+ined b% a $lass2 which is a named collection o+ values -called properties. and procedures -called )ethods. +or carr%ing out operations on the properties5 6or e!ample2 a character string in Net e!! is usuall% o+ t%pe Rexx2 which will be implemented b% the class called Rexx5 &he class Rexx de+ines the properties o+ the string -a se8uence o+ characters. and the methods that work on strings5 &his t%pe o+ string ma% be the subject o+ arithmetic operations as well as more conventional string operations such as concatenation2 and so the methods implement string arithmetic as well as other string operations5 &he names o+ t%pes can +urther be 8uali+ied b% the name o+ a pa$kage where the class is held5 (ee the package instruction +or details o+ packagesF in summar%2 a package name is a se8uence o+ one or more non1numeric s%mbols2 separated b% periods5 &hus2 i+ the Rexx class was part o+ the netrexx.lang package2;: then its 9*ali#ied type would be netrexx.lang.Rexx5 In general2 onl% the class name need be speci+ied to re+er to a t%pe5 ,owever2 i+ a class o+ the same name e!ists in more than one known -imported. package2 then the name should be 8uali+ied b% the package name5 &hat is2 i+ the use o+ just the class name does not uni8uel% identi+% the class then the re+erence is ambiguous and an error is reported5

Primitive types
Implementations ma% optionall% provide pri)iti"e types +or e++icienc%5 $rimitive t%pes are Dbuilt1inE t%pes that are not necessaril% implemented as classes5 &he% t%picall% represent concepts native to the underl%ing environment -such as <;1bit binar% integer numbers. and ma% e!hibit semantics that are di++erent +rom other t%pes5 Net e!!2 however2 makes no s%nta! distinction in the names o+ primitive t%pes2 and assumes &inary $onstr*$tors -see page :B>. e!ist +or primitive values5 $rimitive t%pes are necessar% when per+ormance is an overriding consideration2 and so this de+inition will assume that primitive t%pes corresponding to the common binar% number +ormats are available and will describe how the% di++er +rom other t%pes2 where appropriate5 In the re#eren$e i)ple)entation, the na)es o# the pri)iti"e types are8
boolean char byte short int long float double

where the #irst two des$ri&e a single;&it "al*e and 6ni$ode $hara$ter respe$ti"ely, and the re)ainder des$ri&e signed n*)&ers o# "ario*s #or)ats. 1he )ain di##eren$e &etween these and other types is that the pri)iti"e types are not a s*&$lass o# Object, so they $annot &e assigned to a "aria&le o# type Object or passed to )ethods @&y re#eren$eA. 1o *se the) in this way, an o&5e$t )*st &e $reated to @wrapA the)B Ca"a pro"ides $lasses #or this :#or e%a)ple, the $lass Long>.

Dimensioned types
Another +eature that is provided +or e++icienc% is the concept o+ di)ensioned types2 which are t%pes -normal or primitive. that have an associated dimension -in the sense o+ the dimensions o+ an arra%.5
;: 1his is in #a$t where it )ay &e #o*nd in the re#eren$e i)ple)entation. 46 NetRexx Language Definition Version 2.00

#imensioned values are described in detail in the section on !rrays -see page ?G.5 &he dimension o+ a dimensioned t%pe is represented in Net e!! programs b% s8uare brackets enclosing =ero or more commas2 where the dimension is given b% the number o+ commas2 plus one5 A dimensioned t%pe is distinct +rom the t%pe o+ the same name but with no dimensions5 %xample,.
Rexx int Rexx[] int[,,]

&he e!amples show a normal t%pe2 a primitive t%pe2 and a dimensioned version o+ each -o+ dimension : and < respectivel%.5 &he latter t%pe would result +rom constructing an arra% thus7
myarray=int[10,10,10]

&hat is2 the dimension o+ the t%pe matches the count o+ inde!es de+ined +or the arra%5

Minor and Dependent classes

A )inor $lass in Net e!! is a class whose name is 8uali+ied b% the name o+ another class2 called its parent5 &his 8uali+ication is indicated b% the +orm o+ the name o+ the class7 the short name o+ the minor class is pre+i!ed b% the name o+ its parent class -separated b% a period.5 6or e!ample2 i+ the parent is called Foo then the +ull name o+ a minor class Bar would be written Foo.Bar5 A dependent $lass is a minor class that has a link to its parent class that allows a child object simpli+ied access to its parent object and its properties5 &hese re+inements o+ classes and are described in the section Minor and 4ependent $lasses -see page :;?.5

Version 2.00

NetRexx Language Definition

47

Terms
A ter) in Net e!! is a s%ntactic unit which describes some value -such as a literal string2 a variable2 or the result o+ some computation. that can be manipulated in a Net e!! program5 &erms ma% be either si)ple -consisting o+ a single element. or $o)po*nd -consisting o+ more than one element2 with a period and no other characters between each element.5

Simple terms
A simple term ma% be7 A literal string -see page G:. 9 a character string delimited b% 8uotes2 which is a constant5 A sy)&ol -see page G;.5 A s%mbol that does not begin with a digit identi+ies a variable2 a value2 or a t%pe5 /ne that does begin with a digit is a n*)eri$ sy)&ol2 which is a constant5 A )ethod $all -see page B<.2 which is o+ the +orm
symbol([expression[,expression]...])

An inde%ed re#eren$e -see page ?<.2 which is o+ the +orm;;

symbol'['[expression[,expression]...]']'

An array initiali=er -see page ?B.2 which is o+ the +orm

'['expression[,expression]...']'

A s*&;e%pression -see page AA.2 which consists o+ an% e!pression enclosed within a le+t and a right parenthesis5 Blanks are not permitted between the s%mbol in a method call and the D(E2 or between the s%mbol in an inde!ed re+erence and the D[E5 *ithin simple terms2 method calls with no arguments -that is2 with no e!pressions between the parentheses. ma% be e!pressed without the parentheses provided that the% re+er to a method in the current class -or to a static method in a class *sed b% the current class. and do not re+er to a constructor -see page BA.5 An implementation ma% optionall% provide a mechanism that disallows this parenthesis omission5

Compound terms
Compound terms ma% start with an% simple term2 and2 in addition2 ma% start with a 8uali+ied class name -see page ::>. or a 8uali+ied constructor -see page B<.5 &hese last two both start with a package name -a se8uence o+ non1numeric s%mbols separated b% periods and ending in a period.5 &his +irst part o+ a compound term is known as the st*& o+ the term5

;; &he notations '[' and ']' indicate s8uare brackets appearing in the Net e!! program5 48 NetRexx Language Definition Version 2.00

%xample ,tu',.
"A string" Arca 12.10 paint(g) indexedVar[i+1] ("A" "string") java.lang.Math netrexx.lang.Rexx(1)

-- qualified class name -- qualified constructor

All stubs are s%ntacticall% valid terms -either simple or compound. and ma% optionall% be +ollowed b% a $ontin*ation2 which is one or more additional non1numeric s%mbols2 method calls2 or inde!ed re+erences2 separated +rom each other and +rom the stub b% $onne$tors which are periods5 %xample compound term,.
"A rabbit".word(2).pos('b') Fluffy.left(3) 12.10.max(j) paint(g).picture indexedVar[i+1].length ("A" "string").word(1) java.lang.Math.PI java.lang.Math.log(10)

*ithin compound terms2 method calls with no arguments -that is2 with no e!pressions between the parentheses. ma% be e!pressed without the parentheses provided that the% do not re+er to a constructor -see page BA.5 6or e!ample2 the term7
Thread.currentThread().suspend()

could be written7
Thread.currentThread.suspend

An implementation ma% optionall% provide a mechanism that disallows this parenthesis omission5

Evaluation of terms
(imple terms are evaluated as a whole2 as described below5 Compound terms are evaluated +rom le+t to right5 6irst the stub is evaluated according to the rules detailed below5 &he t%pe o+ the value o+ the stub then 8uali+ies the ne!t element o+ the term -i+ an%. which is then evaluated -again2 the e!act rules are detailed below.5 &his process is then repeated +or each element in the term5 6or instance2 +or the e!ample above7
"A rabbit".word(2).pos('b')

the evaluation proceeds as +ollows7 :5 &he stub -"A rabbit". is evaluated2 resulting in a string o+ t%pe Rexx5 ;5 Because that string is o+ t%pe Rexx2 the Rexx class is then searched +or the word method5 &his is then invoked on the string2 with argument 25 In other words2 the word method is invoked with the string DA rabbitE as its current conte!t -the properties o+ the e!! class when the method is invoked re+lect that value.5 &his returns a new string o+ t%pe Rexx2 DrabbitE -the second word in the original string.5 <5 In the same wa% as be+ore2 the pos method o+ the Rexx class is then invoked on the new string2

Version 2.00

NetRexx Language Definition

49

with argument DbE5 &his returns a new string o+ t%pe Rexx2 D3E -the position o+ the +irst DbE in the previous result.5 &his value2 D3E2 is the +inal value o+ the term5 &he remainder o+ this section gives the details o+ term evaluationF it is best skipped on +irst reading5

Simple term evaluation

All simple terms ma% also be used as stubs2 and are evaluated in precisel% the same wa% as stubs2 as described below5 6or e!ample2 numeric s%mbols are evaluated as though the% were enclosed in 8uotesF their value is a string o+ t%pe Rexx5 In binar% classes -see page @>.2 however2 simple terms that are strings or numeric s%mbols are given an implementation1de+ined string or primitive t%pe respectivel%2 as described in the section on Binary "al*es and operations -see page :GC.

Stub evaluation
A term's stub is evaluated according to the +ollowing rules7 I+ the stub is a literal string2 its value is the string2 o+ t%pe Rexx2 constructed +rom that literal5 I+ the stub is a numeric s%mbol2 its value is the string2 o+ t%pe Rexx2 constructed +rom that literal -as though the literal were enclosed in 8uotes.5 I+ the stub is an un8uali+ied method or constructor call2 or a 8uali+ied constructor call2 then its value and t%pe is the result o+ invoking the method identi+ied b% the stub2 as described in Methods and Constr*$tors -see page B<.5 I+ the stub is a -non1numeric. s%mbol2 then its value and t%pe will be determined b% whichever o+ the +ollowing is +irst +ound7 :5 A local variable or method argument within the current method2 or a propert% in the current class5 ;5 A method whose name matches the s%mbol2 and takes no arguments2 and that is not a constructor2 in the current class5;< I+ the stub is part o+ a compound s%mbol2 then it ma% also be in a superclass2 searching upwards +rom the current class5 <5 A static or constant propert%2 or a static method2;G whose name matches the s%mbol -and that takes no arguments2 i+ a method. in a class listed in the uses phrase o+ the class instruction5 "ach class +rom the list is searched +or a matching propert% or method2 and then its superclasses are searched upwards +rom the class in the same wa%F this process is repeated +or each o+ the classes2 in the order speci+ied in the list5 G5 /ne o+ the allowed special words described in .pe$ial words and )ethods -see page :<>.2 such as this or version5 B5 &he short name o+ a known class or primitive t%pe -in which case the stub has no value2 just a t%pe.5 I+ the stub is an inde!ed re+erence2 then its value and t%pe will be determined b% whichever o+
;< Unless parenthesis omission is disallowed b% an implementation option2 such as options strictargs5 ;G Unless parenthesis omission is disallowed b% an implementation option2 such as options strictargs5 50 NetRexx Language Definition Version 2.00

the +ollowing is +irst +ound7 :5 &he s%mbol naming the re+erence is an undimensioned local variable or method argument within the current method2 or a propert% in the current class2 which has t%pe Rexx5 In this case2 the re+erence is to an inde%ed string -see page ?<.F the e!pressions within the brackets must be convertible to t%pe Rexx2 and the t%pe o+ the result will be Rexx5 ;5 &he s%mbol naming the re+erence is a dimensioned local variable or method argument within the current method2 or a propert% in the current class5 In this case2 the re+erence is to an array -see page ?G.2 and the e!pressions within the brackets must be convertible to whole numbers allowed +or arra% inde!es5 &he t%pe o+ the result will have the t%pe o+ the arra%2 with dimensions reduced b% the number o+ dimensions speci+ied in the stub5 6or e!ample2 i+ the arra% foo was o+ t%pe Baa[,,,] and the stub re+erred to foo[1,2]2 then the result would be o+ t%pe Baa[,]5 It would have been an error +or the stub to have speci+ied more than +our dimensions5 <5 &he s%mbol naming the re+erence is the name o+ a static or constant propert% in a class listed in the uses phrase o+ the class instruction5 "ach class +rom the list is searched in the same wa% as +or s%mbols2 above5 &he re+erence ma% be to an inde%ed string or an array2 as +or properties in the current class5 G5 &he s%mbol naming the re+erence is the name o+ a primitive t%pe or the short name o+ a known class2 and there are no e!pressions within the brackets -just optional commas.5 In this case2 the stub describes a di)ensioned type -see page GA.5 B5 &he s%mbol naming the re+erence is the name o+ a primitive t%pe or is the short name o+ a known class2 and there are one or more e!pressions within the brackets5 In this case2 the re+erence is to an array $onstr*$tor -see page ?G.F the e!pressions within the brackets must be convertible to non1negative whole numbers allowed +or arra% inde!es2 and the value is an arra% o+ the speci+ied t%pe2 dimensions2 and si=e5 I+ the stub is a sub1e!pression2 then its value and t%pe will be determined b% evaluating the e%pression -see page A:. within the parentheses5 I+ the stub starts with the name o+ a package2 then it will either describe a 8uali+ied t%pe -see page GA. or a 8uali+ied constructor -see page BA.5 Its t%pe will be same in either case2 and i+ a constructor then its value will be the value returned b% the constructor5 I+ the stub is not +ollowed b% +urther segments2 the +inal value and t%pe o+ the term is the value and t%pe o+ the stub5

Continuation evaluation
"ach segment o+ a term's continuation is evaluated +rom le+t to right2 according to the t%pe o+ the evaluation o+ the term so +ar -the $ontin*ation type. and the s%nta! o+ the new segment7 I+ the segment is a method call2 then its value and t%pe is the result o+ invoking the matching method in the class de+ining the continuation t%pe -or a superclass or subclass o+ that class.2 as described in Methods and Constr*$tors -see page B<.5 Note that method calls in term continuations cannot be constructors5 I+ the stub is an inde!ed re+erence2 then it will re+er to a propert% in the class de+ining the continuation t%pe -or a superclass o+ that class.5 &hat propert% will either be an undimensioned Net e!! string -t%pe Rexx. or a dimensioned arra%5 In either case2 it is evaluated in the same
Version 2.00 NetRexx Language Definition 51

wa% as an inde!ed re+erence +ound in the stub2 e!cept that it is not necessaril% in the current class2 cannot be an arra% constructor2 and cannot result in a dimensioned t%pe5 I+ the segment is a s%mbol2 then it re+ers to either a propert% or a method in the class de+ining the continuation t%pe -or a superclass o+ that class.5;B &he search +or the propert% or method starts with the class de+ining the continuation t%pe5 I+ a propert% name matches2 it is usedF i+ not2 a method o+ the same name and having no arguments -or onl% optional arguments. will match5 I+ neither propert% nor method is +ound2 then the same search is applied to each o+ the continuation class's superclasses in turn2 starting with the class that it e!tends5 As a convenient special case2 i+ the propert% or method is not +ound2 then i+ the segment is the +inal segment o+ the term and is the simple s%mbol length and the continuation t%pe is a single1dimensioned arra%2 then the segment evaluates to the si=e o+ the arra%5 &his will be a non1 negative whole number o+ an appropriate primitive t%pe -or o+ t%pe Rexx i+ there is no appropriate t%pe.5 &he +inal value and t%pe o+ the term is the value and t%pe determined b% the evaluation o+ the last segment o+ the continuation5

Arrays in terms
I+ a partiall%1evaluated term results in a dimensioned arra% -see page ?G.2 its t%pe is treated as t%pe Object so that evaluation o+ the term can continue5 6or e!ample2 in
ca=char[] "tosh" say ca.toString()

the variable ca is an arra% o+ charactersF in the e!pression on the second line the method toString() o+ the class Object will be +ound5;A

;B Unless parenthesis omission is disallowed b% an implementation option2 such as options strictargs2 in which case it can onl% be a propert%5 ;A In the re#eren$e i)ple)entation, this wo*ld ret*rn an identi#ier #or the o&5e$t. 52 NetRexx Language Definition Version 2.00

Methods and Constructors

Instructions in Net e!! are grouped into )ethods2 which are named routines that alwa%s belong to -are part o+. a $lass5 Methods are invoked b% being re+erenced in a term -see page G@.2 which ma% be part o+ an e!pression or be a clause in its own right -a method call instruction.5 In either case2 the s%nta! used +or a method invocation is7
symbol([expression[,expression]...])

&he sy)&ol2 which must be non1numeric2 is called the na)e o+ the method5 It is important to note that the name o+ the method must be +ollowed immediatel% b% the D(E2 with no blank in between2 or the construct will not be recogni=ed as a method call -a &lank operator would be assumed at that point instead.5 &he e%pressions -separated b% commas. between the parentheses are called the arg*)ents to the method5 "ach argument e!pression ma% include +urther method calls5 &he argument e!pressions are evaluated in turn +rom le+t to right and the resulting values are then passed to the method -the procedure +or locating the method is described below.5 &he method then e!ecutes some algorithm -usuall% dependent on an% arguments passed2 though arguments are not mandator%. and will eventuall% return a value5 &his value is then included in the original e!pression just as though the entire method re+erence had been replaced b% the name o+ a variable whose value is that returned data5 6or e!ample2 the substr method is provided +or strings o+ t%pe Rexx and could be used as7
c='abcdefghijk' a=c.substr(3,7) /* would set A to "cdefghi" */

,ere2 the value o+ the variable c is a string -o+ t%pe Rexx.5 &he substr -substring. method o+ the Rexx class is then invoked2 with arguments 3 and 72 on the value re+erred to b% c5 &hat is2 the the properties available to -the conte!t o+. the substr method are the properties constructed +rom the literal string 'abcdefghijk'5 &he method returns the substring o+ the value2 starting at the third character and o+ length seven characters5 A method ma% have a variable number o+ arguments7 onl% those re8uired need be speci+ied5 6or e!ample2 'ABCDEF'.substr(4) would return the string 'DEF'2 as the substr method will assume that the remainder o+ the string is to be returned i+ no length is provided5 Method invocations that take no arguments ma% omit the -empt%. parentheses in circumstances where this would not be ambiguous5 (ee the section on 1er)s -see page G@. +or details5 Implementation minimum. At least :> argument e!pressions should be allowed in a method call5

Method call instructions

*hen a clause in a method consists o+ just a term2 and the +inal part o+ the term is a method invocation2 the clause is a )ethod $all instr*$tion7 sy)&ol-Oe%pressionO2e%pressionP555P.F &he method is being called as a subroutine o+ the current method2 and an% returned value is discarded5 In this case -and in this case onl%.2 the method invoked need not return a value -that is2 the return
Version 2.00 NetRexx Language Definition 53

instruction that ends it need not speci+% an e!pression.5;? A method call instruction that is the +irst instruction in a constructor -see below. can onl% invoke the special constructors this and super5

Method resolution (search order)

Method resolution in Net e!! proceeds as +ollows7 I+ the method invocation is the +irst part -stub. o+ a term2 then7 :5 &he current class is searched +or the method -see below +or details o+ searching.5 ;5 I+ not +ound in the current class2 then the superclasses o+ the current class are searched2 starting with the class that the current class e!tends5 <5 I+ still not +ound2 then the classes listed in the uses phrase o+ the class instruction are searched +or the method2 which in this case must be a static method -see page :>>.5 "ach class +rom the list is searched +or the method2 and then its superclasses are searched upwards +rom the classF this process is repeated +or each o+ the classes2 in the order speci+ied in the list5 G5 I+ still not +ound2 the method invocation must be a constructor -see below. and so the method name2 which ma% be 8uali+ied b% a package name2 should match the name o+ a primitive t%pe or a known class -t%pe.5 &he speci+ied class is then searched +or a constructor that matches the method invocation5 I+ the method invocation is not the +irst part o+ the term2 then the evaluation o+ the parts o+ the term to the le+t o+ the method invocation will have resulted in a value -or just a t%pe.2 which will have a known t%pe -the continuation t%pe.5 &hen7 :5 &he class that de+ines the continuation t%pe is searched +or the method -see below +or details o+ searching.5 ;5 I+ not +ound in that class2 then the superclasses o+ that class are searched2 starting with the class that that class e!tends5 I+ the search did not +ind a method2 an error is reported5 I+ the search did +ind a method2 that is the method which is invoked2 e!cept in one case7 I+ the evaluation so +ar has resulted in a value -an object.2 then that value ma% have a t%pe which is a subclass o+ the continuation t%pe5 I+2 within that subclass2 there is a method that e!actl% overrides -see page BB. the method that was +ound in the search2 then the method in the subclass is invoked5 &his case occurs when an object is earlier assigned to a variable o+ a t%pe which is a superclass o+ the t%pe o+ the object5 &his t%pe simpli+ication hides the real t%pe o+ the object +rom the language processor2 though it can be determined when the program is e!ecuted5 (earching +or a method in a class proceeds as +ollows7 :5 Candidate methods in the class are selected5 &o be a candidate method7 the method must have the same name as the method invocation -independent o+ the case -see page GG. o+ the letters o+ the name.
;? A method call instruction is e8uivalent to the call instruction o+ other languages2 e!cept that no ke%word is re8uired5 54 NetRexx Language Definition Version 2.00

 the method must have the same number o+ arguments as the method invocation -or more arguments2 provided that the remainder are shown as optional in the method de+inition. it must be possible to assign the result o+ each argument e!pression to the t%pe o+ the corresponding argument in the method de+inition -i+ strict t%pe checking is in e++ect2 the t%pes must match e!actl%.5 ;5 I+ there are no candidate methods then the search is completeF the method was not +ound5 <5 I+ there is just one candidate method2 that method is usedF the search is complete5 G5 I+ there is more than one candidate method2 the sum o+ the costs o+ the conversions -see page A>. +rom the t%pe o+ each argument e!pression to the t%pe o+ the corresponding argument de+ined +or the method is computed +or each candidate method5 B5 &he costs o+ those candidates -i+ an%. whose names match the method invocation e!actl%2 including in case2 are comparedF i+ one has a lower cost than all others2 that method is used and the search is complete5 A5 &he costs o+ all the candidates are comparedF i+ one has a lower cost than all others2 that method is used and the search is complete5 ?5 I+ there remain two or more candidates with the same minimum cost2 the method invocation is ambiguous2 and an error is reported5 Note. *hen a method is +ound in a class2 superclasses o+ that class are not searched +or methods2 even though a lower1cost method ma% e!ist in a superclass5

Method overriding
A method is said to e%a$tly o"erride a method in another class i+ :5 the method in the other class has the same name as the current method ;5 the method in the other class is not private <5 the other class is a superclass o+ the current class2 or is a class that the current class implements -or is a superclass o+ one o+ those classes.5 G5 the number and t%pe o+ the arguments o+ the method in the other class e!actl% match the number and t%pe o+ the arguments o+ the current method -where subsets are also checked2 i+ either method has optional arguments.5 6or e!ample2 the Rexx class includes a substr -see page :AA. method2 which takes +rom one to three strings o+ t%pe Rexx5 In the class7
class mystring extends Rexx method substr(n=Rexx, length=Rexx) return this.reverse.substr(n, length) method substr(n=int, length=int) return this.reverse.substr(Rexx n, Rexx length)

the +irst method e!actl% overrides the substr method in the Rexx class2 but the second does not2 because the t%pes o+ the arguments do not match5 A method that e!actl% overrides a method is assumed to be an e!tension o+ the overridden method2 to be used in the same wa%5 6or such a method2 the +ollowing rules appl%7

Version 2.00

NetRexx Language Definition

55

 It must return a value o+ the same t%pe as the overridden method -or none2 i+ the overridden method returns none.5 It must be at least as visible as the overridden routine5 6or e!ample2 i+ the overridden routine is public then it must also be public5 I+ the overridden method is static then it must also be static5 I+ the overridden method is not static then it must not be static5 I+ the underl%ing implementation checks e!ceptions -see page :B;.2 onl% those checked e!ceptions that are signalled b% the overridden method ma% be le+t uncaught in the current method5

Constructor methods
As described above2 methods are usuall% invoked in the conte!t o+ an e!isting value or t%pe5 A special kind o+ method2 called a constructor method2 is used to actuall% create a value o+ a given t%pe -an object.5 Constructor methods alwa%s have the same short name as the class in which the% are +ound2 and construct and return a value o+ the t%pe de+ined b% that class -sometimes known as an instan$e o+ that class.5 I+ the class is part o+ a package2 then the constructor call ma% be 8uali+ied b% the package name5 %xample con,tructor,.
File('Dan.yr.Ogof') java.io.File('Speleogroup.letter') Rexx('some words') netrexx.lang.Rexx(1)

&here will alwa%s be at least one constructor i+ values can be created +or a class5 Net e!! will add a de+ault public constructor that takes no arguments i+ no constructors are provided2 unless the components o+ the class are all static or constant2 or the class is an inter+ace class5 All constructors +ollow the same rules as other methods2 and in addition7 :5 Constructor calls alwa%s include parentheses in the s%nta!2 even i+ no arguments are supplied5 &his distinguishes them +rom a re+erence to the t%pe o+ the same name5 ;5 Constructors must call a constructor o+ their superclass -the class the% e!tend. be+ore the% carr% out an% initiali=ation o+ their own5 &his is so an% initiali=ation carried out b% the superclass takes place2 and at the appropriate moment5 /nl% a+ter this call is complete can the% make an% re+erence to the special words this or super -see page :<>.5 &here+ore2 the +irst instruction in a constructor must be either a call to the superclass2 using the special constructor super() -with optional arguments.2 or a call to to another constructor in the same class2 using the special constructor this() -with optional arguments.5 In the latter case2 eventuall% a constructor that e!plicitl% calls super() will be invoked and the chain o+ local constructor calls ends5 As a convenience2 Net e!! will add a de+ault call to super()2 with no arguments2 i+ the +irst instruction in a constructor is not a call to this() or super()5 <5 &he properties o+ a constructed value are initiali=ed2 in the order given in the program2 a+ter the call to super() -whether implicit or e!plicit.5

56

NetRexx Language Definition

Version 2.00

G5 B% de+inition2 constructors create a value -object. whose t%pe is de+ined b% the current class2 and then return that value +or use5 &here+ore2 the returns ke%word on the method instruction -see page C@. that introduces the constructor is optional -i+ given2 the t%pe speci+ied must be that o+ the class.5 (imilarl%2 the onl% possible +orms o+ the return instruction used in a constructor are either Dreturn this;E2 which returns the value that has just been constructed2 or just Dreturn;E2 in which case2 the DthisE is assumed -this +orm will be assumed at the end o+ a method2 as usual2 i+ necessar%.5 ,ere is an e!ample o+ a class with two constructors2 showing the use o+ this() and super()2 and taking advantage o+ some o+ the assumptions7
class MyChars extends SomeClass properties private /* the data 'in' the object */ value=char[] /* construct the object from a char array */ method MyChars(array=char[]) /* initialize superclass */ super() value=array -- save the value /* construct the object from a String */ method MyChars(s=String) /* convert to char[] and use the above */ this(s.toCharArray())

/bjects o+ t%pe MyChars could then be created thus7

myvar=MyChars("From a string")

or b% using an argument that has t%pe char[]5

Version 2.00

NetRexx Language Definition

57

Type conversions
As described in the section on 1ypes and $lasses -see page GA.2 all values that are manipulated in Net e!! have an associated t%pe5 /n occasion2 a value involved in some operation ma% have a di++erent t%pe than is needed2 and in this case conversion o+ a value +rom one t%pe to another is necessar%5 Net e!! considerabl% simpli+ies the task o+ programming2 without losing robustness2 b% making man% such conversions automatic5 It will automaticall% convert values providing that there is no loss o+ in+ormation caused b% the automatic conversion -or i+ there is2 an e!ception would be raised.5 Conversions can also be made e!plicit b% concatenating a t%pe -see page AG. to a value and in this case less robust conversions -sometimes known as $asts. ma% be e++ected5 (ee below +or details o+ the permitted automatic and e!plicit conversions5 Almost all conversions carr% some risk o+ +ailure2 or have a per+ormance cost2 and so it is e!pected that implementations will provide options to either report costl% conversions or re8uire that programmers make all conversions e!plicit5;@ (uch options might be recommended +or certain critical programming tasks2 but are not necessar% +or general programming5

Permitted automatic conversions

In general2 the semantics o+ a t%pe is unknown2 and so conversion -+rom a so*r$e type to a target type. is onl% possible in the +ollowing cases7 &he target t%pe and the source t%pe are identical -the trivial case.5 &he target t%pe is a superclass o+ the source t%pe2 or is an inter+ace class implemented b% the source t%pe5 &his is called type si)pli#i$ation2 and in this case the value is not altered2 no in+ormation is lost2 and an e!plicit conversion ma% be used later to revert the value to its original t%pe5 &he source t%pe has a dimension2 and the target t%pe is Object5 &he source t%pe is null and the target t%pe is not primitive5 &he target and source t%pes have known semantics -that is2 the% are Dwell1knownE to the implementation. and the conversion can be e++ected without loss o+ in+ormation -other than knowledge o+ the original t%pe.5 &hese are called well;known $on"ersions5 Necessaril%2 the well1known conversions are implementation1dependent2 in that the% depend on the standard classes +or the implementation and on the primitive t%pes supported -i+ an%.5 "8uall%2 it is this automatic conversion between strings and the primitive t%pes o+ an implementation that o++er the greatest simpli+ications o+ Net e!! programming5 6or e!ample2 i+ the implementation supported an int binar% t%pe -perhaps a <;1bit integer. then this can sa+el% be converted to a Net e!! string -o+ t%pe Rexx.5 ,ence a value o+ t%pe int can be added to a number which is a Net e!! string -resulting in a Net e!! string. without concern over the di++erence in the t%pes o+ the two terms used in the operation5 Conversel%2 converting a long integer to a shorter one without checking +or truncation o+ signi+icant digits could cause a loss o+ in+ormation and would not be permitted5
;@ In the re#eren$e i)ple)entation, options strictassign )ay &e *sed to disallow a*to)ati$ $on"ersions. 58 NetRexx Language Definition Version 2.00

In the re#eren$e i)ple)entation, the se)anti$s o# ea$h o# the #ollowing types is known to the lang*age pro$essor :the #irst #o*r are all string types, and the re)ainder are known as &inary n*)&ers>8 netrexx.lang.Rexx 7 the 3et/e%% string $lass java.lang.String 7 the Ca"a string $lass char 7 the Ca"a pri)iti"e whi$h represents a single $hara$ter char[] 7 an array o# chars boolean 7 a single;&it pri)iti"e byte, short, int, long, 7 signed integer pri)iti"es :0, 1 , ,2, or D &its> float, double 7 #loating;point pri)iti"es :,2 or D &its> 6nder the r*les des$ri&ed a&o"e, the #ollowing well;known $on"ersions are per)itted8 Rexx to binary number, char[], String, or char String to binary number, char[], Rexx, or char char to binary number, char[], String, or Rexx char[] to binary number, Rexx, String, or char binary number to Rexx, String, char[], or char binary number to binary number :i# no loss o# in#or)ation $an take pla$e 7 no sign, high order digits, de$i)al part, or e%ponent in#or)ation wo*ld &e lost> Notes: :5 .o)e o# the $on"ersions $an $a*se a r*n;ti)e error :e%$eption>, as when a string represents a n*)&er that is too large #or an int and a $on"ersion to int is atte)pted, or when a string that does not $ontain e%a$tly one $hara$ter is $on"erted to a char. ;5 1he boolean pri)iti"e is treated as a &inary n*)&er that )ay only take the "al*es 0 or 1. ! &oolean )ay there#ore &e $on"erted to any &inary n*)&er type, as well as any o# the string :or char> types, as the $hara$ter @0A or @1A. .i)ilarly, any &inary n*)&er or string $an &e $on"erted to &oolean :and )*st ha"e a "al*e o# 0 or 1 #or the $on"ersion to s*$$eed>. <5 1he char type is a single;$hara$ter string :it is not a n*)&er that represents the en$oding o# the $hara$ter>.

Permitted explicit conversions

"!plicit conversions are permitted +or all permitted automatic conversions and2 in addition2 when7 &he target t%pe is a subclass o+ the source t%pe2 or implements the source t%pe5 &his conversion will +ail i+ the value being converted was not originall% o+ the target t%pe -or a subclass o+ the target t%pe.5 Both the source and target t%pes are primitive and -depending on the implementation. the conversion ma% +ail or truncate in+ormation5 &he target t%pe is Rexx or a well1known string t%pe -all values have an e!plicit string representation.5
Version 2.00 NetRexx Language Definition 59

Costs of conversions
All conversions are considered to have a cost2 and2 +or permitted automatic conversions2 these costs are used to select a method +or e!ecution when several possibilities arise2 using the algorithm described in Methods and Constr*$tors -see page BG.5 6or permitted automatic conversions2 the cost o+ a conversion +rom a so*r$e type to a target type will range +rom =ero through some arbitrar% positive value2 constrained b% the +ollowing rules7 &he cost is =ero onl% i+ the source and target t%pes are the same2 or i+ the source t%pe is null and the target t%pe is not primitive5 Conversions +rom a given primitive source t%pe to di++erent primitive target t%pes should have di++erent costs5 6or e!ample2 conversion o+ an @1bit number to a AG1bit number might cost more than conversion o+ a @1bit number to a <;1bit number5 Conversions that ma% re8uire the creation o+ a new object cost more than those that can never re8uire the creation o+ a new object5 Conversions that ma% +ail -raise an e!ception. cost more than those that ma% re8uire the creation o+ an object but can never +ail5 *ithin these constraints2 e!act costs are arbitrar%2 and -because the% mostl% involve implementation1 dependent primitive t%pes. are necessaril% implementation1dependent5 &he intent is that the Dbest per+ormanceE method be selected when there is a possibilit% o+ more than one5

60

NetRexx Language Definition

Version 2.00

Expressions and Operators

Man% clauses can include e%pressions5 "!pressions in Net e!! are a general mechanism +or combining one or more data items in various wa%s to produce a result2 usuall% di++erent +rom the original data5 "!pressions consist o+ one or more terms -see page G@.2 such as literal strings2 s%mbols2 method calls2 or sub1e!pressions2 and =ero or more operators that denote operations to be carried out on terms5 Most operators act on two terms2 and there will be at least one o+ these dyadi$ operators between ever% pair o+ terms5;C &here are also pre#i% -monadic. operators2 that act on the term that is immediatel% to the right o+ the operator5 &here ma% be one or more pre+i! operators to the le+t o+ an% term2 provided that adjacent pre+i! operators are di++erent5 "valuation o+ an e!pression is le+t to right2 modi+ied b% parentheses and b% operator precedence -see page AA. in the usual DalgebraicE manner5 "!pressions are wholl% evaluated2 e!cept when an error occurs during evaluation5 As each term is used in an e!pression2 it is evaluated as appropriate and its value -and the t%pe o+ that value. are determined5 &he result o+ an% operation is also a value2 which ma% be a character string2 a data object o+ some other t%pe2 or -in special circumstances. a binar% representation o+ a character or number5 &he t%pe o+ the result is well1de+ined2 and depends on the t%pes o+ an% terms involved in an operation and the operation carried out5 Conse8uentl%2 the result o+ evaluating an% e!pression is a value which has a known t%pe5 Note that the Net e!! language imposes no restriction on the ma!imum si=e o+ results2 but there will usuall% be some practical limitation dependent upon the amount o+ storage and other resources available during e!ecution5

Operators
&he operators in Net e!! are constructed +rom one or more operator characters -see page G<.5 Blanks -and comments. adjacent to operator characters have no e++ect on the operator2 and so the operators constructed +rom more than one character ma% have embedded blanks and comments5 In addition2 blank characters2 where the% occur between tokens within e!pressions but are not adjacent to another operator2 also act as an operator5 &he operators ma% be subdivided into +ive groups7 concatenation2 arithmetic2 comparative2 logical2 and t%pe operators5 &he +irst +our groups work with terms whose t%pe is Dwell1knownE -that is2 strings2 or known t%pes that can be be converted to strings without in+ormation loss.5 &he operations in these groups are de+ined in terms o+ their operations on strings5

;C /ne operator2 direct concatenation2 is implied i+ two terms abut -see page A;.5 Version 2.00 NetRexx Language Definition 61

Concatenation &he concatenation operators are used to combine two strings to +orm one string b% appending the second string to the right1hand end o+ the +irst string5 &he concatenation ma% occur with or without an intervening blank7
(blank) ||

Concatenate terms with one blank in between5 Concatenate without an intervening blank5

(abuttal) Concatenate without an intervening blank5

Concatenation without a blank ma% be +orced b% using the || operator2 but it is use+ul to remember that when two terms are adjacent and are not separated b% an operator2<> the% will be concatenated in the same wa%5 &his is the a&*ttal operation5 6or e!ample2 i+ the variable Total had the value '37.4'2 then Total'%' would evaluate to '37.4%'5 0alues that are not strings are +irst converted to strings be+ore concatenation5 Arithmetic Character strings that are numbers -see page AB. ma% be combined using the arithmetic operators7
+ * / % //

Add5 (ubtract5 Multipl%5 #ivide5 Integer divide5 #ivide and return the integer part o+ the result5 emainder5 #ivide and return the remainder -this is not modulo2 as the result ma% be negative.5 $ower5 aise a number to a whole number power5 (ame as the subtraction7 D0-numberE5 (ame as the addition7 D0+numberE5

** Prefix Prefix +

&he section on 3*)&ers and !rith)eti$ -see page :G>. describes numeric precision2 the +ormat o+ valid numbers2 and the operation rules +or arithmetic5 Note that i+ an arithmetic result is shown in e!ponential notation2 then it is likel% that rounding has occurred5 In binar% classes -see page @>.2 the arithmetic operators will use binar% arithmetic i+ both terms involved have values which are binar% numbers5 &he section on Binary "al*es and operations -see page :GC. describes binar% arithmetic5 Comparative &he comparative operators compare two terms and return the value '1' i+ the result o+ the comparison is true2 or '0' otherwise5 &wo sets o+ operators are de+ined7 the stri$t comparisons and the nor)al comparisons5 &he strict comparative operators all have one o+ the characters de+ining the operator doubled5 &he D==E2 and D\==E operators test +or strict e8ualit% or ine8ualit% between
<> &his can occur when the terms are s%ntacticall% distinct -such as a literal string and a s%mbol.5 62 NetRexx Language Definition Version 2.00

two strings5 &wo strings must be identical to be considered strictl% e8ual5 (imilarl%2 the other strict comparative operators -such as D>>E or D<<E. carr% out a simple le+t1 to1right character1b%1character comparison2 with no padding o+ either o+ the strings being compared5 I+ one string is shorter than2 and is a leading sub1string o+2 another then it is smaller -less than. the other5 (trict comparison operations are case sensitive2 and the e!act collating order ma% depend on the character set used +or the implementation5<: 6or all the other comparative operators2 i+ 'ot" the terms involved are numeric2<; a numeric comparison -in which leading =eros are ignored2 et$.. is e++ectedF otherwise2 both terms are treated as character strings5 6or this character string comparison2 leading and trailing blanks are ignored2 and then the shorter string is padded with blanks on the right5 &he character comparison operation takes place +rom le+t to right2 and is not case sensitive -that is2 DYesE compares e8ual to DyesE.5 As +or strict comparisons2 the e!act collating order ma% depend on the character set used +or the implementation5 &he comparative operators return true -'1'. i+ the terms are7 Normal comparative operators7
= \= > < ><, <> >=, \< <=, \>

"8ual -numericall% or when padded2 et$..5 Not e8ual -inverse o+ W.5 )reater than5 Less than5 )reater than or less than -same as DNot e8ualE.5 )reater than or e8ual to2 not less than5 Less than or e8ual to2 not greater than5 (trictl% e8ual -identical.5 (trictl% not e8ual -inverse o+ ==.5 (trictl% greater than5 (trictl% less than5 (trictl% greater than or e8ual to2 strictl% not less than5 (trictl% less than or e8ual to2 strictl% not greater than5

Strict comparative operators7

== \== >> << >>=, \<< <<=, \>>

&he e8ual and not e8ual operators -D=E2 D==E2 D\=E2 and D\==E. ma% be used to compare two objects which are not strings +or e8ualit%2 i+ the implementation allows them to be compared -usuall% the% will need to be o+ the same t%pe.5 &he strict operators test whether the two objects are in +act the same object2<< and the normal
<: 6or e!ample2 in an A(CII or Unicode environment2 the digits >1C are lower than the alphabetics2 and lowercase alphabetics are higher than uppercase alphabetics5 In an "BC#IC environment2 lowercase alphabetics precede uppercase2 but the digits are higher than all the alphabetics5 <; &hat is2 i+ the% can be compared numericall% without error5 << Note that two distinct objects compared in this wa% ma% contain values -properties. that are identical2 %et the% will not compare e8ual as the% are not the same object5 Version 2.00 NetRexx Language Definition 63

operators ma% provide a more rela!ed comparison2 i+ available to the implementation5<G In binar% classes -see page @>.2 all the comparative operators will use binar% arithmetic to e++ect the comparison i+ both terms involved have values which are binar% numbers5 In this case2 there is no distinction between the strict and the normal comparative operators5 &he section on Binary "al*es and operations -see page :GC. describes the binar% arithmetic used +or comparisons5 Logical (Boolean) A character string is taken to have the value D+alseE i+ it is '0'2 and DtrueE i+ it is '1'5 &he logical operators take one or two such values -values other than '0' or '1' are not allowed. and return '0' or '1' as appropriate7
& | && Prefix \

And5 eturns : i+ both terms are true5 Inclusive or5 eturns : i+ either term is true5 "!clusive or5 eturns : i+ either -but not both. is true5 Logical not5 NegatesF : becomes > and "i$e "ersa5

In binar% classes -see page @>.2 the logical operators will act on all bits in the values i+ both terms involved have values which are boolean or integers5 &he section on Binary "al*es and operations -see page :GC. describes this in more detail5 Type (everal o+ the operators alread% described can be used to carr% out operations related to t%pes5 (peci+icall%7 An% o+ the concatenation operators ma% be used +or type $on$atenation2 which concatenates a t%pe to a value5 All three operators -blank2 D||E2 and abuttal. have the same e++ect2 which is to convert -see page B@.<B the value to the t%pe speci+ied -i+ the conversion is not possible2 an error is reported or an e!ception is signalled.5 &he t%pe must be on the le+t1hand side o+ the operator5 %xample,.
String "abc" int (a+1) long 1 Exception e InputStream myfile

A t%pe on the le+t hand side o+ an operator that could be a pre+i! operator -+2 -2 or \. is assumed to impl% t%pe concatenation a+ter the pre+i! operator is applied to the right1hand operand2 as though an e!plicit concatenation operator were placed be+ore the pre+i! operator5 6or e!ample7

<G In the re#eren$e i)ple)entation, the equals )ethod is *sed #or nor)al $o)parisons. +here not pro"ided &y a type, this is i)ple)ented &y the ?&5e$t $lass as a stri$t $o)parison. <B &his is sometimes known as $asting 64 NetRexx Language Definition Version 2.00

x=int -y

means that -y is evaluated2 and then the result is converted to int be+ore being assigned to x5<A &he Dless than or e8ualE and the Dgreater than or e8ualE operators -D<=E and D>=E. ma% be used with a t%pe on either side o+ the operator2 or on both sides5 In this case2 the% test whether a value or t%pe is a subclass o+2 or is the same as2 a t%pe2 or vice versa5 %xample,.
if i<=Object then say 'I is an Object' if String>=i then say 'I is a String' if String<=Object then say 'String is an Object'

&he precedence o+ these operators is not a++ected b% their being used with t%pes as operands5

Numbers
&he arithmetic operators above re8uire that both terms involved be numbersF similarl% some o+ the comparative operators carr% out a numeric comparison i+ both terms are numbers5 Numbers are introduced and de+ined in detail in the section on 3*)&ers and arith)eti$ -see page :G>.5 In summar%2 n*)&ers are character strings consisting o+ one or more decimal digits optionall% pre+i!ed b% a plus or minus sign2 and optionall% including a single period -D.E. which then represents a decimal point5 A number ma% also have a power o+ ten su++i!ed in conventional e!ponential notation7 an DEE -uppercase or lowercase. +ollowed b% a plus or minus sign then +ollowed b% one or more decimal digits de+ining the power o+ ten5 Numbers ma% have leading blanks -be+ore andMor a+ter the sign2 i+ an%. and ma% have trailing blanks5 Blanks ma% not be embedded among the digits o+ a number or in the e!ponential part5 %xample,.
'12' '-17.9' '127.0650' '73e+128' ' + 7.9E-5 ' '00E+000'

Note that the se8uence -17.9 -without 8uotes. in an e!pression is not simpl% a number5 It is a minus operator -which ma% be pre+i! minus i+ there is no term to the le+t o+ it. +ollowed b% a positive number5 &he result o+ the operation will be a number5 A whole n*)&er -see page :G?. in Net e!! is a number that has a =ero -or no. decimal part5 Implementation minimum. All implementations must support C1digit arithmetic5 In unavoidable cases this ma% be limited to integers onl%2 and in this case the divide operator -D/E. must not be supported5 I+ e!ponents are supported in an implementation2 then the% must be supported +or e!ponents whose absolute value is at least as large as the largest number that can be e!pressed as an e!act integer in de+ault precision2 i.e.2 CCCCCCCCC5

<A &his could also have been written x=int (-y)5 Version 2.00 NetRexx Language Definition 65

Parentheses and operator precedence

"!pression evaluation is +rom le+t to rightF this is modi+ied b% parentheses and b% operator precedence7 *hen parentheses are encountered2 other than those that identi+% method calls -see page B<.2 the entire s*&;e%pression delimited b% the parentheses is evaluated immediatel% when the term is re8uired5 *hen the se8uence
term1 operator1 term2 operator2 term3

is encountered2 and operator2 has a higher precedence than operator12 then the operation (term2 operator2 term3) is evaluated +irst5 &he same rule is applied repeatedl% as necessar%5 Note2 however2 that individual terms are evaluated +rom le+t to right in the e!pression -that is2 as soon as the% are encountered.5 It is onl% the order o+ operation, that is a++ected b% the precedence rules5 6or e!ample2 D*E -multipl%. has a higher precedence than D+E -add.2 so 3+2*5 will evaluate to :< -rather than the ;B that would result i+ strict le+t to right evaluation occurred.5 &o +orce the addition to be per+ormed be+ore the multiplication the e!pression would be written (3+2)*52 where the +irst three tokens have been +ormed into a sub1e!pression b% the addition o+ parentheses5 &he order o+ precedence o+ the operators is -highest at the top.7 Pre#i% operators Power operator !ddition and s*&tra$tion Con$atenation Co)parati"e operators !nd ?r, e%$l*si"e or
+ ** / || > < (abuttal) <= >= << \>> et$. % // \

M*ltipli$ation and di"ision *

+

(blank) = & | && ==

I+2 +or e!ample2 the s%mbol a is a variable whose value is '3'2 and day is a variable with the value 'Monday'2 then7
a+5 a-4*2 a/2 a%2 0.5**2 (a+1)>7 ' '='' ' '=='' ' '\=='' (a+1)*3=12 '077'>'11' '077'>>'11' 'abc'>>'ab' 'If it is' day day.substr(2,3) '!'day'!'
66

== == == == == == == == == == == == == == == ==

'8' '-5' '1.5' '1' '0.25' '0' /* '1' /* '0' /* '1' /* '1' /* '1' /* '0' /* '1' /* 'If it is Monday' 'ond' '!Monday!'

that that that that that that that that

is, is, is, is, is, is, is, is,

False True False True True True False True

*/ */ */ */ */ */ */ */

NetRexx Language Definition

Version 2.00

Note. &he Net e!! order o+ precedence usuall% causes no di++icult%2 as it is the same as in conventional algebra and other computer languages5 &here are two di++erences +rom some common notationsF the pre+i! minus operator alwa%s has a higher priorit% than the power operator2 and power operators -like other operators. are evaluated le+t1to1right5 &hus
-3**2 -(2+1)**2 2**2**3 == == == 9 9 64 /* not -9 */ /* not -9 */ /* not 256 */

&hese rules were +ound to match the e!pectations o+ the majorit% o+ users when the e!! language was +irst designed2 and Net e!! +ollows the same rules5

Version 2.00

NetRexx Language Definition

67

Clauses and Instructions

Clauses -see page G>. are recogni=ed2 and can use+ull% be classi+ied2 in the +ollowing order7 3*ll $la*ses A clause that is empt% or comprises onl% blanks2 comments2 and continuations is a n*ll $la*se and is completel% ignored b% Net e!! -e!cept that i+ it includes a comment it will be traced2 i+ reached during e!ecution.5 Note. A null clause is not an instruction2 so -+or e!ample. putting an e!tra semicolon a+ter the then or else in an if instruction is not e8uivalent to putting a dumm% instruction -as it would be in C or $LMI.5 &he nop instruction is provided +or this purpose5 !ssign)ents (ingle clauses within a class and o+ the +orm ter)=e%pression; are instructions known as assign)ents -see page AC.5 An assignment gives a variable2 identi+ied b% the ter)2 a t%pe or a new value5 In just one conte!t2 where propert% assignments are e!pected -be+ore the +irst method in a class.2 the D=E and the e!pression ma% be omittedF in this case2 the term -and hence the entire clause. will alwa%s be a simple non1numeric s%mbol which names the propert% Method $all instr*$tions Eeyword instr*$tions A method call instruction -see page B<. is a clause within a method that comprises a single term that is2 or ends in2 a method invocation5 A keyword instr*$tion consists o+ one or more clauses2 the +irst o+ which starts with a non1numeric s%mbol which is not the name o+ a variable or propert% in the current class -i+ an%. and is immediatel% +ollowed b% a blank2 a semicolon -which ma% be implied b% the end o+ a line.2 a literal string2 or an operator -other than D=E2 which would impl% an assignment.5 &his s%mbol2 the keyword2 identi+ies the instruction5 Ke%word instructions control the e!ternal inter+aces2 the +low o+ control2 and so on5 (ome ke%word instructions -see page ??. -do2 if2 loop2 or select. can include nested instructions5

68

NetRexx Language Definition

Version 2.00

Assignments and Variables

A "aria&le is a named item whose value ma% be changed during the course o+ e!ecution o+ a Net e!! program5 &he process o+ changing the value o+ a variable is called assigning a new value to it5 "ach variable has an associated t%pe2 which cannot change during the e!ecution o+ a programF there+ore2 the values assigned to a given variable must alwa%s have a t%pe that can sa+el% be assigned to that variable5 0ariables ma% be assigned a new value b% the method or parse instructions2 but the most common wa% o+ changing the value o+ a variable is b% using an assign)ent instr*$tion5 An% clause within a class and o+ the +orm7 assign)entF where assign)ent is7 ter)We%pression is taken to be an assignment instruction5 &he result o+ the e%pression becomes the new value o+ the variable named b% the ter) to the le+t o+ the e8uals sign5 *hen the term is simpl% a s%mbol2 this is called the na)e o+ the variable5 %xample.
/* Next line gives FRED the value 'Frederic' */ fred='Frederic'

&he s%mbol naming the variable cannot begin with a digit ->1C.5<? *ithin a Net e!! program2 variable names are not case1sensitive -+or e!ample2 the names fred2 Fred2 and FRED re+er to the same variable.5 *here public names are e!posed -+or e!ample2 the names o+ properties2 classes2 and methods2 and in cross1re+erence listings. the case used +or the name will be that used when the name was +irst introduced -D+irstE is determined staticall% b% position in a program rather than d%namicall%.5 (imilarl%2 the t%pe o+ a Net e!! variable is determined b% the t%pe o+ the value o+ the e!pression that is +irst assigned to it5<@ 6or subse8uent assignments2 it is an error to assign a value to a variable with a t%pe mismatch unless the language processor can determine that the value can be assigned sa+el% to the t%pe o+ the variable5 In practice2 this means that the t%pes must match e!actl%2 be a simpli+ication2 or both be Dwell1knownE t%pes such as Rexx2 String2 int2 et$.2 +or which sa+e conversions are de+ined5 &he possibilities are described in the section on Con"ersions -see page B@.5<C

<? *ithout this restriction on the +irst character o+ a variable name2 it would be possible to rede+ine a number2 in that +or e!ample the assignment D3=4;E would give a variable called D3E the value '4'5 <@ (ince Net e!! in+ers the t%pe o+ a variable +rom usage2 substantial programs can be written without introducing e!plicit t%pe declarations2 although these are allowed5 <C Implementations ma% provide +or a stricter rule +or assignment -where the t%pes must be identical.2 controlled b% the options instruction5 Version 2.00 NetRexx Language Definition 69

6or e!ample2 i+ there are t%pes -classes. called ibm.util.hex2 RunKnown2 and Window2 then7
hexy=ibm.util.hex(3) rk=RunKnown() fred=Window(10, 20) s="Los Lagos" j=5 -----'hexy' has type 'ibm.util.hex' 'rk' has type 'RunKnown' 'fred' has type 'Window' 's' has type 'Rexx' 'j' has type 'Rexx'

&he +irst three e!amples invoke the $onstr*$tor method +or the t%pe to construct a value -an object.5 A constructor method alwa%s has the same name as the class to which it belongs2 and returns a new value o+ that t%pe5 Constructor methods are described in detail in Methods and Constr*$tors -see page B<.5 &he last two e!amples above illustrate that2 b% de+ault2 the t%pes o+ literal strings and numbers are Net e!! strings -t%pe Rexx. and so variables tend to be o+ t%pe Rexx5 &his simpli+ies the language and makes it eas% to learn2 as man% use+ul programs can be written solel% using the power+ul Rexx t%pe5 $otentiall% more e++icient -though less human1oriented. primitive or built1in t%pes +or literals will be used in binar% classes -see page @>.5 I# the e%a)ples a&o"e were in a &inary $lass, then, in the re#eren$e i)ple)entation, the types o# s and j wo*ld ha"e &een java.lang.String and int respe$ti"ely. A variable ma% be introduced -DdeclaredE. without giving it an initial value b% simpl% assigning a t%pe to it7
i=int r=Rexx f=java.io.File

,ere2 the e!pression to the right o+ the D=E simpl% evaluates to a t%pe with no value5

The use and scope of variables

Net e!! variables all +ollow the same rules o+ assignment2 but are used in di++erent conte!ts5 &hese are7 Properties 0ariables which name the values -the data. owned b% an object o+ the t%pe de+ined b% the class are called properties5 *hen an object is constructed b% the class2 its properties are created and are initiali=ed to either a de+ault value -null or2 +or variables o+ primitive t%pe2 an implementation1de+ined value2 t%picall% >. or to a value provided b% the programmer5 &he attributes o+ properties can be changed b% the properties instruction -see page ::;.5 6or e!ample2 properties ma% also be $onstant2 which means that the% are initiali=ed when the class is +irst loaded and do not change therea+ter5 Method arg*)ents 2o$al "aria&les *hen a method is invoked2 arguments ma% be passed to it5 &hese )ethod arg*)ents are assigned to the variables named on the method instruction -see page C@. that introduces the method5 0ariables that are known onl% within a method are called lo$al "aria&lesF each time a method is invoked a distinct set o+ local variables is available5 Local variables are normall% given an initial value b% the programmer5 I+ the% are not2 the% are initiali=ed to a de+ault value -null or2 +or variables o+ primitive t%pe2 an implementation1de+ined value2 t%picall% >.5

In order +or t%pes to be determined and t%pe1checking to be possible at Dcompile1timeE2 and easil% determined b% inspection2 the use and t%pe o+ ever% variable is determined b% its position in the
70 NetRexx Language Definition Version 2.00

program2 not b% the order in which assignments are e!ecuted5 &hat is2 variable t%ping is static5 &he visibilit% o+ a variable depends on its use5 $roperties are visible to all methods in a classF method arguments and local variables are onl% visible within the method in which the% appear5 In particular7 *ithin a class2 properties have uni8ue names -the% cannot be overridden b% method arguments or b% local variables within methods.F this avoids error1prone ambiguit%5 *ithin a method2 a method argument acts like a local variable -that is2 it is in the same name1 space as local variables2 and can be assigned new values.F it can be considered to be a local variable that is assigned a value just be+ore the bod% o+ the method is e!ecuted5 &here cannot be both a method argument and a local variable in a method with the same name5 *ithin methods2 variables can take onl% one t%pe2 the t%pe assigned to them when +irst encountered in the method -in a strict Dph%sicalE sense2 that is2 as parsed +rom top to bottom o+ the program and +rom le+t to right on each line.5 (ince methods tend to be small2 there is no local scoping o+ variables inside the constructs within a method5G> &hus2 in this e!ample7
method iszero(x) if x=0 then qualifier='is zero' else qualifier='is not zero' say 'The argument' qualifier'.'

the variable qualifier is known throughout the method and hence has a known t%pe and value when the say instruction is e!ecuted5 &o summari=e7 a s%mbol that names a variable in the current class either re+ers to a propert% -and in an% use o+ it within the class re+ers to that propert%.2 or it re+ers to a variable that is uni8ue within a method -and an% use o+ the name within that method re+ers to the same variable.5 Note. A variable is just a name2 or DhandleE +or a value5 It is possible +or more than one variable to re+er to the same value2 as in the program7
first='A string' second=first

,ere2 both variables re+er to the same value5 I+ that value is changeable then a change to the value re+erred to b% one o+ the variable names would also be seen i+ the value is re+erred to b% the other5 6or e!ample2 sub1values o+ a Net e!! string can be changed2 using Inde%ed re#eren$es -see page ?<.2 so a change to a sub1value o+ first would also be seen in an identical inde!ed re+erence to second5

Terms on the left of assignments

In an assignment instruction2 the ter) to the le+t o+ the e8uals sign is most commonl% a simple non1 numeric s%mbol2 which alwa%s names a variable in the current class5 &he other possibilities2 as seen in the e!ample below2 are7 :5 &he term is an inde%ed re#eren$e -see page ?<.2 to an e!isting variable that re+ers to a string o+ t%pe Rexx or an arra% -see page ?G.5 &he variable ma% be in the current class2 or be a propert% in a class named in the uses phrase o+ the class instruction +or the current class5 ;5 &he term is a compound term -see page G@. that ultimatel% re+ers to a propert% -see above. in some class -which ma% be the current class.5 &his propert% cannot be a constant5
G> Unlike the block scoping o+ $LMI2 C2 or 3ava5 Version 2.00 NetRexx Language Definition 71

%xample,.
r=Rexx '' r['foo']='?' s=String[3] s[0]='test' Sample.value=1 this.value=1 super.value=1 -- indexed string assignment ----array assignment property assignment property assignment property assignment

&he last two e!amples show assignments to a propert% in the current class or in a superclass o+ the current class2 respectivel%5 Note that re+erences to properties in other classes must alwa% be 8uali+ied in some wa% -+or e!ample2 b% the pre+i! super..5 &he use o+ the pre+i! this. +or properties in the current class is optional5

72

NetRexx Language Definition

Version 2.00

Indexed strings and Arrays

An% Net e!! string -that is2 a value o+ t%pe Rexx.2 has the abilit% to have s*&;"al*es2 values -also o+ t%pe Rexx. which are associated with the original string and are inde!ed b% an inde% string which identi+ies the sub1value5 An% string with such sub1values is known as an inde%ed string5 &he sub1values o+ a Net e!! string are accessed using inde%ed re#eren$es2 where the name o+ a variable o+ t%pe Rexx is +ollowed immediatel% b% s8uare brackets enclosing one or more e!pressions separated b% commas7G: sy)&olXOXOe%pressionO2 e%pressionP555PXPX It is important to note that the sy)&ol that names the variable must be +ollowed immediatel% b% the D[E2 with no blank in between2 or the construct will not be recogni=ed as an inde!ed re+erence5 &he e%pressions -separated b% commas. between the brackets are called the inde%es to the string5 &hese inde! e!pressions are evaluated in turn +rom le+t to right2 and each must evaluate to a value is o+ t%pe Rexx or that can be converted to t%pe Rexx5 &he resulting inde! strings are taken Das1isE 9 that is2 the% must match e!actl% in content2 case2 and length +or a re+erence to +ind a previousl%1set item5 &he% ma% have an% length -including the null string. and value -the% are not constrained to be just those strings which are numbers2 +or e!ample.5 I+ a re+erence does not +ind a sub1value2 then a cop% o+ the non1inde!ed value o+ the variable is used5 %xample.
surname='Unknown' -- default value surname['Fred']='Bloggs' surname['Davy']='Jones' try='Fred' say surname[try] surname['Bert']

would sa% DBloggs UnknownE5 *hen multiple inde!es are used2 the% indicate accessing a hierarch% o+ strings5 A single Net e!! string has a single set o+ inde!es and subvalues associated with it5 &he sub1values2 however2 are also Net e!! strings2 and so ma% in turn have inde!es and sub1values5 *hen more than one inde! is speci+ied in an inde!ed re+erence2 the inde!es are applied in turn +rom le+t to right to each retrieved sub1value5 6or e!ample2 in the se8uence7
x='?' x['foo', 'bar']='OK' say x['foo', 'bar'] y=x['foo'] say y['bar']

both say instructions would displa% the string DOKE5 Inde!ed strings ma% be used to set up Dassociative arra%sE2 or dictionaries2 in which the subscript is not necessaril% numeric2 and thus o++er great scope +or the creative programmer5 A use+ul application is to set up a variable in which the subscripts are taken +rom the value o+ one or more variables2 so e++ecting a +orm o+ associative -content addressable. memor%5

G: &he notations '[' and ']' indicate s8uare brackets appearing in the Net e!! program5 Version 2.00 NetRexx Language Definition 73

Note,. :5 A variable o+ t%pe Rexx must have been assigned a value be+ore inde!ing is used on it5 &his is the value that is used as the de+ault value whenever an inde!ed re+erence +inds no sub1value5 ;5 &he inde!es2 and hence the sub1values2 o+ a Rexx object can be retrieved in turn using the over -see page CG. ke%word o+ the loop instruction5 <5 &he exists method -see page :A:. o+ the Rexx class ma% be used to test whether an inde!ed re+erence has an e!plicitl%1set value5 G5 Assigning null to an inde!ed re+erence -+or e!ample2 the assignment switch[7]=null;. drops the sub1valueF until set to a new value2 an% re+erence to the sub1value -including use o+ the exists method. will return the same result as when it had never been set5

Arrays
In addition to inde!ed strings2 Net e!! also includes the concept o+ +i!ed1si=e arrays2 which ma% be used +or inde!ing values o+ an% t%pe -including strings.5 Arra%s are used with the same s%nta! and in the same manner as inde!ed strings2 but with important di++erences that allow +or compact implementations and access to e8uivalent data structures constructed using other programming languages7 :5 &he inde!es +or arra%s must be whole numbers that are =ero or positive5 &here will usuall% be an implementation restriction on the ma!imum value o+ the inde! -t%picall% CCCCCCCCC or higher.5 ;5 &he elements o+ an arra% are considered to be orderedF the +irst element has inde! 02 the second 12 and so on5 <5 An arra% is o+ +i!ed si=eF it must be constructed be+ore use5 G5 0ariables that are assigned arra%s can onl% be assigned arra%s -o+ the same dimension2 see below. in the +uture5 &hat is2 being an arra% changes the t%pe o+ a valueF it becomes a di)ensioned type -see page GA.5 Arra% re+erences use the Net e!! inde%ed re#eren$e s%nta! de+ined above5 &he same s%nta! is used +or constructing arra%s2 e!cept that the s%mbol be+ore the le+t bracket describes a t%pe -and hence ma% be 8uali+ied b% a package name.5 &he e!pression or e!pressions between the brackets indicate the si=e o+ the arra% in each dimension2 and must be a positive whole number or =ero7
arg=String[4] -- makes an array for four Strings arg=java.io.File[4] -- makes an array for four Files i=int[3] -- makes an array for three 'int's

-Another wa% o+ describing this is that arra% constructors look just like other object constructors2 e!cept that brackets are used instead o+ parentheses5. /nce an arra% has been constructed2 its elements can be re+erred to using brackets and e!pressions2 as be+ore7
i[2]=3 -- sets the '2'-indexed value of 'i' j=i[2] -- sets 'j' to the '2'-indexed value of 'i'

egular multiple1dimensioned arra%s ma% be constructed and re+erenced b% using multiple e!pressions within the brackets7

74

NetRexx Language Definition

Version 2.00

i=int[2,3] -- makes a 2x3 array of 'int' type objects i[1,2]=3 -- sets the '1,2'-indexed value of 'i' j=i[1,2] -- sets 'j' to the '1,2'-indexed value of 'i'

As with inde!ed strings2 when multiple inde!es are used2 the% indicate accessing a hierarch% o+ arra%s -the underl%ing model is there+ore o+ a hierarch% o+ single1dimensioned arra%s.5 *hen more than one inde! is speci+ied in an inde!ed re+erence to an arra%2 the inde!es are applied in turn +rom le+t to right to each arra%5 As described in the section on 1ypes -see page GA.2 the t%pe o+ a variable that re+ers to an arra% can be set -declared. b% assignment o+ the t%pe with arra% notation that indicates the dimension o+ an arra% without an% si=es7
k=int[] -- one-dimensional array of 'int' objects m=float[,,] -- 3-dimensional array of 'float' objects

&he same s%nta! is also used when describing an arra% t%pe in the arguments o+ a method instruction or when converting t%pes5 6or e!ample2 a+ter7
gg=char[] "Horse"

the variable gg has as its value an arra% o+ t%pe char[] containing the +ive characters H2 o2 r2 s2 and e5

Array initializers
An array initiali=er is a si)ple ter) which is recogni=ed i+ it does not immediatel% +ollow -abut. a s%mbol2 and has the +ormG;
'['expression[,expression]...']'

An arra% initiali=er there+ore comprises a list o+ one or more e!pressions2 separated b% commas2 within brackets5 *hen an arra% initiali=er is evaluated2 the e!pressions are evaluated in turn +rom le+t to right2 and all must result in a value5 An arra% is then constructed2 with a number o+ elements e8ual to the number o+ e!pressions in the list2 with each element initiali=ed b% being assigned the result o+ the corresponding e!pression5 &he t%pe o+ the arra% is derived b% adding one dimension to the t%pe o+ the result o+ the +irst e!pression in the list2 where the t%pe o+ that e!pression is determined using the same rules as are used to select the t%pe o+ a variable when it is +irst assigned a value -see page AC.5 All the other e!pressions in the list must have t%pes that could be assigned to the chosen t%pe without error5 6or e!ample2 in
var1=['aa', 'bb', 'cc'] var2=[char 'a', 'b', 'c'] var3=[String 'a', 'bb', 'c'] var4=[1, 2, 3, 4, 5, 6] var5=[[1,2], [3,4]]

the t%pes o+ the variables would be Rexx[]2 char[]2 String[]2 Rexx[]2 and Rexx[,] respectivel%5 In a binar% class in the re+erence implementation2 the t%pes would be String[]2 char[]2 String[]2 int[]2 and int[,]5 Arra% initiali=ers are most use+ul +or initiali=ing properties and variables2 but like other simple terms2 the% ma% start a compound term5
G; &he notations '[' and ']' indicate s8uare brackets appearing in the Net e!! program5 Version 2.00 NetRexx Language Definition 75

(o2 +or e!ample

say [1,1,1,1].length

would displa% 45 Note that an arra% o+ length =ero cannot be constructed with an arra% initiali=er2 as its t%pe would be unde+ined5 An e!plicitl% t%ped arra% constructor -+or e!ample2 int[0]. must be used5

76

NetRexx Language Definition

Version 2.00

Keyword Instructions
A keyword instr*$tion is one or more clauses2 the +irst o+ which starts with a ke%word that identi+ies the instruction5 (ome ke%word instructions a++ect the +low o+ controlF the remainder just provide services to the programmer5 (ome ke%word instructions -do2 if2 loop2 or select. can include nested instructions5 Appendi! A -see page :?:. includes an e!ample o+ a Net e!! program using man% o+ the instructions available5 As can be deduced +rom the s%nta! rules described earlier2 a ke%word instruction is recogni=ed onl+ i+ its ke%word is the +irst token in a clause2 and i+ the second token is not an D=E character -impl%ing an assignment.5 It would also not be recogni=ed i+ the second token started with D(E2 D[E2 or D.E -impl%ing that the +irst token starts a term.5 6urther2 i+ a current local variable2 method argument2 or propert% has the same name as a ke%word then the ke%word will not be recogni=ed5 &his important rule allows Net e!! to be e!tended with new ke%words in the +uture without invalidating e!isting programs5 &hus2 +or e!ample2 this se8uence in a program with no say variable7
say 'Hello' say('1') say=3 say 'Hello'

would be a say instruction2 a call to some say method2 an assignment to a say variable2 and an error5 In Net e!!2 there+ore2 ke%words are not reservedF the% ma% be used as the names o+ variables -though this is not recommended2 where known in advance.5 Certain other ke%words2 known as s*&;keywords2 ma% be known within the clauses o+ individual instructions 9 +or e!ample2 the s%mbols to and while in the loop instruction5 Again2 these are not reservedF i+ the% had been used as names o+ variables2 the% would not be recogni=ed as sub1ke%words5 Blanks adjacent to ke%words have no e++ect other than that o+ separating the ke%word +rom the subse8uent token5 6or e!ample2 this applies to the blanks ne!t to the sub1ke%word while in
loop while a=3

,ere at least one blank was re8uired to separate the s%mbols +orming the ke%words and the variable name2 a5 ,owever the blank +ollowing the while is not necessar% in
loop while 'Me'=a

though it does aid readabilit%5

Version 2.00

NetRexx Language Definition

77

Class instruction
class na)e O"isi&ilityP O)odi#ierP ObinaryP OdeprecatedP Oextends $lassna)eP Ouses *seslistP Oimplements inter#a$elistPF

where "isi&ility is one o+7

private public shared

and )odi#ier is one o+7

abstract adapter final interface

and *seslist and inter#a$elist are lists o+ one or more $lassna)es2 separated b% commas5 &he class instruction is used to introduce a class2 as described in the sections 1ypes and Classes -see page GA. and Progra) str*$t*re -see page :;G.2 and de+ine its attributes5 &he class must be given a na)e2 which must be di++erent +rom the name o+ an% other classes in the program5 &he na)e2 which must be a non1numeric s%mbol2 is known as the short na)e o+ the class5 A $lassna)e can be either the short name o+ a class -i+ that is unambiguous in the conte!t in which it is used.2 or the 8uali+ied name o+ the class 9 the name o+ the class pre+i!ed b% a package name and a period2 as described under the package instruction -see page ::>.5 &he &ody o+ the class consists o+ all clauses +ollowing the class instruction -i+ an%. until the ne!t class instruction or the end o+ the program5 &he "isi&ility2 )odi#ier2 and binary ke%words2 and the extends2 uses2 and implements phrases2 ma% appear in an% order5

Visibility
Classes ma% be public2 private2 or shared7 A p*&li$ $lass is visible to -that is2 ma% be used b%. all other classes5 A pri"ate $lass is visible onl% within same program and to classes in the same package -see page ::>.5 A shared $lass is also visible onl% within same program and to classes in the same package5G< A program ma% have onl% one public class2 and i+ no class is marked public then the +irst is assumed to be public -unless it is e!plicitl% marked private.5
G< &he shared ke%word on the class instruction means e!actl% the same as the ke%word private2 and is accepted +or consistenc% with the other meanings o+ shared5 78 NetRexx Language Definition Version 2.00

Modifier
Most classes are collections o+ data -properties. and the procedures that can act on that data -methods.F the% completel% implement a datat%pe -t%pe.2 and are permitted to be subclassed5 &hese are called standard $lasses5 &he )odi#ier ke%words indicate that the class is not a standard class 9 it is special in some wa%5 /nl% one o+ the +ollowing modi+ier ke%words is allowed7
abstract

An a&stra$t $lass does not completel% implement a datat%peF one or more o+ the methods that it de+ines -or which it inherits +rom classes it e!tends or implements. is abstract 9 that is2 the name o+ the method and the t%pes o+ its arguments are de+ined2 but no instructions to implement the method are provided5 (ince some methods are not provided2 an object cannot be constructed +rom an abstract class5 Instead2 the class must be e!tended and an% missing methods provided5 (uch a subclass can then be used to construct an object5 Abstract classes are use+ul where man% subclasses can share common data or methods2 but each will have some uni8ue attribute or attributes -data andMor methods.5 6or e!ample2 some set o+ geometric objects might share dimensions in I and H2 %et need uni8ue methods +or calculating the area o+ the object5

adapter

An adapter $lass is a class that is guaranteed to implement all unimplemented abstract methods o+ its superclasses and inter+ace classes that it inherits or lists as implemented on the class instruction5 I+ an% unimplemented methods are +ound2 the% will be automaticall% generated b% the language processor5 Methods generated in this wa% will have the same visibilit% and signature as the abstract method the% implement2 and i+ a return value is e!pected then a de+ault value is returned -as +or the initial value o+ variables o+ the same t%pe7 that is2 null or2 +or values o+ primitive t%pe2 an implementation1de+ined value2 t%picall% >.5 /ther than possibl% returning a value2 these methods are empt%F that is2 the% have no side1e++ects5 An adapter class provides a concrete representation o+ its superclasses and the inter+ace classes it implements5 As such2 it is especiall% use+ul +or implementing event handlers and the like2 where onl% a small number o+ event1handling methods are needed but man% more might be speci+ied in the inter+ace class that describes the event model5GG An adapter class cannot have an% abstract methods5

final interface

A #inal $lass is considered to be completeF it cannot be subclassed -e!tended.2 and all its methods are considered complete5GB An inter#a$e $lass is an abstract class that contains onl% abstract method de+initions andM or constants5 &hat is2 it de+ines neither instructions that implement methods nor modi+iable properties2 and hence cannot be used to construct an object5 Inter+ace classes are used b% classes that claim to i)ple)ent them -see the implements ke%word2 described below.5 &he di++erence between abstract and inter+ace classes is that the +ormer ma% have methods which are not abstract2 and hence can onl% be subclassed -e!tended.2 whereas the latter are wholl% abstract and ma% onl% be implemented5

GG 6or e!ample2 see the D(cribbleE sample in the Net e!! package5 GB &his modi+ier is provided +or consistenc% with other languages2 and ma% allow compilers to improve the per+ormance o+ classes that re+er to the +inal class5 In man% cases it will reduce the reusabilit% o+ the class2 and hence should be avoided5 Version 2.00 NetRexx Language Definition 79

Binary
&he ke%word binary indicates that the class is a &inary $lass5 In binar% classes2 literal strings and numeric s%mbols are assigned native string or binar% -primitive. t%pes2 rather than Net e!! t%pes2 and native binar% operations are used to implement operators where possible5 *hen binary is not in e++ect -the de+ault.2 terms in e!pressions are converted to Net e!! t%pes be+ore use b% operators5 &he section Binary "al*es and operations -see page :GC. describes the implications o+ binar% classes in detail5 Individual methods in a class which is not binar% can be made into &inary )ethods using the binary ke%word on the method instruction -see page C@.5

Deprecated
&he ke%word deprecated indicates that the class is depre$ated2 which implies that a better alternative is available and documented5 A compiler can use this in+ormation to warn o+ out1o+1date or other use that is not recommended5

Extends
Classes +orm a hierarch%2 with all classes -e!cept the top o+ the tree2 the ObjectGA class. being a s*&$lass o+ some other class5 &he extends ke%word identi+ies the $lassna)e o+ the immediate s*per$lass o+ the new class 9 that is2 the class immediatel% above it in the hierarch%5 I+ no extends phrase is given2 the superclass is assumed to be Object -or null2 in the case where the current class is Object.5

Uses
&he uses ke%word introduces a list o+ the names o+ one or more classes that will be used as a source o+ constant -or static. properties andMor methods5 *hen a term -see page G@. starts with a s%mbol2 method call2 or inde!ed re+erence that is not known in the current conte!t2 each class in the *seslist and its superclasses are searched -in the order speci+ied in the *seslist. +or a constant or static method or propert% that matches the item5 I+ +ound2 the method or propert% is used just as though e!plicitl% 8uali+ied b% the name o+ the class in which it was +ound5 &he uses mechanism a++ects onl% the s%nta! o+ terms in the current classF it is not inherited b% subclasses o+ the current class5

Implements
&he implements ke%word introduces a list o+ the names o+ one or more inter+ace classes -see above.5 &hese inter+ace classes are then known to -inherited b%. the current class2 in the order speci+ied in the inter#a$elist5 &heir methods -which are all abstract. and constant properties act as though part o+ the current class2 unless the% are overridden -hidden. b% a method or constant o+ the same name in the current class5 I+ the current class is not an inter+ace class then it must implement -provide non1abstract methods +or. all the methods inherited +rom the inter+ace classes in the implements list5 Inter+ace classes2 there+ore2 can be used to7 :5 #e+ine a common set o+ methods -possibl% with associated constants. that will be implemented
GA In the re#eren$e i)ple)entation, java.lang.Object. 80 NetRexx Language Definition Version 2.00

b% other classes5 ;5 Convenientl% package collections o+ constants +or use b% other classes5 &he implements list ma% not include the superclass o+ the current class5

Version 2.00

NetRexx Language Definition

81

Do instruction
do Olabel na)eP Oprotect ter)PF

instr*$tionlist Ocatch O"are WP e%$eptionF instr*$tionlistP555 OfinallyOFP instr*$tionlistP end Ona)ePF where na)e is a non1numeric sy)&ol and instr*$tionlist is =ero or more instr*$tions &he do instruction is used to group instructions together +or e!ecutionF these are e!ecuted once5 &he group ma% optionall% be given a label2 and ma% protect an object while the instructions in the group are e!ecutedF e!ceptional conditions can be handled with catch and finally5 &he most common use o+ do is simpl% +or treating a number o+ instructions as group5 %xample.
/* The two instructions between DO and END will both */ /* be executed if A has the value 3. */ if a=3 then do a=a+2 say 'Smile!' end

,ere2 onl% the +irst instr*$tionlist is used5 &his +orms the &ody o+ the group5 &he instructions in the instr*$tionlists ma% be an% assignment2 method call2 or ke%word instruction2 including an% o+ the more comple! constructions such as loop2 if2 select2 and the do instruction itsel+5

Label phrase
I+ label is used to speci+% a na)e +or the group2 then a leave which speci+ies that name ma% be used to leave the group2 and the end that ends the group ma% optionall% speci+% the name o+ the group +or additional checking5 %xample.
do label sticky x=ask if x='quit' then leave sticky say 'x was' x end sticky

Protect phrase
I+ protect is given it must be +ollowed b% a ter) that evaluates to a value that is not just a t%pe and is not o+ a primitive t%peF while the do construct is being e!ecuted2 the value -object. is protected 9 that is2 all the instructions in the do construct have e!clusive access to the object5 Both label and protect ma% be speci+ied2 in an% order2 i+ re8uired5
82 NetRexx Language Definition Version 2.00

Exceptions in do groups
"!ceptions that are raised b% the instructions within a do group ma% be caught using one or more catch clauses that name the e%$eption that the% will catch5 *hen an e!ception is caught2 the e!ception object that holds the details o+ the e!ception ma% optionall% be assigned to a variable2 "are5 (imilarl%2 a finally clause ma% be used to introduce instructions that will alwa%s be e!ecuted at the end o+ the group2 even i+ an e!ception is raised -whether caught or not.5 &he '%$eptions section -see page :B;. has details and e!amples o+ catch and finally5

Version 2.00

NetRexx Language Definition

83

Exit instruction
exit Oe%pressionPF exit is used to unconditionall% leave a program2 and optionall% return a result to the caller5 &he entire

program is terminated immediatel%5 I+ an e%pression is given2 it is evaluated and the result o+ the evaluation is then passed back to the caller in an implementation1dependent manner when the program terminates5 &%picall% this value is e!pected to be a small whole numberF most implementations will accept values in the range > through ;B>5 I+ no e!pression is given2 a de+ault result -which depends on the implementation2 and is t%picall% =ero. is passed back to the caller5 %xample.
j=3 exit j*4 /* Would exit with the value '12' */

D unning o++ the endE o+ a program is e8uivalent to the instruction return;5 In the case where the program is simpl% a stand1alone application with no class or method instructions2 this has the same e++ect as exit;2 in that it terminates the whole program and returns a de+ault result5

84

NetRexx Language Definition

Version 2.00

If instruction
if e%pressionOFP thenOFP instr*$tion OelseOFP instr*$tionP

&he if construct is used to conditionall% e!ecute an instruction or group o+ instructions5 It can also be used to select between two alternatives5 &he e!pression is evaluated and must result in either > or :5 I+ the result was : -true. then the instruction a+ter the then is e!ecuted5 I+ the result was > -+alse. and an else was given then the instruction a+ter the else is e!ecuted5 %xample.
if answer='Yes' then say 'OK!' else say 'Why not?'

emember that i+ the else clause is on the same line as the last clause o+ the then part2 then %ou need a semicolon to terminate that clause5 %xample.
if answer='Yes' then say 'OK!'; else say 'Why not?'

&he else binds to the nearest then at the same level5 &his means that an% if that is used as the instruction +ollowing the then in an if construct that has an else clause2 must itsel+ have an else clause -which ma% be +ollowed b% the dumm% instruction2 nop.5 %xample.
if answer='Yes' then if name='Fred' then say 'OK, Fred.' else say 'OK.' else say 'Why not?'

&o include more than one instruction +ollowing then or else2 use a grouping instruction -do2 loop2 or select.5 %xample.
if answer='Yes' then do say 'Line one of two' say 'Line two of two' end

In this instance2 both say instructions are e!ecuted when the result o+ the if e!pression is :5 Multiple e!pressions2 separated b% commas2 can be given on the if clause2 which then has the s%nta!7
if e%pressionO2 e%pressionP555 OFP

In this case2 the e!pressions are evaluated in turn +rom le+t to right2 and i+ the result o+ an% evaluation is : then the test has succeeded and the instruction +ollowing the associated then clause is e!ecuted5 I+ all the e!pressions evaluate to > and an else was given then the instruction a+ter the else is e!ecuted5 Note that once an e!pression evaluation has resulted in :2 no +urther e!pressions in the clause are evaluated5 (o2 +or e!ample2 in7
-- assume 'name' is a string if name=null, name='' then say 'Empty'
Version 2.00 NetRexx Language Definition 85

then i+ name does not re+er to an object it will compare e8ual to null and the say instruction will be e!ecuted without evaluating the second e!pression in the if clause5 Note,. :5 An instr*$tion ma% be an% assignment2 method call2 or ke%word instruction2 including an% o+ the more comple! constructions such as do2 loop2 select2 and the if instruction itsel+5 A null clause is not an instruction2 however2 so putting an e!tra semicolon a+ter the then or else is not e8uivalent to putting a dumm% instruction5 &he nop instruction is provided +or this purpose5 ;5 &he ke%word then is treated speciall%2 in that it need not start a clause5 &his allows the e!pression on the if clause to be terminated b% the then2 without a D;E being re8uired 9 were this not so2 people used to other computer languages would be inconvenienced5 ,ence the s%mbol then cannot be used as a variable name within the e!pression5G?

G? (trictl% speaking2 then should onl% be recogni=ed i+ not the name o+ a variable5 In this special case2 however2 Net e!! language processors are permitted to treat then as reserved in the conte!t o+ an if clause2 to provide better per+ormance and more use+ul error reporting5 86 NetRexx Language Definition Version 2.00

Import instruction
import na)eF

where na)e is one or more non1numeric sy)&ols separated b% periods2 with an optional trailing period5 &he import instruction is used to simpli+% the use o+ classes +rom other packages5 I+ a class is identi+ied b% an import instruction2 it can then be re+erred to b% its short name2 as given on the class instruction -see page ?@.2 as well as b% its +ull% 8uali+ied name5 &here ma% be =ero or more import instructions in a program5 &he% must precede an% class instruction -or an% instruction that would start the de+ault class.5 In the +ollowing description2 a pa$kage na)e names a package as described under the package instruction -see page ::>.5 &he import na)e must be one o+7 A 8uali+ied class name2 which is a package name immediatel% +ollowed b% a period which is immediatel% +ollowed b% a short class name 9 in this case2 the individual class identi+ied is imported5 A package name 9 in this case2 all the classes in the speci+ied package are imported5 &he name ma% have a trailing period5 A partial package name -a package name with one or more parts omitted +rom the right2 indicated b% a trailing period a+ter the parts that are present. 9 in this case2 all classes in the package hierarch% below the speci+ied point are imported5 %xample,.
import java.lang.String import java.lang import java.

&he +irst e!ample above imports a single class -which could then be re+erred to simpl% as DStringE.5 &he second e!ample imports all classes in the Djava.langE package5 &he third e!ample imports all classes in all the packages whose name starts with Djava.E5 *hen a class is imported e!plicitl%2 +or e!ample2 using
import java.awt.List

this indicates that the short name o+ the class -List2 in this e!ample. ma% be used to re+er to the class unambiguousl%5 &hat is2 using this short name will not report an ambiguous re+erence warning -as it would without the import instruction2 because a java.util.List class was added in 3ava :5;.5 It +ollows that7 &wo classes imported e!plicitl% cannot have the same short name5 No class in a program being compiled can have the same short name as a class that is imported e!plicitl%5 because in either o+ these situations a use o+ the short name would be ambiguous5 Note also that an e!plicit import does not import the minor or dependent classes associated with a nameF the% each re8uire their own e!plicit import -unless the entire package is imported.5

Version 2.00

NetRexx Language Definition

87

In the re#eren$e i)ple)entation, the #*nda)ental 3et/e%% and Ca"a pa$kage hierar$hies are a*to)ati$ally i)ported &y de#a*lt, as tho*gh the instr*$tions8
import import import import import import import netrexx.lang. java.lang. java.io. java.util. java.net. java.awt. java.applet.

had &een e%e$*ted &e#ore the progra) &egins. In addition, $lasses in the $*rrent :working> dire$tory are i)ported i# no package instr*$tion is spe$i#ied. I# a package instr*$tion is spe$i#ied then all $lasses in that pa$kage are i)ported.

88

NetRexx Language Definition

Version 2.00

Iterate instruction
iterate Ona)ePF

where na)e is a non1numeric sy)&ol5

iterate alters the +low o+ control within a loop construct5 It ma% onl% be used in the bod% -the +irst

instr*$tionlist. o+ the construct5 "!ecution o+ the instruction list stops2 and control is passed directl% back up to the loop clause just as though the last clause in the bod% o+ the construct had just been e!ecuted5 &he control variable -i+ an%. is then stepped -iterated. and termination conditions tested as normal and the instruction list is e!ecuted again2 unless the loop is terminated b% the loop clause5 I+ no na)e is speci+ied2 then iterate will step the innermost active loop5 I+ a na)e is speci+ied2 then it must be the name o+ the label2 or control variable i+ there is no label2 o+ a currentl% active loop -which ma% be the innermost.2 and this is the loop that is iterated5 An% active do2 loop2 or select constructs inside the loop selected +or iteration are terminated -as though b% a leave instruction.5 %xample.
loop i=1 to 4 if i=2 then iterate i say i end /* Would display the numbers:

1, 3, 4

*/

Note,. :5 A loop is active i+ it is currentl% being e!ecuted5 I+ a method -even in the same class. is called during e!ecution o+ a loop2 then the loop becomes inactive until the method has returned5 iterate cannot be used to step an inactive loop5 ;5 &he na)e s%mbol2 i+ speci+ied2 must e!actl% match the label -or the name o+ the control variable2 i+ there is no label. in the loop clause in all respects e!cept case5

Version 2.00

NetRexx Language Definition

89

Leave instruction
leave Ona)ePF

where na)e is a non1numeric sy)&ol5

leave causes immediate e!it +rom one or more do2 loop2 or select constructs5 It ma% onl% be used in

the bod% -the +irst instr*$tionlist. o+ the construct5 "!ecution o+ the instruction list is terminated2 and control is passed to the end clause o+ the construct2 just as though the last clause in the bod% o+ the construct had just been e!ecuted or -i+ a loop. the termination condition had been met normall%2 e!cept that on e!it the control variable -i+ an%. will contain the value it had when the leave instruction was e!ecuted5 I+ no na)e is speci+ied2 then leave must be within an active loop and will terminate the innermost active loop5 I+ a na)e is speci+ied2 then it must be the name o+ the label -or control variable +or a loop with no label.2 o+ a currentl% active do2 loop2 or select construct -which ma% be the innermost.5 &hat construct -and an% active constructs inside it. is then terminated5 Control then passes to the clause +ollowing the end clause that matches the do2 loop2 or select clause identi+ied b% the na)e5 %xample.
loop i=1 to 5 say i if i=3 then leave end i /* Would display the numbers:

1, 2, 3

*/

Note,. :5 I+ an% construct being le+t includes a finally clause2 the instr*$tionlist +ollowing the finally will be e!ecuted be+ore the construct is le+t5 ;5 A do2 loop2 or select construct is active i+ it is currentl% being e!ecuted5 I+ a method -even in the same class. is called during e!ecution o+ an active construct2 then the construct becomes inactive until the method has returned5 leave cannot be used to leave an inactive construct5 <5 &he na)e s%mbol2 i+ speci+ied2 must e!actl% match the label -or the name o+ the control variable2 +or a loop with no label. in the do2 loop2 or select clause in all respects e!cept case5

90

NetRexx Language Definition

Version 2.00

Loop instruction
loop Olabel na)eP Oprotect ter)pP OrepetitorP O$onditionalPF

instr*$tionlist Ocatch O"are WP e%$eptionF instr*$tionlistP555 OfinallyOFP instr*$tionlistP end Ona)ePF where repetitor is one o+7 "ar$ W e%pri Oto e%prtP Oby e%pr&P Ofor e%pr#P "aro over ter)o for e%prr
forever

and $onditional is either o+7

while e%prw until e%pr*

and na)e is a non1numeric sy)&ol and instr*$tionlist is =ero or more instr*$tions and e%pri2 e%prt2 e%pr&2 e%pr#2 e%prr2 e%prw2 and e%pr* are e%pressions5 &he loop instruction is used to group instructions together and e!ecute them repetitivel%5 &he loop ma% optionall% be given a label2 and ma% protect an object while the instructions in the loop are e!ecutedF e!ceptional conditions can be handled with catch and finally5
loop is the most complicated o+ the Net e!! ke%word instructions5 It can be used as a simple

inde+inite loop2 a predetermined repetitive loop2 as a loop with a bounding condition that is recalculated on each iteration2 or as a loop that steps over the contents o+ a collection o+ values5

Syntax notes:
&he label and protect phrases ma% be in an% order5 &he% must precede an% repetitor or $onditional5 &he +irst instr*$tionlist is known as the &ody o+ the loop5 &he to2 by2 and for phrases in the +irst +orm o+ repetitor ma% be in an% order2 i+ used2 and will be evaluated in the order the% are written5 An% instruction allowed in a method is allowed in an instr*$tionlist2 including assignments2 method call instructions2 and ke%word instructions -including an% o+ the more comple! constructions such as if2 do2 select2 or the loop instruction itsel+.5 I+ for or forever start the repetitor and are +ollowed b% an D=E character2 the% are taken as
Version 2.00 NetRexx Language Definition 91

control variable names2 not ke%words -as +or assignment instructions.5 &he e!pressions e%pri2 e%prt2 e%pr&2 or e%pr# will be ended b% an% o+ the ke%words to2 by2 for2 while2 or until -unless the word is the name o+ a variable.5 &he e!pressions e%prw or e%pr* will be ended b% either o+ the ke%words while or until -unless the word is the name o+ a variable.5

Indefinite loops
I+ neither repetitor nor $onditional are present2 or the repetitor is the ke%word forever2 then the loop is an inde#inite loop5 It will be ended onl% when some instruction in the +irst instr*$tionlist causes control to leave the loop5 %xample.
/* This displays "Go caving!" at least once */ loop forever say 'Go caving!' if ask='' then leave end

Bounded loops
I+ a repetitor -other than forever. or $onditional is given2 the +irst instr*$tionlist +orms a &o*nded loop2 and the instruction list is e!ecuted according to an% repetitor phrase2 optionall% modi+ied b% a $onditional phrase5 Simple bounded loops *hen the repetitor starts with the ke%word for2 the e!pression e%prr is evaluated immediatel% -with 0 added2 to e++ect an% rounding. to give a repetition count2 which must be a whole number that is =ero or positive5 &he loop is then e!ecuted that man% times2 unless it is terminated b% some other condition5 %xample.
/* This displays "Hello" five times */ loop for 5 say 'Hello' end

Controlled bounded loops

A $ontrolled loop begins with an assign)ent2 which can be identi+ied b% the D=E that +ollows the name o+ a control variable2 "ar$5 &he control variable is assigned an initial value -the result o+ e%pri2 +ormatted as though > had been added. be+ore the +irst e!ecution o+ the instruction list5 &he control variable is then stepped -b% adding the result o+ e%pr&. be+ore the second and subse8uent times that the instruction list is e!ecuted5 &he name o+ the control variable2 "ar$2 must be a non1numeric s%mbol that names an e!isting or new variable in the current method or a propert% in the current class -that is2 it cannot be element o+ an arra%2 the propert% o+ a superclass2 or a more comple! term.5 It is +urther restricted in that it must not alread% be used as the name o+ a control variable or label in a loop -or do or select construct. that encloses the new loop5 &he instruction list in the bod% o+ the loop is e!ecuted repeatedl% while the end condition -determined b% the result o+ e%prt. is not met5 I+ e%pr& is positive or

92

NetRexx Language Definition

Version 2.00

=ero2 then the loop will be terminated when "ar$ is greater than the result o+ e%prt5 I+ negative2 then the loop will be terminated when "ar$ is less than the result o+ e%prt5 &he e!pressions e%prt and e%pr& must result in numbers5 &he% are evaluated once onl% -with > added2 to e++ect an% rounding.2 in the order the% appear in the instruction2 and be+ore the loop begins and be+ore e%pri -which must also result in a number. is evaluated and the control variable is set to its initial value5 &he de+ault value +or e%pr& is :5 I+ no e%prt is given then the loop will e!ecute inde+initel% unless it is terminated b% some other condition5 %xample.
loop i=3 to -2 by -1 say i end /* Would display: 3, 2, 1, 0, -1, -2 */

Note that the numbers do not have to be whole numbers7 %xample.

x=0.3 loop y=x to x+4 by 0.7 say y end /* Would display: 0.3, 1.0, 1.7, 2.4, 3.1, 3.8 */

&he control variable ma% be altered within the loop2 and this ma% a++ect the iteration o+ the loop5 Altering the value o+ the control variable in this wa% is normall% considered to be suspect programming practice2 though it ma% be appropriate in certain circumstances5 Note that the end condition is tested at the start o+ each iteration -and a+ter the control variable is stepped2 on the second and subse8uent iterations.5 It is there+ore possible +or the bod% o+ the loop to be skipped entirel% i+ the end condition is met immediatel%5 &he e!ecution o+ a controlled loop ma% +urther be bounded b% a for phrase5 In this case2 e%pr# must be given and must evaluate to a non1negative whole number5 &his acts just like the repetition count in a simple bounded loop2 and sets a limit to the number o+ iterations around the loop i+ it is not terminated b% some other condition5 e%pr# is evaluated along with the e!pressions e%prt and e%pr&5 &hat is2 it is evaluated once onl% -with 0 added.2 when the loop instruction is +irst e!ecuted and be+ore the control variable is given its initial valueF the three e!pressions are evaluated in the order in which the% appear5 Like the to condition2 the for count is checked at the start o+ each iteration2 as shown in the programmer's model -see page CA.5 %xample.
loop y=0.3 to 4.3 by 0.7 for 3 say y

Version 2.00

NetRexx Language Definition

93

end /* Would display: 0.3, 1.0, 1.7 */

In a controlled loop2 the s%mbol that describes the control variable ma% be speci+ied on the end clause -unless a label is speci+ied2 see below.5 Net e!! will then check that this s%mbol e!actl% matches the "ar$ o+ the control variable in the loop clause -in all respects e!cept case.5 I+ the s%mbol does not match2 then the program is in error 9 this enables the nesting o+ loops to be checked automaticall%5 %xample.
loop k=1 to 10 ... ... end k /* Checks this is the END for K loop */

Note. &he values taken b% the control variable ma% be a++ected b% the numeric settings2 since normal Net e!! arithmetic rules appl% to the computation o+ stepping the control variable5 Over loops *hen the second token o+ the repetitor is the ke%word over2 the control variable2 "aro2 is used to work through the sub1values in the collection o+ inde!ed strings identi+ied b% ter)o5 In this case2 the loop instruction takes a DsnapshotE o+ the inde!es that e!ist in the collection at the start o+ the loop2 and then +or each iteration o+ the loop the control variable is set to the ne!t available inde! +rom the snapshot5 &he number o+ iterations o+ the loop will be the number o+ inde!es in the collection2 unless the loop is terminated b% some other condition5 %xample.
mycoll='' mycoll['Tom']=1 mycoll['Dick']=2 mycoll['Harry']=3 loop name over mycoll say mycoll[name] end /* might display: 3, 1, 2 */

Note,. :5 &he order in which the values are returned is unde+inedF all that is known is that all inde!es available when the loop started will be recorded and assigned to "aro in turn as the loop iterates5 ;5 &he same restrictions appl% to "aro as appl% to "ar$2 the control variable +or controlled loops -see above.5 <5 (imilarl%2 the s%mbol "aro ma% be used as a name +or the loop and be speci+ied on the end clause -unless a label is speci+ied2 see below.5 In the re#eren$e i)ple)entation, the over #or) o# repetitor )ay also &e *sed to step tho*gh the $ontents o# any o&5e$t that is o# a type that is a s*&$lass o# java.util.Dictionary, s*$h as an o&5e$t o# type java.util.Hashtable. In this $ase, ter)o spe$i#ies the di$tionary, and a snapshot :en*)eration> o# the keys to the 4i$tionary is taken at the start o# the loop. 'a$h iteration o# the loop then assigns a new key to the $ontrol "aria&le "aro whi$h )*st &e :or will &e
94 NetRexx Language Definition Version 2.00

gi"en, i# it is new> the type java.lang.Object. Conditional phrases An% o+ the +orms o+ loop s%nta! can be +ollowed b% a $onditional phrase which ma% cause termination o+ the loop5 I+ while is speci+ied2 e%prw is evaluated2 using the latest values o+ all variables in the e!pression2 be+ore the instruction list is e!ecuted on ever% iteration2 and a+ter the control variable -i+ an%. is stepped5 &he e!pression must evaluate to either > or :2 and the instruction list will be repeatedl% e!ecuted while the result is : -that is2 the loop ends i+ the e!pression evaluates to >.5 %xample.
loop i=1 to 10 by 2 while i<6 say i end /* Would display: 1, 3, 5 */

I+ until is speci+ied2 e%pr* is evaluated2 using the latest values o+ all variables in the e!pression2 on the second and subse8uent iterations2 and be+ore the control variable -i+ an%. is stepped5G@ &he e!pression must evaluate to either > or :2 and the instruction list will be repeatedl% e!ecuted until the result is : -that is2 the loop ends i+ the e!pression evaluates to :.5 %xample.
loop i=1 to 10 by 2 until i>6 say i end /* Would display: 1, 3, 5, 7 */

Note that the e!ecution o+ loops ma% also be modi+ied b% using the iterate or leave instructions5

Label phrase
&he label phrase ma% used to speci+% a na)e +or the loop5 &he name can then optionall% be used on a leave instruction2 to speci+% the name o+ the loop to leave an iterate instruction2 to speci+% the name o+ the loop to be iterated the end clause o+ the loop2 to con+irm the identit% o+ the loop that is being ended2 +or additional checking5 %xample.
loop label pooks i=1 to 10 loop label hill while j<3 ... if a=b then leave pooks ... end hill end pooks

In this e!ample2 the leave instruction leaves both loops5 I+ a label is speci+ied using the label ke%word2 it overrides an% name derived +rom the control variable name -i+ an%.5 &hat is2 the variable name cannot be used to re+er to the loop i+ a label is speci+ied5
G@ &hus2 it appears that the until condition is tested a+ter the instruction list is e!ecuted on each iteration5 ,owever2 it is the loop clause that carries out the evaluation5 Version 2.00 NetRexx Language Definition 95

Protect phrase
&he protect phrase ma% used to speci+% a term2 ter)p2 that evaluates to a value that is not just a t%pe and is not o+ a primitive t%peF while the loop construct is being e!ecuted2 the value -object. is protected 9 that is2 all the instructions in the loop construct have e!clusive access to the object5 %xample.
loop protect myobject while a<b ... end

Both label and protect ma% be speci+ied2 in an% order2 i+ re8uired5

Exceptions in loops
"!ceptions that are raised b% the instructions within a loop construct ma% be caught using one or more catch clauses that name the e%$eption that the% will catch5 *hen an e!ception is caught2 the e!ception object that holds the details o+ the e!ception ma% optionall% be assigned to a variable2 "are5 (imilarl%2 a finally clause ma% be used to introduce instructions that will alwa%s be e!ecuted when the loop ends2 even i+ an e!ception is raised -whether caught or not.5 &he '%$eptions section -see page :B;. has details and e!amples o+ catch and finally5

Programmers model how a typical loop is executed

&his model +orms part o+ the de+inition o+ the loop instruction5 6or the +ollowing loop7
loop varc = expri to exprt by exprb while exprw ... instruction list ... end

Net e!! will e!ecute the +ollowing7

$tempt=exprt+0 /* ($variables are internal and */ $tempb=exprb+0 /* are not accessible.) */ varc=expri+0 Transfer control to the point identified as $start: $loop: /* An UNTIL expression would be tested here, with: /* if expru then leave varc=varc + $tempb $start: if varc > $tempt then leave /* leave quits a loop /* A FOR count would be checked here if \exprw then leave ... instruction list ... Transfer control to the point identified as $loop: */ */ */ */

Note,. :5 &his e!ample is +or e%pr& >= 05 6or a negative e%pr&2 the test at the start point o+ the loop

96

NetRexx Language Definition

Version 2.00

would use D<E rather than D>E5 ;5 &he upwards trans+er o+ control takes place at the end o+ the bod% o+ the loop2 immediatel% be+ore the end clause -or an% catch or finally clause.5 &he end clause is onl% reached when the loop is +inall% completed5

Version 2.00

NetRexx Language Definition

97

Method instruction
method na)eO-OarglistP.P

O"isi&ilityP O)odi#ierP OprotectP ObinaryP OdeprecatedP Oreturns ter)rP Osignals signallistPF where arglist is a list o+ one or more assign)ents2 separated b% commas and "isi&ility is one o+7
inheritable private public shared

and )odi#ier is one o+7

abstract constant final native static

and signallist is a list o+ one or more ter)s2 separated b% commas5 &he method instruction is used to introduce a method within a class2 as described in Progra) str*$t*re -see page :;G.2 and de+ine its attributes5 &he method must be given a na)e2 which must be a non1numeric s%mbol5 &his is its short na)e5 I+ the short name o+ a method matches the short name o+ the class in which it appears2 it is a $onstr*$tor )ethod5 Constructor methods are used +or constructing values -objects.2 and are described in detail in Methods and Constr*$tors -see page B<.5 &he &ody o+ the method consists o+ all clauses +ollowing the method instruction -i+ an%. until the ne!t method or class instruction2 or the end o+ the program5 &he "isi&ility2 )odi#ier2 and protect ke%words2 and the returns and signals phrases2 ma% appear in an% order5

Arguments
&he arglist on a method instruction2 immediatel% +ollowing the method name2 is optional and de+ines a list o+ the arguments +or the method5 An arg*)ent is a value that was provided b% the caller when the method was invoked5 I+ there are no arguments2 this ma% optionall% be indicated b% an Dempt%E pair o+ parentheses5 In the arglist2 each argument has the s%nta! o+ an assign)ent -see page AC.2 where the D=E and the +ollowing e%pression ma% be omitted5 &he name in the assignment provides the name +or the argument -which must not be the same as the name o+ an% propert% in the class.5 "ach argument is also
98 NetRexx Language Definition Version 2.00

optionall% assigned a t%pe2 or t%pe and de+ault value2 +ollowing the usual rules o+ assignment5 I+ there is no assignment2 the argument is assigned the Net e!! string t%pe2 Rexx5 I+ there is no assignment -that is2 there is no D=E. or the e!pression to the right o+ the D=E returns just a t%pe2 the argument is re9*ired -that is2 it must alwa%s be speci+ied b% the caller when the method is invoked.5 I+ an e!plicit value is given b% the e!pression then the argument is optionalF when the caller does not provide an argument in that position2 then the e!pression is evaluated when the method is invoked and the result is provided to the method as the argument5 /ptional arguments ma% be omitted D+rom the rightE onl%5 &hat is2 arguments ma% not be omitted to the le+t o+ arguments that are not omitted5 %xample,.
method method method method fred fred() fred(width, height) fred(width=int, height=int 10)

In these e!amples2 the +irst two method instructions are e8uivalent2 and take no arguments5 &he third e!ample takes two arguments2 which are both strings o+ t%pe Rexx5 &he +inal e!ample takes two arguments2 both o+ t%pe intF the second argument is optional2 and i+ not supplied will de+ault to the value :> -note that an% valid e!pression could be used +or the de+ault value.5

Visibility
Methods ma% be public2 inheritable2 private2 or shared7 A p*&li$ )ethod is visible to -that is2 ma% be used b%. all other classes to which the current class is visible5 An inherita&le )ethod is visible to -that is2 ma% be used b%. all classes in the same package and also those classes that e!tend -that is2 are subclasses o+. the current class5 A pri"ate )ethod is visible onl% within the current class5 A shared )ethod is visible within the current package but is not visible outside the package5 (hared methods cannot be inherited b% classes outside the package5 B% de+ault -i.e.2 i+ no visibilit% ke%word is speci+ied.2 methods are public5

Modifier
Most methods consist o+ instructions that +ollow the method instruction and implement the methodF the method is associated with an object constructed b% the class5 &hese are called standard )ethods5 &he )odi#ier ke%words de+ine that the method is not a standard method 9 it is special in some wa%5 /nl% one o+ the +ollowing modi+ier ke%words is allowed7
abstract

An a&stra$t )ethod has the name o+ the method and the t%pes -but not values. o+ its arguments de+ined2 but no instructions to implement the method are provided -or permitted.5 I+ a class contains an% abstract methods2 an object cannot be constructed +rom it2 and so the class itsel+ must be abstractF the abstract ke%word must be present on the class

Version 2.00

NetRexx Language Definition

99

instruction -see page ?@.5 *ithin an inter+ace class2 the abstract ke%word is optional on the methods o+ the class2 as all methods must be abstract5 No other )odi#ier is allowed on the methods o+ an inter+ace class5
constant final native

A $onstant )ethod is a static method that cannot be overridden b% a method in a subclass o+ the current class5 &hat is2 it is both final and static -see below.5 A #inal )ethod is considered to be completeF it cannot be overridden b% a subclass o+ the current class5 private methods are implicitl% final5GC A nati"e )ethod is a method that is implemented b% the environment2 not b% instructions in the current class5 (uch methods have no Net e!! instructions to implement the method -and none are permitted.2 and the% cannot be overridden b% a method in a subclass o+ the current class5 Native methods are used +or accessing primitive operations provided b% the underl%ing operating s%stem or b% implementation1dependent packages5

static

A stati$ )ethod is a method that is not a constructor and is associated with the class2 rather than with an object constructed b% the class5 It cannot use properties directl%2 e!cept those that are also static -or constant.5 (tatic methods ma% be invoked in the +ollowing wa%s7 :5 *ithin the initiali=ation e!pression o+ a static or constant propert% -such methods are invoked when the class is +irst loaded.5 ;5 B% 8uali+%ing the name o+ the method with the name o+ its class -8uali+ied b% the package name i+ necessar%.2 +or e!ample2 using DMath.Sin(1.3)E or Djava.lang.Math.Sin(1.3)E5 Methods called in this wa% are in e++ect #*n$tions5 <5 B% implicitl% 8uali+%ing the name b% including the name o+ its class in the uses phrase in the class instruction +or the current class5 (tatic methods in classes listed in this wa% can be used directl%2 without 8uali+ication2 +or e!ample2 as DSin(1.3)E5 &he% ma% be still be 8uali+ied2 i+ pre+erred5 In the re#eren$e i)ple)entation, stand;alone appli$ations are started &y the java $o))and in"oking a stati$ )ethod $alled main whi$h takes a single arg*)ent :o# type java.lang.String[]> and ret*rns no res*lt.

Protect
&he ke%word protect indicates that the method protects the current object -or class2 +or a static method. while the instructions in the method are e!ecuted5 &hat is2 the instructions in the method have e!clusive access to the objectF i+ some other method -or construct. is e!ecuting in parallel with the invocation o+ the method and is protecting the same object then the method will not start e!ecution until the object is no longer protected5 Note that i+ a method or construct protecting an object invokes a method -or starts a new construct. that protects the same object then e!ecution continues normall%5 &he inner method or construct is not
GC &his modi+ier ma% allow compilers to improve the per+ormance o+ methods that are +inal2 but ma% also reduce the reusabilit% o+ the class5 100 NetRexx Language Definition Version 2.00

prevented +rom e!ecuting2 because it is not e!ecuting in parallel5

Binary
&he ke%word binary indicates that the method is a &inary )ethod5 In binar% methods2 literal strings and numeric s%mbols are assigned native string or binar% -primitive. t%pes2 rather than Net e!! t%pes2 and native binar% operations are used to implement operators where possible5 *hen binary is not in e++ect -the de+ault.2 terms in e!pressions are converted to Net e!! t%pes be+ore use b% operators5 &he section Binary "al*es and operations -see page :GC. describes the implications o+ binar% methods and classes in detail5 Note,. :5 /nl% the instructions inside the bod% o+ the method are a++ected b% the binary ke%wordF an% arguments and e!pressions on the method instruction itsel+ are not a++ected -this ensures that a single rule applies to all the method signatures in a class.5 ;5 All methods in a binar% class are binar% methodsF the binary ke%word on methods is provided +or classes in which onl% the occasional method needs to be binar% -perhaps +or per+ormance reasons.5 It is not an error to speci+% binary on a method in a binar% class5

Deprecated
&he ke%word deprecated indicates that the method is depre$ated2 which implies that a better alternative is available and documented5 A compiler can use this in+ormation to warn o+ out1o+1date or other use that is not recommended5 Note that individual methods in inter+ace classes cannot be deprecatedF the whole class should be deprecated in this case5

Returns
&he returns ke%word is +ollowed b% a term2 ter)r2 that must evaluate to a t%pe5 &his t%pe is used to de+ine the t%pe o+ values returned b% return instructions within the method5 &he returns phrase is onl% re8uired i+ the method is to return values o+ a t%pe that is not Net e!! strings -class Rexx.5 I+ returns is speci+ied2 all return instructions -see page ::G. within the method must speci+% an e!pression5 %xample.
method filer(path, name) returns File return File(path||name)

&his method alwa%s returns a value which is a File object5

Signals
&he signals ke%word introduces a list o+ terms that evaluate to t%pes that are "!ceptions -see page :B;.5 &his list enumerates and documents the e!ceptions that are signalled within the method -or b% a method which is called +rom the current method. but are not caught b% a catch clause in a control construct5

Version 2.00

NetRexx Language Definition

101

%xample.
method soup(cat) signals IOException, DivideByZero

It is considered good programming practice to use this list to document DunusualE e!ceptions signalled b% a method5 Implementations that support the concept o+ checked e!ceptions -see page :B<. must report as an error an% checked e!ception that is incorrectl% included in the list -that is2 i+ the e!ception is never signalled or would alwa%s be caught.5 (uch implementations ma% also o++er an option that en+orces the listing o+ all or some checked e!ceptions5

Duplicate methods
Methods ma% not duplicate properties or other methods in the same class5 (peci+icall%7 &he short name o+ a method must not be the same as the name o+ an% propert% in the same class5 &he number -=ero or more. and t%pes o+ the arguments o+ a method -or an% subset permitted b% omitting optional arguments. must not be the same as those o+ an% other method o+ the same name in the class -also checking an% subset permitted b% omitting optional arguments.5 Note that the second rule does allow multiple methods with the same name in a class2 provided that the number o+ arguments di++er or at least one argument di++ers in t%pe5

102

NetRexx Language Definition

Version 2.00

Nop instruction
nopF nop is a dumm% instruction that has no e++ect5 It can be use+ul as an e!plicit Ddo nothingE instruction +ollowing a then or else clause5

%xample.
select when a=b then nop when a>b then say 'A > B' otherwise say 'A < B' end -- Do nothing

Note. $utting an e!tra semicolon instead o+ the nop would merel% insert a null clause2 which would just be ignored b% Net e!!5 &he second when clause would then immediatel% +ollow the then2 and hence would be reported as an error5 nop is a true instruction2 however2 and is there+ore a valid target +or the then clause5

Version 2.00

NetRexx Language Definition

103

Numeric instruction
numeric digits Oe%prdPF form OscientificPF OengineeringPF

&he numeric instruction is used to change the wa% in which arithmetic operations are carried out b% a program5 &he e++ects o+ this instruction are described in detail in the section on 3*)&ers and !rith)eti$ -see page :G>.5
numeric digits

controls the precision under which arithmetic operations will be evaluated5 I+ no e!pression e%prd is given then the de+ault value o+ C is used5 /therwise the result o+ the e!pression is rounded2 i+ necessar%2 according to the current setting o+ numeric digits be+ore it is used5 &he value used must be a positive whole number5 &here is normall% no limit to the value +or numeric digits -e!cept the constraints imposed b% the amount o+ storage and other resources available. but note that high precisions are likel% to be e!pensive in processing time5 It is recommended that the de+ault value be used wherever possible5 Note that small values o+ numeric digits -+or e!ample2 values less than A. are generall% onl% use+ul +or ver% speciali=ed applications5 &he setting o+ numeric digits a++ects all computations2 so even the operation o+ loops ma% be a++ected b% rounding i+ small values are used5 I+ an implementation does not support a re8uested value +or numeric digits then the instruction will +ail with an e!ception -which ma%2 as usual2 be caught with the catch clause o+ a control construct.5 &he current setting o+ numeric digits ma% be retrieved with the digits special word -see page :<>.5

numeric form

controls which +orm o+ e!ponential notation -see page :G?. is to be used +or the results o+ operations5 &his ma% be either s$ienti#i$ -in which case onl% one2 non1=ero2 digit will appear be+ore the decimal point.2 or engineering -in which case the power o+ ten will alwa%s be a multiple o+ three2 and the part be+ore the decimal point will be in the range : through CCC.5 &he de+ault notation is scienti+ic5 &he +orm is set directl% b% the sub1ke%words scientific or engineeringF i+ neither sub1 ke%word is given2 scientific is assumed5 &he current setting o+ numeric form ma% be retrieved with the form special word -see page :<>.5 I+ an implementation does not support a re8uested value +or numeric form then the instruction will +ail with an e!ception -which ma%2 as usual2 be caught with the catch clause o+ a control construct.5

&he numeric instruction ma% be used where needed as a d%namicall% e!ecuted instruction in a method5 It ma% also appear2 more than once i+ necessar%2 be+ore the +irst method in a class2 in which case it +orms the de+ault setting +or the initiali=ation o+ subse8uent properties in the class and +or all methods in the class5 In this case2 an% e!ception due to the numeric instruction is raised when the class is +irst loaded5

104

NetRexx Language Definition

Version 2.00

6urther2 one or more numeric instructions ma% be placed be+ore the +irst class instruction in a programF the% do not impl% the start o+ a class5 &he numeric settings then appl% to all classes in the program -e!cept inter+ace classes.2 as though the numeric instructions were placed immediatel% +ollowing the class instruction in each class -e!cept that the% will not be traced.5

Version 2.00

NetRexx Language Definition

105

Options instruction
options wordlistF

where wordlist is one or more sy)&ols separated b% blanks5 &he options instruction is used to pass special re8uests to the language processor -+or e!ample2 an interpreter or compiler.5 Individual words2 known as option words2 in the wordlist which are meaning+ul to the language processor will be obe%ed -these might control optimi=ations2 en+orce standards2 enable implementation1dependent +eatures2 et$..F those which are not recogni=ed will be ignored -the% are assumed to be instructions to a di++erent language processor.5 /ption words in the list that are known will be recogni=ed independentl% o+ case5 &here ma% be =ero or more options instructions in a program5 &he% appl% to the whole program2 and must come be+ore the +irst class instruction -or an% instruction that starts a class.5 In the re#eren$e i)ple)entation, the known option words are8
binary

!ll $lasses in this progra) will &e &inary $lasses :see page 00>. In &inary $lasses, literals are assigned &inary :pri)iti"e> or nati"e string types, rather than 3et/e%% types, and nati"e &inary operations are *sed to i)ple)ent operators where appropriate, as des$ri&ed in @Binary "al*es and operationsA :see page 1D9>. In $lasses that are not &inary, ter)s in e%pressions are $on"erted to the 3et/e%% string type, Rexx, &e#ore *se &y operators. Co))ents #ro) the 3et/e%% so*r$e progra) will &e passed thro*gh to the the Ca"a o*tp*t #ile :whi$h )ay &e sa"ed with a .java.keep e%tension &y *sing the -keep $o))and option>. 2ine $o))ents &e$o)e Ca"a line $o))ents :introd*$ed &y @//A>. Blo$k $o))ents &e$o)e Ca"a &lo$k $o))ents :deli)ited &y @/*A and @*/A>, with nested &lo$k $o))ents ha"ing their deli)iters $hanged to @(-A and @-)A>.

comments

compact

/e9*ests that warnings and error )essages &e displayed in $o)pa$t #or). 1his #or)at is )ore easily parsed than the de#a*lt #or)at, and is intended #or *se &y editing en"iron)ents. 'a$h error )essage is presented as a single line, pre#i%ed with the error token identi#i$ation en$losed in s9*are &ra$kets. 1he error token identi#i$ation $o)prises three words, with one &lank separating the words. 1he words are8 the so*r$e #ile spe$i#i$ation, the line n*)&er o# the error token, the $ol*)n in whi$h it starts, and its length. For e%a)ple :all on one line>8
[D:\test\test.nrx 3 8 5] Error: The external name 'class' is a Java reserved word, so would not be usable from Java programs

!ny &lanks in the #ile spe$i#i$ation are repla$ed &y a n*ll :'\0'> $hara$ter. !dditional words $o*ld &e added to the error token identi#i$ation later.

106

NetRexx Language Definition

Version 2.00

console

/e9*ests that $o)piler )essages &e written to $onsole :the de#a*lt>. 6se -noconsole to pre"ent )essages &eing written to the $onsole. 1his option only has an e##e$t as a $o)piler option, and applies to all progra)s &eing $o)piled.

crossref decimal

/e9*ests that $ross;re#eren$e listings o# "aria&les &e prepared, &y $lass. 4e$i)al arith)eti$ )ay &e *sed in the progra). I# nodecimal is spe$i#ied, the lang*age pro$essor will report operations that *se :or, like nor)al string $o)parison, )ight *se> de$i)al arith)eti$ as an error. 1his option is intended #or per#or)an$e;$riti$al progra)s where the o"erhead o# inad"ertent *se o# de$i)al arith)eti$ is *na$$epta&le. /e9*ests that diagnosti$ in#or)ation :#or e%peri)ental *se only> &e displayed. 1he diag option word )ay also ha"e side;e##e$ts. /e9*ires that all lo$al "aria&les )*st &e e%pli$itly de$lared :&y assigning the) a type &*t no "al*e> &e#ore assigning any "al*e to the). 1his option is intended to per)it the en#or$e)ent o# @ho*se stylesA :&*t note that the 3et/e%% $o)piler always $he$ks #or "aria&les whi$h are re#eren$ed &e#ore their #irst assign)ent, and warns o# "aria&les whi$h are set &*t not *sed>. /e9*ests that the translator o*tp*t #ile :Ca"a so*r$e $ode> &e #or)atted #or i)pro"ed reada&ility. 3ote that i# this option is in e##e$t, line n*)&ers #ro) the inp*t #ile will not &e preser"ed :so r*n;ti)e errors and e%$eption tra$e;&a$ks )ay show in$orre$t line n*)&ers>. /e9*ests that Ca"a so*r$e $ode &e prod*$ed &y the translator. I# nojava is spe$i#ied, no Ca"a so*r$e $ode will &e prod*$edB this $an &e *sed to sa"e a little ti)e when $he$king o# a progra) is re9*ired witho*t any $o)pilation or Ca"a $ode res*lting. /e9*ests that the lang*age pro$essor display an introd*$tory logotype se9*en$e :na)e and "ersion o# the $o)piler or interpreter, et$.>. /e9*ests that repla$e)ent o# the translator o*tp*t :.java> #ile &e allowed. 1he de#a*lt, noreplace, pre"ents an e%isting .java #ile &eing a$$identally o"erwritten. /e9*ests that $o)piler )essages &e written to the #ile 3et/e%%C.log in the $*rrent dire$tory. 1he )essages are also displayed on the $onsole, *nless -noconsole is spe$i#ied. 1his option only has an e##e$t as a $o)piler option, and applies to all progra)s &eing $o)piled.

diag explicit

format

java

logo replace savelog

sourcedir

/e9*ests that all .class #iles &e pla$ed in the sa)e dire$tory as the so*r$e #ile #ro) whi$h they are $o)piled. ?ther o*tp*t #iles are already pla$ed in that dire$tory. 3ote that *sing this option will pre"ent the -run $o))and option #ro) working *nless the so*r$e dire$tory is the $*rrent dire$tory. /e9*ires that )ethod in"o$ations always spe$i#y parentheses, e"en when no arg*)ents are s*pplied. !lso, i# strictargs is in e##e$t, )ethod arg*)ents are $he$ked #or *sage 7 a warning is gi"en i# no re#eren$e to the arg*)ent is )ade in the )ethod. /e9*ires that only e%a$t type )at$hes &e allowed in assign)ents :this is stronger than Ca"a re9*ire)ents>. 1his also applies to the )at$hing o# arg*)ents in )ethod
NetRexx Language Definition 107

strictargs

strictassign

Version 2.00

$alls.
strictcase

/e9*ires that lo$al and e%ternal na)e $o)parisons #or "aria&les, properties, )ethods, $lasses, and spe$ial words )at$h in $ase :that is, na)es )*st &e identi$al to )at$h>. /e9*ires that all i)ported pa$kages and $lasses &e i)ported e%pli$itly *sing import instr*$tions. 1hat is, i# in e##e$t, there will &e no a*to)ati$ i)ports :see page 07>, e%$ept those related to the package instr*$tion. 1his option only has an e##e$t as a $o)piler option, and applies to all progra)s &eing $o)piled.

strictimport

strictprops

/e9*ires that all properties, in$l*ding those lo$al to the $*rrent $lass, &e 9*ali#ied in re#eren$es. 1hat is, i# in e##e$t, lo$al properties $annot appear as si)ple na)es &*t )*st &e 9*ali#ied &y this. :or e9*i"alent> or the $lass na)e :#or stati$ properties>. /e9*ires that all $he$ked e%$eptions :see page 1G,> signalled within a )ethod &*t not $a*ght &y a catch $la*se &e listed in the signals phrase o# the )ethod instr*$tion. .y)&ol ta&le in#or)ation :na)es o# lo$al "aria&les, et$.> will &e in$l*ded in any generated .class #ile. 1his option is pro"ided to aid the prod*$tion o# $lasses that are easy to analyse with tools that $an *nderstand the sy)&ol ta&le in#or)ation. 1he *se o# this option in$reases the si=e o# .class #iles. I# gi"en as trace, trace1, or trace2, then trace instr*$tions are a$$epted. 1he tra$e o*tp*t is dire$ted a$$ording to the option word8 trace1 re9*ests that tra$e o*tp*t is written to the standard o*tp*t strea), trace or trace2 i)ply that the o*tp*t sho*ld &e written to the standard error strea) :the de#a*lt>. I# notrace is gi"en, then tra$e instr*$tions are ignored. 1he latter $an &e *se#*l to pre"ent tra$ing o"erheads while lea"ing trace instr*$tions in a progra).

strictsignal symbols

trace, traceX

utf8

I# gi"en, $la*ses #ollowing the options instr*$tion are e%pe$ted to &e en$oded *sing 61F;0, so all 6ni$ode $hara$ters )ay &e *sed in the so*r$e o# the progra). In 61F;0 en$oding, 6ni$ode $hara$ters less than '\u0080' are represented *sing one &yte :whose )ost;signi#i$ant &it is 0>, $hara$ters in the range '\u0080' thro*gh '\u07FF' are en$oded as two &ytes, in the se9*en$e o# &its8
110xxxxx 10xxxxxx

where the ele"en digits shown as x are the least signi#i$ant ele"en &its o# the $hara$ter, and $hara$ters in the range '\u0800' thro*gh '\uFFFF' are en$oded as three &ytes, in the se9*en$e o# &its8
1110xxxx 10xxxxxx 10xxxxxx

where the si%teen digits shown as x are the si%teen &its o# the $hara$ter. I# noutf8 is gi"en, #ollowing $la*ses are ass*)ed to $o)prise only 6ni$ode $hara$ters in the range '\x00' thro*gh '\xFF', with the )ore signi#i$ant &yte o# the en$oding o# ea$h $hara$ter &eing 0. Note: this option only has an e##e$t as a $o)piler option, and applies to all progra)s &eing $o)piled. I# present on an options instr*$tion, it is $he$ked and )*st )at$h the $o)piler option :this allows pro$essing with or witho*t utf8 to &e en#or$ed>.
verbose,
108

.ets the @noisinessA o# the lang*age pro$essor. 1he digit X )ay &e any o# the digits 0
NetRexx Language Definition Version 2.00

verboseX

thro*gh 5B i# o)itted, a "al*e o# 3 is *sed. 1he options noverbose and verbose0 &oth s*ppress all )essages e%$ept errors and warnings.

Pre#i%ing any o# the a&o"e with @noA t*rns the sele$ted option o##. !ample:
options binary nocrossref nostrictassign strictargs

1he de#a*lt settings o# the "ario*s options are8

nobinary nocomments nocompact console crossref decimal nodiag noexplicit noformat java logo noreplace nosavelog nosourcedir nostrictargs nostrictassign nostrictcase nostrictimport nostrictprops nostrictsignal nosymbols trace2 noutf8 verbose3

+hen an option word is repeated :in the sa)e options instr*$tion or not>, or $on#li$ting option words are spe$i#ied, then the last *se deter)ines the state o# the option. !ll option words )ay also &e set as $o))and line options when in"oking the pro$essor, &y pre#i%ing the) with @-A8 !ample:
java COM.ibm.netrexx.process.NetRexxC -format foo.nrx

In this $ase, any options )ay $o)e &e#ore, a#ter, or &etween #ile spe$i#i$ations. +ith the e%$ept o# the utf8 option :see a&o"e>, options set with the options instr*$tion o"erride $o))and;line settings, #ollowing the @last *seA r*le. For )ore in#or)ation, see the installation and *ser do$*)entation #or yo*r i)ple)entation.

Version 2.00

NetRexx Language Definition

109

Package instruction
package na)eF

where na)e is one or more non1numeric sy)&ols separated b% periods5 &he package instruction is used to de+ine the package to which the class or classes in the current program belong5 Classes that belong to the same package have privileged access to other classes in the same package2 in that each class is visible to all other classes in the same package2 even i+ not declared public5 $ackages also convenientl% group classes +or use b% the import instruction -see page @?.5 &he na)e must speci+% a pa$kage na)e2 which is one or more non1numeric s%mbols2 separated b% periods2 with no blanks5 &here must be at most one package instruction in a program5 It must precede an% class instruction -or an% instruction that would start the de+ault class.5 I+ a program contains no package instruction then its package is implementation1de+ined5 &%picall% it is grouped with other programs in some implementation1de+ined logical collection2 such as a director% in a +ile s%stem5 %xample,.
package testpackage package com.ibm.venta

*hen a class is identi+ied as belonging to a package2 it has a 9*ali#ied $lass na)e2 which is its short name2 as given on the class instruction -see page ?@.2 pre+i!ed with the package name and a period5 6or e!ample2 i+ the short name o+ a class is DRxLanguageE and the package name is Dcom.ibm.ventaE then the 8uali+ied name o+ the class would be Dcom.ibm.venta.RxLanguageE5 In the re#eren$e i)ple)entation, pa$kages are kept in a hierar$hy deri"ed #ro) the Ca"a $lasspath, where the seg)ents o# a pa$kage na)e $orrespond to a path in the hierar$hy. 1he hierar$hy is typi$ally the dire$tories in a #ile syste), or so)e e9*i"alent :s*$h as a @<ipA ar$hi"e #ile>, and so pa$kage na)es sho*ld &e $onsidered $ase;sensiti"e :as so)e Ca"a i)ple)entations *se $ase;sensiti"e #ile syste)s>.

110

NetRexx Language Definition

Version 2.00

Parse instruction
parse ter) te)plateF

where te)plate is one or more non1numeric sy)&ols separated b% blanks andMor patterns2 and a pattern is one o+7 literalstring Oindi$atorP n*)&er Oindi$atorP -sy)&ol. and indi$ator is one o+ +2 -2 or =5 &he parse instruction is used to assign characters -+rom a string. to one or more variables according to the rules and templates described in the section Parsing te)plates -see page :<<.5 &he value o+ the ter) is e!pected to be a stringF i+ it is not a string2 it will be converted to a string5 An% variables used in the te)plate are named b% non1numeric sy)&ols -that is2 the% cannot be an arra% re+erence or other term.F the% re+er to a variable or propert% in the current class5 An% values that are used in patterns during the parse are converted to strings be+ore use5 An% variables set b% the parse instruction must have a known string t%pe2 or are given the Net e!! string t%pe2 Rexx2 i+ the% are new5 &he term itsel+ is not changed unless it is a variable which also appears in the template and whose value is changed b% being in the template5 %xample.
parse wordlist word1 wordlist

In this idiomatic e!ample2 the +irst word is removed +rom wordlist and is assigned to the variable word12 and the remainder is assigned back to wordlist5 Note,. :5 &he special words ask2 source2 and version2 as described in the section .pe$ial na)es and )ethods -see page :<>.2 allow7
parse ask x -- parses a line from input stream parse source x -- parses 'Java method filename' parse version x -- parses 'NetRexx version date'

&hese special words ma% also be used within e!pressions5 ;5 (imilarl%2 it is recommended that the initial -main. method in a stand1alone application place the command string passed to it in a variable called arg5B> I+ this is done2 the instruction7
parse arg template

will work2 in a stand1alone application2 in the same wa% as in e!! -even though arg is not a ke%word in this case.5B:
B> In the re#eren$e i)ple)entation, this is a*to)ati$ i# the main )ethod is generated &y the 3et/e%% lang*age pro$essor. B: Note2 though2 that the command string ma% have been edited b% the environmentF certain characters ma% not be allowed2 multiple blanks ma% have been reduced to single blanks2 et$. Version 2.00 NetRexx Language Definition 111

Properties instruction
properties O"isi&ilityP O)odi#ierP OdeprecatedP OunusedPF

where "isi&ility is one o+7

inheritable private public shared

and )odi#ier is one o+7

constant static transient volatile

and there must be at least one "isi&ility or )odi#ier ke%word5 &he properties instruction is used to de+ine the attributes o+ +ollowing property variables2 and there+ore must precede the +irst method instruction in a class5 A properties instruction replaces an% previous properties instruction -that is2 the attributes speci+ied on properties instructions are not cumulative.5 &he "isi&ility2 )odi#ier2 deprecated2 and unused ke%words ma% be in an% order5 An e!ample o+ the use o+ properties instructions ma% be +ound in the Progra) .tr*$t*re section -see page :;G.5

Visibility
$roperties ma% be public2 inheritable2 private2 or shared7B; A p*&li$ property is visible to -that is2 ma% be used b%. all other classes to which the current class is visible5 An inherita&le property is visible to -that is2 ma% be used b%. all classes in the same package and also those classes that e!tend -that is2 are subclasses o+. the current class2 and which 8uali+% the propert% using an object o+ the subclass2 or either this or super5 A pri"ate property is visible onl% within the current class5 A shared property is visible within the current package but is not visible outside the package5 (hared properties cannot be inherited b% classes outside the package5 B% de+ault2 i+ no properties instruction is used2 or "isi&ility is not speci+ied2 properties are inheritable -but not public.5B<

B; An e!perimental option +or "isi&ility2 indirect2 is described in Appendi! B -see page :?B.5 B< &he de+ault2 here2 was chosen to encourage the DencapsulationE o+ data within classes5 112 NetRexx Language Definition Version 2.00

Modifier
$roperties ma% also be constant2 static2 transient2 or volatile7 A $onstant property is associated with the class2 rather than with an instance o+ the class -an object.5 It is initiali=ed when the class is loaded and ma% not be changed therea+ter5 A stati$ property is associated with the class2 rather than with an instance o+ the class -an object.5 It is initiali=ed when the class is loaded2 and ma% be changed therea+ter5 A transient property is a propert% which should not be saved when an instance o+ the class is saved -made persistent.5 A "olatile property ma% change as%nchronousl%2 outside the control o+ the class2 even when no method in the class is being e!ecuted5 I+ an implementation does not allow as%nchronous modi+ication o+ properties2 it should ignore this ke%word5 Constant and static properties e!ist +rom when the class is +irst loaded -used.2 even i+ no object is constructed b% the class2 and there will onl% be one cop% o+ each propert%5 /ther properties are constructed and initiali=ed onl% when an object is constructed b% the classF each object then has its own cop% o+ such properties5 B% de+ault2 i+ no properties instruction is used2 or )odi#ier is not speci+ied2 properties are associated with an object constructed b% the class5

Deprecated
&he ke%word deprecated indicates that an% propert% introduced b% this instruction is depre$ated2 which implies that a better alternative is available and documented5 A compiler can use this in+ormation to warn o+ out1o+1date or other use that is not recommended5

Unused
&he ke%word unused indicates that the private properties which +ollow are not re+erenced e!plicitl% in the code +or the class2 and so a language processor should not warn that the% e!ist but have not been used5 I+ a "isi&ility ke%word is speci+ied it must be private5 6or e!ample7
properties private constant unused -- Serialization version serialVersionUID=long 8245355804974198832

Properties in interface classes

In inter+ace classes -see page ?C.2 properties must be both public and constant5 In such classes2 these attributes +or properties are the de+ault and the properties instruction must not be used5

Version 2.00

NetRexx Language Definition

113

Return instruction
return Oe%pressionPF return is used to return control -and possibl% a result. +rom a Net e!! program or method to the point

o+ its invocation5 &he e!pression -i+ an%. is evaluated2 active control constructs are terminated -as though b% a leave instruction.2 and the value o+ the e!pression is passed back to the caller5 &he result passed back to the caller is a string o+ t%pe Rexx2 unless a di++erent t%pe was speci+ied using the returns ke%word on the method instruction -see page C@. +or the current method5 In this case2 the t%pe o+ the value o+ the e!pression must match -or be convertible to2 as b% the rules +or assignment. the t%pe speci+ied b% the returns phrase5 *ithin a method2 the use o+ e!pressions on return must be consistent5 &hat is2 either all return instructions must speci+% a e!pression2 or none ma%5 I+ a returns phrase is given on the method instruction +or the current method then all return instructions must speci+% an e!pression5

114

NetRexx Language Definition

Version 2.00

Say instruction
say Oe%pressionPF say writes a string to the de+ault output character stream5 &his t%picall% causes it to be displa%ed -or

spoken2 or t%ped2 et$.. to the user5 %xample.

data=100 say data 'divided by 4 =>' data/4 /* would display: "100 divided by 4 => 25"

*/

&he result o+ evaluating the e%pression is e!pected to be a stringF i+ it is not a string2 it will be converted to a string5 &his result string is written +rom the program via an implementation1de+ined output stream5 B% de+ault2 the result string is treated as a DlineE -an implementation1dependent mechanism +or indicating line termination is e++ected a+ter the string is written.5 I+2 however2 the string ends in the NUL character -'\-' or '\0'. then that character is removed and line termination is not indicated5 &he result string ma% be o+ an% length5 I+ no e!pression is speci+ied2 or the e!pression result is null2 then an empt% line is written -that is2 as though the e!pression resulted in a null string.5

Version 2.00

NetRexx Language Definition

115

Select instruction
select Olabel na)eP Oprotect ter)P Ocase e%pressionPF

whenlist OotherwiseOFP instr*$tionlistP Ocatch O"are WP e%$eptionF instr*$tionlistP555 OfinallyOFP instr*$tionlistP end Ona)ePF where na)e is a non1numeric sy)&ol and whenlist is one or more when$onstr*$ts and when$onstr*$t is7
when e%pressionO2 e%pressionP555 OFP thenOFP instr*$tion

and instr*$tionlist is =ero or more instr*$tions5

select is used to conditionall% e!ecute one o+ several alternatives5 &he construct ma% optionall% be

given a label2 and ma% protect an object while the instructions in the construct are e!ecutedF e!ceptional conditions can be handled with catch and finally2 which +ollow the bod% o+ the construct5 (tarting with the +irst when clause2 each e!pression in the clause is evaluated in turn +rom le+t to right2 and i+ the result o+ an% evaluation is : -or e8uals the case e!pression2 see below. then the test has succeeded and the instruction +ollowing the associated then -which ma% be a comple! instruction such as if2 do2 loop2 or select. is e!ecuted and control will then pass directl% to the end5 I+ the result o+ all the e!pressions in a when clause is >2 control will pass to the ne!t when clause5 Note that once an e!pression evaluation in a when clause has resulted in a success+ul test2 no +urther e!pressions in the clause are evaluated5 I+ none o+ the when e!pressions result in :2 then control will pass to the instruction list -i+ an%. +ollowing otherwise5 In this situation2 the absence o+ an otherwise is a run1time error5BG Note,. :5 An instr*$tion ma% be an% assignment2 method call2 or ke%word instruction2 including an% o+ the more comple! constructions such as do2 loop2 if2 and the select instruction itsel+5 A null clause is not an instruction2 however2 so putting an e!tra semicolon a+ter the then is not e8uivalent to putting a dumm% instruction -as it would be in C or $LMI.5 &he nop instruction is provided +or this purpose5 ;5 &he ke%word then is treated speciall%2 in that it need not start a clause5 &his allows the e!pression on the when clause to be terminated b% the then2 without a D;E being re8uired 9 were this not so2 people used to other computer languages would be inconvenienced5 ,ence the s%mbol then cannot be used as a variable name within the e!pression5BB
BG In the re#eren$e i)ple)entation, a NoOtherwiseException is raised. BB (trictl% speaking2 then should onl% be recogni=ed i+ not the name o+ a variable5 In this special case2 however2 Net e!! 116 NetRexx Language Definition Version 2.00

Label phrase
I+ label is used to speci+% a na)e +or the select group2 then a leave instruction -see page C>. which speci+ies that name ma% be used to leave the group2 and the end that ends the group ma% optionall% speci+% the name o+ the group +or additional checking5 %xample.
select label roman when a=b then say 'same' when a<b then say 'lo' otherwise say 'hi' if a=0 then leave roman say 'a non-0' end roman

In this e!ample2 i+ the variable a has the value > and b is negative then just DhiE is displa%ed5

Protect phrase
I+ protect is given it must be +ollowed b% a ter) that evaluates to a value that is not just a t%pe and is not o+ a primitive t%peF while the select construct is being e!ecuted2 the value -object. is protected 9 that is2 all the instructions in the select construct have e!clusive access to the object5 Both label and protect ma% be speci+ied2 in an% order2 i+ re8uired5

Case phrase
I+ case is given it must +ollow an% label or protect phrase2 and must be +ollowed b% an e%pression5 *hen case is used2 the e!pression +ollowing it is evaluated at the start o+ the select construct5 &he result o+ the e!pression is then compared2 using the strict e8ualit% operator -==.2 to the result o+ evaluating the e!pression or e!pressions in each o+ the when clauses in turn until a match is +ound5 As usual2 i+ no match is +ound then control will pass to the instruction list -i+ an%. +ollowing otherwise2 and in this situation the absence o+ an otherwise is a run1time error5 6or e!ample2 in7
select when when when end case i+1 1 then say 'one' 1+1 then say 'two' 3, 4, 5 then say 'many'

then i+ i had the value : then the message displa%ed would be DtwoE5 &he third when clause in the e!ample demonstrates the use o+ the multiple e!pressions in a when clause in this conte!t5 (imilar to a select without case2 each e!pression is evaluated in turn +rom le+t to right and is then compared to the result o+ the case e!pression5 As soon as one matches that result2 e!ecution o+ the when clause stops -an% +urther e!pressions are not evaluated. and the instruction +ollowing the associated then clause is e!ecuted5 Note,. :5 *hen case is used2 the result o+ evaluating the e!pression +ollowing each when no longer has
language processors are permitted to treat then as reserved in the conte!t o+ a when clause2 to provide better per+ormance and more use+ul error reporting5 Version 2.00 NetRexx Language Definition 117

to be > or :5 Instead2 it must be possible to compare each result to the result o+ the case e!pression5 ;5 &he case e!pression is evaluated onl% on entr% to the select constructF it is not re1evaluated +or each when clause5 <5 An e!ception raised during evaluation o+ the case e!pression will be caught b% a suitable catch clause in the construct2 i+ one is present5 (imilarl%2 evaluation o+ the case e!pression is protected b% the protect phrase2 i+ one is present5 G5 In the re#eren$e i)ple)entation, a select case $onstr*$t will &e translated into a Ca"a switch $onstr*$t pro"ided that it )eets the #ollowing $riteria8 1he type o# the case e%pression is byte, char, int, or short. 1he "al*e o# all the e%pressions on the when $la*ses are pri)iti"e $onstants :that is, they $onsist o# only $onstants o# pri)iti"e types and operators "alid #or the) and so )ay &e e"al*ated at $o)pile ti)e>. 3o two e%pressions on the when $la*ses e"al*ate to the sa)e "al*e. It is not s*&5e$t to tra$ing. 6nder these $onditions the se)anti$s o# the switch $onstr*$t )at$h those de#ined #or select. 1he e%a)ple shown a&o"e wo*ld &e translated to a switch $onstr*$t i# i had type int and options binary were in e##e$t.

Exceptions in select constructs

"!ceptions that are raised b% the instructions within the bod% o+ the group2 or during evaluation o+ the case e!pression2 ma% be caught using one or more catch clauses that name the e%$eption that the% will catch5 *hen an e!ception is caught2 the e!ception object that holds the details o+ the e!ception ma% optionall% be assigned to a variable2 "are5 (imilarl%2 a finally clause ma% be used to introduce instructions that will alwa%s be e!ecuted at the end o+ the select group2 even i+ an e!ception is raised -whether caught or not.5 &he '%$eptions section -see page :B;. has details and e!amples o+ catch and finally5

118

NetRexx Language Definition

Version 2.00

Signal instruction
signal ter)F

&he signal instruction causes an DabnormalE change in the +low o+ control2 b% raising an e%$eption5 &he e!ception ter) ma% be a term that constructs or evaluates to an e!ception object2 or it ma% be e!pressed as the name o+ an e!ception t%pe -in which case the de+ault constructor2 with no arguments2 +or that t%pe is used to construct an e!ception object.5 &he e!ception object then represents the e!ception and is available2 i+ re8uired2 when the e!ception is handled5 &he handling o+ e!ceptions is detailed in the '%$eptions section -see page :B;.5 In summar%2 when an e!ception is signalled2 all active pending do groups2 loop loops2 if constructs2 and select constructs ma% be ended5 6or each one in turn2 +rom the innermost7 :5 No +urther clauses within the bod% o+ the construct will be e!ecuted -in this respect2 signal acts like a leave +or the construct.5 ;5 &he instr*$tionlist +ollowing the +irst catch clause that matches the e!ception2 i+ an%2 is e!ecuted5 <5 &he instr*$tionlist +ollowing the finally clause +or the construct2 i+ an%2 is e!ecuted5 I+ a catch matched the e!ception the e!ception is deemed handled2 and e!ecution resumes as though the construct ended normall% -unless a new e!ception was signalled in the catch or finally instruction lists2 in which case it is processed.5 /therwise2 an% enclosing construct is ended in the same manner5 I+ there is no enclosing construct2 then the current method is ended and the e!ception is signalled in the caller5 %xample,.
signal RxErrorTrace signal DivideException('Divide by zero')

In the re#eren$e i)ple)entation, the ter) )*st either e"al*ate to an o&5e$t that is assigna&le to the type Throwable :#or e%a)ple, a s*&$lass o# Exception or RuntimeException>. &e a type that is a s*&$lass o# Throwable, in whi$h $ase the de#a*lt $onstr*$tor :with no arg*)ents> #or the gi"en type is *sed to $onstr*$t the e%$eption o&5e$t.

Version 2.00

NetRexx Language Definition

119

Trace instruction
trace tra$eoptionF

where tra$eoption is one o+7 tra$esetting var O"arlistP where tra$esetting is one o+7
all methods off results

and "arlist is one or more variable na)es2 optionall% pre+i!ed with a + or &he trace instruction is used to control the tracing o+ the e!ecution o+ Net e!! methods2 and is primaril% used +or debugging5 It ma% change either the general trace setting or ma% select or deselect the tracing o+ individual variables5 *ithin methods2 the trace instruction changes the trace setting or variables tracing when it is e!ecuted2 and a++ects the tracing o+ all clauses in the method which are then e!ecuted -until changed b% a later trace instruction.5 /ne or more trace instructions ma% appear be+ore the +irst method in a class2 one o+ which ma% set the initial trace setting +or all methods in the class -the de+ault is off. and others ma% set up variables tracing that applies to all the methods in the class5 &hese act as though the trace instructions were placed immediatel% +ollowing the method instruction in each method -e!cept that the% will not be traced.5 (imilarl%2 one or more trace instructions ma% be placed be+ore the +irst class instruction in a programF the% do not impl% the start o+ a class5 /ne o+ these ma% set the initial trace setting and others ma% set up variables tracing +or all classes in the program -e!cept inter+ace classes. and act as though the trace instructions were placed immediatel% +ollowing the class instruction in each class5

Tracing clauses
&he trace setting controls the tracing o+ clauses in a program2 and ma% be one o+ the +ollowing7
all

All clauses -e!cept null clauses without commentar%. which are in methods and which are e!ecuted a+ter the trace instruction will be traced5 I+ trace all is placed be+ore the +irst method in the current class2 the method instructions in the class2 together with the values o+ the arguments passed to each method2 will be traced when the method is invoked -that is2 trace all implies trace methods.5 All method clauses in the class will be traced when the method the% introduce is invoked2 together with the values o+ the arguments passed to each methodF no other clauses2 or results2 will be traced5 &he trace methods instruction must be placed be+ore the +irst method in the current class -as otherwise it would have no e++ect.5 &urns tracing o++F no +ollowing clauses2 variables2 or results will be traced5
NetRexx Language Definition Version 2.00

methods

off
120

results

All clauses -e!cept null clauses without commentar%. which are in methods and which are e!ecuted a+ter the trace instruction will be traced2 as though trace all had been re8uested5 In addition2 the results o+ all e%pression evaluations and an% results assigned to a variable b% an assignment2 loop2 or parse instruction are also traced5 I+ trace results is placed be+ore the +irst method in the current class2 the method instructions in the class will be traced when the method is invoked2 together with the values o+ the arguments passed to each method5

Note,. :5 &racing o+ clauses shows the data +rom the source o+ the program2 starting at the +irst character o+ the +irst token o+ the clause and including an% commentar% +rom that point until the end o+ the clause5 ;5 *hen a loop is being traced2 the loop clause itsel+ will be traced on ever% iteration o+ the loop2 as indicated b% the programmer's model -see page CA.F the end clause is onl% traced once2 when the loop completes normall%5 <5 *ith trace results2 an e!pression is not traced i+ it is immediatel% used +or an assignment -in an assignment instruction2 or when the control variable is initiali=ed in a loop instruction.5 &he assignment will trace the result o+ the e!pression5

Tracing variables
&he var option adds names to a list o+ monitored variablesF it can also remove names +rom the list5 I+ the name o+ a variable in the current class or method is in the list2 then trace results is turned on +or an% assignment2 loop2 or parse clause that assigns a new value to the named variable5 0ariable names are speci+ied b% listing them a+ter the var ke%word5 "ach name ma% be optionall% pre+i!ed b% a + or a - sign5 A + sign indicates that the variable is to be added to the list o+ monitored variables -the de+ault.2 and a - sign indicates that the variable is to be removed +rom the list5 Blanks ma% be added be+ore and a+ter variable names and signs to separate the tokens and to improve readabilit%5 6or e!ample7
trace var a b c -- now variables a, b, and c will be traced trace var -b -c d -- now variables a and d will be traced

Note,. :5 Names in the list +ollowing the var ke%word are simple s%mbols that name variables in the current class or current method5 &he variables ma% be properties2 method arguments2 or local variables2 and ma% be o+ an% t%pe2 including arra%s5 &he names are not case1sensitiveF an% variables whose names match2 independent o+ case2 will be monitored5 ;5 No variable name can appear more than once in the list on one trace var instruction5 ,owever2 it is not an error to add the name o+ a variable which does not e!ist or is not then assigned a value5 (imilarl%2 it is not an error to remove a name which is not currentl% being monitored5 <5 /ne or more trace var instructions -along with one other trace instruction. are allowed be+ore the +irst method in a class5 &he% all modi+% an initial list o+ monitored variables which is then
Version 2.00 NetRexx Language Definition 121

used +or all methods in the class5 (imilarl%2 trace var instructions are allowed be+ore the +irst class in a program2 in which case the% appl% to all classes -e!cept inter+ace classes.5 G5 /ther trace instructions do not a++ect the list o+ monitored variables5 &he trace off instruction ma% be used to turn o++ tracing completel%F in this case trace var -with or without an% variable names. will then turn the tracing o+ variables back on2 using the current -or modi+ied. variable list5 B5 6or a parse instruction2 onl% monitored variables have their assignments traced -unless trace results is alread% in e++ect.5

The format of trace output

&race output is either clauses +rom the program being traced2 or results -such as the results +rom e!pressions.5 &he +irst clause or result traced on an% line will be preceded b% its line number in the programF this is right1justi+ied in a space which allows +or the largest line number in the program2 plus one blank5 6ollowing clauses or results +rom the same line are preceded b% white space o+ the same widthF however2 an% change o+ line number causes the line number to be included5 Clauses that are traced will be displa%ed with the +ormatting -indention. and la%out used in the original source stream +or the program2 starting with the +irst character o+ the +irst token o+ the clause5 esults -i+ re8uested. are converted to a string +or tracing i+ necessar%2 are not indented2 and have a double 8uote pre+i!ed and su++i!ed so that leading and trailing blanks are apparentF i+2 however2 the result being traced is null -see page :<:. then the string D[null]E is shown -without 8uotes.5 6or results with an associated name -the values assigned to local variables2 method arguments2 or properties in the current class.2 the name o+ the result precedes the data2 separated b% a single blank5 6or clarit%2 implementations ma% replace Dcontrol codesE in the encoding o+ results -+or e!ample2 "BC#IC values less than '\x40'2 or Unicode values less than '\x20'. b% a 8uestion mark -D?E.5 All lines displa%ed during tracing have a three character tag to identi+% the t%pe o+ data being traced5 &his tag +ollows the line number -or the space +or a line number.2 and is separated +rom the line number b% a single blank5 &he traced clause or result +ollows the tag2 a+ter another blank5 &he identi+ier tags ma% be7
*=* *-*

identi+ies the +irst line o+ the source o+ a single clause2 i.e.2 the data actuall% in the program5 identi+ies a continuation line +rom the source o+ a single clause5 Continuations ma% be due to the use o+ a continuation character -see page GG. or to the use o+ a block comment -see page G>. which spans more than one line5 Identi+ies a value assigned to a method argument o+ the current method5 &he name o+ the argument is included in the trace5 Identi+ies a value assigned to a propert%5 &he name o+ the propert% is included in the trace i+ the propert% is in the current class5 Identi+ies a value assigned to a local variable in the current method5 &he name o+ the variable is included in the trace5 Identi+ies the result o+ an e!pression evaluation that is not used +or an assignment -+or e!ample2 an argument e!pression in a method call.5 eserved +or error messages that are not supplied b% the environment underl%ing the
NetRexx Language Definition Version 2.00

>a> >p> >v> >>> +++

122

implementation5 I+ a trace line is produced in a di++erent conte!t -program or thread. +rom the preceding trace line -i+ an%. then a tra$e $onte%t line is shown5 &his shows the name o+ the program that produced the trace line2 and also the name o+ the thread -and thread group. o+ the conte!t5 &he thread group name is not shown i+ it is main2 and in this case the thread name is then also suppressed i+ its name is main5 %xample,. I+ the +ollowing instructions2 starting on line B< o+ a :;>1line program2 were e!ecuted7
trace all if i=1 then say 'Hello' else say 'i<>1' say 'A continued line'

the trace output -i+ i were 1. would be7

54 *=* if i=1 *=* then *=* say 'Hello' 56 *=* say 57 *-* 'A continued line'

(imilarl%2 +or the <1line program7

trace results number=1/7 parse number before '.' after

the trace output would be7

2 *=* >v> 3 *=* >v> >v> number=1/7 number "0.142857143" parse number before '.' after before "0" after "142857143"

Note,. :5 &race output is written to an implementation1de+ined output stream -t%picall% the Dstandard errorE output stream2 which lets it be redirected to a destination separate +rom the de+ault destination +or output which is used b% the say instruction.5 ;5 In some implementations2 the use o+ trace instructions ma% substantiall% increase the si=e o+ classes and the e!ecution time o+ methods a++ected b% tracing5BA <5 *ith some implementations it ma% be possible to switch tracing on e!ternall%2 without re8uiring modi+ication to the program5

BA In the re#eren$e i)ple)entation, options notrace )ay &e *sed to disa&le all trace instr*$tions and hen$e ens*re that tra$ing o"erhead is not a$$identally in$*rred. Version 2.00 NetRexx Language Definition 123

Program structure
A Net e!! progra) is a collection o+ clauses -see page G>. derived +rom a single implementation1 de+ined source stream -such as a +ile.5 *hen a program is processed b% a language processorB? it de+ines one or more classes5 Classes are usuall% introduced b% the class instruction -see page ?@.2 but i+ the +irst is a standard class2 intended to be run as a stand1alone application2 then the class instruction can be omitted5 In this case2 Net e!! de+ines an implied class and initiali=ation method that will be used5 &he implied class and method permits the writing o+ Dlow boilerplateE programs2 with a minimum o+ s%nta!5 &he simplest2 documented2 Net e!! program that has an e++ect might there+ore be7 %xample.
/* This is a very simple NetRexx program */ say 'Hello World!'

In more detail2 a Net e!! program consists o+7 :5 An optional prolog -package2 import2 and options instructions.5 /nl% one package instruction is permitted per program5 ;5 /ne or more class de+initions2 each introduced b% a class instruction5 A $lass de#inition comprises7 :5 &he class instruction which introduces the class -which ma% be in+erred2 see below.5 ;5 Sero or more propert% variable assignments2 along with optional properties instructions that can alter their attributes2 and optional numeric and trace instructions5 $ropert% variable assignments take the +orm o+ an assign)ent -see page AC.2 with an optional D=E and e!pression2 which ma%7 just name a propert% -b% omitting the D=E and e!pression o+ the assignment.2 in which case it re+ers to a string o+ t%pe Rexx assign a t%pe to the propert% -when the e!pression evaluates to just a t%pe. assign a t%pe and initial value to the propert% -when the e!pression returns a value.5 <5 Sero or more method de+initions2 each introduced b% a method instruction -which ma% be in+erred i+ the class instruction is in+erred2 see below.5 A )ethod de#inition comprises7 An% Net e!! instructions2 e!cept the class2 method2 and properties instructions and those allowed in the prolog -the package2 import2 and options instructions.5

B? (uch as a compiler or interpreter5 124 NetRexx Language Definition Version 2.00

%xample.
/* A program with two classes */ import java.applet. -- for example class testclass extends Applet properties public state -- property of type 'Rexx' i=int -- property of type 'int' properties constant j=int 3 -- property initialized to '3' method start say 'I started' state='start' method stop say 'I stopped' state='stop' class anotherclass method testing loop i=1 to 10 say '1, 2, 3, 4...' if i=7 then return end return method anothertest say '1, 2, 3, 4'

&his e!ample shows a prolog -with just an import instruction. +ollowed b% two classes5 &he +irst class includes two public properties2 one constant propert%2 and two methods5 &he second class includes no properties2 but also has two methods5 Note that a return instruction implies no static scopingF the content o+ a method is ended b% a method -or class. instruction2 or b% the end o+ the source stream5 &he return instruction at the end o+ the testing method is2 there+ore2 unnecessar%5

Program defaults
&he +ollowing de+aults are provided +or Net e!! programs7 :5 I+2 while parsing prolog instructions2 some instruction that is not valid +or the prolog and is not a class instruction is encountered2 then a de+ault class instruction -with an implementation1 provided short name2 t%picall% derived +rom the name o+ the source stream. is inserted5 I+ the instruction was not a method instruction2 then a de+ault method instruction -with a name and attributes appropriate +or the environment2 such as main. is also inserted5 In this latter case2 it is assumed that e!ecution o+ the program will begin b% invocation o+ the de+ault method5 In other words2 a Dstand1aloneE application can be written without e!plicitl% providing the class and method instructions +or the +irst method to be e!ecuted5 An e!ample o+ such a program is given in Appendi! A -see page :?:.5 In the re#eren$e i)ple)entation, the main )ethod in a stand;alone appli$ation is passed the words #or)ing the $o))and string as an array o# strings o# type java.lang.String :one word to ea$h ele)ent o# the array>. +hen the 3et/e%% re#eren$e i)ple)entation pro"ides the main )ethod instr*$tion &y de#a*lt, it also $onstr*$ts a 3et/e%% string o# type Rexx #ro) this
Version 2.00 NetRexx Language Definition 125

array o# words, with a &lank added &etween words, and assigns the string to the "aria&le arg. 1he $o))and string )ay also ha"e &een edited &y the *nderlying operating syste) en"iron)entB $ertain $hara$ters )ay not &e allowed, )*ltiple &lanks or whitespa$e )ay ha"e &een red*$ed to single &lanks, et$. ;5 I+ a method ends and the last instruction at the outer level o+ the method scope is not return then a return instruction is added i+ it could be reached5 In this case2 i+ a value is e!pected to be returned b% the method -due to other return instructions returning values2 or there being a returns ke%word on the method instruction.2 an error is reported5 Language processors ma% provide options to prevent2 or warn o+2 these de+aults being applied2 as desired5

126

NetRexx Language Definition

Version 2.00

Minor and Dependent classes

A )inor $lass in Net e!! is a class whose name is 8uali+ied b% the name o+ another class2 called its parent2 and a dependent $lass is a minor class that has a link to its parent class that allows a child object simpli+ied access to its parent object and its properties5

Minor classes
A )inor $lass in Net e!! is a class whose name is 8uali+ied b% the name o+ another class2 called its parent5 &his 8uali+ication is indicated b% the +orm o+ the name o+ the class7 the short name o+ the minor class is pre+i!ed b% the name o+ its parent class -separated b% a period.5 6or e!ample2 i+ the parent is called Foo then the +ull name o+ a minor class Bar would be written Foo.Bar5 &he short name2 Bar2 is used +or the name o+ an% constructor method +or the classF outside the class it can onl% be used to identi+% the class in the conte!t o+ the parent class -or +rom children o+ the minor class2 see below.5 &he names o+ minor classes ma% be used in e!actl% the same wa% as other class names -t%pes. in programs5 6or e!ample2 a propert% might be declared and initiali=ed thus7
abar=Foo.Bar null -- this has type Foo.Bar

or2 i+ the class has a constructor2 perhaps7

abar=Foo.Bar() -- constructs a Foo.Bar object

Minor classes must be in the same program -and hence in the same package. as their parent5 &he% are introduced b% a class instruction that speci+ies their +ull name2 +or e!ample7
class Foo.Bar extends SomeClass

Minor classes must immediatel% +ollow their parent class5B@ Minor classes ma% have a parent which is itsel+ a minor class2 to an% depthF the name and the positioning rules are e!tended as necessar%5 6or e!ample2 the +ollowing classes might e!ist in a program7
class Foo class Foo.Bar class Foo.Bar.Nod class Foo.Bar.Pod class Foo.Car

As be+ore2 the children o+ Foo.Bar immediatel% +ollow their parent5 &he list o+ children o+ Foo can be continued a+ter the children o+ Foo.Bar have all been speci+ied5 Note that the short name -last part o+ the name. o+ a minor class ma% not be the same as the short name o+ an% o+ its parents -a class Foo.Bar.Foo or a class Foo.Bar.Bar would be in error2 +or e!ample.5 &his allows minor classes to re+er to their parent classes b% their short name without ambiguit%5

Constructing objects in minor classes

A parent class can construct an object o+ a child class in the usual manner2 b% simpl% speci+%ing its constructor -identi+ied b% its short name2 +ull name2 or 8uali+ied name.5 6or e!ample2 a method in the Foo.Bar class above could construct an object o+ t%pe Foo.Bar.Nod using7
anod=Nod()
B@ &his allows compilers that generate 3ava source code to preserve line numbering5 Version 2.00 NetRexx Language Definition 127

-assuming the Foo.Bar.Nod class has a constructor that takes no arguments.5 (imilarl%2 minor classes can re+er to the t%pes and constructors o+ an% o+ its parents b% simpl% using their short names5 ,ence2 the Foo.Bar.Nod class could construct objects o+ its parents' t%pes thus7
abar=Bar() afoo=Foo()

-again assuming the parent classes have constructors that take no arguments.5 Classes other than the parent or an immediate child must use the +ull name -i+ necessar%2 8uali+ied b% the package name. to re+er to a minor class or its constructor5

Dependent classes
As described in the last section2 minor classes provide an enhanced packaging -naming. mechanism +or classes2 allowing classes to be structured within packages5 A stronger link between a child class and its parent is indicated b% the modi+ier ke%word dependent on the child class2 which indicates that the child is a dependent $lass5 6or e!ample7
class Foo.Dep dependent extends SomeClass method Dep -- this is the constructor

An object constructed +rom a dependent class -a dependent o&5e$t. is linked to the conte!t o+ an object o+ its parent t%pe -its parent o&5e$t.5 &he linkage thus provided allows the child object simpli+ied access to the parent object and its properties5 In the e!ample2 an object o+ t%pe Foo.Dep can onl% be constructed in the conte!t o+ a parent object2 which must be o+ t%pe Foo5

Constructing dependent objects

A parent class can construct a dependent object in the same wa% as when constructing objects o+ other child t%pesF that is2 b% simpl% speci+%ing its constructor5 In this case2 however2 the current object -this. becomes the parent object o+ the newl% constructed object5 6or e!ample2 a method in the Foo class above could construct a dependent object o+ t%pe Foo.Dep using7
adep=Dep()

-assuming the Dep class has a constructor that takes no arguments.5 In general2 +or a class to construct an object +rom a dependent class2 it must have a re+erence to an object o+ the parent class -which will become the parent o+ the new object.2 and the constructor must be called -b% its short name. in the conte!t o+ that parent object5 6or e!ample7
parentObject=Foo() adep=parentObject.Dep()

-In the same wa%2 the +irst e!ample could have been written7
adep=this.Dep()

within the parent class the this. is implied5. In order to subclass a dependent class2 the constructor o+ the dependent class must be invoked b% the subclass constructor in a similar manner5 In this case2 a 8uali+ied call to the usual special constructor super is used2 +or e!ample7

128

NetRexx Language Definition

Version 2.00

class ASub extends Foo.Dep method Asub(afoo=Foo) afoo.super()

&he 8uali+ier -afoo in the e!ample. must be either the name o+ an argument to the constructor2 or the special word parent -i+ the classes share a common parent class.2 or the short name o+ a parent class +ollowed b% .this -see below.5 &he call to super must be the +irst instruction in the method2 as usual2 and it must be present -it will not be generated automaticall% b% the compiler.5

Access to parent objects and their properties

#ependent classes have simpli+ied access to their parent objects and their properties5 In particular7 &he special word parent ma% be used to re+er to the parent object o+ the current object5 It ma% appear alone in a term2 or at the start o+ a compound term5 It can onl% be used in non1static conte!ts in a dependent class5 In general2 an% o+ the objects in the chain o+ parents o+ a dependent object ma% be re+erred to b% 8uali+%ing the special word this with the short name o+ the parent class5 6or e!ample2 e!tending the previous e!ample2 i+ the class Foo.Dep.Ent was a dependent class it could contain re+erences to Foo.this -the parent o+ its parent. or Dep.this -the latter being the same as speci+%ing parent.5 I+ pre+erred2 the +ull name or the +ull% 8uali+ied name o+ the parent class ma% be used instead o+ the short name5 Like parent2 this construct can onl% be used at the start o+ a term in non1static conte!ts in a dependent class5 As usual2 properties e!ternal to the current class must alwa%s be 8uali+ied in some wa% -+or e!ample2 the pre+i! parent. can be used in a term such as parent.aprop.5

Restrictions
Minor classes ma% have an% o+ the attributes -public2 interface2 et$.. o+ other classes2 and behave in ever% wa% like other classes2 with the +ollowing restrictions7 I+ a class is a static class -that is2 it contains onl% static or constant properties and methods. then an% children cannot be dependent classes -because no object o+ the parent class can be constructed.5 (imilarl%2 inter+ace classes and abstract classes cannot have dependent classes5 #ependent classes ma% not be inter+aces5 #ependent classes ma% not contain static or constant properties -or methods.5BC &hese must be placed in a parent which is not a dependent class5 Minor classes ma% be public onl% i+ their parent is also public5 -Note that this is the onl% case where more than one public class is permitted in a program5. In general7 a minor class cannot be more visible than its parent5

BC &his restriction allows compilation +or the 3ava plat+orm5 Version 2.00 NetRexx Language Definition 129

Special names and methods

6or convenience2 Net e!! provides some spe$ial na)es +or naming commonl%1used concepts within terms5 &hese are onl% recogni=ed i+ there is no variable o+ the same name previousl% seen in the current scope2 as described in the section on 1er)s -see page G@.5 &his allows the set o+ special words to be e!panded in the +uture2 i+ necessar%2 without invalidating e!isting variables5 &here+ore2 these names are not reservedF the% ma% be used as variable names instead2 i+ desired5 &here are also two Dspecial methodsE that are used when constructing objects5

Special names
&he +ollowing special names are allowed in Net e!! programs2 and are recogni=ed independentl% o+ case5A> *ith the e!ception o+ length and class2 these ma% onl% be used alone as a term or at the start o+ a compound term5
ask

eturns a string o+ t%pe Rexx2 read as a line +rom the implementation1de+ined de+ault input stream -o+ten the user's DconsoleE.5 %xample.
if ask='yes' then say 'OK' ask can onl% appear alone2 or at the start o+ a compound term5A:

class

&he object o+ t%pe Class that describes a speci+ic t%pe5 &his word is onl% recogni=ed as the second part o+ a compound term2 where the evaluation o+ the +irst part o+ the term resulted in a t%pe or 8uali+ied t%pe5 %xample.
obj=String.class say obj.isInterface /* would say '0' */

digits

&he current setting o+ numeric digits -see page :>G.2 returned as a string o+ t%pe Rexx5 &his will be one or more Arabic numerals2 with no leading blanks2 =eros2 or sign2 and no trailing blanks or e!ponent5
digits can onl% appear alone2 or at the start o+ a compound term5

form

&he current setting o+ numeric form -see page :>G.2 returned as a string o+ t%pe Rexx5 &his will have either the value DscientificE or the value DengineeringE5
form can onl% appear alone2 or at the start o+ a compound term5

length

&he length o+ an arra% -see page ?G.2 returned as an implementation1dependent binar% t%pe or string5 &his word is onl% recogni=ed as the last part o+ a compound term2 where the evaluation o+ the rest o+ the term resulted in an arra% o+ dimension :5 %xample.
foo=char[7] say foo.length /* would say '7' */

Note that %ou can get the length o+ a Net e!! string with the same s%nta!5A; In that
A> 6nless options strictcase is in e##e$t. A: In the re#eren$e i)ple)entation, ask is si)ply a shorthand #or RexxIO.Ask(). A; 6nless options strictargs is in e##e$t. 130 NetRexx Language Definition Version 2.00

case2 however2 a length() method is being invoked5

null

&he e)pty re#eren$e5 &his is a special value that represents Dno valueE and ma% be assigned to variables -or returned +rom methods. e!cept those whose t%pe is both primitive and undimensioned5 It ma% also be be used in a comparison +or e8ualit% -or ine8ualit%. with values o+ suitable t%pe2 and ma% be given a t%pe5 %xample,.
blob=int[3] blob=null ---mob=Mark null -'blob' refers to array of 3 ints 'blob' is still of type int[], but refers to no real object 'mob' is type 'Mark'

&he null value ma% be considered to represent the state o+ being uninitiali=ed5 It can onl% appear as simple s%mbol2 not as a part o+ a compound term5
source

eturns a string o+ t%pe Rexx identi+%ing the source o+ the current class5 &he string consists o+ the +ollowing words2 with a single blank between the words and no trailing or leading blanks7 :5 the name o+ the underl%ing environment -e.g.2 Java. ;5 either method -i+ the term is being used within a method. or class -i+ the term is being used within a propert% assignment2 be+ore the +irst method in a class. <5 an implementation1dependent representation o+ the name o+ the source stream +or the class -e.g.2 Fred.nrx.5
source can onl% appear alone2 or at the start o+ a compound term5

sourceline

&he line number o+ the +irst token o+ the current clause in the Net e!! program2 returned as a string o+ t%pe Rexx5 &his will be one or more Arabic numerals2 with no leading blanks2 =eros2 or sign2 and no trailing blanks or e!ponent5
sourceline can onl% appear alone2 or at the start o+ a compound term5

super

eturns a re+erence to the current object2 with a t%pe that is the t%pe o+ the class that the current object's class e!tends5 &his means that a search +or methods or properties which super 8uali+ies will start +rom the superclass rather than in the current class5 &his is used +or invoking a method or propert% -in the superclass or one o+ its superclasses. that has been overridden in the current class5 %xample.
method printit(x) say 'it' super.printit(x) -- modification -- now the usual processing

I+ a propert% being re+erenced is in +act de+ined b% a superclass o+ the current class2 then the pre+i! Dsuper.E is perhaps the clearest wa% to indicate that name re+ers to a propert% o+ a superclass rather than to a local variable5 -Hou could also 8uali+% it b% the name o+ the superclass5.
super can onl% appear alone2 or at the start o+ a compound term5 this

eturns a re+erence to the current object5 *hen a method is invoked2 +or e!ample in7

Version 2.00

NetRexx Language Definition

131

word=Rexx "hello" -- 'word' refers to "hello" say word.substr(3) -- invokes substr on "hello"

then the method substr in the class Rexx is invoked2 with argument '3'2 and with the properties o+ the value -object. "hello" available to it5 &hese properties ma% be accessed simpl% b% name2 or -more e!plicitl%. b% pre+i!ing the name with Dthis.E5 Using Dthis.E can make a method more readable2 especiall% when several objects o+ the same t%pe are being manipulated in the method5
this can onl% appear alone2 or at the start o+ a compound term5 trace

&he current trace -see page :;>. setting2 returned as a Net e!! string5 &his will be one o+ the words7
off var methods all results

-var is returned when clause tracing is o++ but variable tracing has then been turned on using a trace var instruction5.
trace can onl% appear alone2 or at the start o+ a compound term5 version

eturns a string o+ t%pe Rexx identi+%ing the version o+ the Net e!! language in e++ect when the current class was processed5 &he string consists o+ the +ollowing words2 with a single blank between the words and no trailing or leading blanks7 :5 A word describing the language5 &he +irst seven letters will be the characters NetRexx2 and the remainder ma% be used to identi+% a particular implementation or language processor5 &his word ma% not include an% periods5 ;5 &he language level description2 which must be a number with no sign or e!ponential part5 6or e!ample2 D2.00E is the language level o+ this de+inition5 <5 &hree words describing the language processor release date in the same +ormat as the de+ault +or the e!! Ddate()E +unction5A< 6or e!ample2 D22 May 2009E5
version can onl% appear alone2 or at the start o+ a compound term5

Special methods
Constructors -methods used +or constructing objects. in Net e!! must invoke a constructor o+ their superclass be+ore making an% modi+ications to the current object -or invoke another constructor in the current class.5 &his is simpli+ied and made e!plicit b% the provision o+ the special method names super and this2 which re+er to constructors o+ the superclass and current class respectivel%5 &hese special methods are onl% recogni=ed when used as the +irst2 method call2 instruction in a constructor2 as described in Methods and $onstr*$tors -see page B<.5 &heir names will be recogni=ed independentl% o+ case5AG In addition2 Net e!! provides special constructor methods +or the primitive t%pes that allow binar% construction o+ primitives5 &hese are described in Binary "al*es and arith)eti$ -see page :B>.5

A< As de+ined in !)eri$an 3ational .tandard #or In#or)ation 1e$hnology 7 Progra))ing 2ang*age /'HH, H,.27D;199 2 American National (tandards Institute2 New Hork2 :CCA5 AG 6nless options strictcase is in e##e$t. 132 NetRexx Language Definition Version 2.00

Parsing templates
&he parse instruction allows a selected string to be parsed -split up. and assigned to variables2 under the control o+ a te)plate5 &he various mechanisms in the template allow a string to be split up b% e!plicit matching o+ strings -called patterns.2 or b% speci+%ing numeric positions -positional patterns 9 +or e!ample2 to e!tract data +rom particular columns o+ a line read +rom a character stream.5 /nce split into parts2 each segment o+ the string can then be assigned to variables as a whole or b% words -delimited b% blanks.5 &his section +irst gives some in+ormal e!amples o+ how the parsing template can be used2 and then de+ines the algorithms in detail5

Introduction to parsing
&he simplest +orm o+ parsing template consists o+ a list o+ variable names5 &he string being parsed is split up into words -characters delimited b% blanks.2 and each word +rom the string is assigned to a variable in se8uence +rom le+t to right5 &he +inal variable is treated speciall% in that it will be assigned whatever is le+t o+ the original string and ma% there+ore contain several words5 6or e!ample2 in the parse instruction7
parse 'This is a sentence.' v1 v2 v3

the term -in this case a literal string. +ollowing the instruction ke%word is parsed2 and then7 the variable v1 would be assigned the value DThisE2 v2 would be assigned the value DisE2 and v3 would be assigned the value Da sentence.E5 Leading blanks are removed +rom each word in the string be+ore it is assigned to a variable2 as is the blank that delimits the end o+ the word5 &hus2 variables set in this manner -v1 and v2 in the e!ample. will never have leading or trailing blanks2 though v3 could have both leading and trailing blanks5 Note that the variables assigned values in a template are alwa%s given a new value and so i+ there are +ewer words in the string than variables in the template then the unused variables will be set to the null string5 &he second parsing mechanism uses a literal string in a template as a pattern2 to split up the string5 6or e!ample7
parse 'To be, or not to be?' w1 ',' w2

would cause the string to be scanned +or the comma2 and then split at that pointF the variable w1 would be set to DTo beE2 and w2 is set to D or not to be?E5 Note that the pattern itsel+ -and onl+ the pattern. is removed +rom the string5 "ach section o+ the string is treated in just the same wa% as the whole string was in the previous e!ample2 and so either section could be split up into words5 &hus2 in7
parse 'To be, or not to be?' w1 ',' w2 w3 w4 w2 and w3 would be assigned the values DorE and DnotE2 and w4 would be assigned the remainder7 Dto be?E5

I+ the string in the last e!ample did not contain a comma2 then the pattern would e++ectivel% DmatchE the end o+ the string2 so the variable to the le+t o+ the pattern would get the entire input string2 and the variables to the right would be set to a null string5 &he pattern ma% be speci+ied as a variable2 b% putting the variable name in parentheses5 &he +ollowing
Version 2.00 NetRexx Language Definition 133

instructions there+ore have the same e++ect as the last e!ample7

c=',' parse 'To be, or not to be?' w1 (c) w2 w3 w4

&he third parsing mechanism is the numeric positional pattern5 &his works in the same wa% as the string pattern e!cept that it speci+ies a column number5 (o7
parse 'Flying pigs have wings' x1 5 x2

would split the string at the +i+th column2 so x1 would be DFlyiE and x2 would start at column B and so be Dng pigs have wingsE5 More than one pattern is allowed2 so +or e!ample7
parse 'Flying pigs have wings' x1 5 x2 10 x3

would split the string at columns B and :>2 so x2 would be Dng piE and x3 would be Dgs have wingsE5 &he numbers can be relative to the last number used2 so7
parse 'Flying pigs have wings' x1 5 x2 +5 x3

would have e!actl% the same e++ect as the last e!ampleF here the +5 ma% be thought o+ as speci+%ing the length o+ the string to be assigned to x25 As with literal string patterns2 the positional patterns can be speci+ied as a variable b% putting the name o+ a variable2 in parentheses2 in place o+ the number5 An absolute column number should then be indicated b% using an e8uals sign -D=E. instead o+ a plus or minus sign5 &he last e!ample could there+ore be written7
start=5 length=5 data='Flying pigs have wings' parse data x1 =(start) x2 +(length) x3

(tring patterns and positional patterns can be mi!ed -in e++ect the beginning o+ a string pattern just speci+ies a variable column number. and some ver% power+ul things can be done with templates5 &he ne!t section describes in more detail how the various mechanisms interact5

Parsing definition
&his section describes the rules that govern parsing5 In its most general +orm2 a template consists o+ alternating pattern speci+ications and variable names5 Blanks ma% be added between patterns and variable names to separate the tokens and to improve readabilit%5 &he patterns and variable names are used strictl% in se8uence +rom le+t to right2 and are used once onl%5 In practice2 various simpler +orms are used in which either variable names or patterns ma% be omittedF we can there+ore have variable names without patterns in between2 and patterns without intervening variable names5 In general2 the value assigned to a variable is that se8uence o+ characters in the input string between the point that is matched b% the pattern on its le+t and the point that is matched b% the pattern on its right5 I+ the +irst item in a template is a variable2 then there is an implicit pattern on the le+t that matches the start o+ the string2 and similarl% i+ the last item in a template is a variable then there is an implicit pattern on the right that matches the end o+ the string5 ,ence the simplest template consists o+ a single
134 NetRexx Language Definition Version 2.00

variable name which in this case is assigned the entire input string5 (etting a variable during parsing is identical in e++ect to setting a variable in an assignment5 &he constructs that ma% appear as patterns +all into two categoriesF patterns that act b% searching +or a matching string -literal patterns.2 and numeric patterns that speci+% an absolute or relative position in the string -positional patterns.5 "ither o+ these can be speci+ied e!plicitl% in the template2 or alternativel% b% a re+erence to a variable whose value is to be used as the pattern5 6or the +ollowing e!amples2 assume that the +ollowing sample string is being parsedF note that all blanks are signi+icant 9 there are two blanks a+ter the +irst word DisE and also a+ter the second comma7
'This is the text which, I think, is scanned.'

Parsing with literal patterns

Literal patterns cause scanning o+ the data string to +ind a se8uence that matches the value o+ the literal5 Literals are e!pressed as a 8uoted string5 &he null string matches the end o+ the data5 &he template7
w1 ',' w2 ',' w3

when parsing the sample string2 results in7

w1 has the value "This is the text which" w2 has the value " I think" w3 has the value " is scanned."

,ere the string is parsed using a template that asks that each o+ the variables receive a value corresponding to a portion o+ the original string between commasF the commas are given as 8uoted strings5 Note that the patterns themselves are removed +rom the data being parsed5 A di++erent parse would result with the template7
w1 ',' w2 ',' w3 ',' w4

which would result in7

w1 w2 w3 w4 has the value has the value has the value has the value "This is the text which" " I think" " is scanned." "" (null string)

&his illustrates an important rule5 *hen a match +or a pattern cannot be +ound in the input string2 it instead DmatchesE the end o+ the string5 &hus2 no match was +ound +or the third ',' in the template2 and so w3 was assigned the rest o+ the string5 w4 was assigned a null string because the pattern on its le+t had alread% reached the end o+ the string5 Note that all variables that appear in a template in this wa% are assigned a new value5

Parsing strings into words

I+ a variable is directl% +ollowed b% one or more other variables2 then the string selected b% the patterns is assigned to the variables in the +ollowing manner5 "ach blank1delimited word in the string is assigned to each variable in turn2 e!cept +or the last variable in the group -which is assigned the remainder o+ the string.5 &he values o+ the variables which are assigned words will have neither leading nor trailing blanks5

Version 2.00

NetRexx Language Definition

135

&hus the template7

w1 w2 w3 w4 ','

would result in7

w1 w2 w3 w4 has the value has the value has the value has the value "This' "is" "the" "text which"

Note that the +inal variable -w4 in this e!ample. could have had both leading blanks and trailing blanks2 since onl% the blank that delimits the previous word is removed +rom the data5 Also observe that this e!ample is not the same as speci+%ing e!plicit blanks as patterns2 as the template7
w1 ' ' w2 ' ' w3 ' ' w4 ','

would in +act result in7

w1 w2 w3 w4 has the value has the value has the value has the value "This' "is" "" (null string) "the text which"

since the third pattern would match the third blank in the data5 In general2 when a variable is +ollowed b% another variable then parsing o+ the input into individual words is implied5 &he parsing process ma% be thought o+ as +irst splitting the original string up into other strings using the various kinds o+ patterns2 and then assigning each o+ these new strings to -=ero or more. variables5

Use of the period as a placeholder

A period -separated +rom an% s%mbols b% at least one blank. acts as a placeholder in a template5 It has e!actl% the same e++ect as a variable name2 e!cept that no variable is set5 It is especiall% use+ul as a Ddumm% variableE in a list o+ variables2 or to collect -ignore. unwanted in+ormation at the end o+ a string5 &hus the template7
. . . word4 .

would e!tract the +ourth word -DtextE. +rom the sample string and place it in the variable word45 Blanks between successive periods in templates ma% be omitted2 so the template7
... word4 .

would have the same result as the last template5

Parsing with positional patterns

$ositional patterns ma% be used to cause the parsing to occur on the basis o+ position within the string2 rather than on its contents5 &he% take the +orm o+ whole numbers2 optionall% preceded b% a plus2 minus2 or e8uals sign which indicate relative or absolute positioning5 &hese ma% cause the matching operation to Dback upE to an earlier position in the data string2 which can onl% occur when positional patterns are used5

136

NetRexx Language Definition

Version 2.00

A',olute po,itional pattern,. A number in a template that is not preceded b% a sign re+ers to a particular -absolute. character column in the input2 with : re+erring to the +irst column5 6or e!ample2 the template7
s1 10 s2 20 s3

results in7
s1 has the value "This is " s2 has the value "the text w" s3 has the value "hich, I think,

is scanned."

,ere s1 is assigned characters +rom the +irst through the ninth character2 and s2 receives input characters :> through :C5 As usual the +inal variable2 s32 is assigned the remainder o+ the input5 An e8uals sign -D=E. ma% be placed be+ore the number to indicate e!plicitl% that it is to be used as an absolute column positionF the last template could have been written7
s1 =10 s2 =20 s3

A positional pattern that has no sign or is preceded b% the e8uals sign is known as an a&sol*te positional pattern5 Relative po,itional pattern,. A number in a template that is preceded b% a plus or minus sign indicates movement relative to the character position at which the previous pattern match occurred5 &his is a relati"e positional pattern5 I+ a plus or minus is speci+ied2 then the position used +or the ne!t match is calculated b% adding -or subtracting. the number given to the last matched position5 &he last matched position is the position o+ the +irst character o+ the last match2 whether speci+ied numericall% or b% a string5 6or e!ample2 the instructions7
parse '123456789' 3 w1 +3 w2 3 w3

result in
w1 has the value "345" w2 has the value "6789" w3 has the value "3456789"

&he +3 in this case is e8uivalent to the absolute number 6 in the same position2 and ma% also be considered to be speci+%ing the length o+ the data string to be assigned to the variable w15 &his e!ample also illustrates the e++ects o+ a positional pattern that implies movement to a character position to the le+t o+ -or to. the point at which the last match occurred5 &he variable on the le+t is assigned characters through the end o+ the input2 and the variable on the right is2 as usual2 assigned characters starting at the position dictated b% the pattern5 A use+ul e++ect o+ this is that multiple assignments can be made7
parse x 1 w1 1 w2 1 w3

&his results in assigning the -entire. value o+ x to w12 w22 and w35 -&he +irst D1E here could be omitted as it is e++ectivel% the same as the implicit starting pattern described at the beginning o+ this section5. I+ a positional pattern speci+ies a column that is greater than the length o+ the data2 it is e8uivalent to speci+%ing the end o+ the data -i.e.2 no padding takes place.5 (imilarl%2 i+ a pattern speci+ies a column to the le+t o+ the +irst column o+ the data2 this is not an error but instead is taken to speci+% the +irst column o+ the data5

Version 2.00

NetRexx Language Definition

137

An% pattern match sets the Dlast positionE in a string to which a relative positional pattern can re+er5 &he Dlast positionE set b% a literal pattern is the position at which the match occurred2 that is2 the position in the data o+ the #irst character in the pattern5 &he literal pattern in this case is not removed +rom the parsed data5 &hus the template7
',' -1 x +1

will7 :5 6ind the +irst comma in the input -or the end o+ the string i+ there is no comma.5 ;5 Back up one position5 <5 Assign one character -the character immediatel% preceding the comma or end o+ string. to the variable x5 /ne possible application o+ this is looking +or abbreviations in a string5 &hus the instruction7
/* Ensure options have a leading blank and are in uppercase before parsing. */ parse (' 'opts).upper ' PR' +1 prword ' '

will set the variable prword to the +irst word in opts that starts with DPRE -in an% case.2 or will set it to the null string i+ no such word e!ists5 Note,. :5 &he positional patterns +0 and -0 are valid2 have the same e++ect2 and ma% be used to include the whole o+ a previous literal -or variable. pattern within the data string to be parsed into an% +ollowing variables5 ;5 As illustrated in the last e!ample2 patterns ma% +ollow each other in the template without intervening variable names5 In this case each pattern is obe%ed in turn +rom le+t to right2 as usual5 <5 &here ma% be blanks between the sign in a positional pattern and the number2 because Net e!! de+ines that blanks adjacent to special characters are removed5

Parsing with variable patterns

It is sometimes desirable to be able to speci+% a pattern b% using the value o+ a variable instead o+ a +i!ed string or number5 &his ma% be achieved b% placing the name o+ the variable to be used as the pattern in parentheses -blanks are not necessar% either inside or outside the parentheses2 but ma% be added i+ desired.5 &his is called a "aria&le re#eren$eF the value o+ the variable is converted to string be+ore use2 i+ necessar%5 I+ the parenthesis to the le+t o+ the variable name is not preceded b% an e8uals2 plus2 or minus sign -D=E2 D+E2 or D-E. the value o+ the variable is then used as though it were a literal -string. pattern5 &he variable ma% be one that has been set earlier in the parsing process2 so +or e!ample7
input="L/look for/1 10" parse input verb 2 delim +1 string (delim) rest

will set7
verb to 'L' delim to '/' string to 'look for' rest to '1 10'

138

NetRexx Language Definition

Version 2.00

I+ the le+t parenthesis i, preceded b% an e8uals2 plus2 or minus sign then the value o+ the variable is used as an absolute or relative positional pattern -instead o+ as a literal string pattern.5 In this case the value o+ the variable must be a non1negative whole number2 and -as be+ore. it ma% have been set earlier in the parsing process5

Version 2.00

NetRexx Language Definition

139

Numbers and Arithmetic

Net e!! arithmetic attempts to carr% out the usual operations -including addition2 subtraction2 multiplication2 and division. in as DnaturalE a wa% as possible5 *hat this reall% means is that the rules +ollowed are those that are conventionall% taught in schools and colleges5 ,owever2 it was +ound that un+ortunatel% the rules used var% considerabl% -indeed much more than generall% appreciated. +rom person to person and +rom application to application and in wa%s that are not alwa%s predictable5 &he Net e!! arithmetic described here is there+ore a compromise which -although not the simplest. should provide acceptable results in most applications5

Introduction
Numbers can be e!pressed in Net e!! ver% +le!ibl% -leading and trailing blanks are permitted2 e!ponential notation ma% be used. and +ollow conventional s%nta!5 (ome valid numbers are7
12 '-76' 12.76 ' + 0.003 ' 17. '.5' 4E+9 0.73e-7 /* /* /* /* /* /* /* /* A whole number */ A signed whole number */ Some decimal places */ Blanks around the sign, etc. */ Equal to 17 */ Equal to 0.5 */ Exponential notation */ Exponential notation */

-"!ponential notation means that the number includes a sign and a power o+ ten +ollowing an DEE that indicates how the decimal point will be shi+ted5 &hus 4E+9 above is just a short wa% o+ writing 40000000002 and 0.73e-7 is short +or 0.0000000735. &he arithmetic operators include addition -indicated b% a D+E.2 subtraction -D-E.2 multiplication -D*E.2 power -D**E.2 and division -D/E.5 &here are also two +urther division operators7 integer divide -D%E. which divides and returns the integer part2 and remainder -D//E. which divides and returns the remainder5 $re+i! plus -D+E. and pre+i! minus -D-E. operators are also provided5 *hen two numbers are combined b% an operation2 Net e!! uses a set o+ rules to de+ine what the result will be -and how the result is to be represented as a character string.5 &hese rules are de+ined in the ne!t section2 but in summar%7 esults will be calculated with up to some ma!imum number o+ signi+icant digits5 &hat is2 i+ a result re8uired more than C digits it would normall% be rounded to C digits5 6or instance2 the division o+ ; b% < would result in >5AAAAAAAA? -it would re8uire an in+inite number o+ digits +or per+ect accurac%.5 Hou can change the de+ault o+ C signi+icant digits b% using the numeric digits instruction5 &his lets %ou calculate using as man% digits as %ou need 9 thousands2 i+ necessar%5 "!cept +or the division and power operators2 trailing =eros are preserved -this is in contrast to most electronic calculators2 which remove all trailing =eros in the decimal part o+ results.5 (o2 +or e!ample7
2.40 2.40 2.40 2.40 + * / 2 2 2 2 => => => => 4.40 0.40 4.80 1.2

&his preservation o+ trailing =eros is desirable +or most calculations -and especiall% +inancial calculations.5
140 NetRexx Language Definition Version 2.00

I+ necessar%2 trailing =eros ma% be easil% removed with the strip method -see page :AA.2 or b% division b% :5 A =ero result is alwa%s e!pressed as the single digit '0'5 "!ponential +orm is used +or a result depending on its value and the setting o+ numeric digits -the de+ault is C digits.5 I+ the number o+ places needed be+ore the decimal point e!ceeds this setting2 or the absolute value o+ the number is less than 0.0000012 then the number will be e!pressed in e!ponential notationF thus
1e+6 * 1e+6

results in D1E+12E instead o+ D1000000000000E2 and

1 / 3E+10

results in D3.33333333E-11E instead o+ D0.0000000000333333333E5 An% mi!ture o+ Arabic numerals ->1C. and "!tra digits -see page G;. can be used +or the digits in numbers used in calculations5 &he results are e!pressed using Arabic numerals5

Definition
&his de+inition describes arithmetic +or Net e!! strings -t%pe Rexx.5 &he arithmetic operations are identical to those de+ined in the AN(I standard +or e!!5 AB

Numbers
A n*)&er in Net e!! is a character string that includes one or more decimal digits2 with an optional decimal point5 &he decimal point ma% be embedded in the digits2 or ma% be pre+i!ed or su++i!ed to them5 &he group o+ digits -and optional point. thus constructed ma% have leading or trailing blanks2 and an optional sign -D+E or D-E. which must come be+ore an% digits or decimal point5 &he sign ma% also have leading or trailing blanks5 &hus7
sign digit digits numeric number ::= ::= ::= ::= ::= + | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 digit [digit]... digits . [digits] | [.] digits [blank]... [sign [blank]...] numeric [blank]...

where i+ the implementation supports e!tra digits -see page G;. these are also accepted as digits2 providing that the% represent values in the range =ero through nine5 In this case each e!tra digit is treated as though it were the corresponding character in the range >1C5 Note that a single period alone is not a valid number5

Precision
&he ma!imum number o+ signi+icant digits that can result +rom an arithmetic operation is controlled b% the digits ke%word on the numeric instruction -see page :>G.7
numeric digits [expression];
AB !)eri$an 3ational .tandard #or In#or)ation 1e$hnology 7 Progra))ing 2ang*age /'HH, H,.27D;199 2 American National (tandards Institute2 New Hork2 :CCA5 Version 2.00 NetRexx Language Definition 141

&he e!pression is evaluated and must result in a positive whole number5 &his de+ines the precision -number o+ signi+icant digits. to which arithmetic calculations will be carried outF results will be rounded to that precision2 i+ necessar%5 I+ no e!pression is speci+ied2 then the de+ault precision is used5 &he de+ault precision is C2 that is2 all implementations must support at least nine digits o+ precision5 An implementation1dependent ma!imum -e8ual to or larger than C. ma% appl%7 an attempt to e!ceed this will cause e!ecution o+ the instruction to terminate with an e!ception5 &hus i+ an algorithm is de+ined to use more than C digits then i+ the numeric digits instruction succeeds then the computation will proceed and produce identical results to an% other implementation5 Note that numeric digits ma% set values below the de+ault o+ nine5 (mall values2 however2 should be used with care 9 the loss o+ precision and rounding thus re8uested will a++ect all Net e!! computations2 including -+or e!ample. the computation o+ new values +or the control variable in loops5 In the remainder o+ this section2 the notation digits re+ers to the current setting o+ numeric digits5 &his setting ma% also be re+erred to in e!pressions in programs b% using the digits special word -see page :<>.5

Arithmetic operators
Net e!! arithmetic is e++ected b% the operators D+E2 D-E2 D*E2 D/E2 D%E2 D//E2 and D**E -add2 subtract2 multipl%2 divide2 integer divide2 remainder2 and power. which all act upon two terms2 together with the pre+i! operators D+E and D-E -plus and minus. which both act on a single term5 &he result o+ all these operations is a Net e!! string2 o+ t%pe Rexx5 &his section describes the wa% in which these operations are carried out5 Be+ore ever% arithmetic operation2 the term or terms being operated upon have an% e!tra digits converted to the corresponding Arabic numeral -the digits >1C.5 &he% then have leading =eros removed -noting the position o+ an% decimal point2 and leaving just one =ero i+ all the digits in the number are =eros. and are then truncated to digits+1 signi+icant digitsAA -i+ necessar%. be+ore being used in the computation5 &he operation is then carried out under up to double that precision2 as described under the individual operations below5 *hen the operation is completed2 the result is rounded i+ necessar% to the precision speci+ied b% the numeric digits instruction5 ounding is done in the DtraditionalE manner2 in that the e!tra -guard. digit is inspected and values o+ B through C are rounded up2 and values o+ > through G are rounded down5A? A conventional =ero is supplied preceding a decimal point i+ otherwise there would be no digit be+ore it5 &railing =eros are retained +or addition2 subtraction2 and multiplication2 according to the rules given below2 e!cept that a result o+ =ero is alwa%s e!pressed as the single character '0'5 6or division2 insigni+icant trailing =eros are removed a+ter rounding5 &he format method -see page :A:. is de+ined to allow a number to be represented in a particular +ormat i+ the standard result provided b% Net e!! does not meet re8uirements5

AA &hat is2 to the precision set b% numeric digits2 plus one e!tra DguardE digit5 A? "venModd rounding would re8uire the abilit% to calculate to arbitrar% precision -that is2 to a precision not governed b% the setting o+ numeric digits. at an% time and is there+ore not the mechanism de+ined +or Net e!!5 142 NetRexx Language Definition Version 2.00

Arithmetic operation rules basic operators

&he basic operators -addition2 subtraction2 multiplication2 and division. operate on numbers as +ollows7 Addition and subtraction I+ either number is =ero then the other number2 rounded to digits digits i+ necessar%2 is used as the result -with sign adjustment as appropriate.5 /therwise2 the two numbers are e!tended on the right and le+t as necessar% up to a total ma!imum o+ digits+1 digits5 &he number with smaller absolute value ma% there+ore lose some or all o+ its digits on the right5A@ &he numbers are then added or subtracted as appropriate5 6or e!ample7
xxxx.xxx + yy.yyyyy

becomes7
xxxx.xxx00 + 00yy.yyyyy -----------zzzz.zzzzz

&he result is then rounded to digits digits i+ necessar%2 taking into account an% e!tra -carr%. digit on the le+t a+ter an addition2 but otherwise counting +rom the position corresponding to the most signi+icant digit o+ the terms being added or subtracted5 6inall%2 an% insigni+icant leading =eros are removed5 &he pre#i% operators are evaluated using the same rulesF the operations D+numberE and D-numberE are calculated as D0+numberE and D0-numberE2 respectivel%5 "ultiplication &he numbers are multiplied together -Dlong multiplicationE. resulting in a number which ma% be as long as the sum o+ the lengths o+ the two operands5 6or e!ample7
xxx.xxx * yy.yyyyy

becomes7
zzzzz.zzzzzzzz

and the result is then rounded to digits digits i+ necessar%2 counting +rom the +irst signi+icant digit o+ the result5 #ivision 6or the division7
yyy / xxxxx

the +ollowing steps are taken7 +irst2 the number DyyyE is e!tended with =eros on the right until it is larger than the number DxxxxxE -with note being taken o+ the change in the power o+ ten that this implies.5 &hus in this e!ample2 DyyyE might become Dyyy00E5 &raditional long division then takes place2 which can be written7
zzzz .-----xxxxx | yyy00

&he length o+ the result -DzzzzE. is such that the rightmost DzE will be at least as +ar right as the rightmost digit o+ the -e!tended. DyE number in the e!ample5 #uring the division2 the DyE number will be e!tended +urther as necessar%2 and the DzE number -which will not include an% leading =eros. ma% increase up to digits+1 digits2 at which point the division stops and the result is rounded5 6ollowing completion o+ the
A@ In the e!ample2 the number yy.yyyyy would have three digits truncated i+ digits were 55 Version 2.00 NetRexx Language Definition 143

division -and rounding i+ necessar%.2 insigni+icant trailing =eros are removed5 %xample,.
/* With 'numeric digits 5' */ 12+7.00 == 19.00 1.3-1.07 == 0.23 1.3-2.07 == -0.77 1.20*3 == 3.60 7*3 == 21 0.9*0.8 == 0.72 1/3 == 0.33333 2/3 == 0.66667 5/2 == 2.5 1/10 == 0.1 12/12 == 1 8.0/2 == 4

Note. *ith all the basic operators2 the position o+ the decimal point in the terms being operated upon is arbitrar%5 &he operations ma% be carried out as integer operations with the e!ponent being calculated and applied a+terwards5 &here+ore the signi+icant digits o+ a result are not in an% wa% dependent on the position o+ the decimal point in either o+ the terms involved in the operation5

Arithmetic operation rules additional operators

&he operation rules +or the power -D**E.2 integer division -D%E.2 and remainder -D//E. operators are as +ollows7 $o%er &he D**E -power. operator raises a number -on the le+t o+ the operator. to a power -on the right o+ the operator.5 &he term on the right is rounded to digits digits -i+ necessar%.2 and must2 a+ter an% rounding2 be a whole number2 which ma% be positive2 negative2 or =ero5 I+ negative2 the absolute value o+ the power is used2 and then the result is inverted -divided into :.5 6or calculating the power2 the number is e++ectivel% multiplied b% itsel+ +or the number o+ times e!pressed b% the power2 and +inall% trailing =eros are removed -as though the result were divided b% one.5 In practice -see note below +or the reasons.2 the power is calculated b% the process o+ le+t1to1right binar% reduction5 6or Dx**nE7 DnE is converted to binar%2 and a temporar% accumulator is set to :5 I+ DnE has the value > then the initial calculation is complete5 /therwise each bit -starting at the +irst non1=ero bit. is inspected +rom le+t to right5 I+ the current bit is : then the accumulator is multiplied b% DxE5 I+ all bits have now been inspected then the initial calculation is complete2 otherwise the accumulator is s8uared b% multiplication and the ne!t bit is inspected5 *hen the initial calculation is complete2 the temporar% result is divided into : i+ the power was negative5 &he multiplications and division are done under the normal arithmetic operation rules2 detailed earlier in this section2 using a precision o+ digits+elength+1 digits5 ,ere2 elength is the length in decimal digits o+ the integer part o+ the whole number DnE -i.e.2 e!cluding an% sign2 decimal part2 decimal point2 or insigni+icant leading =eros2 as though the operation n%1 had been carried out and an% sign removed.5 6inall%2 the result is rounded to digits digits2 i+ necessar%2 and insigni+icant trailing =eros are removed5

144

NetRexx Language Definition

Version 2.00

&nteger division

&he D%E -integer divide. operator divides two numbers and returns the integer part o+ the result5 &he result returned is de+ined to be that which would result +rom repeatedl% subtracting the divisor +rom the dividend while the dividend is larger than the divisor5 #uring this subtraction2 the absolute values o+ both the dividend and the divisor are used7 the sign o+ the +inal result is the same as that which would result i+ normal division were used5 &he result returned will have no +ractional part -that is2 no decimal point or =eros +ollowing it.5 I+ the result cannot be e!pressed e!actl% within digits digits2 the operation is in error and will +ail 9 that is2 the result cannot have more digits than the current setting o+ numeric digits5 6or e!ample2 10000000000%3 re8uires ten digits to e!press the result e!actl% -3333333333. and would there+ore +ail i+ digits were 9 or smaller5

'emainder

&he D//E -remainder. operator will return the remainder +rom integer division2 and is de+ined as being the residue o+ the dividend a+ter the operation o+ calculating integer division as just described5 &he sign o+ the remainder2 i+ non1=ero2 is the same as that o+ the original dividend5 &his operation will +ail under the same conditions as integer division -that is2 i+ integer division on the same two terms would +ail2 the remainder cannot be calculated.5

%xample,.
/* Again with 'numeric digits 5' */ 2**3 == 8 2**-3 == 0.125 1.7**8 == 69.758 2%3 == 0 2.1//3 == 2.1 10%3 == 3 10//3 == 1 -10//3 == -1 10.2//1 == 0.2 10//0.3 == 0.1 3.6//1.3 == 1.0

Note,. :5 A particular algorithm +or calculating powers is described2 since it is e++icient -though not optimal. and considerabl% reduces the number o+ actual multiplications per+ormed5 It there+ore gives better per+ormance than the simpler de+inition o+ repeated multiplication5 (ince results could possibl% di++er +rom those o+ repeated multiplication2 the algorithm must be de+ined here so that di++erent implementations will give identical results +or the same operation on the same values5 /ther algorithms +or this -and other. operations ma% alwa%s be used2 so long as the% give identical results to those described here5 ;5 &he integer divide and remainder operators are de+ined so that the% ma% be calculated as a b%1 product o+ the standard division operation -described above.5 &he division process is ended as soon as the integer result is availableF the residue o+ the dividend is the remainder5

Version 2.00

NetRexx Language Definition

145

Numeric comparisons
An% o+ the comparative operators -see page A;. ma% be used +or comparing numeric strings5 ,owever2 the strict comparisons -+or e!ample2 D==E and D>>E. are not numeric comparative operators and should not normall% be used +or comparing numbers2 since the% compare +rom le+t to right and leading and trailing blanks -and leading =eros. are signi+icant +or these operators5 Numeric comparison2 using the normal comparative operators2 is e++ected b% subtracting the two numbers -calculating the di++erence. and then comparing the result with '0' 9 that is2 the operation7
A ? B

where D?E is an% normal comparative operator2 is identical to7

(A - B) ? '0'

It is there+ore the di##eren$e between two numbers2 when subtracted under Net e!! subtraction rules2 that determines their e8ualit%5

Exponential notation
&he de+inition o+ numbers above -see page :G:. describes DpureE numbers2 in the sense that the character strings that describe numbers can be ver% long5 %xample,.
say 10000000000 * 10000000000 /* would display: 100000000000000000000 */ say 0.00000000001 * 0.00000000001 /* would display: 0.0000000000000000000001 */

6or both large and small numbers some +orm o+ e!ponential notation is use+ul2 both to make such long numbers more readable and to make evaluation possible in e!treme cases5 In addition2 e!ponential notation is used whenever the DpureE +orm would give misleading in+ormation5 6or e!ample7
numeric digits 5 say 54321*54321

would displa% D2950800000E i+ long +orm were to be used5 &his is misleading2 as it appears that the result is an e!act multiple o+ :>>>>>2 and so Net e!! would e!press the result in e!ponential notation2 in this case D2.9508E+9E5 &he de+inition o+ n*)&er -see above. is there+ore e!tended b% replacing the description o+ numeric b% the +ollowing7
mantissa ::= numeric ::= digits . [digits] | [.] digits mantissa [E sign digits]

In other words2 the numeric part o+ a number ma% be +ollowed b% an DEE -indicating an e!ponential part.2 a sign2 and an integer +ollowing the sign that represents a power o+ ten that is to be applied5 &he DEE ma% be in uppercase or lowercase5 Note that no blanks are permitted within this part o+ a number2 but the integer ma% have leading =eros5 %xample,.
12E+11 12E-5 12e+4 = = = 1200000000000 0.00012 120000

146

NetRexx Language Definition

Version 2.00

All valid numbers ma% be used as data +or arithmetic5 &he results o+ calculations will be returned in e!ponential +orm depending on the setting o+ numeric digits5 I+ the number o+ places needed be+ore the decimal point e!ceeds digits2 or i+ the absolute value o+ the result is less than 0.0000012 then e!ponential +orm will be used5 &he e!ponential +orm generated b% Net e!! alwa%s has a sign +ollowing the DEE5 I+ the e!ponent is > then the e!ponential part is omitted 9 that is2 an e!ponential part o+ DE+0E will never be generated5 I+ the de+ault +ormat +or a number is not satis+actor% +or a particular application2 then the format method ma% be used to control its +ormat5 Using this2 numbers ma% be e!plicitl% converted to e!ponential +orm or even +orced to be returned in DpureE +orm5 #i++erent e!ponential notations ma% be selected with the numeric form instruction -see page :>G.5 &his instruction allows the selection o+ either scienti+ic or engineering notation5 .$ienti#i$ notation adjusts the power o+ ten so there is a single non1=ero digit to the le+t o+ the decimal point5 'ngineering notation causes powers o+ ten to be e!pressed as a multiple o+ three 9 the integer part ma% there+ore range +rom 1 through 9995 %xample,.
numeric form scientific say 123.45 * 1e11 /* would display: 1.2345E+13 */ numeric form engineering say 123.45 * 1e11 /* would display: 12.345E+12 */

&he de+ault e!ponential notation is scienti+ic5

Whole numbers
*ithin the set o+ numbers understood b% Net e!! it is use+ul to distinguish the subset de+ined as whole n*)&ers5 A whole n*)&er in Net e!! is a number that has a decimal part which is all =eros -or that has no decimal part.5

Numbers used directly by NetRexx

As discussed above2 the result o+ an% arithmetic operation is rounded -i+ necessar%. according to the setting o+ numeric digits5 (imilarl%2 when a number -which has not necessaril% been involved in an arithmetic operation. is used directl% b% Net e!! then the same rounding is also applied2 just as though the operation o+ adding the number to 0 had been carried out5 A+ter this operation2 the integer part o+ the number must have no more digits than the current setting o+ numeric digits5 In the +ollowing cases2 the number used must be a whole number and an implementation restriction on the largest number that can be used ma% appl%7 positional patterns2 including variable positional patterns2 in parsing templates -see page :<<. the power value -right hand operand. o+ the power operator -see page :GG. the values o+ e%prr and e%pr# -+ollowing the for ke%word. in the loop instruction -see page C:. the value o+ e%prd -+ollowing the digits ke%word. in the numeric instruction -see page :>G.5 Implementation minimum. A minimum length o+ C digits must be supported +or these uses o+ whole
Version 2.00 NetRexx Language Definition 147

numbers b% a Net e!! language processor5

Implementation independence
&he Net e!! arithmetic rules are de+ined in detail2 so that when a given program is run the results o+ all computations are su++icientl% de+ined that the same answer will result +or all correct implementations5 #i++erences due to the underl%ing machine architecture will not a++ect computations5 &his contrasts with most other programming languages2 and with binar% arithmetic -see page :GC. in Net e!!2 where the result obtained ma% depend on the implementation because the precision and algorithms used b% the language processor are de+ined b% the implementation rather than b% the language5

Exceptions and errors

&he +ollowing e!ceptions and errors ma% be signalled during arithmetic7 #ivide e!ception &his e!ception will be signalled i+ division b% =ero was attempted2 or i+ the integer result o+ an integer divide or remainder operation had too man% digits5 /ver+lowMUnder+low e!ception &his e!ception will be signalled i+ the e!ponential part o+ a result -+rom an operation that is not an attempt to divide b% =ero. would e!ceed the range that can be handled b% the language processor2 when the result is +ormatted according to the current settings o+ numeric digits and numeric form5 &he language de+ines a minimum capabilit% +or the e!ponential part2 namel% e!ponents whose absolute value is at least as large as the largest number that can be e!pressed as an e!act integer in de+ault precision5 &hus2 since the de+ault precision is nine2 implementations must support e!ponents in the range -999999999 through 9999999995 Insu++icient storage (torage is needed +or calculations and intermediate results2 and on occasion an arithmetic operation ma% +ail due to lack o+ storage5 &his is considered an operating environment error as usual2 rather than an arithmetical e!ception5 In the re#eren$e i)ple)entation, the e%$eptions and error types *sed #or these three $ases are DivideException, ExponentOverflowException, and OutOfMemoryError, respe$ti"ely.

148

NetRexx Language Definition

Version 2.00

Binary values and operations

B% de+ault2 arithmetic and string operations in Net e!! are carried out using the Net e!! string class2 Rexx2 which o++ers the robust set o+ operators described in '%pressions and operators -see page A:.5 Net e!! implementations2 however2 ma% also provide pri)iti"e datat%pes2 as described in 1ypes and Classes -see page GA.5 &hese primitive t%pes are used +or compact storage o+ numbers and +or +ast binar% arithmetic2 +eatures which are built1in to the hardware o+ most computers5 &o make use o+ binar% arithmetic2 a class is declared to be a &inary $lass -see page @>. b% using the binary ke%word on the class instruction5 In such a class2 literal strings and numeric s%mbols are assigned native string or primitive t%pes2 rather than Net e!! t%pes2 where appropriate2 and native binar% operations are used to implement operators where possible2 as detailed below5 Implementations ma% also provide a ke%word on the options -see page :>A. instruction that indicates that all classes in a program are binar% classes5AC Alternativel%2 individual methods within a class ma% be declared to be a &inary )ethod -see page :>:. b% using the binary ke%word on the method instruction5 Binar% classes and methods should be used with care5 Although binar% arithmetic can have a considerable per+ormance advantage over arithmetic that is not implemented in hardware2 it can give incorrect or une!pected results5 In particular2 whole numbers -integers. are o+ten held in +i!ed1si=ed data areas -o+ @2 :A2 <;2 or AG bits.2 and over+lowing the data area during a calculation can result in a positive number becoming negative and vice versa5 (imilarl%2 binar% numbers that are not whole numbers -+loating1point numbers. cannot e!actl% represent common numbers in the decimal s%stem -0.12 0.22 et$..2 and hence can give une!pected results5

Operations in binary classes and methods

In a binar% class or method2 the +ollowing -and onl% the +ollowing. rules di++er +rom the usual rules7 4yadi$ operations in e%pressions I+ the operands o+ a d%adic operator both have primitive numeric t%pes?> then binar% operations are carried out5 &he t%pe o+ the result is implementation de+ined2 and is t%picall% the t%pe o+ the more precise o+ the two operands2 or o+ some minimum precision5?: Arithmetic operations +ollow the usual rules o+ binar% arithmetic2 as de+ined +or the underl%ing environment o+ the implementation5 Note that Net e!! provides both divide and integer divide operatorsF in a binar% class or method2 the divide operator -D/E. converts its operands to +loating1point t%pes and returns a +loating1point result2 whereas the integer divide operator -D%E. converts its operands to integer t%pes and returns an integer result5 &he remainder operator must accept both integer and +loating1point t%pes5 Logical operations -and2 or2 and e%$l*si"e or. appl% to all the bits o+ the operands2 and are not permitted on +loating1point t%pes5 Pre#i% operations in I+ the operand o+ a pre+i! operator has a primitive numeric t%pe2 then the t%pe o+ the result is the t%pe o+ the operand2 subject to the same minimum as d%adic operations5

AC In the re#eren$e i)ple)entation, options binary is *sed5 ?> In the re#eren$e i)ple)entation, boolean is $onsidered to &e a n*)eri$ type :ha"ing the "al*es 0 or 1> &*t char is not. Chara$ters, and strings or arrays o# $hara$ters, always *se the r*les de#ined #or 3et/e%% strings. ?: In the re#eren$e i)ple)entation, the )ini)*) pre$ision is ,2 &its, so an int is ret*rned #or res*lts that wo*ld otherwise &e byte or short. I# &oth operands are boolean, howe"er, and the operation is a logi$al operation, then the type o# the res*lt is boolean. Version 2.00 NetRexx Language Definition 149

e%pressions

$re+i! plus and minus +ollow the rules o+ d%adic operators -because the% are de+ined as being =ero plus or minus the operand. with the additional rule that i+ acting on a literal number -a constant in the program. then the result is also considered to be a literal constant5 Logical not -pre+i! D\E. does not appl% to all the bits o+ its operandF instead2 it changes a 0 to 1 and vice versa5 In assignments where the value being assigned is the result o+ an e!pression which comprises a string or number literal constant2 the t%pe o+ the result is de+ined as +ollows7 :5 (trings are given the native string t%pe2 even +or a single1character literal5?; ;5 Numbers are given the smallest possible primitive numeric t%pe that will contain the literal without loss o+ in+ormation -or minimal loss o+ in+ormation +or numbers with decimal or e!ponential parts.5 I+ this is smaller than the implementation1de+ined minimum precision used +or the result o+ adding the literal to 02 then the t%pe o+ that minimum precision is used5 I+ the constant is an integer2 and no primitive integer binar% t%pe has su++icient precision to hold the number without loss o+ in+ormation2 then the number is treated as a literal string -that is2 as though it were enclosed in 8uotes.5 Net e!! arithmetic would then be used i+ it were involved in an arithmetic operation5 &hese rules can appl% in assignment instructions2 the initial assignment to the control variable in the loop instruction2 or the assignment o+ a de+ault value to the argument o+ a methodF the result t%pe ma% de+ine the t%pe o+ the variable -i+ new2 or a method argument.5

!ssign)ents

Control "aria&les in loops

In the loop instruction2 i+ the control variable has a primitive integer t%pe2 and the increment -by value. has a primitive integer t%pe2 then binar% arithmetic will be used +or stepping the control variable2 +ollowing the rules +or binar% arithmetic in e!pressions described above5 (imilarl%2 i+ the control variable has a primitive integer t%pe2 and the end -to. value has a primitive integer t%pe2 then binar% arithmetic will be used +or the comparison that tests +or loop termination5

3*)eri$ instr*$tion

&he numeric instruction does not a++ect binar% operations5 It has the usual e++ects on operations carried out using Net e!! arithmetic5

Note. At all times -whether in binar% classes2 binar% methods2 or an%where else. implementations ma% use primitive t%pes and operations2 and techni8ues such as late binding o+ t%pes2 as an optimi=ation providing that the results obtained are identical to those de+ined in this language de+inition5

Binary constructors
Net e!! provides special constructors +or implementation1de+ined primitive t%pes that allow bit1wise construction o+ primitives5 &hese &inary $onstr*$tors are especiall% use+ul +or manipulating the binar% encodings o+ individual characters5 &he binar% constructors +ollow the same s%nta! as other constructors2 with the name being that o+ a primitive t%pe5 All binar% constructors take one argument2 which must have a primitive t%pe5
?; In the re#eren$e i)ple)entation, this type is java.lang.String5 150 NetRexx Language Definition Version 2.00

&he bits o+ the value o+ the argument are e!tended or truncated on the le+t to the same length as the bits re8uired +or the t%pe o+ the constructor -+ollowing the usual binar% rules o+ sign e!tension i+ the argument t%pe is a signed numeric t%pe.2 and a value with the t%pe o+ the constructor is then constructed directl% +rom those bits and returned5 %xample. &his e!ample illustrates t%pes +rom the re+erence implementation2 with <;1bit signed integers o+ t%pe int and :A1bit Unicode characters o+ t%pe char5
i=int 77 c=char(i) j=int(c) -- i is now the integer 77 -- c is now the character 'M' -- j is now the integer 77

Note that the conversion

j=int c

would have +ailed2 as DME is not a number5

Version 2.00

NetRexx Language Definition

151

Exceptions
"!ceptional conditions2 including errors2 in Net e!! are handled b% a mechanism called '%$eptions5 *hen an e!ceptional condition occurs2 a signal takes place which ma% optionall% be $a*ght b% an enclosing control construct2 as detailed below5 An e!ception can be signalled b%7 :5 the program's environment2 when some processing error occurs -such as running out o+ memor%2 or a problem discovered when reading or writing a +ile. ;5 a method called b% a Net e!! program -i+2 +or e!ample2 it is passed incorrect arguments. <5 the signal instruction -see page ::C.5 In all cases2 the signal is handled in e!actl% the same wa%5 6irst2 e!ecution o+ the current clause ceasesF no +urther operations within the clause will be carried out5?< Ne!t2 an object that represents the e!ception is constructed5 &he t%pe o+ the e!ception object is implementation1dependent2 as described +or the signal instruction -see page ::C.2 and de+ines the t%pe o+ the e!ception5 &he object constructed usuall% contains in+ormation about the "!ception -such as a descriptive string.5 /nce the object has been constructed2 all active do groups2 loop loops2 if constructs2 and select constructs in the active method are DunwoundE2 starting with the innermost2 until the e!ception is caught b% a control construct that speci+ies a suitable catch clause -see below. +or handling the e!ception5 &his unwinding takes place as +ollows7 :5 No +urther clauses within the bod% o+ the construct will be e!ecuted -in this respect2 the signal acts like a leave +or the construct.5 ;5 I+ a catch clause speci+ies a t%pe to which the e!ception object can be assigned -that is2 it matches or is a superclass o+ the t%pe o+ e!ception object.2 then the instr*$tionlist +ollowing that clause is e!ecuted2 and the e!ception is considered to be handled -no +urther control constructs will be unwound.5 I+ more than one catch clause speci+ies a suitable t%pe2 the +irst is used5 <5 &he instr*$tionlist +ollowing the finally clause +or the construct2 i+ an%2 is e!ecuted5 G5 &he end clause is e!ecuted2 hence completing e!ecution o+ the construct5 -&he onl% e++ect o+ this is that it is seen when tracing5. B5 I+ the e!ception was handled2 then e!ecution resumes as though the construct completed normall%5 I+ it was not handled2 then the process is repeated +or an% enclosing constructs5 I+ the e!ception is not caught b% an% o+ the control constructs enclosing the original point o+ the e!ception signal2 then the current active method is terminated2 without returning an% data2 and the e!ception is then signalled at the point where the method was invoked -that is2 in the caller.5 &he process o+ unwinding control constructs and terminating the method is then repeated in each calling method until the e!ception is caught or the initial program invocation method -the main method. is terminated2 in which case the program ends and the environment receives the signal -it would usuall% then displa% diagnostic in+ormation.5

?< &his is the onl% case in which an e!pression will not be wholl% evaluated2 +or e!ample5 152 NetRexx Language Definition Version 2.00

Syntax and example

&he constructs that ma% be used to handle -catch. an e!ception are do groups2 loop loops2 and select constructs5 (peci+icall%2 as shown in the s%nta! diagrams -9."..2 where the end clause can appear in these constructs2 =ero or more catch clauses can be used to de+ine e!ception handlers2 +ollowed b% =ero or one finally clauses that describe Dclean1upE code +or the construct5 &he whole construct continues to be ended b% an end clause5 &he s%nta! o+ a catch clause is shown in the s%nta! diagrams5 It alwa%s speci+ies an e%$eption t%pe2 which ma% be 8uali+ied5 It ma% optionall% speci+% a s%mbol2 "are2 which is +ollowed b% an e8uals sign5 &his indicates that when the e!ception is caught then the object representing the e!ception will be assigned to the variable "are5 I+ new2 the t%pe o+ the variable will be e%$eption5 ,ere is an e!ample o+ a program that handles some o+ the e!ceptions signalled b% methods in the Rexx classF the trace results instruction is included to show the +low o+ e!ecution7
trace results do -- could be LOOP i=1 to 10, etc. say 1/arg catch DivideException say 'Divide exception' catch ex=NumberFormatException /* 'ex' is assigned the exception object */ say 'Bad number for division:' ex.getMessage finally say 'Done!' end

In this e!ample2 i+ the argument passed to the program -and hence placed in arg. is a valid number2 then its inverse is displa%ed5 I+ the argument is >2 then DDivide exceptionE would be displa%ed5 I+ the argument were an invalid number2 the message describing the bad number would be displa%ed5 6or an% other e!ception -such as an ExponentOverflowException.2 the program would end and the environment would normall% report the e!ception5 In all cases2 the message DDone!E would be displa%edF this would be true even i+ the bod% o+ the do construct e!ecuted a return2 leave2 or iterate instruction5 /nl% an exit instruction -see page @G. would cause immediate termination o+ the construct -and the program.5 Note. &he finally ke%word2 like otherwise in the select construct2 implies a semicolon a+ter it2 so the last say instruction in the e!ample could have appeared on the same line as the finally without an intervening semicolon5

Exceptions after catch and finally clauses

I+ an e!ception is signalled in the instr*$tionlist +ollowing a catch or finally clause2 then the current e!ception is considered handled2 the instr*$tionlist is terminated2 and the new e!ception is signalled5 It will not be caught b% catch clauses in the current construct5 I+ it occurs in the instr*$tionlist +ollowing a catch clause2 then an% finally instructions will be e!ecuted2 as usual5 (imilarl%2 e!ecuting a return or exit instruction within either o+ the instr*$tionlists completes the handling o+ an% pending signal5

Checked exceptions
Net e!! implementations ma% de+ine certain e!ceptions as $he$ked e%$eptions5 &hese are e!ceptions that the implementation considers it use+ul to checkF the checked e!ceptions that each method ma%
Version 2.00 NetRexx Language Definition 153

signal are recorded5 *ithin do groups2 loop loops2 and select constructs2 +or e!ample2 it is then possible to report i+ a catch clause tries to catch a checked e!ception that is not signalled within the bod% o+ the construct5 Checked e!ceptions that are signalled within a method -b% a signal instruction or a method invocation. but not caught b% a catch clause in the method are automaticall% added to the signals list +or a method5 Implementations that support checked e!ceptions are encouraged to provide options that list the uncaught checked e!ceptions +or methods or en+orce the e!plicit inclusion o+ some or all checked e!ceptions in the signals list on the method instruction5 In the re#eren$e i)ple)entation, all e%$eptions are $he$ked e%$ept those that are s*&$lasses o# java.lang.RuntimeException or java.lang.Error. 1hese latter are $onsidered so *&i9*ito*s that al)ost all )ethods wo*ld signal the). '%pressions assigned as the initial "al*es o# properties )*st not in"oke )ethods that )ay signal $he$ked e%$eptions. 1he strictsignal option on the options instr*$tion )ay &e *sed to en#or$e the in$l*sion o# all *n$a*ght $he$ked e%$eptions in )ethodsI signals listsB this )ay &e *sed to ass*re that any *n$a*ght $he$ked e%$eptions are intentional.

154

NetRexx Language Definition

Version 2.00

Methods for NetRexx strings

&his section describes the set o+ methods de+ined +or the Net e!! string class2 Rexx5 &hese are called &*ilt;in )ethods2 and include character manipulation2 word manipulation2 conversion2 and arithmetic methods5 Implementations will also provide other methods +or the Rexx class -+or e!ample2 to implement the Net e!! operators or to provide constructors with primitive arguments.2 but these are not part o+ the Net e!! language5?G

General notes on the built-in methods:

:5 All methods work on a Net e!! string o+ t%pe RexxF this is re+erred to b% the name string in the descriptions o+ the methods5 6or e!ample2 i+ the word method were invoked using the term7
"Three word phrase".word(2)

then in the description o+ word the name string re+ers to the string DThree word phraseE2 and the name n re+ers to the string D2E5 ;5 All method arguments are o+ t%pe Rexx and all methods return a string o+ t%pe RexxF i+ a number is returned2 it will be +ormatted as though > had been added with no rounding5 <5 &he +irst parenthesis in a method call must immediatel% +ollow the name o+ the method2 with no space in between5 G5 &he parentheses in a method call can be omitted i+ no arguments are re8uired and the method call is part o+ a $o)po*nd ter) -see page G@.5?B B5 A position in a string is the number o+ a character in the string2 where the +irst character is at position :2 et$. A5 *here arguments are optional2 commas ma% onl% be included between arguments that are present -that is2 trailing commas in argument lists are not permitted.5 ?5 A pad argument2 i+ speci+ied2 must be e!actl% one character long5 @5 I+ a method has a sub1option selected b% the +irst character o+ a string2 that character ma% be in upper or lowercase5 C5 Conversion between character encodings and decimal or he!adecimal is dependent on the machine representation -encoding. o+ characters and hence will return appropriatel% di++erent results +or Unicode2 A(CII2 "BC#IC2 and other implementations5

?G 4etails o# the )ethods pro"ided in the re#eren$e i)ple)entation are in$l*ded in !ppendi% C :see page 179>. ?B Unless an implementation1provided option to disallow parenthesis omission is in +orce5 Version 2.00 NetRexx Language Definition 155

The built-in methods

abbrev(info [,length])

returns : i+ in#o is e8ual to the leading characters o+ string and in#o is not less than the minimum length2 lengthF > is returned i+ either o+ these conditions is not met5 length must be a non1negative whole numberF the de+ault is the length o+ in#o5 %xample,.
'Print'.abbrev('Pri') 'PRINT'.abbrev('Pri') 'PRINT'.abbrev('PRI',4) 'PRINT'.abbrev('PRY') 'PRINT'.abbrev('') 'PRINT'.abbrev('',1) == == == == == == 1 0 0 0 1 0

Note. A null string will alwa%s match i+ a length o+ > -or the de+ault. is used5 &his allows a de+ault ke%word to be selected automaticall% i+ desired5 %xample.
say 'Enter option:'; option=ask select /* keyword1 is to be the default */ when 'keyword1'.abbrev(option) then ... when 'keyword2'.abbrev(option) then ... ... otherwise ... end abs()

returns the absolute value o+ string2 which must be a number5 An% sign is removed +rom the number2 and it is then +ormatted b% adding =ero with a digits setting that is either nine or2 i+ greater2 the number o+ digits in the mantissa o+ the number -e!cluding leading insigni+icant =eros.5 (cienti+ic notation is used2 i+ necessar%5 %xample,.
'12.3'.abs ' -0.307'.abs '123.45E+16'.abs '- 1234567.7654321'.abs == == == == 12.3 0.307 1.2345E+18 1234567.7654321

b2x()

Binar% to he!adecimal5 Converts string2 a string o+ at least one binar% -0 andMor 1. digits2 to an e8uivalent string o+ he!adecimal characters5 &he returned string will use uppercase oman letters +or the values A162 and will not include an% blanks5 I+ the number o+ binar% digits in the string is not a multiple o+ +our2 then up to three '0' digits will be added on the le+t be+ore conversion to make a total that is a multiple o+ +our5 %xample,.
'11000011'.b2x '10111'.b2x '0101'.b2x '101'.b2x '111110000'.b2x == == == == == 'C3' '17' '5' '5' '1F0'

156

NetRexx Language Definition

Version 2.00

center(length [,pad]) centre(length [,pad])

or returns a string o+ length length with string centered in it2 with pad characters added as necessar% to make up the re8uired length5 length must be a non1negative whole number5 &he de+ault pad character is blank5 I+ the string is longer than length2 it will be truncated at both ends to +it5 I+ an odd number o+ characters are truncated or added2 the right hand end loses or gains one more character than the le+t hand end5 %xample,.
'ABC'.centre(7) 'ABC'.center(8,'-') 'The blue sky'.centre(8) 'The blue sky'.center(7) == == == == ' ABC ' '--ABC---' 'e blue s' 'e blue '

Note. &his method ma% be called either centre or center2 which avoids di++iculties due to the di++erence between the British and American spellings5
changestr(needle, returns a cop% o+ string in which each occurrence o+ the needle string is replaced new) b% the new string5 "ach uni8ue -non1overlapping. occurrence o+ the needle string

is changed2 searching +rom le+t to right and starting +rom the +irst -le+tmost. position in string5 /nl% the original string is searched +or the needle2 and each character in string can onl% be included in one match o+ the needle5 I+ the needle is the null string2 the result is a cop% o+ string2 unchanged5 %xample,.
'elephant'.changestr('e','X') 'elephant'.changestr('ph','X') 'elephant'.changestr('ph','hph') 'elephant'.changestr('e','') 'elephant'.changestr('','!!') == == == == == 'XlXphant' 'eleXant' 'elehphant' 'lphant' 'elephant'

&he countstr method -see page :B@. can be used to count the number o+ changes that could be made to a string in this +ashion5
compare(target [,pad])

returns > i+ string and target are the same5 I+ the% are not2 the returned number is positive and is the position o+ the +irst character that is not the same in both strings5 I+ one string is shorter than the other2 one or more pad characters are added on the right to make it the same length +or the comparison5 &he de+ault pad character is a blank5 %xample,.
'abc'.compare('abc') 'abc'.compare('ak') 'ab '.compare('ab') 'ab '.compare('ab',' ') 'ab '.compare('ab','x') 'ab-- '.compare('ab','-') == == == == == == 0 2 0 0 3 5

copies(n)

returns n directl% concatenated copies o+ string5 n must be positive or >F i+ >2 the null string is returned5 %xample,.
'abc'.copies(3) == 'abcabcabc' 'abc'.copies(0) == ''

Version 2.00

NetRexx Language Definition

157

''.copies(2)

== ''

copyindexed(sub) copies the collection o+ inde!ed sub1values -see page ?<. o+ s*& into the

collection associated with string2 and returns the modi+ied string5 &he resulting collection is the union o+ the two collections -that is2 it contains the inde!es and their values +rom both collections.5 I+ a given inde! e!ists in both collections then the sub1value o+ string +or that inde! is replaced b% the sub1value +rom s*&5 &he non1inde!ed value o+ string is not a++ected5 %xample. 6ollowing the instructions7
foo='def' foo['a']=1 foo['b']=2 bar='ghi' bar['b']='B' bar['c']='C' merged=foo.copyIndexed(bar)

then7
merged['a'] merged['b'] merged['c'] merged['d'] countstr(needle) == == == == '1' 'B' 'C' 'def'

returns the count o+ non1overlapping occurrences o+ the needle string in string2 searching +rom le+t to right and starting +rom the +irst -le+tmost. position in string5 I+ the needle is the null string2 0 is returned5 %xample,.
'elephant'.countstr('e') == '2' 'elephant'.countstr('ph') == '1' 'elephant'.countstr('') == '0'

&he changestr method -see page :B?. can be used to change occurrences o+ needle to some other string5
c2d()

Coded character to decimal5 Converts the encoding o+ the character in string -which must be e!actl% one character. to its decimal representation5 &he returned string will be a non1negative number that represents the encoding o+ the character and will not include an% sign2 blanks2 insigni+icant leading =eros2 or decimal part5 %xample,.
'M'.c2d '7'.c2d '\r'.c2d '\0'.c2d == == == == '77' -- ASCII or Unicode '247' -- EBCDIC '13' -- ASCII or Unicode '0'

&he c2x method -see page :B@. can be used to convert the encoding o+ a character to a he!adecimal representation5
c2x()

Coded character to he!adecimal5 Converts the encoding o+ the character in string -which must be e!actl% one character. to its he!adecimal representation -unpacks.5 &he returned string will use uppercase oman letters +or the values A1
NetRexx Language Definition Version 2.00

158

62 and will not include an% blanks5 Insigni+icant leading =eros are removed5 %xample,.
'M'.c2x '7'.c2x '\r'.c2x '\0'.c2x == == == == '4D' -- ASCII or Unicode 'F7' -- EBCDIC 'D' -- ASCII or Unicode '0'

&he c2d method -see page :B@. can be used to convert the encoding o+ a character to a decimal number5
datatype(option)

returns : i+ string matches the description re8uested with the option2 or > otherwise5 I+ string is the null string2 > is alwa%s returned5 /nl% the +irst character o+ option is signi+icant2 and it ma% be in either uppercase or lowercase5 &he +ollowing option characters are recogni=ed7
A B D L M N S

-Alphanumeric.F returns : i+ string onl% contains characters +rom the ranges Da1=E2 DA1SE2 and D>1CE5 -Binar%.F returns : i+ string onl% contains the characters D>E andMor D:E5 -#igits.F returns : i+ string onl% contains characters +rom the range D>1CE5 -Lowercase.F returns : i+ string onl% contains characters +rom the range Da1 =E5 -Mi!ed case.F returns : i+ string onl% contains characters +rom the ranges Da1=E and DA1SE5 -Number.F returns : i+ string is a s%ntacticall% valid Net e!! number that could be added to '0' without error2 -(%mbol.F returns : i+ string onl% contains characters that are valid in non1 numeric s%mbols -the alphanumeric characters and underscore.2 and does not start with a digit5 Note that both uppercase and lowercase letters are permitted5 -Uppercase.F returns : i+ string onl% contains characters +rom the range DA1 SE5 -*hole Number.F returns : i+ string is a s%ntacticall% valid Net e!! number that can be added to '0' without error2 and whose decimal part a+ter that addition2 with no rounding2 is =ero5 -heIadecimal.F returns : i+ string onl% contains characters +rom the ranges Da1+E2 DA16E2 and D>1CE5
'101'.datatype('B') '12.3'.datatype('D') '12.3'.datatype('N') '12.3'.datatype('W') 'LaArca'.datatype('M') ''.datatype('M') 'Llanes'.datatype('L') '3 d'.datatype('s') 'BCd3'.datatype('X') 'BCgd3'.datatype('X') == == == == == == == == == == 1 0 1 0 1 0 0 1 1 0

U W

%xample,.

Version 2.00

NetRexx Language Definition

159

Note. &he datatype method tests the meaning o+ the characters in a string2 independent o+ the encoding o+ those characters5 "!tra letters and "!tra digits cause datatype to return > e!cept +or the number tests -DNE and DWE.2 which treat e!tra digits whose value is in the range >1C as though the% were the corresponding Arabic numeral5
delstr(n [,length]) returns a cop% o+ string with the sub1string o+ string that begins at the nth

character2 and is o+ length length characters2 deleted5 I+ length is not speci+ied2 or is greater than the number o+ characters +rom n to the end o+ the string2 the rest o+ the string is deleted -including the nth character.5 length must be a non1negative whole number2 and n must be a positive whole number5 I+ n is greater than the length o+ string2 the string is returned unchanged5 %xample,.
'abcd'.delstr(3) == 'ab' 'abcde'.delstr(3,2) == 'abe' 'abcde'.delstr(6) == 'abcde' delword(n [,length])

returns a cop% o+ string with the sub1string o+ string that starts at the nth word2 and is o+ length length blank1delimited words2 deleted5 I+ length is not speci+ied2 or is greater than number o+ remaining words in the string2 it de+aults to be the remaining words in the string -including the nth word.5 length must be a non1 negative whole number2 and n must be a positive whole number5 I+ n is greater than the number o+ words in string2 the string is returned unchanged5 &he string deleted includes an% blanks +ollowing the +inal word involved2 but none o+ the blanks preceding the +irst word involved5 %xample,.
'Now is the time'.delword(2,2) == 'Now time' 'Now is the time '.delword(3) == 'Now is ' 'Now time'.delword(5) == 'Now time'

d2c()

#ecimal to coded character5 Converts the string -a Net e!! n*)&er. to a single character2 where the number is used as the encoding o+ the character5 string must be a non1negative whole number5 An error results i+ the encoding described does not produce a valid character +or the implementation -+or e!ample2 i+ it has more signi+icant bits than the implementation's encoding +or characters.5 %xample,.
'77'.d2c '+77'.d2c '247'.d2c '0'.d2c == == == == 'M' -- ASCII or Unicode 'M' -- ASCII or Unicode '7' -- EBCDIC '\0'

d2x([n])

#ecimal to he!adecimal5 eturns a string o+ he!adecimal characters o+ length as needed or o+ length n2 which is the he!adecimal -unpacked. representation o+ the decimal number5 &he returned string will use uppercase oman letters +or the values A162 and will not include an% blanks5 string must be a whole number2 and must be non1negative unless n is speci+ied2 or an error will result5 I+ n is not speci+ied2 the length o+ the result returned is such that there are no leading > characters2 unless string was e8ual to > -in which

160

NetRexx Language Definition

Version 2.00

case '0' is returned.5 I+ n is speci+ied it is the length o+ the +inal result in charactersF that is2 a+ter conversion the input string will be sign1e!tended to the re8uired length -negative numbers are converted assuming twos1complement +orm.5 I+ the number is too big to +it into n characters2 it will be truncated on the le+t5 n must be a non1 negative whole number5 %xample,.
'9'.d2x '129'.d2x '129'.d2x(1) '129'.d2x(2) '127'.d2x(3) '129'.d2x(4) '257'.d2x(2) '-127'.d2x(2) '-127'.d2x(4) '12'.d2x(0) exists(index) == == == == == == == == == == '9' '81' '1' '81' '07F' '0081' '01' '81' 'FF81' ''

returns : i+ inde% names a sub1value -see page ?<. o+ string that has e!plicitl% been assigned a value2 or > otherwise5 %xample. 6ollowing the instructions7
vowel=0 vowel['a']=1 vowel['b']=1 vowel['b']=null -- drops previous assignment

then7
vowel.exists('a') == '1' vowel.exists('b') == '0' vowel.exists('c') == '0' format([before [,after]])

+ormats -la%s out. string2 which must be a number5 &he number2 string2 is +irst +ormatted b% adding =ero with a digits setting that is either nine or2 i+ greater2 the number o+ digits in the mantissa o+ the number -e!cluding leading insigni+icant =eros.5 I+ no arguments are given2 the result is precisel% that o+ this operation5 &he arguments &e#ore and a#ter ma% be speci+ied to control the number o+ characters to be used +or the integer part and decimal part o+ the result respectivel%5 I+ either o+ these is omitted -with no arguments speci+ied to its right.2 or is null2 the number o+ characters used will be as man% as are needed +or that part5 &e#ore must be a positive numberF i+ it is larger than is needed to contain the integer part2 that part is padded on the le+t with blanks to the re8uested length5 I+ &e#ore is not large enough to contain the integer part o+ the number -including the sign2 +or negative numbers.2 an error results5 a#ter must be a non1negative numberF i+ it is not the same si=e as the decimal part o+ the number2 the number will be rounded -or e!tended with =eros. to +it5 (peci+%ing > +or a#ter will cause the number to be rounded to an integer -that is2

Version 2.00

NetRexx Language Definition

161

it will have no decimal part or decimal point.5 %xample,.

' - 12.73'.format '0.000'.format '3'.format(4) '1.73'.format(4,0) '1.73'.format(4,3) '-.76'.format(4,1) '3.03'.format(4) ' - 12.73'.format(null,4) == == == == == == == == '-12.73' '0' ' 3' ' 2' ' 1.730' ' -0.8' ' 3.03' '-12.7300'

6urther arguments ma% be passed to the format method to control the use o+ e!ponential notation5 &he +ull s%nta! o+ the method is then7
format([before[,after[,explaces[,exdigits[,exform]]]]])

&he +irst two arguments are as alread% described5 &he other three -e%pla$es2 e%digits2 and e%#or). control the e!ponent part o+ the result5 &he de+ault +or an% o+ the arguments ma% be selected b% omitting them -i+ there are no arguments to be speci+ied to their right. or b% using the value null5 e%pla$es must be a positive numberF it sets the number o+ places -digits a+ter the sign o+ the e!ponent. to be used +or an% e!ponent part2 the de+ault being to use as man% as are needed5 I+ e%pla$es is speci+ied and is not large enough to contain the e!ponent2 an error results5 I+ e%pla$es is speci+ied and the e!ponent will be >2 then e%pla$esY; blanks are supplied +or the e!ponent part o+ the result5 e%digits sets the trigger point +or use o+ e!ponential notation5 I+2 a+ter the +irst +ormatting2 the number o+ places needed be+ore the decimal point e!ceeds e%digits2 or i+ the absolute value o+ the result is less than 0.0000012 then e!ponential +orm will be used2 provided that e%digits was speci+ied5 *hen e%digits is not speci+ied2 e!ponential notation will never be used5 &he current setting o+ numeric digits ma% be used +or e%digits b% speci+%ing the special word digits -see page :<>.5 I+ > is speci+ied +or e%digits2 e!ponential notation is alwa%s used unless the e!ponent would be >5 e%#or) sets the +orm +or e!ponential notation -i+ needed.5 e%#or) ma% be either 'Scientific' -the de+ault. or 'Engineering'5 /nl% the +irst character o+ e%#or) is signi+icant and it ma% be in uppercase or in lowercase5 &he current setting o+ numeric form ma% be used b% speci+%ing the special word form -see page :<>.5 I+ engineering +orm is in e++ect2 up to three digits -plus sign. ma% be needed +or the integer part o+ the result -&e#ore.5 %xample,.
'12345.73'.format(null,null,2,2) '12345.73'.format(null,3,null,0) '1.234573'.format(null,3,null,0) '123.45'.format(null,3,2,0) '1234.5'.format(null,3,2,0,'e') '1.2345'.format(null,3,2,0) '12345.73'.format(null,null,3,6) '12345e+5'.format(null,3) == == == == == == == == '1.234573E+04' '1.235E+4' '1.235' '1.235E+02' '1.235E+03' '1.235 ' '12345.73 ' '1234500000.000'

Implementation minimum. I+ e!ponents are supported in an implementation2 then the% must be supported +or e!ponents whose absolute value is at least as
162 NetRexx Language Definition Version 2.00

large as the largest number that can be e!pressed as an e!act integer in de+ault precision2 i.e.2 CCCCCCCCC5 &here+ore2 values +or e%pla$es o+ up to C should also be supported5
insert(new [,n [,length [,pad]]])

inserts the string new2 padded or truncated to length length2 into a cop% o+ the target string a+ter the nth characterF the string with an% inserts is returned5 length and n must be a non1negative whole numbers5 I+ n is greater than the length o+ the target string2 padding is added be+ore the new string also5 &he de+ault value +or n is >2 which means insert be+ore the beginning o+ the string5 &he de+ault value +or length is the length o+ new5 &he de+ault pad character is a blank5 %xample,.
'abc'.insert('123') 'abcdef'.insert(' ',3) 'abc'.insert('123',5,6) 'abc'.insert('123',5,6,'+') 'abc'.insert('123',0,5,'-') == == == == == '123abc' 'abc def' 'abc 123 ' 'abc++123+++' '123--abc'

lastpos(needle [,start])

returns the position o+ the last occurrence o+ the string needle in string -the Dha%stackE.2 searching +rom right to le+t5 I+ the string needle is not +ound2 or is the null string2 > is returned5 B% de+ault the search starts at the last character o+ string and scans backwards5 &his ma% be overridden b% speci+%ing start2 the point at which to start the backwards scan5 start must be a positive whole number2 and de+aults to the value string.length i+ larger than that value or i+ not speci+ied -with a minimum de+ault value o+ one.5 %xample,.
'abc def ghi'.lastpos(' ') 'abc def ghi'.lastpos(' ',7) 'abcdefghi'.lastpos(' ') 'abcdefghi'.lastpos('cd') ''.lastpos('?') == == == == == 8 4 0 3 0

left(length [,pad]) returns a string o+ length length containing the le+t1most length characters o+

string5 &he string is padded with pad characters -or truncated. on the right as needed5 &he de+ault pad character is a blank5 length must be a non1negative whole number5 &his method is e!actl% e8uivalent to string.substr(12 length O2 padP)5 %xample,.
'abc d'.left(8) == 'abc d ' 'abc d'.left(8,'.') == 'abc d...' 'abc defg'.left(6) == 'abc de' length()

returns the number o+ characters in string5 %xample,.

'abcdefgh'.length == 8 ''.length == 0

lower([n [,length]]) returns a cop% o+ string with an% uppercase characters in the sub1string o+ string

that begins at the nth character2 and is o+ length length characters2 replaced b% their lowercase e8uivalent5 n must be a positive whole number2 and de+aults to : -the +irst character in

Version 2.00

NetRexx Language Definition

163

string.5 I+ n is greater than the length o+ string2 the string is returned unchanged5 length must be a non1negative whole number5 I+ length is not speci+ied2 or is greater than the number o+ characters +rom n to the end o+ the string2 the rest o+ the string -including the nth character. is assumed5 %xample,.
'SumA'.lower 'SumA'.lower(2) 'SuMB'.lower(1,1) 'SUMB'.lower(2,2) ''.lower max(number) == == == == == 'suma' 'Suma' 'suMB' 'SumB' ''

returns the larger o+ string and n*)&er2 which must both be numbers5 I+ the% compare e8ual -that is2 when subtracted2 the result is >.2 then string is selected +or the result5 &he comparison is e++ected using a numerical comparison with a digits setting that is either nine or2 i+ greater2 the larger o+ the number o+ digits in the mantissas o+ the two numbers -e!cluding leading insigni+icant =eros.5 &he selected result is +ormatted b% adding =ero to the selected number with a digits setting that is either nine or2 i+ greater2 the number o+ digits in the mantissa o+ the number -e!cluding leading insigni+icant =eros.5 (cienti+ic notation is used2 i+ necessar%5 %xample,.
0.max(1) ==1 '-1'.max(1) ==1 '+1'.max(-1) ==1 '1.0'.max(1.00) =='1.0' '1.00'.max(1.0) =='1.00' '123456700000'.max(1234567E+5) == '123456700000' '1234567E+5'.max('123456700000') == '1.234567E+11'

min(number)

returns the smaller o+ string and n*)&er2 which must both be numbers5 I+ the% compare e8ual -that is2 when subtracted2 the result is >.2 then string is selected +or the result5 &he comparison is e++ected using a numerical comparison with a digits setting that is either nine or2 i+ greater2 the larger o+ the number o+ digits in the mantissas o+ the two numbers -e!cluding leading insigni+icant =eros.5 &he selected result is +ormatted b% adding =ero to the selected number with a digits setting that is either nine or2 i+ greater2 the number o+ digits in the mantissa o+ the number -e!cluding leading insigni+icant =eros.5 (cienti+ic notation is used2 i+ necessar%5 %xample,.
0.min(1) ==0 '-1'.min(1) =='-1' '+1'.min(-1) =='-1' '1.0'.min(1.00) =='1.0' '1.00'.min(1.0) =='1.00' '123456700000'.min(1234567E+5) == '123456700000' '1234567E+5'.min('123456700000') == '1.234567E+11'

overlay(new [,n
164

overla%s the string new2 padded or truncated to length length2 onto a cop% o+ the
NetRexx Language Definition Version 2.00

[,length [,pad]]])

target string starting at the nth characterF the string with an% overla%s is returned5 /verla%s ma% e!tend be%ond the end o+ the original string5 I+ length is speci+ied it must be a non1negative whole number5 I+ n is greater than the length o+ the target string2 padding is added be+ore the new string also5 &he de+ault pad character is a blank2 and the de+ault value +or n is :5 n must be greater than >5 &he de+ault value +or length is the length o+ new5 %xample,.
'abcdef'.overlay(' ',3) 'abcdef'.overlay('.',3,2) 'abcd'.overlay('qq') 'abcd'.overlay('qq',4) 'abc'.overlay('123',5,6,'+') == == == == == 'ab def' 'ab. ef' 'qqcd' 'abcqq' 'abc+123+++'

pos(needle [,start])

returns the position o+ the string needle2 in string -the Dha%stackE.2 searching +rom le+t to right5 I+ the string needle is not +ound2 or is the null string2 > is returned5 B% de+ault the search starts at the +irst character o+ string -that is2 start has the value :.5 &his ma% be overridden b% speci+%ing start -which must be a positive whole number.2 the point at which to start the searchF i+ start is greater than the length o+ string then > is returned5 %xample,.
'Saturday'.pos('day') 'abc def ghi'.pos('x') 'abc def ghi'.pos(' ') 'abc def ghi'.pos(' ',5) == == == == 6 0 4 8

reverse()

returns a cop% o+ string2 swapped end +or end5 %xample,.

'ABc.'.reverse == '.cBA' 'XYZ '.reverse == ' ZYX' 'Tranquility'.reverse == 'ytiliuqnarT'

right(length [,pad])

returns a string o+ length length containing the right1most length characters o+ string 9 that is2 padded with pad characters -or truncated. on the le+t as needed5 &he de+ault pad character is a blank5 length must be a non1negative whole number5 %xample,.
'abc d'.right(8) == ' abc d' 'abc def'.right(5) == 'c def' '12'.right(5,'0') == '00012'

sequence(final)

returns a string o+ all characters2 in ascending order o+ encoding2 between and including the character in string and the character in #inal5 string and #inal must be single charactersF i+ string is greater than #inal2 an error is reported5 %xample,.
'a'.sequence('f') == 'abcdef' '\0'.sequence('\x03') == '\x00\x01\x02\x03' '\ufffe'.sequence('\uffff') == '\ufffe\uffff'

sign()

returns a number that indicates the sign o+ string2 which must be a number5 string is +irst +ormatted2 just as though the operation Dstring+0E had been carried out with su++icient digits to avoid rounding5 I+ the number then starts with '-' then
NetRexx Language Definition 165

Version 2.00

'-1' is returnedF i+ it is '0' then '0' is returnedF and otherwise '1' is returned5

%xample,.
'12.3'.sign == 1 '0.0'.sign == 0 ' -0.307'.sign == -1 space([n [,pad]])

returns a cop% o+ string with the blank1delimited words in string +ormatted with n -and onl% n. pad characters between each word5 n must be a non1negative whole number5 I+ n is >2 all blanks are removed5 Leading and trailing blanks are alwa%s removed5 &he de+ault +or n is :2 and the de+ault pad character is a blank5 %xample,.
'abc def ' abc def 'abc def 'abc def 'abc def '.space '.space(3) '.space(1) '.space(0) '.space(2,'+') == == == == == 'abc def' 'abc def' 'abc def' 'abcdef' 'abc++def'

strip([option [,char]])

returns a cop% o+ string with Leading2 &railing2 or Both leading and trailing characters removed2 when the +irst character o+ option is L2 &2 or B respectivel% -these ma% be given in either uppercase or lowercase.5 &he de+ault is B5 &he second argument2 $har2 speci+ies the character to be removed2 with the de+ault being a blank5 I+ given2 $har must be e!actl% one character long5 %xample,.
' ab c '.strip ' ab c '.strip('L') ' ab c '.strip('t') '12.70000'.strip('t',0) '0012.700'.strip('b',0) == == == == == 'ab c' 'ab c ' ' ab c' '12.7' '12.7'

substr(n [,length [,pad]])

returns the sub1string o+ string that begins at the nth character2 and is o+ length length2 padded with pad characters i+ necessar%5 n must be a positive whole number2 and length must be a non1negative whole number5 I+ n is greater than string.length2 then onl% pad characters can be returned5 I+ length is omitted it de+aults to be the rest o+ the string -or > i+ n is greater than the length o+ the string.5 &he de+ault pad character is a blank5 %xample,.
'abc'.substr(2) 'abc'.substr(2,4) 'abc'.substr(5,4) 'abc'.substr(2,6,'.') 'abc'.substr(5,6,'.') == == == == == 'bc' 'bc ' ' ' 'bc....' '......'

Note. In some situations the positional -numeric. patterns o+ parsing templates are more convenient +or selecting sub1strings2 especiall% i+ more than one sub1 string is to be e!tracted +rom a string5
subword(n [,length])

returns the sub1string o+ string that starts at the nth word2 and is up to length blank1delimited words long5 n must be a positive whole numberF i+ greater than the number o+ words in the string then the null string is returned5 length must be a non1negative whole number5 I+ length is omitted it de+aults to be the remaining words in the string5 &he returned string will never have leading or trailing blanks2
NetRexx Language Definition Version 2.00

166

but will include all blanks between the selected words5 %xample,.
'Now is the 'Now is the 'Now is the translate(tableo, tablei [,pad]) time'.subword(2,2) == 'is the' time'.subword(3) == 'the time' time'.subword(5) == ''

returns a cop% o+ string with each character in string either unchanged or translated to another character5 &he translate method acts b% searching the input translate table2 ta&lei2 +or each character in string5 I+ the character is +ound in ta&lei -the +irst2 le+tmost2 occurrence being used i+ there are duplicates. then the corresponding character in the same position in the output translate table2 ta&leo2 is used in the result stringF otherwise the original character +ound in string is used5 &he result string is alwa%s the same length as string5 &he translate tables ma% be o+ an% length2 including the null string5 &he output table2 ta&leo2 is padded with pad or truncated on the right as necessar% to be the same length as ta&lei5 &he de+ault pad is a blank5 %xample,.
'abbc'.translate('&','b') 'abcdef'.translate('12','ec') 'abcdef'.translate('12','abcd','.') '4123'.translate('abcd','1234') '4123'.translate('hods','1234') == == == == == 'a&&c' 'ab2d1f' '12..ef' 'dabc' 'shod'

Note. &he last two e!amples show how the translate method ma% be used to move around the characters in a string5 In these e!amples2 an% G1character string could be speci+ied as the +irst argument and its last character would be moved to the beginning o+ the string5 (imilarl%2 the term7
'gh.ef.abcd'.translate(19970827,'abcdefgh')

-which returns D27.08.1997E. shows how a string -in this case perhaps a date. might be re1+ormatted and merged with other characters using the translate method5
trunc([n])

returns the integer part o+ string2 which must be a number2 with n decimal places -digits a+ter the decimal point.5 n must be a non1negative whole number2 and de+aults to =ero5 &he number string is +ormatted b% adding =ero with a digits setting that is either nine or2 i+ greater2 the number o+ digits in the mantissa o+ the number -e!cluding leading insigni+icant =eros.5 It is then truncated to n decimal places -or trailing =eros are added i+ needed to make up the speci+ied length.5 I+ n is > -the de+ault. then an integer with no decimal point is returned5 &he result will never be in e!ponential +orm5 %xample,.
'12.3'.trunc '127.09782'.trunc(3) '127.1'.trunc(3) '127'.trunc(2) '0'.trunc(2) == == == == == 12 127.097 127.100 127.00 0.00

Version 2.00

NetRexx Language Definition

167

upper([n [,length]])

returns a cop% o+ string with an% lowercase characters in the sub1string o+ string that begins at the nth character2 and is o+ length length characters2 replaced b% their uppercase e8uivalent5 n must be a positive whole number2 and de+aults to : -the +irst character in string.5 I+ n is greater than the length o+ string2 the string is returned unchanged5 length must be a non1negative whole number5 I+ length is not speci+ied2 or is greater than the number o+ characters +rom n to the end o+ the string2 the rest o+ the string -including the nth character. is assumed5 %xample,.
'Fou-Baa'.upper 'Mad Sheep'.upper 'Mad sheep'.upper(5) 'Mad sheep'.upper(5,1) 'Mad sheep'.upper(5,4) 'tinganon'.upper(1,1) ''.upper == == == == == == == 'FOU-BAA' 'MAD SHEEP' 'Mad SHEEP' 'Mad Sheep' 'Mad SHEEp' 'Tinganon' ''

verify(reference [,option [,start]])

veri+ies that string is composed onl% o+ characters +rom re#eren$e2 b% returning the position o+ the +irst character in string that is not also in re#eren$e5 I+ all the characters were +ound in re#eren$e2 > is returned5 &he option ma% be either 'Nomatch' -the de+ault. or 'Match'5 /nl% the +irst character o+ option is signi+icant and it ma% be in uppercase or in lowercase5 I+ 'Match' is speci+ied2 the position o+ the +irst character in string that i, in re#eren$e is returned2 or > is returned i+ none o+ the characters were +ound5 &he de+ault +or start is : -that is2 the search starts at the +irst character o+ string.5 &his can be overridden b% giving a di++erent start point2 which must be positive5 I+ string is the null string2 the method returns >2 regardless o+ the value o+ the option85 (imilarl% i+ start is greater than string.length2 > is returned5 I+ re#eren$e is the null string2 then the returned value is the same as the value used +or start2 unless 'Match' is speci+ied as the option2 in which case > is returned5 %xample,.
'123'.verify('1234567890') '1Z3'.verify('1234567890') 'AB4T'.verify('1234567890','M') '1P3Q4'.verify('1234567890','N',3) 'ABCDE'.verify('','n',3) 'AB3CD5'.verify('1234567890','m',4) == == == == == == 0 2 3 4 3 6

word(n)

returns the nth blank1delimited word in string5 n must be positive5 I+ there are +ewer than n words in string2 the null string is returned5 &his method is e!actl% e8uivalent to string.subword(n21)5 %xample,.
'Now is the time'.word(3) == 'the' 'Now is the time'.word(5) == ''

wordindex(n)

returns the character position o+ the nth blank1delimited word in string5 n must be positive5 I+ there are +ewer than n words in the string2 > is returned5
NetRexx Language Definition Version 2.00

168

%xample,.
'Now is the time'.wordindex(3) == 8 'Now is the time'.wordindex(6) == 0 wordlength(n)

returns the length o+ the nth blank1delimited word in string5 n must be positive5 I+ there are +ewer than n words in the string2 > is returned5 %xample,.
'Now is the time'.wordlength(2) == 2 'Now comes the time'.wordlength(2) == 5 'Now is the time'.wordlength(6) == 0

wordpos(phrase [,start])

searches string +or the +irst occurrence o+ the se8uence o+ blank1delimited words phrase2 and returns the word number o+ the +irst word o+ phrase in string5 Multiple blanks between words in either phrase or string are treated as a single blank +or the comparison2 but otherwise the words must match e!actl%5 (imilarl%2 leading or trailing blanks on either string are ignored5 I+ phrase is not +ound2 or contains no words2 > is returned5 B% de+ault the search starts at the +irst word in string5 &his ma% be overridden b% speci+%ing start -which must be positive.2 the word at which to start the search5 %xample,.
'now is the time'.wordpos('the') 'now is the time'.wordpos('The') 'now is the time'.wordpos('is the') 'now is the time'.wordpos('is the') 'now is the time'.wordpos('is time') 'To be or not to be'.wordpos('be') 'To be or not to be'.wordpos('be',3) == == == == == == == 3 0 2 2 0 2 6

words()

returns the number o+ blank1delimited words in string5 %xample,.

'Now is the time'.words == 4 ' '.words == 0 ''.words == 0

x2b()

,e!adecimal to binar%5 Converts string -a string o+ at least one he!adecimal characters. to an e8uivalent string o+ binar% digits5 ,e!adecimal characters ma% be an% decimal digit character ->1C. or an% o+ the +irst si! alphabetic characters -a1+.2 in either lowercase or uppercase5 string ma% be o+ an% lengthF each he!adecimal character with be converted to a string o+ +our binar% digits5 &he returned string will have a length that is a multiple o+ +our2 and will not include an% blanks5 %xample,.
'C3'.x2b == '11000011' '7'.x2b == '0111' '1C1'.x2b == '000111000001'

x2c()

,e!adecimal to coded character5 Converts the string -a string o+ he!adecimal characters. to a single character -packs.5 ,e!adecimal characters ma% be an% decimal digit character ->1C. or an% o+ the +irst si! alphabetic characters -a1+.2 in either lowercase or uppercase5

Version 2.00

NetRexx Language Definition

169

string must contain at least one he!adecimal characterF insigni+icant leading =eros are removed2 and the string is then padded with leading =eros i+ necessar% to make a su++icient number o+ he!adecimal digits to describe a character encoding +or the implementation5 An error results i+ the encoding described does not produce a valid character +or the implementation -+or e!ample2 i+ it has more signi+icant bits than the implementation's encoding +or characters.5 %xample,.
'004D'.x2c '4d'.x2c 'A2'.x2c '0'.x2c == == == == 'M' -- ASCII or Unicode 'M' -- ASCII or Unicode 's' -- EBCDIC '\0'

&he d2c method -see page :A>. can be used to convert a Net e!! number to the encoding o+ a character5
x2d([n])

,e!adecimal to decimal5 Converts the string -a string o+ he!adecimal characters. to a decimal number2 without rounding5 I+ string is the null string2 > is returned5 I+ n is not speci+ied2 string is taken to be an unsigned number5 %xample,.
'0E'.x2d '81'.x2d 'F81'.x2d 'FF81'.x2d 'c6f0'.x2d == == == == == 14 129 3969 65409 50928

I+ n is speci+ied2 string is taken as a signed number e!pressed in n he!adecimal characters5 I+ the most signi+icant -le+t1most. bit is =ero then the number is positiveF otherwise it is a negative number in twos1complement +orm5 In both cases it is converted to a Net e!! number which ma%2 there+ore2 be negative5 I+ n is >2 > is alwa%s returned5 I+ necessar%2 string is padded on the le+t with '0' characters -note2 not Dsign1 e!tendedE.2 or truncated on the le+t2 to length n charactersF -that is2 as though string.right(n2 '0') had been e!ecuted5. %xample,.
'81'.x2d(2) '81'.x2d(4) 'F081'.x2d(4) 'F081'.x2d(3) 'F081'.x2d(2) 'F081'.x2d(1) '0031'.x2d(0) == == == == == == == -127 129 -3967 129 -127 1 0

&he c2d method -see page :B@. can be used to convert a character to a decimal representation o+ its encoding5

170

NetRexx Language Definition

Version 2.00

Appendix A A Sample NetRexx Program

&his appendi! includes a short program2 called qtime2 which is an e!ample o+ a DrealE Net e!! program5 &he programs included elsewhere in this document have been contrived to illustrate speci+ic points5 B% contrast2 qtime is a simple but use+ul tool that genuinel% improves the human +actors o+ computer s%stems5 $eople +re8uentl% wish to know the time o+ da%2 and this program presents this in+ormation in a natural wa%5 &he st%le used +or this e!ample is the same as that used throughout the document2 with all s%mbols e!cept those describing classes being written in lower case5 /ther Net e!! programming st%les are possible2 o+ courseF Net e!! s%nta! is designed to permit a wide variet% o+ st%les with a minimum o+ punctuation5 &he qtime program is a modi+ication o+ one o+ the +irst e!! programs ever written -much o+ the program is identical.5 &he main changes are7 Inde!ed variables -brackets notation. are used instead o+ e!! stems5 &he word method +rom the Rexx class is used instead o+ the word e!! built1in +unction5 &he 3ava Date class is used to determine the current time5

Version 2.00

Appendix A A Sample NetRexx Program

171

/time#nrx 0uer+ !ime

/*--------------------------------------------------------*/ /* qtime.nrx. This program displays the time in English. */ /* If "?" is given as the first argument word then the */ /* program displays a description of itself. */ /*--------------------------------------------------------*/ /*--------- First process any argument words -------------*/ parse arg parm . /* get the first argument word */ select when parm='?' then tell /* say what we do */ when parm='' then nop /* OK (no first argument) */ otherwise say 'The only valid argument to QTIME is "?". The word' say 'that you supplied ("'parm'") has been ignored.' tell /* usually helpful to describe the program */ end /*-------- Now start processing in earnest ---------------*/ /* Nearness phrases - using associative array lookup */ near='' /* default */ near[0]='' /* exact */ near[1]=' just gone'; near[2]=' just after' /* after */ near[3]=' nearly'; near[4]=' almost' /* before */ /* Extract the hours, minutes, and seconds from the time. */ /* Use the Java Date class to get the time-of-day. */ parse Date() . . . now . /* time is the fourth word */ parse now hour':'min':'sec if sec>29 then min=min+1 /* round up minutes mod=min//5 /* where we are in 5-minute bracket out="It's"near[mod] /* start building the result if min>32 then hour=hour+1 /* we are TO the hour... min=min+2 /* shift minutes to straddle a 5-minute point */ */ */ */ */

/* Now special-case the result for Noon and Midnight. */ if hour//12=0 & min//60<=4 then do if hour=12 then say out 'Noon.' else say out 'Midnight.' exit /* we are finished here */ end /* Find five-minute segment and convert to 12-hour clock. min=min-(min//5) /* find nearest 5 mins if hour>12 then hour=hour-12 /* get rid of 24-hour clock else if hour=0 then hour=12 /* .. and allow for midnight */ */ */ */

172

Appendix A A Sample NetRexx Program

Version 2.00

$ontin*edJ
/* Determine the phrase to select when min= 0 then nop when min=60 then min=0 when min= 5 then out=out when min=10 then out=out when min=15 then out=out when min=20 then out=out when min=25 then out=out when min=30 then out=out when min=35 then out=out when min=40 then out=out when min=45 then out=out when min=50 then out=out when min=55 then out=out end use for each 5-minute segment. */ /* add "o'clock" later */ /* ditto */ 'five past' 'ten past' 'a quarter past' 'twenty past' 'twenty-five past' 'half past' 'twenty-five to' 'twenty to' 'a quarter to' 'ten to' 'five to'

numbers='one two three four five six'- /* (continuation) */ 'seven eight nine ten eleven twelve ' out=out numbers.word(hour) /* add the hour number */ if min=0 then out=out "o'clock" /* and o'clock if exact */ say out'.' exit /* display the final result */

/*--------------------------------------------------------*/ /* Tell: function that describes the use of the program. */ /*--------------------------------------------------------*/ method tell static say 'QTIME displays the current time in natural English.' say 'Call without any arguments to display the time, or' say 'with "?" to display this information.' say 'British English idioms are used in this program.' say /* space -- we are about to continue and show time. */ return /* Mike Cowlishaw, December 1979 - January 1985 /* NetRexx version March 1996 */ */

Version 2.00

Appendix A A Sample NetRexx Program

173

Appendix B JavaBean Support

&his appendi! describes an e!perimental +eature2 indire$t properties2 which is supported b% the Net e!! re+erence implementation5 &he intention o+ the +eature is to make it easier to write a certain kind o+ class known as a Ca"aBean5 Almost all 3avaBeans will have properties2 which are data items that a user o+ a 3avaBean is e!pected to be able to customi=e -+or e!ample2 the te!t on a pushbutton.5 &he names and t%pes o+ the properties o+ a 3avaBean are in+erred +rom Ddesign patternsE -in this conte!t2 conventions +or naming methods. or +rom $ropert%#escriptor objects associated with the 3avaBean5 &he 3avaBean properties do not necessaril% correspond to instance variables in the class 9 although ver% o+ten the% do5 &he 3avaBean speci+ication does not guarantee that 3avaBean properties that can be set can also be inspected2 nor does it describe how ambiguities o+ naming and method signatures are to be handled5 &he Net e!!C compiler allows a more rigorous treatment o+ 3avaBean properties2 b% allowing an optional attribute o+ properties in a class that declares them to be indire$t properties5 Indirect properties are properties o+ a known t%pe that are private to the class2 but which are e!pected to be publicl% accessible indirectl%2 though certain conventional method calls5 #eclaring properties to be indirect o++ers the +ollowing advantages7 6or man% simple cases2 the access methods +or the properties can be generated automaticall%F there is no need to e!plicitl% code them in the source +ile +or the class5 &his is especiall% help+ul +or Inde!ed $roperties -where +our methods are needed2 in general.5 *here access methods are e!plicitl% provided in the class2 the% can be checked +or correct +orm2 signature and accessibilit%5 &his detects errors at compile time that otherwise would onl% be determined b% testing5 (imilarl%2 attention can be drawn to the presence o+ methods that ma% be intended to be an access method +or an indirect propert%2 but will not be recogni=ed as such b% builders5 &he ne!t section describes the use o+ indirect properties in more detail5

Version 2.00

Appendix B JavaBean Support

175

Indirect properties
&he properties instruction -see page ::;. is used to de+ine the attributes o+ +ollowing property variables5 &he "isi&ility o+ properties ma% include a new alternative7 indirect5 $roperties with this +orm o+ visibilit% are known as indire$t properties5 &hese are properties o+ a known t%pe that are private to the class2 but which are e!pected to be publicl% accessible indirectl%2 though certain conventional method calls5 6or e!ample2 consider the simple program7
class Sandwich extends Canvas implements Serializable properties indirect slices=Color.gray filling=Color.red method Sandwich resize(100,30) method paint(g=Graphics) g.setColor(slices) g.fillRect(0, 0, size.width, size.height) g.setColor(filling) g.fillRect(12, 12, size.width-12, size.height-12)

&his declares the Sandwich class as having two indirect properties2 called slices and filling2 both being o+ t%pe java.awt.Color5 In the e!ample2 no access methods are provided +or the properties2 so the compiler will add them5 B% implementation1dependent convention2 the names are pre+i!ed with verbs such as get and set2 et$.2 and have the +irst character o+ their name uppercased to +orm the method names5 ,ence2 in this 3ava1 based e!ample2 the +ollowing +our methods are added7
method getSlices returns java.awt.Color return slices method getFilling returns java.awt.Color return filling method setSlices($1=java.awt.Color) slices=$1 method setFilling($2=java.awt.Color) filling=$2

-where $1 and $2 are DhiddenE names used +or accessing the method arguments.5 Note that the indirect attribute +or a propert% is an alternative to the public2 private2 and inheritable2 and shared attributes5 Like private properties2 indirect properties can onl% be accessed directl% b% name +rom within the class in which the% occurF other classes can onl% access them using the access methods -or other methods that ma% use2 or have a side1e++ect on2 the properties.5 Indirect properties ma% be constant -impl%ing that onl% a get method is generated or allowed2 though the private propert% ma% be changed b% methods within the class. or transient -see page ::<.5 &he% ma% not be static or volatile5 In detail2 the rules used +or generating automatic methods +or a propert% whose name is xxxx are as +ollows7 :5 A method called getXxxx which returns the value o+ the propert% is generated5 &he returned value will have the same t%pe as xxxx5 ;5 I+ the t%pe o+ xxxx is boolean then the generated method will be called isXxxx instead o+
176 Appendix B JavaBean Support Version 2.00

getXxxx5

<5 I+ the propert% is not constant then a method +or setting the propert% will also be generated5 &his will be called setXxxx2 and take a single argument o+ the same t%pe as xxxx5 &his assigns the argument to the propert% and returns no value5 I+ the propert% has an arra% t%pe -+or e!ample2 char[].2 then it must onl% have a single dimension5 &wo +urther methods ma% then be generated2 according to the rules7 :5 A method called getXxxx which takes a single int as an argument and which returns an item +rom the propert% arra% is generated5 &he returned value will have the same t%pe as xxxx2 without the []5 &he integer argument is used to inde! into the arra%5 ;5 As be+ore2 i+ the result t%pe o+ the method would be boolean then the name o+ the method will be isXxxx instead o+ getXxxx5 <5 I+ the propert% is not constant then a method +or setting an item in the propert% arra% will also be generated5 &his will be called setXxxx2 and take two arguments7 the +irst is an int that is used to select the item to be changed2 and the second is an undimensioned argument o+ the same t%pe as xxxx5 It assigns the second argument to the item in the propert% arra% inde!ed b% the +irst argument2 and returns no value5 6or e!ample2 +or an indirect propert% declared thus7
properties indirect fred=foo.Bar[]

the +our methods generated would be7

method method method method getFred returns foo.Bar[]; return fred getFred($1=int) returns foo.Bar; return fred[$1] setFred($2=foo.Bar[]); fred=$2 setFred($3=int, $4=foo.Bar); fred[$3]=$4

Note that in all cases a method will onl% be generated i+ it would not e!actl% match a method e!plicitl% coded in the current class5

Explicit provision of access methods

/+ten2 +or e!ample when an indirect propert% has an on1screen representation2 it is desirable to redraw the propert% when the propert% is changed -and in more complicated cases2 there ma% be interactions between properties.5 &hese and other actions will re8uire e!tra processing which will not be carried out b% automaticall% generated methods5 &o add this processing the access methods will have to be coded e!plicitl%5 In the D(andwichE e!ample2 we onl% need to suppl% the set methods2 perhaps b% adding the +ollowing to the e!ample class above7
method setSlices(col=Color) slices=col -- update the property this.repaint -- redraw the component method setFilling(col=Color) filling=col this.repaint

I+ we add these two methods2 the% will no longer be added automaticall% -the two get methods will continue to be provided automaticall%2 however.5 6urther2 since the names match possible access methods +or properties that are declared to be indirect2 the compiler will check the method declaration7 the method signatures and return t%pe -i+ an%. must be correct2 +or e!ample5 Also2 since the names o+
Version 2.00 Appendix B JavaBean Support 177

access methods are case1sensitive -in a 3ava environment.2 %ou will be warned i+ a method appears to be intended to be an access method but the case o+ one or more letters is wrong5 (peci+icall%2 the checks carried out are as +ollows7 :5 6or methods whose names e!actl% match a potential access method +or an indirect propert% -that is2 start with is2 get2 or set2 which is then +ollowed b% the name o+ an indirect propert% with the +irst character o+ the name uppercased.7 &he argument list +or -signature o+. the method must match one o+ those that could possibl% be automaticall% generated +or the propert%5 &he returns t%pe -i+ an%. must match the e!pected returns t%pe +or that method5 I+ the returns t%pe is simpl% boolean2 then the method name must start with is5 Conversel%2 i+ the method name starts with is then the returns t%pe must be just boolean5 I+ the propert% is constant then the name o+ the method cannot start with set5 A warning is given i+ the method is not public -the de+ault.5 ;5 6or methods whose names match a potential access method2 as above2 e!cept in case7 A warning is given that the method in 8uestion ma% be intended to be an indirect propert% access method2 but will not be recogni=ed as such b% builders5 &hese checks detect a wide variet% o+ errors at compile time2 hence speeding the development o+ classes that use indirect properties5

178

Appendix B JavaBean Support

Version 2.00

Appendix C The netrexx.lang Package

&his appendi! documents the netrexx.lang package2 which includes the classes used +or creating string objects o+ t%pe Rexx along with several classes that are o+ten used while running Net e!! programs5 &his appendi! describes the public methods and properties o+ these classes2 as implemented b% the re+erence implementation5 It does not include those Dbuilt1inE Methods +or Net e!! strings -see page :BB. in the Rexx class that +orm part o+ the Net e!! language2 or those classes and methods that are internal DhelperE components -which2 +or e!ample2 are used as repositories +or rarel%1e!ecuted code.5 &he classes in the netre!!5lang package are7 &he "!ception classes -see page :@>. e!! -see page :@:. e!!I/ -helper class2 +or say and ask. e!!Node -helper class2 +or inde!ed strings. e!!/perators inter+ace -see page :@B. e!!$arse -helper class2 +or parse. e!!(et -see page :@A. e!!&race -helper class2 +or trace. e!!Util -helper class2 +or the e!! class. e!!*ords -helper class2 +or the e!! class.

Version 2.00

Appendix C The netrexx.lang Package

179

Exception classes
&he classes provided +or e!ceptions in the netrexx.lang package are all subclasses o+ java.lang.RuntimeException and all have the same content5 "ach has two constructors7 one taking no argument and the other taking a string o+ t%pe java.lang.String2 which is used +or additional detail describing the e!ception5 &he "!ceptions are signalled as +ollows5
BadArgumentException BadColumnException BadNumericException DivideException

signalled when an argument to a method is incorrect5 signalled when a column number in a parsing template is not valid -+or e!ample2 not a number.5 signalled when a numeric digits instruction tries to set a value that is not a whole number2 or is not positive2 or is more than nine digits5 signalled when an error occurs during a division5 &his ma% be due to an attempt to divide b% =ero2 or when the intermediate result o+ an integer divide or remainder operation is not valid5 re8uire more than nine digits5

ExponentOverflowException signalled when the e!ponent resulting +rom an operation would NoOtherwiseException NotCharacterException NotLogicException

signalled when a select construct does not suppl% an otherwise clause and none o+ e!pressions on the when clauses resulted in '1'5 signalled when a conversion +rom a string to a single character was attempted but the string was not e!actl% one character long5 signalled when a conversion +rom a string to a boolean was attempted but the string was neither the string '0' nor the string '1'5

/ther e!ceptions2 +rom the java.lang package2 ma% also be signalled2 +or e!ample NumberFormatException or NullPointerException5

180

Appendix C The netrexx.lang Package

Version 2.00

The Rexx class

&he class netrexx.lang.Rexx implements the Net e!! string class2 and includes the Dbuilt1inE Methods +or Net e!! strings -see page :BB.5 #escribed here are the plat+orm1dependent methods as provided in the re+erence implementation7 constructors -see page :@:. +or the class2 the methods +or arithmetic operations -see page :@;.2 and miscellaneous methods -see page :@G. intended +or general use5 &he class netrexx.lang.Rexx is seriali=able5

Rexx constructors
&hese constructors all create a string o+ t%pe netrexx.lang.Rexx5
Rexx(arg=boolean) Constructs a string which will have the value '1' i+ arg is : -tr*e. or the value '0' i+ arg is > -#alse.5 Rexx(arg=byte)

Constructs a string which is the decimal representation o+ the @1bit signed binar% integer arg5 &he string will contain onl% decimal digits2 pre+i!ed with a leading minus sign -h%phen. i+ arg is negative5 A leading =ero will be present onl% i+ arg is =ero5 Constructs a string o+ length : whose +irst and onl% character is a cop% o+ arg5 Constructs a string b% cop%ing the characters o+ the character arra% arg in se8uence5 &he length o+ the string is the number o+ elements in the character arra% -that is2 arg.length.5 Constructs a string which is the decimal representation o+ the <;1bit signed binar% integer arg5 &he string will contain onl% decimal digits2 pre+i!ed with a leading minus sign -h%phen. i+ arg is negative5 A leading =ero will be present onl% i+ arg is =ero5 Constructs a string which is the decimal representation o+ the AG1bit signed binar% +loating point number arg5 :1he pre$ise #or)at o# the res*lt )ay $hange and will &e de#ined later.> Constructs a string which is the decimal representation o+ the <;1bit signed binar% +loating point number arg5 :1he pre$ise #or)at o# the res*lt )ay $hange and will &e de#ined later.> Constructs a string which is the decimal representation o+ the AG1bit signed binar% integer arg5 &he string will contain onl% decimal digits2 pre+i!ed with a leading minus sign -h%phen. i+ arg is negative5 A leading =ero will be present onl% i+ arg is =ero5 Constructs a string which is cop% o+ arg2 which is o+ t%pe netrexx.lang.Rexx5 arg must not be null5 An% sub1values -see page ?<. are ignored -that is2 the% are not present in the object returned b% the constructor.5 Constructs a string which is the decimal representation o+ the :A1bit signed binar% integer arg5 &he string will contain onl% decimal digits2 pre+i!ed with a
Appendix C The netrexx.lang Package 181

Rexx(arg=char) Rexx(arg=char[])

Rexx(arg=int)

Rexx(arg=double)

Rexx(arg=float)

Rexx(arg=long)

Rexx(arg=Rexx)

Rexx(arg=short)

Version 2.00

leading minus sign -h%phen. i+ arg is negative5 A leading =ero will be present onl% i+ arg is =ero5
Rexx(arg=String)

Constructs a Net e!! string b% cop%ing the characters o+ arg2 which is o+ t%pe java.lang.String2 in se8uence5 &he length o+ the string is same as the length o+ arg -that is2 arg.length().5 arg must not be null5 Constructs a Net e!! string b% concatenating the elements o+ the java.lang.String arra% arg together in se8uence with a blank between each pair o+ elements5 &his ma% be used +or converting the argument word arra% passed to the main method o+ a 3ava application into a single string5 I+ the number o+ elements o+ arg is =ero then an empt% string -o+ length >. is returned5 /therwise2 the length o+ the string is the sum o+ the lengths o+ the elements o+ arg2 plus the number o+ elements o+ arg2 less one5 arg must not be null5

Rexx(arg=String[])

Rexx arithmetic methods

&hese methods implement the Net e!! arithmetic operators2 as described in the section on 3*)&ers and arith)eti$ -see page :G>.5 "ach corresponds to and implements a method in the e!!/perators inter+ace class -see page :@B.5 "ach o+ the methods here takes a e!!(et -see page :@A. object as an argument5 &his argument provides the numeric settings +or the operationF i+ null is provided +or the argument then the de+ault settings are used -digitsW92 formWscientific.5 6or monadic operators2 onl% the RexxSet argument is presentF the operation acts upon the current object5 6or d%adic operators2 the RexxSet argument and a Rexx argument are presentF the operation acts with the current object being the le+t1hand operand and the second argument being the right1hand operand5 6or e!ample2 under de+ault numeric settings2 the e!pression7
award+extra

-where award and e%tra are re+erences to objects o+ t%pe Rexx. could be written as7
award.OpAdd(null, extra)

which would return the result o+ adding award and e%tra under the de+ault numeric settings5
OpAdd(set=RexxSet, rhs=Rexx) OpAnd(set=RexxSet, rhs=Rexx) OpCc(set=RexxSet, rhs=Rexx)

Implements the Net e!! + -Add. operator2 and returns the result as a string o+ t%pe Rexx5 Implements the Net e!! & -And. operator2 and returns a result -> or :. o+ t%pe boolean5 Implements the Net e!! || or a&*ttal -Concatenate without blank. operator2 and returns the result as a string o+ t%pe Rexx5

OpCcblank(set=RexxSet, Implements the Net e!! &lank -Concatenate with blank. operator2 and rhs=Rexx) returns the result as a string o+ t%pe Rexx5 OpDiv(set=RexxSet, rhs=Rexx) OpDivI(set=RexxSet, rhs=Rexx)
182

Implements the Net e!! / -#ivide. operator2 and returns the result as a string o+ t%pe Rexx5 Implements the Net e!! % -Integer divide. operator 2 and returns the

Appendix C The netrexx.lang Package

Version 2.00

result as a string o+ t%pe Rexx5

OpEq(set=RexxSet, rhs=Rexx) OpEqS(set=RexxSet, rhs=Rexx) OpGt(set=RexxSet, rhs=Rexx) OpGtEq(set=RexxSet, rhs=Rexx) OpGtEqS(set=RexxSet, rhs=Rexx) OpGtS(set=RexxSet, rhs=Rexx) OpLt(set=RexxSet, rhs=Rexx) OpLtEq(set=RexxSet, rhs=Rexx) OpLtEqS(set=RexxSet, rhs=Rexx) OpLtS(set=RexxSet, rhs=Rexx) OpMinus(set=RexxSet) OpMult(set=RexxSet, rhs=Rexx) OpNot(set=RexxSet) OpNotEq(set=RexxSet, rhs=Rexx) OpNotEqS(set=RexxSet, rhs=Rexx) OpOr(set=RexxSet, rhs=Rexx) OpPlus(set=RexxSet) OpPow(set=RexxSet, rhs=Rexx) OpRem(set=RexxSet, rhs=Rexx) OpSub(set=RexxSet,
Version 2.00

Implements the Net e!! = -"8ual. operator2 and returns a result -> or :. o+ t%pe boolean5 Implements the Net e!! == -(trictl% e8ual. operator2 and returns a result -> or :. o+ t%pe boolean5 Implements the Net e!! > -)reater than. operator2 and returns a result -> or :. o+ t%pe boolean5 Implements the Net e!! >= -)reater than or e8ual. operator2 and returns a result -> or :. o+ t%pe boolean5 Implements the Net e!! >>= -(trictl% greater than or e8ual. operator2 and returns a result -> or :. o+ t%pe boolean5 Implements the Net e!! >> -(trictl% greater than. operator2 and returns a result -> or :. o+ t%pe boolean5 Implements the Net e!! < -Less than. operator2 and returns a result -> or :. o+ t%pe boolean5 Implements the Net e!! <= -Less than or e8ual. operator2 and returns a result -> or :. o+ t%pe boolean5 Implements the Net e!! <<= -(trictl% less than or e8ual. operator2 and returns a result -> or :. o+ t%pe boolean5 Implements the Net e!! << -(trictl% less than. operator2 and returns a result -> or :. o+ t%pe boolean5 Implements the Net e!! Prefix - -Minus. operator 2 and returns the result as a string o+ t%pe Rexx5 Implements the Net e!! * -Multipl%. operator 2 and returns the result as a string o+ t%pe Rexx5 Implements the Net e!! Prefix \ -Not. operator2 and returns a result -> or :. o+ t%pe boolean5 Implements the Net e!! \= -Not e8ual. operator2 and returns a result -> or :. o+ t%pe boolean5 Implements the Net e!! \== -(trictl% not e8ual. operator2 and returns a result -> or :. o+ t%pe boolean5 Implements the Net e!! | -Inclusive or. operator2 and returns a result -> or :. o+ t%pe boolean5 Implements the Net e!! Prefix + -$lus. operator 2 and returns the result as a string o+ t%pe Rexx5 Implements the Net e!! ** -$ower. operator 2 and returns the result as a string o+ t%pe Rexx5 Implements the Net e!! // - emainder. operator 2 and returns the result as a string o+ t%pe Rexx5 Implements the Net e!! - -(ubtract. operator2 and returns the result as a
Appendix C The netrexx.lang Package 183

rhs=Rexx) OpXor(set=RexxSet, rhs=Rexx)

string o+ t%pe Rexx5 Implements the Net e!! && -"!clusive or. operator2 and returns a result -> or :. o+ t%pe boolean5

Rexx miscellaneous methods

&hese methods provide standard 3ava methods +or the class2 together with various conversions5
charAt(offset=int)

eturns the character +rom the string at o##set -that is2 i+ o##set is > then the +irst character is returned2 et$..5 &he character is returned as t%pe char5 I+ o##set is negative2 or is greater than or e8ual to the length o+ the string2 an e!ception is signalled5

equals(item=Object) Compares the string with the value o+ ite)2 using a strict character1b%1 character comparison2 and returns a result o+ t%pe boolean5

I+ ite) is null or is not an instance o+ one o+ the t%pes Rexx2 java.lang.String2 or char[]2 then > is returned5 /therwise2 ite) is converted to t%pe Rexx and the /p"8( -see page :@<. method -or e8uivalent. is used to compare the current string with the converted string2 and its result is returned5
hashCode() toboolean() tobyte()

eturns a hashcode o+ t%pe int +or the string5 &his hashcode is suitable +or use b% the java.util.Hashtable class5 Converts the string to t%pe boolean5 I+ the string is neither 0 nor 1 then a NotLogicException -see page :@>. is signalled5 Converts the string to t%pe byte5 I+ the string is not a number2 has a non1=ero decimal part2 or is out o+ the possible range +or a byte -@1bit signed integer. result then a NumberFormatException is signalled5 Converts the string to t%pe char5 I+ the string is not e!actl% one character in length then a NotCharacterException -see page :@>. is signalled5 Converts the string to t%pe char[]5 A character arra% object o+ the same length as the string is created2 and the characters o+ the string are copied to the arra% in se8uence5 &he character arra% is then returned5 Converts the string to t%pe double5 I+ the string is not a number2 or is out o+ the possible range +or a double -AG1bit signed +loating point. result then a NumberFormatException is signalled5 Converts the string to t%pe float5 I+ the string is not a number2 or is out o+ the possible range +or a float -<;1bit signed +loating point. result then a NumberFormatException is signalled5 Converts the string to t%pe int5 I+ the string is not a number2 has a non1=ero decimal part2 or is out o+ the possible range +or an int -<;1bit signed integer. result then a NumberFormatException is signalled5 Converts the string to t%pe long5 I+ the string is not a number2 has a non1=ero decimal part2 or is out o+ the possible range +or a long -AG1bit signed integer. result then a NumberFormatException is signalled5
Appendix C The netrexx.lang Package Version 2.00

tochar() toCharArray()

todouble()

tofloat()

toint()

tolong()

184

toshort()

Converts the string to t%pe short5 I+ the string is not a number2 has a non1 =ero decimal part2 or is out o+ the possible range +or a short -:A1bit signed. result then a NumberFormatException is signalled5 Converts the string to t%pe java.lang.String5 A (tring object o+ the same length as the string is created2 and the characters o+ the string are copied to the new string in se8uence5 &he (tring is then returned5

toString()

The RexxOperators interface class

&he RexxOperators inter+ace class de+ines the signatures o+ the methods that implement the Net e!! -and e!!. operators5 &hese methods are described in the section /e%% arith)eti$ )ethods :see page 102>5 In the +uture this inter+ace ma% be used to allow the overloading o+ operators +or objects o+ t%pes other than Rexx5 &he current Net e!! language de+inition does not permit operator overloading5

Version 2.00

Appendix C The netrexx.lang Package

185

The RexxSet class

&he RexxSet class is used to provide the numeric settings +or the methods described in the section /e%% arith)eti$ )ethods :see page 102>5 *hen provided2 a e!!(et /bject supplies the numeric settings +or the operationF when null is provided then the de+ault settings are used -digitsW92 formWSCIENTIFIC.5

Public properties
&hese properties suppl% the numeric settings and certain values the% ma% take5 A+ter construction2 the digits and form values should onl% be changed b% using the setDigits and setForm methods5
DEFAULT_DIGITS DEFAULT_FORM digits

A constant o+ t%pe int that describes the de+ault number o+ digits +or a numeric operation -C.5 A constant o+ t%pe byte that describes the de+ault e!ponential +ormat +or a numeric operation -SCIENTIFIC.5 A value o+ t%pe int that describes the numeric digits to be used +or a numeric operation5 &he e!! arithmetic methods -see page :@;. use this value to determine the signi+icance o+ results5 digits must alwa%s be greater than =ero5 A constant o+ t%pe byte that signi+ies that engineering e!ponential +ormatting should be used +or a numeric operation5 A value o+ t%pe byte that describes the e!ponential +ormat to be used +or a numeric operation5 &he e!! arithmetic methods -see page :@;. use this value to determine the +ormatting o+ results that re8uire an e!ponent5 form must be either ENGINEERING or SCIENTIFIC5 A constant o+ t%pe byte that signi+ies that scienti+ic e!ponential +ormatting should be used +or a numeric operation5

ENGINEERING form

SCIENTIFIC

Constructors
&hese constructors are used to set the initial values o+ a e!!(et object5
RexxSet() RexxSet(newdigits=int) RexxSet(newdigits=int, newform=byte) RexxSet(arg=RexxSet)

Constructs a e!!(et object which has de+ault digits and form properties5 Constructs a e!!(et object which has its digits propert% set to newdigits and its form propert% set to DEFAULT_DIGITS5 Constructs a e!!(et object which has its digits propert% set to newdigits and its form propert% set to new#or)5 Constructs a e!!(et object which is cop% o+ arg2 which is o+ t%pe netrexx.lang.RexxSet5 arg must not be null5

186

Appendix C The netrexx.lang Package

Version 2.00

Methods
&he e!!(et class has the +ollowing additional methods7
formword()

eturns a string o+ t%pe netrexx.lang.Rexx that describes the form propert%5 &his will either be the string 'engineering' or the string 'scientific'2 corresponding to the form value ENGINEERING or SCIENTIFIC2 respectivel%5 (ets the digits value +or the RexxSet object2 +rom newdigits2 a+ter rounding and checking as de+ined +or the numeric instructionF newdigits must be a positive whole number with no more than nine digits5 No value is returned5 (ets the form value +or the RexxSet object2 +rom new#or)word5 &his must e8ual either the string 'engineering' or the string 'scientific'2 corresponding to the form value ENGINEERING or SCIENTIFIC2 respectivel%5 No value is returned5

setDigits(newdigits=Rexx)

setForm(newformword=Rexx)

Version 2.00

Appendix C The netrexx.lang Package

187

Index
A
ABB "0 method 156 Abbreviations testing with ABB "0 method 156 AB( method 156 Absolute column speci+ication in parsing 136 positional pattern 137 value2 +inding using AB( method 156 AB(& AC& on CLA(( instruction 79 on M"&,/# instruction 99 Abstract classes 79 Abstract methods 79, 99 Abuttal concatenation operator 62, 64 Acknowledgements 15 Active constructs 90 Active constructs
89

Adaptabilit% 13 A#A$&" on CLA(( instruction 79 Adapter classes 79 Addition 62 de+inition 143 Algebraic precedence 66 ALL & AC" setting 120 Alphabetics checking with #A&A&H$" 159 Alphanumerics checking with #A&A&H$" 159 AN# logical operator 64 AN(I standard arithmetic de+inition 141 +or "II 9 Arbitrar% precision arithmetic 140 Arguments o+ methods 53

on M"&,/# instruction 98 optional 99 passing to methods 53 provided b% caller 98 re8uired 99 Arithmetic 140 comparisons 146 errors 148 e!ceptions 148 implementation independence 148 NUM" IC settings 104 operation rules 143 operators 62, 140, 142 over+low 148 overview 22 precision 141 under+low 148 Arra% initiali=er in terms 48, 75 Arra%s 74 constructors 74 in terms 52 initiali=ing 75 overview 26 re+erences 74 A(CII coded character set 39 A(K special word 130 Assignment 68, 69 binar% 150 instruction 68, 69 o+ literals 150 propert% initiali=ation 124 Astonishment +actor 13

B
B;I method 156 Background 7 Backslash character escape se8uence in strings 41
Index 41

Version 2.00

189

not operator 64 BadArgument"!ception 180 BadColumn"!ception 180 BadNumeric"!ception 180 BA(IC2 programming language 11 Binar% arithmetic 149 checking with #A&A&H$" 159 conversion to he!adecimal 156 operations 149 see Conversion 159 values 149 BINA H in /$&I/N( instruction 106 on CLA(( instruction 80 on M"&,/# instruction 101 Binar% classes 80, 149 assignment 150 binar% methods 101 control variables 150 L//$ instruction 150 NUM" IC instruction 150 Binar% constructors 150 Binar% literals 150 Binar% methods 101, 149 assignment 150 control variables 150 L//$ instruction 150 NUM" IC instruction 150 Binar% numbers 59, 149 Binar% numbers overview 33 Binar% numeric s%mbol 42, 45 Binar% operations d%adic 149 monadic 150 pre+i! 150 Bits binar% operators 64 checking with #A&A&H$" 159 Blank 40 adjacent to operator character 43 adjacent to special character 43 as concatenation operator 62 as t%pe conversion operator 64 operator 62, 64 removal with ($AC" method 166 removal with (& I$ method 166 Block comments 40 Bod% o+ a loop 91 o+ classes 78 o+ group 82 o+ methods 98
190

o+ select 116 Boolean operations 64 boolean t%pe2 value o+ 59 Bottom o+ program2 reaching during e!ecution Bounded loop 92 controlled 92 over values 94 simple 92 Brackets in arra% initiali=ers 48, 75 in arra% re+erences 74 in inde!ed re+erences 48 in inde!ed strings 73 in terms 48 Built1in methods 155 Built1in methods see Method2 built1in 155 BH phrase o+ L//$ instruction 91

84

C
C2 programming language 8 C;# method 158 C;I method 158 Carriage return character escape se8uence 41 Case insensitivit% to 10 o+ names 44 CA(" on ("L"C& instruction 117 Casting to t%pe 64 Casts see Conversion 58 CA&C, on #/ instruction 83 on L//$ instruction 96 on ("L"C& instruction 118 use o+ 153 Caught e!ceptions 152 C"N&" method 157 C"N& " method 157 C,AN)"(& method 157 Changing strings using C,AN)"(& 157 using & AN(LA&" 167 char as a string 59 Character 39 appearance 39 conversion to decimal 158 conversion to he!adecimal 158 converting to binar% 150

Index

Version 2.00

encodings 39, 150 +rom a number 160, 169 +rom decimal 160 +rom he!adecimal 169 gl%phs 39 removal with (& I$ method 166 Character sets 39 Characters see (trings 41 charAt method 184 Checked e!ceptions 153 Class 46 bod% o+ 78 de+inition 124 +ilename o+ 131 instances o+ 56 name o+ 78 names2 case o+ 44 package o+ 110 8uali+ied name o+ 110 short name o+ 78 starting 78 CLA(( special word 130 CLA(( instruction 78 see program structure 78 Classes abstract 79 adapter 79 and subclasses 80 and superclasses 80 binar% 80 dependent 47, 128 +inal 79 inter+ace 79 minor 47, 127 overview 29 parent 47, 127 private 78 public 78 shared 78 standard 79 Clauses 40 continuation o+ 44 null 68 Coded character 39 conversion to decimal 158 conversion to he!adecimal 158 +rom decimal 160 +rom he!adecimal 169 Coded character set A(CII 39 "BC#IC 39 Unicode 39
Version 2.00

Collating se8uence2 using ("NU"NC" Column speci+ication in parsing 136 Comma in arra% re+erences 74 in inde!ed strings 73 in method calls 53 Command line options 109 Comments 40 block 40 line 40 nesting 40 starting a program with 41 C/MM"N&( option 106 C/M$AC& option 106 Comparative operators 62 C/M$A " method 157 Comparison o+ numbers 62, 146 o+ strings

165

using C/M$A "

157

o+ strings and numbers 62 Compiler options 106 Compound terms 48 Concatenation o+ strings 62 o+ t%pes 64 Conditional loops 91 Conditional phrase 92, 95 Consistenc% 13 C/N(/L" option 107 Console2 writing to with (AH 115 C/N(&AN& on M"&,/# instruction 99 on $ /$" &I"( instruction 113 Constant methods 100 see Methods2 static 100 Constants 113 Constants used b% classes 80 using properties 113 Constructor e!!-boolean. 181 e!!-b%te. 181 e!!-char. 181 e!!-charOP. 181 e!!-double. 181 e!!-+loat. 181 e!!-int. 181 e!!-long. 181 e!!- e!!. 181 e!!-short. 181 e!!-(tring. 182 e!!-(tringOP. 182

Index

191

e!!(et-. 186 e!!(et-int2b%te. 186 e!!(et-int. 186 e!!(et- e!!(et. 186 Constructor methods see Constructors 56 Constructors 56, 98 arra% 74 binar% 150 de+ault 56 in minor classes 127 method 98 o+ dependent objects 128 o+ minor classes 127 8uali+ied 128 special 132 Constructs active 90 Continuation character 44 o+ clauses 44 Control instructions2 overview 21 Control variable 92, 94 Controlled loops 92 Conversion automatic 58 binar% constructors 150 binar% to he!adecimal 156 character to decimal 158 character to he!adecimal 158 coded character to decimal 158 coded character to he!adecimal 158 cost o+ 60 decimal to character 160 decimal to he!adecimal 160 e!plicit 59 +ormatting numbers 161 he!adecimal to binar% 169 he!adecimal to character 169 he!adecimal to decimal 170 o+ characters 150 o+ t%pes 58 o+ well1known t%pes 58 overview 33 C/$I"( method 157 C/$HIN#"I"# method 158 Cop%ing a string using C/$I"( 157 Cop%ing inde!ed variables 158 Counting see Arithmetic 104 strings2 using C/UN&(& 158 words2 using */ #( 169 C/UN&(& method 158 C /(( "6 option 107
192

D
#;C method 160 #;I method 160 #ata conversions 58 length o+ 61, 163 terms 48, 61 t%pe checking 10, 61 t%pes 46 #A&A&H$" method 159 #atat%pes 10, 46, 58, 61 #ealing with realit% 13 #ebugging Net e!! programs see & AC" instruction 120 #ecimal arithmetic 10, 140 conversion to character 160 conversion to he!adecimal 160 #"CIMAL option 107 #eclarations o+ variables 70 wh% optional in Net e!! 12 #"6AUL&T#I)I&( propert% 186 #"6AUL&T6/ M propert% 186 #eleting part o+ a string 160 words +rom a string 160 #elimiters +or comments 40 +or strings 41 #elimiters2 clause see (emicolons 40 #"L(& method 160 #"L*/ # method 160 #"$"N#"N& on CLA(( instruction 128 #ependent classes 47, 128 restrictions 129 see Minor classes 128 #ependent object 128 constructing 128 #"$ "CA&"# on CLA(( instruction 80 on M"&,/# instruction 101 on $ /$" &I"( instruction 113 #IA) option 107 #iagrams2 o+ s%nta! 38 #igits checking with #A&A&H$" 159 in numbers 141 #I)I&( e++ect on whole numbers 147 on NUM" IC instruction 104, 141
Index Version 2.00

rounding when numbers used special word 130 digits propert% 186 #imension o+ arra%s 46 o+ t%pes 46 #imensioned t%pes 46 #ispla%ing data see (AH instruction 115 #ivide"!ception 180 #ivision 62 de+inition 143 integer 140 #/ group 82 naming o+ 82 #/ instruction 82 LAB"L 82 see grouping 82 #ollar sign in s%mbols 42 #ouble18uote escape se8uence 41 string delimiter 41 #umm% instruction2 N/$ 103 #uplicate methods 102 #%adic operators 61

147

E
"1notation 65, 147 "1notation de+inition 146 in s%mbols 42 "BC#IC coded character set 39 "L(" ke%word see I6 instruction 85 "mpt% re+erence2 null 131 "ncodings binar% 150 o+ characters 39 "ncodings2 o+ characters 39 "N# clause see #/ instruction 82 see L//$ instruction 91 see ("L"C& instruction 116 speci+%ing control variable 94 "nd condition o+ a L//$ loop 92 "nd1o+1+ile character 40 "ngineering notation 104, 147 "N)IN"" IN) propert% 186 "N)IN"" IN) value +or NUM" IC 6/ M "nvironment2 independence +rom 12 "/6 character 40

104

"8ualit% o+ objects 63 testing o+ 62 e8uals method 184 "8uals sign see W e8uals sign 69 "rror detection2 locali=ed 12 "rrors during arithmetic 148 "scape se8uences in strings 41 "uro character 42 in s%mbols 42 "valuation o+ e!pressions 61 o+ terms 49 "venModd rounding 142 "!ample applet 34 arra%s 26 ,ello *orld 124 inde!ed strings 25 o+ constructors 57 o+ e!ception handling 153 o+ two classes 125 program 18, 19, 25, 27, 29, 31-33, 35, 77, 172 trace 31, 32 "!ception BadArgument"!ception 180 BadColumn"!ception 180 BadNumeric"!ception 180 #ivide"!ception 180 "!ponent/ver+low"!ception 180 No/therwise"!ception 180 NotCharacter"!ception 180 NotLogic"!ception 180 Null$ointer"!ception 180 Number6ormat"!ception 180 "!ceptions 152 a+ter CA&C, clause 153 a+ter 6INALLH clause 153 checked 153 during arithmetic 148 during conversions 59 listed on M"&,/# instruction 101 overview 21, 35 raising 119 signalling 119 throwing 119 "!clusive / logical operator 64 "II(&( method 161 "II& instruction 84 "!perimental +eature 175 "I$LICI& option 107 "!ponential notation 65, 104, 140, 147
Index 193

Version 2.00

"!ponential notation de+inition 146 in s%mbols 42 "!ponentiation 62 de+inition 144 "!ponent/ver+low"!ception 180 "!pressions evaluation 61 e!amples 66 overview 19 results o+ 61 "!tending classes overview 29 "I&"N#( on CLA(( instruction 80 "!tra digits in numbers 141 in numeric s%mbols 42, 43 in s%mbols 42 "!tra letters2 in s%mbols 42 "!tracting a sub1string 166 words +rom a string 166

F
6alse value 64 6INAL on CLA(( instruction 79 on M"&,/# instruction 99 6inal classes 79 6inal methods 100 6INALLH on #/ instruction 83 on L//$ instruction 96 on ("L"C& instruction 118 reached b% L"A0" 90 use o+ 153 6inding a mismatch using C/M$A " 157 6inding a string in another string 163, 165 6i!ed si=e2 o+ arra%s 74 6loating1point numbers2 binar% 149 6low control abnormal2 with (I)NAL 119 with #/ construct 82 with I6 construct 85 with L//$ construct 91 with ("L"C& construct 116 6/ phrase o+ L//$ instruction 91 repetitor on L//$ instruction 91 6/ "0" loops 92 repetitor on L//$ instruction 91

6/ M option o+ NUM" IC instruction 104, 147 special word 130 6orm +eed character 40 +orm propert% 186 6/ MA& method 161 option 107 6ormatting numbers +or displa% 161 numbers with & UNC 167 o+ output during tracing 122 te!t centering 157 te!t le+t justi+ication 163 te!t right justi+ication 165 te!t spacing 166 +ormword-. method 187 6ull name o+ classes 127 6ull%18uali+ied name2 o+ classes 110 6unctions numeric arguments o+ 147 return +rom 114 see Methods2 static 100 used b% classes 80

G
)l%phs 39 )roup2 #/ 82 )uard digit in arithmetic
142

H
hashCode method 184 ,e!adecimal checking with #A&A&H$" 159 conversion to binar% 169 conversion to character 169 conversion to decimal 170 digits in escapes 42 escape se8uence 41 see Conversion 159 ,e!adecimal numeric s%mbol 42, 45 ,%phen as continuation character 44

I
I6 instruction 85 IM$L"M"N&( on CLA(( instruction Implied semicolons 44 IM$/ & instruction 87 Imports automatic 88
Index 80

194

Version 2.00

e!plicit 87 Inclusive / operator see / logical operator 64 Inde+inite loops 91, 92 Indention during tracing 122 Inde! strings +or sub1values 73 testing +or 161 Inde!ed re+erences arra%s 74 in terms 48 inde!ed strings 73 Inde!ed strings 73 cop%ing 158 e!ample 25 merging 158 overview 25 testing +or 161 IN#I "C& on $ /$" &I"( instruction 176 Indirect properties 176 Ine8ualit%2 testing o+ 62 In+inite loops 91 In+luence o+ C 8 o+ 3ava 8 o+ e!! 7 IN," I&ABL" on M"&,/# instruction 99 on $ /$" &I"( instruction 112 Initiali=ing arra%s 75 Inner classes see Minor classes 127 IN(" & method 163 Inserting a string into another 163 Instance2 o+ a class 56 Instructions 77 assignment 68, 69 CLA(( 78 #/ 82 "II& 84 I6 85 IM$/ & 87 I&" A&" 89 ke%word 68, 77 L"A0" 90 L//$ 91 M"&,/# 98, 101 method call 68 N/$ 103 NUM" IC 104 /$&I/N( 106 $ACKA)" 110 $A (" 111
Version 2.00

$ /$" &I"( 112, 176 "&U N 114 (AH 115 ("L"C& 116 (I)NAL 119 & AC" 120 Integer arithmetic 140 Integer division 62, 140 de+inition 145 Integers2 binar% 149 IN&" 6AC" on CLA(( instruction 79 Inter+ace classes 79 properties in 113 Inter+aces implemented b% classes 80 Internal +unctions return +rom 114 Interpreter options 106 Introduction 7 I&" A&" instruction 89 see L//$ construct 89 use o+ variable on 89

J
3ava +eatures o+ 8 in re+erence implementation in+luence o+ 8 programming language 8 3A0A option 107 3avaBean properties 175
37

K
Ke%word instructions Ke%word sa+et% 7 Ke%words 68 mi!ed case 77
68, 77

L
LAB"L on #/ instruction 82 on L//$ instruction 95 on ("L"C& instruction 117 Language concepts 10 Language processor options 106 LA(&$/( method 163 Leading blanks removal with (& I$ method 166 Leading =eros adding with the I),& method 165 removal with (& I$ method 166 L"A0" instruction 90
Index 195

see #/ construct 90 use o+ variable on 90 L"6& method 163 Legibilit%2 perceived 10 Length o+ arra%s 52 o+ comments 40 L"N)&, method 163 special word 52, 130 Letters checking with #A&A&H$" 159 Limits o+ si=e 14 Line comments 40 Line ends2 e++ect o+ 44 Line +eed character escape se8uence 41 Line numbers2 in tracing 122 Line2 displa%ing 115 Literal patterns 135 Literal strings 41 in terms 48 see (trings 41 Literals2 binar% 150 Local variables 70 Locating a string in another string 163, 165 a word or phrase in a string 169 Logical operations 64 L/)/ option 107 L//$ instruction 91 see loops 91 Loops active 89, 90 e!ecution model 96 in binar% classes and methods 150 label 95 modi+ication o+ 89 naming o+ 95 repetitive 91, 92 see L//$ instruction 91 termination o+ 90 L/*" method 163 Lowercase checking with #A&A&H$" 159 names 44 Lowercasing strings 163

M
Mantissa o+ e!ponential numbers Matching methods 54 Mathematical method AB( 156
146

#A&A&H$" options 159 6/ MA& 161 MAI 164 MIN 164 (I)N 165 MAI method 164 Member classes see #ependent classes 128 Merging inde!ed variables 158 Method 46 argument variables 70 bod% o+ 98 calls in terms 48 charAt 184 de+inition 124 e8uals 184 +ormword-. 187 hashCode 184 names2 case o+ 44 Not"8 183 Not"8( 183 /pAdd 182 /pAnd 182 /pCc 182 /pCcblank 182 /p#iv 182 /p#ivI 182 /p"8 183 /p"8( 183 /p)t 183 /p)t"8 183 /p)t"8( 183 /p)t( 183 /pLt 183 /pLt"8 183 /pLt"8( 183 /pLt( 183 /pMinus 183 /pMult 183 /pNot 183 /p/r 183 /p$lus 183 /p$ow 183 /p em 183 /p(ub 184 /pIor 184 set#igits- e!!. 187 set6orm- e!!. 187 short name o+ 98 starting 98 toboolean 184 tob%te 184 tochar 184 todouble 184
Index Version 2.00

196

to+loat 184 toint 184 tolong 184 toshort 185 to(tring 185 Method call instructions 53, 68 M"&,/# instruction 98, 101 M"&,/# instruction see program structure 98 Method2 built1in ABB "0 156 AB( 156 B;I 156 C;# 158 C;I 158 C"N&" 157 C"N& " 157 C,AN)"(& 157 C/M$A " 157 C/$I"( 157 C/$HIN#"I"# 158 C/UN&(& 158 #;C 160 #;I 160 #A&A&H$" 159 #"L(& 160 #"L*/ # 160 "II(&( 161 6/ MA& 161 IN(" & 163 LA(&$/( 163 L"6& 163 L"N)&, 163 L/*" 163 MAI 164 MIN 164 /0" LAH 165 $/( 165 "0" (" 165 I),& 165 ("NU"NC" 165 (I)N 165 ($AC" 166 (& I$ 166 (UB(& 166 (UB*/ # 166 & AN(LA&" 167 & UNC 167 U$$" 168 0" I6H 168 */ # 168 */ #IN#"I 168 */ #L"N)&, 169 */ #$/( 169
Version 2.00

*/ #( 169 I;B 169 I;C 169 I;# 170 Methods 53 abstract 79, 99 arguments o+ 98 binar% 101 built1in 155 constant 100 constructor 56, 98 duplicate 102 +inal 100 inheritable 99 invocation o+ 53 native 100 Net e!! 155 overloading 102 overriding 55 private 99 protected 100 public 99 resolution o+ 54 return values 101 searching +or 54 shared 99 special 132 standard 99 static 100 M"&,/#( & AC" setting 120 MIN method 164 Minor classes 47, 127 constructing 127 naming o+ 127 nesting o+ 127 restrictions 129 see #ependent classes 127 Mi!ed case checking with #A&A&H$" 159 names 44 Model o+ loop e!ecution 96 Modulo see emainder operator 145 Monadic -pre+i!. operators 61 Moving characters2 with & AN(LA&" method Multiplication 62 de+inition 143

167

N
Names case o+
44

Index

197

o+ variables 69 on I&" A&" instructions 89 on L"A0" instructions 90 special

ask 130 digits 130 +orm 130 length 130 null 131 source 131 super 131 this 131 trace 132 version 132
Names2 special class 130 sourceline 131 NA&I0" on M"&,/# instruction 99 Native methods 100 Natural data t%ping 10 Negation o+ logical values 64 o+ numbers 62 Nested classes see Minor classes 127 Nesting o+ comments 40 Net e!! background 7 introduction 7 language concepts 10 language de+inition 37 objectives 7 overview 17 netre!!5lang "!ceptions 180 e!! arithmetic methods 182 e!! class 181 e!! constructors 181 e!! miscellaneous methods 184 e!!/perators class 185 e!!(et class 186 e!!(et constructors 186 e!!(et methods 187 e!!(et properties 186 netre!!5lang package 179 Newline character escape se8uence 41 N/BINA H option 106 N/C/MM"N&( option 106 N/C/M$AC& option 106 N/C/N(/L" option 107 N/C /(( "6 option 107
198

N/#"CIMAL option 107 N/#IA) option 107 N/"I$LICI& option 107 N/6/ MA& option 107 N/3A0A option 107 N/L/)/ option 107 No/therwise"!ception 180 N/$ instruction 103 N/ "$LAC" option 107 Normal comparative operators 62 N/(A0"L/) option 107 N/(/U C"#I option 107 N/(& IC&A )( option 107 N/(& IC&A((I)N option 107 N/(& IC&CA(" option 108 N/(& IC&IM$/ & option 108 N/(& IC&$ /$( option 108 N/(& IC&(I)NAL option 108 N/(HMB/L( option 108 N/& operator 64 Notation engineering 104, 147 scienti+ic 104, 147 Notations in te!t 38 s%nta! 38 NotCharacter"!ception 180 Not"8 method 183 Not"8( method 183 Nothing to declare 12 NotLogic"!ception 180 N/& AC" option 108 N/U&6@ option 108 N/0" B/(" option 109 Null character escape se8uence 41 Null clauses 68 Null instruction2 N/$ 103 NULL special word 131 Null strings 41 Null$ointer"!ception 180 Number6ormat"!ception 180 Numbers 65, 140 arithmetic on 62, 140, 142 as s%mbols 42 checking with #A&A&H$" 159 comparison o+ 62, 146 conversion to character 160, 169 conversion to he!adecimal 160 de+inition 141, 146 e!amples o+ 65 +ormatting +or displa% 161 in L//$ instruction 91 rounding 161
Index Version 2.00

see Conversion 159 truncating 167 use o+ b% Net e!! 147 Numeric part o+ a number 141, 146 NUM" IC #I)I&( 141 6/ M 147 in binar% classes and methods instruction 104 Numeric s%mbols 42, 48 Numeric s%mbols binar% 45 he!adecimal 45

150

O
/bject e!!2 programming language 8 /bject1oriented programming concepts 10 /bjectives o+ the Net e!! language 7 /bjects comparing 63 constructing 56 e8ualit% 63 overview 27 /66 & AC" setting 120 /pAdd method 182 /pAnd method 182 /pCc method 182 /pCcblank method 182 /p#iv method 182 /p#ivI method 182 /p"8 method 183 /p"8( method 183 /perators 61 arithmetic 62, 140, 142 blank 62, 64 characters used +or 43 comparative 62, 146 composition o+ 61 concatenation 62 logical 64 precedence -priorities. o+ 66 t%pe 64 /p)t method 183 /p)t"8 method 183 /p)t"8( method 183 /p)t( method 183 /pLt method 183 /pLt"8 method 183 /pLt"8( method 183 /pLt( method 183 /pMinus method 183

/pMult method 183 /pNot method 183 /p/r method 183 /p$lus method 183 /p$ow method 183 /p em method 183 /p(ub method 184 /ption words 106 /ptional arguments 99 /ptions on command line 109 /$&I/N( instruction 106 /pIor method 184 / logical e!clusive 64 logical inclusive 64 /&," *I(" clause see ("L"C& instruction 116 /ver loops 94 /0" repetitor on L//$ instruction 91 /ver+low2 arithmetic 148 /0" LAH method 165 /verla%ing a string onto another 165 /verloaded methods 102 /verriding methods 55 /verview Arithmetic 22 Arra%s 26 binar% t%pes 33 control instructions 21 conversions 33 e!ceptions 35 e!pressions 19 e!tending classes 29 inde!ed strings 25 Net e!! 17 objects 27 parsing 24 programs 18 strings 23 tracing 31 variables 19

P
$ackage 46, 110 name o+ 87, 110 netre!!5lang 179 $ACKA)" instruction $acking a string with B;I 156 with I;C 169 $arent
110

Version 2.00

Index

199

o+ dependent object 128 $A "N& special word 129 $arent class 127 $arent object 128 $arentheses adjacent to blanks 43 in e!pressions 61, 66 in method calls 48, 53 in parsing templates 138 in terms 48 omitting +rom method calls 48, 49 $A (" instruction 111 parsing rules 133 $arsing 133 absolute columns 137 de+inition 134 general rules 133, 134 introduction 133 literal patterns 135 overview 24 patterns 135 positional patterns 136 selecting words 135 variable patterns 138 $arsing templates 133 $arsing templates in $A (" instruction 111 $atterns in parsing 135 $erceived legibilit% 10 $eriod as placeholder in parsing 136 in numbers 141 in terms 48 $hilosoph% o+ Net e!! 7, 10 $/( position method 165 $ositional patterns 136 $ower operator 62 de+inition 144 $owers o+ ten in numbers 65, 146 $recedence o+ operators 66 $recision arbitrar% 10, 140 o+ arithmetic 141 $re+i! operators 61 arithmetic 143 1 62

with t%pes

64

with t%pes
Z Y
64

64 64

with t%pes
62

$rimitive t%pes 46, 149 $rimitive t%pes conversions 58 $riorities o+ operators 66 $ I0A&" on CLA(( instruction 78 on M"&,/# instruction 99 on $ /$" &I"( instruction 112 $rogram +ilename o+ 131 prolog 124 structure 124 $rogrammerXs model o+ L//$ 96 $rogramming st%le 10 $rograms 124 e!amples 25, 27, 29, 172 overview 18 structure 124 $rolog2 o+ a program 124 $roperties 46, 70, 112 case o+ names 44 constant 113 deprecated 113 +or 3avaBeans 175 in dependent classes 129 in inter+ace classes 113 in minor classes 129 indirect 176 inheritable 112 initiali=ation 124 modi+iers 113 naming 112 private 112 public 112 shared 112 static 113 transient 113 unused 113 visibilit% 112 volatile 113 $ /$" &I"( instruction 112, 176 $ropert% #"6AUL&T#I)I&( 186 #"6AUL&T6/ M 186 digits 186 "N)IN"" IN) 186 +orm 186 (CI"N&I6IC 186 $ /&"C& on #/ instruction 82 on L//$ instruction 96 on M"&,/# instruction 100

200

Index

Version 2.00

on ("L"C& instruction 117 $rotected methods 100 $UBLIC on CLA(( instruction 78 on M"&,/# instruction 99 on $ /$" &I"( instruction 112 $unctuation2 optional 10 $ure numbers 146 $ure numbers see Numbers 140

Q
8time e!ample program 172 Nuali+ied name2 o+ classes 110 Nuali+ied t%pes 46 Nuotes in strings 41

si=e o+ 61 "(UL&( & AC" setting 121 eturn character escape se8uence 41 eturn code2 setting on e!it 84 "&U N instruction 114 eturn string2 setting on e!it 84 "&U N( on M"&,/# instruction 101 "0" (" method 165 e!! arithmetic 140 class

R
aising e!ceptions 119 aising e!ceptions see (I)NAL 119 e1ordering characters with & AN(LA&" method 167 eadabilit%2 o+ programs 10 eal numbers2 binar% 149 ealit%2 dealing with 13 e+erence implementation 37 e+erences in terms 48 null 131 to arra%s 74 to current object 131 to inde!ed strings 73 to methods 53 elative column speci+ication in parsing elative positional pattern 137 eliabilit%2 o+ a language 13 emainder operator 62, 140 de+inition 145 epeating a string with C/$I"( 157 epetitive loops 92 epetitor phrase 92 "$LAC" option 107 eplacing strings using C,AN)"(& 157 using & AN(LA&" 167 e8uired arguments 99 esidue see emainder operator 145 esolution o+ methods 54 esults o+ methods 101 returned b% "&U N 114

conversions 58 methods o+ 155 Net e!! strings 46 use b% $A (" 111

+eatures o+ 7 in+luence o+ 7 e!!-boolean. constructor 181 e!!-b%te. constructor 181 e!!-char. constructor 181 e!!-charOP. constructor 181 e!!-double. constructor 181 e!!-+loat. constructor 181 e!!-int. constructor 181 e!!-long. constructor 181 e!!- e!!. constructor 181 e!!-short. constructor 181 e!!-(tring. constructor 182 e!!-(tringOP. constructor 182 e!!(et-. constructor 186 e!!(et-int2b%te. constructor 186 e!!(et-int. constructor 186 e!!(et- e!!(et. constructor 186 I),& method 165 obustness 13 ounding 140 de+inition 142 when numbers used 147 outines see Methods 53 unning o++ the end o+ a program 84

137

S
(ample programs see "!amples 172 (A0"L/) option 107 (AH instruction 115 (cienti+ic notation 104, 147 (CI"N&I6IC propert% 186
Index 201

Version 2.00

(CI"N&I6IC value +or NUM" IC 6/ M 104 (earch order +or methods 54 +or term evaluation 50 (earching a string +or a word or phrase 165, 169 (elect label 117 naming o+ 117 ("L"C& instruction 116 (emicolons 40 can be omitted 38 implied 44 ("NU"NC" method 165 set#igits- e!!. method 187 set6orm- e!!. method 187 (,A "# on CLA(( instruction 78 on M"&,/# instruction 99 on $ /$" &I"( instruction 112 (hort name o+ classes 78, 127 o+ methods 98 (I)N method 165 (I)NAL instruction 119 (ignals 152 (I)NAL( on M"&,/# instruction 101 (ignature see &%pe 46 (igni+icand o+ e!ponential numbers 146 (igni+icant digits2 in arithmetic 141 (igns in parsing templates 136 (imple #/ group 82 (imple number 42 see Numbers 140 (imple repetitor phrase 92 (imple terms 48 (ingle18uote escape se8uence 41 string delimiter 41 (i=e o+ language 14 see Length 14 (/U C" special word 131 (/U C"#I option 107 (/U C"LIN" special word 131 ($AC" method 166 (pecial characters 43 (pecial characters used +or operators 43 (pecial methods 132 super 128, 132 this 132
202

(pecial words 130 ask 130 class 130 digits 130 +orm 130 length 130 null 131 parent 129 source 131 sourceline 131 super 131 this 129, 131 trace 132 version 132 (8uare brackets in arra% initiali=ers 48, 75 in inde!ed re+erences 48 (tandard classes 79 (tandard methods 99 (&A&IC on M"&,/# instruction 99 on $ /$" &I"( instruction 113 (tatic methods 100 (tatic methods used b% classes 80 (tatic variable t%ping 70 stderr2 used b% & AC" 123 stdin2 reading with A(K 130 stdout2 writing to with (AH 115 (trict comparative operators 62 (& IC&A )( option 107 (& IC&A((I)N option 107 (& IC&CA(" option 108 (& IC&IM$/ & option 108 (& IC&$ /$( option 108 (& IC&(I)NAL option 108 (trings 41 as literal constants 41 comparison o+ 62 concatenation o+ 62 escapes in 41 in terms 48 inde!ed 73 length o+ 163 lowercasing 163 moving with & AN(LA&" method null 41 overview 23 8uotes in 41 sub1values o+ 73 t%pes o+ 59 uppercasing 168 veri+%ing contents o+ 168 (& I$ method 166
Index

167

Version 2.00

(trong t%ping 10 (tructured programming concepts 10 (tub2 o+ term 48 (t%le2 programming 10 (ub1e!pressions2 in terms 48 (ub1ke%words 77 (ub1string2 e!tracting 166 (ub1values2 o+ strings 73 (ubclass o+ a class 80 (ubroutines calling 53 passing back values +rom 114 return +rom 114 (ubstitution in e!pressions 61 (UB(& method 166 (ubtraction 62 de+inition 143 (UB*/ # method 166 (U$" special method 128, 132 special word 131 (uperclass o+ a class 80 (%mbol characters checking with #A&A&H$" 159 (%mbolic manipulation 11 (%mbols 42 assigning values to 69 case o+ 44 in terms 48 numeric 42, 48 use o+ 69 valid names 42 (HMB/L( option 108 (%ntactic units 12 (%nta! checking see & AC" instruction 120 (%nta! diagrams notation +or 38 (%nta! notation 38 (%stem independence 12 (%stem1dependent options 106

T
&ab character 40 escape se8uence 41 &abulation character 40 &emplates2 parsing 133 general rules 133 in $A (" instruction 111 &en2 powers o+ 146 &erminal2 writing to with (AH 115 &erms 48, 61

compound 48 evaluation o+ 49 in assignments 71 on le+t o+ W 71 parsing o+ 111 simple 48 stub o+ 48 &esting +or inde!ed variables 161 &e!t +ormatting see 6ormatting 155 see *ords 155 &,"N +ollowing I6 clause 85 +ollowing *,"N clause 116 &,I( special method 132 special word 129, 131 &hread tracing 123 &/ phrase o+ L//$ instruction 91 toboolean method 184 tob%te method 184 tochar method 184 todouble method 184 to+loat method 184 toint method 184 &okens 41 tolong method 184 &ools2 reliabilit% o+ 13 toshort method 185 to(tring method 185 &race conte!t 123 & AC" instruction 120 option 108 special word 132 &race setting 120 &race setting altering with & AC" instruction 120 &racing clauses 120 data identi+iers 122 e!ecution o+ programs 120 line numbers 122 overview 31 variables 121 &railing blanks removal with (& I$ method 166 &railing =eros 143 & AN(I"N& on $ /$" &I"( instruction 113 & AN(LA&" method 167 &ranslation
Index 203

Version 2.00

see Case translation 167 with & AN(LA&" method &rapping o+ e!ceptions 119 &rapping o+ e!ceptions see (I)NAL 119 &rue value 64 & UNC method 167 &runcating numbers 167 &%pes 46 checking instances o+ 64 checking with #A&A&H$" concatenation o+ 64 conversions 58 declaring 70 dimensioned 46 o+ terms 61 o+ values 61 operations on 64 primitive 46, 149 8uali+ied 46 simpli+ication 58 &%ping -printing. data see (AH instruction 115

167

159

U
Under+low2 arithmetic 148 Underscore in s%mbols 42 Unicode coded character set 39 escape se8uence 41 U&61@ encoding 108 Unpacking a string with C;I 158 with I;B 169 UN&IL phrase o+ L//$ instruction 91 UNU("# on $ /$" &I"( instruction 113 U$$" method 168 Uppercase checking with #A&A&H$" 159 names 44 Uppercasing strings 168 U("( on CLA(( instruction 80 U&61@ encoding 108 U&6@ option 108 Utilit% methods 155

controlling loops 92 in parsing patterns 138 inde!ed 73 local 70 method arguments 70 names o+ 69 overview 19 parsing o+ 111 properties 70 scope o+ 70 setting new value 69 static t%ping o+ 70 subscripts 73 t%pe o+ 69 valid names 69 visibilit% 70 0" B/(" option 109 0" B/("n option 109 0" I6H method 168 0" (I/N special word 132 0isibilit% o+ classes 78 o+ methods 99 o+ properties 112 0/LA&IL" on $ /$" &I"( instruction

113

W
*ell1known conversions 58 *,"N clause see ("L"C& instruction 116 *,IL" phrase o+ L//$ instruction 91 *hite space 40 *hole numbers 65 checking with #A&A&H$" 159 de+inition 147 */ # method 168 *ord processing see 6ormatting 155 see *ords 155 */ #IN#"I method 168 */ #L"N)&, method 169 */ #$/( method 169 *ords counting2 using */ #( 169 deleting +rom a string 160 e!tracting +rom a string 166, 168 +inding in a string 169 +inding length o+ 169 in parsing 135 locating in a string 168 special

V
0ariable re+erence in parsing template 0ariables 69
204 138

ask
Index

130

Version 2.00

digits 130 +orm 130 length 130 null 131 source 131 super 131 this 131 trace 132 version 132
*/ #( method 169 *ords2 special class 130 sourceline 131

/
M division operator 62, 143 M[ block comment delimiter 40 MM remainder operator 62, 145

\
Z backslash escape character 41 not operator 64 ZZ invalid se8uence 43 Z\ not less than operator 63 Z\\ strictl% not less than operator 63 ZW not e8ual operator 63 ZWW strictl% not e8ual operator 63 Z] not greater than operator 63 Z]] strictl% not greater than operator 63

X
I;B method 169 I;C method 169 I;# method 170 I/ 2 logical operator
64

&
K and operator 64 KK e!clusive or operator
64

Z
Sero character escape se8uence 41 Seros adding on the le+t 165 padding 165 removal with (& I$ method

%
^ integer division operator
62, 145

+
166

_
T underscore in s%mbols
42

Y plus sign addition operator 62, 143 in parsing template 137 YY invalid se8uence 43 YYY tracing +lag 122

1 continuation character 44 1 minus sign in parsing template 137 subtraction operator 62, 143 11 line comment delimiter 40

<
\ less than operator 63 \\ strictl% less than operator 63 \\W strictl% less than or e8ual operator 63 \W less than or e8ual operator 63 on t%pes 65 \] less than or greater than operator 63

.
5 -period. as placeholder in parsing in numbers 141 in terms 48
136

=
W e8uals sign assignment indicator 69 e8ual operator 63 in L//$ instruction 91 in parsing template 137 WW strictl% e8ual operator 63

*
[ multiplication operator 62, 143 [1[ tracing +lag 122 [[ power operator 62, 144 [M block comment delimiter 40 [W[ tracing +lag 122

>
] greater than operator 63 ]\ greater than or less than operator 63 ]W greater than or e8ual operator 63 on t%pes 65
Index 205

Version 2.00

]] strictl% greater than operator 63 ]]W strictl% greater than or e8ual operator ]]] tracing +lag 122 ]a] tracing +lag 122 ]p] tracing +lag 122 ]v] tracing +lag 122

63

|
_ or operator 64 __ concatenation operator
62, 64

$
U dollar sign in s%mbols
42

206

Index

Version 2.00