regina rexx v3.7 - user manual

8/11/2019 Regina REXX v3.7 - User Manual

1/262

The Regina Rexx InterpreterVersion 3.7

Mark Hessling

Florian Groe-Coosmann

5 September, 2012

Original Author: Anders Christensen

egina !ome "age at:http:##regina$re%%.sour&e'orge.net

1
mailto:[email protected]:[email protected]://regina-rexx.sourceforge.net/http://regina-rexx.sourceforge.net/mailto:[email protected]://regina-rexx.sourceforge.net/mailto:[email protected]


2/262

Cop(right ) 1**2$1**+ Anders Christensen

Cop(right ) 1**+$2012 ar- !essling

"ermission is granted to &op(, distribute and#or modi'( this do&ument under the terms o' the /

ree o&umentation 3i&ense, 4ersion 1.1 or an( later ersion published b( the ree So't6are

oundation7 6ith no 8nariant Se&tions, 6ith no ront$Coer 9e%ts, and 6ith no a&-$Coer 9e%ts.

A &op( o' the li&ense is in&luded in the se&tion entitled ;/ ree o&umentation 3i&ense;.

2


3/262

Table of Contents1 8ntrodu&tion to egina...................................................................................................................1

1.1 "urpose o' this do&ument.......................................................................................................1

1.2 8mplementation......................................................................................................................1

1.= "orts o' egina.......................................................................................................................15

1. %e&uting e%% programs 6ith egina.................................................................................15

1..1 S6it&hes.........................................................................................................................1?1..2 %ternal e%% programs.................................................................................................1

2 e%% 3anguage Constru&ts............................................................................................................20

2.1 e'initions.............................................................................................................................20

2.2 /ull &lauses............................................................................................................................21

2.= Commands.............................................................................................................................2=

2.=.1 Assignments...................................................................................................................2=

2. 8nstru&tions.............................................................................................................................2

2..1 9he ASS 8nstru&tion............................................................................................2?

2..2 9he A 8nstru&tion......................................................................................................==

2..= 9he CA33 8nstru&tion....................................................................................................=

2.. 9he O#/ 8nstru&tion...............................................................................................=

2..5 9he O" 8nstru&tion....................................................................................................0

2..? 9he 89 8nstru&tion.....................................................................................................2

2.. 9he 8#9!/#3S 8nstru&tion....................................................................................=

2..+ 9he 8/9"9 8nstru&tion.........................................................................................=

2..* 9he 89A9 8nstru&tion..............................................................................................5

2..10 9he 3A4 8nstru&tion................................................................................................?

2..11 9he /O" 8nstru&tion.....................................................................................................?

2..12 9he /8C 8nstru&tion..........................................................................................

2..1= 9he O"98O/S 8nstru&tion...........................................................................................+

2..1 9he "AS 8nstru&tion................................................................................................*2..15 9he "OC 8nstru&tion....................................................................................52

2..1? 9he "33 8nstru&tion..................................................................................................55

2..1 9he "S! 8nstru&tion..................................................................................................55

2..1+ 9he B 8nstru&tion...............................................................................................55

2..1* 9he 9/ 8nstru&tion............................................................................................55

2..20 9he SA 8nstru&tion.....................................................................................................5

2..21 9he S3C9#D!/#O9!D8S 8nstru&tion........................................................5

2..22 9he S8/A3 8nstru&tion..............................................................................................5+

2..2= 9he 9AC 8nstru&tion...............................................................................................?1

2..2 9he "" 8nstru&tion................................................................................................?=

2.5 Operators................................................................................................................................?=2.5.1 Arithmeti& Operators......................................................................................................?=

2.5.2 Assignment Operators....................................................................................................?=

2.5.= Con&atenation Operators................................................................................................?=

2.5. Comparatie Operators..................................................................................................?

2.5.5 3ogi&al Operators...........................................................................................................?

2.? Spe&ial 4ariables....................................................................................................................?5

2.?.1 3o&al S&ope E ser Driteable........................................................................................?5

C $ FA/S8G.............................................................................................................................?5

C $ FA/S8G........................................................................................................................?5

S39 $ FA/S8G....................................................................................................................?5

S39 $ FA/S8G...............................................................................................................?5

3


4/262

S83 $ FA/S8G..........................................................................................................................?5

S83 $ FA/S8G.....................................................................................................................?5

2.?.2 lobal S&ope E ead$Onl(.............................................................................................?5

./ $ FA/S8G...........................................................................................................................?5

./ $ FA/S8G......................................................................................................................?5

.C $ FA/S8G............................................................................................................................?5

.C $ FA/S8G.......................................................................................................................?5.S $ FA/S8G.............................................................................................................................?5

.S $ FA/S8G........................................................................................................................?5

.S39 $ FA/S8G...................................................................................................................?5

.S39 $ FA/S8G..............................................................................................................?5

.38/ $ FeginaG......................................................................................................................?5

.38/ $ FeginaG..................................................................................................................?5

./O38/ $ FeginaG.........................................................................................................?5

./O38/ $ FeginaG....................................................................................................?5

2. 8mplementation$Spe&i'i& 8n'ormation....................................................................................??

2..1 is&ellaneous.................................................................................................................??

2..2 8mplementation o' the ASS enironment............................................................??= e%% uilt$in un&tions.................................................................................................................0

=.1 eneral 8n'ormation...............................................................................................................0

=.1.1 9he S(nta% ormat.........................................................................................................0

=.1.2 "re&ision and /ormaliHation..........................................................................................1

=.1.= Standard "arameter /ames............................................................................................1

=.1. rror essages...............................................................................................................2

=.1.5 "ossible S(stem ependen&ies......................................................................................2

=.1.? lan-s s. Spa&es...........................................................................................................

=.2 egina uilt$in un&tions......................................................................................................5

A4Flong, short I,lengthJG $ FA/S8G................................................................................5

A4Flong, short I,lengthJG $ FA/S8G...........................................................................5

ASFnumberG $ FA/S8G............................................................................................................5

ASFnumberG $ FA/S8G.......................................................................................................5

ASSFIoptionJG $ FA/S8G.................................................................................................5

ASSFIoptionJG $ FA/S8G............................................................................................5

AFIargno I,optionJJG $ FA/S8G.............................................................................................?

AFIargno I,optionJJG $ FA/S8G........................................................................................?

2CFbinstringG $ FAG......................................................................................................

2CFbinstringG $ FAG.................................................................................................

2FbinstringG $ FA/S8G..........................................................................................................

2FbinstringG $ FA/S8G....................................................................................................."F'reKuen&( I,durationJG $ FOS#2G.....................................................................................+

"F'reKuen&( I,durationJG $ FOS#2G................................................................................+

89A/Fstring1 I,Istring2J I,pad&harJJG $ FA/S8G..................................................................+

89A/Fstring1 I,Istring2J I,pad&harJJG $ FA/S8G.............................................................+

89C!Fstring, bitG $ FAG.............................................................................................+

89C!Fstring, bitG $ FAG........................................................................................+

89C3Fstring, bitG $ FAG..............................................................................................+

89C3Fstring, bitG $ FAG.........................................................................................+

89CO"Fstring1, string2, bit I,padJG $ FAG.................................................................*

89CO"Fstring1, string2, bit I,padJG $ FAG............................................................*

89OFstring1 I, Istring2J I,pad&harJJG $ FA/S8G....................................................................*

4


5/262

89OFstring1 I, Istring2J I,pad&harJJG $ FA/S8G...............................................................*

89S9Fstring, bitG $ FAG..............................................................................................*

89S9Fstring, bitG $ FAG..........................................................................................*

899S9Fstring, bitG $ FAG..............................................................................................*

899S9Fstring, bitG $ FAG..........................................................................................*

89OFstring1I, Istring2J I,pad&harJJG $ FA/S8G..................................................................*

89OFstring1I, Istring2J I,pad&harJJG $ FA/S8G.............................................................*9"FG $ FCSG...............................................................................................................+0

9"FG $ FCSG..........................................................................................................+0

C2FstringG $ FAG...........................................................................................................+0

C2FstringG $ FAG......................................................................................................+0

C2Fstring I,lengthJG $ FA/S8G................................................................................................+0

C2Fstring I,lengthJG $ FA/S8G............................................................................................+0

C2FstringG $ FA/S8G...............................................................................................................+1

C2FstringG $ FA/S8G..........................................................................................................+1

CFdire&tor(G $ F8/AG......................................................................................................+1

CFdire&tor(G $ F8/AG.................................................................................................+1

C!8Fdire&tor(G $ F8/AG...............................................................................................+1C!8Fdire&tor(G $ F8/AG..........................................................................................+1

C/9Fstring, length I, pad&har J G $ FA/S8G.......................................................................+1

C/9Fstring, length I, pad&har J G $ FA/S8G..................................................................+1

C/9Fstring, length I, pad&har J G $ FA/S8G.......................................................................+1

C/9Fstring, length I, pad&har J G $ FA/S8G..................................................................+1

C!A/S9Fneedle, ha(sta&-, ne6needle G $ FA/S8G.........................................................+2

C!A/S9Fneedle, ha(sta&-, ne6needle G $ FA/S8G.....................................................+2

C!A8/FIstreamidJ I,IstartJ I,lengthJJG $ FA/S8G...................................................................+2

C!A8/FIstreamidJ I,IstartJ I,lengthJJG $ FA/S8G..............................................................+2

C!AO9FIstreamidJ I,IstringJ I,startJJG $ FA/S8G................................................................+=

C!AO9FIstreamidJ I,IstringJ I,startJJG $ FA/S8G...........................................................+=

C!ASFIstreamidJG $ FA/S8G..................................................................................................+=

C!ASFIstreamidJG $ FA/S8G.............................................................................................+=

C3OSF'ileG $ FAG.........................................................................................................+

C3OSF'ileG $ FAG.....................................................................................................+

CO"AFstring1, string2 I,pad&harJG $ FA/S8G...................................................................+

CO"AFstring1, string2 I,pad&harJG $ FA/S8G...............................................................+

CO"SSFstring I,listJG $ FAG....................................................................................+

CO"SSFstring I,listJG $ FAG...............................................................................+

CO/898O/FIoptionJG $ FA/S8G.............................................................................................+

CO/898O/FIoptionJG $ FA/S8G........................................................................................+CO"8SFstring, &opiesG $ FA/S8G.............................................................................................+5

CO"8SFstring, &opiesG $ FA/S8G........................................................................................+5

CO/9S9Fneedle, ha(sta&-G $ FA/S8G................................................................................+5

CO/9S9Fneedle, ha(sta&-G $ FA/S8G...........................................................................+5

C"9Fstring, saltG $ F8/AG.............................................................................................+5

C"9Fstring, saltG $ F8/AG........................................................................................+5

A9A9"Fstring I,optionJG $ FA/S8G....................................................................................+?

A9A9"Fstring I,optionJG $ FA/S8G...............................................................................+?

A9FIoptionLout I,date I,optionLinJJJG $ FA/S8G..................................................................+

A9FIoptionLout I,date I,optionLinJJJG $ FA/S8G.............................................................+

3S9Fstring, start I,lengthJG $ FA/S8G................................................................................+*

5


6/262

3S9Fstring, start I,lengthJG $ FA/S8G...........................................................................+*

3DOFstring,startI,lengthJG FA/S8G................................................................................+*

3DOFstring,startI,lengthJG FA/S8G...........................................................................+*

SFG $ FCSG.................................................................................................................*0

SFG $ FCSG.............................................................................................................*0

889SFG $ FA/S8G...................................................................................................................*0

889SFG $ FA/S8G..............................................................................................................*08C9OFIne6 dire&tor(JG $ FOS#2G.................................................................................*0

8C9OFIne6 dire&tor(JG $ FOS#2G.............................................................................*0

2CFinteger I,lengthJG $ FA/S8G..............................................................................................*0

2CFinteger I,lengthJG $ FA/S8G..........................................................................................*0

2Finteger I,lengthJG $ FA/S8G..............................................................................................*1

2Finteger I,lengthJG $ FA/S8G.........................................................................................*1

O"FInumberJG $ FCSG...............................................................................................*1

O"FInumberJG $ FCSG...........................................................................................*1

OF'ileG $ FAG..............................................................................................................*2

OF'ileG $ FAG..........................................................................................................*2

O99Ferrorno I, langJG $ FA/S8G................................................................................*2O99Ferrorno I, langJG $ FA/S8G...........................................................................*2

8S9SF'ilenameG $ FAG................................................................................................*=

8S9SF'ilenameG $ FAG...........................................................................................*=

"O9Faddress, IstringJ, IlengthJ I,padJG $ FAG.........................................................*=

"O9Faddress, IstringJ, IlengthJ I,padJG $ FAG....................................................*=

83S"CFoption, 'ilespe&G $ FOS#2G......................................................................................*

83S"CFoption, 'ilespe&G $ FOS#2G.................................................................................*

8/Fstring, phraseG $ FCSG..................................................................................................*

8/Fstring, phraseG $ FCSG.............................................................................................*

OMFG $ F8/AG...............................................................................................................*

OMFG $ F8/AG...........................................................................................................*

OFG $ FA/S8G....................................................................................................................*

OFG $ FA/S8G................................................................................................................*

OA9Fnumber I,Ibe'oreJ I,Ia'terJ I,Ie%ppJ I,Ie%ptJJJJJG $ FA/S8G......................................*5

OA9Fnumber I,Ibe'oreJ I,Ia'terJ I,Ie%ppJ I,Ie%ptJJJJJG $ FA/S8G.................................*5

S"ACFaddress, lengthG $ FAG.............................................................................*?

S"ACFaddress, lengthG $ FAG.........................................................................*?

NNFG $ FA/S8G......................................................................................................................*?

NNFG $ FA/S8G.................................................................................................................*?

9CA33S9ACMFstemG $ F8/AG...................................................................................*?

9CA33S9ACMFstemG $ F8/AG...............................................................................*?9/4FenironmentarG $ F8/AG.................................................................................*?

9/4FenironmentarG $ F8/AG............................................................................*?

9"8FG $ F8/AG............................................................................................................*?

9"8FG $ F8/AG.......................................................................................................*?

9S"ACFlengthG $ FAG.............................................................................................*

9S"ACFlengthG $ FAG.........................................................................................*

998FG $ F8/AG............................................................................................................*

998FG $ F8/AG.......................................................................................................*

!AS!FstringG $ FAG.......................................................................................................*

!AS!FstringG $ FAG...................................................................................................*

8"O9Faddress I,lengthJG $ FAG..................................................................................*

6


7/262

8"O9Faddress I,lengthJG $ FAG.............................................................................*

8/Fha(sta&-, needle I,startJG $ FCSG..............................................................................*

8/Fha(sta&-, needle I,startJG $ FCSG..........................................................................*

8/S9Fstring1, string2 I,position I,length I,pad&harJJJG $ FA/S8G........................................*

8/S9Fstring1, string2 I,position I,length I,pad&harJJJG $ FA/S8G....................................*

S98Fstring, length I,padJG $ FCSG..................................................................................*+

S98Fstring, length I,padJG $ FCSG.............................................................................*+3AS9"OSFneedle, ha(sta&- I,startJG $ FA/S8G........................................................................*+

3AS9"OSFneedle, ha(sta&- I,startJG $ FA/S8G....................................................................*+

39Fstring, length I,pad&harJG $ FA/S8G................................................................................*+

39Fstring, length I,pad&harJG $ FA/S8G...........................................................................*+

3/9!FstringG $ FA/S8G.......................................................................................................**

3/9!FstringG $ FA/S8G..................................................................................................**

38/8/FIstreamidJI,IlineJI,&ountJJG FA/S8G...........................................................................**

38/8/FIstreamidJI,IlineJI,&ountJJG FA/S8G.......................................................................**

38/O9FIstreamidJ I,IstringJ I,lineJJG $ FA/S8G.................................................................100

38/O9FIstreamidJ I,IstringJ I,lineJJG $ FA/S8G............................................................100

38/SFIstreamidJ I,optionJG $ FA/S8G...................................................................................10138/SFIstreamidJ I,optionJG $ FA/S8G..............................................................................101

3ODFstring I,start I,length I,padJJJG $ F8/AG............................................................101

3ODFstring I,start I,length I,padJJJG $ F8/AG.......................................................101

AMFG $ FCSG...........................................................................................................102

AMFG $ FCSG......................................................................................................102

AFnumber1 I,number2J ...G $ FA/S8G...............................................................................102

AFnumber1 I,number2J ...G $ FA/S8G...........................................................................102

8/Fnumber I,numberJ ...G $ FA/S8G.....................................................................................102

8/Fnumber I,numberJ ...G $ FA/S8G................................................................................102

O"/F'ile, 'ilename, IPAppendPQPeadPQPDritePJG $ FAG.................................................10=

O"/F'ile, 'ilename, IPAppendPQPeadPQPDritePJG $ FAG............................................10=

O43AFstring1, string2 I,IstartJ I,IlengthJ I,pad&harJJJG $ FA/S8G..................................10=

O43AFstring1, string2 I,IstartJ I,IlengthJ I,pad&harJJJG $ FA/S8G.............................10=

"OO38FG $ F8/AG.........................................................................................................10=

"OO38FG $ F8/AG.....................................................................................................10=

"O"/F&ommand I,stem.JG $ F8/AG..............................................................................10

"O"/F&ommand I,stem.JG $ F8/AG..........................................................................10

"OSFneedle, ha(sta&- I,startJG $ FA/S8G................................................................................10

"OSFneedle, ha(sta&- I,startJG $ FA/S8G............................................................................10

"9/4FenironmentarRIalueJG $ F8/AG.................................................................10

"9/4FenironmentarRIalueJG $ F8/AG.............................................................10BA38FIstreamidJG $ FA/S8G............................................................................................10

BA38FIstreamidJG $ FA/S8G.......................................................................................10

BFG $ FA/S8G.............................................................................................................10

BFG $ FA/S8G.........................................................................................................10

A/OFma%G $ FA/S8G.....................................................................................................105

A/OFma%G $ FA/S8G................................................................................................105

A/OFIminJ I,Ima%J I,seedJJG $ FA/S8G.........................................................................105

A/OFIminJ I,Ima%J I,seedJJG $ FA/S8G....................................................................105

A/FIseedJG $ FAG.................................................................................................10?

A/FIseedJG $ FAG.............................................................................................10?

AC!F'ile, lengthG $ FAG........................................................................................10?

7


8/262

AC!F'ile, lengthG $ FAG...................................................................................10?

A3/F'ileG $ FAG....................................................................................................10?

A3/F'ileG $ FAG...............................................................................................10?

4SFstringG $ FA/S8G...................................................................................................10?

4SFstringG $ FA/S8G..............................................................................................10?

8!9Fstring, lengthI,pad&harJG $ FA/S8G............................................................................10?

8!9Fstring, lengthI,pad&harJG $ FA/S8G.......................................................................10?/CAFe%ternalname, librar(, internalnameG $ FSAAG.............................................10

/CAFe%ternalname, librar(, internalnameG $ FSAAG.........................................10

/CO"Fe%ternalnameG $ FSAAG...............................................................................10

/CO"Fe%ternalnameG $ FSAAG..........................................................................10

/CSFG $ F8/AG.......................................................................................10

/CSFG $ F8/AG...................................................................................10

/CBFe%ternalnameG $ FSAAG............................................................................10

/CBFe%ternalnameG $ FSAAG.......................................................................10

BF&ommand I,KueueQtimeoutJG $ FOS#2G.................................................................10

BF&ommand I,KueueQtimeoutJG $ FOS#2G............................................................10

SMF'ile, o''set, IPeginPQPCurrentPQPndPG $ FAG.........................................................10+SMF'ile, o''set, IPeginPQPCurrentPQPndPG $ FAG.....................................................10+

S!ODFoption, InameJ, IpadJG $ FAG............................................................................10+

S!ODFoption, InameJ, IpadJG $ FAG.......................................................................10+

S8/FnumberG $ FA/S8G........................................................................................................10*

S8/FnumberG $ FA/S8G...................................................................................................10*

S3"Fse&ondsG $ FCSG......................................................................................................10*

S3"Fse&ondsG $ FCSG.................................................................................................10*

SOC38/FIlinenoJG $ FA/S8G........................................................................................10*

SOC38/FIlinenoJG $ FA/S8G...................................................................................10*

S"ACFstringI, IlengthJ I,pad&harJJG $ FA/S8G......................................................................10*

S"ACFstringI, IlengthJ I,pad&harJJG $ FA/S8G.................................................................10*

S9A9FstreamidG $ FCSG.....................................................................................................110

S9A9FstreamidG $ FCSG.................................................................................................110

S9OAFIaddressJ, IstringJ, IlengthJ, IpadJG $ FAG..................................................110

S9OAFIaddressJ, IstringJ, IlengthJ, IpadJG $ FAG.............................................110

S9AFstreamidI,optionI,&ommandJJG FA/S8G.................................................................110

S9AFstreamidI,optionI,&ommandJJG FA/S8G............................................................110

S98"Fstring I,IoptionJ I,&harJJG $ FA/S8G.............................................................................11

S98"Fstring I,IoptionJ I,&harJJG $ FA/S8G........................................................................11

SS9Fstring, start I,length I,pad&harJJG $ FA/S8G.............................................................115

SS9Fstring, start I,length I,pad&harJJG $ FA/S8G........................................................115SDOFstring, start I,lengthJG $ FA/S8G.........................................................................115

SDOFstring, start I,lengthJG $ FA/S8G.....................................................................115

SO3FstringG $ FA/S8G....................................................................................................115

SO3FstringG $ FA/S8G...............................................................................................115

98FIoptionLout I,time IoptionLinJJJG $ FA/S8G.................................................................11?

98FIoptionLout I,time IoptionLinJJJG $ FA/S8G.............................................................11?

9ACFIsettingJG $ FA/S8G....................................................................................................11

9ACFIsettingJG $ FA/S8G...............................................................................................11

9A/S3A9Fstring I,ItableoutJ I,ItableinJ I,pad&harJJJG $ FA/S8G......................................11+

9A/S3A9Fstring I,ItableoutJ I,ItableinJ I,pad&harJJJG $ FA/S8G.................................11+

98FstringG $ FAG......................................................................................................11+

8


9/262

98FstringG $ FAG..................................................................................................11+

9/CFnumber I,lengthJG $ FA/S8G......................................................................................11+

9/CFnumber I,lengthJG $ FA/S8G.................................................................................11+

/AFIoptionJG $ F8/AG.............................................................................................11*

/AFIoptionJG $ F8/AG........................................................................................11*

/8OFerrornoG $ F8/AG.....................................................................................11*

/8OFerrornoG $ F8/AG................................................................................11*""Fstring I,start I,length I,padJJJG E FA#8/AG..............................................120

""Fstring I,start I,length I,padJJJG E FA#8/AG.........................................120

S8FG $ F8/AG..........................................................................................................120

S8FG $ F8/AG.....................................................................................................120

4A3Fs(mbol I,IalueJ, IpoolJJG $ FA/S8G.........................................................................120

4A3Fs(mbol I,IalueJ, IpoolJJG $ FA/S8G.....................................................................120

48Fstring, re' I,IoptionJ I,startJJG $ FA/S8G...................................................................121

48Fstring, re' I,IoptionJ I,startJJG $ FA/S8G..............................................................121

DOFstring, 6ordnoG $ FA/S8G..........................................................................................122

DOFstring, 6ordnoG $ FA/S8G......................................................................................122

DO8/Fstring, 6ordnoG $ FA/S8G..............................................................................122DO8/Fstring, 6ordnoG $ FA/S8G.........................................................................122

DO3/9!Fstring, 6ordnoG $ FA/S8G..........................................................................122

DO3/9!Fstring, 6ordnoG $ FA/S8G......................................................................122

DO"OSFphrase, string I,startJG $ FA/S8G.........................................................................122

DO"OSFphrase, string I,startJG $ FA/S8G....................................................................122

DOSFstringG $ FA/S8G......................................................................................................12=

DOSFstringG $ FA/S8G..................................................................................................12=

D89C!F'ile, stringG $ FAG.......................................................................................12=

D89C!F'ile, stringG $ FAG..................................................................................12=

D893/F'ile, stringG $ FAG.......................................................................................12=

D893/F'ile, stringG $ FAG..................................................................................12=

A/FIstartJ I,endJG $ FA/S8G.........................................................................................12=

A/FIstartJ I,endJG $ FA/S8G....................................................................................12=

2Fhe%stringG $ FA/S8G.......................................................................................................12=

2Fhe%stringG $ FA/S8G...................................................................................................12=

2CFhe%stringG $ FA/S8G.......................................................................................................12=

2CFhe%stringG $ FA/S8G...................................................................................................12=

2Fhe%string I,lengthJG $ FA/S8G........................................................................................12

2Fhe%string I,lengthJG $ FA/S8G....................................................................................12

=.= 8mplementation spe&i'i& do&umentation 'or egina............................................................125

=.=.1 eiations 'rom the Standard.......................................................................................125=.=.2 8nterpreter 8nternal ebugging un&tions....................................................................125

A33OCA9FIoptionJG.........................................................................................................125

A33OCA9FIoptionJG....................................................................................................125

"9FG........................................................................................................................12?

"9FG...................................................................................................................12?

"4ASFG.......................................................................................................................12?

"4ASFG...................................................................................................................12?

38S93AMFG.....................................................................................................................12?

38S93AMFG................................................................................................................12?

9ACACMFG.....................................................................................................................12?

9ACACMFG................................................................................................................12?

9


10/262

=.=.= e%% 4S 8nter'a&e un&tions....................................................................................12

=. e%%til 'or egina.............................................................................................................12*

Conditions....................................................................................................................................1=0

.1 Dhat are Conditions............................................................................................................1=0

.1.1 Dhat o De /eed Conditions 'or..............................................................................1=0

.1.2 9erminolog(.................................................................................................................1=0

.2 9he (thi&al Standard Condition........................................................................................1=1.2.1 8n'ormation egarding Conditions Fdata stru&turesG....................................................1=1

.2.2 !o6 to Set up a Condition 9rap...................................................................................1=2

.2.= !o6 to aise a Condition............................................................................................1==

.2. !o6 to 9rigger a Condition 9rap.................................................................................1=5

.2.5 9rapping b( ethod S8/A3.....................................................................................1=5

.2.? 9rapping b( ethod CA33.........................................................................................1=?

.2. 9he Current 9rapped Condition...................................................................................1=

.= 9he eal Conditions............................................................................................................1=+

.=.1 9he S/9A &ondition...............................................................................................1=+

.=.2 9he !A39 &ondition....................................................................................................1=*

.=.= 9he O &ondition.................................................................................................1=*.=. 9he A83 &ondition..............................................................................................10

.=.5 9he /O4A3 &ondition............................................................................................10

.=.? 9he /O9A &ondition.........................................................................................11

.=. 9he 3OS9889S &ondition.......................................................................................11

. urther /otes on Conditions................................................................................................12

..1 Conditions under 3anguage 3eel =.50.......................................................................12

..2 "it'alls 6hen sing Condition 9raps...........................................................................12

..= 9he Corre&tness o' this es&ription.............................................................................12

.5 Conditions in egina...........................................................................................................1=

.5.1 !o6 to aise the !A39 &ondition...............................................................................1=

.? "ossible uture e%tensions...................................................................................................1

5 Stream 8nput and Output..............................................................................................................15

5.1 a&-ground and !istori&al emar-s...................................................................................15

5.2 e%%Ps /otion o' a Stream...................................................................................................15

5.= Short Crash$Course..............................................................................................................1?

5. /aming Streams...................................................................................................................1

5.5 "ersistent and 9ransient Streams.........................................................................................150

5.? Opening a Stream.................................................................................................................151

5. Closing a Stream..................................................................................................................152

5.+ Chara&ter$6ise and 3ine$6ise 8#O.......................................................................................152

5.* eading and Driting............................................................................................................155.10 etermining the Current "osition......................................................................................15?

5.11 "ositioning Dithin a ile....................................................................................................15

5.12 rrors: is&oer(, !andling, and e&oer(......................................................................1?0

5.1= Common i''eren&es and "roblems 6ith Stream 8#O.......................................................1?1

5.1=.1 Dhere 8mplementations are Allo6ed to i''er..........................................................1?1

5.1=.2 Dhere 8mplementations might i''er an(6a(...........................................................1?2

5.1=.= 38/SFG and C!ASFG are 8na&&urate......................................................................1?2

5.1=. 9he 3ast 3ine o' a Stream..........................................................................................1?

5.1=.5 Other "arts o' the 8#O S(stem....................................................................................1?

5.1=.? 8mplementation$Spe&i'i& 8n'ormation........................................................................1?5

5.1=. Stream 8#O in egina 0.0a........................................................................................1?5

10


11/262

5.1=.+ un&tionalit( to be 8mplemented 3ater......................................................................1?+

5.1=.* Stream 8#O in Ae%% 1.15..........................................................................................1?+

5.1=.10 ain i''eren&es 'rom Standard e%%....................................................................12

5.1=.11 Stream 8#O in e%% 1.0b........................................................................................1

5.1=.12 "roblems 6ith inar( and 9e%t odes....................................................................1+

? %tensions....................................................................................................................................1+0

?.1 Dh( !ae %tensions..........................................................................................................1+0?.2 %tensions and Standard e%%............................................................................................1+0

?.= Spe&i'(ing %tensions in egina.........................................................................................1+0

?. 9he 9rouble egins..............................................................................................................1+1

?.5 9he ormat o' the O"98O/S &lause....................................................................................1+1

?.? 9he undamental %tensions...............................................................................................1+2

?. eta$e%tensions...................................................................................................................1+5

?.+ Semi$standards.....................................................................................................................1+?

?.* Standards..............................................................................................................................1+?

9he Sta&-.....................................................................................................................................1++

.1 a&-ground and histor(.......................................................................................................1++

.2 eneral 'un&tionalit( o' the sta&-........................................................................................1++.2.1 asi& 'un&tionalit(.......................................................................................................1++

.2.2 38O and 8O sta&- operations..................................................................................1*0

.2.= sing multiple bu''ers in the sta&-..............................................................................1*1

.2. 9he Heroth bu''er..........................................................................................................1*2

.2.5 Creating ne6 sta&-s......................................................................................................1*=

.= 9he inter'a&e bet6een e%% and the sta&-...........................................................................1*

. Strategies 'or implementing sta&-s......................................................................................1*

.5 8mplementations o' the sta&- in egina...............................................................................1*?

.5.1 8mplementation o' the internal sta&- in egina 2.2 and aboe....................................1*

.5.2 8mplementation o' the e%ternal sta&- in egina 2.2 and aboe...................................1*+

r%sta&-...............................................................................................................................1*+

r%Kueue..............................................................................................................................1*+

r%Kueue uilt$in un&tion.................................................................................................1**

Bueue /ames....................................................................................................................1**

Se&urit( o' %ternal Bueues..............................................................................................1**

nironment 4ariables......................................................................................................200

+ 8nter'a&ing e%% to other programs.............................................................................................201

+.1 Oerie6 o' 'un&tions in SAA............................................................................................201

+.1.1 8n&lude iles and 3ibraries...........................................................................................201

+.1.2 "repro&essor S(mbols..................................................................................................202

+.1.= ata stru&tures and data t(pes......................................................................................2021.1.1.1 9he S98/ stru&ture......................................................................................20=

1.1.2 9he SS89 stru&ture.......................................................................................20

+.2 9he Sub&ommand !andler 8nter'a&e...................................................................................20?

+.2.1 Dhat is a Sub&ommand !andler..................................................................................20?

+.2.2 9he e%%egisterSub&om%eFG 'un&tion.....................................................................20

+.2.= 9he e%%egisterSub&omllFG 'un&tion......................................................................20+

+.2. 9he e%%eregisterSub&omFG 'un&tion.......................................................................20*

+.2.5 9he e%%Buer(Sub&omFG 'un&tion..............................................................................210

+.= 9he %ternal un&tion !andler 8nter'a&e.............................................................................211

+.=.1 Dhat is an %ternal un&tion !andler.........................................................................211

+.=.2 9he e%%egisterun&tion%eFG 'un&tion...................................................................212

11


12/262

+.=.= 9he e%%egisterun&tionllFG 'un&tion.....................................................................212

+.=. 9he e%%eregisterun&tionFG 'un&tion......................................................................21=

+.=.5 9he e%%Buer(un&tionFG 'un&tion.............................................................................21

+. %e&uting e%% Code..........................................................................................................215

+..1 9he e%%StartFG 'un&tion..............................................................................................215

+.5 4ariable "ool 8nter'a&e.........................................................................................................21*

+.5.1 S(mboli& or ire&t.......................................................................................................21*+.5.2 9he S!43OCM stru&ture..........................................................................................21*

+.5.= egina /otes 'or the 4ariable "ool..............................................................................22=

+.5. 9he e%%4ariable"oolFG 'un&tion.................................................................................22

+.? 9he S(stem %it !andler 8nter'a&e......................................................................................22?

+.?.1 9he S(stem %it !andler.............................................................................................22?

+.?.2 3ist o' S(stem %it !andlers.......................................................................................22

1.1.2.1.1 /C $ 9he %ternal un&tion %it !andler...................................................22

1.1.2.2 C $ 9he Sub&ommand %it !andler...........................................................22+

1.1.2.= SB $ 9he %ternal ata Bueue %it !andler................................................22*

1.1.2. S8O $ 9he Standard 8#O %it !andler...............................................................2=1

1.1.2.5 !39 $ 9he !alt Condition %it !andler...........................................................2=21.1.2.? 9C $ 9he 9ra&e Status %it !andler...............................................................2=2

1.1.2. 8/8 $ 9he 8nitialiHation %it !andler................................................................2=2

1.1.2.+ 9 $ 9he 9ermination %it !andler...............................................................2=2

1.1.2.* /4 $ 9he %ternal nironment %it !andler...............................................2==

+. 9he %ternal Bueue 8nter'a&e..............................................................................................2=

+..1 9he e%%CreateBueueFG 'un&tion................................................................................2=

+..2 9he e%%eleteBueueFG 'un&tion................................................................................2=5

+..= 9he e%%Buer(BueueFG 'un&tion.................................................................................2=5

+.. 9he e%%AddBueueFG 'un&tion....................................................................................2=?

+..5 9he e%%"ullBueueFG 'un&tion....................................................................................2=?

+.+ 9he a&ro Spa&e 8nter'a&e..................................................................................................2=*

+.+.1 9he e%%Adda&roFG 'un&tion....................................................................................2=*

+.+.2 9he e%%ropa&roFG 'un&tion...................................................................................2=*

+.+.= 9he e%%Saea&roSpa&eFG 'un&tion.........................................................................2=*

+.+. 9he e%%3oada&roSpa&eFG 'un&tion.........................................................................2=*

+.+.5 9he e%%Buer(a&roFG 'un&tion.................................................................................2=*

+.+.? 9he e%%eordera&roFG 'un&tion..............................................................................2=*

+.+. 9he e%%Cleara&roSpa&eFG 'un&tion.........................................................................2=*

+.* Allo&ating and e$allo&ating Spa&e.....................................................................................20

+.*.1 9he e%%Allo&ateemor(FG 'un&tion..........................................................................20

+.*.2 9he e%%reeemor(FG 'un&tion................................................................................20+.10 Calling ba&- into running e%% Code................................................................................21

+.10.1 9he e%%Calla&-FG 'un&tion....................................................................................21

* 8mplementation 3imits................................................................................................................2=

*.1 Dh( se 3imits.................................................................................................................2=

*.2 Dhat 3imits to Choose.......................................................................................................2=

*.= eKuired 3imits...................................................................................................................2=

*. Older FObsoleteG 3imits.......................................................................................................2

*.5 Dhat the Standard does not Sa(..........................................................................................25

*.? Dhat an 8mplementation is Allo6ed to ;8gnore;.................................................................25

*. 3imits in egina...................................................................................................................2?

10 egina eatures and 8mplementation........................................................................................2+

12


13/262

10.1 egina estri&ted ode.....................................................................................................2+

10.2 /atie 3anguage Support..................................................................................................2+

10.2.1 rror essages...........................................................................................................2+

10.2.2 3o&ale Support...........................................................................................................2*

10.2.= sing /atie 3anguage Support................................................................................2*

10.= e%% and egina binaries: Dh(.......................................................................................250

11 Appendi%es................................................................................................................................25111.1 e'initions..........................................................................................................................251

11.2 ibliograph(.......................................................................................................................255

11.= / ree o&umentation 3i&ense....................................................................................25

13


14/262

1 Introduction to Regina

This chapter provides an introduction to Regina, an Open Source RexxInterpreter distributedunder the GNU General Library License.

1.1 Purpose of this document9he purpose o' this do&ument is to proide an oerie6 o' the Rexx3anguage and the eginaimplementation o' the Rexx3anguage. 8t is not intended as a de'initie re'eren&e to Rexx7 (oushould reall( hae a &op( o' the Rexx;bible;7 The RexxLanguage, b(Mie !o"lisha"I932J.

1.2 Implementation9he egina Rexx8nterpreter is implemented as a librar( suitable 'or lin-ing into third$part(appli&ations. A&&ess to egina 'rom third$part( appli&ations is ia the egina A"8, 6hi&h is

&onsistent 6ith the 8Ps Rexx SAA A"8. 9his A"8 is implemented on most other Rexxinterpreters.

9he librar( &ontaining egina is aailable either as a stati& librar( or as a d(nami&all( loadable

librar(. 9he onl( 'un&tional di''eren&e bet6een the t6o libraries is that the abilit( to d(nami&all(

load Rexxe%ternal 'un&tion pa&-ages ia the built$in 'un&tion7 %un&Add, is onl( aailable 6ith

the d(nami&all( loadable librar(.

9he egina distribution also in&ludes a 'ront end to the egina librar(, to enable the e%e&ution o'

Rexxprograms dire&tl( 'rom the &ommand line. 9he co##and linere'erred to here relates to the ani% shell, an OS#2 or OS &ommand 6indo6 or a Dindo6s /9#*% &ommand prompt.

On plat'orms 6here both a stati& and a d(nami& e%e&utable e%ist, it should be noted that the abilit(

to load and e%e&ute e%ternal 'un&tions ia the %un&Add 'un&tion, is onl( aailable b( running the

d(nami& e%e&utable.

14


15/262

1.3 Ports of Reginaegina has been ported to man( operating s(stems. 9he 'ollo6ing table proides implementation

details o' ea&h o' the ports o' egina.

Operating System Static

Library

Dynamic

Library

Dynamic

LibraryThreadSae

Dynamic

!"ec#tab$e

Static

!"ec#tab$e

Lin#" libregina.a libregina.so es regina re%%

%&'() libregina.a libregina.sl /o regina re%%

*+) libregina.a libregina.a es regina re%%

Other (ni" libregina.a libregina.so a(be regina re%%

32'bit DOS

,D-.&&/

,(ses D&+memry manager/

libregina.a /#A /o /#A re%%.e%e

32'bit DOS ,!)/

,(ses &+ memry

manager/

regina.a /#A /o /#A re%%.e%e

OS2 ,!)/ regina.a regina.dll

Fregina.libG

es regina.e%e re%%.e%e

OS2

,Openatcm/

re%%.lib regina.dll

Fregina.libG

/o regina.e%e re%%.e%e

inds 32bit

inds 64bit

re%%.lib regina.dllFregina.libG

es regina.e%e re%%.e%e

eOS libregina.a libregina.so /o regina re%%

*migaOS libregina.a /#A /o /#A re%%

!&O32 /#A /#A /o /#A re%%.e%e

*theOSSy$$ab$e libregina.a libregina.so /o regina re%%

) 4:2" re%%.lib /#A /o /#A re%%

) 6:" libregina.a libregina.so es regina re%%acOS ) libregina.a libregina.d(lib /o regina re%%

S;yOS libregina.a libregina.dll /o regina.app re%%.app

1.4 Executing Rexx programs ith ReginaRexxprograms are generall( e%e&uted b( egina 'rom the co##and linein the 'ollo6ing manner:

reginaIs"itchesJ IprogramJ Iprogra# para#etersJ

15


16/262

6here:

regina is the name o' the egina e%e&utable Fsee table aboeG

s"itches are optional s6it&hes. See the se&tion belo6 'or an e%planation o' the

s6it&hes &urrentl( supported b( egina

prgram the name o' the Rexxprogram to be e%e&uted. See the se&tion!"terna$ Rexx&rgrams, belo6, 'or details on ho6 egina

interprets this argument. 8' no program name is spe&i'ied, egina6aits 'or Rexx&ommands to be t(ped in and 6ill e%e&ute those&ommands 6hen the appropriate end$o'$'ile &hara&ter FT on ni%

and TN on OS, OS#2 and Dindo6s /9#*5G is t(ped.

progra# para#eters an( optional parameters to be passed to the Rexxprogram.

Rexxprograms to be e%e&uted b( egina on ni% plat'orms &an ta-e adantage o' a 'eature o'ni% shell programs &alled #agic nu#bers. ( haing the 'irst line o' a Rexxprogram &onsist o'the spe&ial seKuen&e o'


17/262

SOC 6ill return SO98/ instead o' the normal

COA/ alue.

$r un egina in restri&ted mode. See the se&tion on egina estri&ted

ode 'or more details.

$ ispla(s the ersion in'ormation 'or the e%e&utable run. 9he string

displa(ed is the same that is returned b( &*>S! SO(>!. 9heersion string proides an indi&ator as to 6hether the egina librar( is

thread$sa'e or not. 8' the 'irst 6ord ends inUF9GV, then the librar( is

thread$sa'e. 9his s6it&h, e%e&uted b( the static e$ecutable, 6ill al6a(s

result in noUF9GVindi&ator.

$lIlocaleJ 8ndi&ates 6hi&h national lo&ale that egina is to use 'or +@s li-e

T>*SL*T!, LO!>, or (&&!>. /o alidation is done on the

spe&i'ied lo&ale. 9he a''e&ted behaiour is de'ined in Se&tion 27

U/atie 3anguage SupportV.

9he localeis passed to the underl(ing C librar(, 6hi&h resoles the

des&riber in a s(stem spe&i'i& 6a(. An omitted localelets the s(stem

&hoose the &urrent pre$sele&ted lo&ale 'or the user. 9his is the usualoption a user 6ould &hoose. ;-l; 6ithout a locale, 6or-s best 'or

most users 6ho de&ided to use lo&ale support. rror messages &an be

sele&ted b( another s&heme using an enironment ariable, see Se&tion

10.27/atie 3anguage Support7 this ariable &an be used to sele&t a

lo&ale, too.

9he te%t o' the localeis eKuialent to those o' the enironment

ariables LANGor LC_CTYPEor the alue used in registries, et&.%amples are en_US.ISO-8859-1or nglis_US".15'or

some s(stems.

$oO"98O/S 9his s6it&h spe&i'ies the alues o' O"98O/S to set. 9his is a string o'6ords in the same 'ormat as the O"98O/S instru&tion. 9his s6it&h

oer6rites 8/ALO"98O/S

$p 9his s6it&h &auses egina to pause on e%it. 9his is onl( alid on most

plat'orms. 9his s6it&h is use'ul i' (ou run Rexxprograms 'rom a8 'ile manager and 6ant to see the output 'rom that program.

$& !o#pile the spe&i'ied prgraminto a to-enised 'ormat. 9he onl(

program parameters 6hen using this s6it&h is the 'ilename 'or the

to-enised program. i.e. regina$& prgram'ilename

$e %$ecute the spe&i'ied program 'rom a to-enised 'ormat. prgram

must be a 'ile &reated b( the $& s6it&h. All other s6it&hes and program

parameters are allo6ed.

1.4.2 External Rexx programs

egina sear&hes 'or Rexxprograms, using a &ombination o' the >!.+*?*>OSenironment ariable, the &*T%enironment ariable, the >!.+*?S(@@+)!S enironment

ariable and the addition o' 'ilename e%tensions. 9his rule applies to both e%ternal 'un&tion &alls

6ithin a Rexxprogram and the prgramspe&i'ied on the co##and line.

irst o' all 6e pro&ess the enironment ariable >!.+*?*>OS. 8' no 'ile is 'ound 6e

pro&eed 6ith the &urrent dire&tor( and then 6ith the enironment ariable &*T%. 9he semanti&s o'

the use o' >!.+*?*>OSand &*T%are the same, and the sear&h in the &urrent dire&tor( is

omitted 'or the superuser on ni% s(stems 'or se&urit( reasons. 9he &urrent dire&tor( must be

17


18/262

spe&i'ied e%pli&itl( b( the superuser.

Dhen pro&essing an enironment ariable, the &ontent is split into the di''erent paths and ea&h path

is pro&essed separatel(. /ote that the sear&h algorithm to this point is ignored i' the program name

&ontains a 'ile path spe&i'i&ation. eg. i' ;CA33 .W"O; is &alled, then no sear&hing o'

>!.+*?*>OSor &*T%is done7 onl( the &on&atenation o' su''i%es is &arried out.

or ea&h 'ile name and path element, a &on&atenated 'ile name is &reated. 8' a -no6n 'ile e%tension

is part o' the 'ile name onl( this 'ile is sear&hed, other6ise the 'ile name is e%tended b( the

e%tensions ;; Fempt( stringG, ;.re%%;, ;.re%;, ;.&md;, and ;.r%; in this order. 9he 'ile name &ase is

ignored on s(stems that ignore the &hara&ter &ase 'or normal 'ile operations li-e OS, Dindo6s,

and OS#2.

9he 'irst mat&hing 'ile terminates the 6hole algorithm and the 'ound 'ile is returned.

9he enironment ariable >!.+*?S(@@+)!Se%tends the list o' -no6n su''i%es as spe&i'ied

aboe, and is inserted a'ter the e#ptye%tension in the pro&ess. >!.+*?S(@@+)!Shas to

&ontain a spa&e or &omma separated list o' e%tensions, a dot in 'ront o' ea&h entr( is allo6ed,e.g. ;.ma&ro,.ma&,.regina; or ;ma&ro ma& regina;

/ote that it is planned to e%tend the list o' -no6n su''i%es b( ;.r%&; in ersion =. to allo6 'or

seamless integration o' pre$&ompiled ma&ros.

Example" #ocating an external Rexx program for execution

Assume (ou hae a &all to an e%ternal 'un&tion, and it is &oded as 'ollo6s:

$all %ye&'(unc arg1) arg

Assume also that the 'ile mye"t#nc:cmde%ists in the dire&tor( #opt#re%%#, and that

&*T%R#usr#bin:#opt#re%%, >!.+*?*>OSis ntset, and >!.+*?S(@@+)!SR.ma&ro.

9he 'iles that egina 6ill sear&h 'or in order are:

.#m(e%t'un&

.#m(e%t'un&.ma&ro

.#m(e%t'un&.re%%

.#m(e%t'un&.re%

.#m(e%t'un&.&md

.#m(e%t'un&.r%

#usr#bin#m(e%t'un&

#usr#bin#m(e%t'un&.ma&ro

#usr#bin#m(e%t'un&.re%%

#usr#bin#m(e%t'un&.re%

#usr#bin#m(e%t'un&.&md

#usr#bin#m(e%t'un&.r%

#opt#re%%#m(e%t'un&

#opt#re%%#m(e%t'un&.ma&ro

#opt#re%%#m(e%t'un&.re%%

18


19/262

#opt#re%%#m(e%t'un&.re%

#opt#re%%#m(e%t'un&.&md #X 'oundYY terminate sear&hX#

19


20/262

2 Rexx #anguage Constructs

In this chapter, the concept and synta$ o& Rexx clauses are e$plained. 't the end o& the chapterthere is a section describing ho" Regina di&&ers &ro# standard Rexx as described in the &irst parto& the chapter.

2.1 $efinitionsA program in the Rexxlanguage &onsists o' &lauses, 6hi&h are diided into 'our groups: null&lauses, &ommands, assignments, and instru&tions. 9he three latter groups F&ommands, assignments,

and instru&tionsG are &olle&tiel( re'erred to as statements. 9his does not mat&h the terminolog( in

I932J, 6here ;instru&tion; is eKuialent to 6hat is -no6n here as ;statement;, and ;-e(6ordinstru&tion; is eKuialent to 6hat is -no6n here as ;instru&tion;. !o6eer, 8 'ind the terminolog(

used here simpler and less &on'using.

8n&identall(, the terminolog( used here mat&hes IA/J.

A &lause is de'ined as all non$&lause$delimiters Fi.e. blan-s and to-ensG up to and in&luding a &lause

delimiter. A to-en delimiter &an be:

An end$o'$line, unless it lies 6ithin a &omment, or the last to-en on a line is the line

&ontinuation &hara&ter. An end$o'$line 6ithin a &onstant string is &onsidered a s(nta% error Z?[.

A semi&olon &hara&ter that is not 6ithin a &omment or &onstant string. A &olon &hara&ter, proided that the seKuen&e o' to-ens leading up to it &onsists o' a single

s(mbol and 6hitespa&e. 8' a seKuen&e o' t6o s(mbol to-ens is 'ollo6ed b( a &olon, then this

implies S*+,"&ondition Z20[.

Some s(stems hae the abilit( to store a te%t 'ile haing a last line unterminated b( an end$o'$line

&hara&ter seKuen&e. 8n general, this applies to s(stems that use an e%pli&it end$o'$line &hara&ter

seKuen&e to denote end$o'$lines, e.g. ni% and S$OS s(stems. nder these s(stems, i' the last

line is unterminated, it 6ill stri&tl( spea-ing not be a &lause, sin&e a &lause must in&lude its

terminating &lause delimiter. !o6eer, some interpreters are li-el( to regard the end$o'$'ile as a

&lause delimiter too. 9he 'un&tionalit( o' I+,P,gies some 6eight to this interpretation. utother s(stems ma( ignore that last, unterminated line, or ma(be issue a s(nta% error. F!o6eer,

there is no S*+,"&ondition number adeKuatel( &oering this situation.

Example" %inar& transferring files

Suppose a Rexxprogram is stored on an S$OS ma&hine. 9hen, an end$o'$line seKuen&e ismar-ed in the 'ile as the t6o &hara&ters &arriage return and ne6line. 8' this 'ile is trans'erred to a

ni% s(stem, then onl( ne6line mar-s the end$o'$line. or this to 6or-, the 'ile must be trans'erred

as a te%t 'ile. 8' it is Fin&orre&tl(G trans'erred as a binar( 'ile, the result is that on the ni% s(stem,

ea&h line seems to &ontain a trailing &arriage return &hara&ter. 8n an editor, it might loo- li-e this:

20


21/262

say ello 0orl23say 'a'4s i'23

9his 6ill probabl( raise S*+,"&ondition Z1=[.

2.2 'ull clauses/ull &lauses are &lauses that &onsist o' onl( 6hitespa&e, or &omments, or both7 in addition to the

terminating &lause delimiter. 9hese &lauses are ignored 6hen interpreting the &ode, e%&ept 'or one

situation: null &lauses &ontaining at least one &omment is tra&ed 6hen appropriate. /ull &lauses not

&ontaining an( &omments are ignored in eer( respe&t.

Example" Tracing comments

9he tra&ing o' &omments ma( be a ma\or problem, depending on the &onte%t. 9here are basi&all(

t6o strategies 'or large &omments: either bo% multiple lines as a single &omment, or ma-e the te%ton ea&h line an independent &omment, as sho6n belo6:

'race all

/ ,is is a single) large co%%en') 0ic s6ans %ul'i6le lines. Suc co%%en's are o('en use a' 'e s'ar' o( a subrou'ine or si%ilar) in orer 'o escribe bo' 'e in'er(ace 'o an 'e (unc'ionali'y o( 'e (unc'ion.

/

/ ,is is also a large co%%en') bu' i' is 0ri''en as // %ul'i6le co%%en's) eac on i's o0n line. ,us) 'ese // are several clauses 0ile 'e co%%en' above is a // single co%%en'. /

-- ,ese lines also consis' o( %ul'i6le co%%en's) an 'us-- %ul'i6le clauses. ,is (or% o( co%%en' 0as in'rouce-- in egina 7.

uring tra&ing, the 'irst o' these 6ill be displa(ed as one large &omment, and during intera&tietra&ing, it 6ill onl( pause on&e. 9he se&ond 6ill be displa(ed as multiple lines, and 6ill ma-e

seeral pauses during intera&tie tra&ing. An interpreter ma( sole this situation in seeral 6a(s, the

main ob\e&tie must be to displa( the &omments ni&el( the to programmer debugging the &ode.

"re'erabl(, the &ode is sho6n in a 'ashion that resembles ho6 it is entered in the 'ile.

8' a label is multiple de'ined, the 'irst de'inition is used and the rest are ignored. ultiple de'ined

labels is not an S*+,"&ondition.

A null &lause is not a statement. 8n some situations, li-e a'ter the ,+sub&lause, onl( a statement

is e%pe&ted. 8' a null &lause is proided, then it is ignored, and the ne%t statement is used instead.

21


22/262

Consider the 'ollo6ing &ode:

6arse 6ull (oo

i( (oo: 'ensay (oo is no'

else / o no'ing /

say 'a';s i'

9his 6ill not 6or- the 6a( indentation indi&ates, sin&e the &omment in this e%ample is not a

statement. 9hus, the ;Sreads be(ond the &omment, and &onne&ts to the S"*instru&tion 6hi&h

be&omes the ;Spart. F9hat 6hat probabl( not 6hat the programmer intended.G 9his &ode 6ill

sa( 'a's i', onl( 6hen (oois di''erent 'rom . A separate instru&tion, +OPhas been

proided in order to 'ill the need that 6as inadeKuatel( attempted 'illed b( the &omment in the &ode

'ragment aboe.

Example" Trailing comments

9he e''e&t that &omments are not statements &an be e%ploited 6hen do&umenting the program, and

simultaneousl( ma-ing the program 'aster. Consider the 'ollo6ing t6o loops:

su% : instru&tion, een though it might loo- li-e one. 8' (ou need an ">instru&tion

6hi&h template starts 6ith an absolute indire&t positional pattern, use the P"S UPP

">instru&tion instead, or prepend a dot in 'ront o' the template.

An assignment &an assign a alue to a simple ariable, a stem ariable or a &ompound ariable.

Dhen assigning to a stem ariable, all possible ariable s(mbols haing that stem are assigned the

alue. /ote spe&i'i&all( that this is not li-e setting a de'ault, it is a one time multiple assignment.

Example" )ultiple assignment

9he di''eren&e bet6een RexxPs multiple assignment and a de'ault alue &an be seen 'rom the'ollo6ing &ode:

(oo. : bar(oo.1 : ba?ro6 (oo.1say (oo.1 / says [email protected] /

!ere, the S"*instru&tion 6rites out @OO.1, not bar. uring the AOPinstru&tion, the ariable

@OO.1regains its original, uninitialiHed alue @OO.1, not the alue o' its stem ariable @OO., i.e.

bar, be&ause stem assignments does not set up a de'ault.

23


24/262

Example" Emulating a default *alue

8' (ou 6ant to set the &ompound ariable to the alue o' its stem ariable, i' the stem is initialiHed,

then (ou ma( use the 'ollo6ing &ode:

i( Bsy%bolB(oo.CC 'en

(oo.1 : (oo.else

ro6 (oo.1

8n this e%ample, the @OO.1ariable is set to the alue o' its stem i' the stem &urrentl( is assigned a

alue. lse, the @OO.1ariable is dropped.

!o6eer, this is probabl( not e%a&tl( the same, sin&e the internal storage o' the &omputer is li-el(

to store ariables li-e @OO.and @OO.7onl( impli&itl( Fa'ter all, it &an not e%pli&itl( store eer(

&ompound haing @OO.as stemG. A'ter the assignment o' the alue o' @OO.to @OO.1, the @OO.1

&ompound ariable is li-el( to be e%pli&itl( stored in the interpreter.

9here is no 6a( (ou &an dis&oer the di''eren&e, but the e''e&ts are o'ten that more memor( is used,

and some 'un&tionalit( that dumps all ariables ma( dump @OO.1but not @OO.F6hi&h is

in&onsistentG. See se&tion e%%4ariable"ool.

Example" !pace considerations

en more strange are the e''e&ts o' the 'ollo6ing short e%ample:

(oo. : barro6 (oo.1

Although apparentl( er( simple, there is no 6a( that an interpreter &an release all memor(

re'erring to @OO.1. A'ter all, @OO.1has a di''erent alue than @OO., @OO.7, et&., so the

interpreter must store in'ormation that tells it that @OO.1has the uninitialiHed alue.

9hese &onsiderations ma( seem li-e nit$pi&-ing, but the( 6ill matter i' (ou drop lots o' &ompound

ariables 'or a stem 6hi&h has preiousl( re&eied a alue. Some programming idioms do this, so

be a6are. 8' (ou &an do 6ithout assigning to the stem ariable, then it is possible 'or the interpreter

to regain all memor( used 'or that stemPs &ompound ariables.

2.4 Instructions8n this se&tion, all instru&tions in standard Rexxare des&ribed.

%tensions are listed later in this &hapter.

irst some notes on the terminolog(. Dhat is &alled an instru&tion in this do&ument is eKuialent to

a ;unit; o' &lauses. 9hat is, ea&h instru&tion &an &onsist o' one or more &lauses. or instan&e, the

S"*instru&tion is al6a(s a single instru&tion, but the I@instru&tion is a multi$&lause instru&tion.

Consider the 'ollo6ing s&ript, 6here ea&h &lause has been bo%ed:

24


25/262

i( a:b 'ensay ello

elsesay bye

urther, the ,+or ;Sparts o' this instru&tion might &onsist o' a AO#+Apair, in 6hi&h &ase

the I@ instru&tion might &onsists o' an irtuall( unlimited number o' &lauses.

9hen, some notes on the s(nta% diagrams used in the 'ollo6ing des&riptions o' the instru&tions. 9he

rules appl(ing to these diagrams &an be listed as:

An(thing 6ritten in courier'ont in the s(nta% diagrams indi&ates that it should o&&ur as$is in

the Rexxprogram. Dheneer something is 6ritten in italic'ont, it means that the term shouldbe substituted 'or another alue, e%pression, or terms.

An(thing &ontained 6ithin mat&hing pairs o' sKuare bra&-ets FI...JG are optional, and ma( be le't

out.

Dheneer a pair o' &url( bra&es is used, it &ontains t6o or more sub&lauses that are separated b(the erti&al bar FDG. 8t means that the &url( bra&es 6ill be substituted 'or one o' the sub&lauses it

&ontains.

Dheneer the ellipsis F...G is used, it indi&ates that the immediatel( pre&eding sub&lauses ma( be

repeated Hero or more times. 9he s&ope o' the ellipsis is limited to the &ontents o' a set o' sKuare

bra&-ets or &url( bra&es, i' it o&&urs there.

Dheneer the erti&al bar Dis used in an( o' the s(nta% diagrams, it means that either the term

to the le't, or the term to the right &an be used, but not both, and at least one o' the must be used.

9his ;operator; is asso&iatie F&an be used in seKuen&eG, and it has lo6er priorit( than the sKuare

bra&-ets Fthe s&ope o' the erti&al bar lo&ated 6ithin a pair o' sKuare bra&-ets or &url( bra&es is

limited to the te%t

regina rexx v3.7 - user manual

Documents