Regina REXX v3.7 - User Manual

The Regina Rexx Interpreter
Version 3.7
Mark Hessling <mark@rexx.org>
Florian Groe-Coosmann <florian@grosse-coosmann.de>
5 September, 2012
Original Author: Anders Christensen <Anders.Christensen@idi.ntnu.no>
egina !ome "age at: http:##regina$re%%.sour&e'orge.net
1
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 ./0
1ree 2o&umentation 3i&ense, 4ersion 1.1 or an( later 5ersion published b( the 1ree So't6are
1oundation7 6ith no 8n5ariant Se&tions, 6ith no 1ront$Co5er 9e%ts, and 6ith no :a&-$Co5er 9e%ts.
A &op( o' the li&ense is in&luded in the se&tion entitled ;./0 1ree 2o&umentation 3i&ense;.
2
Table of Contents
1 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 2e'initions.............................................................................................................................20
2.2 /ull &lauses............................................................................................................................21
2.= Commands.............................................................................................................................2=
2.=.1 Assignments...................................................................................................................2=
2.< 8nstru&tions.............................................................................................................................2<
2.<.1 9he A22>SS 8nstru&tion............................................................................................2?
2.<.2 9he A. 8nstru&tion......................................................................................................==
2.<.= 9he CA33 8nstru&tion....................................................................................................=<
2.<.< 9he 2O#>/2 8nstru&tion...............................................................................................=@
2.<.5 9he 2O" 8nstru&tion....................................................................................................<0
2.<.? 9he >A89 8nstru&tion.....................................................................................................<2
2.<.@ 9he 81#9!>/#>3S> 8nstru&tion....................................................................................<=
2.<.+ 9he 8/9>">9 8nstru&tion.........................................................................................<=
2.<.* 9he 89>A9> 8nstru&tion..............................................................................................<5
2.<.10 9he 3>A4> 8nstru&tion................................................................................................<?
2.<.11 9he /O" 8nstru&tion.....................................................................................................<?
2.<.12 9he /0,>8C 8nstru&tion..........................................................................................<@
2.<.1= 9he O"98O/S 8nstru&tion...........................................................................................<+
2.<.1< 9he "AS> 8nstru&tion................................................................................................<*
2.<.15 9he "OC>20> 8nstru&tion....................................................................................52
2.<.1? 9he "033 8nstru&tion..................................................................................................55
2.<.1@ 9he "0S! 8nstru&tion..................................................................................................55
2.<.1+ 9he B0>0> 8nstru&tion...............................................................................................55
2.<.1* 9he >90/ 8nstru&tion............................................................................................55
2.<.20 9he SAC 8nstru&tion.....................................................................................................5@
2.<.21 9he S>3>C9#D!>/#O9!>D8S> 8nstru&tion........................................................5@
2.<.22 9he S8./A3 8nstru&tion..............................................................................................5+
2.<.2= 9he 9AC> 8nstru&tion...............................................................................................?1
2.<.2< 9he 0""> 8nstru&tion................................................................................................?=
2.5 Operators................................................................................................................................?=
2.5.1 Arithmeti& Operators......................................................................................................?=
2.5.2 Assignment Operators....................................................................................................?=
2.5.= Con&atenation Operators................................................................................................?=
2.5.< Comparati5e Operators..................................................................................................?<
2.5.5 3ogi&al Operators...........................................................................................................?<
2.? Spe&ial 4ariables....................................................................................................................?5
2.?.1 3o&al S&ope E 0ser Driteable........................................................................................?5
C $ FA/S8G.............................................................................................................................?5
C $ FA/S8G........................................................................................................................?5
>S039 $ FA/S8G....................................................................................................................?5
>S039 $ FA/S8G...............................................................................................................?5
3
S8.3 $ FA/S8G..........................................................................................................................?5
S8.3 $ 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
.>S039 $ FA/S8G...................................................................................................................?5
.>S039 $ FA/S8G..............................................................................................................?5
.38/> $ FeginaG......................................................................................................................?5
.38/> $ FeginaG..................................................................................................................?5
.>/2O138/> $ FeginaG.........................................................................................................?5
.>/2O138/> $ FeginaG....................................................................................................?5
2.@ 8mplementation$Spe&i'i& 8n'ormation....................................................................................??
2.@.1 ,is&ellaneous.................................................................................................................??
2.@.2 8mplementation o' the A22>SS en5ironment............................................................??
= e%% :uilt$in 1un&tions.................................................................................................................@0
=.1 .eneral 8n'ormation...............................................................................................................@0
=.1.1 9he S(nta% 1ormat.........................................................................................................@0
=.1.2 "re&ision and /ormaliHation..........................................................................................@1
=.1.= Standard "arameter /ames............................................................................................@1
=.1.< >rror ,essages...............................................................................................................@2
=.1.5 "ossible S(stem 2ependen&ies......................................................................................@2
=.1.? :lan-s 5s. Spa&es...........................................................................................................@<
=.2 egina :uilt$in 1un&tions......................................................................................................@5
A::>4Flong, short I,lengthJG $ FA/S8G................................................................................@5
A::>4Flong, short I,lengthJG $ FA/S8G...........................................................................@5
A:SFnumberG $ FA/S8G............................................................................................................@5
A:SFnumberG $ FA/S8G.......................................................................................................@5
A22>SSFIoptionJG $ FA/S8G.................................................................................................@5
A22>SSFIoptionJG $ FA/S8G............................................................................................@5
A.FIargno I,optionJJG $ FA/S8G.............................................................................................@?
A.FIargno I,optionJJG $ FA/S8G........................................................................................@?
:2CFbinstringG $ FA>AAG......................................................................................................@@
:2CFbinstringG $ FA>AAG.................................................................................................@@
:2AFbinstringG $ FA/S8G..........................................................................................................@@
:2AFbinstringG $ FA/S8G.....................................................................................................@@
:>>"F'reKuen&( I,durationJG $ FOS#2G.....................................................................................@+
:>>"F'reKuen&( I,durationJG $ FOS#2G................................................................................@+
:89A/2Fstring1 I,Istring2J I,pad&harJJG $ FA/S8G..................................................................@+
:89A/2Fstring1 I,Istring2J I,pad&harJJG $ FA/S8G.............................................................@+
:89C!.Fstring, bitG $ FA>AAG.............................................................................................@+
:89C!.Fstring, bitG $ FA>AAG........................................................................................@+
:89C3Fstring, bitG $ FA>AAG..............................................................................................@+
:89C3Fstring, bitG $ FA>AAG.........................................................................................@+
:89CO,"Fstring1, string2, bit I,padJG $ FA>AAG.................................................................@*
:89CO,"Fstring1, string2, bit I,padJG $ FA>AAG............................................................@*
:89OFstring1 I, Istring2J I,pad&harJJG $ FA/S8G....................................................................@*
4
:89OFstring1 I, Istring2J I,pad&harJJG $ FA/S8G...............................................................@*
:89S>9Fstring, bitG $ FA>AAG..............................................................................................@*
:89S>9Fstring, bitG $ FA>AAG..........................................................................................@*
:899S9Fstring, bitG $ FA>AAG..............................................................................................@*
:899S9Fstring, bitG $ FA>AAG..........................................................................................@*
:89AOFstring1I, Istring2J I,pad&harJJG $ FA/S8G..................................................................@*
:89AOFstring1I, Istring2J I,pad&harJJG $ FA/S8G.............................................................@*
:019C">FG $ FC,SG...............................................................................................................+0
:019C">FG $ FC,SG..........................................................................................................+0
C2:FstringG $ FA>AAG...........................................................................................................+0
C2:FstringG $ FA>AAG......................................................................................................+0
C22Fstring I,lengthJG $ FA/S8G................................................................................................+0
C22Fstring I,lengthJG $ FA/S8G............................................................................................+0
C2AFstringG $ FA/S8G...............................................................................................................+1
C2AFstringG $ FA/S8G..........................................................................................................+1
C2Fdire&tor(G $ F>.8/AG......................................................................................................+1
C2Fdire&tor(G $ F>.8/AG.................................................................................................+1
C!28Fdire&tor(G $ F>.8/AG...............................................................................................+1
C!28Fdire&tor(G $ F>.8/AG..........................................................................................+1
C>/9>Fstring, length I, pad&har J G $ FA/S8G.......................................................................+1
C>/9>Fstring, length I, pad&har J G $ FA/S8G..................................................................+1
C>/9>Fstring, length I, pad&har J G $ FA/S8G.......................................................................+1
C>/9>Fstring, 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!AO09FIstreamidJ I,IstringJ I,startJJG $ FA/S8G................................................................+=
C!AO09FIstreamidJ I,IstringJ I,startJJG $ FA/S8G...........................................................+=
C!ASFIstreamidJG $ FA/S8G..................................................................................................+=
C!ASFIstreamidJG $ FA/S8G.............................................................................................+=
C3OS>F'ileG $ FA>AAG.........................................................................................................+<
C3OS>F'ileG $ FA>AAG.....................................................................................................+<
CO,"A>Fstring1, string2 I,pad&harJG $ FA/S8G...................................................................+<
CO,"A>Fstring1, string2 I,pad&harJG $ FA/S8G...............................................................+<
CO,">SSFstring I,listJG $ FA>AAG....................................................................................+<
CO,">SSFstring I,listJG $ FA>AAG...............................................................................+<
CO/2898O/FIoptionJG $ FA/S8G.............................................................................................+<
CO/2898O/FIoptionJG $ FA/S8G........................................................................................+<
CO"8>SFstring, &opiesG $ FA/S8G.............................................................................................+5
CO"8>SFstring, &opiesG $ FA/S8G........................................................................................+5
CO0/9S9Fneedle, ha(sta&-G $ FA/S8G................................................................................+5
CO0/9S9Fneedle, ha(sta&-G $ FA/S8G...........................................................................+5
CC"9Fstring, saltG $ F>.8/AG.............................................................................................+5
CC"9Fstring, saltG $ F>.8/AG........................................................................................+5
2A9A9C">Fstring I,optionJG $ FA/S8G....................................................................................+?
2A9A9C">Fstring I,optionJG $ FA/S8G...............................................................................+?
2A9>FIoptionLout I,date I,optionLinJJJG $ FA/S8G..................................................................+@
2A9>FIoptionLout I,date I,optionLinJJJG $ FA/S8G.............................................................+@
2>3S9Fstring, start I,lengthJG $ FA/S8G................................................................................+*
5
2>3S9Fstring, start I,lengthJG $ FA/S8G...........................................................................+*
2>3DO2Fstring,startI,lengthJG FA/S8G................................................................................+*
2>3DO2Fstring,startI,lengthJG FA/S8G...........................................................................+*
2>S:01FG $ FC,SG.................................................................................................................*0
2>S:01FG $ FC,SG.............................................................................................................*0
28.89SFG $ FA/S8G...................................................................................................................*0
28.89SFG $ FA/S8G..............................................................................................................*0
28>C9OCFIne6 dire&tor(JG $ FOS#2G.................................................................................*0
28>C9OCFIne6 dire&tor(JG $ FOS#2G.............................................................................*0
22CFinteger I,lengthJG $ FA/S8G..............................................................................................*0
22CFinteger I,lengthJG $ FA/S8G..........................................................................................*0
22AFinteger I,lengthJG $ FA/S8G..............................................................................................*1
22AFinteger I,lengthJG $ FA/S8G.........................................................................................*1
2O":01FInumberJG $ FC,SG...............................................................................................*1
2O":01FInumberJG $ FC,SG...........................................................................................*1
>O1F'ileG $ FA>AAG..............................................................................................................*2
>O1F'ileG $ FA>AAG..........................................................................................................*2
>O9>A9Ferrorno I, langJG $ FA/S8G................................................................................*2
>O9>A9Ferrorno I, langJG $ FA/S8G...........................................................................*2
>A8S9SF'ilenameG $ FA>AAG................................................................................................*=
>A8S9SF'ilenameG $ FA>AAG...........................................................................................*=
>A"O9Faddress, IstringJ, IlengthJ I,padJG $ FA>AAG.........................................................*=
>A"O9Faddress, IstringJ, IlengthJ I,padJG $ FA>AAG....................................................*=
183>S">CFoption, 'ilespe&G $ FOS#2G......................................................................................*<
183>S">CFoption, 'ilespe&G $ FOS#2G.................................................................................*<
18/2Fstring, phraseG $ FC,SG..................................................................................................*<
18/2Fstring, phraseG $ FC,SG.............................................................................................*<
1OMFG $ F>.8/AG...............................................................................................................*<
1OMFG $ F>.8/AG...........................................................................................................*<
1O,FG $ FA/S8G....................................................................................................................*<
1O,FG $ FA/S8G................................................................................................................*<
1O,A9Fnumber I,Ibe'oreJ I,Ia'terJ I,Ie%ppJ I,Ie%ptJJJJJG $ FA/S8G......................................*5
1O,A9Fnumber I,Ibe'oreJ I,Ia'terJ I,Ie%ppJ I,Ie%ptJJJJJG $ FA/S8G.................................*5
1>>S"AC>Faddress, lengthG $ FA>AAG.............................................................................*?
1>>S"AC>Faddress, lengthG $ FA>AAG.........................................................................*?
10NNFG $ FA/S8G......................................................................................................................*?
10NNFG $ FA/S8G.................................................................................................................*?
.>9CA33S9ACMFstemG $ F>.8/AG...................................................................................*?
.>9CA33S9ACMFstemG $ F>.8/AG...............................................................................*?
.>9>/4Fen5ironment5arG $ F>.8/AG.................................................................................*?
.>9>/4Fen5ironment5arG $ F>.8/AG............................................................................*?
.>9"82FG $ F>.8/AG............................................................................................................*?
.>9"82FG $ F>.8/AG.......................................................................................................*?
.>9S"AC>FlengthG $ FA>AAG.............................................................................................*@
.>9S"AC>FlengthG $ FA>AAG.........................................................................................*@
.>9982FG $ F>.8/AG............................................................................................................*@
.>9982FG $ F>.8/AG.......................................................................................................*@
!AS!FstringG $ FA>AAG.......................................................................................................*@
!AS!FstringG $ FA>AAG...................................................................................................*@
8,"O9Faddress I,lengthJG $ FA>AAG..................................................................................*@
6
8,"O9Faddress I,lengthJG $ FA>AAG.............................................................................*@
8/2>AFha(sta&-, needle I,startJG $ FC,SG..............................................................................*@
8/2>AFha(sta&-, needle I,startJG $ FC,SG..........................................................................*@
8/S>9Fstring1, string2 I,position I,length I,pad&harJJJG $ FA/S8G........................................*@
8/S>9Fstring1, string2 I,position I,length I,pad&harJJJG $ FA/S8G....................................*@
O0S981CFstring, length I,padJG $ FC,SG..................................................................................*+
O0S981CFstring, length I,padJG $ FC,SG.............................................................................*+
3AS9"OSFneedle, ha(sta&- I,startJG $ FA/S8G........................................................................*+
3AS9"OSFneedle, ha(sta&- I,startJG $ FA/S8G....................................................................*+
3>19Fstring, length I,pad&harJG $ FA/S8G................................................................................*+
3>19Fstring, 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/>O09FIstreamidJ I,IstringJ I,lineJJG $ FA/S8G.................................................................100
38/>O09FIstreamidJ I,IstringJ I,lineJJG $ FA/S8G............................................................100
38/>SFIstreamidJ I,optionJG $ FA/S8G...................................................................................101
38/>SFIstreamidJ I,optionJG $ FA/S8G..............................................................................101
3OD>Fstring I,start I,length I,padJJJG $ F>.8/AG............................................................101
3OD>Fstring I,start I,length I,padJJJG $ F>.8/AG.......................................................101
,AM>:01FG $ FC,SG...........................................................................................................102
,AM>:01FG $ FC,SG......................................................................................................102
,AAFnumber1 I,number2J ...G $ FA/S8G...............................................................................102
,AAFnumber1 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 $ FA>AAG.................................................10=
O">/F'ile, 'ilename, IPAppendPQPeadPQPDritePJG $ FA>AAG............................................10=
O4>3ACFstring1, string2 I,IstartJ I,IlengthJ I,pad&harJJJG $ FA/S8G..................................10=
O4>3ACFstring1, string2 I,IstartJ I,IlengthJ I,pad&harJJJG $ FA/S8G.............................10=
"OO382FG $ F>.8/AG.........................................................................................................10=
"OO382FG $ F>.8/AG.....................................................................................................10=
"O">/F&ommand I,stem.JG $ F>.8/AG..............................................................................10<
"O">/F&ommand I,stem.JG $ F>.8/AG..........................................................................10<
"OSFneedle, ha(sta&- I,startJG $ FA/S8G................................................................................10<
"OSFneedle, ha(sta&- I,startJG $ FA/S8G............................................................................10<
"09>/4Fen5ironment5arRI5alueJG $ F>.8/AG.................................................................10<
"09>/4Fen5ironment5arRI5alueJG $ F>.8/AG.............................................................10<
B0A381CFIstreamidJG $ FA/S8G............................................................................................10<
B0A381CFIstreamidJG $ FA/S8G.......................................................................................10<
B0>0>2FG $ FA/S8G.............................................................................................................10<
B0>0>2FG $ FA/S8G.........................................................................................................10<
A/2O,Fma%G $ FA/S8G.....................................................................................................105
A/2O,Fma%G $ FA/S8G................................................................................................105
A/2O,FIminJ I,Ima%J I,seedJJG $ FA/S8G.........................................................................105
A/2O,FIminJ I,Ima%J I,seedJJG $ FA/S8G....................................................................105
A/20FIseedJG $ FA>AAG.................................................................................................10?
A/20FIseedJG $ FA>AAG.............................................................................................10?
>A2C!F'ile, lengthG $ FA>AAG........................................................................................10?
7
>A2C!F'ile, lengthG $ FA>AAG...................................................................................10?
>A23/F'ileG $ FA>AAG....................................................................................................10?
>A23/F'ileG $ FA>AAG...............................................................................................10?
>4>S>FstringG $ FA/S8G...................................................................................................10?
>4>S>FstringG $ FA/S8G..............................................................................................10?
8.!9Fstring, lengthI,pad&harJG $ FA/S8G............................................................................10?
8.!9Fstring, lengthI,pad&harJG $ FA/S8G.......................................................................10?
A10/CA22Fe%ternalname, librar(, internalnameG $ FSAAG.............................................10@
A10/CA22Fe%ternalname, librar(, internalnameG $ FSAAG.........................................10@
A10/C2O"Fe%ternalnameG $ FSAAG...............................................................................10@
A10/C2O"Fe%ternalnameG $ FSAAG..........................................................................10@
A10/C>,S.FG $ F>.8/AG.......................................................................................10@
A10/C>,S.FG $ F>.8/AG...................................................................................10@
A10/CB0>CFe%ternalnameG $ FSAAG............................................................................10@
A10/CB0>CFe%ternalnameG $ FSAAG.......................................................................10@
AB0>0>F&ommand I,KueueQtimeoutJG $ FOS#2G.................................................................10@
AB0>0>F&ommand I,KueueQtimeoutJG $ FOS#2G............................................................10@
S>>MF'ile, o''set, IP:eginPQPCurrentPQP>ndPG $ FA>AAG.........................................................10+
S>>MF'ile, o''set, IP:eginPQPCurrentPQP>ndPG $ FA>AAG.....................................................10+
S!ODFoption, InameJ, IpadJG $ FA>AAG............................................................................10+
S!ODFoption, InameJ, IpadJG $ FA>AAG.......................................................................10+
S8./FnumberG $ FA/S8G........................................................................................................10*
S8./FnumberG $ FA/S8G...................................................................................................10*
S3>>"Fse&ondsG $ FC,SG......................................................................................................10*
S3>>"Fse&ondsG $ FC,SG.................................................................................................10*
SO0C>38/>FIlinenoJG $ FA/S8G........................................................................................10*
SO0C>38/>FIlinenoJG $ FA/S8G...................................................................................10*
S"AC>FstringI, IlengthJ I,pad&harJJG $ FA/S8G......................................................................10*
S"AC>FstringI, IlengthJ I,pad&harJJG $ FA/S8G.................................................................10*
S9A9>FstreamidG $ FC,SG.....................................................................................................110
S9A9>FstreamidG $ FC,SG.................................................................................................110
S9OA.>FIaddressJ, IstringJ, IlengthJ, IpadJG $ FA>AAG..................................................110
S9OA.>FIaddressJ, IstringJ, IlengthJ, IpadJG $ FA>AAG.............................................110
S9>A,FstreamidI,optionI,&ommandJJG FA/S8G.................................................................110
S9>A,FstreamidI,optionI,&ommandJJG FA/S8G............................................................110
S98"Fstring I,IoptionJ I,&harJJG $ FA/S8G.............................................................................11<
S98"Fstring I,IoptionJ I,&harJJG $ FA/S8G........................................................................11<
S0:S9Fstring, start I,length I,pad&harJJG $ FA/S8G.............................................................115
S0:S9Fstring, start I,length I,pad&harJJG $ FA/S8G........................................................115
S0:DO2Fstring, start I,lengthJG $ FA/S8G.........................................................................115
S0:DO2Fstring, start I,lengthJG $ FA/S8G.....................................................................115
SC,:O3FstringG $ FA/S8G....................................................................................................115
SC,:O3FstringG $ FA/S8G...............................................................................................115
98,>FIoptionLout I,time IoptionLinJJJG $ FA/S8G.................................................................11?
98,>FIoptionLout I,time IoptionLinJJJG $ FA/S8G.............................................................11?
9AC>FIsettingJG $ FA/S8G....................................................................................................11@
9AC>FIsettingJG $ FA/S8G...............................................................................................11@
9A/S3A9>Fstring I,ItableoutJ I,ItableinJ I,pad&harJJJG $ FA/S8G......................................11+
9A/S3A9>Fstring I,ItableoutJ I,ItableinJ I,pad&harJJJG $ FA/S8G.................................11+
98,FstringG $ FA>AAG......................................................................................................11+
8
98,FstringG $ FA>AAG..................................................................................................11+
90/CFnumber I,lengthJG $ FA/S8G......................................................................................11+
90/CFnumber I,lengthJG $ FA/S8G.................................................................................11+
0/A,>FIoptionJG $ F>.8/AG.............................................................................................11*
0/A,>FIoptionJG $ F>.8/AG........................................................................................11*
0/8A>OFerrornoG $ F>.8/AG.....................................................................................11*
0/8A>OFerrornoG $ F>.8/AG................................................................................11*
0"">Fstring I,start I,length I,padJJJG E FA>AA#>.8/AG..............................................120
0"">Fstring I,start I,length I,padJJJG E FA>AA#>.8/AG.........................................120
0S>82FG $ F>.8/AG..........................................................................................................120
0S>82FG $ F>.8/AG.....................................................................................................120
4A30>Fs(mbol I,I5alueJ, IpoolJJG $ FA/S8G.........................................................................120
4A30>Fs(mbol I,I5alueJ, IpoolJJG $ FA/S8G.....................................................................120
4>81CFstring, re' I,IoptionJ I,startJJG $ FA/S8G...................................................................121
4>81CFstring, re' I,IoptionJ I,startJJG $ FA/S8G..............................................................121
DO2Fstring, 6ordnoG $ FA/S8G..........................................................................................122
DO2Fstring, 6ordnoG $ FA/S8G......................................................................................122
DO28/2>AFstring, 6ordnoG $ FA/S8G..............................................................................122
DO28/2>AFstring, 6ordnoG $ FA/S8G.........................................................................122
DO23>/.9!Fstring, 6ordnoG $ FA/S8G..........................................................................122
DO23>/.9!Fstring, 6ordnoG $ FA/S8G......................................................................122
DO2"OSFphrase, string I,startJG $ FA/S8G.........................................................................122
DO2"OSFphrase, string I,startJG $ FA/S8G....................................................................122
DO2SFstringG $ FA/S8G......................................................................................................12=
DO2SFstringG $ FA/S8G..................................................................................................12=
D89>C!F'ile, stringG $ FA>AAG.......................................................................................12=
D89>C!F'ile, stringG $ FA>AAG..................................................................................12=
D89>3/F'ile, stringG $ FA>AAG.......................................................................................12=
D89>3/F'ile, stringG $ FA>AAG..................................................................................12=
AA/.>FIstartJ I,endJG $ FA/S8G.........................................................................................12=
AA/.>FIstartJ I,endJG $ FA/S8G....................................................................................12=
A2:Fhe%stringG $ FA/S8G.......................................................................................................12=
A2:Fhe%stringG $ FA/S8G...................................................................................................12=
A2CFhe%stringG $ FA/S8G.......................................................................................................12=
A2CFhe%stringG $ FA/S8G...................................................................................................12=
A22Fhe%string I,lengthJG $ FA/S8G........................................................................................12<
A22Fhe%string I,lengthJG $ FA/S8G....................................................................................12<
=.= 8mplementation spe&i'i& do&umentation 'or egina............................................................125
=.=.1 2e5iations 'rom the Standard.......................................................................................125
=.=.2 8nterpreter 8nternal 2ebugging 1un&tions....................................................................125
A33OCA9>2FIoptionJG.........................................................................................................125
A33OCA9>2FIoptionJG....................................................................................................125
20,"9>>FG........................................................................................................................12?
20,"9>>FG...................................................................................................................12?
20,"4ASFG.......................................................................................................................12?
20,"4ASFG...................................................................................................................12?
38S93>AM>2FG.....................................................................................................................12?
38S93>AM>2FG................................................................................................................12?
9AC>:ACMFG.....................................................................................................................12?
9AC>:ACMFG................................................................................................................12?
9
=.=.= e%% 4,S 8nter'a&e 1un&tions....................................................................................12@
=.< e%%0til 'or egina.............................................................................................................12*
< Conditions....................................................................................................................................1=0
<.1 Dhat are Conditions............................................................................................................1=0
<.1.1 Dhat 2o De /eed Conditions 'orS..............................................................................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 SC/9AA &ondition...............................................................................................1=+
<.=.2 9he !A39 &ondition....................................................................................................1=*
<.=.= 9he >O &ondition.................................................................................................1=*
<.=.< 9he 1A830> &ondition..............................................................................................1<0
<.=.5 9he /O4A30> &ondition............................................................................................1<0
<.=.? 9he /O9>A2C &ondition.........................................................................................1<1
<.=.@ 9he 3OS928.89S &ondition.......................................................................................1<1
<.< 1urther /otes on Conditions................................................................................................1<2
<.<.1 Conditions under 3anguage 3e5el =.50.......................................................................1<2
<.<.2 "it'alls 6hen 0sing Condition 9raps...........................................................................1<2
<.<.= 9he Corre&tness o' this 2es&ription.............................................................................1<2
<.5 Conditions in egina...........................................................................................................1<=
<.5.1 !o6 to aise the !A39 &ondition...............................................................................1<=
<.? "ossible 1uture e%tensions...................................................................................................1<<
5 Stream 8nput and Output..............................................................................................................1<5
5.1 :a&-ground and !istori&al emar-s...................................................................................1<5
5.2 e%%Ps /otion o' a Stream...................................................................................................1<5
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............................................................................................................15<
5.10 2etermining the Current "osition......................................................................................15?
5.11 "ositioning Dithin a 1ile....................................................................................................15@
5.12 >rrors: 2is&o5er(, !andling, and e&o5er(......................................................................1?0
5.1= Common 2i''eren&es and "roblems 6ith Stream 8#O.......................................................1?1
5.1=.1 Dhere 8mplementations are Allo6ed to 2i''er..........................................................1?1
5.1=.2 Dhere 8mplementations might 2i''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.0@a........................................................................................1?5
10
5.1=.+ 1un&tionalit( to be 8mplemented 3ater......................................................................1?+
5.1=.* Stream 8#O in Ae%% 1.15..........................................................................................1?+
5.1=.10 ,ain 2i''eren&es 'rom Standard e%%....................................................................1@2
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( !a5e >%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 1ormat o' the O"98O/S &lause....................................................................................1+1
?.? 9he 1undamental >%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 381O and 181O sta&- operations..................................................................................1*0
@.2.= 0sing 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 abo5e....................................1*@
@.5.2 8mplementation o' the e%ternal sta&- in egina 2.2 and abo5e...................................1*+
r%sta&-...............................................................................................................................1*+
r%Kueue..............................................................................................................................1*+
r%Kueue :uilt$in 1un&tion.................................................................................................1**
Bueue /ames....................................................................................................................1**
Se&urit( o' >%ternal Bueues..............................................................................................1**
>n5ironment 4ariables......................................................................................................200
+ 8nter'a&ing e%% to other programs.............................................................................................201
+.1 O5er5ie6 o' 'un&tions in SAA............................................................................................201
+.1.1 8n&lude 1iles and 3ibraries...........................................................................................201
+.1.2 "repro&essor S(mbols..................................................................................................202
+.1.= 2ata stru&tures and data t(pes......................................................................................202
1.1.1.1 9he AS98/. stru&ture......................................................................................20=
1.1.2 9he ASCS>A89 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&om2llFG 'un&tion......................................................................20+
+.2.< 9he e%%2eregisterSub&omFG 'un&tion.......................................................................20*
+.2.5 9he e%%Buer(Sub&omFG 'un&tion..............................................................................210
+.= 9he >%ternal 1un&tion !andler 8nter'a&e.............................................................................211
+.=.1 Dhat is an >%ternal 1un&tion !andler.........................................................................211
+.=.2 9he e%%egister1un&tion>%eFG 'un&tion...................................................................212
11
+.=.= 9he e%%egister1un&tion2llFG 'un&tion.....................................................................212
+.=.< 9he e%%2eregister1un&tionFG 'un&tion......................................................................21=
+.=.5 9he e%%Buer(1un&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 2ire&t.......................................................................................................21*
+.5.2 9he S!4:3OCM 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 A1/C $ 9he >%ternal 1un&tion >%it !andler...................................................22@
1.1.2.2 AC,2 $ 9he Sub&ommand >%it !andler...........................................................22+
1.1.2.= A,SB $ 9he >%ternal 2ata Bueue >%it !andler................................................22*
1.1.2.< AS8O $ 9he Standard 8#O >%it !andler...............................................................2=1
1.1.2.5 A!39 $ 9he !alt Condition >%it !andler...........................................................2=2
1.1.2.? A9C $ 9he 9ra&e Status >%it !andler...............................................................2=2
1.1.2.@ A8/8 $ 9he 8nitialiHation >%it !andler................................................................2=2
1.1.2.+ A9> $ 9he 9ermination >%it !andler...............................................................2=2
1.1.2.* A>/4 $ 9he >%ternal >n5ironment >%it !andler...............................................2==
+.@ 9he >%ternal Bueue 8nter'a&e..............................................................................................2=<
+.@.1 9he e%%CreateBueueFG 'un&tion................................................................................2=<
+.@.2 9he e%%2eleteBueueFG '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%%Add,a&roFG 'un&tion....................................................................................2=*
+.+.2 9he e%%2rop,a&roFG 'un&tion...................................................................................2=*
+.+.= 9he e%%Sa5e,a&roSpa&eFG 'un&tion.........................................................................2=*
+.+.< 9he e%%3oad,a&roSpa&eFG 'un&tion.........................................................................2=*
+.+.5 9he e%%Buer(,a&roFG 'un&tion.................................................................................2=*
+.+.? 9he e%%eorder,a&roFG 'un&tion..............................................................................2=*
+.+.@ 9he e%%Clear,a&roSpa&eFG 'un&tion.........................................................................2=*
+.* Allo&ating and 2e$allo&ating Spa&e.....................................................................................2<0
+.*.1 9he e%%Allo&ate,emor(FG 'un&tion..........................................................................2<0
+.*.2 9he e%%1ree,emor(FG 'un&tion................................................................................2<0
+.10 Calling ba&- into running e%% Code................................................................................2<1
+.10.1 9he e%%Call:a&-FG 'un&tion....................................................................................2<1
* 8mplementation 3imits................................................................................................................2<=
*.1 Dh( 0se 3imitsS.................................................................................................................2<=
*.2 Dhat 3imits to ChooseS.......................................................................................................2<=
*.= eKuired 3imits...................................................................................................................2<=
*.< Older FObsoleteG 3imits.......................................................................................................2<<
*.5 Dhat the Standard does not Sa(..........................................................................................2<5
*.? Dhat an 8mplementation is Allo6ed to ;8gnore;.................................................................2<5
*.@ 3imits in egina...................................................................................................................2<?
10 egina 1eatures and 8mplementation........................................................................................2<+
12
10.1 egina estri&ted ,ode.....................................................................................................2<+
10.2 /ati5e 3anguage Support..................................................................................................2<+
10.2.1 >rror ,essages...........................................................................................................2<+
10.2.2 3o&ale Support...........................................................................................................2<*
10.2.= 0sing /ati5e 3anguage Support................................................................................2<*
10.= e%% and egina binaries: Dh(S.......................................................................................250
11 Appendi%es................................................................................................................................251
11.1 2e'initions..........................................................................................................................251
11.2 :ibliograph(.......................................................................................................................255
11.= ./0 1ree 2o&umentation 3i&ense....................................................................................25@
13
1 Introduction to Regina
This chapter provides an introduction to Regina, an Open Source Rexx Interpreter distributed
under the GNU General Library License.
1.1 Purpose of this document
9he purpose o' this do&ument is to pro5ide an o5er5ie6 o' the Rexx 3anguage and the egina
implementation o' the Rexx 3anguage. 8t is not intended as a de'initi5e re'eren&e to Rexx7 (ou
should reall( ha5e a &op( o' the Rexx ;bible;7 The Rexx Language, b( Mie !o"lisha" I932J.
1.2 Implementation
9he egina Rexx 8nterpreter is implemented as a librar( suitable 'or lin-ing into third$part(
appli&ations. A&&ess to egina 'rom third$part( appli&ations is 5ia the egina A"8, 6hi&h is
&onsistent 6ith the 8:,Ps Rexx SAA A"8. 9his A"8 is implemented on most other Rexx
interpreters.
9he librar( &ontaining egina is a5ailable 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 Rexx e%ternal 'un&tion pa&-ages 5ia the built$in 'un&tion7 %1un&Add, is onl( a5ailable 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'
Rexx programs dire&tl( 'rom the &ommand line. 9he co##and line re'erred to here relates to the a
0ni% shell, an OS#2 or 2OS &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 5ia the %1un&Add 'un&tion, is onl( a5ailable b( running the
d(nami& e%e&utable.
14
1.3 Ports of Regina
egina has been ported to man( operating s(stems. 9he 'ollo6ing table pro5ides implementation
details o' ea&h o' the ports o' egina.
Operating System Static
Library
Dynamic
Library
Dynamic
Library
ThreadSae
Dynamic
!"ec#tab$e
Static
!"ec#tab$e
Lin#" libregina.a libregina.so Ces regina re%%
%&'() libregina.a libregina.sl /o regina re%%
*+) libregina.a libregina.a Ces regina re%%
Other (ni" libregina.a libregina.so ,a(be regina re%%
32'bit DOS
,D-.&&/
,(ses D&0+
mem1ry manager/
libregina.a /#A /o /#A re%%.e%e
32'bit DOS ,!0)/
,(ses 23&+ mem1ry
manager/
regina.a /#A /o /#A re%%.e%e
OS42 ,!0)/ regina.a regina.dll
Fregina.libG
Ces regina.e%e re%%.e%e
OS42
,Open5atc1m/
re%%.lib regina.dll
Fregina.libG
/o regina.e%e re%%.e%e
5ind16s 32bit
5ind16s 64bit
re%%.lib regina.dll
Fregina.libG
Ces regina.e%e re%%.e%e
7eOS libregina.a libregina.so /o regina re%%
*migaOS libregina.a /#A /o /#A re%%
!&O332 /#A /#A /o /#A re%%.e%e
*theOS4Sy$$ab$e libregina.a libregina.so /o regina re%%
89) 4:2" re%%.lib /#A /o /#A re%%
89) 6:" libregina.a libregina.so Ces regina re%%
0acOS ) 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 Regina
Rexx programs are generall( e%e&uted b( egina 'rom the co##and line in the 'ollo6ing manner:
regina Is"itchesJ IprogramJ Iprogra# para#etersJ
15
6here:
regina is the name o' the egina e%e&utable Fsee table abo5eG
s"itches are optional s6it&hes. See the se&tion belo6 'or an e%planation o' the
s6it&hes &urrentl( supported b( egina
pr1gram the name o' the Rexx program to be e%e&uted. See the se&tion
!"terna$ Rexx &r1grams, belo6, 'or details on ho6 egina
interprets this argument. 8' no program name is spe&i'ied, egina
6aits 'or Rexx &ommands to be t(ped in and 6ill e%e&ute those
&ommands 6hen the appropriate end$o'$'ile &hara&ter FT2 on 0ni%
and TN on 2OS, OS#2 and Dindo6s /9#*5G is t(ped.
progra# para#eters an( optional parameters to be passed to the Rexx program.
Rexx programs to be e%e&uted b( egina on 0ni% plat'orms &an ta-e ad5antage o' a 'eature o'
0ni% shell programs &alled #agic nu#bers. :( ha5ing the 'irst line o' a Rexx program &onsist o'
the spe&ial seKuen&e o' <= 'ollo6ed b( the 'ull 'ile name o' the egina e%e&utable, (ou &an in5o-e
this program simpl( b( t(ping the name o' the Rexx program on the co##and line 'ollo6ed b( an(
parameters (ou 6ish to pass to the Rexx program. 9he 'ile name must also ha5e the appropriate
e%e&ute bit set 'or this to 6or-. As an e%ample suppose (our Rexx program, mypr1g, &ontained:
#!/usr/local/bin/regina
Parse Version ver
Say ver
Dhen e%e&uting this program 'rom the co##and line b( t(ping mypr1g, the 0ni% shell program
6ould e%e&ute the program /usr/local/bin/regina and pass the remainder o' the lines in
the 'ile to this program 5ia stdin.
9he spe&ial pro&essing done b( egina to 'ind the 'ile name in >!.+9*?0*3>OS and the 'ile
e%tension sear&hing is ignored 'or the program to be run 6hen using the magi& number method o'
in5o&ation, but is still done inside the program 6hen using 3*LL.
1.4.1 !itches
9he 'ollo6ing s6it&hes allo6 the user to &ontrol ho6 egina e%e&utes the supplied Rexx program.
S6it&hes are re&ognised b( a leading h(phen &hara&ter7 P'P, 'ollo6ed immediatel( b( a single
alphabeti& &hara&ter. Some s6it&hes allo6 'or optional parameters. 9hese, too must 'ollo6 the
s6it&h 6ithout an( inter5ening spa&es. All s6it&hes and their optional parameters are &ase$
sensiti5e. S6it&hes that ta-e no option &an be &ombined. e.g. U$arpV
$tItrace para#eterJ 9urn on the spe&i'ied tra&ing le5el. 9he optional trace para#eter
indi&ates the tra&ing le5el to be used. See the 9AC> &ommand later
in this do&ument 'or an e%planation o' ea&h tra&e le5el. 0se o' this
s6it&h 6ill result in an( 9AC> &ommands in the program to be
ignored.
$a Dithout this s6it&h, all &ommand line parameters are passed to
egina as a single argument. Spe&i'(ing $a, ensures that the Rexx
program in5o-ed has a&&ess to the &ommand line parameters as
separate arguments, as passed 'rom the &ommand line interpreter. i.e.
9he :81 A.FG &an return a 5alue o' other than 1 or 0. Also "AS>
16
SO0C> 6ill return S0:O098/> instead o' the normal
CO,,A/2 5alue.
$r un egina in restri&ted mode. See the se&tion on egina estri&ted
,ode 'or more details.
$5 2ispla(s the 5ersion in'ormation 'or the e%e&utable run. 9he string
displa(ed is the same that is returned b( &*>S! SO(>3!. 9he
5ersion string pro5ides an indi&ator as to 6hether the egina librar( is
thread$sa'e or not. 8' the 'irst 6ord ends inUF,9GV, then the librar( is
thread$sa'e. 9his s6it&h, e%e&uted b( the static e$ecutable, 6ill al6a(s
result in noUF,9GVindi&ator.
$lIlocaleJ 8ndi&ates 6hi&h national lo&ale that egina is to use 'or 7+@s li-e
T>*9SL*T!, LO5!>, or (&&!>. /o 5alidation is done on the
spe&i'ied lo&ale. 9he a''e&ted beha5iour is de'ined in Se&tion 27
U/ati5e 3anguage SupportV.
9he locale is passed to the underl(ing C librar(, 6hi&h resol5es the
des&riber in a s(stem spe&i'i& 6a(. An omitted locale lets the s(stem
&hoose the &urrent pre$sele&ted lo&ale 'or the user. 9his is the usual
option 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 en5ironment 5ariable, see Se&tion
10.27/ati5e 3anguage Support7 this 5ariable &an be used to sele&t a
lo&ale, too.
9he te%t o' the locale is eKui5alent to those o' the en5ironment
5ariables LANG or LC_CTYPE or the 5alue used in registries, et&.
>%amples are en_US.ISO-8859-1 or nglis!_US".1#5# 'or
some s(stems.
$oO"98O/S 9his s6it&h spe&i'ies the 5alues 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
o5er6rites >.8/ALO"98O/S
$p 9his s6it&h &auses egina to pause on e%it. 9his is onl( 5alid on most
plat'orms. 9his s6it&h is use'ul i' (ou run Rexx programs 'rom a
.08 'ile manager and 6ant to see the output 'rom that program.
$& !o#pile the spe&i'ied pr1gram into a to-enised 'ormat. 9he onl(
program parameters 6hen using this s6it&h is the 'ilename 'or the
to-enised program. i.e. regina $& pr1gram 'ilename
$e %$ecute the spe&i'ied program 'rom a to-enised 'ormat. pr1gram
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 Rexx programs, using a &ombination o' the >!.+9*?0*3>OS
en5ironment 5ariable, the &*T% en5ironment 5ariable, the >!.+9*?S(@@+)!S en5ironment
5ariable and the addition o' 'ilename e%tensions. 9his rule applies to both e%ternal 'un&tion &alls
6ithin a Rexx program and the pr1gram spe&i'ied on the co##and line.
1irst o' all 6e pro&ess the en5ironment 5ariable >!.+9*?0*3>OS. 8' no 'ile is 'ound 6e
pro&eed 6ith the &urrent dire&tor( and then 6ith the en5ironment 5ariable &*T%. 9he semanti&s o'
the use o' >!.+9*?0*3>OS and &*T% are the same, and the sear&h in the &urrent dire&tor( is
omitted 'or the superuser on 0ni% s(stems 'or se&urit( reasons. 9he &urrent dire&tor( must be
17
spe&i'ied e%pli&itl( b( the superuser.
Dhen pro&essing an en5ironment 5ariable, 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,C"O.; is &alled, then no sear&hing o'
>!.+9*?0*3>OS or &*T% is done7 onl( the &on&atenation o' su''i%es is &arried out.
1or 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 2OS, Dindo6s,
and OS#2.
9he 'irst mat&hing 'ile terminates the 6hole algorithm and the 'ound 'ile is returned.
9he en5ironment 5ariable >!.+9*?S(@@+)!S e%tends the list o' -no6n su''i%es as spe&i'ied
abo5e, and is inserted a'ter the e#pty e%tension in the pro&ess. >!.+9*?S(@@+)!S has 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 5ersion =.< to allo6 'or
seamless integration o' pre$&ompiled ma&ros.
Example" #ocating an external Rexx program for execution
Assume (ou ha5e 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:cmd e%ists in the dire&tor( #opt#re%%#, and that
&*T%R#usr#bin:#opt#re%%, >!.+9*?0*3>OS is n1t set, and >!.+9*?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
#opt#re%%#m(e%t'un&.re%
#opt#re%%#m(e%t'un&.&md #X 'oundYY terminate sear&hX#
19
2 Rexx #anguage Constructs
In this chapter, the concept and synta$ o& Rexx clauses are e$plained. 't the end o& the chapter
there is a section describing ho" Regina di&&ers &ro# standard Rexx as described in the &irst part
o& the chapter.
2.1 $efinitions
A program in the Rexx language &onsists o' &lauses, 6hi&h are di5ided into 'our groups: null
&lauses, &ommands, assignments, and instru&tions. 9he three latter groups F&ommands, assignments,
and instru&tionsG are &olle&ti5el( re'erred to as statements. 9his does not mat&h the terminolog( in
I932J, 6here ;instru&tion; is eKui5alent to 6hat is -no6n here as ;statement;, and ;-e(6ord
instru&tion; is eKui5alent to 6hat is -no6n here as ;instru&tion;. !o6e5er, 8 'ind the terminolog(
used here simpler and less &on'using.
8n&identall(, the terminolog( used here mat&hes I2A/>CJ.
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, pro5ided 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 ha5e the abilit( to store a te%t 'ile ha5ing 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. 0ni% and ,S$2OS s(stems. 0nder 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. !o6e5er, some interpreters are li-el( to regard the end$o'$'ile as a
&lause delimiter too. 9he 'un&tionalit( o' I+,.P., gi5es some 6eight to this interpretation. :ut
other s(stems ma( ignore that last, unterminated line, or ma(be issue a s(nta% error. F!o6e5er,
there is no S*+,"- &ondition number adeKuatel( &o5ering this situation.
Example" %inar& transferring files
Suppose a Rexx program is stored on an ,S$2OS ma&hine. 9hen, an end$o'$line seKuen&e is
mar-ed in the 'ile as the t6o &hara&ters &arriage return and ne6line. 8' this 'ile is trans'erred to a
0ni% s(stem, then onl( ne6line mar-s the end$o'$line. 1or 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 0ni% s(stem,
ea&h line seems to &ontain a trailing &arriage return &hara&ter. 8n an editor, it might loo- li-e this:
20
say /!ello 0orl1/23
say /'!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 e5er( 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%t
on ea&h line an independent &omment, as sho6n belo6:
'race all
/5
,!is is a single) large co%%en') 0!ic! s6ans %ul'i6le
lines.
Suc! co%%en's are o('en use1 a' '!e s'ar' o( a subrou'ine
or si%ilar) in or1er 'o 1escribe bo'! '!e in'er(ace 'o an1
'!e (unc'ionali'y o( '!e (unc'ion.
5/
/5 ,!is is also a large co%%en') bu' i' is 0ri''en as 5/
/5 %ul'i6le co%%en's) eac! on i's o0n line. ,!us) '!ese 5/
/5 are several clauses 0!ile '!e co%%en' above is a 5/
/5 single co%%en'. 5/
-- ,!ese lines also consis' o( %ul'i6le co%%en's) an1 '!us
-- %ul'i6le clauses. ,!is (or% o( co%%en' 0as in'ro1uce1
-- in .egina 7.8
2uring tra&ing, the 'irst o' these 6ill be displa(ed as one large &omment, and during intera&ti5e
tra&ing, it 6ill onl( pause on&e. 9he se&ond 6ill be displa(ed as multiple lines, and 6ill ma-e
se5eral pauses during intera&ti5e tra&ing. An interpreter ma( sol5e this situation in se5eral 6a(s, the
main ob\e&ti5e 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 ,9+ sub&lause, onl( a statement
is e%pe&ted. 8' a null &lause is pro5ided, then it is ignored, and the ne%t statement is used instead.
21
Consider the 'ollo6ing &ode:
6arse 6ull (oo
i( (oo:# '!en
say /(oo is no' #/
else
/5 1o no'!ing 5/
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 ;S reads be(ond the &omment, and &onne&ts to the S"* instru&tion 6hi&h
be&omes the ;S part. F9hat 6hat probabl( not 6hat the programmer intended.G 9his &ode 6ill
sa( '!a'/s i', onl( 6hen (oo is di''erent 'rom #. A separate instru&tion, +OP has been
pro5ided in order to 'ill the need that 6as inadeKuatel( attempted 'illed b( the &omment in the &ode
'ragment abo5e.
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% : <
1o i:1 'o 1<
/5 su% 1 # 7 ... 8 9 1< 5/
su% : su% = i
en1
su% : <
1o i:1 'o 1<
su% : su% = i /5 su% 1 # 7 ... 8 9 1< 5/
en1
8n the 'irst loop, there are t6o &lauses, 6hile the se&ond loop &ontains onl( one &lause, be&ause the
&omment is appended to an alread( e%isting &lause. 2uring e%e&ution, the interpreter has to spend
time ignoring the null &lause in the 'irst loop, 6hile the se&ond loop a5oids this problem Fassuming
tra&ing is not enabledG. 9hus, the se&ond loop is 'aster7 although onl( insigni'i&antl( 'aster 'or
small loops. O' &ourse, the &omment &ould ha5e been ta-en out o' the loop, 6hi&h 6ould be eKuall(
'ast to the se&ond 5ersion abo5e.
22
2.3 Commands
2.3.1 (ssignments
Assignments are &lauses 6here the 'irst to-en is a s(mbol and the se&ond to-en is the eKual sign
F:G. 9his de'inition opens 'or some &urious e''e&ts, &onsider the 'ollo6ing &lauses:
a == b
9his is not a &ommand, but an assignment o' the e%pression : b to the 5ariable a. O'
&ourse, the e%pression is illegal F:bG and 6ill trigger a S*+,"- &ondition 'or s(nta% error
Z=5[. 932 de'ines the operator :: as &onsisting o' t6o to-ens. 9hus, in the 'irst o' these
e%amples, the se&ond to-en is :, the third to-en is also :, 6hile the 'ourth to-en is b.
3 = 5
9his is an assignment o' the 5alue 5 to the s(mbol 7, but sin&e this is not a 5ariable s(mbol,
this is an illegal assignment, and 6ill trigger the S*+,"- &ondition 'or s(nta% error Z=1[.
"hello" = foo
9his is not an in5alid assignment, sin&e the 'irst to-en in the &lause is not a s(mbol. 8nstead,
this be&omes a &ommand.
arg =(foo) bar
9he 'ourth statement is a 5alid assignment, 6hi&h 6ill spa&e$&on&atenate the t6o 5ariable
s(mbols (oo and bar, and assign the result to the 5ariable s(mbol arg. 8t is spe&i'i&all(
not an ".> instru&tion, e5en 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 5alue to a simple 5ariable, a stem 5ariable or a &ompound 5ariable.
Dhen assigning to a stem 5ariable, all possible 5ariable s(mbols ha5ing that stem are assigned the
5alue. /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 5alue &an be seen 'rom the
'ollo6ing &ode:
(oo. : /bar/
(oo.1 : /ba?/
1ro6 (oo.1
say (oo.1 /5 says 4@OO.14 5/
!ere, the S"* instru&tion 6rites out @OO.1, not bar. 2uring the A.OP instru&tion, the 5ariable
@OO.1 regains its original, uninitialiHed 5alue @OO.1, not the 5alue o' its stem 5ariable @OO., i.e.
bar, be&ause stem assignments does not set up a de'ault.
23
Example" Emulating a default *alue
8' (ou 6ant to set the &ompound 5ariable to the 5alue o' its stem 5ariable, i' the stem is initialiHed,
then (ou ma( use the 'ollo6ing &ode:
i( Bsy%bolB/(oo./CC '!en
(oo.1 : (oo.
else
1ro6 (oo.1
8n this e%ample, the @OO.1 5ariable is set to the 5alue o' its stem i' the stem &urrentl( is assigned a
5alue. >lse, the @OO.1 5ariable is dropped.
!o6e5er, this is probabl( not e%a&tl( the same, sin&e the internal storage o' the &omputer is li-el(
to store 5ariables li-e @OO.# and @OO.7 onl( impli&itl( Fa'ter all, it &an not e%pli&itl( store e5er(
&ompound ha5ing @OO. as stemG. A'ter the assignment o' the 5alue o' @OO. to @OO.1, the @OO.1
&ompound 5ariable is li-el( to be e%pli&itl( stored in the interpreter.
9here is no 6a( (ou &an dis&o5er the di''eren&e, but the e''e&ts are o'ten that more memor( is used,
and some 'un&tionalit( that dumps all 5ariables ma( dump @OO.1 but not @OO.# F6hi&h is
in&onsistentG. See se&tion e%%4ariable"ool.
Example" !pace considerations
>5en more strange are the e''e&ts o' the 'ollo6ing short e%ample:
(oo. : /bar/
1ro6 (oo.1
Although apparentl( 5er( simple, there is no 6a( that an interpreter &an release all memor(
re'erring to @OO.1. A'ter all, @OO.1 has a di''erent 5alue than @OO.#, @OO.7, et&., so the
interpreter must store in'ormation that tells it that @OO.1 has the uninitialiHed 5alue.
9hese &onsiderations ma( seem li-e nit$pi&-ing, but the( 6ill matter i' (ou drop lots o' &ompound
5ariables 'or a stem 6hi&h has pre5iousl( re&ei5ed a 5alue. Some programming idioms do this, so
be a6are. 8' (ou &an do 6ithout assigning to the stem 5ariable, then it is possible 'or the interpreter
to regain all memor( used 'or that stemPs &ompound 5ariables.
2.4 Instructions
8n this se&tion, all instru&tions in standard Rexx are des&ribed.
>%tensions are listed later in this &hapter.
1irst some notes on the terminolog(. Dhat is &alled an instru&tion in this do&ument is eKui5alent to
a ;unit; o' &lauses. 9hat is, ea&h instru&tion &an &onsist o' one or more &lauses. 1or 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
i( a:b '!en
say /!ello/
else
say /bye/
1urther, the ,9+ or ;S parts o' this instru&tion might &onsist o' a AO#+A pair, in 6hi&h &ase
the I@ instru&tion might &onsists o' an 5irtuall( 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 Rexx program. Dhene5er something is 6ritten in italic 'ont, it means that the term should
be substituted 'or another 5alue, 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.
Dhene5er a pair o' &url( bra&es is used, it &ontains t6o or more sub&lauses that are separated b(
the 5erti&al bar FDG. 8t means that the &url( bra&es 6ill be substituted 'or one o' the sub&lauses it
&ontains.
Dhene5er 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.
Dhene5er the 5erti&al bar D is 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&iati5e F&an be used in seKuen&eG, and it has lo6er priorit( than the sKuare
bra&-ets Fthe s&ope o' the 5erti&al bar lo&ated 6ithin a pair o' sKuare bra&-ets or &url( bra&es is
limited to the te%t 6ithin those sKuare bra&-ets or &url( bra&es.
Dhene5er a semi&olon FEG is used in the s(nta% diagram, it indi&ates that a &lause separator
must be present at the point. 8t ma( either be a semi&olon &hara&ter, or an end$o'$line.
Dhene5er the s(nta% diagram is spread out o5er more lines, it means that an( o' the lines &an
be used, but that the indi5idual lines are mutuall( e%&lusi5e. Consider the s(nta%:
S"* symbol
string
9his is eKui5alent to the s(nta%:
S"* Fsymbol D string G
:e&ause in the 'irst o' these t6o s(nta%es, the S"* part ma( be &ontinued at either line.
Sometimes the s(nta% o' an instru&tion is so &omple% that parts o' the s(nta% has been e%tra&ted,
and is sho6n belo6 in its e%panded state. 9he 'ollo6ing is an e%ample o' ho6 this loo-s:
25
S"* so%e'!ing ,O so%eone
so%e'!ing H : 9I
9;;O
I*
so%eone H : ,9 IOSS
*OU. +I>9IO.
Cou &an generall( identi'( these situations b( the 'a&t that the( &omes a bit belo6 the real
s(nta% diagram, and that the( &ontains a &olon &hara&ter a'ter the name o' the term to be
e%panded.
8n the s(nta% diagrams, some generi& names ha5e been used 'or the 5arious parts, in order to
indi&ate &ommon attributes 'or the term. 1or instan&e, 6hene5er a term in the s(nta% diagrams is
&alled e$pr, it means that an( 5alid Rexx e%pression ma( o&&ur instead o' that term. 9he most
&ommon su&h names are:
condition
8ndi&ates that the sub&lause &an be an( o' the names o' the &onditions, e.g. S*+,"-,
+OV";U, 9";,, et&.
e$pr
8ndi&ates that the sub&lause &an be an( 5alid Rexx e%pression, and 6ill in general be
e5aluated as normal during e%e&ution.
state#ent
8ndi&ates that e%tra &lauses ma( be inserted into the instru&tion, and that e%a&tl( one o' them
must be a true statement.
string
8ndi&ates that the sub&lause is a &onstant string, i.e. either en&losed b( single Kuotes FP...PG or
double Kuotes F;...;G.
sy#bol
8ndi&ates that the sub&lause is a single s(mbol. 8n general, 6hene5er sy#bol is used as the
name 'or a sub&lause, it means that the s(mbol 6ill not automati&all( be e%panded to the
5alue o' the s(mbol. :ut instead, some operation is per'ormed on the name o' the s(mbol.
te#plate
8ndi&ates that the sub&lause is a parsing template. 9he e%a&t s(nta% o' this is e%plained in a
&hapter on tra&ing, to be 6ritten later.
8n addition to this, 5ariants ma( also e%ist. 9hese 5ariants 6ill ha5e an e%tra letter or number
appended to the name o' the sub&lause, and is used 'or di''ering bet6een t6o or more sub&lauses
ha5ing the same ;t(pe; in one s(nta% diagram. 8n the &ase o' other names 'or the sub&lauses, these
are e%plained in the des&ription o' the instru&tion.
2.4.1 The ($$RE!! Instruction
"AA.SS F environment F command G F redirection G G E
F F V";U G expr F redirection G G E
26
redirection H : JI,9 input_redir Foutput_redirG Ferror_redirG
JI,9 input_redir Ferror_redirG Foutput_redirG
JI,9 output_redir Finput_redirG Ferror_redirG
JI,9 output_redir Ferror_redirG Finput_redirG
JI,9 error_redir Finput_redirG Foutput_redirG
JI,9 error_redir Foutput_redirG Finput_redirG
input_redir H : I+PU, +O.3";
I+PU, io
output_redir H : OU,PU, +O.3";
OU,PU, F "PP+A D .P;"$ G io
error_redir H : ..O. +O.3";
..O. F "PP+A D .P;"$ G io
io H : K S,."3 D S,3 D ;I@O D @I@O L symbol
K S,."3 D ;I@O D @I@O L string
De 6ill dis&uss redire&tion later.
9he "AA.SS instru&tion &ontrols 6here &ommands to an e%ternal en5ironment are sent. 8' both
environ#ent and co##and are spe&i'ied, the gi5en &ommand 6ill be e%e&uted in the gi5en
en5ironment. 9he e''e&t is the same as issuing an e%pression to be e%e&uted as a &ommand Fsee
se&tion CommandsG, e%&ept that the en5ironment in 6hi&h it is to be e%e&uted &an be e%pli&itl(
spe&i'ied in the "AA.SS &lause. 8n this &ase, the spe&ial 5ariable .$ 6ill be set as usual, and the
..O. or @"I;U. &onditions might be raised, as 'or normal &ommands. Starting 6ith egina =.0
the spe&ial 5ariables ..$ and ..S are set too, a&&ording to the A/S8 standard.
8n other 6ords: All nor#al &ommands are A22>SS statements 6ith a suppressed -e(6ord and
en5ironment.
9he environ#ent term must be a s(mbol or a literal string. 8' it is a s(mbol, its ;name; is used, i.e. it
is not tail substituted or s6apped 'or a 5ariable 5alue. 9he co##and and e$pression terms &an be
an( Rexx e%pression. eg.
S*S,3:/P",9/
"AA.SS S*S,3 4ec!o 9ello4
is eKui5alent to a plain
"AA.SS S*S,3 4ec!o 9ello4
or
"AA.SS 4S*S,34 4ec!o 9ello4
'or the e%ternal echo &ommand.
A s(mbol spe&i'ied as an en5ironment name isnPt &ase$sensiti5e, 6hereas a string must mat&h the
&ase. :uilt$in en5ironments are al6a(s upper&ased.
Rexx maintains a list o' en5ironments, the siHe o' this list is at least t6o. 8' (ou sele&t a ne6
en5ironment, it 6ill be put in the 'ront o' this list. /ote that i' co##and is spe&i'ied, the &ontents o'
27
the en5ironment sta&- is not &hanged. 8' (ou omit co##and, environ#ent 6ill al6a(s be put in the
'ront o' the list o' en5ironments. Regina has an in'inite list and ne5er pushes out an( entr(.
"ossible 5alues are listed belo6. 8' (ou suppl( a co##and 6ith the "AA.SS statement, the
environ#ent is interpreted as a temporar( &hange 'or \ust this &ommand.
Dhat happens i' (ou spe&i'( an en5ironment that is alread( in the list, is not &ompletel( de'ined.
Stri&tl( spea-ing, (ou should end up 6ith both entries in the list pointing to the same en5ironment,
but some implementations 6ill probabl( handle this b( reordering the list, lea5ing the sele&ted
en5ironment in the 'ront. 9his is eginaPs beha5ior. >5er( en5ironment e%ists onl( on&e. 9he
redire&tion &ommand belo6 al6a(s &hanges the beha5ior o' one $$ the gi5en $$ en5ironment. Cou
&an imagine a set o' pla(ing &ards in (our hand. 9he operation is to dra6 one &ard b( name and put
it to the 'ront.
8' (ou do not spe&i'( an( sub-e(6ords or parameters to "AA.SS, the e''e&t is to s6ap the t6o
'irst entries in the list o' en5ironments. ConseKuentl(, e%e&uting "AA.SS multiple times 6ill
toggle bet6een t6o en5ironments.
9he se&ond s(nta% 'orm o' "AA.SS is a spe&ial &ase o' the 'irst 'orm 6ith co##and omitted. 8'
the 'irst to-en a'ter "AA.SS is V";U, then the rest o' the &lause is ta-en to be an e%pression,
naming the en5ironment 6hi&h is to be made the &urrent en5ironment. 0sing V";U ma-es it
possible to &ir&um5ent the restri&tion that the name o' the ne6 en5ironment must be a s(mbol or
literal string. !o6e5er, (ou &an not &ombine both V";U and co##and in a single &lause.
>%ample: >%amples o' the "AA.SS instru&tion
3etPs loo- at some e%amples, the( &an sometimes be &ombined 6ith a redire&tion:
"AA.SS $O33"+A
"AA.SS S*S,3 /co6y/ (ro%(ile 'o(ile
"AA.SS sys'e%
"AA.SS V";U ne0env
"AA.SS
"AA.SS Bol1envC
9he 'irst o' these sets the en5ironment $O33"+A as the &urrent en5ironment.
9he se&ond per'orms the &ommand /co6y/ in the en5ironment S*S,3, using the 5alues o' the
s(mbols (ro%(ile and 'o(ile as parameters. /ote that this 6ill not set S*S,3 as the &urrent
en5ironment.
9he third e%ample sets S*S,3 as the &urrent en5ironment Fit 6ill be automati&all( &on5erted to
upper &aseG.
9he 'ourth e%ample sets as the &urrent en5ironment the &ontents o' the s(mbol ne0env, pushing
28
S*S,3 do6n one le5el in the sta&-.
9he 'i'th &lause s6aps the t6o uppermost entries on the sta&-7 and S*S,3 ends up at the top
pushing the en5ironment spe&'ied in ne"env belo6 it.
9he si%th &lause is eKui5alent to the 'ourth e%ample, but is not allo6ed b( A/S8. Sin&e egina =.0
this st(le is depre&ated and &anPt be used i' OP,IO+S S,.I$,_"+SI is in e''e&t. Again, a5oid
this -ind o' "AA.SS statement st(le, and use the V";U 5ersion instead.
>%ample: 9he V";U sub-e(6ord
3et us loo- a bit &loser at the last e%ample. /ote the di''eren&es bet6een the t6o &lauses:
"AA.SS +V
"AA.SS V";U +V
9he 'irst o' these sets the &urrent de'ault en5ironment to +V, 6hile the se&ond sets it to the 5alue
o' the s(mbol +V.
8' (ou are still &on'used, donPt "ani&7 the s(nta% o' "AA.SS is some6hat biHarre, and (ou should
not put too mu&h e''ort into learning all aspe&ts o' it. Oust ma-e sure that (ou understand ho6 to use
it in simple situations. Chan&es are that (ou 6ill not ha5e use 'or its more &ompli&ated 5ariants 'or
Kuite some time.
9hen, 6hat names are legal as en5ironmentsS Dell, that is implementation$spe&i'i&, but some
names seems to be in &ommon use. 9he name $O33"+A is sometimes used to re'er to an
en5ironment that sends the &ommand to the operating s(stem. 3i-e6ise, the name o' the operating
s(stem is o'ten used 'or this F$3S, U+I-, et&.G. Cou ha5e to &onsult the implementation spe&i'i&
do&umentation 'or more in'ormation about this. A&tuall(, there is not reall( an( restri&tions on 6hat
&onstitutes a legal en5ironment name Fe5en the nullstring is legalG. Some interpreters 6ill allo6 (ou
to sele&t an(thing as the &urrent en5ironment7 and i' it is an illegal name, the interpreter 6ill
&omplain onl( 6hen the en5ironment is a&tuall( used. Other implementations ma( not allo6 (ou to
sele&t an in5alid en5ironment name at all.
Regina allo6s e5er( name as an en5ironment name. Regina gi5es an error message about 6rong
names onl( 6hen the name is used. 9he error string loo-s some6hat strange i' Regina is used as a
separate program, sin&e the e%tension o' the en5ironment name spa&e is onl( use'ul 6hen running
as part o' a program 6hi&h e%tends the standard names.
Regina uses three -inds o' en5ironments. Some ha5e alias names. 9he en5ironment names are:
S*S,3
alias OS#+VI.O+3+,
alias +VI.O+3+,
9his is the de'ault en5ironment 6hi&h is sele&ted at startup. 9he standard operating s(stem
&ommand line interpreter 6ill be loaded to e%e&ute the &ommands. Cou &an use the built$in
&ommands o' the &ommand line interpreter, o'ten &alled shell, or an( other program 6hi&h
29
the &ommand line interpreter &an 'ind and load.
$O33"+A
alias $3A
alias P",9
9his en5ironment loads the named program dire&tl(. Cou ma( suppl( a path i' this is needed
'or the &urrent operating s(stem to load the program, other6ise Regina uses the standard
operating s(stem sear&h rules 'or programs. 9his is done b( sear&hing through the items o'
the "A9! s(stem$en5ironment 5ariable in most operation s(stems. Cou &anPt use built$in
shell 'un&tionalit( li-e s(stem redire&tions li-e (ou &an 6ith SCS9>,. Regina's
redire&tions are more po6er'ul and 6or- in either en5ironment.
.--
alias .>I+"
9his en5ironment uses a ne6 instan&e o' the Regina interpreter program to e%e&ute a
program. 9he program has to be a Rexx s&ript. 9his en5ironment has se5eral ad5antages.
9he output o' a s&ript &an be redire&ted, the pro&ess is independent and a ris- o' a &rash is
minimiHed 6hen pla(ing 6ith e%ternal libraries, 'inall(, Regina itsel' tries to 'ind the
&orre&t Rexx interpreter b( itsel' and does e5er(thing to &reate a ne6 in&arnation o'
Regina.
9he de'inition o' Rexx sa(s nothing about 6hi&h en5ironment is presele&ted 6hen (ou in5o-e the
interpreter, although 93 de'ines that one en5ironment is automati&all( presele&ted 6hen starting
up a Rexx s&ript. /ote that there is no +O+ en5ironment in standard Rexx, i.e. an en5ironment
that ignores &ommands, but some interpreters implement the ,."$ setting SSS to a&&omplish this.
Regina uses the en5ironment S*S,3 as the presele&ted en5ironment as mentioned abo5e. ,ore
implementation spe&i'i& details &an be 'ound in the se&tion implementation spe&i'i& do&umentation
'or Regina.
9he list o' en5ironments 6ill be sa5ed a&ross subroutine &alls7 so the e''e&t o' an( "AA.SS
&lauses in a subroutine 6ill &ease upon return 'rom the subroutine.
($$RE!! Redirections
AN! de'ines redire&tions 'or the "AA.SS statement. 9his 'eature has been missing 'rom Regina
until 5ersion =.07 although (ou ha5e had the &han&e to redire&t input and output b( using L+@O>
and >@+@O modi'iers on &ommand strings.
9hese &ommand modi'iers still e%ist and ha5e a higher pre&eden&e than the AN! de'ined
redire&tions. /ote, that L+@O and @+@O &an be used b( the ne6er redire&tion s(stem. :ut, 'irst o'
all, some e%amples sho6 the usage o' "AA.SS redire&tions.
30
ADDRESS SYSTEM "sort" WITH INPUT STEM names. OUTPUT STEM
names.
ADDRESS SYSTEM "myprog" WITH INPUT STEM somefood. OUTPUT
STREAM 'prg.out' ERROR STEM oops.
ADDRESS PATH WITH INPUT FIFO '' OUTPUT NORMAL
ADDRESS SYSTEM WITH INPUT FIFO '' OUTPUT FIFO '' ERROR NORMAL
ADDRESS SYSTEM "fgrep 'bongo'" WITH INPUT STREAM 'feeder'
9he 'irst &ommand instru&ts the de'ault &ommand line interpreter to &all the program &alled sort.
9he input 'or the &ommand is read 'rom the stem na#es. Fnote the trailing periodG and the output is
sent ba&- to the same stem 5ariable a'ter the &ommand terminates. 9hus, bothering about the
implementation o' a 'ast sort algorithm 'or a stem is as simple as &alling a program 6hi&h &an
a&tuall( do the sort.
A program &alled #yprog is &alled in the se&ond &ase. 9he input is 'et&hed 'rom the stem so#e&ood.
Fagain note the trailing periodG, and the standard output o' the program is redire&ted to the stream
&alled prg.out. An( generated error messages 5ia the standard error stream are redire&ted to the stem
&alled oops.
8n the third e%ample, the redire&tion beha5ior o' the en5ironment "A9! is &hanged 'or all 'uture
uses. 9he input 'or all &ommands addressed to this en5ironment is 'et&hed 'rom the standard sta&-
in 181O order. A'ter ea&h &all the sta&- 6ill be 'lushed. 9he output is sent to the de'ault output
stream, 6hi&h is the &urrent &onsole in most &ases. 9he beha5ior 'or error messages is not &hanged.
9he 'ourth e%ample allo6s pipes bet6een &ommands in the en5ironment7 SCS9>, 'or all 'uture
uses. 9he input is 'et&hed 'rom the de'ault sta&- and sent to the de'ault sta&- a'ter ea&h &ommand.
9he sta&- itsel' is 'lushed in bet6een. >a&h e%e&uted program 6ill 6rite to something 6hi&h is the
input to the ne%t &alled &ommand. 9he error redire&tion is set or set ba&- to the initial beha5ior o'
6riting to the standard error stream.
9he 'i'th e%ample relates to the 'ourth. 9he de'ault sta&- has to be 'illed 6ith something initiall(.
9his is done b( the redire&tion to the stream U'eederV 6hile 6riting the output o' the &grep
&ommand to the de'ault 181O as de&lared in e%ample 'our. A'ter this, a single line 6ith a simple
sort &ommand 6ill sort the output o' &grep and pla&e it in the de'ault sta&-. Cou &an 'et&h the 'inal
output o' (our pipe &as&ade b( reading the sta&- &ontents. 9his statement o5er6rites some o' the
rules o' the 'ourth e%ample temporaril(.
Cou &an see the po6er'ul possibilities o' the redire&tion &ommand. 9he disad5antage is the loss o' a
dire&t o5er5ie6 o' 6hat happens a'ter a permanent redire&tion &ommand has e%e&uted.
8ts no6 the time to sho6 (ou all rules and semanti&s o' the redire&tion.
Rules for the redirection b& the +e&ord WITH of the ADDRESS statement"
>5er( en5ironment has its o6n de'ault redirection set.
>5er( redirection set &onsists o' three independent redirection ele#ents7 standard input
FI+PU,G, standard output FOU,PU,G and standard error F..O.G. 0sers 6ith some e%perien&es
31
6ith 0ni%, 2OS ] Dindo6s or OS#2 ma( remember the redire&tion &ommands o' the &ommand
line interpreter 6hi&h &an redire&t ea&h o' the streams, too. 9his is nearl( the same.
>a&h redirection ele#ent starts 6ith the program$startup streams gi5en to Rexx 6hen in5o-ing
the interpreter. 9hese &an be reset to the startup de'ault b( spe&i'(ing the argument +O.3"; 'or
ea&h redirection ele#ent.
9he seKuen&e o' the redirection ele#ents is irrele5ant.
Cou &an spe&i'( ea&h redirection ele#ent onl( on&e per statement.
edire&tions &an be intermi%ed. 9his means (ou &an let both the OU,PU, and the ..O.
redire&tion point to the same ;thing;. 9he data 'rom the di''erent &hannels 6ill be put to the
assigned ;thing; as the( arri5e. AN!Ps point o' 5ie6 isnPt 5er( &lear at this point. 9he( state to
-eep the output di''erent 'or 'iles and put them together a'ter the &alled program 'inished 6hile
the data shall be mi%ed at on&e 6hen using stems.
egina al6a(s mi%es the 'et&hed data at on&e i' possible.
edire&tions 'rom and to the same sour&e#destination tr( to -eep the data &onsistent. 8' the
I+PU,#OU,PU, pair or the I+PU,#..O. pair points to the same destination, the &ontent o'
the input or output &hannel is bu''ered so that 6riting to the output 6onPt o5er6rite the input.
A redirection ele#ent is entered b( its name Fe.g. I+PU,G, a redire&tion pro&essor Fe.g.
S,."3G and a destination s(mbol Fe.g. O09L1/G 'ollo6ing the rules to the redire&tion
pro&essor. 9his means that (ou ha5e to enter a dot a'ter a s(mbol name 'or a stem, or an( s(mbol
'or the rest o' the pro&essors, in 6hi&h &ase the &ontent o' the s(mbol is used as 'or normal
5ariables.
:oth OU,PU, and ..O. streams &an repla&e or append the data to the destination. Simpl(
append either "PP+A or .P;"$ immediatel( a'ter the OU,PU, or ..O. -e(6ords.
.P;"$ is the de'ault.
9he destination is &he&-ed or &leared prior to the e%e&ution o' the &ommand.
AN! de'ines t6o redire&tion pro&essors: S,3 and S,."3. 9he pro&essors ;I@O and @I@O
are allo6ed e%tensions to the standard.
9he pro&essor S,3 uses the &ontent o' the s(mbol destination.( to a&&ess the &ount o' the
&urrentl( a&&essible lines. destination is the gi5en destination name, o' &ourse. destination.( must
be 'illed 6ith a 6hole, non$negati5e number in terms o' the 2A9A9C"> built$in 'un&tion. >a&h
o' n lines &an be addressed b( appending the 6hole numbers one to n to the stem. >%ample:
S,3 'oo. is gi5en, 1OO.0 &ontains =. 9his indi&ates three &ontent lines. 9he( are the &ontents
o' the s(mbols 1OO.1 and 1OO.2 and 1OO.= .
9he pro&essor S,."3 uses the &ontent o' the s(mbol destination to use a stream as -no6n in
the S9>A, built$in 'un&tion. 9he usage is nearl( eKui5alent to the &ommands 38/>8/
destination or 38/>O09 destination 'or a&&essing the &ontents o' the 'ile. An empt( 5ariable
F&ontent set to the empt( stringG as the &ontent o' the destination is allo6ed and indi&ates the
de'ault input, output or error streams gi5en to the Rexx program. 9his is eKui5alent to the
/O,A3 -e(6ord.
9he pro&essor ;I@O uses the &ontent o' the s(mbol destination as a Kueue name. /e6 lines are
pushed in last$in, 'irst$out order to the Kueue. An empt( destination string is allo6ed and
des&ribes the de'ault Kueue. 3ines are 'et&hed 'rom the Kueue i' this pro&essor is used 'or the
I+PU, stream.
9he pro&essor @I@O uses the &ontent o' the s(mbol destination as a Kueue name. /e6 lines are
pushed in 'irst$in, 'irst$out order to the Kueue. An empt( destination string is allo6ed and
des&ribes the de'ault Kueue. 3ines are 'et&hed 'rom the Kueue i' this pro&essor is used 'or the
I+PU, stream.
On I+PU,, all the data in the input stream is read up to either the end o' the input data or until
the &alled pro&ess terminates. 9he latter one ma( be determined a'ter 'eeding up the input stream
32
o' the &alled pro&ess 6ith unused data. 9hus, there is no 6a( to sa( i' data is used or not. 9his
isnPt a problem 6ith S,3s. :ut all 'ile related seKuential a&&ess ob\e&ts in&luding ;I@Os and
@I@Os ma( ha5e lost data bet6een t6o &alls. 8magine an input 'ile FS,."3G 6ith three lines:
One line
A;I3I,.
Secon1 line
and 'urthermore t6o pro&esses p1 and p2 &alled JI,9 I+PU, S,."3 6ith &ontaining the
three lines abo5e. p1 reads lines up until a line &ontaining 2>38,89> and p2 pro&esses the
rest. 8t is 5er( li-el( that the se&ond pro&ess 6onPt 'et&h an( line be&ause the stream ma( be
pro&essed b( Rexx, and Rexx ma( has put one or more lines ahead into the 'eeder pipe to the
pro&ess. 9his might or might not happen. 8t is implementation dependent and Regina sho6s this
beha5ior. 9he input ob\e&t is &he&-ed 'or e%isten&e and i' it is properl( set up be'ore the
&ommand is started.
8n short: I+PU, ma( or ma( not use the entire input.
:oth OU,PU, and ..O. ob\e&ts are &he&-ed 'or being properl( set up \ust be'ore the
&ommand starts. .P;"$ is implemented as a deletion \ust be'ore the &ommand starts. /ote
that AN! doesnPt 'or&e S,3 lines to be dropped in &ase o' a repla&ement. A big stem 6ith
thousands o' lines 6ill still e%ist a'ter a repla&ement operation i' the &alled &ommand doesnPt
produ&e an( output. Oust destination.0 is set to 0.
9he redire&tion o' &ommands is a m(ster( to man( people and it 6ill &ontinue be. Cou &an than- all
the people 6ho designed sta&-s, Kueues, pipelines and all the little helper utilities o' a 6it&hPs
-it&hen o' pro&ess management.
2.4.2 The (R, Instruction
".> F template G F) F template G ... GE
9he ".> instru&tion 6ill parse the argument strings at the &urrent pro&edural le5el into the template.
"arsing 6ill be per'ormed in upper &ase mode. 9his &lause is eKui5alent to:
P".S UPP. ".> F template G E
1or more in'ormation, see the P".S instru&tion. /ote that this is the onl( situation 6here a
multistring template is rele5ant.
Example" %eare assignments
9he similarit( bet6een ".> and P".S UPP. ".> has one e%&eption. Suppose the P".S
UPP. ".> has an absolute positional pattern as the 'irst element in the template, li-e:
6arse u66er arg :B(ooC bar
9his is not eKui5alent to an ".> instru&tion, be&ause ".> instru&tion 6ould be&ome an assignment.
A simple tri&- to a5oid this problem is \ust to prepend a pla&eholder period F.G to the pattern, thus
the eKual sign F:G is no longer the se&ond to-en in the ne6 ".> instru&tion. Also, unless the
absolute positional pattern is indire&t, the eKual sign &an be remo5ed 6ithout &hanging the meaning
o' the statement.
33
2.4.3 The C(## Instruction
$";; routine F parameter G F) F parameter G ... G E
K O+ D O@@ L condition F +"3 label G E
9he $";; instru&tion in5o-es a subroutine, named b( routine, 6hi&h &an be internal, built$in, or
e%ternal7 and the three repositories o' 'un&tions are sear&hed 'or routine in that order. 9he to-en
routine must be either a literal string or a s(mbol F6hi&h is ta-en literall(G. !o6e5er, i' routine is a
literal string, the pool o' internal subroutines is not sear&hed. /ote that some interpreters ma( ha5e
additional repositories o' labels to sear&h.
8n a $";; instru&tion, ea&h para#eter is e5aluated, stri&tl( in order 'rom le't to right, and passed as
an argument to the subroutine. A para#eter might be le't out Fi.e. an empt( argumentG, 6hi&h is not
the same as passing the nullstring as argument.
0sers o'ten &on'use a parameter 6hi&h is the nullstring 6ith lea5ing out the parameter. !o6e5er,
this is t6o 5er( di''erent situations. Consider the 'ollo6ing &alls to the built$in 'un&tion
,."+S;",BC:
say 'ransla'eB/abcA@/ C /5 says "I$A@ 5/
say 'ransla'eB/abcA@/)44C /5 says abcA@ 5/
say 'ransla'eB/abcA@/))44C /5 says / / 5/
9he ,."+S;",BC 'un&tion is able to di''er bet6een re&ei5ing the nullstring Fi.e. a de'ined string
ha5ing Hero lengthG, 'rom the situation 6here a parameter 6as not spe&i'ied Fi.e. the unde'ined
stringG. Sin&e ,."+S;",BC is one o' the 'e6 'un&tions 6here the parametersP de'ault 5alues are
5er( di''erent 'rom the nullstring, the distin&tion be&omes 5er( 5isible.
7rea;age *$ert==
"rior to 4ersion =.1 o' Regina, the 'ollo6ing s(nta&ti&al use o' the $";; instru&tion 6as 5alid:
$";; routine /B/ F parameter G F) F parameter G ... G /C/ E
e.g.
call %y(uncB/abcA@/))44C
9his s(nta% is not allo6ed b( A/S8 and use o' this s(nta% 6ill no6 result in >rror =@.1. 9here
e%ists an option introdu&ed in Regina =.= 6hi&h re$enables a similar beha5iour, although
parameters 6ith indi5idual parentheses are allo6ed sin&e =.1. 9he option is &alled
CA33SLASL10/CS and should
be enabled using the en5ironment 5ariable &alled >.8/ALO"98O/S. See the des&ription o' the
instru&tion OP,IO+S 'or 'urther details.
7rea;age *$ert==
1or the $";; instru&tion, 6at&h out 'or inter'eren&e 6ith line &ontinuation. 8' there are trailing
34
&ommas, it might be interpreted as line &ontinuation. Appending a semi&olon 6here appropriate is a
&ommon solution to ma-e the desired beha5iour ob5ious. 8' a $";; instru&tion uses line
&ontinuation bet6een t6o parameters, t6o &ommas are needed: one to separate the parameters, and
one to denote line &ontinuation.
A number o' settings are stored a&ross internal subroutine &alls. An internal subroutine 6ill inherit
the 5alues in e''e&t 6hen the &all is made, and the settings are restored on e%it 'rom the subroutine.
9hese settings are:
Conditions traps, see &hapter Conditions.
Current trapped &ondition, see se&tion C9S.
+U3.I$ settings, see se&tion /umeri&.
"AA.SS en5ironments, see se&tion Address.
,."$ mode, see se&tion 9ra&e and &hapter Inot (et 6rittenJ.
9he elapse time &lo&-, see se&tion 9ime.
Also, the OP,IO+S settings ma( or ma( not be restored, depending on the implementation7
Regina restores the &urrent OP,IO+S. /ote that e%ternal subroutines donPt inherit the &urrent
OP,IO+S as internal subroutines do. See the se&tion OP,IO+S 'or a detailed e%planation. 1urther,
a number o' other things ma( be sa5ed a&ross internal subroutines. 9he e''e&t on 5ariables are
&ontrolled b( the P.O$AU. instru&tion in the subroutine itsel'. 9he state o' all AO$loops 6ill be
preser5ed during subroutine &alls.
Example" !ubroutines and trace settings
Subroutines &an not be used to set 5arious settings li-e tra&e settings, +U3.I$ settings, et&. 9hus,
the 'ollo6ing &ode 6ill not 6or- as intended:
say 1igi'sBC /5 says 9) %aybe 5/
call inc_1igi's
say 1igi'sBC /5 s'ill says 9 5/
e&i'
inc_1igi'sH
nu%eric 1igi's 1igi'sBC = 1
re'urn
9he programmer probabl( 6anted to &all a routine 6hi&h in&remented the pre&ision o' arithmeti&
operations. !o6e5er, sin&e the setting o' +U3.I$ AI>I,S is sa5ed a&ross subroutine &alls, the
ne6 5alue set in inc_1igi's is lost at return 'rom that routine. 9hus, in order to 6or- &orre&tl(,
the +U3.I$ instru&tion must be lo&ated in the main routine itsel'.
:uilt$in subroutines 6ill ha5e no e''e&t on the settings, e%&ept 'or e%pli&itl( de'ined side e''e&ts.
/or 6ill e%ternal subroutines &hange the settings. 1or all pra&ti&al purposes, an e%ternal subroutine
is &on&eptuall( eKui5alent to re$in5o-ing the interpreter in a totall( separated pro&ess.
8' the name o' the subroutine is spe&i'ied b( a literal string, then the name 6ill be used as$is7 it 6ill
not be &on5erted to upper &ase. 9his is important be&ause a routine 6hi&h &ontains lo6er &ase
35
letters &an onl( be in5o-ed b( using a literal string as the routine name in the $";; instru&tion.
Example" #abels are literals
3abels are literal, 6hi&h means that the( are neither tail$substituted nor substituted 'or the 5alue o'
the 5ariable. 1urther, this also means that the setting o' +U3.I$ AI>I,S has no in'luen&e on the
se&tion o' labels, e5en 6hen the labels are numeri& s(mbols. Consider the 'ollo6ing &ode:
call M58.7#
e&i'
M58.7#1H
say !ere
re'urn
M58.7#H
say '!ere
re'urn
8n this e%ample, the se&ond o' the t6o subroutines are al6a(s &hosen, independent o' the setting o'
+U3.I$ AI>I,S. Assuming that +U3.I$ AI>I,S are set to 5, then the number ?5<.=21 is
&on5erted to ?5<.=2, but that does not a''e&t labels. /or 6ould a statement $";; M.587## &all
the se&ond label, e5en though the numeri& 5alue o' that s(mbol is eKual to that o' one o' the labels.
9he &alled subroutines ma( or ma( not return data to the &aller. 8n the &alling routine, the spe&ial
5ariable .SU;, 6ill be set to the return 5alue or dropped, depending on 6hether an( data 6as
returned or not. 9hus, the $";; instru&tion is eKui5alent to &alling the routine as a 'un&tion, and
assigning the return 5alue to .SU;,, e%&ept 6hen the routine does not return data.
8n Rexx, re&ursi5e routines are allo6ed. A minimum number o' 100 nested internal and e%ternal
subroutine in5o&ations, and support 'or a minimum o' 10 parameters 'or ea&h &all are reKuired b(
Rexx. See &hapter 3imits 'or more in'ormation &on&erning implementation limits.
Dhen the to-en 'ollo6ing $";; is either O+ or O@@, the $";; instru&tion is not used 'or &alling a
subroutine, but 'or setting up &ondition traps. 8n this &ase, the third to-en o' the &lause must be the
name o' a &ondition, 6hi&h setup is to be &hanged.
8' the se&ond to-en 6as O+, then there &an be either three or 'i5e to-ens. 8' the 'i5e to-en 5ersion is
used, then the 'ourth to-en must be +"3 and the 'i'th to-en is ta-en to be the s(mboli& name o' a
label, 6hi&h is the &ondition handler. 9his name &an be either a &onstant string, or a s(mbol, 6hi&h
is ta-en literall(. Dhen O@@ is used, the named &ondition trap is turned o''.
/ote that the O+ and O@@ 'orms o' the $";; instru&tion 6ere introdu&ed in 932. 9hus, the( are
not li-el( to be present on older interpreters. ,ore in'ormation about &onditions and &ondition traps
are gi5en in a &hapter Conditions.
36
2.4.4 The $-.E'$ Instruction
AO F repetitor G F conditional G E
F clauses G
+A F symbol G E
repetitor H : symbol : expri F ,O exprt G
F I* exprb G F @O. exprf G
exprr
@O.V.
conditional H : J9I; exprw
U+,I; expru
9he AO#+A instru&tion is the instru&tion used 'or looping and grouping se5eral statements into one
blo&-. 9his is a multi$&lause instru&tion.
9he most simple &ase is 6hen there is no repetitor or conditional it groups Hero or more Rexx
&lauses into one &on&eptual statement. 9his is most o'ten used to e%e&ute multiple &lauses in an I@
instru&tion.
e.g.
i( & : 1 '!en
1o
say /!ello/
say /0orl1/
en1
9he repetitor sub&lause &ontrols the &ontrol 5ariable o' the loop, or the number o' repetitions. 9he
e$prr sub&lause ma( spe&i'( a &ertain number o' repetitions, or (ou ma( use @O.V. to go on
looping 'ore5er.
8' (ou spe&i'( the &ontrol 5ariable sy#bol, it must be a 5ariable s(mbol, and it 6ill get the initial
5alue e$pri at the start o' the loop. At the start o' ea&h iteration, in&luding the 'irst, it 6ill be
&he&-ed 6hether it has rea&hed the 5alue spe&i'ied b( e$prt. At the end o' ea&h iteration the 5alue
e$prb is added to the &ontrol 5ariable. 9he loop 6ill terminate a'ter at most e$pr& iterations. /ote
that all these e%pressions are e5aluated onl( on&e, be'ore the loop is entered 'or the 'irst iteration.
Cou ma( also spe&i'( U+,I; or J9I;, 6hi&h ta-e a boolean e%pression. J9I; is &he&-ed
be'ore ea&h iteration, immediatel( a'ter the ma%imum number o' iteration has been per'ormed.
U+,I; is &he&-ed a'ter ea&h iteration, immediatel( be'ore the &ontrol 5ariable is in&remented. 8t is
not possible to spe&i'( both U+,I; and J9I; in the same AO instru&tion.
9he @O.V. -e(6ord is onl( needed 6hen there is no conditional, and the repetitor 6ould also
be empt( i' @O.V. 6as not spe&i'ied. A&tuall(, (ou &ould re6rite this as AO J9I; 1. 9he
t6o 'orms are eKui5alent, e%&ept 'or tra&ing output.
9he sub&lauses ,O, I*, and @O. ma( &ome in an( order, and their e%pressions are e5aluated in the
order in 6hi&h the( o&&ur. !o6e5er, the initial assignment must al6a(s &ome 'irst. 9heir order ma(
a''e&t (our program i' these e%pressions ha5e an( side e''e&ts. !o6e5er, this is seldom a problem,
sin&e it is Kuite intuiti5e.
37
Example" E*aluation order
Dhat ma( pro5e a real trap, is that although the 5alue to 6hi&h the &ontrol 5ariable is set is
e5aluated be'ore an( other e%pressions in the repetitor, it is assigned to the &ontrol 5ariable a'ter all
e%pressions in the repetitor ha5e been e5aluated.
9he 'ollo6ing &ode illustrates this problem:
c'rl : 1
1o c'rl:(B#C by (B7C 'o (B5C
call ( M
en1
call ( N
e&i'
(H
say /c'rl:/c'rl /arg:/argB1C
re'urn argB1C
9his &ode produ&es the 'ollo6ing output:
c'rl:1 arg:#
c'rl:1 arg:7
c'rl:1 arg:5
c'rl:# arg:M
c'rl:5 arg:M
c'rl:8 arg:N
,a-e sure (ou understand 6h( the program produ&es this output. 1ailure to understand this ma(
gi5e (ou a surprise later, 6hen (ou happen to 6rite a &omple% AO$instru&tion, and do not get the
e%pe&ted result.
8' the ,O e%pression is omitted, there is no &he&-ing 'or an upper bound o' the e%pression. 8' the I*
sub&lause is omitted, then the de'ault in&rement o' 1 is used. 8' the @O. sub&lause is omitted, then
there is no &he&-ing 'or a ma%imum number o' iterations.
Example" #oop con*ergence /or the reasons 0ust explained1 the instruction"
1o c'rl:1
no6 /5 an1 o'!er s'a'e%en's 5/
en1
6ill start 6ith $,.; being 1, and then iterate through 2, =, <, ..., and ne5er terminate e%&ept b(
;"V, .,U.+, SI>+";, or -I,.
Although similar &onstru&ts in other languages t(pi&all( pro5o-es an o5er'lo6 at some point,
something ;strange; happens in Rexx. Dhene5er the 5alue o' c'rl be&omes too large, the
38
in&rementation o' that 5ariable produ&es a result that is identi&al to the old 5alue o' c'rl. 1or
+U3.I$ AI>I,S set to *, this happens 6hen c'rl be&omes 1.00000000>^*. Dhen adding 1 to
this number, the result is still 1.00000000>^*. 9hus, the loop ;&on5erges; at that 5alue.
8' the 5alue o' +U3.I$ AI>I,S is 1, then it 6ill ;&on5erge; at 10, or 1>^1 6hi&h is the
;&orre&t; 6a( o' 6riting that number under +U3.I$ AI>I,S 1. Cou &an in general disregard
loop ;&on5ergen&e;, be&ause it 6ill onl( o&&ur in 5er( rare situations.
!"amp$eA Dierence bet6een UNTIL and WHILE
One 'reKuent misunderstanding is that the J9I; and U+,I; sub&lauses o' the AO#+A instru&tion
are eKui5alent, e%&ept that J9I; is &he&-ed be'ore the 'irst iteration, 6hile U+,I; is 'irst
&he&-ed be'ore the se&ond iteration.
9his ma( be so in other languages, but in Rexx. :e&ause o' the order in 6hi&h the parts o' the loop
are per'ormed, there are other di''eren&es. Consider the 'ollo6ing &ode:
coun' : 1
1o i:1 0!ile coun' O: 5
coun' : coun' = 1
en1
say i coun'
coun' : 1
1o i:1 un'il coun':5
coun' : coun' = 1
en1
say i coun'
A'ter the 'irst loop, the numbers 5 and 5, 6hile in the se&ond loop, the numbers < and 5 are 6ritten
out. 9he reason is that a J9I; &lause is &he&-ed a'ter the &ontrol 5ariable o' the loop has been
in&remented, but an U+,I; e%pression is &he&-ed be'ore the in&rementation.
A loop &an be terminated in se5eral 6a(s. A .,U.+ or -I, instru&tion terminates all a&ti5e
loops in the pro&edure le5els terminated. 1urther, a SI>+"; instru&tion trans'erring &ontrol Fi.e.
neither a SI>+"; O+ nor SI>+"; O@@G terminates all loops at the &urrent pro&edural le5el. 9his
applies e5en to ;impli⁢ SI>+"; instru&tions, i.e. 6hen triggering a &ondition handler b( the
method o' SI>+";. A ;"V instru&tion terminates one or more loops. 3ast but not least, a loop
&an terminate itsel', 6hen it has rea&hed its spe&i'ied stop &onditions.
/ote that the SI>+"; instru&tion terminates also non$repetiti5e loops For rather: AO#+A pairsG,
thus a'ter an SI>+"; instru&tion, (ou must not e%e&ute an +A instru&tion 6ithout ha5ing
e%e&uted its &orresponding AO 'irst Fand a'ter the SI>+"; instru&tionG. !o6e5er, as long as (ou
sta( a6a( 'rom the +As, it is all right a&&ording to 93 to e%e&ute &ode 6ithin a loop 6ithout
ha5ing properl( a&ti5ated the loop itsel'.
/ote that on e%it 'rom a loop, the 5alue o' the &ontrol 5ariable has been in&remented on&e a'ter the
last iteration o' the loop, i' the loop 6as terminated b( the J9I; e%pression, b( e%&eeding the
39
number o' ma% iterations, or i' the &ontrol 5ariable e%&eeded the stop 5alue. !o6e5er, the &ontrol
5ariable has the 5alue o' the last iteration i' the loop 6as terminated b( the U+,I; e%pression, or
b( an instru&tion inside the loop Fe.g. ;"V, SI>+";, et&.G.
9he 'ollo6ing algorithm in Rexx &ode sho6s the e%e&ution o' a AO instru&tion, assuming that
e$pri, e$prt, e$prb, e$pr&, e$pr", e$pru, and sy#bol ha5e been ta-en 'rom the s(nta% diagram o'
AO.
Pe&6ri : expri
Pe&6r' : exprt
Pe&6rb : exprb
Pe&6r( : exprf
Pi'ers : <
symbol : Pe&6ri
s'ar'_o(_loo6H
i( symbol Q Pe&'r' '!en signal a('er_loo6
i( Pi'ers Q Pe&6r( '!en signal a('er_loo6
i( Oexprw '!en signal a('er_loo6
instructions
en1_o(_loo6H
i( expru '!en signal a('er_loo6
symbol : symbol = Pe&6rb
signal s'ar'_o(_loo6
a('er_loo6H
Some notes are in order 'or this algorithm. 1irst, it uses the SI>+"; instru&tion, 6hi&h is de'ined to
terminate all a&ti5e loops. 9his aspe&t o' the SI>+"; instru&tion has been ignored 'or the purpose
o' illustrating the AO, and &onseKuentl(, the &ode sho6n abo5e is not suitable 'or nested loops.
1urther, the order o' the 'irst 'our statements should be identi&al to the order in the &orresponding
sub&lauses in the repetitor. 9he &ode has also ignored that the J9I; and the U+,I; sub&lauses
&an not be used in the same AO instru&tion. And in addition, all 5ariables starting 6ith the at sign
FPG, are assumed to be internal 5ariables, pri5ate to this parti&ular loop. Dithin instructions, a
;"V instru&tion is eKui5alent to signal a('er_loo6, 6hile a I,.", instru&tion is
eKui5alent to signal en1_o(_loo6.
2.4.2 The $R-P Instruction
A.OP symbol F symbol ... G E
9he A.OP instru&tion ma-es the named variables uninitialiHed, i.e. the same state that the( had at
the startup o' the program. 9he list o' 5ariable names are pro&essed stri&tl( 'rom le't to right and
dropped in that order. ConseKuentl(, i' one o' the 5ariables to be dropped is used in a tail o'
another, then the order might be signi'i&ant. >.g. the 'ollo6ing t6o A.OP instru&tions are not
eKui5alent:
40
bar : /a/
1ro6 bar (oo.bar /5 1ro6s /I"./ an1 /@OO.I"./ 5/
bar : /a/
1ro6 (oo.bar bar /5 1ro6s /@OO.a/ an1 /I"./
9he variable terms &an be either a 5ariable s(mbol or a s(mbol en&losed in parentheses. 9he 'ormer
'orm is 'irst tail$substituted, and then ta-en as the literal name o' the s(mbol to be dropped. 9he
result names the 5ariable to drop. 8n the latter 'orm, the 5alue o' the 5ariable s(mbol inside the
parentheses is retrie5ed and ta-en as a spa&e separated list o' s(mbols. >a&h o' these s(mbols is tail$
substituted Fi' rele5antG7 and the result is ta-en as the literal name o' a 5ariable to be dropped.
!o6e5er, this pro&ess is not re&ursi5e, so that the list o' names re'erred to indire&tl( &an not itsel'
&ontain parentheses. /ote that the se&ond 'orm 6as introdu&ed in 932, mainl( in order to ma-e
I+,.P., unne&essar(.
8n general, things &ontained in parentheses &an be an( 5alid Rexx e%pression, but this does not
appl( to the A.OP, P".S, and P.O$AU. instru&tions.
Example" $ropping compound *ariables
/ote a potential problem 'or &ompound 5ariables: 6hen a stem 5ariable is set, it 6ill not set a
de'ault 5alue, rather it 6ill assign ;all possible 5ariables; in that stem &olle&tion at on&e. So
dropping a &ompound 5ariable in a stem &olle&tion 'or 6hi&h the stem 5ariable has been set, 6ill set
that &ompound 5ariable to the original uninitialiHed 5alue7 not the 5alue o' the stem 5ariable. See
se&tion Assign 'or 'urther notes on assignments. 9o illustrate &onsider the &ode:
(oo. : /1e(aul'/
1ro6 ba? bar (oo.bar
say (oo.bar (oo.ba? /5 says /@OO.I". 1e(aul'/ 5/
8n this e%ample, the S"* instru&tion 6rites out the 5alue o' the t6o &ompound 5ariables @OO.I".
and @OO.I"R. Dhen per'orming tail$substitution 'or these, the interpreter 'inds that both I". and
I"R are uninitialiHed. 1urther, @OO.I". has also been made uninitialiHed, 6hile @OO.I"R has the
5alue assigned to it in the assignment to the stem 5ariable.
!"amp$eA Tai$'s#bstit#ti1n in DROP
1or instan&e, suppose that the 5ariable @OO has the 5alue bar. A'ter being dropped, @OO 6ill ha5e
its uninitialiHed 5alue, 6hi&h is the same as its name: @OO. 8' the 5ariable to be dropped is a stem
5ariable, then both the stem 5ariable and all &ompound 5ariables o' that stem be&ome uninitialiHed.
bar : 1#7
1ro6 (oo.bar /5 1ro6s /@OO.1#7/ 5/
9e&hni&all(, it should be noted that some operations in5ol5ing dropping o' &ompound 5ariables &an
be 5er( spa&e &onsuming. >5en though the standard does not operate 6ith the term ;de'ault 5alue;
'or the 5alue assigned to a stem 5ariable, that is the 6a( in 6hi&h it is most li-el( to be
implemented. Dhen a stem is assigned a 5alue, and some o' its &ompound 5ariables are dropped
a'ter6ards, then the interpreter must use memor( to store re'eren&es to the 5ariables dropped. 9his
41
might seem &ounter$intuiti5e at 'irst, sin&e dropping ought to release memor(, not allo&ate more.
9here is a parallel bet6een A.OP and P.O$AU. -POS. !o6e5er, there is one important
di''eren&e, although P.O$AU. -POS 6ill e%pose the name o' a 5ariable en&losed in
parentheses be'ore starting to e%pose the s(mbols that 5ariable re'ers to, this is not so 'or A.OP. 8'
A.OP had mimi&-ed the beha5iour o' P.O$AU. -POS in this matter, then the 6hole
purpose o' indire&t spe&i'(ing o' 5ariables in A.OP 6ould ha5e been de'eated.
2ropping a 5ariable 6hi&h does not ha5e a 5alue is not an error. 9here is no upper limit on the
number o' 5ariables that &an be dropped in one A.OP &lause, other than restri&tions on the &lause
length. 8' an e%posed 5ariable is dropped, the 5ariable in the &aller is dropped, but the 5ariable
remains e%posed. 8' it reassigned a 5alue, the 5alue is assigned to a 5ariable in the &aller routine.
2.4.3 The E4IT Instruction
-I, F expr G E
9erminates the Rexx program, and optionall( returns the e%pression e$pr to the &aller. 8' spe&i'ied,
e$pr &an be an( string. 8n some s(stems, there are restri&tions on the range o' 5alid 5alues 'or the
e$pr. O'ten the return e%pression must be an integer, or e5en a non$negati5e integer. 9his is not
reall( a restri&tion on the Rexx language itsel', but a restri&tion in the en5ironment in 6hi&h the
interpreter operates, &he&- the s(stem dependent do&umentation 'or more in'ormation.
8' e$pr is omitted, nothing 6ill be returned to the &aller. 0nder some &ir&umstan&es that is not legal,
and might be handled as an error or a de'ault 5alue might be used. 9he -I, instru&tion beha5es
di''erentl( in a ;program; than in an e%ternal subroutine. 8n a ;program;, it returns &ontrol to the
&aller e.g. the operating s(stem &ommand interpreter. Dhile 'or an e%ternal routine, it returns
&ontrol to the &alling Rexx s&ript, independent o' the le5el o' nesting inside the e%ternal routine
being terminated.
RETURN EXIT
At the main le5el o' the program >%its program >%its program
At an internal subroutine le5el o' the
program
>%its subroutine, and returns
to &aller
>%its program
At the main le5el o' an e%ternal
subroutine
>%its the e%ternal subroutine >%its the e%ternal
subroutine
At a subroutine le5el 6ithin an e%ternal
subroutine
>%its the subroutine, returning
to &alling routine 6ithin
e%ternal subroutine s&ript
>%its the e%ternal
subroutine
*cti1ns 1 RETURN and EXIT +nstr#cti1ns
8' terminating an e%ternal routine Fi.e. returning to the &alling Rexx s&riptG an( legal Rexx string
5alue is allo6ed as a return 5alue. Also, no return 5alue &an be returned, and in both &ases, this
in'ormation is su&&ess'ull( transmitted ba&- to the &alling routine. 8n the &ase o' a 'un&tion &all Fas
opposed to a subroutine &allG, returning no 5alue 6ill raise S*+,"- &ondition Z<<[. 9he table
abo5e des&ribes the a&tions ta-en b( the -I, and .,U.+ instru&tion in 5arious situations.
42
2.4.5 The I/.T6E'.E#!E Instruction
I@ expr FEG ,9+ FEG statement
F ;S FEG statement G
9his is a normal i'$&onstru&t. 1irst the boolean e%pression e$pr is e5aluated, and its 5alue must be
either < or 1 Fe5er(thing else is a s(nta% error 6hi&h raises S*+,"- &ondition number Z=<[G.
9hen, the statement 'ollo6ing either ,9+ or ;S is e%e&uted, depending on 6hether e$pr 6as 1
or <, respe&ti5el(.
/ote that there must &ome a statement a'ter ,9+ and ;S. 8t is not allo6ed to put \ust a null$
&lause Fi.e. a &omment or a labelG there. 8' (ou 6ant the ,9+ or ;S part to be empt(, use the
+OP instru&tion. Also note that (ou &an not dire&tl( put more than one statement a'ter ,9+ or
;S7 (ou ha5e to pa&-age them in a AO$+A pair to ma-e them a single, &on&eptual statement.
A'ter ,9+, a'ter ;S, and be'ore ,9+, (ou might put one or more &lause delimiters Fne6lines
or semi&olonsG, but these are not reKuired. Also, the ;S part is not reKuired either, in 6hi&h &ase
no &ode is e%e&uted i' e$pr is 'alse Fe5aluates to <G. /ote that there must also be a statement
separator be'ore ;S, sin&e the that statement must be terminated. 9his also applies to the
statement a'ter ;S. !o6e5er, sin&e state#ent in&ludes a trailing &lause delimiter itsel', this is
not e%pli&itl( sho6n in the s(nta% diagram.
!"amp$eA Dang$ing ELSE
/ote the &ase o' the ;dangling; ;S. 8' an ;S part &an &orre&tl( be thought o' as belonging to
more than one I@#,9+ instru&tion pair, it 6ill be parsed as belonging to the &losest Fi.e.
innermostG I@ instru&tion:
6arse 6ull (oo bar
i( (oo '!en
i( bar '!en
say /(oo an1 bar are 'rue/
else
say /one or bo'! are (alse/
8n this &ode, the ;S instru&tion is nested to the innermost I@, i.e. to I@ I". ,9+.
2.4.7 The I'TERPRET Instruction
I+,.P., expr E
9he I+,.P., instru&tion is used to d(nami&all( build and e%e&ute Rexx instru&tions during
run$time. 1irst, it e5aluates the e%pression e$pr, and then parses and interprets the result as a
Fpossibl( empt(G list o' Rexx instru&tions to be e%e&uted. 1or instan&e:
(oo : /!ello) 0orl1/
in'er6re' /say 4/(oo/!4/
e%e&utes the statement S"* 4!ello) 0orl1!4 a'ter ha5ing e5aluated the e%pression 'ollo6ing
43
I+,.P.,. 9his e%ample sho6s se5eral important aspe&ts o' I+,.P.,. 1irstl(, itPs 5er( eas(
to get &on'used b( the le5els o' Kuotes, and a bit o' &aution should be ta-en to nest the Kuotes
&orre&tl(. Se&ondl(, the use o' I+,.P., does not e%a&tl( impro5e readabilit(.
Also, I+,.P., 6ill probabl( in&rease e%e&ution time &onsiderabl( i' put inside loops, sin&e the
interpreter ma( be 'or&ed to reparse the sour&e &ode 'or ea&h iteration. ,an( optimiHing Rexx
interpreters Fand in parti&ular Rexx &ompilersG has little or no support 'or I+,.P.,. Sin&e
5irtuall( an(thing &an happen inside it, it is hard to optimiHe, and it o'ten in5alidates assumptions in
other parts o' the s&ript, 'or&ing it to ignore other possible optimiHations. 9hus, (ou should a5oid
I+,.P., 6hen speed is at a premium.
9here are some restri&tions on 6hi&h statements &an be inside an I+,.P., statement. 1irstl(,
labels &annot o&&ur there. 93 states that the( are not allo6ed, but (ou ma( 'ind that in some
implementations labels o&&urring there 6ill not a''e&t the label s(mbol table o' the program being
run. Consider the statement:
in'er6re' /signal '!ereE '!ereH say !allo/
'!ereH
9his statement trans'ers &ontrol to the label ,9. in the program, ne5er to the ,9. label inside
the e%pression o' the I+,.P., instru&tion. >Kui5alentl(, an( SI>+"; to a label ,9.
else6here in the program ne5er trans'ers &ontrol to the label inside the I+,.P., instru&tion.
!o6e5er, labels are stri&tl( spea-ing not allo6ed inside I+,.P., strings.
Example" !elf8modif&ing Program
9here is an idea 'or a sel'$modi'(ing program in Rexx 6hi&h is basi&all( li-e this:
s'ring : //
1o i:1 'o sourcelineBC
s'ring : s'ring /E/ sourcelineBiC
en1
s'ring : 'rans(or%B s'ring C
in'er6re' s'ring
e&i'
'rans(or%H 6roce1ure
6arse arg s'ring
/5 1o so%e 'rans(or%a'ion on '!e argu%en' 5/
re'urn s'ring
0n'ortunatel(, there are se5eral reasons 6h( this program 6ill not 6or- in Rexx, and it ma( be
instru&ti5e to in5estigate 6h(. 1irstl(, it uses the label ,."+S@O.3, 6hi&h is not allo6ed in the
argument to I+,.P.,. 9he interpret 6ill thus re'er to the ,."+S@O.3 routine o' the
;outermost; in5o&ation, not the one ;in; the I+,.P., string.
Se&ondl(, the program does not ta-e line &ontinuations into mind. Dorse, the SOU.$;I+BC
built$in 'un&tion re'ers to the data o' the main program, e5en inside the &ode e%e&uted b( the
44
I+,.P., instru&tion. 9hirdl(, the program 6ill ne5er end, as it 6ill nest itsel' up till an
implementation$dependent limit 'or the ma%imum number o' nested I+,.P., instru&tions.
8n order to ma-e this idea 6or- better, temporar( 'iles should be used.
On the other hand, loops and other multi$&lause instru&tions, li-e I@ and S;$, o&&ur inside an
I+,.P., e%pression, but onl( i' the 6hole instru&tion is there7 (ou &an not start a stru&tured
instru&tion inside an I+,.P., instru&tion and end it outside, or 5i&e$5ersa. !o6e5er, the
instru&tion SI>+"; is allo6ed e5en i' the label is not in the interpreted string. Also, the instru&tions
I,.", and ;"V are allo6ed in an I+,.P.,, e5en 6hen the( re'er to a loop that is
e%ternal to the interpreted string.
,ost o' the time, I+,.P., is not needed, although it &an (ield &ompa&t and interesting &ode. 8'
(ou do not stri&tl( need I+,.P.,, (ou should &onsider not using it, 'or reasons o' &ompatibilit(,
speed, and readabilit(. ,an( o' the traditional uses o' I+,.P., ha5e been repla&ed b( other
me&hanisms in order to de&rease the ne&essit( o' I+,.P.,7 e.g. indire&t spe&i'i&ation o'
5ariables in -POS and A.OP, the impro5ed V";UBC built$in 'un&tion, and indire&t
spe&i'i&ation o' patterns in templates.
Onl( semi&olon FEG is allo6ed as a &lause delimiter in the string interpreted b( an I+,.P.,
instru&tion. 9he &olon o' labels &an not be used, sin&e labels are not allo6ed. /or does spe&i'i& end$
o'$line &hara&ter seKuen&es ha5e an( de'ined meaning there. !o6e5er, most interpreters probabl(
allo6 the end$o'$line &hara&ter seKuen&e o' the host operating s(stem as alternati5e &lause
delimiters. 8t is interesting to note that in the &onte%t o' the I+,.P., instru&tion, an impli&it,
trailing &lause delimiter is al6a(s appended to the string to be interpreted.
2.4.9 The ITER(TE Instruction
I,.", F symbol G E
9he I,.", instru&tion 6ill iterate the innermost, a&ti5e loop in 6hi&h the I,.", instru&tion
is lo&ated. 8' sy#bol is spe&i'ied, it 6ill iterate the innermost, a&ti5e loop ha5ing sy#bol as &ontrol
5ariable. 9he simple AO#+A statement 6ithout a repetitor and conditional is not a''e&ted b(
I,.",. All a&ti5e multi&lause stru&tures FAO, S;$,, and I@G 6ithin the loop being iterated
are terminated.
9he e''e&t o' an I,.", is to immediatel( trans'er &ontrol to the +A statement o' the a''e&ted
loop, so that the ne%t Fi' an(G iteration o' the loop &an be started. 8t onl( a''e&ts loops on the &urrent
pro&edural le5el. All a&tions normall( asso&iated 6ith the end o' an iteration is per'ormed.
/ote that sy#bol must be spe&i'ied literall(7 i.e. tail substitution is not per'ormed 'or &ompound
5ariables. So i' the &ontrol 5ariable in the AO instru&tion is @OO.I"., then sy#bol must use
@OO.I". i' it is to re'er to the &ontrol 5ariable, no matter the 5alue o' the I". 5ariable.
Also note that I,.", Fand ;"VG are means o' trans'erring &ontrol in the program, and
there'ore the( are related to SI>+";, but the( do not ha5e the e''e&t o' automati&all( terminating
all a&ti5e loops on the &urrent pro&edural le5el, 6hi&h SI>+"; has.
96o t(pes o' errors &an o&&ur. >ither sy#bol does not re'er to an( loop a&ti5e at the &urrent
45
pro&edural le5el7 or Fi' sy#bol is not spe&i'iedG there does not e%ist an( a&ti5e loops at the &urrent
pro&edural le5el. :oth errors are reported as S*+,"- &ondition Z2+[.
2.4.1: The #E(;E Instruction
;"V F symbol G E
9his statement terminates the innermost, a&ti5e loop. 8' sy#bol is spe&i'ied, it terminates the
innermost, a&ti5e loop ha5ing sy#bol as &ontrol 5ariable. As 'or s&ope, s(nta%, errors, and
'un&tionalit(, it is identi&al to I,.",, e%&ept that ;"V terminates the loop, 6hile I,.",
lets the loop start on the ne%t iteration normal iteration. /o a&tions normall( asso&iated 6ith the
normal end o' an iteration o' a loop is per'ormed 'or a ;"V instru&tion.
!"amp$eA +terating a simp$e DO.END
8n order to &ir&um5ent this, a simple AO#+A &an be re6ritten as this:
i( (oo '!en 1o un'il 1
say /,!is is a si%6le AO/+A grou6/
say /bu' i' can be 'er%ina'e1 by/
leave
say /i'era'e or leave/
en1
9his sho6s ho6 I,.", has been used to terminate 6hat 'or all pra&ti&al purposes is a simple
AO#+A group. >ither I,.", or ;"V &an be used 'or this purpose, although ;"V is
perhaps marginall( 'aster.
2.4.11 The '-P Instruction
+OP E
9he +OP instru&tion is the ;no operation; statement7 it does nothing. A&tuall(, that is not totall(
true, sin&e the +OP instru&tion is a ;real; statement Fand a pla&eholderG, as opposed to null &lauses.
8P5e onl( seen this used in t6o &ir&umstan&es.
A'ter an( ,9+ or ;S -e(6ord, 6here a statement is reKuired, 6hen the programmer 6ants
an empt( ,9+ or ;S part. :( the 6a(, this is the intended use o' +OP. /ote that (ou &an
not use a null &lause there Flabel, &omment, or empt( linesG, sin&e these are not parsed as
;independent; statements.
8 ha5e seen it used as ;tra&e$bait;. 9hat is, 6hen (ou start intera&ti5e tra&e, the statement
immediatel( a'ter the ,."$ instru&tion 6ill be e%e&uted be'ore (ou re&ei5e intera&ti5e &ontrol.
8' (ou donPt 6ant that to happen For ma(be the ,."$ instru&tion 6as the last in the programG,
(ou need to add an e%tra dumm( statement. !o6e5er, in this &onte%t, labels and &omments &an
be used, too.
46
2.4.12 The '<)ERIC Instruction
+U3.I$ AI>I,S F expr G E
@O.3 F S$I+,I@I$ D +>I+.I+> D F V";U G expr G E
@URR F expr G E
Rexx has an unusual 'orm o' arithmeti&. ,ost programming languages use integer and 'loating
point arithmeti&, 6here numbers are &oded as bits in the &omputers nati5e memor( 6ords. !o6e5er,
Rexx uses 'loating point arithmeti& o' arbitrar( pre&ision, that operates on strings representing the
numbers. Although mu&h slo6er, this approa&h gi5es lots o' interesting 'un&tionalit(. 0nless
number$&run&hing is (our tas-, the e%tra time spent b( the interpreter is generall( Kuite a&&eptable
and o'ten almost unnoti&eable.
9he +U3.I$ statement is used to &ontrol most aspe&ts o' arithmeti& operations. 8t has three
distin&t 'orms: AI>I,S, @O.3 and @URR7 6hi&h to &hoose is gi5en b( the se&ond to-en in the
instru&tion:
DIGITS
8s used to set the number o' signi'i&ant digits in arithmeti& operations. 9he initial 5alue is *,
6hi&h is also the de'ault 5alue i' e$pr is not spe&i'ied. 3arge 5alues 'or AI>I,S tend to
slo6 do6n some arithmeti& operations &onsiderabl(. 8' spe&i'ied, e$pr must be a positi5e
integer.
FUZZ
8s used in numeri& &omparisons, and its initial and de'ault 5alue is 0. /ormall(, t6o numbers
must ha5e identi&al numeri& 5alues 'or a number o' their most signi'i&ant digits in order to
be &onsidered eKual. !o6 man( digits are &onsidered is determined b( AI>I,S. 8' AI>I,S
is <, then 12=<5 and 12=<? are eKual, but not 12=<5 and 12=5?. !o6e5er, 6hen @URR is
non$Hero, then onl( the AI>I,S minus @URR most signi'i&ant digits are &he&-ed. >.g. i'
AI>I,S is < and @URR are 2, then 12=< and 12<5 are eKual, but not 12=< and 1=<5.
9he 5alue 'or @URR must be a non$negati5e integer, and less than the 5alue o' AI>I,S.
@URR is seldom used, but is use'ul 6hen (ou 6ant to ma-e &omparisons less in'luen&ed b(
ina&&ura&ies. /ote that using 6ith 5alues o' @URR that is &lose to AI>I,S ma( gi5e highl(
surprising results.
FORM
8s used to set the 'orm in 6hi&h e%ponential numbers are 6ritten. 8t &an be set to either
S$I+,I@I$ or +>I+.I+>. 9he 'ormer uses a mantissa in the range 1.000... to
*.***..., and an e%ponent 6hi&h &an be an( integer7 6hile the latter uses a mantissa in the
range 1.000... to ***.***..., and an e%ponent 6hi&h is di5idable b( =. 9he initial and de'ault
setting is S$I+,I@I$. 1ollo6ing the sub-e(6ord @O.3 ma( be the sub-e(6ords
S$I+,I@I$ and +>I+.I+>, or the sub-e(6ord V";U. 8n the latter &ase, the rest
o' the statement is &onsidered an e%pression, 6hi&h 6ill e5aluate to either S$I+,I@I$ or
+>I+.I+>. !o6e5er, i' the 'irst to-en o' the e%pression 'ollo6ing V";U is neither a
s(mbol nor literal string, then the V";U sub-e(6ord &an be omitted.
9he setting o' @O.3 ne5er a''e&ts the de&ision about 6hether to &hoose e%ponential 'orm or normal
'loating point 'orm7 it onl( a''e&ts the appearan&e o' the e%ponential 'orm on&e that 'orm has been
sele&ted.
47
,an( things &an be said about the use'ulness o' @URR. ,( impression is that it is seldom used in
Rexx programs. One problem is that it onl( addresses relati5e ina&&ura&(: i.e. that the smaller 5alue
must be 6ithin a &ertain range, that is determined b( a per&entage o' the larger 5alue. O'ten one
needs absolute ina&&ura&(, e.g. t6o measurements are eKual i' their di''eren&e are less than a &ertain
absolute threshold.
Example" !imulating relati*e accurac& ith absolute accurac&
As e%plained abo5e, Rexx arithmeti& has onl( relati5e a&&ura&(, in order to obtain absolute
a&&ura&(, one &an use the 'ollo6ing tri&-:
nu%eric (u?? 7
i( a:b '!en
say /rela'ive accuracy/
i( absBa-bCS:5<< '!en
say /absolu'e accuracy/
8n the 'irst I@ instru&tion, i' " is 100,000, then the range o' 5alues 'or I 6hi&h ma-es the
e%pression true is **,500$100,<**, i.e. an ina&&ura&( o' about ^$500. 8' " has the 5alue 10,000,000,
then I must be 6ithin the range *,*50,000$10,0<*,***7 i.e. an ina&&ura&( o' about ^$50,000.
!o6e5er, in the se&ond I@ instru&tion, assuming " is 100,000, the e%pression be&omes true 'or
5alues o' I in the range **,500$100,500. Assuming that " is 10,000,000, the e%pression be&omes
true 'or 5alues o' I in the range *,***,500$10,000,500.
9he e''e&t is largel( to 'or&e an absolute a&&ura&( 'or the se&ond e%ample, no matter 6hat the
5alues o' " and I are. 9his trans'ormation has ta-en pla&e sin&e an arithmeti& subtra&tion is not
a''e&ted b( the +U3.I$ @URR, onl( numeri& &omparison operations. 9hus, the e''e&t o'
+U3.I$ @URR on the impli&it subtra&tion in the operation : in the 'irst I@ has been remo5ed b(
ma-ing the subtra&tion e%pli&it.
/ote that there are some minor di''eren&es in ho6 numbers are rounded, but this &an be 'i%ed b(
trans'orming the e%pression into something more &omple%.
9o retrie5e the 5alues set 'or +U3.I$, (ou &an use the built$in 'un&tions AI>I,SBC, @O.3BC,
and @URRBC. 9hese 5alues are sa5ed a&ross subroutine &alls and restored upon return.
2.4.13 The -PTI-'! Instruction
OP,IO+S expr E
9he OP,IO+S instru&tion is used to set 5arious interpreter$spe&i'i& options. 8ts t(pi&al uses are to
sele&t &ertain Rexx diale&ts, enable optimiHations Fe.g. time 5ersus memor( &onsiderationsG, et&. /o
standard di&tates 6hat ma( 'ollo6 the OP,IO+S -e(6ord, e%&ept that it should be a 5alid Rexx
e%pression, 6hi&h is e5aluated. Currentl(, no spe&i'i& options are reKuired b( an( standard.
9he &ontents o' e$pr is supposed to be 6ord based, and it is the intention that more than one option
&an be spe&i'ied in one OP,IO+S instru&tion. Rexx interpreters are spe&i'i&all( instru&ted to
ignore OP,IO+S 6ords 6hi&h the( do not re&ogniHe. 9hat 6a(, a program &an use run$time
48
options 'or one interpreter, 6ithout ma-ing other interpreters trip 6hen the( see those options. An
e%ample o' OP,IO+ ma( be:
OP,IO+S 8.<< +",IV_@;O",
9he instru&tion might instru&t the interpreter to start en'or&ing language le5el <.00, and to use
nati5e 'loating point numbers in stead o' the Rexx arbitrar( pre&ision arithmeti&. On the other
hand, it might also be &ompletel( ignored b( the interpreter.
8t is un&ertain 6hether modes sele&ted b( OP,IO+S 6ill be sa5ed a&ross subroutine &alls. e'er to
implementation$spe&i'i& do&umentation 'or in'ormation about this.
!"amp$eA Dra6bac; 1 OPTIONS
0n'ortunatel(, the pro&essing o' the OP,IO+S instru&tion has a dra6ba&-. Sin&e an interpreter is
instru&ted to ignore option$settings that it does not understand, it ma( ignore options 6hi&h are
essential 'or 'urther pro&essing o' the program. Continuing might &ause a 'atal error later, although
the beha5iour that 6ould most pre&isel( point out the problem is a &omplaint about the non$
supported OP,IO+ setting. Consider:
o6'ions /c%s_bi(s/
6os : (in1B !ays'acT) nee1le C
8' this &ode 'ragment is run on an interpreter that does not support the c%s_bi(s option setting,
then the OP,IO+S instru&tion ma( still seem to ha5e been e%e&uted &orre&tl(. !o6e5er, the se&ond
&lause 6ill generall( &rash, sin&e the @I+ABC 'un&tion is still not a5ailable. >5en though the real
problem is in the 'irst line, the error message is reported 'or the se&ond line.
2.4.14 The P(R!E Instruction
P".S F o6'ion G F $"S;SS G type F template G E
option : K UPP. D ;OJ. L
type : K ".> D ;I+I+ D PU;; D SOU.$ D V.SIO+ D V";U F
expr G JI,9 D V". symbol L
9he P".S instru&tion ta-es one or more sour&e strings, and then parses them using the te#plate
'or dire&tions. 9he pro&ess o' parsing is one 6here parts o' a sour&e string are e%tra&ted and stored
in 5ariables. >%a&tl( 6hi&h parts, is determined b( the patterns spe&i'ied b( te#plate. te#plate &an
be a number o' patterns separated b( &ommas. A &omplete des&ription o' parsing is gi5en in &hapter
Inot (et 6rittenJ.
8' the option (&&!> is spe&i'ied, the input sour&e strings are upper&ased Fbased on lo&aleG be'ore
being split into the 5ariables spe&i'ied b( template.
8' the option LO5!> is spe&i'ied, the input sour&e strings are lo6er&ased Fbased on lo&aleG be'ore
being split into the 5ariables spe&i'ied b( template.
8' 3*S!L!SS is spe&i'ied, an( &hara&ter strings in te#plate 6ill be mat&hed against the sour&e
strings irrespe&ti5e o' &ase Fbased on lo&aleG.
49
Dhi&h strings are to be the sour&e o' the parsing is de'ined b( the type sub&lause, 6hi&h &an be an(
o':
ARG.
9he data to use as the sour&e during the parsing is the argument strings gi5en at the
in5o&ation o' this pro&edure le5el. /ote that this is the onl( &ase 6here the sour&e ma(
&onsist o' multiple strings.
LININ.
,a-es the P".S instru&tion read a line 'rom the standard input stream, as i' the
;I+I+BC built$in 'un&tion had been &alled. 8t uses the &ontents o' that line Fa'ter stripping
o'' end$o'$line &hara&ters, i' ne&essar(G as the sour&e 'or the parsing. 9his ma( raise the
+O,."A* &ondition i' problems o&&urred during the read.
!ULL.
etrie5es as the sour&e string 'or the parsing the topmost line 'rom the sta&-. 8' the sta&- is
empt(, the de'ault a&tion 'or reading an empt( sta&- is ta-en. 9hat is, it 6ill read a 6hole
line 'rom the standard input stream, strip o'' an( end$o'$line &hara&ters Fi' ne&essar(G, and
use that string as the sour&e.
SOUR".
9he sour&e string 'or the parsing is a string &ontaining in'ormation about ho6 this
in5o&ation o' the Rexx interpreter 6as started. 9his in'ormation 6ill not &hange during the
e%e&ution o' a Rexx s&ript. 9he 'ormat o' the string is:
system invocation filename
!ere, the 'irst spa&e$separated 6ord Fsyste#G is a single 6ord des&ribing the plat'orm on
6hi&h the s(stem is running. O'ten, this is the name o' the operating s(stem. 9he se&ond
6ord des&ribes ho6 the s&ript 6as in5o-ed. 932 suggests that invocation &ould be
$O33"+A, @U+$,IO+, or SUI.OU,I+, but notes that this ma( be spe&i'i& to 4,#C,S.
>5er(thing a'ter the se&ond 6ord is implementation$dependent. 8t is indi&ated that it should
re'er to the name o' the Rexx s&ript, but the 'ormat is not spe&i'ied. 8n pra&ti&e, the 'ormat
6ill di''er be&ause the 'ormat o' 'ile names di''ers bet6een 5arious operating s(stems. Also,
the part a'ter the se&ond 6ord might &ontain other t(pes o' in'ormation. e'er to the
implementation$spe&i'i& notes 'or e%a&t in'ormation.
#ALU e$%r &IT'.
9his 'orm 6ill e5aluate e$pr and use the result o' that e5aluation as the sour&e string to be
parsed. 9he to-en JI,9 ma( not o&&ur inside e$pr, sin&e it is a reser5ed sub-e(6ord in this
&onte%t.
#AR ()*bol.
9his 'orm uses the &urrent 5alue o' the named 5ariable sy#bol Fa'ter tail$substitutionG as the
sour&e string to be parsed. 9he 5ariable ma( be an( 5ariable s(mbol. 8' the 5ariable is
uninitialiHed, then a +O,."A* &ondition 6ill be raised.
#RSION.
9his 'ormat resembles SOU.$, but it &ontains in'ormation about the 5ersion o' Rexx that
the interpreter supports. 9he string &ontains 'i5e 6ords, and has the 'ollo6ing 'ormat:
50
language level date month year
Dhere language is the name o' the language supported b( the Rexx interpreter. 9his ma(
seem li-e o5er-ill, sin&e the language is Rexx, but there ma( be 5arious di''erent diale&ts o'
Rexx. 9he 6ord &an be \ust about an(thing, e%&ept 'or t6o restri&tions, the 'irst 'our letters
should be .-- Fin upper &aseG, and the 6ord should not &ontain an( periods. I932J
indi&ates that the remainder o' the 6ord Fa'ter the 'ourth &hara&terG &an be used to identi'(
the implementation.
9he se&ond 6ord is the Rexx language le5el supported b( the interpreter. /ote that this is
not the same as the 5ersion o' the interpreter, although se5eral implementations ma-es this
mista-e. Stri&tl( spea-ing, neither I931J nor I932J de'ine the 'ormat o' this 6ord, but a
numeri& 'ormat is strongl( suggested.
9he last three 6ords Fdate, #onth, and yearG ma-es up the date part o' the string. 9his is the
release date o' the interpreter, in the de'ault 'ormat o' the A",BC built$in 'un&tion.
,u&h &on'usion seems to be related to the se&ond 6ord o' P".S V.SIO+. 8t des&ribes the
language le5el, 6hi&h is not the same as the 5ersion number o' the interpreter. 8n 'a&t, most
interpreters ha5e a 5ersion numbering 6hi&h is independent o' the Rexx language le5el.
0n'ortunatel(, se5eral interpreters ma-es the mista-e o' using this 'ield as 'or their o6n 5ersion
number. 9his is 5er( un'ortunate 'or t6o reasons7 'irst, it is in&orre&t, and se&ond, it ma-es it
di''i&ult to determine 6hi&h Rexx language le5el the interpreter is supposed to support.
Chan&es are that (ou &an 'ind the interpreter 5ersion number in P".S SOU.$ or the 'irst 6ord
o' P".S V.SIO+.
9he 'ormat o' the Rexx language le5el is not rigidl( de'ined, but 931 &orresponds to the language
le5el =.50, 6hile 932 &orresponds to the language le5el <.00. :oth impli&itl( indi&ate the that
language le5el des&ription is a number, and states that an implementation less than a &ertain number
;ma( be assumed to indi&ate a subset; o' that language le5el. !o6e5er, this must not be ta-en to
literall(, sin&e language le5el =.50 has at least t6o 'eatures 6hi&h are missing in language le5el <.00
Fthe Scan tra&e setting, and the P.O$AU. instru&tion that is not 'or&ed to be the 'irst instru&tion
in a subroutineG. I9!:"8C>J gi5es a 5er( good o5er5ie6 o5er the 5ar(ing 'un&tionalit( o'
di''erent language le5els o' Rexx up to le5el <.00.
Dith the release o' the A/S8 Rexx Standard IA/S8J in 1**?, the Rexx language 8S no6 rigidl(
de'ined. 9he language le5el o' A/S8 Rexx is 5.00. egina is no6 &ompliant to the A/S8 Standard.
9hus "AS> 4>S8O/ 6ill return 5.00.
/ote that e5en though the in'ormation o' the P".S SOU.$ is &onstant throughout the e%e&ution
o' a Rexx s&ript, this is not ne&essaril( &orre&t 'or the P".S V.SIO+. 8' (our interpreter
supports multiple language le5els Fe.g. through the OP,IO+S instru&tionG, then it 6ill ha5e to
&hange the &ontents o' the P".S V.SIO+ string in order to &ompl( 6ith di''erent language
le5els. 9o some e%tent, this ma( also appl( to P".S SOU.$, sin&e it ma( ha5e to &ompl( 6ith
se5eral implementation$spe&i'i& standards.
A'ter the sour&e string has been sele&ted b( the type sub&lause in the P".S instru&tion, this string
is parsed into the te#plate. 9he 'un&tionalit( o' templates is &ommon 'or the P".S, ".> and
51
PU;; instru&tions, and is 'urther e%plained in &hapter Inot (et 6rittenJ.
2.4.12 The PR-CE$<RE Instruction
P.O$AU. F -POS F varref F varref ... G G G E
varref : K symbol D B symbol C L
9he P.O$AU. instru&tion is used b( Rexx subroutines in order to &ontrol ho6 5ariables are
shared among routines. 9he simplest use is 6ithout an( parameters7 then all 'uture re'eren&es to
5ariables in that subroutine re'er to lo&al 5ariables. 8' there is no P.O$AU. instru&tion in a
subroutine, then all 5ariable re'eren&es in that subroutine re'er to 5ariables in the &alling routinePs
name spa&e.
8' the -POS sub-e(6ord is spe&i'ied too, then an( re'eren&es to the 5ariables in the list
'ollo6ing -POS re'er to lo&al 5ariables, but to 5ariables in the name spa&e o' the &alling routine.
!"amp$eA Dynamic e"ec#ti1n 1 PROCEDURE
9he de'inition opens 'or some strange e''e&ts, &onsider the 'ollo6ing &ode:
call 'es'ing
'es'ingH
say (oo
6roce1ure e&6ose bar
say (oo
!ere, the 'irst re'eren&e to @OO is to the 5ariable @OO in the &aller routinePs name spa&e, 6hile the
se&ond re'eren&e to @OO is to a lo&al 5ariable in the &alled routinePs name spa&e. 9his is di''i&ult to
parse stati&all(, sin&e the names to e%pose Fand e5en 6hen to e%pose themG is determined
d(nami&all( during run$time. /ote that this use o' P.O$AU. is allo6ed in I931J, but not in
I932J.
Se5eral restri&tions ha5e been imposed on P.O$AU. in I932J in order to simpli'( the
e%e&ution o' P.O$AU. Fand in parti&ular, to ease the implementation o' optimiHing interpreters
and &ompilersG.
9he 'irst restri&tion, to 6hi&h all Rexx interpreters adhere as 'ar as 8 -no6, is that ea&h
in5o&ation o' a subroutine Fi.e. not the main programG ma( e%e&ute P.O$AU. at most on&e.
:oth 931 and 932 &ontain this restri&tion. !o6e5er, more than one P.O$AU. instru&tion
ma( e%ist ;in; ea&h routine, as long as at most one is e%e&uted at ea&h in5o&ation o' the
subroutine.
9he se&ond restri&tion is that the P.O$AU. instru&tion must be the 'irst statement in the
subroutine. 9his restri&tion 6as introdu&ed bet6een Rexx language le5el =.50 and <.00, but
se5eral le5el <.00 interpreters ma( not en'or&e it, sin&e there is no brea-age 6hen allo6ing it.
9here are se5eral important &onseKuen&es o' this se&ond restri&tion:
52
F1G it impli&itl( in&ludes the 'irst restri&tion listed abo5e, sin&e onl( one instru&tion &an be the 'irst7
F2G it prohibits sele&ting one o' se5eral possible P.O$AU. instru&tions7 F=G it prohibits using the
same 5ariable name t6i&e7 'irst as an e%posed and then as a lo&al 5ariable, as indi&ated in the
e%ample abo5e7 F<G it prohibits the &ustomar( use o' P.O$AU. and I+,.P.,, 6here the
latter is used to &reate a le5el o' indire&tness 'or the P.O$AU. instru&tion. 9his parti&ular use
&an be e%empli'ied b(:
'es'ingH
in'er6re' /6roce1ure e&6ose/ bar
6here I". holds a list o' 5ariable names 6hi&h are to be e%posed. !o6e5er, in order to ma-e this
'un&tionalit( a5ailable 6ithout ha5ing to resort to I+,.P.,, 6hi&h is generall( &onsidered
;bad; programming st(le, ne6 'un&tionalit( has been added to P.O$AU. bet6een language
le5els =.50 and <.00. 8' one o' the 5ariables in the list o' 5ariables is en&losed in parentheses, that
means indire&tion. 9hen, the 5ariables e%posed are: F1G the 5ariable en&losed in parentheses7 F2G the
5alue o' that 5ariable is read, and its &ontents is ta-en to be a spa&e$separated list o' 5ariable names7
and F=G all there 5ariable names are e%posed stri&tl( in order 'rom le't to right.
Example" Indirect exposing
Consider the 'ollo6ing e%ample:
'es'ingH
6roce1ure e&6ose (oo BbarC ba?
Assuming that the 5ariable I". holds the 5alue one '0o, then 5ariables e%posed are the
'ollo6ing: @OO, I"., O+, ,JO, I"R, in that order. 8n parti&ular, note that the 5ariable @OO is
e%posed immediatel( be'ore the 5ariables 6hi&h it names are e%posed.
Example" -rder of exposing
9hen there is another 'ine point about e%posing, the 5ariables are hidden immediatel( a'ter the
-POS sub-e(6ord, so the( are not initiall( a5ailable 6hen the 5ariable list is pro&essed.
Consider the 'ollo6ing &ode:
'es'ingH
6roce1ure e&6ose bar (oo.bar (oo.ba? ba?
6hi&h e%poses 5ariables in the order spe&i'ied. 8' the 5ariable I". holds the 5alue 1#7, then
@OO.1#7 is e%posed as the se&ond item, sin&e I". is 5isible a'ter ha5ing alread( been e%posed as
the 'irst item. On the other hand, the third item 6ill al6a(s e%pose the 5ariable @OO.I"R, no
matter 6hat the 5alue o' I"R is in the &aller, sin&e the I"R 5ariable is 5isible onl( a'ter it has been
used in the third item. 9here'ore, the order in 6hi&h 5ariables are e%posed is important. So, i' a
&ompound 5ariable is used inside parentheses in an P.O$AU. instru&tion, then an( simple
s(mbols needed 'or tail substitution must pre5iousl( to ha5e been e%pli&itl( e%posed. Compare this
to the A.OP instru&tion.
Dhat e%a&tl( is e%posingS Dell, the best des&ription is to sa( that it ma-es all 'uture uses F6ithin
53
that pro&edural le5elG to a parti&ular 5ariable name re'er to the 5ariable in the &alling routine rather
than in the lo&al subroutine. 9he impli&ation o' this is that e5en i' it is dropped or it has ne5er been
set, an e%posed 5ariable 6ill still re'er to the 5ariable in the &alling routine. Another important
thing is that it is the tail$substituted 5ariable name that is e%posed. So i' (ou e%pose @OO.I"., and
I". has the 5alue 1#7, then onl( @OO.1#7 is e%posed, and &ontinues to be so, e5en i' I". later
&hanges its 5alue to e.g. #78.
Example" ,lobal *ariables
A problem lur-ing on ne6 Rexx users, is the 'a&t that e%posing a 5ariable onl( e%poses it to the
&alling routine. 9here'ore, it is in&orre&t to spea- o' global 5ariables, sin&e the 5ariable might be
lo&al to the &alling routine. 9o illustrate, &onsider the 'ollo6ing &ode:
(oo : /bar/
call sub1
call sub#
e&i'
sub1H 6roce1ure e&6ose (oo
say (oo /5 (irs' says /bar/) '!en /@OO/ 5/
re'urn
sub#H 6roce1ure
say (oo /5 says /@OO/ 5/
call sub1
re'urn
!ere, the 'irst subroutine &all in the ;main; program 6rites out bar, sin&e the 5ariable @OO in
SUI1 re'ers to the @OO 5ariable in the main programPs Fi.e. its &aller routinePsG name spa&e. 2uring
the se&ond &all 'rom the main program, SUI# 6rites out @OO, sin&e the 5ariable is not e%posed.
!o6e5er, SUI# &alls SUI1, 6hi&h e%poses @OO, but that subroutine also 6rites out @OO. 9he
reason 'or this is that -POS 6or-s on the run$time nesting o' routines, not on the t(pographi&al
stru&ture o' the &ode. So the P.O$AU. in SUI1 Fon its se&ond in5o&ationG e%poses @OO to
SUI#, not to the main program as t(pograph( might 'alsel( indi&ate.
9he o'ten &on'using &onseKuen&e o' the run$time binding o' 5ariable names is that an e%posed
5ariable o' SUI1 &an be bound to di''erent global 5ariables, depending on 'rom 6here it 6as &alled.
9his di''ers 'rom most &ompiled languages, 6hi&h bind their 5ariables independentl( o' 'rom 6here
a subroutine is &alled. 8n turn, the &onseKuen&e o' this is that Rexx has se5ere problems storing a
persistent, stati& 5ariable 6hi&h is needed b( one subroutine onl(. A subroutine needing su&h a
5ariable Fe.g. a &ount 5ariable 6hi&h is in&remented ea&h time the subroutine is &alledG, must either
use an operating s(stem &ommand, or all subroutines &alling that subroutine Fand their &alling
routines, et&.G must e%pose the 5ariable. 9he 'irst o' these solution is 5er( inelegant and non$
standard, 6hile the se&ond is at best troublesome and at 6orst seriousl( limits the ma%imum
pra&ti&al siHe o' a Rexx program. 9here are hopes that the V";UBC built$in 'un&tion 6ill 'i% this
in 'uture standards o' Rexx.
Another important dra6ba&- 6ith P.O$AU. is that it onl( 6or-s 'or internal subroutines7 'or
54
e%ternal subroutines it either do not 6or-, or P.O$AU. ma( not e5en be allo6ed on the main
le5el o' the e%ternal subroutine. !o6e5er, in internal subroutines inside the e%ternal subroutines,
P.O$AU. is allo6ed, and 6or-s li-e usual.
2.4.13 The P<## Instruction
PU;; F template G E
9his statement ta-es a line 'rom the top o' the sta&- and parse it into the 5ariables in the te#plate. 8t
6ill also translate the &ontents o' the line to upper&ase.
9his statement is eKui5alent to P".S UPP. PU;; Ftemplate J 6ith the same e%&eption as
e%plained 'or the ".> instru&tion. See &hapter Inot (et 6rittenJ 'or a des&ription o' parsing and
&hapter Sta&- 'or a dis&ussion o' the sta&-.
2.4.15 The P<!6 Instruction
PUS9 F expr G E
9he PUS9 instru&tion 6ill add a string to the sta&-. 9he string added 6ill either be the result o' the
e$pr, or the nullstring i' e$pr is not spe&i'ied.
9he string 6ill be added to the top o' the sta&- F381OG, i.e. it 6ill be the 'irst line normall( e%tra&ted
'rom the sta&-. 1or a thorough dis&ussion o' the sta&- and the methods o' manipulating it, see
&hapter Sta&- 'or a dis&ussion o' the sta&-.
2.4.17 The =<E<E Instruction
UUU F expr G E
9he UUU instru&tion is identi&al to the PUS9 instru&tion, e%&ept 'or the position in the sta&-
6here the ne6 line is inserted. Dhile the PUS9 puts the line on the ;top; o' the sta&-, the UUU
instru&tion inserts it at the bottom o' the sta&- F181OG, or in the bottom o' the topmost bu''er, i'
bu''ers are used.
1or 'urther in'ormation, re'er to do&umentation 'or the PUS9 instru&tion, and see &hapter Sta&- 'or
general in'ormation about the sta&-.
2.4.19 The RET<R' Instruction
.,U.+ F expr G E
9he .,U.+ instru&tion is used to terminate the &urrent pro&edure le5el, and return &ontrol to a
le5el abo5e. Dhen .,U.+ is e%e&uted inside one or more nesting &onstru&t, i.e. AO, I@, J9+, or
O,9.JIS, then the nesting &onstru&ts Fin the pro&edural le5els being terminatedG are terminated
too.
Optionall(, an e%pression &an be spe&i'ied as an argument to the .,U.+ instru&tion, and the string
resulting 'rom e5aluating this e%pression 6ill be the return 5alue 'rom the pro&edure le5el
terminated to the &aller pro&edure le5el. Onl( a single 5alue &an be returned. Dhen .,U.+ is
e%e&uted 6ith no argument, no return 5alue is returned to the &aller, and then a S*+,"- &ondition
Z<<[ is raised i' the subroutine 6as in5o-ed as a 'un&tion.
55
Example" )ultiple entr& points
A routine &an ha5e multiple e%it points, i.e. a pro&edure &an be terminated b( an( o' se5eral
.,U.+ instru&tions. A routine &an also ha5e multiple entr( points, i.e. se5eral routine entr( points
&an be terminated b( the same .,U.+ instru&tion. !o6e5er, this is rarer than ha5ing multiple e%it
points, be&ause it is generall( per&ei5ed that it &reates less stru&tured and readable &ode. Consider
the 'ollo6ing &ode:
call (oo
call bar
call ba?
e&i'
(ooH
i( 1a'a'y6eBna%e) /0/C '!en
1ro6 na%e
signal ba?
barH
na%e : /(oo/
ba?H
i( sy%bolB/na%e/C:: /V"./ '!en
say /+"3 curren'ly !as '!e value/ na%e
else
say /+"3 is curren'ly an unse' variable/
re'urn
Although this is hardl( a 5er( pra&ti&al e%ample, it sho6s ho6 the main bul- o' a routine &an be
used together 6ith three di''erent entr( points. 9he main part o' the routine is the I@ statement
ha5ing t6o S"* statements. 8t &an be in5o-ed b( &alling @OO, I"., or I"R.
9here are se5eral restri&tions to this approa&h. 1or instan&e, the P.O$AU. statement be&omes
&umbersome, but not impossible, to use.
Also note that 6hen a routine has multiple e%it points, it ma( &hoose to return a return 5alue onl( at
some o' those e%it points.
Dhen a routine is lo&ated at the 5er( end o' a sour&e 'ile, there is an impli&it .,U.+ instru&tion
a'ter the last e%pli&it &lause. !o6e5er, a&&ording to good programming pra&ti&e, (ou should a5oid
ta-ing ad5antage o' this 'eature, be&ause it &an &reate problems later i' (ou append ne6 routines to
the sour&e 'ile and 'orget to &hange the implied .,U.+ to an e%pli&it one.
8' the &urrent pro&edure le5el is the main le5el o' either the program or an e%ternal subroutine, then
a .,U.+ instru&tion is eKui5alent to an -I, instru&tion, i.e. it 6ill terminate the Rexx program
or the e%ternal routine. 9he table in the >%it se&tion sho6s the a&tions o' both the .,U.+ and
-I, instru&tions depending on the &onte%t in 6hi&h the( o&&ur.
56
2.4.2: The !(> Instruction
S"* F expr G E
>5aluates the e%pression e$pr, and prints the resulting string on the standard output stream. 8' e$pr
is not spe&i'ied, the nullstring is used instead. A'ter the string has been 6ritten, an implementation$
spe&i'i& a&tion is ta-en in order to produ&e an end$o'$line.
9he S"* instru&tion is roughl( eKui5alent to
call lineou' ) e&6r
9he di''eren&es are that there is no 6a( o' determining 6hether the printing 6as su&&ess'ull(
&ompleted i' S"* is used, and the spe&ial 5ariable .SU;, is ne5er set 6hen e%e&uting a S"*
instru&tion. :esides, the e''e&t o' omitting e$pr is di''erent. 8n SAA A"8, the .-SIOS"*
sub'un&tion o' the .-SIO e%it handler is able to trap a S"* instru&tion, but not a &all to the
;I+OU,BC built$in 'un&tion. 1urther, the +O,."A* &ondition is ne5er raised 'or a S"*
instru&tion.
2.4.21 The !E#ECT.?6E'.-T6ER?I!E Instruction
S;$, E whenpart F whenpart ... G F O,9.JIS FEG
F statement ... G G +A E
whenpart H J9+ expr FEG ,9+ FEG statement
9his instru&tion is used 'or general purpose, nested I@ stru&tures. An e%ample o' the general use o'
the S;$, instru&tion is:
selec'
0!en e&6r1 '!en s'a'e%en'1
0!en e&6r# '!en 1o
s'a'e%en'#a
s'a'e%en'#b
en1
0!en e&6r7 '!en s'a'e%en'7
o'!er0ise
os'a'e%en'1
os'a'e%en'#
en1
Dhen the S;$, instru&tion is e%e&uted, the ne%t statement a'ter the S;$, statement must be
a J9+ statement. 9he e%pression immediatel( 'ollo6ing the J9+ to-en is e5aluated, and must
result in a 5alid boolean 5alue. 8' it is true Fi.e. 1G, the statement 'ollo6ing the ,9+ to-en
mat&hing the J9+ is e%e&uted, and a'ter6ards, &ontrol is trans'erred to the instru&tion 'ollo6ing
the +A to-en mat&hing the S;$, instru&tion. 9his is not &ompletel( true, sin&e an instru&tion
ma( trans'er &ontrol else6here, and thus impli&itl( terminate the S;$, instru&tion7 e.g. ;"V,
-I,, I,.",, SI>+";, or .,U.+ or a &ondition trapped b( method SI>+";.
8' the e%pression o' the 'irst J9+ is not true Fi.e. <G, then the ne%t statement must be either another
57
J9+ or an O,9.JIS statement. 8n the 'ormer &ase, the pro&ess e%plained abo5e is iterated. 8n
the latter &ase, the &lauses 'ollo6ing the O,9.JIS up to the +A statement are interpreted.
8t is &onsidered a S*+,"- &ondition, Z@[ i' no O,9.JIS statement 6hen none o' the J9+$
e%pressions e5aluates to true. 8n general this &an onl( be dete&ted during runtime. !o6e5er, i' one
o' the J9+s is sele&ted, the absen&e o' an O,9.JIS is not &onsidered an error.
:( the nature o' the S;$, instru&tion, the J9+s are tested in the seKuen&e the( o&&ur in the
sour&e. 8' more than one J9+ ha5e an e%pression that e5aluates to true, the 'irst one en&ountered is
sele&ted.
8' the programmer 6ants to asso&iate more than one statement 6ith a J9+ statement, a AO/+A
pair must be used to en&lose the statements, to ma-e them one statement &on&eptuall(. !o6e5er,
Hero, one, or more statements ma( be put a'ter the O,9.JIS 6ithout ha5ing to en&lose them in
a AO#+A pair. 9he &lause delimiter is optional a'ter O,9.JIS, and be'ore and a'ter ,9+.
!"amp$eA 5riting SELECT as IF
S;$, in Rexx is \ust a shorthand notation 'or nested I@ instru&tions. 9hus a S;$,
instru&tion &an al6a(s be 6ritten as set o' nested I@ statements7 but 'or 5er( large S;$,
statements, the &orresponding nested I@ stru&ture ma( be too deepl( nested 'or the interpreter to
handle.
9he 'ollo6ing &ode sho6s ho6 the S;$, statement sho6n abo5e &an be 6ritten as a nested I@
stru&ture:
i( e&6r1 '!en s'a'e%en'1
else i( e&6r# '!en 1o
s'a'e%en'#a
s'a'e%en'#b
en1 else i( e&6r7 '!en s'a'e%en'7
else
os'a'e%en'1
os'a'e%en'#
en1
2.4.22 The !I,'(# Instruction
SI>+"; K string D symbol L E
F V";U G expr E
K O+ D O@@ L condition F +"3
K string D symbol L G E
9he SI>+"; instru&tion is used 'or t6o purposes: FaG to trans'er &ontrol to a named label in the
program, and FbG to set up a named &ondition trap.
9he 'irst 'orm in the s(nta% de'inition trans'ers &ontrol to the named label, 6hi&h must e%ist
some6here in the program7 i' it does not e%ist, a S*+,"- &ondition Z1?[ is raised. 8' the label is
58
multiple de'ined, the 'irst de'inition is used. 9he parameter &an be either a s(mbol F6hi&h is ta-en
literall(G or a string. 8' it is a string, then be sure that the &ase o' the string mat&hes the &ase o' the
label 6here it is de'ined. 8n pra&ti&e, labels are in upper &ase, so the string should &ontain onl(
upper&ase letters too, and no spa&e &hara&ters.
9he se&ond 'orm o' the s(nta% is used i' the se&ond to-en o' the instru&tion is V";U. 9hen, the
rest o' the instru&tion is ta-en as a general Rexx e%pression, 6hi&h result a'ter e5aluation is ta-en to
be the name o' the label to trans'er &ontrol to. 9his 'orm is reall( \ust a spe&ial &ase o' the 'irst 'orm,
6here the programmer is allo6ed to spe&i'( the label as an e%pression. /ote that i' the start o'
e&6r is su&h that it &an not be misinterpreted as the 'irst 'orm Fi.e. the 'irst to-en o' e$pr is neither
a string nor a s(mbolG, then the V";U sub-e(6ord &an be omitted.
Example" Transferring control to inside a loop
Dhen the &ontrol o' e%e&ution is trans'erred b( a SI>+"; instru&tion, all a&ti5e loops at the &urrent
pro&edural le5el are terminated, i.e. the( &an not &ontinued later, although the( &an o' &ourse be
reentered 'rom the normal start. 9he &onseKuen&e o' this is that the 'ollo6ing &ode is illegal:
1o (orever
signal '!ere
'!ereH
no6
en1
9he 'a&t that the \ump is altogether 6ithin the loop does not pre5ent the loop 'rom being terminated.
9hus, a'ter the \ump to the loop, the +A instru&tion is attempted e%e&uted, 6hi&h 6ill result in a
S*+,"- &ondition Z10[. !o6e5er, i' &ontrol is trans'erred out o' the loop a'ter the label, but be'ore
the +A, then it 6ould be legal, i.e. the 'ollo6ing is legal:
1o (orever
signal '!ere
'!ereH
no6
signal a('er
en1
a('erH
9his is legal, simpl( be&ause the +A instru&tion is ne5er seen during this s&ript. Although both
931 and 932 allo6 this &onstru&t, it 6ill probabl( be disallo6ed in A/S8.
Oust as loops are terminated b( a SI>+"; instru&tion, S;$, and I@ instru&tions are also
terminated. 9hus, it is illegal to \ump to a lo&ation 6ithin a blo&- o' statements &ontained in a
J9+, O,9.JIS, or I@ instru&tion, unless the &ontrol is trans'erred out o' the blo&- be'ore the
e%e&ution rea&hes the end o' the blo&-.
Dhene5er e%e&ution is trans'erred during a SI>+"; instru&tion, the spe&ial 5ariable SI>; is set to
the line number o' the line &ontaining the SI>+"; instru&tion, be'ore the &ontrol is trans'erred. 8'
this instru&tion e%tends o5er se5eral lines, it re'ers to the 'irst o' this. /ote that e5en blan-s are part
59
o' a &lause, so i' the instru&tion starts 6ith a line &ontinuation, the real line o' the instru&tion is
di''erent 'rom that line 6here the instru&tion -e(6ord is lo&ated.
9he third 'orm o' s(nta% is used 6hen the se&ond to-en in the instru&tion is either O+ or O@@. 8n
both &ases must the third to-en in the instru&tion be then name o' a &ondition Fas a &onstant string or
a s(mbol, 6hi&h is ta-en literall(G, and the setup o' that &ondition trap is &hanged. 8' the se&ond
to-en is O@@, then the trap o' the named &ondition is disabled.
8' the se&ond to-en is O+, then the trap o' the named &ondition is enabled. 1urther, in this situation
t6o more to-ens ma( be allo6ed in the instru&tion: the 'irst must be +"3 and the se&ond must be
the name o' a label Feither as a &onstant string or a s(mbol, 6hi&h is ta-en literall(G. 8' the 'i5e
to-en 'orm is used, then the label o' the &ondition handler is set to the named label, else the name o'
the &ondition handler is set to the de'ault, 6hi&h is identi&al to the name o' the &ondition itsel'.
/ote that the +"3 sub&lause o' the SI>+"; instru&tion 6as a ne6 &onstru&t in 932, and is not a
part o' 931. 9hus, older interpreters ma( not support it.
Example" 'aming condition traps
/ote that the de'ault 5alue 'or the &ondition handler Fi' the /A,> sub&lause is not spe&i'iedG is the
name o' the &ondition, not the &ondition handler 'rom the pre5ious time the &ondition 6as enabled.
9hus, a'ter the 'ollo6ing &ode, the name o' the &ondition handler 'or the &ondition S*+,"- is
S*+,"-, not 1OO:A:
signal on syn'a& na%e (oobar
signal on syn'a&
Example" 'amed condition traps in TR#1
A &ommon problem 6hen tr(ing to port Rexx &ode 'rom a 932 interpreter to a 931 interpreter,
is that e%pli&itl( named &ondition traps are not supported. 9here e%ist 6a(s to &ir&um5ent this, li-e:
syn'a&_na%e : /S*+,"-_9"+A;./
signal on syn'a&
i( 1 = # '!en /5 0ill genera'e S*+,"- con1i'ion 5/
no6
syn'a&H
ol1sigl : sigl
signal value 'ransla'eBsyn'a&_na%eC
syn'a&_!an1lerH
say /con1i'ion a' line/ ol1sigl /is being !an1le1.../
e&i'
!ere, a ;global; 5ariable is used to store the name o' the real &ondition handler, in the absen&e o' a
'ield 'or this in the interpreter. 9his 6or-s 'ine, but there are some problems: the 5ariable
S*+,"-_+"3 must be e%posed to e5er(6here, in order to be a5ailable at all times. 8t 6ould be
'ar better i' this 5alue &ould be stored some6here 'rom 6hi&h it &ould be retrie5ed 'rom an( part o'
60
the s&ript, no matter the &urrent state o' the &all$sta&-. 9his &an be 'i%ed 6ith programs li-e
>;OI";V under 4,#C,S and 6u'env under 0ni%.
Another problem is that this destro(s the possibilit( o' setting up the &ondition handler 6ith the
de'ault handler name. !o6e5er, to &ir&um5ent this, add a ne6 A@"U;,_S*+,"-_9"+A;.
label 6hi&h be&omes the ne6 name 'or the old S*+,"- label.
1urther in'ormation about &onditions and &ondition traps are gi5en in &hapter Conditions.
2.4.23 The TR(CE Instruction
,."$ F setting D F V";U G expr G E
9he ,."$ instru&tion is used to set a tra&ing mode. 2epending on the &urrent mode, 5arious le5els
o' debugging in'ormation is displa(ed 'or the programmer. Also intera&ti5e tra&ing is allo6ed,
6here the user &an re$e%e&ute &lauses, &hange 5alues o' 5ariables, or in general, e%e&ute Rexx &ode
intera&ti5el( bet6een the statements o' the Rexx s&ript.
8' no parameters are spe&i'ied, then the de'ault 5alue + is assumed.
8' a parameter is gi5en to the ,."$ instru&tion, and the 'irst to-en in the parameters is not V";U,
then there must onl( be one to-en a'ter ,."$, and it must be either a &onstant string or a s(mbol
F6hi&h is ta-en literall(G. 9he 5alue o' this to-en &an be either a 6hole number or a tra&e setting.
8' the 'irst to-en a'ter ,."$ is V";U, then the remaining parts o' the &lause is interpreted as an
e%pression, the result o' 6hi&h is used as the tra&e setting.
8' setting is a 6hole number and the number is positi5e, then the number spe&i'ies ho6 man(
intera&ti5e pauses to s-ip i' intera&ti5e tra&ing is enabled. 8' intera&ti5e tra&ing is not enabled, this
,."$ instru&tion is ignored.
8' setting is a 6hole, negati5e number, then tra&ing is turned o'' temporaril( 'or a number o' &lauses
determined b( the absolute 5alue o' nu#ber.
8' setting is a s(mbol or string, but not a 6hole number, then the 'irst &hara&ter F'ollo6ing an(
optional Kuestion mar- FSG &hara&tersG is translated to upper &ase and must be one o' the 5alues
spe&i'ied belo6. 9he Kuestion mar- &hara&ter toggles intera&ti5e tra&ing on or o''.
+A,
FAllG 9ra&es all &lauses be'ore e%e&ution.
+C,
FCommandsG 9ra&es all &ommand &lauses be'ore e%e&ution.
+E,
F>rrorsG 9ra&es an( &ommand that 6ould raise the ..O. &ondition F6hether enabled or
notG a'ter e%e&ution. :oth the &ommand &lause and the return 5alue is tra&ed.
+F,
F1ailuresG 9ran&es an( &ommand that 6ould raise the @"I;U. &ondition F6hether enabled
61
or notG a'ter e%e&ution. :oth the &ommand &lause and the return 5alue is tra&ed.
+I,
F8ntermediateG 9ra&es not onl( all &lauses, but also tra&es all e5aluation o' e%pressions7 e5en
intermediate results. 9his is the most detailed le5el o' tra&ing.
+L,
F3abelsG 9ra&es the name o' an( label &lause e%e&uted7 6hether the label 6as \umped to or
not.
+N,
F/ormal or /egati5eG 9his is the same as the @ailure setting.
+O,
FO''G 9urns o'' all tra&ing.
+R,
FesultsG 9ra&es all &lauses and the results o' e5aluating e%pressions. !o6e5er, intermediate
e%pressions are not tra&ed.
9he rrors and @ailures settings are not in'luen&ed b( 6hether the ..O. or @"I;U.
&onditions are enabled or not. 9hese ,."$ settings 6ill tra&e the &ommand and return 5alue a'ter
the &ommand ha5e been e%e&uted, but be'ore the respe&ti5e &ondition is raised.
9he le5els o' tra&ing might be set up graphi&all(, as in the 'igure belo6. An arro6 indi&ates that the
setting pointed to is a superset o' the setting pointed 'rom.
/-Q @ailures -Q rrors -Q $o%%an1s
O(( O
O-----Q ;abels --------Q "ll -Q .esul's -Q In'er%e1ia'e
%ierarchy 1 TRACE settings
A&&ording to this 'igure, In'er%e1ia'e is a superset o' .esul', 6hi&h is a superset o' "ll.
1urther, "ll is a superset o' both $o%%an1s and ;abels. $o%%an1s is a superset o' rrors,
6hi&h is a superset o' @ailures. :oth @ailure and ;abels are supersets o' O((. A&tuall(,
$o%%an1 is stri&tl( spea-ing not a superset o' rrors, sin&e rrors tra&es a'ter the &ommand,
6hile $o%%an1 tra&es be'ore the &ommand.
Scan is not part o' this diagram, sin&e it pro5ides a &ompletel( di''erent tra&ing 'un&tionalit(. /ote
that Scan is part o' 931, but 6as remo5ed in 932. 8t is not li-el( to be part o' ne6er Rexx
interpreters.
62
2.4.24 The <PPER Instruction
UPP. sy%bol F sy%bol F sy%bol F...G G G E
9he 0""> instru&tion is used to translate the &ontents o' one or more 5ariables to upper&ase. 9he
5ariables are translated in seKuen&e 'rom le't to right.
>a&h s(mbol is separated b( one or more blan-s.
Dhile it is more &on5enient and probabl( 'aster than indi5idual &alls to 9A/S3A9>, 0""> is
not part o' the A/S8 standard and is not &ommon in other interpreters so should be a5oided. 8t is
pro5ided to ease porting o' programs 'rom C,S.
Onl( simple and &ompound s(mbols &an be spe&i'ied. Spe&i'i&ation o' a stem 5ariable results in an
error.
2.2 -perators
An operator represents an operation to be &arried out bet6een t6o terms, su&h as di5ision. 9here are
5 groups o' operators in the Rexx 3anguage: 'rith#etic, 'ssign#ent, !o#parative,
!oncatenation, and Logical Operators. 9he groups are sho6n belo6 in des&ending order o'
pre&eden&e 6ith 'urther details 'or group. 9he de'ined pre&eden&e o' operators &an be o5erridden b(
the use o' mat&hing pairs o' parentheses: FG.
2.2.1 (rithmetic -perators
Arithmeti& operators &an be applied to numeri& &onstants and Rexx 5ariables that e5aluate to 5alid
Rexx numbers. 9he 'ollo6ing operators are grouped in de&reasing order o' pre&eden&e:
' 0nar( pre'i%. Same as 0 B n#mber:
C 0nar( pre'i%. Same as 0 C n#mber:
_.....................................................................................................................................
DD "o6er.
_.....................................................................................................................................
D ,ultipl(.
4 2i5ide.
E 8nteger di5ide. 2i5ide and return the integer part o' the di5ision.
44 emainder di5ide. 2i5ide and return the remainder o' the di5ision.
_.....................................................................................................................................
C Add.
' Subtra&t.
2.2.2 (ssignment -perators
Assignment operators are a means to &hange the 5alue o' a 5ariable. Rexx onl( has one assignment
operator.
F Assign the 5alue on the right side o' the ;R; to the 5ariable on the le't.
2.2.3 Concatenation -perators
9he &on&atenation operators &ombine t6o strings to 'orm one, b( appending the se&ond string to the
right side o' the 'irst. 9he Rexx &on&atenation operators are:
63
Fb$an;G Con&atenation o' strings 6ith one spa&e bet6een them.
Fab#tta$G Con&atenation o' strings 6ith no inter5ening spa&e.
GG Con&atenation o' strings 6ith no inter5ening spa&e.
>%amples:
a = ab-.b = /0ef/
Sa) a b 12 re(3l4( 56 /ab- 0ef/
Sa) a 77 b 12 re(3l4( 56 /ab-0ef/
Sa) a/$)8/ 12 re(3l4( 56 /ab-$)8/
2.2.4 Comparati*e -perators
9he Rexx &omparati5e operators &ompare t6o terms and return the logi&al 5alue 1 i' the result o'
the &omparison is true, or 0 i' the result o' the &omparison is 'alse. 9he non$stri&t &omparati5e
operators 6ill ignore leading or trailing blan-s 'or string &omparisons, and leading Heros 'or
numeri& &omparisons. /umeri& &omparisons are made i' both terms to be &ompared are 5alid Rexx
numbers, other6ise string &omparison is done. String &omparisons are &ase sensiti5e, and the
shorter o' the t6o strings is padded 6ith blan-s.
9he 'ollo6ing lists the non$stri&t &omparati5e operators.
F >Kual
HFI JF /ot eKual
K .reater than.
L 3ess than.
KF .reater than or eKual.
LF 3ess than or eKual
LKI KL .reater than or less than. Same as /ot eKual.
9he 'ollo6ing lists the stri&t &omparati5e operators. 1or t6o strings to be &onsidered eKual 6hen
using the stri&t eKual &omparati5e operator, both strings must be the same length.
FF Stri&tl( eKual
HFFI JFF Stri&tl( not eKual.
KK Stri&tl( greater than.
LL Stri&tl( less than.
KKF Stri&tl( greater than or eKual.
LLF Stri&tl( less than or eKual.
2.2.2 #ogical -perators
3ogi&al operators 6or- 6ith the Rexx strings 1 and 0, usuall( as a result o' a &omparati5e operator.
9hese operators also onl( result in logi&al 90>7 1 or logi&al 1A3S>7 0. 9he logi&al operators are
sho6n in de&reasing order o' pre&eden&e.
M And eturns 1 i' both terms are 1, other6ise returns 0.
G 8n&lusi5e or eturns 1 i' either term is 1, other6ise returns 0.
MM >%&lusi5e or eturns 1 i' either term is 1 but not i' both terms are 1, other6ise
returns 0.
H 3ogi&al not e5erses the result7 0 be&omes 1 and 1 be&omes 0.
64
2.3 !pecial ;ariables
9he Rexx 3anguage de'ines a number o' spe&ial 5ariables 6hi&h are set b( the interpreter during
the e%e&ution o' a program. 9here are t6o t(pes o' spe&ial 5ariables. 9he 'irst are spe&ial 5ariables
that are lo&al in s&ope and &an be &hanged b( the programmer. 9he se&ond are global in s&ope and
&annot be &hanged b( the programmer.
2.3.1 #ocal !cope @ <ser ?riteable
9hese 5araibles are lo&al in s&ope and &an be &hanged b( the user at an( time. 9he 5alues o' these
5ariables 6ill ho6e5er be set b( the interpreter during the e%e&ution o' the program.
RC - (ANSI)
9his 5ariable is set b( an( e%e&uted &ommand in&luding those e%e&uted 5ia "AA.SS. /ote that
C is not set 'or &ommands e%e&uted manuall( 6hile training intera&ti5el(.
RESULT - (ANSI)
9his 5ariable is set b( the .,U.+ instru&tion in a subroutine that has been $";;e1 pro5ided that
the .,U.+ instru&tion &ontains an e%pression. >S039 is dropped i' the .,U.+ instru&tion
&ontains no e%pression.
SIGL - (ANSI)
Contains the line number o' instru&tion e%e&uted that &aused a \ump to a label.
2.3.2 ,lobal !cope @ Read8-nl&
As these 5ariables begin 6ith a period, the( &annot be &hanged b( the programmer. 9hese 5araibles
are global in s&ope.
.MN - (ANSI)
Dhen a S*+,"- &ondition has been raised, this 5ariable is set to the error message number
Fin&luding sub$error numberG that &aused the S*+,"- &ondition.
.RC - (ANSI)
Contains the same 5alues as the spe&ial 5ariable7 C.
.RS - (ANSI)
9his 5ariable is an indi&ator as to 6hether the last &ommand e%e&uted ga5e rise to a @"I;U. or
..O. &ondition.
.RESULT - (ANSI)
Contains the same 5alues as the spe&ial 5ariable7 >S039.
.LINE - (Regina)
9his spe&ial 5ariable &ontains the line number o' the Rexx program.
.ENDOFLINE - (Regina)
9his spe&ial 5ariable &ontains the de'ault end o' line &hara&ter seKuen&e 'or the plat'orm on 6hi&h
Regina is &urrentl( running. 8n general this 6ill be 31 F%0dG on 0ni%#3inu%#"osi% plat'orms C
F%0aG on ,a& plat'orms, and C31 F%0a0dG on all others.
65
2.5 Implementation8!pecific Information
2.5.1 )iscellaneous
OPTIONS (e4456g(
Are sa5ed a&ross subroutines, \ust li-e other pie&es o' in'ormation, li-e &onditions settings,
+U3.I$ settings, et&. See &hapter Options 'or more in'ormation about OP,IO+S settings.
Re43r6 9al3e
9o the program that &alled egina is limited to being an integer, 6hen this is reKuired b( the
operating s(stems. All &urrent implementations are 'or operating s(stems that reKuire this.
Defa3l4 re43r6 9al3e
1rom a Rexx program is < under most s(stems, spe&i'i&all( 0ni%, OS#2, ,S$2OS. !ere,
4,S de5iates, sin&e it uses 1 as the de'ault return 5alue. 0sing < under 4,S tends to ma-e
4,S issue a 6arning sa(ing that no error o&&urred.
Tra6(ferr56g -o64rol 564o a loo%
Dor-s 'ine in egina, as long as no +A, ,9+, ;S, J9+, or O,9.JIS instru&tions
are e%e&uted a'ter6ards7 unless the normal entr($point 'or the &onstru&t has been e%e&uted
a'ter the trans'er o' &ontrol.
!ARS SOUR" 56for*a45o6
!ARS #RSION 56for*a45o6
La(4 l56e of (o3r-e -o0e
8s impli&itl( ta-en to be terminated b( an end$o'$line seKuen&e in egina, e5en i' su&h a
seKuen&e is not present in the sour&e &ode o' the Rexx s&ript. 9his applies onl( to sour&e
&ode. Also, the end$o'$string in I+,.P., strings is ta-en to be impli&itl( terminated b(
an end$o'$line &hara&ter seKuen&e.
Mo956g -o0e MS1DOS 4o U65$
8s simpli'ied b( egina, sin&e it 6ill a&&ept the ,S$2OS t(pe end o' line seKuen&es as
5alid. i.e. an( Ctrl$, in 'ront o' a Ctrl$O in the sour&e 'ile is ignored on 0ni% s(stems b(
egina. 9his applies onl( to sour&e &ode.
Label( 56 INTERPRET
8s handled b( egina in the 'ollo6ing 6a(: A label &an o&&ur inside an I+,.P., string,
but it is ignored, and &an ne5er be \umped to in a SI>+"; or $";; instru&tion.
2.5.2 Implementation of the ($$RE!! en*ironment
,ost people ha5e problems in5o-ing e%ternal programs. 9his se&tion sho6s the basi& rules, and
some tri&-s to let (ou use Regina and other Rexx interpreters su&&ess'ull(.
>5er( &all to an e%ternal program is e%e&uted b( an impli&it "AA.SS statement.
66
/ec!o 9ello 6lane'/
is eKui5alent to
"AA.SS curren'environ%en' /ec!o 9ello 6lane'/
9he de'ault en5ironment is S*S,3 in Regina and man( other Rexx interpreters.
>5er( "AA.SS en5ironment has its o6n purpose and ad5antages. 8t is a good idea to use
"AA.SS in 'ront o' ea&h &ommand. >5er(bod( -no6s 6hat happens in this &ase. And (ou &an
&hoose the best en5ironment 'or the &ommand.
!>!TE) a+a E';IR-')E'T a+a -!2E';IR-')E'T
9his is the all$purpose solution 'or e5er( &ommand. 9he &ommand is passed to the &urrent
&ommand interpreter. 8t is generall( the best option 'or most &ommands, but is has some
disad5antages:
Cou donPt ha5e &ontrol o5er the di''erent interpreters. Cou &an get ugl( errors in Dindo6s /9,
2000, A" or in uni&es i' (ou donPt -no6 ho6 the interpreter interprets (our &ommand.
Cou ha5e some trouble passing spe&ial &hara&ters to the &ommand. !a5e (ou e5er( tried to pass
a ;>; sign to a &ommandS Cou 6onPt get 6hat (ou e%pe&t i' (ou donPt -no6 ho6 to Kuote it to
b(pass the interpreter.
Cou in5o-e a separate program \ust to in5o-e another program. 8t &osts time and memor( usage.
Choosing another en5ironment ma( lead to a Kui&-er and sa'er e%e&ution.
0se S*S,3 i' (ou 6ant to use pipelines and redire&tions o' the interpreter or i' (ou 6ant to use a
built$in &ommand o' the shell. ;e&ho; is a built$in &ommand in &ommand interpreters. Also, the
0ni% pipeline o' &ommands li-e ;prog1 Q prog2 Q prog=; &annot be represented shorter in Regina.
C-))('$ a+a C)$ a+a P(T6
9his is the right A22>SS en5ironment i' (ou -no6 the &alled programPs name but not 6here it is
on dis-. One e%ample is ;sort; in man( s(stems.
Sin&e Regina has AN!Ps e%tremel( use'ul "AA.SS JI,9 te&hniKue, (ou &an 5er( e''e&ti5el(
sort Kueue &ontents or stem lea5es b(:

"AA.SS P",9 /sor'/ JI,9 I+PU, S,3 unsor'. OU,PU, S,3 sor'.
Cou let Regina 'ind the program PsortP For SO9.>A> i' (ou use Dindo6sG and get the 'astest 6a(
to do it. Cou donPt ha5e to bother about the &urrent &ommand interpreter7 Regina a&ts as one. Cou
&an pass e5er( &hara&ter (ou 6ant and Regina does its best to let it appear in the &alled program. 8'
(ou 6ant to spe&i'( a spe&i'i& program, simpl( spe&i'( the 'ull( Kuali'ied 'ilename o' the &ommand
to e%e&ute.
RE44 or RE,I'(
0se this i' (ou 6ant to e%e&ute a Rexx program in a separate instan&e o' the interpreter. Dhereas a
normal $";; on an e%ternal program 6ill run the e%ternal Rexx program in the &urrent instan&e o'
Regina, this allo6s the e%ternal Rexx program to run in a ne6, independent instan&e o' Regina.
0se this en5ironment i':
67
1. 9he &alled interpreter is unstable and a &rash in it should not a''e&t the &urrent e%e&ution. A
&ommon situation 6here (ou 6ant it, is an e%ternal program librar( (ou &an bind 6ith
.&@unc"11. Su&h a librar( &an &rash or terminate the interpreter. 9he &alling interpreter 6onPt
be a''e&ted b( this termination.
2. Cou 6ant to ta-e ad5antage o' the po6er'ul "AA.SS JI,9 redire&tion. 9he general
me&hanism to &ommuni&ate 6ith e%ternal s&ripts is a Kueue, but (ou donPt ha5e this in &ases
6here (ou 6ant to pass error messages in a di''erent 6a( or i' (ou use a s&ript 6hi&h 6asnPt
designed to use Kueues originall(.
=. 9he &urrent interpreter shall be reused and (ou 6ant to ta-e ad5antage o' the se&ond point. Cou
ma( ha5e di''erent Regina interpreters and (ou 6ant to use \ust the &urrent interpreter e5en i' it
isnPt in (our path. Regina tries to load the &urrent interpreter a se&ond time i' (ou use this
"AA.SS en5ironment. 9here is no di''eren&e bet6een "AA.SS .-- and "AA.SS
.>I+". Regina also attempts to load the same e%e&utable that the &urrent instan&e 6as started
'rom, but not e5er( s(stem passes enough in'ormations to Regina to 'ind its o6n e%e&utable in
all &ases.
($RRE!! ?IT6 on ?indos
edire&tion o' programPs input and#or output in general is relati5el( predi&table on most operating
s(stems, ho6e5er mention must be made o' beha5iour spe&i'i& to the Dindo6s plat'orm.
Dindo6s and to a lesser degree OS#2, ha5e te&hniKues to hide 6indo6s, to start programs in
separate 6indo6s and other cool 'eatures. 1lorian did some signi'i&ant testing o' this on all
di''erent Dindo6s plat'orms and there is bad ne6s. 9here is no &onsistent me&hanism to start
e%ternal programs 6ithout error and 'ull &ontrol. Sounds strange, is strange. De ha5e the options to:
use the interpreter F"AA.SS S*S,3G or not F"AA.SS P",9 or $3AG
start .08 or te%t mode programs
&hoose the interpreter FC,2.>A> or CO,,A/2.CO,G
9he main goal 6as to start .08s separatel( and te%t mode programs under the &ontrol o' the &aller
F.08 or te%tG. Regina &an be part o' a .08 progress and must be treated as .08 in this &ase. ,ost
people get upset 6ith &onsole 6indo6s popping up sho6ing nothing.
Some &ombinations o' the interpreter, the target programs, and the options 6e &an pass along to the
s(stem lead to nonstarting, nonstopping, &rashing programs. Or 6e ma( loose &ontrol b( means o'
bro-en &ommuni&ations to the subpro&ess F"AA.SS JI,9...G.
So 6e had to &hoose either to let program run sa'el( O to let program run prett(. :lame the gu(s
6ho designed Dindo6s, not the Regina &re6Y
So, i' (ou ha5e a 2OS graphi&al e%tension -no6n as Dindo6s *5, Dindo6s *+ or Dindo6s
,illennium (ou 6ill get &onsole 6indo6s popping up i' run 'rom a .08 program. De are sorr( 'or
this, 6e &anPt &hange it.
9hose S(stems 6ith a =2 bit startup -ernel -no6n as Dindo6s /9, Dindo6s 2000, Dindo6s A"
6ill hide the &onsole 6indo6s 6hen starting a te%t mode program 'rom a .08 program.
*TT!9T+O9: Cour programs might &rash or (ou ma( loose &ontrol either o' the &alled program or
o' egina i' (ou &hange the interpreter inside (our Rexx program. /e5er use
68
$";; V";U /$O3SP$/) so%e'!ing) /S*S,3/
in (our program i' (ou donPt -no6 the &onseKuen&esY 0npredi&table beha5iour is li-el( to o&&ur7
use at (our o6n perilY
69
3 Rexx %uilt8in /unctions
This chapter describes the Rexx library o& built)in &unctions. It is divided into three parts*
+irst a general introduction to built)in &unctions, pointing out concepts, pit&alls, para#eter
conventions, peculiarities, and possible syste# dependencies.
Then there is the re&erence section, "hich describes in detail each &unction in the built)in
library.
't the end, there is docu#entation that describes "here and ho" Regina di&&ers &ro# standard
Rexx, as described in the t"o other sections. It also lists Regina,s e$tensions to the built)in
library.
It is reco##ended that you read the &irst part on &irst on &irst reading o& this docu#entation, and
that you use the second part as re&erence. The third part is only relevant i& you are going to use
Regina.
3.1 ,eneral Information
9his se&tion is an introdu&tion to the built$in 'un&tions. 8t des&ribes &ommon beha5ior, parameter
&on5entions, &on&epts and list possible s(stem$dependent parts.
3.1.1 The !&ntax /ormat
8n the des&ription o' the built$in 'un&tions, the s(nta% o' ea&h one is listed. 1or ea&h o' the s(nta%
diagrams, the parts 6ritten in italic 'ont names the parameters. 9erms en&losed in FsKuare bra&-etsG
denote optional elements. And the courier 'ont is used to denote that something should be
6ritten as is, and it is also used to mar- output 'rom the &omputer. At the right o' ea&h 'un&tion
s(nta% is an indi&ation o' 6here the 'un&tion is de'ined.
,*9S+/ A/S8 Standard 'or Rexx 1**?
,!)T'*9S+/ >%tended Rexx
,S**/ S(stem Appli&ation Ar&hite&ture $ 8:,
,OS42/ 8:, OS#2 Rexx
,30S/ Rexx on C,S
,*>!))/ A>AA on Amiga
,>!.+9*/ Additional 'un&tion pro5ided b( egina
2e'initions o' the A>AA built$in 'un&tions 6ere ta-en 5erbatim in 200= 'rom
"##$%&&dfd'ck."omei$.ne#&dfd&ados&arexx&main.s"#ml
/ote that in standard Rexx it is not reall( allo6ed to let the last possible parameter be empt( i' all
70
&ommas are in&luded, although some implementations allo6 it. 8n the 'ollo6ing &alls:
say A#$B M5 C
say A#$B M5) 1 C
say A#$B M5) C
9he t6o 'irst return the string &onsisting o' a single &hara&ter ", 6hile the last should return error. 8'
the last argument o' a 'un&tion &all is omitted, (ou &an not sa'el( in&lude the immediatel( pre&eding
&omma.
3.1.2 Precision and 'ormaliAation
9he built$in librar( uses its o6n internal pre&ision 'or 6hole numbers, 6hi&h ma( be the range 'rom
$********* to ^*********. 9hat is probabl( 'ar more than (ou 6ill e5er need in the built$in
'un&tions. 1or most 'un&tions, neither parameters nor return 5alues 6ill be e''e&ted b( an( setting
o' +U3.I$. 8n the 'e6 &ases 6here this does not hold, it is e%pli&itl( stated in the des&ription o'
the 'un&tion.
8n general, onl( parameters that are reKuired to be 6hole numbers are used in the internal pre&ision,
6hile numbers not reKuired to be 6hole numbers are normaliHed a&&ording to the setting o'
+U3.I$ be'ore use. :ut o' &ourse, i' a parameter is a numeri& e%pression, that e%pression 6ill be
&al&ulated and normaliHed under the settings o' +U3.I$ be'ore it is gi5en to the 'un&tion as a
parameter.
3.1.3 !tandard Parameter 'ames
8n the des&riptions o' the built$in 'un&tions, se5eral generi& names are used 'or parameters, to
indi&ate something about the t(pe and use o' that parameter, e.g. 5alid range. 9o a5oid repeating the
same in'ormation 'or the ma\orit( o' the 'un&tions, some &ommon ;rules; 'or the standard
parameter names are stated here. 9hese rules impli&itl( appl( 'or the rest o' this &hapter.
/ote that the 'ollo6ing list does not tr( to &lassi'( an( general Rexx ;datat(pes;, but pro5ides a
binding bet6een the sub$datat(pes o' strings and the methodolog( used 6hen naming parameters.
Length is a non$negati5e 6hole number 6ithin the internal pre&ision o' the built$in 'un&tions.
Dhether it denotes a length in &hara&ters or in 6ords, depends on the &onte%t.
String &an be an( normal &hara&ter string, in&luding the nullstring. 9here are no 'urther
reKuirements 'or this parameter. Sometimes a string is &alled a ;pa&-ed string; to e%pli&itl(
sho6 that it usuall( &ontains more than the normal printable &hara&ters.
Option is used in some o' the 'un&tions to &hoose a parti&ular a&tion, e.g. in A",BC to set the
'ormat in 6hi&h the date is returned. >5er(thing e%&ept the 'irst &hara&ter 6ill be ignored, and
&ase does not matter. note that the string should &onseKuentl( not ha5e an( leading spa&e.
Start is a positi5e 6hole number, and denotes a start position in e.g. a string. Dhether it re'ers to
&hara&ters or 6ords depends on the &onte%t. 9he 'irst position is al6a(s numbered 1, unless
e%pli&itl( stated other6ise in the do&umentation. /ote that 6hen return 5alues denotes
positions, the number < is generall( used to denote a none%istent position.
-adchar must be a string, e%a&tl( one &hara&ter long. 9hat &hara&ter is used 'or padding.
71
Strea#id is a string that identi'ies a Rexx stream. 9he a&tual &ontents and 'ormat o' su&h a
string is implementation dependent.
Nu#ber is an( 5alid Rexx number, and 6ill be normaliHed a&&ording to the settings o'
+U3.I$ be'ore it is used b( the 'un&tion.
8' (ou see one o' these names ha5ing a number appended, that is onl( to separate se5eral parameters
o' the same t(pe, e.g. string., string/ et&. 9he( still 'ollo6 the rules listed abo5e. 9here are se5eral
parameters in the built$in 'un&tions that do not easil( 'all into the &ategories abo5e. 9hese are gi5en
other names, and their t(pe and 'un&tionalit( 6ill be des&ribed together 6ith the 'un&tions in 6hi&h
the( o&&ur.
3.1.4 Error )essages
9here are se5eral errors that might o&&ur in the built$in 'un&tions. Oust one error message is onl(
rele5ant 'or all the built$in 'un&tions, that is number <0 FIncorrect call to routineG. 8n 'a&t, an
implementation o' Rexx &an &hoose to use that 'or an( problem it en&ounters in the built$in
'un&tions. egina also pro5ides 'urther in'ormation in errors in built$in 'un&tions, as de'ined b( the
A/S8 standard. 9his additional in'ormation is pro5ided as sub$error messages and usuall( pro5ide a
more detailed e%planation o' the error.
2epending on the implementation, other error messages might be used as 6ell. >rror message
number 2? FInvalid "hole nu#berG might be used 'or an( &ase 6here a parameter should ha5e been
a 6hole number, or 6here a 6hole number is out o' range. 8t is implied that this error message &an
be used in these situations, and it is not e%pli&itl( mentioned in the des&ription o' the 'un&tions.
Other general error messages that might be used in the built$in 'un&tions are error number <1 F0ad
arith#etic conversionG 'or an( parameter that should ha5e been a 5alid Rexx number. 9he error
message 15 FInvalid binary or he$adeci#al stringG might o&&ur in an( o' the &on5ersion routines
that &on5erts 'rom binar( or he%ade&imal 'ormat FI#-BC, -#IBC, -#$BC, -#ABCG. And o' &ourse
the more general error messages li-e error message 5 FMachine resources e$haustedG &an o&&ur.
.enerall(, it is ta-en as granted that these error messages might o&&ur 'or an( rele5ant built$in
'un&tion, and this 6ill not be restated 'or ea&h 'un&tion. Dhen other error messages than these are
rele5ant, it 6ill be mentioned in the te%t.
8n Rexx, it is in general not an error to spe&i'( a start position that is larger than the length o' the
string, or a length that re'ers to parts o' a string that is be(ond the end o' that string. 9he meaning o'
su&h instan&es 6ill depend on the &onte%t, and are des&ribed 'or ea&h 'un&tion.
3.1.2 Possible !&stem $ependencies
Some o' the 'un&tions in the built$in librar( are more or less s(stem or implementation dependent.
9he 'un&tionalit( o' these ma( 5ar(, so (ou should use de'ensi5e programming and be prepared 'or
an( side$e''e&ts that the( might ha5e. 9hese 'un&tions in&lude:
"AA.SSBC is dependent on (our operating s(stem and the implementation o' Rexx, sin&e
there is no standard 'or naming en5ironments.
".>BC at the main le5el Fnot in subroutines and 'un&tionsG is dependent on ho6 (our
72
implementation handles and parses the parameters it got 'rom the operating s(stem. 8t is also
dependent on 6hether the user spe&i'ies the 'a &ommand line s6it&h.
II,"+ABC, II,O.BC and II,-O.BC are dependent on the &hara&ter set o' (our ma&hine.
Seemingl( identi&al parameters 6ill in general return 5er( di''erent results on ASC88 and
>:C28C ma&hines. esults 6ill be identi&al i' the parameter 6as gi5en to these 'un&tions as a
binar( or he%ade&imal literal.
$#-BC, $#ABC, A#$BC and -#$BC 6ill be e''e&ted b( the &hara&ter set o' (our &omputer
sin&e the( &on5ert to or 'rom &hara&ters. /ote that i' $#-BC and $#ABC get their 'irst
parameter as a binar( or he%ade&imal literal, the result 6ill be una''e&ted b( the ma&hine t(pe.
Also note that the 'un&tions I#-BC, -#IBC, -#ABC and A#-BC are not e''e&ted b( the
&hara&ter set, sin&e the( do not use &hara&ter representation.
$9".I+BC, $9".OU,BC, $9".SBC, ;I+I+BC, ;I+OU,BC, ;I+SBC and S,."3BC
are the inter'a&e to the 'ile s(stem. 9he( might ha5e s(stem dependent pe&uliarities in se5eral
6a(s. 1irstl(, the naming o' streams is 5er( dependent on the operating s(stem. Se&ondl(, the
operation o' stream is 5er( dependent on both the operating s(stem and the implementation. Cou
&an sa'el( assume 5er( little about ho6 streams beha5e, so &are'ull( read the do&umentation 'or
(our parti&ular implementation.
$O+AI,IO+BC is dependent on the &ondition s(stem, 6hi&h in turn depends on su&h
implementation dependent things as 'ile 8#O and e%e&ution o' &ommands. Although the general
operation o' this 'un&tion 6ill be 'airl( eKual among s(stems, the details ma( di''er.
A",",*PBC and ,."+S;",BC -no6 ho6 to re&ogniHe upper and lo6er &ase letters, and
ho6 to trans'orm letters to upper &ase. 8' (our Rexx implementation supports national
&hara&ter sets, the operation o' these t6o 'un&tions 6ill depend on the language &hosen.
A",BC has the options 3on'!, JeeT1ay and +or%al, 6hi&h produ&e the name o' the da(
or month in te%t. 2epending on ho6 (our implementation handles national &hara&ter sets, the
result 'rom these 'un&tions might use the &orre&t spelling o' the &urrentl( &hosen language.
A;JO.ABC, SUIJO.ABC, JO.ABC, JO.AI+A-BC, JO.A;+>,9BC, JO.APOSBC and
JO.ASBC reKuires the &on&ept o' a ;6ord;, 6hi&h is de'ined as a non$blan- &hara&ters
separated b( blan-s. !o6e5er, the interpretation o' 6hat is a blan- &hara&ter depends upon the
implementation.
..O.,-,BC might ha5e slightl( di''erent 6ordings, depending on the implementation, but
the meaning and numbering should be the same. !o6e5er, note that some implementations ma(
ha5e additional error messages, and some might not 'ollo6 the standard numbering. >rror
messages ma( also be returned in the userPs nati5e language.
UUUABC re'ers to the s(stem spe&i'i& &on&ept o' a ;sta&-;, 6hi&h is either internal or
e%ternal to the implementation. 9he result o' this 'un&tion ma( there'ore be dependent on ho6
the sta&- is implemented on (our s(stem.
."+AO3BC 6ill di''er 'rom ma&hine to ma&hine, sin&e the algorithm is implementation
73
dependent. 8' (ou set the seed, (ou &an sa'el( assume that the same interpreter under the same
operating s(stem and on the same hard6are plat'orm 6ill return a reprodu&ible seKuen&e. :ut i'
(ou &hange to another interpreter, another ma&hine or e5en \ust another 5ersion o' the operating
s(stem, the same seed might not gi5e the same pseudo$random seKuen&e.
SOU.$;I+BC has been &hanged bet6een Rexx language le5el =.50 and <.00. 8n <.00 it &an
return < i' the Rexx implementation 'inds it ne&essar(, and an( reKuest 'or a parti&ular line ma(
get a nullstring as result. :e'ore assuming that this 'un&tion 6ill return an(thing use'ul, &onsult
the do&umentation.
,I3BC 6ill di''er some6hat on di''erent ma&hines, sin&e it is dependent on the underl(ing
operating s(stem to produ&e the timing in'ormation. 8n parti&ular, the granularit( and a&&ura&(
o' this in'ormation ma( 5ar(.
V";UBC 6ill be dependent on implementation and operating s(stem i' it is &alled 6ith its third
parameter spe&i'ied. Consult the implementation spe&i'i& do&umentation 'or more in'ormation
about ho6 ea&h implementation handles this situation.
-."+>BC 6ill return a string, 6hi&h &ontents 6ill be dependent on the &hara&ter set used b(
(our &omputer. Cou &an sa'el( ma-e 5er( 'e6 assumptions about the 5isual representation, the
length, or the &hara&ter order o' the string returned b( this 'un&tion.
9he built$in 'un&tions mar-ed as *>!)) are a5ailable b( de'ault on Amiga and AOS s(stems,
but the *>!))?7+@S O"98O/ is reKuired on other s(stem to ma-e these 'un&tions a5ailable.
As (ou &an see, e5en Rexx interpreters that are 6ithin the standard &an di''er Kuite a lot in the built$
in 'un&tions. Although the points listed abo5e seldom are an( problem, (ou should ne5er assume
an(thing about them be'ore (ou ha5e read the implementation spe&i'i& do&umentation. 1ailure to
do so 6ill gi5e (ou surprises sooner or later.
And, b( the 6a(, man( implementations Fprobabl( the ma\orit(G do not 'ollo6 the standard
&ompletel(. So, in 'a&t, (ou should ne5er assume an(thing at all. Sorr( ...
3.1.3 %lan+s *s. !paces
/ote that the des&ription di''ers bet6een ;blan-s; and the <spa&e> &hara&ter. A blan- is an(
&hara&ter that might be used as ;6hitespa&e; to separate te%t into groups o' &hara&ters. 9he <spa&e>
&hara&ter is onl( one o' se5eral possible blan-s. Dhen this te%t sa(s ;blan-; it means an( one 'rom
a set o' &hara&ters that are used to separate 5isual &hara&ters into 6ords. Dhen this te%t sa(s
<spa&e>, it means one parti&ular blan-, that 6hi&h is generall( bound to the spa&e bar on a normal
&omputer -e(board.
All implementation &an be trusted to treat the <spa&e> &hara&ter as blan-. Additional &hara&ters
that might be interpreted as blan-s are <tab> FhoriHontal tabulatorG, <''> F'orm'eedG, <5t> F5erti&al
tabulatorG, <nl> Fne6lineG and <&r> F&arriage returnG. 9he interpretation o' 6hat is blan- 6ill 5ar(
bet6een ma&hines, operating s(stems and interpreters. 8' (ou are using support 'or national
&hara&ter sets, it 6ill e5en depend on the language sele&ted. So be sure to &he&- the do&umentation
be'ore (ou assume an(thing about blan- &hara&ters.
Some implementations use onl( one blan- &hara&ter, and per&ei5es the set o' blan- &hara&ters as
74
eKui5alent to the <spa&e> &hara&ter. 9his 6ill depend on the implementation, the &hara&ter set, the
&ustoms o' the operating s(stem and 5arious other reasons.
3.2 Regina %uilt8in /unctions
:elo6 'ollo6s an in depth des&ription o' all the 'un&tions in the librar( o' built$in 'un&tions. /ote
that all 'un&tions in this se&tion are a5ailable on all ports o' egina. >a&h 'un&tion is designated as
being part o' the A/S8 standard, or 'rom other implementations. 1ollo6ing se&tions des&ribe those
built$in 'un&tions that are a5ailable on spe&i'i& ports o' egina, or 6hen egina is built 6ith &ertain
s6it&hes.
ARE!("#ng$ %&#'( )$"eng(&*) - (ANSI)
eturns 1 i' the string short is stri&tl( eKual to the leading &har&aters o' the string long, and returns
<FHeroG other6ise. 9he minimum length 6hi&h short must ha5e, &an be spe&i'ied as length. 8'
length is unspe&i'ied, length is set to the length o' short. 9he nullstring is an abbre5iation o' an(
string.
/ote that this 'un&tion is &ase sensiti5e, and that leading and trailing spa&es are not stripped o''
be'ore the t6o strings are &ompared.
"II.VB/@oobar/)/@oo/C 1
"II.VB/@oobar/)/@oo/)8C < /5,oo s!or' 5/
"II.VB/@oobar/)/(oo/C < /5Ai((eren' case 5/
"II.VB/@oobar/)//)<C 1 /5 // %a'c!es any s'ring 5/
"II.VB//)/any'!ing/)<C < /5 no'!ing %a'c!es // 5/
AS(n+,-e') - (ANSI)
eturns the absolute 5alue o' the nu#ber, 6hi&h &an be an( 5alid Rexx number. /ote that the result
6ill be normaliHed a&&ording to the &urrent setting o' +U3.I$.
"ISB-8#C 8#
"ISB1<<C 1<<
ADDRESS()#.(i#n*) - (ANSI)
eturns the &urrent de'ault en5ironment to 6hi&h &ommands are sent or optionall( spe&i'i& details
about the targets o' &ommand input#output and errors. 9he 5alue is set 6ith the "AA.SS &lause,
'or more in'ormation, see do&umentation on that &lause.
8' option is not spe&i'ied the de'ault option is U/V.
Option &an be:
+N,
F/ormalG eturns the &urrent de'ault en5ironment.
+I,
F8nputG eturns the target details 'or input as three 6ords: position type resource.
+O,
FOutputG eturns the target details 'or output as three 6ords: position type resource.
75
+E,
F>rrorG eturns the target details 'or errors as three 6ords: position type resource.
position 6ill be one o': +9&(T F'or option U8VG, *&&!9D or >!&L*3!
type 6ill be one o': ST!0, ST>!*0, @+@O, L+@O, 9O>0*L
resource 6ill be the name o' the stem, stream or Kueue or blan-
"AA.SSBC S*S,3 /5 3aybe 5/
"AA.SSB/+/C S*S,3 /5 3aybe 5/
Ae(aul'sH
"AA.SSB/I/C I+PU, +O.3";
"AA.SSB/O/C .P;"$ +O.3";
"AA.SSB//C .P;"$ +O.3";
"('erH "AA.SS S*S,3 JI,9 I+PU, @I@O /3*UUU/ OU,PU, S,3
%ys'e%. ..O. "PP+A S,."3 /%y.err/
"AA.SSB/I/C I+PU, @I@O 3*UUU
"AA.SSB/O/C .P;"$ S,3 3*S,3.
"AA.SSB//C "PP+A S,."3 %y.err
ARG()a'gn# )$#.(i#n**) - (ANSI)
eturns in'ormation about the arguments o' the &urrent pro&edure le5el. 1or subroutines and
'un&tions it 6ill re'er to the arguments 6ith 6hi&h the( 6ere &alled. 1or the ;main; program it 6ill
re'er to the arguments used 6hen the Rexx interpreter 6as &alled.
/ote that under some operating s(stems, Rexx s&ripts are run b( starting the Rexx interpreter as a
program, gi5ing it the name o' the s&ript to be e%e&uted as parameter. 9hen the Rexx interpreter
might pro&ess the &ommand line and ;eat; some or all o' the arguments and options. 9here'ore, the
result o' this 'un&tion at the main le5el is implementation dependent. 9he parts o' the &ommand
line 6hi&h are not a5ailable to the Rexx s&ript might 'or instan&e be the options and arguments
meaning'ul onl( to the interpreter itsel'.
Also note that ho6 the interpreter on the main le5el di5ides the parameter line into indi5idual
arguments, is implementation dependent. 9he standard seems to de'ine that the main pro&edure
le5el &an onl( get one parameter string, but donPt &ount on it. On all plat'orms, egina 6ill re&ei5e
one parameter string at the main pro&edural le5el, unless egina is started 6ith the $a s6it&h, 6hen
multiple parameter strings are passed in.
1or more in'ormation on ho6 the interpreter pro&esses arguments 6hen &alled 'rom the operating
s(stem, see the do&umentation on ho6 to run a Rexx s&ript.
Dhen &alled 6ithout an( parameters, ".>BC 6ill return the number o' &omma$delimited
arguments. 0nspe&i'ied FomittedG arguments at the end o' the &all are not &ounted. /ote the
di''eren&e bet6een using &omma and using spa&e to separate strings. Onl( &omma$separated
arguments 6ill be interpreted b( Rexx as di''erent arguments. Spa&e$separated strings are
interpreted as di''erent parts o' the same argument.
76
'rgno must be a positi5e 6hole number. 8' onl( argno is spe&i'ied, the argument spe&i'ied 6ill be
returned. 9he 'irst argument is numbered 1. 8' argno re'ers to an unspe&i'ied argument Feither
omitted or argno is greater than the number o' argumentsG, a nullstring is returned.
8' option is also spe&i'ied, the return 5alue 6ill be 1 or <, depending on the 5alue o' option and on
6hether the numbered parameter 6as spe&i'ied or not. Option &an be:
+O,
FOmittedG eturns 1 i' the numbered argument 6as omitted or unspe&i'ied. Other6ise, < is
returned.
+E,
F>%istingG eturns 1 i' the numbered argument 6as spe&i'ied, and < other6ise.
8' &alled as:
$";; @U+$,IO+ /,!is/ /is/) /a/)) /'es'/))
".>BC 8 /5;as' 6ara%e'er o%i''e1 5/
".>B1C /,!is is/
".>B#C /a/
".>B7C //
".>B9C // /5+in'! 6ara%e'er 1oesn/' e&is'5/
".>B#)//C 1
".>B#)/O/C <
".>B7)//C < /5,!ir1 6ara%e'er o%i''e1 5/
".>B9)/O/C 1
/C(-in%('ing) - (AREXX)
Con5erts a string o' binar( digitsF0,1Ginto the &orrespondingFpa&-edG&hara&ter representation. 9he
&on5ersion is the same as though the argument string had been spe&i'ied as a literal binar(
stringFe.g. P1010P:G. :lan-s are permitted in the string,but onl( at b(te boundaries. 9his 'un&tion is
parti&ularl( use'ul 'or &reating strings that are to be used as bit mas-s.

I#$B/<<11<<11/C /7/
I#$B/<11<<<<1/C /"/
/X(-in%('ing) - (ANSI)
9a-es a parameter 6hi&h is interpreted as a binar( string, and returns a he%ade&imal string 6hi&h
represent the same in'ormation. 0instring &an onl( &ontain the binar( digits < and 1. 9o in&rease
readabilit(, blan-s ma( be in&luded in binstring to group the digits into groups. >a&h su&h group
must ha5e a multiple o' 'our binar( digits, e%&ept 'rom the 'irst group. 8' the number o' binar( digits
in the 'irst group is not a multiple o' 'our, that group is padded at the le't 6ith up to three leading
Heros, to ma-e it a multiple o' 'our. :lan-s &an onl( o&&ur bet6een binar( digits, not as leading or
trailing &hara&ters.
77
>a&h group o' 'our binar( digits is translated into on he%ade&imal digit in the output string. 9here
6ill be no e%tra blan-s in the result, and the upper si% he%ade&imal digits are in upper &ase.
I#-B/<<1< <1<111<< <<11/C /#M$7/
I#-B/1< <1<1 11111111/C /#M@@/
I#-B/<1<<1<< <<11/C /#87/
EEP(0'e1+en23 )$4+'a(i#n*) - (OS5/)
Sounds the ma&hinePs bell. 9he &re1uency and duration Fin millise&ondsG o' the tone are spe&i'ied. 8'
no duration 5alue is spe&i'ied, it de'aults to 1. /ot all operating s(stems &an sound their bells 6ith
the gi5en spe&i'i&ations.
IPB5<)1<<<C
ITAND(%('ing6 )$)%('ing/* )$.a42&a'**) - (ANSI)
eturns the result 'rom b(te6ise appl(ing the operator A/2 to the &hara&ters in the t6o strings
string. and string/. /ote that this is not the logi&al A/2 operation, but the bit6ise A/2 operation.
String/ de'aults to a nullstring. 9he t6o strings are le't$\usti'ied7 the 'irst &hara&ters in both strings
6ill be A/2Ped, then the se&ond &hara&ters and so 'orth.
9he beha5ior o' this 'un&tion 6hen the t6o strings do not ha5e eKual length is de'ined b( the
padchar &hara&ter. 8' it is unde'ined, the remaining part o' the longer string is appended to the result
a'ter all &hara&ters in the shorter string ha5e been pro&essed. 8' padchar is de'ined, ea&h &har in the
remaining part o' the longer string is logi&all( A/2Ped 6ith the padchar For rather, the shorter
string is padded on the right length, using padcharG.
Dhen using this 'un&tion on &hara&ter strings, e.g. to upper&ase or lo6er&ase a string, the result 6ill
be dependent on the &hara&ter set used. 9o lo6er&ase a string in >:C28C, use II,"+ABC 6ith a
padchar 5alue o' /b(/&. 9o do the same in ASC88, use II,O.BC 6ith a padchar 5alue o' /#</&.
II,"+AB/1#785M/&)/785M/&C /1<185M/&
II,"+AB/(oobar/))/1(/&C /@OOI"./ /5@or "S$II5/
II,"+AB/1#785M/&)/785M/&)/(</&C /1<185</&
ITCHG(%('ing$ -i() - (AREXX)
Changes the state o' the spe&i'ied bit in the argument string. :it numbers are de'ined su&h that bit 0
is the lo6$order bit o' the rightmost b(te o' the string.
II,$9>B/<717/&)8C /<7<7/&
ITCLR(%('ing$ -i() - (AREXX)
Clears Fsets to HeroG the spe&i'ied bit in the argument string. :it numbers are de'ined su&h that bit 0
is the lo6$order bit o' the rightmost b(te o' the string.
II,$;.B/<717/&)8C /<7<7/&
78
ITCOMP(%('ing6$ %('ing/$ -i( )$.a4*) - (AREXX)
Compares the argument strings bit$b($bit,starting at bit number 0. 9he returned 5alue is the bit
number o' the 'irst bit in 6hi&h the strings di''er,or $1 i' the strings are identi&al.
II,$O3PB/N@/&)/@@/&C /N/
II,$O3PB/@@/&)/@@/&C /-1/
ITOR(%('ing6 )$ )%('ing/* )$.a42&a'**) - (ANSI)
eturns the result 'rom b(te6ise appl(ing the operator O to the &hara&ters in the t6o strings
string. and string/. /ote that this is not the logi&al O operation, but the bit6ise O operation.
String/ de'aults to a nullstring. 9he t6o strings are le't$\usti'ied7 the 'irst &hara&ters in both strings
6ill be OPed, then the se&ond &hara&ters and so 'orth.
9he beha5ior o' this 'un&tion 6hen the t6o strings do not ha5e eKual length is de'ined b( the
padchar &hara&ter. 8' it is unde'ined, the remaining part o' the longer string is appended to the result
a'ter all &hara&ters in the shorter string ha5e been pro&essed. 8' padchar is de'ined, ea&h &har in the
remaining part o' the longer string is logi&all( OPed 6ith the padchar For rather, the shorter string
is padded on the right length, using padcharG.
Dhen using this 'un&tion on &hara&ter strings, e.g. to upper&ase or lo6er&ase a string, the result 6ill
be dependent on the &hara&ter set used.
II,O.B/1#&C /1#/&
II,O.B/15/&)/#8/&C /75/&
II,O.B/15/&)/#85M/&C /755M/&
II,O.B/15/&)/#85M/&)/@</&C /75@M/&
II,O.B/1111/&))/8A/&C /5A5A/&
II,O.B/6UrS/))/#</&C /6Vrs/ /5 "S$II 5/
ITSET(%('ing$ -i() - (AREXX)
Sets the spe&i'ied bit in the argument string to 1. :it numbers are de'ined su&h that bit 0 is the lo6$
order bit o' the rightmost b(te o' the string.
II,S,B/<717/&)#C /<71N/&
ITTST(%('ing$ -i() - (AREXX)
9he boolean return indi&ates the state o' the spe&i'ied bit in the argument string.
:it numbers are de'ined su&h that bit 0 is the lo6$order bit o' the rightmost b(te to the string.
II,,S,B/<717/&)8C /1/
ITXOR(%('ing6)$ )%('ing/* )$.a42&a'**) - (ANSI)
Dor-s li-e II,"+ABC, e%&ept that the logi&al 'un&tion AO Fe%&lusi5e OG is used instead o'
A/2. 1or more in'ormation see II,"+ABC.
79
II,-O.B/1#785M/&)/785M/&C /#MM#5M/&
II,-O.B/@ooIar/))/#</&C /(OOb"./ /5@or "S$II 5/
II,-O.B/1#785M/&)/785M/&)/(</&C /#MM#"M/&
UFTYPE() - (CMS)
9his 'un&tion is used 'or displa(ing the &ontents o' the sta&-. 8t 6ill displa( both the string and
noti'( 6here the bu''ers are displa(ed. 8t is meant 'or debugging, espe&iall( intera&ti5e, 6hen (ou
need to obtain in'ormation about the &ontents o' the sta&-. 8t al6a(s returns the nullstring, and ta-es
no parameters.
!ere is an e%ample o' the output 'rom &alling IU@,*P Fnote that the se&ond and 'ourth bu''ers are
empt(G:
::Q ;inesH 8
::Q Iu((erH 7
4(our'! line 6us!e1) in '!ir1 bu((er4
::Q Iu((erH #
::Q Iu((erH 1
4'!ir1 line 6us!e1) in (irs' bu((er4
::Q Iu((erH <
4secon1 line 6us!e1) in /?ero'!/ bu((er4
4(irs' line 6us!e1) in /?ero'!/ bu((er4
::Q n1 o( S'acT
C/(%('ing) - (AREXX)
Con5erts the supplied string into the eKui5alent string o' binar( digits.
$#IB/abc/C /<11<<<<1<11<<<1<<11<<<11/
C/D(%('ing )$"eng(&*) - (ANSI)
eturns a 6hole number, 6hi&h is the de&imal representation o' the pa&-ed string string, interpreted
as a binar( number. 8' length F6hi&h must be a non$negati5e 6hole numberG is spe&i'ied, it denotes
the number o' &hara&ters in string to be &on5erted, and string is interpreted as a t6oPs &omplement
representation o' a binar( number, &onsisting o' the length rightmost &hara&ters in string. 8' length
is not spe&i'ied, string is interpreted as an unsigned number.
8' length is larger than the length o' string, string is sign$e%tended on the le't. i.e. i' the most
signi'i&ant bit o' the le'tmost &har o' string is set, string is padded 6ith /((/& &hars at the le't
side. 8' the bit is not set, /<</& &hars are used 'or padding.
8' length is too short, onl( the length rightmost &hara&ters in string are &onsidered. /ote that this
6ill not onl( in general &hange the 5alue o' the number, but it might e5en &hange the sign.
/ote that this 'un&tion is 5er( dependent on the &hara&ter set that (our &omputer is using.
8' it is not possible to e%press the 'inal result as a 6hole number under the &urrent settings o'
+U3.I$ AI>I,S, an error is reported. 9he number to be returned 6ill not be stored in the
internal representation o' the built$in librar(, so siHe restri&tions on 6hole numbers that generall(
80
applies 'or built$in 'un&tions, do not appl( in this &ase.
$#AB/(oo/C /MN17199/ /5@or "S$II %ac!ines 5/
$#AB/1<7/&C /#59/
$#AB/1<7/&)1C /7/
$#AB/1<7/&)#C /#59/
$#AB/<1<7/&)7C /#59/
$#AB/((((/&)#C /-1/
$#AB/((((/&C /M5575/
$#AB/((((/&)7C /M5575/
$#AB/(((9/&)#C /-M/
$#AB/((8</&)#C /-1#8/
C/X(%('ing) - (ANSI)
eturns a string o' he%ade&imal digits that represents the &hara&ter string string. Con5erting is done
b(te6ise, the si% highest he%ade&imal digits are in upper&ase, and there are no blan- &hara&ters in
the result 3eading Heros are not stripped o'' in the result. /ote that the beha5ior o' this 'un&tion is
dependent on the &hara&ter set that (our &omputer is running Fe.g. ASC88 or >:C28CG.
$#-B/((((/&C /@@@@/
$#-B/"bc/C /81M#M7/ /5@or "S$II 3ac!ines 5/
$#-B/1#78/&C /1#78/
$#-B/<11 <<11 11<1/bC /<77A/
CD(4i'e2(#'3) - (REGINA)
CHDIR(4i'e2(#'3) - (REGINA)
Changes the &urrent pro&essPs dire&tor( to the directory spe&i'ied. A more portable, though non$
standard alternati5e is to use the 28>C9OC :81.
$9AI.B//'%6/aa/C /5 ne0 1irec'ory no0 /'%6/aa 5/
CENTER(%('ing$ "eng(& )$ .a42&a' * ) - (ANSI)
CENTRE(%('ing$ "eng(& )$ .a42&a' * ) - (ANSI)
9his 'un&tion has t6o names, to support both Ameri&an and :ritish spelling. 8t 6ill &enter string in
a string total o' length length &hara&ters. 8' length F6hi&h must be a non$negati5e 6hole numberG is
greater than the length o' string, string is padded 6ith padchar or <spa&e> i' padchar is
unspe&i'ied. 8' length is smaller than the length o' string &hara&ter 6ill be remo5ed.
8' possible, both ends o' string re&ei5es For losesG the same number o' &hara&ters. 8' an odd number
o' &hara&ters are to be added For remo5edG, one &hara&ter more is added to For remo5ed 'romG the
right end than the le't end o' string.
81
$+,.B/@oobar/)1<C / @oobar /
$+,.B/@oobar/)11C / @oobar /
$+,.B/@oobar/)7C /oob/
$+,.B/@oobar/)8C /ooba/
$+,.B/@oobar/)1<)/5/C /55@oobar55/
CHANGESTR(nee4"e$ &a3%(a27$ ne8nee4"e ) - (ANSI)
9he purpose o' this 'un&tion is to repla&e all o&&urren&es o' needle in the string haystac 6ith
ne"needle. 9he 'un&tion returns the &hanged string.
8' haystac does not &ontain needle, then the original haystac is returned.
$9"+>S,.B/a/)/(re1/)/c/C /(re1/
$9"+>S,.B//)//)/&/C //
$9"+>S,.B/a/)/abc1e(/)/&/C /&bc1e(/
$9"+>S,.B/</)/</)/1/C /1/
$9"+>S,.B/a/)/1e(/)/&y?/C /1e(/
$9"+>S,.B/a/)//)/&/C //
$9"+>S,.B//)/1e(/)/&y?/C /1e(/
$9"+>S,.B/abc/)/abc1e(/)/&y?/C /&y?1e(/
$9"+>S,.B/abc1e(g/)/abc1e(/)/&y?/C /abc1e(/
$9"+>S,.B/abc/)/abc1e(abcc1abc1/)/?/C /?1e(?c1?1/
CHARIN()%('ea,i4* )$)%(a'(* )$"eng(&**) - (ANSI)
9his 'un&tion 6ill in general read &hara&ters 'rom a stream, and return a string &ontaining the
&hara&ters read. 9he strea#id parameter names a parti&ular stream to read 'rom. 8' it is unspe&i'ied,
the de'ault input stream is used.
9he start parameter spe&i'ies a &hara&ter in the stream, on 6hi&h to start reading. :e'ore an(thing is
read, the &urrent read position is set to that &hara&ter, and it 6ill be the 'irst &hara&ter read. 8' start is
unspe&i'ied, no repositioning 6ill be done. 8ndependent o' an( &on5entions o' the operating
s(stem, the 'irst &hara&ter in a stream is al6a(s numbered 1. /ote that transient streams do not
allo6 repositioning, and an error is reported i' the start parameter is spe&i'ied 'or a transient stream.
9he length parameter spe&i'ies the number o' &hara&ters to read. 8' the reading did 6or-, the return
string 6ill be o' length length. 9here are no other 6a(s to -no6 man( &hara&ters 6ere read other
than &he&-ing the length o' the return 5alue. A'ter the read, the &urrent read position is mo5ed
'or6ard as man( &hara&ters as 6as read. 8' length is unspe&i'ied, it de'aults to 1. 8' length is <,
nothing is read, but the 'ile might still be repositioned i' start 6as spe&i'ied.
/ote that this 'un&tion reads the stream ra6. Some operating s(stems use spe&ial &hara&ters to
di''erentiate bet6een separate lines in te%t 'iles. On these s(stems these spe&ial &hara&ters 6ill be
returned as 6ell. 9here'ore, ne5er assume that this 'un&tion 6ill beha5e identi&all( 'or te%t streams
on di''erent s(stems.
82
Dhat happens 6hen an error o&&urs or the >nd$O'$1ile F>O1G is seen during reading, is
implementation dependent. 9he implementation ma( &hoose to set the +O,."A* &ondition Fdoes
not e%ist in Rexx language le5el =.50G. 1or more in'ormation, see &hapter on Stream +np#t and
O#tp#t.
FAssuming that the 'ile ;/'%6/(ile; &ontains the 'irst line: ;,!is is '!e (irs' line;G:
$9".I+BC
/@/ /53aybeX#
$9".I+B))MC
/@oobar/ /53aybeX#
$9".I+B//'%6/(ile/))MC /,!is i/
$9".I+B//'%6/(ile/)8)MC /s is '/
CHAROUT()%('ea,i4* )$)%('ing* )$%(a'(**) - (ANSI)
8n general this 'un&tion 6ill 6rite string to a strea#id. 8' strea#id is not spe&i'ied the de'ault output
stream 6ill be used.
8' start is spe&i'ied, the &urrent 6rite position 6ill be set to the startth &hara&ter in strea#id, be'ore
an( 6riting is done. /ote that the &urrent 6rite position &a not be set 'or transient streams, and
attempts to do so 6ill report an error. 8ndependent o' an( &on5entions that the operating s(stem
might ha5e, the 'irst &hara&ter in the stream is numbered 1. 8' start is not spe&i'ied, the &urrent 6rite
position 6ill not be &hanged be'ore 6riting.
8' string is omitted, nothing is 6ritten, and the e''e&t is to set the &urrent 6rite position i' start is
spe&i'ied. 8' neither string nor start is spe&i'ied, the implementation &an reall( do 6hate5er it li-es,
and man( implementations use this operation to &lose the 'ile, or 'lush an( &hanges. Che&-
implementation spe&i'i& do&umentation 'or more in'ormation.
9he return 5alue is the number o' &hara&ters in string that 6as not su&&ess'ull( 6ritten, so < denotes
a su&&ess'ul 6rite. /ote that in man( Rexx implementations there is no need to open a stream7 it
6ill be impli&itl( opened 6hen it is 'irst used in a read or 6rite operation.
FAssuming the 'ile re'erred to b( ou'1a'a 6as empt(, it 6ill &ontain the string @oobJo0
a'ter6ards. /ote that there might 6ill not be an >nd$O'$3ine mar-er a'ter this string, it depends on
the implementation.G
$9".OU,B)/@oobar/C /</
$9".OU,Bou'1a'a)/@oobar/C /</
$9".OU,Bou'1a'a)/Jo0/)5C /</
CHARS()%('ea,i4*) - (ANSI)
eturns the number o' &hara&ters le't in the named strea#id, or the de'ault input stream i' strea#id
is unspe&i'ied. 1or transient streams this 6ill al6a(s be either 1 i' more &hara&ters are a5ailable, or
< i' the >nd$O'$1ile &ondition has been met. 1or persistent streams the number o' remaining b(tes
in the 'ile 6ill be possible to &al&ulate and the true number o' remaining b(tes 6ill be returned.
!o6e5er, on some s(stems, it is di''i&ult to &al&ulate the number o' &hara&ters le't in a persistent
83
stream7 the reKuirements to $9".SBC has there'ore been rela%ed, so it &an return 1 instead o' an(
number other than <. 8' it returns 1, (ou &an there'ore not assume an(thing more than that there is at
least one more &hara&ter le't in the input stream.
$9".SBC /1/ /5 %ore 1a'a on 1e(. in6u' s'rea% 5/
$9".SBC /</ /5 O@ (or 1e(. in6u' s'rea% 5/
$9".SB/ou'1a'a/C /98/ /5 %aybe 5/
CLOSE(0i"e) - (AREXX)
Closes the &ile spe&i'ied b( the gi5en logi&al name. 9he returned 5alue is a boolean su&&ess 'lag, and
6ill be 1 unless the spe&i'ied 'ile 6as not open. 0se O&T+O9S *>!))?S!0*9T+3S 'or the
A>AA beha5iour to be e%e&uted.
$;OSB/in6u'/C /1/
COMPARE(%('ing6$ %('ing/ )$.a42&a'*) - (ANSI)
9his 'un&tion 6ill &ompare string. to string/, and return a 6hole number 6hi&h 6ill be 0 i' the( are
eKual, other6ise the position o' the 'irst &hara&ter at 6hi&h the t6o strings di''er is returned. 9he
&omparison is &ase$sensiti5e, and leading and trailing spa&e do matter.
8' the strings are o' uneKual length, the shorter string 6ill be padded at the right hand end 6ith the
padchar &hara&ter to the length o' the longer string be'ore the &omparison. 8' a padchar is not
spe&i'ied, <spa&e> is used.
$O3P".B/@ooIar/)/@oobar/C /8/
$O3P".B/@oobar/)/@oobar/C /</
$O3P".B/@oobarrr/)/@ooba/C /M/
$O3P".B/@oobarrr/)/@ooba/)/r/ C /</
COMPRESS(%('ing )$"i%(*) - (AREXX)
8' the list argument is omitted,the 'un&tion remo5es leading,trailing,or embedded blan- &hara&ters
'rom the string argument. 8' the optional list is supplied, it spe&i'ies the &hara&ters to be remo5ed
'rom the string.
$O3P.SSB/ 0!y no' /C /0!yno'/
$O3P.SSB/==1#-78-=/)/=-/C /1#78/
CONDITION()#.(i#n*) - (ANSI)
eturns in'ormation about the &urrent trapped &ondition. A &ondition be&omes the &urrent trapped
&ondition 6hen a &ondition handler is &alled Fb( $";; or SI>+";G to handle the &ondition. 9he
parameter option spe&i'ies 6hat sort o' in'ormation to return:
+C,
FConditionG 9he name o' the &urrent trapped &ondition is return, this 6ill be one o' the
&ondition named legal to SI>+"; O+, li-e S*+,"-, 9";,, +OV";U, +O,."A*,
..O. or @"I;U..
84
+D,
F2es&riptionG A te%t des&ribing the reason 'or the &ondition. Dhat to put into this 5ariable is
implementation and s(stem dependent.
+E,
F>%traG 9he error &ode Fa single numberG and a sub$error &ode i' a5ailable Ft6o numbers and
a period7 eg <0.5G that 6as generated b( the &ondition.
+I,
F8nstru&tionG eturns either $";; or SI>+";, depending on 6hi&h method 6as &urrent
6hen the &ondition 6as trapped.
+S,
FStateG 9he &urrent state o' the &urrent trapped &ondition. 9his &an be one o' O+, O@@ or
A;"*. /ote that this option re'le&t the &urrent state, 6hi&h ma( &hange, not the state at the
time 6hen the &ondition 6as trapped.
1or more in'ormation on &onditions, &onsult the &hapter Conditions. /ote that &ondition ma( in
se5eral 6a(s be dependent on the implementation and s(stem, so read s(stem and implementation
dependent in'ormation too.
COPIES(%('ing$ 2#.ie%) - (ANSI)
eturns a string 6ith copies &on&atenated &opies o' string. !opies must be a non$negati5e 6hole
number. /o e%tra spa&e is added bet6een the &opies.
$OPISB/@oo/)7C /@oo@oo@oo/
$OPISB/5/)1MC /5555555555555555/
$OPISB/Iar /)#C /Iar Iar /
$OPISB//)1<<<<C //
COUNTSTR(nee4"e$ &a3%(a27) - (ANSI)
eturns a &ount o' the number o' o&&urren&es o' needle in haystac that do not o5erlap.
$OU+,S,.B//)//C <
$OU+,S,.B/a/)/abc1e(/C 1
$OU+,S,.B<)<C 1
$OU+,S,.B/a/)/1e(/C <
$OU+,S,.B/a/)//C <
$OU+,S,.B//)/1e(/C <
$OU+,S,.B/abc/)/abc1e(/C 1
$OU+,S,.B/abc1e(g/)/abc1e(/ <
$OU+,S,.B/abc/)/abc1e(abcc1abc1/C 7
CRYPT(%('ing$ %a"() - (REGINA)
>n&r(pts the gi5en string using the supplied salt and returns the en&r(pted string. Onl( the 'irst t6o
&hara&ters o' salt are used. /ot all operating s(stems support en&r(ption, and on these plat'orms, the
string is returned un&hanged. 8t is also important to note that the en&r(pted string is not portable
bet6een plat'orms.
85
$.*P,B/a s'ring/) /1&/C /1&*0PPJI1?.Ws/ /5 %aybe 5/
DATATYPE(%('ing )$#.(i#n*) - (ANSI)
Dith onl( one parameter, this 'un&tion identi'ies the ;datat(pe; o' string. 9he 5alue returned 6ill be
;+U3; i' string is a 5alid Rexx number. Other6ise, ;$9".; is returned. /ote that the interpretation
o' 6hether string is a 5alid number 6ill depend on the &urrent setting o' +U3.I$.
8' option is spe&i'ied too, it 6ill &he&- i' string is o' a parti&ular datat(pe, and return either ;1; or
;<; depending on 6hether string is or is not, respe&ti5el(, o' the spe&i'ied datat(pe. 9he possible
5alues o' option are:
+A,
FAlphanumeri&G Consisting o' onl( alphabeti& &hara&ters Fin upper, lo6er or mi%ed &aseG and
de&imal digits.
+,
F:inar(G Consisting o' onl( the t6o binar( digits < and 1. /ote that blan-s are not allo6ed
6ithin string, as 6ould ha5e allo6ed been 6ithin a binar( string.
+L,
F3o6erG Consisting o' onl( alphabeti& &hara&ters in lo6er &ase.
+M,
F,i%edG Consisting o' onl( alphabeti& &hara&ters, but the &ase does not matter Fi.e. upper,
lo6er or mi%ed.G
+N,
F/umeri&G 8' string is a 5alid Rexx number, i.e. A",",*PBstring2 6ould return +U3.
+S,
FS(mboli&G Consists o' &hara&ters that are legal in Rexx s(mbols. /ote that this test 6ill
pass se5eral strings that are not legal s(mbols. 9he &hara&ters in&ludes plus, minus and the
de&imal point.
+U,
F0pperG Consists o' onl( upper &ase alphabeti& &hara&ters.
+W,
FDholeG 8' string is a 5alid Rexx 6hole number under the &urrent setting o' +U3.I$.
/ote that 17.< is a 6hole number sin&e the de&imal part is Hero, 6hile 17=1 is not a
6hole number, sin&e it must be interpreted as 1=0 plus#minus 5.
+X,
F!e%ade&imalG Consists o' he%ade&imal digits, i.e. the de&imal digits 0$* and the alphabeti&
&hara&ters A$1 in either &ase For mi%edG. :lan-s are allo6ed 6ithin string, as long as the(
appear bet6een pairs o' he%ade&imal digits. 9he nullstring is also &onsidered a 5alid
he%ade&imal 5alue.
8' (ou 6ant to &he&- 6hether a string is suitable as a 5ariable name, (ou should &onsider using the
S*3IO;BC 'un&tion instead, sin&e the Sy%bolic option onl( 5eri'ies 6hi&h &hara&ters string
&ontains, not the order. Cou should also ta-e &are to 6at&h out 'or lo6er &ase alphabeti& &hara&ters,
6hi&h are allo6ed in the tail o' a &ompound s(mbol, but not in a simple or stem s(mbol or in the
head o' &ompound s(mbol.
86
Also note that the beha5ior o' the options ", ;, 3 and U might depend on the setting o' language, i'
(ou are using an interpreter that supports national &hara&ter sets.
A",",*PB/ - 1.75-5 /C /+U3/
A",",*PB/1999999999/C /$9"./
A",",*PB/19999999999/C /$9"./
A",",*PB/!P#X#YBX5Z[/C /$9"./
A",",*PB/@ooIar/)/"/C /1/
A",",*PB/@oo Iar/)/"/C /</
A",",*PB/<1<<1<1111<1/)/I/C /1/
A",",*PB/<1<< 1<11 11<1/)/I/C /</
A",",*PB/(oobar/)/;/C /1/
A",",*PB/@ooIar/)/3/C /1/
A",",*PB/ -787 /)/+/C /1/
A",",*PB/"_S*3IO;!\!/)/S/C /1/
A",",*PB/1.#7.79=8.5/)/S/C /1/
A",",*PB/@oo bar/)/S/C /</
A",",*PB/@OOI"./)/U/C /1/
A",",*PB/1#71ea1bee(/)/-/C /1/
DATE()#.(_#+( )$4a(e )$#.(_in)$%e._#+()$%e._in*****) - (ANSI9)
9his 'un&tion returns in'ormation relating to the &urrent lo&al date. 8' the opt3out &hara&ter is
spe&i'ied, it 6ill set the 'ormat o' the return string. 9he de'ault 5alue 'or opt3out is ;+;.
"ossible options are:
+,
F:aseG 9he number o' &omplete da(s 'rom Oanuar( 1
st
0001 until (esterda( in&lusi5e, as a
6hole number. 9his 'un&tion uses the .regorian &alendar e%tended ba&-6ards. 9here'ore
2ateFP:PG ## @ 6ill eKual the da( o' the 6ee- 6here 0 &orresponds to ,onda( and ? Sunda(.
FA/S8G
+C,
FCentur(G 9he number o' da(s in this &entur( 'rom Oanuar( 1
st
-00 until toda(, in&lusi5e.
9he return 5alue 6ill be a positi5e integer. Fegina >%tensionG
+D,
F2a(sG 9he number o' da(s in this (ear 'rom Oanuar( 1
st
until toda(, in&lusi5e. 9he return
5alue 6ill be a positi5e integer. FA/S8G
+E,
F>uropeanG 9he date in >uropean 'ormat, i.e. ;11/%%/yy;. 8' an( o' the numbers is single
digit, it 6ill ha5e a leading Hero. FA/S8G
+I,
F8SOG eturns the date a&&ording the 'ormat spe&i'ied b( 8nternational Standards
OrganiHation Standard 8SO +?01:200<. 9he 'ormat 6ill be ;yyyy-%%-11;, and ea&h part is
87
padded 6ith leading Hero 6here appropriate. Fegina >%tensionG
+M,
F,onthG 9he unabbre5iated name o' the &urrent month, in >nglish. FA/S8G
+N,
F/ormalG eturn the date 6ith the name o' the month abbre5iated to three letters, 6ith onl(
the 'irst letter in upper &ase. 9he 'ormat 6ill be ;11 3%% yyyy;, 6here 3%% is the month
abbre5iation Fin >nglishG and 11 is the da( o' the month, 6ithout leading Heros. FA/S8G
+O,
FOrderedG eturns the date in the ordered 'ormat, 6hi&h is ;yy/%%/11;. FA/S8G
+S,
FStandard#SortedG eturns the date a&&ording the 'ormat spe&i'ied b( 8nternational Standards
OrganiHation Standard 8SO 201<$1*@? F>G. 9he 'ormat 6ill be ;yyyy%%11;, and ea&h part
is padded 6ith leading Hero 6here appropriate. FA/S8G
+U,
F0SAG eturns the date in the 'ormat that is normall( used in 0SA, i.e. ;%%/11/yy;, and
ea&h part is padded 6ith leading Hero 6here appropriate. FA/S8G
+W,
FDee-da(G eturns the >nglish unabbre5iated name o' the &urrent 6ee-da( 'or toda(. 9he
'irst letter o' the result is in upper &ase, the rest is in lo6er &ase. FA/S8G
+T,
Fti#e3tG eturns the &urrent 09C date#time in 0/8A ti#e3t 'ormat. ti#e3t is the number o'
se&onds sin&e Oanuar( 1
st
1*@0. 8t al6a(s represents the 09C date#time, so an( &on5ersion
'rom another date 'ormat F6hi&h is al6a(s assumed to be lo&al timeG 6ill result in a ti#e3t
5alue o''set b( time Hone. Fegina >%tensionG
/ote that the ;$; option is present in Rexx language le5el =.50, but 6as remo5ed in le5el <.00. 9he
ne6 ;I; option should be used instead. Dhen porting &ode that use the ;$; option to an interpreter
that onl( ha5e the ;I; option, (ou 6ill &an use the &on5ersion that Oanuar( 1
st
1*00 is da( ?*=5*5 in
the .regorian &alendar.
/ote that none o' the 'ormats in 6hi&h A",BC returns its result are a''e&ted b( the settings o'
+U3.I$. Also note that i' there is more than one &all to A",BC For ,I3BCG in a single &lause
o' Rexx &ode, all o' them 6ill use the same basis data 'or &al&ulating the date For timeG.
8' the Rexx interpreter &ontains national support, some o' these options ma( return di''erent output
'or the names o' months and 6ee-da(s.
88
Assuming that toda( is Oanuar( ?
th
1**2:
A",B/I/C /N#N#<7/
A",B/$/C /77M<9/
A",B/A/C /M/
A",B//C /<M/<1/9#/
A",B/3/C /Wanuary/
A",B/+/C /M Wan 199#/
A",B/O/C /9#/<1/<M/
A",B/S/C /199#<1<M/
A",B/U/C /<1/<M/9#/
A",B/J/C /3on1ay/
A",B/,/C M98M#<<<<
A",B/I/C /199#-<1-<M/
8' the date option is spe&i'ied, the 'un&tion pro5ides 'or date &on5ersions. 9he optional opt3in
spe&i'ies the 'ormat in 6hi&h date is supplied. 9he possible 5alues 'or opt3in are: 7D!O(9ST+:
9he de'ault 5alue 'or opt3in is 9.
Dhen a date is &on5erted to 'ormat T, the returned 5alue is the input date 6ith a time o' 00:00:00.
A",B/O/)/17 @eb 19#7/C /#7/<#/17/
A",B/O/)/<M/<1/5</)/U/C /5</<M/<1/
8' the date supplied does not in&lude a &entur( in its 'ormat, then the result is &hosen to ma-e the
(ear 6ithin 50 (ears past or <* (ears 'uture o' the &urrent (ear.
9he date &on5ersion &apabilit( o' the 2A9> :81 6as introdu&ed 6ith the A/S8 standard.
8' the sep3out option is pro5ided, the &hara&ter used to separate the &omponents o' the returned date
&an be &hanged. An( non$alphanumeri& &hara&ter &an be used as the separator. 9his option &an onl(
be used 6hen opt3out is one o' !9OS(+. 9he de'ault separator 'or ea&h option is:
! U#V
9 U V Fspa&eG
O U#V
S UV Fempt( stringG
( U#V
+ U$V
Assuming that toda( is Oanuar( ?
th
1**2:
A",B/+/)))/_/C /M_Wan_199#/
A",B/O/)/<M/<1/5</)/U/)//C /5<<M<1/
A",B/S/)/17 @eb 199M/)+/)/-/C 199M-<#-17
8' the separator o' the date &omponents o' date are di''erent to the de'aults spe&i'ied abo5e, then the
sep3in option needs to be pro5ided to spe&i'( 6hat separator is being used.
89
A",B/O/)/<M.<1.5</)/U/)//)/./C /5<<M<1/
A",B/S/)/17-<#-9M/)/)/-/)/-/C 199M-<#-17
9he sep3out and sep3in options are e%tensions to the A/S8 standard originall( pro5ided b( Ob\e&t
e%%.
DELSTR(%('ing$ %(a'( )$"eng(&*) - (ANSI)
eturns string, a'ter the substring o' length length starting at position start has been remo5ed. 9he
de'ault 5alue 'or length is the rest o' the string. Start must be a positi5e 6hole number, 6hile length
must be a non$negati5e 6hole number. 8t is not an error i' start or length For a &ombination o'
themG re'ers to more &hara&ters than string holds
A;S,.B/@oobar/)8C /@oo/
A;S,.B/@oobar/)8)#C /@oor/
A;S,.B/@oobar/)8)8C /@oo/
A;S,.B/@oobar/)NC /@oobar/
DELWORD(%('ing$%(a'()$"eng(&*) (ANSI)
emo5es length 6ords and all blan-s bet6een them, 'rom string, starting at 6ord number start. 9he
de'ault 5alue 'or length is the rest o' the string. All &onse&uti5e spa&es immediatel( a'ter the last
deleted 6ord, but no spa&es be'ore the 'irst deleted 6ord is remo5ed. /othing is remo5ed i' length
is Hero.
9he 5alid range o' start is the positi5e 6hole numbers7 the 'irst 6ord in string is numbered 1. 9he
5alid range o' length is the non$negati5e integers. 8t is not an error i' start or length For a
&ombination o' themG re'ers to more 6ords than string holds.
A;JO.AB/,!is is a 'es'/)7C /,!is is /
A;JO.AB/,!is is a 'es'/)#)1C /,!is a 'es'/
A;JO.AB/,!is is a 'es'/)#)5C /,!is/
A;JO.AB/,!is is a 'es'/)1)7C /'es'/ /5+o lea1ing s6ace5/
DESUF() - (CMS)
9his 'un&tion remo5es all bu''ers on the sta&-, it is reall( \ust a 6a( o' &learing the 6hole sta&- 'or
bu''ers as 6ell as strings. 1un&tionall(, it is eKui5alent to e%e&uting A.OPIU@ 6ith a parameter o'
<. FA&tuall(, this is a lie, sin&e A.OPIU@ is not able to ta-e Hero as a parameter. ather, it is
eKui5alent to e%e&uting A.OPIU@ 6ith 1 as parameter and then e%e&uting A.OPIU@ 6ithout a
parameter, but this is a subtle point.G 8t 6ill return the number o' bu''ers le't on the sta&- a'ter the
'un&tion has been e%e&uted. 9his should be < in all &ases.
ASIU@BC <
90
DIGITS() - (ANSI)
eturns the &urrent pre&ision o' arithmeti& operations. 9his 5alue is set using the +U3.I$
statement. 1or more in'ormation, re'er to the do&umentation on +U3.I$.
AI>I,SBC /9/ /5 3aybe 5/
DIRECTORY()ne8 4i'e2(#'3*) - (OS5/)
eturns the &urrent dire&tor( 'or the running pro&ess, and optionall( &hanges dire&tor( to the
spe&i'ied ne" directory. 8' the ne" directory e%ists, and the &hange to ne" directory su&&eeds, the
ne" directory is returned. 8' the ne" directory does not e%ist or an error o&&urred &hanging to that
ne" directory, the empt( string is returned.
AI.$,O.*BC //'%6/ /5 3aybe 5/
AI.$,O.*B/cHO'e%6/C /cHO'e%6/ /5 3aybe 5/
D/C(in(ege' )$"eng(&*) - (ANSI)
eturns a Fpa&-edG string, that is the &hara&ter representation o' integer, 6hi&h must be a 6hole
number, and is go5erned b( the settings o' +U3.I$ AI>I,S, not o' the internal pre&ision o' the
built$in 'un&tions. 8' length is spe&i'ied the string returned 6ill be length b(tes long, 6ith sign
e%tension. 8' length F6hi&h must be a non$negati5e 6hole numberG is not large enough to hold the
result, an error is reported.
8' length is not spe&i'ied, integer 6ill be interpreted as an unsigned number, and the result 6ill ha5e
no leading <nul> &hara&ters. 8' integer is negati5e, it 6ill be interpreted as a t6oPs &omplement, and
length must be spe&i'ied.
A#$B<C /<</&
A#$BM5C /"/ /5 on "S$II %ac!ines 5/
A#$B1#NC /N@/&
A#$B1#8C /8</&
A#$B1#8)7C /<<<<8</&
A#$B-1#8C rror 8<.17 an1 S*+,"- con1i'ion raise1
A#$B-1<)7C /(((((5/&
D/X(in(ege' )$"eng(&*) - (ANSI)
eturns a he%ade&imal number that is the he%ade&imal representation o' integer. Integer must be a
6hole number under the &urrent settings o' +U3.I$ AI>I,S, it is not e''e&ted b( the pre&ision
o' the built$in 'un&tions.
8' length is not spe&i'ied, then integer must be non$negati5e, and the result 6ill be stripped o' an(
leading Heros.
8' length is spe&i'ied, then the resulting string 6ill ha5e that length. 8' ne&essar(, it 6ill be sign$
e%tended on the le't side to ma-e it the right length. 8' length is not large enough to hold integer, an
error is reported.
91
A#-B<C /</
A#-BM5C /81/
A#-B1#NC /N@/
A#-B1#8C /8</
A#-B1#8)5C /<<<8</&
A#-B-1#8C rror 8<.17 an1 S*+,"- con1i'ion raise1
A#-B-1<)5C /((((5/&
DROPUF()n+,-e'*) - (CMS)
9his 'un&tion 6ill remo5e Hero or more bu''ers 'rom the sta&-. Called 6ithout a parameter, it 6ill
remo5e the topmost bu''er 'rom the sta&-, pro5ided that there 6ere at least one bu''er in the sta&-.
8' there 6ere no bu''ers in the sta&-, it 6ill remo5e all strings in the sta&-, i.e. remo5e the Heroth
bu''er.
8' the parameter nu#ber 6as spe&i'ied, and the sta&- &ontains a bu''er 6ith an assigned number
eKual to nu#ber, then that bu''er itsel', and all strings and bu''ers abo5e it on the sta&- 6ill be
remo5ed7 but no strings or bu''ers belo6 the numbered bu''er 6ill be tou&hed. 8' nu#ber re'ers to a
bu''er that does not e%ist in the sta&-7 no strings or bu''ers in the sta&- is tou&hed.
As an e%tra e%tension, in egina the A.OPIU@BC built$in 'un&tion &an be gi5en a non$positi5e
integer as parameter. 8' the name is negati5e then it 6ill &on5ert that number to its absolute 5alue,
and remo5e that man( bu''ers, &ounted 'rom the top. 9his is 'un&tionall( eKui5alent to repeating
A.OPIU@BC 6ithout parameters 'or so man( times as the absolute 5alue o' the negati5e number
spe&i'ies. /ote that using -< as parameter is eKui5alent to remo5ing all strings and bu''ers in the
sta&-, sin&e -< is eKui5alent to normal <. 9he number is &on5erted during e5aluation o' parameters
prior to the &all to the A.OPIU@BC routine, so the sing is lost.
9he 5alue returned 'rom this 'un&tion is the number o' bu''ers le't on the sta&- a'ter the bu''ers to
be deleted ha5e been remo5ed. Ob5iousl(, this 6ill be a non$negati5e integer. 9his too, de5iates
'rom the beha5ior o' the A.OPIU@ &ommand under C,S, 6here Hero is al6a(s returned.
A.OPIU@B7C # /5 re%ove bu((er 7 an1 8 5/
A.OPIU@B8C < /5 no bu((ers on '!e s'acT 5/
A.OPIU@BC 8 /5 i( '!ere 0!ere 5 bu((ers 5/
EOF(0i"e) - (AREXX)
Che&-s the spe&i'ied logi&al &ile name and returns the boolean 5alue 1F9rueG i' the end$o'$'ile has
been rea&hed, and 0F1alseGother6ise. 0se O&T+O9S *>!))?S!0*9T+3S 'or the A>AA
beha5iour to be e%e&uted.
O@B/in(ile/C /1/ /5 %aybe 5/
ERRORTEXT(e''#'n# )$ "ang*) - (ANSI)
eturns the Rexx error message asso&iated 6ith error number errorno. 8' the lang &hara&ter is
spe&i'ied, it 6ill determine the nati5e language in 6hi&h the error message is returned. 9he de'ault
92
5alue 'or lang is ;+;.
+N,
F/ormalG 9he error te%t is returned in the de'ault nati5e language.
+S,
FStandard >nglishG 9he error te%t is returned in >nglish.
1or more in'ormation on ho6 egina supports di''erent nati5e languages, see 9atiNe Lang#age
S#pp1rt:
8' the error message is not de'ined, a nullstring is returned.
..O.,-,B#<C /Sy%bol e&6ec'e1/
..O.,-,B7<C /+a%e or s'ring 'oo long/
..O.,-,B8<C /Incorrec' call 'o rou'ine/
errorno &an also be spe&i'ied as an errorno 'ollo6ed b( a sub error number, 6ith a period bet6een.
9he resulting string 6ill be the te%t o' the sub$error number 6ith pla&e$mar-ers indi&ating 6here
substitution 5alues 6ould normall( be pla&ed.
..O.,-,B8<.#8C Sbi(Q argu%en' 1 %us' be a binary s'ringE
(oun1 4SvalueQ4
egina also supports messages in se5eral nati5e languages. See the se&tion on 9atiNe Lang#age
S#pp1rt 'or details on ho6 this is &on'igured. Dith D! as the nati5e language in e''e&t:
..O.,-,B8<.#8C .ou'ine Sbi(Q) "rgu%en' 1 %u] eine
Iin^'?eic!enTe''e seinE 4SvalueQ4
..O.,-,B8<.#8)/S/C Sbi(Q argu%en' 1 %us' be a binary s'ringE
(oun1 4SvalueQ4
9he error messages in Rexx might be slightl( di''erent bet6een the 5arious implementations. 9he
*9S+ standard sa(s that errno must be in the range 0$*0, but in some implementations it might be
6ithin a less restri&ted range 6hi&h gi5es room 'or s(stem spe&i'i& messages. Cou should in general
not assume that the 6ordings and ordering o' the error messages are &onstant bet6een
implementations and s(stems.
Dith O&T+O9S ST>+3T?*9S+, egina 6ill return an error i' errorno is larger than *0:
..O.,-,B#<<C
>O9>A9 argument 1, must ha5e an integer part in the range 0:*0 and
a de&imal part no larger than .*7 'ound 200
Dith O&T+O9S 9OST>+3T?*9S+ Fthe de'aultG egina treats an( errorno larger than 100 as an
operating s(stem error. egina 'irst subtra&ts 100 'rom errorno and then obtains the te%t 'or errorno
'rom the operating s(stem. 9his 'a&ilit( is used to repla&e the no6 depre&ated U+I-..O. :81.
93
..O.,-,B#<<C +e'0orT is 1o0n /5 sys'e% errno 1<< 5/
..O.,-,BNNNC UnTno0n error /5 sys'e% errno MNN 5/
EXISTS(0i"ena,e) - (AREXX)
9ests 6hether the spe&i'ied name o' the gi5en &ilena#e e%ists. 9he &ilena#e string ma( in&lude an(
portion o' a 'ull 'ile path spe&i'i&ation. /ote that the argument is not a logi&al 'ile name used in
other Ae%% 'ile 'un&tions. A more portable eKui5alent o' this is to use the PB0>C >A8S9SP
&ommand o' the S9>A, :81.
-IS,SB/cHO'e%6Oin(ile.'&'/C /1/ /5 %aybe 5/
EXPORT(a44'e%%$ )%('ing*$ )"eng(&* )$.a4*) - (AREXX)
Copies data 'rom the FoptionalG string into a pre5iousl($allo&ated memor( area, 6hi&h must be
spe&i'ied as a <$b(te address. 9he length parameter spe&i'ies the ma%imum number o' &hara&ters to
be &opied7 the de'ault is the length o' the string. 8' the spe&i'ied length is longer than the string, the
remaining area is 'illed 6ith the pad &hara&ter or nullsFP00P%G. 9he returned 5alue is the number
o' &hara&ters &opied.
3a#ti1n is adNised in #sing this #ncti1n: An( area o' memor( &an be o5er6ritten,possibl(
&ausing a s(stem &rash.
See also S9OA.>FG and 8,"O9FG.
/ote that the address spe&i'ied is sub\e&t to a ma&hinePs endianess.
-PO.,B/<<<8 <<<</&)/,!e ans0er/C /1</
FILESPEC(#.(i#n$ 0i"e%.e2) - (OS5/)
eturns the spe&i'ied portion o' a passed &ilespec, depending on the option passed.
+D'i:e,
9he 'ilePs dri5e. On plat'orms that donPt ha5e the &on&ept o' a dri5e letter, returns blan-.
+Na*e,
9he 'ilePs name. 9his is the string 'ollo6ing the last path delimiter Fi' there is oneG.
+!a4h,
9he 'ilePs path. 9his is the string up to, and in&luding the last path delimiter.
Onl( the 'irst letter o' option is reKuired.
@I;SP$B/Arive/)/$HOcon(ig.sys/C /$/
@I;SP$B/+a%e/)/$HOcon(ig.sys/C /con(ig.sys/
@I;SP$B/Pa'!/)/$HOcon(ig.sys/C /O/
@I;SP$B/Arive/)//usr/bin/regina/C //
@I;SP$B/+a%e/)//usr/bin/regina/C /regina/
@I;SP$B/Pa'!/)//usr/bin/regina/C //usr/bin//
FIND(%('ing$ .&'a%e) - (CMS)
Sear&hes string 'or the 'irst o&&urren&e o' the seKuen&e o' blan-$delimited 6ords phrase, and return
the 6ord number o' the 'irst 6ord o' phrase in string. ,ultiple blan-s bet6een 6ords are treated as
94
a single blan- 'or the &omparison. eturns 0 i' phrase not 'ound. 2epre&ated: see DO2"OSFG.
@I+AB/no0 is '!e 'i%e/)/is '!e 'i%e/C #
@I+AB/no0 is '!e 'i%e/)/is '!e/C #
@I+AB/no0 is '!e 'i%e/)/is 'i%e/C <
FOR;() - (REGINA)
9his 'un&tion spa6ns a ne6 pro&ess as a &hild o' the &urrent pro&ess at the &urrent point in the
program 6here @O._ is &alled. 9he program then &ontinues 'rom this point as t6o separate
pro&esses7 the parent and the &hild. @O._ returns 0 to the &hild pro&ess, and the pro&ess id o' the
&hild pro&ess spa6ned to the parent Fal6a(s non$HeroG. A negati5e return 5alue indi&ates an error
6hile attempting to &reate the ne6 pro&ess. @O._ is not a5ailable on all plat'orms. 8' @O._ is not
supported, it 6ill al6a(s return P1P. 8t is sa'e to assume that a return 5alue o' P1P means that @O._ is
not supported. All plat'orms A1A8M, 6ill ne5er return P1P as a &hild pro&ess id7 that number is
usuall( reser5ed 'or the 'irst pro&ess that starts on a ma&hine.
@O._BC /</ /5 ,o c!il1 5/
/785M/ /5 %aybe 'o 6aren' 5/
FORM() - (ANSI)
eturns the &urrent ;'orm;, in 6hi&h numbers are presented 6hen e%ponential 'orm is used. 9his
might be either S$I+,I@I$ Fthe de'aultG or +>I+.I+>. 9his 5alue is set through the
+U3.I$ @O.3 &lause. 1or more in'ormation, see the do&umentation on +U3.I$.
@O.3BC /S$I+,I@I$/ /5 3aybe 5/
FORMAT(n+,-e' )$)-e0#'e* )$)a0(e'* )$)e<..* )$)e<.(*****) - (ANSI)
9his 'un&tion is used to &ontrol the 'ormat o' numbers, and (ou ma( reKuest the siHe and 'ormat in
6hi&h the number is 6ritten. 9he parameter nu#ber is the number to be 'ormatted, and it must be a
5alid Rexx number. note that be'ore an( &on5ersion or 'ormatting is done, this number 6ill be
normaliHed a&&ording to the &urrent setting o' +U3.I$.
9he be&ore and a&ter parameters determines ho6 man( &hara&ters that are used be'ore and a'ter the
de&imal point, respe&ti5el(. /ote that be&ore does n1t spe&i'( the number o' digits in the integer
part, it spe&i'ies the siHe o' the 'ield in 6hi&h the integer part o' the number is 6ritten. emember to
allo&ate spa&e in this 'ield 'or a minus too, i' that is rele5ant. 8' the 'ield is not long enough to hold
the integer part Fin&luding a minus i' rele5antG, an error is reported.
9he a&ter parameter 6ill di&tate the siHe o' the 'ield in 6hi&h the 'ra&tional part o' the number is
6ritten. 9he de&imal point itsel' is not a part o' that 'ield, but the de&imal point 6ill be omitted i'
the 'ield holding the 'ra&tional part is empt(. 8' there are less digits in the number than the siHe o'
the 'ield, it is padded 6ith Heros at the right. 8' there is more digits then it is possible to 'it into the
'ield, the number 6ill be rounded Fnot trun&atedG to 'it the 'ield.
0e&ore must at least be large enough to hold the integer part o' nu#ber. 9here'ore it &an ne5er be
less than 1, and ne5er less than # 'or negati5e numbers. 9he integer 'ield 6ill ha5e no leading
Heros, e%&ept a single Hero digit i' the integer part o' nu#ber is empt(.
95
9he parameter e$pp the siHe o' the 'ield in 6hi&h the e%ponent is 6ritten. 9his is the siHe o' the
numeri& part o' the e%ponent, so the ;; and the sign &omes in addition, i.e. the real length i' the
e%ponent is t6o more than e$pp spe&i'ies. 8' e$pp is Hero, it signaliHes that e%ponential 'orm should
not be used. %$pp must be a non$negati5e 6hole number. 8' e$pp is positi5e, but not large enough
to hold the e%ponent, an error is reported.
%$pt is the trigger 5alue that de&ides 6hen to s6it&h 'rom simple to e%ponential 'orm. /ormall(, the
de'ault pre&ision F+U3.I$ AI>I,SG is used, but i' e$pt is set, it 6ill o5erride that. /ote that i'
e$pt is set to Hero, e%ponential 'orm 6ill al6a(s be used. !o6e5er, i' e$pt tries to 'or&e e%ponential
'orm, simple 'orm 6ill still be used i' e$pp is Hero. /egati5e 5alues 'or e$pt 6ill gi5e an error.
>%ponential 'orm is used i' more digits than e$pt is needed in the integer part, or more than t6i&e
e$pt digits are needed in the 'ra&tional part.
/ote that the a&ter number 6ill mean di''erent things in e%ponential and simple 'orm. 8' a&ter is set
to e.g. 7, then in simple 'orm it 6ill 'or&e the pre&ision to 0.001, no matter the magnitude o' the
number. 8' in e%ponential 'orm, it 6ill 'or&e the number to < digits pre&ision.
@O.3",B1#.78)7)8C / 1#.78<</
@O.3",B1#.78)7))7)<C / 1.#78=<<1/
@O.3",B1#.78)7)1C / 1#.78<</
@O.3",B1#.78)7)<C / 1#.7/
@O.3",B1#.78)7)8C / 1#/
@O.3",B1#.78))))<C /1.#78=1/
@O.3",B1#.78)))<C /1#.78/
@O.3",B1#.78)))<)<C /1#.78/
FREESPACE(a44'e%%$ "eng(&) - (AREXX)
eturns a blo&- o' memor( o' the gi5en length to the interpreterPs internal pool. 9he address
argument must be a <$b(te string obtained b( a prior &all to .>9S"AC>FG,the internal allo&ator. 8t is
not al6a(s ne&essar( to release internall($allo&ated memor(,sin&e it 6ill be released to the s(stem
6hen the program terminates. !o6e5er,i' a 5er( large blo&- has been allo&ated,returning it to the
pool ma( a5oid memor( spa&e problems. 9he return 5alue is a boolean su&&ess 'lag.
See also .>9S"AC>FG
@.SP"$B/<<<8#<<</&)7#C /1/
FU==() - (ANSI)
eturns the &urrent number o' digits 6hi&h are ignored 6hen &omparing numbers, during operations
li-e : and Q. 9he de'ault 5alue 'or this is <. 9his 5alue is set using the +U3.I$ @URR statement,
'or more in'ormation see that.
@URRBC /</ /5 3aybe 5/
GETCALLSTAC;(%(e,) - (REGINA)
eturns in the spe&i'ied stem name an arra( &ontaining the &urrent &all sta&-. >a&h item in the arra(
96
&ontains the line number 'rom 6hi&h the routine 6as &alled 'ollo6ed b( the routine name.
>,$";;S,"$_B/s'acT./C /#/ /5 s'acT.< B3aybeC 5/
GETEN!(en:i'#n,en(:a') - (REGINA)
eturns the 5alue o' the en5ironment 5ariable 'rom the s(stem. 8' this 5ariable is not de'ined, a
nullstring is returned. 8t is not possible to use this 'un&tion to determine 6hether the 5ariable 6as
unset, or \ust set to the nullstring.
9his 'un&tion is no6 obsolete, instead (ou should use:
V";UB environ%en'var) )/S*S,3/ C
GETPID() - (REGINA)
eturns the pro&ess id o' the &urrentl( running pro&ess.
>,PIABC /#78/ /5 3aybe 5/
GETSPACE("eng(&) - (AREXX)
Allo&ates a blo&- o' memor( o' the spe&i'ied length 'rom the interpreterPs internal pool. 9he
returned 5alue is the <$b(te address o' the allo&ated blo&-, 6hi&h is not &leared or other6ise
initialiHed. 8nternal memor( is automati&all( returned to the s(stem 6hen the Rexx program
terminates,so this 'un&tion
should not be used to allo&ate memor( 'or use b( e%ternal programs.
See also 1>>S"AC>FG
>,SP"$B7#C /<<<7I@8</ /5 %aybe 5/
GETTID() - (REGINA)
eturns the thread id o' the &urrentl( running pro&ess.
>,,IABC /#/ /5 3aybe 5/
HASH(%('ing) - (AREXX)
eturns the hash attribute o' a string as a de&imal number,and updates the internal hash 5alue o' the
string.
9"S9B/1/C /89/
IMPORT(a44'e%% )$"eng(&*) - (AREXX)
Creates a string b( &op(ing data 'rom the spe&i'ied <$b(te address. 8' the length parameter is not
supplied,the &op( terminates 6hen a null b(te is 'ound.
See also >A"O9FG
/ote that the address spe&i'ied is sub\e&t to a ma&hinePs endianess.
I3PO.,B/<<<8 <<<</&)1<C /,!e ans0er/ /5 %aybe 5/
97
INDEX(&a3%(a27$ nee4"e )$%(a'(*) - (CMS)
eturns the &hara&ter position o' the string needle in haystac. 8' needle is not 'ound, 0 is returned.
:( de'ault the sear&h starts at the 'irst &hara&ter o' ha(sta&- Fstart is 1G. 9his &an be o5erridden b(
gi5ing a di''erent start, 6hi&h must be a positi5e, 6hole number. See "OS 'un&tion 'or an A/S8
'un&tion that does the same thing.
I+A-B/abc1e(/)/c1/C /7/
I+A-B/abc1e(/)/&1/C /</
I+A-B/abc1e(/)/bc/)7C /</
I+A-B/abcabc/)/bc/)7C /5/
I+A-B/abcabc/)/bc/)MC /</
INSERT(%('ing6$ %('ing/ )$.#%i(i#n )$"eng(& )$.a42&a'***) - (ANSI)
eturns the result o' inserting string. into a &op( o' string/. 8' position is spe&i'ied, it mar-s the
&hara&ter in string/ 6hi&h string. it to be inserted a'ter. -osition must be a non$negati5e 6hole
number, and it de'aults to <, 6hi&h means that string/ is put in 'ront o' the 'irst &hara&ter in string..
8' length is spe&i'ied, string. is trun&ated or padded on the right side to ma-e it e%a&tl( length
&hara&ters long be'ore it is inserted. 8' padding o&&urs, then padchar is used, or <spa&e> i' padchar
is unde'ined.
I+S.,B/(irs'/)/S$O+A/C /S$O+A(irs'/
I+S.,B/(irs'/)/S$O+A/)7C /(iS$O+Ars'/
I+S.,B/(irs'/)/S$O+A/)7)1<C /(iS$O+A rs'/
I+S.,B/(irs'/)/S$O+A/)7)1<)/5/C /(iS$O+A5555rs'/
I+S.,B/(irs'/)/S$O+A/)7)8C /(iS$Ors'/
I+S.,B/(irs'/)/S$O+A/)8C /(irs' S$O+A/
>USTIFY(%('ing$ "eng(& )$.a4*) - (CMS)
1ormats blan-$delimited 6ords in string, b( adding pad &hara&ters bet6een 6ords to \usti'( to both
margins. 9hat is, to 6idth length Flength must be non$negati5eG. 9he de'ault pad &hara&ter is a
blan-.
string is 'irst normaliHed as though S"AC>FstringG had been e%e&uted Fthat is, multiple blan-s are
&on5erted to single blan-s, and leading and trailing blan-s are remo5edG. 8' length is less than the
6idth o' the normaliHed string, the string is then trun&ated on the right and an( trailing blan- is
remo5ed. >%tra pad &hara&ters are then added e5enl( 'rom the le't to right to pro5ide the reKuired
length, and the blan-s bet6een 6ords are repla&ed 6ith the pad &hara&ter.
WUS,I@*B/,!e blue sTy/)18C /,!e blue sTy/
WUS,I@*B/,!e blue sTy/)8C /,!e blue/
WUS,I@*B/,!e blue sTy/)9C /,!e blue/
WUS,I@*B/,!e blue sTy/)9)/=/C /,!e==blue/
98
LASTPOS(nee4"e$ &a3%(a27 )$%(a'(*) - (ANSI)
Sear&hes the string haystac 'or the string needle, and returns the position in haystac o' the 'irst
&hara&ter in the substring that mat&hed needle. 9he sear&h is started 'rom the right side, so i' needle
o&&urs se5eral times, the last o&&urren&e is reported.
8' start is spe&i'ied, the sear&h starts at &hara&ter number start in haystac. /ote that the standard
onl( states that the sear&h starts at the startth &hara&ter. 8t is not stated 6hether a mat&h &an partl(
be to the right o' the start position, so some implementations ma( di''er on that point.
;"S,POSB/be/),o be or no' 'o be/C 1N
;"S,POSB/'o/)'o be or no' 'o be/)1<C 7
;"S,POSB/is/)'o be or no' 'o be/C <
;"S,POSB/'o/)'o be or no' 'o be/)<C <
LEFT(%('ing$ "eng(& )$.a42&a'*) - (ANSI)
eturns the length le'tmost &hara&ters in string. 8' length F6hi&h must be a non$negati5e 6hole
numberG is greater than the length o' string, the result is padded on the right 6ith <spa&e> For
padchar i' that is spe&i'iedG to ma-e it the &orre&t length.
;@,B/@oo bar/)5C /@oo b/
;@,B/@oo bar/)7C /@oo/
;@,B/@oo bar/)1<C /@oo bar /
;@,B/@oo bar/)1<)/5/C /@oo bar555/
LENGTH(%('ing) - (ANSI)
eturns the number o' &hara&ters in string.
;+>,9B//C /</
;+>,9B/@oo/C /7/
;+>,9B/@oo bar/C /N/
;+>,9B/ (oo bar /C /1</
LINEIN()%('ea,i4*)$)"ine*)$2#+n(**) (ANSI)
eturns a line read 'rom a 'ile. Dhen onl( strea#id is spe&i'ied, the reading starts at the &urrent
read position and &ontinues to the 'irst >nd$O'$3ine F>O3G mar-. A'ter6ard, the &urrent read
position is set to the &hara&ter a'ter the >O3 mar- 6hi&h terminated the read$operation. 8' the
operating s(stem uses spe&ial &hara&ters 'or >O3 mar-s, these are not returned b( as a part o' the
string read..
9he de'ault 5alue 'or strea#id is de'ault input stream. 9he 'ormat and range o' the string strea#id
are implementation dependent.
9he line parameter F6hi&h must be a positi5e 6hole numberG might be spe&i'ied to set the &urrent
position in the 'ile to the beginning o' line number line be'ore the read operation starts. 8' line is
unspe&i'ied, the &urrent position 6ill not be &hanged be'ore the read operation. /ote that line is onl(
99
5alid 'or persistent steams. 1or transient streams, an error is reported i' line is spe&i'ied. 9he 'irst
line in the stream is numbered 1.
!ount spe&i'ies the number o' lines to read. !o6e5er, it &an onl( ta-e the 5alues < and 1. Dhen it
is 1 F6hi&h is the de'aultG, it 6ill read one line. Dhen it is < it 6ill not read an( lines, and a
nullstring is returned. 9his has the e''e&t o' setting the &urrent read position o' the 'ile i' line 6as
spe&i'ied.
Dhat happens 6hen the 'un&tions 'inds a >nd$O'$1ile F>O1G &ondition is to some e%tent
implementation dependent. 9he implementation ma( interpret the >O1 as an impli&it >nd$O'$3ine
F>O3G mar- is none su&h 6as e%pli&itl( present. 9he implementation ma( also &hoose to raise the
+O,."A* &ondition 'lag Fthis &ondition is ne6 'rom Rexx language le5el <.00G.
Dhether or not strea# must be e%pli&itl( opened be'ore a read operation &an be per'ormed, is
implementation dependent. 8n man( implementations, a read or 6rite operation 6ill impli&itl( open
the stream i' not alread( open.
Assuming that the 'ile /'%6/(ile &ontains the three lines: ;+irst line;, Second line; and ;Third
line;:
;I+I+B//'%6/(ile/)1C /@irs' line/
;I+I+B//'%6/(ile/C /Secon1 line/
;I+I+B//'%6/(ile/)1)<C // /5 Iu' se's rea1 6osi'ion 5/
;I+I+B//'%6/(ile/C /@irs' line/
;I+I+BC /9i) '!ere!/ /5 %aybe 5/
LINEOUT()%('ea,i4* )$)%('ing* )$"ine**) - (ANSI)
eturns the number o' lines remaining a'ter ha5ing positioned the stream strea#id to the start o'
line line and 6ritten out string as a line o' te%t. 8' strea#id is omitted, the de'ault output stream is
used. 8' line F6hi&h must be a positi5e 6hole numberG is omitted, the stream 6ill not be
repositioned be'ore the 6rite. 8' string is omitted, nothing is 6ritten to the stream. 8' string is
spe&i'ied, a s(stem$spe&i'i& a&tion is ta-en a'ter it has been 6ritten to stream, to mar- a ne6 line.
9he 'ormat and &ontents o' the 'irst parameter 6ill depend upon the implementation and ho6 it
names streams. Consult implementation$spe&i'i& do&umentation 'or more in'ormation.
8' string is spe&i'ied, but not line, the e''e&t is to 6rite string to the stream, starting at the &urrent
6rite position. 8' line is spe&i'ied, but not string, the e''e&t is onl( to position the stream at the ne6
position. /ote that the line parameter is onl( legal i' the stream is persistent7 (ou &an not position
the &urrent 6rite position 'or transient streams.
8' neither line nor string is spe&i'ied, the standard reKuires that the &urrent 6rite position is set the
end o' the stream, and implementation spe&i'i& side$e''e&ts ma( o&&ur. 8n pra&ti&e, this means that
an implementation &an use this situation to do things li-e &losing the stream, or 'lushing the output.
Consult the implementation spe&i'i& do&umentation 'or more in'ormation.
Also note that the return 5alue o' this 'un&tions ma( be o' little or no 5alue, 8' \ust a hal' line is
6ritten, 1 ma( still be returned, and there are no 6a( o' 'inding out ho6 mu&h Fi' an(G o' string 6as
100
6ritten. 8' string is not spe&i'ied, the return 5alue 6ill al6a(s be <, e5en i' ;I+OU,BC 6as not
able to &orre&tl( position the stream.
8' it is impossible to &orre&tl( 6rite string to the stream, the +O,."A* 'lag 6ill be raised. 8t is not
de'ined 6hether or not the +O,."A* 'lag is raised 6hen ;I+OU,BC is used 'or positioning, and
this is not possible.
/ote that i' (ou 6rite string to a line in the middle o' the stream Fi.e. line is less than the total
number o' lines in the streamG, then the beha5ior is s(stem and implementation spe&i'i&. Some
s(stems 6ill trun&ate the stream a'ter the ne6l( 6ritten line, other 6ill onl( trun&ate i' the ne6l(
6ritten line has a di''erent length than the old line 6hi&h it repla&ed, and (et other s(stems 6ill
o5er6rite and ne5er trun&ate.
8n general, &onsult (our s(stem and implementation spe&i'i& do&umentation 'or more in'ormation
about this 'un&tion. Cou &an sa'el( assume 5er( little about ho6 it beha5es.
;I+OU,B)/@irs' line/C /1/
;I+OU,B//'%6/(ile/)/Secon1 line/)#C /1/
;I+OU,B//'%6/(ile/)/,!ir1 line/C /1/
;I+OU,B//'%6/(ile/)/@our'! line/)8C /</
LINES()%('ea,i4* )$#.(i#n*) - (ANSI)
eturns 1 i' there is at least one &omplete line remaining in the named 'ile strea# or 0 i' no
&omplete lines remain in the 'ile. A &omplete line is not reall( as &omplete as the name might
indi&ate7 a &omplete line is Hero or more &hara&ters, 'ollo6ed b( an >nd$O'$3ine F>O3G mar-er. So,
i' (ou ha5e read hal' a line alread(, (ou still ha5e a ;&omplete; line le't. /ote that it is not de'ined
6hat to do 6ith a hal'$'inished line at the end o' a 'ile. Some interpreters might interpret the >nd$
O'$1ile as an impli&it >O3 mar- too, 6hile others might not.
9he 'ormat and &ontents o' the stream strea#id is s(stem and implementation dependent. 8'
omitted, the de'ault input stream 6ill be used.
9he A/S8 Standard has e%tended this 'un&tion 'rom 932. 8t allo6s an option:
+C,
FCountG eturns the a&tual number o' &omplete lines remaining in the stream, irrespe&ti5e o'
ho6 e%pensi5e this operation is.
+N,
F/ormalG eturns 1 i' there is at least one &omplete line remaining in the 'ile or 0 i' no lines
remain. 9his is the de'ault. 9o maintain ba&-6ards &ompatibilit( 6ith older releases o'
egina, the O"98O/7 /O1AS9L38/>SL:81L2>1A039 &an be used to ma-e the de'ault
option beha5e as though 38/>SFstreamid,PCPG 6as spe&i'ied.
38/>S 6ill onl( return 0 or 1 'or all transient streams, as the interpreter &an not reposition in these
'iles, and &an there'ore not &ount the number o' remaining lines.
As a result, de'ensi5e programming indi&ates that (ou &an sa'el( onl( assume that this 'un&tion 6ill
return either < or a non$Hero result. 8' (ou 6ant to use the non$Hero result to more than \ust an
101
indi&ator on 6hether more lines are a5ailable, (ou must &he&- that it is larger than one. 8' so, (ou
&an sa'el( assume that it hold the number o' a5ailable lines le't.
As 6ith all the 'un&tions operating on streams, (ou &an sa'el( assume 5er( little about this 'un&tion,
so &onsult the s(stem and implementation spe&i'i& do&umentation.
;I+SBC /1/ /5 3aybe 5/
;I+SBC /</ /5 3aybe 5/
;I+SB//'%6/(ile/)/$/C /#/ /5 3aybe 5/
;I+SB//'%6/(ile/C /1/ /5 3aybe 5/
LOWER(%('ing )$%(a'( )$"eng(& )$.a4***) - (REGINA)
9ranslates the substring o' string that starts at start, and has the length length to lo6er &ase. Length
de'aults to the rest o' the string. Start must be a positi5e 6hole number, 6hile length &an be an(
non$negati5e 6hole number. 9he de'ault 5alue 'or start is 1 and 'or length is the length o' string.
8t is not an error 'or start to be larger than the length o' string. 8' length is spe&i'ied and the sum o'
length and start minus 1 is greater that the length o' string, then the result 6ill be padded 6ith
padchars to the spe&i'ied length. 9he de'ault 5alue 'or padchar is the <spa&e> &hara&ter.
8' a spe&i'i& lo&ale is set F5ia the $l s6it&hG, then the string is set to the &orre&t lo6er&ase 5alues
based on that lo&ale.
;OJ.B/One @ine Aay/C /one (ine 1ay/
;OJ.B/@.A/) # C /@re1/
;OJ.B/@.A/) 7) 1 C /@reA/
;OJ.B/@.A/)1) 1<) /5/ C /(re1555555/
MA;EUF() - (CMS)
Creates a ne6 bu''er on the sta&-, at the &urrent top o' the sta&-. >a&h ne6 bu''er 6ill be assigned
a number7 the 'irst bu''er being assigned the number 1. A ne6 bu''er 6ill be assigned a number
6hi&h is one higher than the &urrentl( highest number o' an( bu''er on the sta&-. 8n pra&ti&e, this
means that the bu''ers are numbered, 6ith the bottom$most ha5ing the number 1 and the topmost
ha5ing a number 6hi&h 5alue is identi&al to the number o' bu''ers &urrentl( in the sta&-.
9he 5alue returned 'rom this 'un&tion is the number assigned to the ne6l( &reated bu''er. 9he
assigned number 6ill be one more than the number o' bu''ers alread( in the sta&-, so the numbers
6ill be ;re&(&led;. 9hus, the assigned numbers 6ill not ne&essaril( be in seKuen&e.
3"_IU@BC 1 /5 i( no bu((ers e&is'e1 5/
3"_IU@BC M /5 i( 5 bu((ers e&is'e1 5/
MAX(n+,-e'6 )$n+,-e'/* ...) - (ANSI)
9a-es an( positi5e number o' parameters, and 6ill return the parameter that had the highest
numeri&al 5alue. 9he parameters ma( be an( 5alid Rexx number. 9he number that is returned, is
normaliHed a&&ording to the &urrent settings o' +U3.I$, so the result need not be stri&tl( eKual to
an( o' the parameters.
102
A&tuall(, the standard sa(s that the 5alue returned is the 'irst number in the parameter list 6hi&h is
eKual to the result o' adding a positi5e number or Hero to an( o' the other parameters. /ote that this
de'inition opens 'or ;strange; results i' (ou are bra5e enough to pla( around 6ith the settings o'
+U3.I$ @URR.
3"-B1)#)7)5)8C /5/
3"-BMC /M/
3"-B-8).<<17)8C /8/
3"-B1)#)<5.<)8C /5.</
MIN(n+,-e' )$n+,-e'* ...) - (ANSI)
3i-e 3"-BC, e%&ept that the lo6est numeri&al 5alue is returned. 1or more in'ormation, see 3"-BC.
3I+B5)8)7)1)#C /1/
3I+BMC /M/
3I+B-8).<<17)8C /-8/
3I+B1)#)<5.<-1)8C /<.5</
OPEN(0i"e$ 0i"ena,e$ )?A..en4?@?Rea4?@?W'i(e?*) - (AREXX)
Opens a 'ile 'or the spe&i'ied operation. 9he &ile argument de'ines the logi&al name b( 6hi&h the
'ile 6ill be re'eren&ed. 9he &ilena#e is the e%ternal name o' the 'ile, and ma( in&lude an( portions
o' a 'ull 'ile path.
9he 'un&tion returns a boolean 5alue that indi&ates 6hether the operation 6as su&&ess'ul. 9here is
no limit to the number o' 'iles that &an be open simultaneousl(, and all open 'iles are &losed
automati&all( 6hen the program e%its.
0se O&T+O9S *>!))?S!0*9T+3S 'or the A>AA beha5iour to be e%e&uted.
See also C3OS>FG, >A2FG, D89>FG.
OP+B/%y(ile/)/cHO'e%6Oaa.'&'/)/./C /1/
OP+B/in(ile/)//'%6/(re1.'&'/C /1/
O!ERLAY(%('ing6$ %('ing/ )$)%(a'(* )$)"eng(&* )$.a42&a'***) -
(ANSI)
eturns a &op( o' string/, totall( or partiall( o5er6ritten b( string.. 8' these are the onl( arguments,
the o5er6riting starts at the 'irst &hara&ter in string/.
8' start is spe&i'ied, the 'irst &hara&ter in string. o5er6rites &hara&ter number start in string/. Start
must be a positi5e 6hole number, and de'aults to 1, i.e. the 'irst &hara&ter o' string.. 8' the start
position is to the right o' the end o' string/, then string/ is padded at the right hand end to ma-e it
start-1 &hara&ters long, be'ore string. is added.
8' length is spe&i'ied, then string/ 6ill be stripped or padded at the right hand end to mat&h the
spe&i'ied length. 1or padding Fo' both stringsG padchar 6ill be used, or <spa&e> i' padchar is
unspe&i'ied. Length must be non$negati5e, and de'aults to the length o' string..
103
OV.;"*B/+J/)/ol1-value/C /+J-value/
OV.;"*B/+J/)/ol1-value/)8C /ol1+Jlue/
OV.;"*B/+J/)/ol1-value/)8)5C /ol1+J e/
OV.;"*B/+J/)/ol1-value/)8)5)/5/C /ol1+J55e/
OV.;"*B/+J/)/ol1-value/)8)#C /ol1+alue/
OV.;"*B/+J/)/ol1-value/)9C /ol1-valu+J/
OV.;"*B/+J/)/ol1-value/)1#C /ol1-value +J/
OV.;"*B/+J/)/ol1-value/)1#))/5/C /ol1-value55+J/
OV.;"*B/+J/)/ol1-value/)1#)5)/5/C /ol1-value55+J55/
POOLID() - (REGINA)
eturns the &urrent &all le5el 'or the &urrent pro&edure.
POO;IABC /1/ /5 'o6 level 5/
POO;IABC /M/ /5 M
'!
level call nes'ing 5/
POPEN(2#,,an4 )$%(e,.*) - (REGINA)
uns the operating s(stem co##and. 8' the optional ste#. is supplied all output 'rom the co##and
is pla&ed in the spe&i'ied stem 5ariable as a Rexx arra(. /ote that onl( the &ommandPs stdout &an be
&aptured.
9his &ommand is no6 depre&ated. A22>SS D89! &an do the same thing, and &an also &apture
the &ommandPs stderr.
POP+B/ls -l/) /lis's./C /5 ;IS,S. s'e% !as lis' 5/
"AA.SS S*S,3 /ls -l/ JI,9 OU,PU,
S,3 ;IS,S.
/5 sa%e as above 5/
POS(nee4"e$ &a3%(a27 )$%(a'(*) - (ANSI)
See-s 'or an o&&urren&e o' the string needle in the string haystac. 8' needle is not 'ound, then < is
returned. >lse, the position in haystac o' the 'irst &hara&ter in the part that mat&hed is returned,
6hi&h 6ill be a positi5e 6hole number. 8' start F6hi&h must be a positi5e 6hole numberG is
spe&i'ied, the sear&h 'or needle 6ill start at position start in haystac.
POSB/be/)/'o be or no' 'o be/C 8
POSB/'o/)/'o be or no' 'o be/)1<C 18
POSB/is/)/'o be or no' 'o be/C <
POSB/'o/)/'o be or no' 'o be/)18C <
PUTEN!(en:i'#n,en(:a'A):a"+e*) - (REGINA)
Sets the 5alue o' the named s(stem en5ironment 5ariable or deletes it. 9he e%isting 5alue is
returned i' the en5ironment 5ariable has a 5alue or i' this en5ironment 5ariable is not de'ined, a
nullstring is returned.
8' no 5alue is supplied, the s(stem en5ironment 5ariable is deleted. 9his is the onl( me&hanism
104
a5ailable to delete a s(stem en5ironment 5ariable.
PU,+VB/@.A:!ello/C // /5 I( unse' 5/
PU,+VB/@.A:/C /!ello/ /5 variable 1ele'e1 5/
BUALIFY()%('ea,i4*) - (ANSI)
eturns a name 'or the strea#id. 9he t6o names are &urrentl( asso&iated 6ith the same resour&e
and the result o' this 'un&tion ma( be more persistentl( asso&iated 6ith that resour&e.
UU";I@*B/../%y6a'!/(re1.'!e/C //!o%e/%arT/%y6a'!/(re1.'!e/
BUEUED() - (ANSI)
eturns the number o' lines &urrentl( in the e%ternal data Kueue Fthe ;sta&-;G. /ote that the sta&- is
a &on&ept e%ternal to Rexx, this 'un&tion ma( depend on the implementation and s(stem Consult
the s(stem spe&i'i& do&umentation 'or more in'ormation.
UUUABC /</ /5 3aybe 5/
UUUABC /8#/ /5 3aybe 5/
RANDOM(,a<) - (ANSI)
RANDOM(),in* )$),a<* )$%ee4**) - (ANSI)
eturns a pseudo$random 6hole number. 8' &alled 6ith onl( the 'irst parameter, the 'irst 'ormat 6ill
be used, and the number returned 6ill be in the range < to the 5alue o' the 'irst parameter, in&lusi5e.
9hen the parameter #a$ must be a non$negati5e 6hole number, not greater than 100000.
8' &alled 6ith more than one parameter, or 6ith one parameter, 6hi&h is not the 'irst, the se&ond
'ormat 6ill be used. 9hen #in and #a$ must be non$negati5e 6hole numbers, and #a$ &an not be
less than #in, and the di''eren&e #a$-#in &an not be more than 100000. 8' one or both o' them is
unspe&i'ied, the de'ault 'or #in is <, and the de'ault 'or #a$ is 999.
8' seed is spe&i'ied7 Fit must be a non$negati5e 6hole numberG (ou ma( &ontrol 6hi&h numbers the
pseudo$random algorithm 6ill generate. 8' (ou do not spe&i'( it, it 6ill be set to some ;random;
5alue at the 'irst &all to ."+AO3BC Ft(pi&all( a 'un&tion o' the timeG. Dhen spe&i'(ing seed, it 6ill
e''e&t the result o' the &urrent &all to ."+AO3BC.
9he standard does not reKuire that a spe&i'i& method is to be used 'or generating the pseudo$random
numbers, so the reprodu&ibilit( &an onl( be guaranteed as long as (ou use the same implementation
on the same ma&hine, using the same operating s(stem. 8' an( o' these &hange, a gi5en seed ma(
produ&e a di''erent seKuen&e o' pseudo$random numbers.
/ote that depending on the implementation, some numbers might ha5e a slightl( in&reased &han&e
o' turning up than other. 8' the Rexx implementation uses a =2 bit pseudo$random generator
pro5ided b( the operating s(stem and returns the remainder a'ter integer di5iding it b( the
di''eren&e o' #in and #a$, lo6 numbers are 'a5ored i' the 2T=2 is not a multiple o' that di''eren&e.
Supposing that the &all is ."+AO3B1<<<<<C and the pseudo$random generator generates an( =2
bit number 6ith eKual &han&e, the &hange o' getting a number in the range 0-?@2*? is about
0.0000100000@?, 6hile the &hanges o' getting a number in the range ?@2*@-100000 is about
105
0.00000****+<=.
A mu&h 6orse problem 6ith pseudo$random numbers are that the( sometimes do not tend to be
random at all. 0nder one operating s(stem Fname 6ithheld to prote&t the guilt(G, the s(stemPs
pseudo$random routine returned numbers 6here the last binar( digit alternated bet6een 0 and 1. On
that ma&hine, ."+AO3B1C 6ould return the series 0, 1, 0, 1, 0, 1, 0, 1 et&., 6hi&h is hardl( random
at all. Cou should there'ore ne5er trust the pseudo$random routine to gi5e (ou random numbers.
/ote that due to the spe&ial s(nta%, there is a big di''eren&e bet6een using ."+AO3B1<C and
."+AO3B1<)C. 9he 'ormer 6ill gi5e a pseudo$random number in the range 0-10, 6hile the latter
6ill gi5e a pseudo$random number in the range 10-***.
Also note that it is not &lear 6hether the standard allo6s #in to be eKual to #a$, so to program
&ompatible, ma-e sure that #a$ is al6a(s larger than #in.
."+AO3BC /1#7/ /5Ie'0een < an1 999 5/
."+AO3B1<C /5/ /5Ie'0een < an1 1< 5/
."+AO3B)1<C /7/ /5Ie'0een < an1 1< 5/
."+AO3B#<)7<C /#N/ /5Ie'0een #< an1 7< 5/
."+AO3B))1#785C /NM5/ /5Ie'0een < an1 999) an1 se's see1 5/
RANDU()%ee4*) - (AREXX)
eturns a uni'orml($distributed pseudo random number bet6een 0 and 1. 9he number o' digits o'
pre&ision in the result is al6a(s eKual to the &urrent /umeri& 2igits setting. Dith the &hoi&e o'
suitable s&aling and translation 5alues, A/20FG&an be used to generate pseudo random numbers
on an arbitrar( inter5al.
9he optional seed argument is used to initialiHe the internal state o' the random number generator.
See also A/2O,FG
."+AUBC /<.7N19<#<#1/
."+AUB85C /<.8N7/ /5nu%eric 1igi's 75/
READCH(0i"e$ "eng(&) - (AREXX)
eads the spe&i'ied number o' &hara&ters 'rom the gi5en logi&al 'ile and returns them. 9he length o'
the returned string is the a&tual number o' &hara&ters read,and ma( be less than the reKuested length
i', 'or e%ample, the end$o'$'ile 6as rea&hed.
See also >A23/FG
."A$9B/in(ile/)1<C /a s'ring o/
READLN(0i"e) - (AREXX)
eads &hara&ters 'rom the gi5en logi&al 'ile into a string until a ;ne6line; &hara&ter is 'ound. 9he
returned string does not in&lude the ;ne6line;.
See also >A2C!FG
."A;+B/in(ile/C /a s'ring o( c!ars/
106
RE!ERSE(%('ing) - (ANSI)
eturns a string o' the same length as string, but ha5ing the order o' the &hara&ters re5ersed.
.V.SB/@ooIar/C /raIoo@/
.V.SB/ @oo Iar/C /raI oo@ /
.V.SB/7.18159/C /95181.7/
RIGHT(%('ing$ "eng(&)$.a42&a'*) - (ANSI)
eturns the length rightmost &hara&ters in string. 8' length F6hi&h must be a non$negati5e 6hole
numberG is greater than the length o' string the result is padded on the le't 6ith the ne&essar(
number o' padchars to ma-e it as long as length spe&i'ies. -adchar de'aults to <spa&e>.
.I>9,B/@oo bar/)5C /o bar/
.I>9,B/@oo bar/)7C /bar/
.I>9,B/@oo bar/)1<C / @oo bar/
.I>9,B/@oo bar/)1<)/5/C //555@oo bar/
RXFUNCADD(e<(e'na"na,e$ "i-'a'3$ in(e'na"na,e) - (SAA)
egisters the internalna#e in library as an e%ternal 'un&tion &allable 'rom 6ith the &urrent program
b( re'eren&ing e$ternalna#e. library is a Rexx e%ternal 'un&tion pa&-age in the 'ormat o' shared
librar( or d(nami& lin- librar( F233G. library and internalname are &ase$sensiti5e. library is the
base name o' the shared librar( or d(nami& lin- librar(. On plat'orms that support 233s, the 'ull
name o' the e%ternal 'un&tion pa&-age is library.d$$. On 0ni% en5ironments, the 'ull name o' the
shared librar( is $iblibrary.a FA8AG, $iblibrary.s$ F!"0AG or $iblibrary.s1 Fmost other 0ni%esG.
>%ternal 'un&tion pa&-ages are sear&hed 'or in the lo&ation 6here shared libraries or 233s are
normall( 'ound b( the operating s(stem. 233s are normall( lo&ated in dire&tories spe&i'ied in the
&*T% or L+7&*T% en5ironment 5ariables. Shared libraries are normall( sear&hed 'or in
LD?L+7>*>O?&*T% or L+7&*T% en5ironment 5ariables.
9his 'un&tion returns 0 i' the 'un&tion is registered su&&ess'ull(7 non$Hero other6ise.
.-@U+$"AAB/SU;;oa1@uncs/)/re&&sVl/)/SU;;oa1@uncs/C <
RXFUNCDROP(e<(e'na"na,e) - (SAA)
emo5es the spe&i'ied e%ternalname 'rom the list o' e%ternal 'un&tions a5ailable to be &alled. 9his
'un&tion returns 0 i' the 'un&tion 6as su&&ess'ull( dropped.
.-@U+$A.OPB/SU;;oa1@uncs/C <
RXFUNCERRMSG() - (REGINA)
eturns the error message asso&iated 6ith the last &all to A10/CA22. 9his 'un&tion is generall(
used immediatel( a'ter a 'ailed &all to A10/CA22 to determine 6h( it 'ailed.
.-@U+$..3S>BC /re&&sVl.1ll no' (oun1/ /5 3aybe 5/
107
RXFUNCBUERY(e<(e'na"na,e) - (SAA)
eturns 0 i' the e$ternalna#e is alread( registered, or 1 i' the e$ternalna#e is not registered.
.-@U+$UUU.*B/SU;;oa1@uncs/C 1 /5 3aybe 5/
RXBUEUE(2#,,an4 )$1+e+e@(i,e#+(*) - (OS5/)
9his 'un&tion inter'a&es to the egina internal or e%ternal Kueue me&hanism. 8' O"98O/S
8/9>/A3LB0>0>S is set, all operations on Kueues are internal to the interpreter.
+C,
FCreateG eKuest the interpreter or r%sta&- to &reate a ne6 named 1ueue. 8' the 1ueue name
alread( e%ists, a ne6 uniKue Kueue name is generated. 9he name o' the Kueue that 6as
&reated Feither the spe&i'ied Kueue or the s(stem$generated KueueG is returned. All Kueue
names are &ase$insensiti5e7 i.e. the Kueue name 1>2 and 'red are the same.
+D,
F2eleteG 2eletes the spe&i'ied 1ueue. 9he de'ault Kueue7 S>SS8O/ be&omes the &urrent
Kueue.
+G,
F.etG eturns the &urrent 1ueue name.
+S,
FSetG Sets the &urrent Kueue name to that 1ueue spe&i'ied. 9he pre5iousl( &urrent Kueue is
returned. 8t is 5alid to set a Kueue name to a Kueue that has not been &reated.
+T,
F9imeoutG Sets the ti#eout period Fin millise&ondsG to 6ait 'or something to appear on the
&urrent Kueue Fas set b( AB0>0>FPSP, KueueG G. :( de'ault, 6hen a line is read 'rom a
Kueue 6ith a "033 &ommand, it either returns immediatel( 6ith the top line in the sta&-, or
it 6ill 6ait 'or a line to be entered b( the user 5ia the pro&essP stdin. 8' 0 is spe&i'ied, egina
6ill 6ait 'ore5er 'or a line to be read( on the sta&-.
An error 6ill result i' an attempt is made to set a timeout on an internal Kueue7 timeouts onl(
ma-e sense on e%ternal Kueues Fie those 6ith a P@P in them that use the r%sta&- pro&essG.
.-UUUB/$rea'e/C /S<N78#8</
.-UUUB/$rea'e/)/(re1/C /@.A/
.-UUUB/$rea'e/) /(re1/C /S88781/
.-UUUB/>e'/C /S88781/
.-UUUB/Aele'e/)/(re1/C /SSSIO+/
.-UUUB/Se'/)/(re1/C /SSSIO+/
.-UUUB/,i%eou'/)1<<<C /</
SEE;(0i"e$ #00%e($ )?egin?@?C+''en(?@?En4?) - (AREXX)
,o5es to a ne6 position in the gi5en logi&al 'ile, spe&i'ied as an o&&set 'rom an an&hor position. 9he
de'ault an&hor is Current. 9he returned 5alue is the ne6 position relati5e to the start o' the 'ile.
S_B/in(ile/)1<)/I/C /1</
S_B/in(ile/)<)//C /75M/ /5 (ile leng'! 5/
108
SHOW(#.(i#n$ )na,e*$ ).a4*) - (AREXX)
eturns the names in the resour&e list spe&i'ied b( the option argument, or tests to see 6hether an
entr( 6ith the spe&i'ied na#e is a5ailable. 9he &urrentl( implemented options -e(6ords are Clip,
1iles, 3ibraries, and "orts, 6hi&h are des&ribed belo6.
3$ip. >%amines the names in the Clip 3ist.
@i$es. >%amines the names o' the &urrentl( open logi&al 'ile names.
Libraries. >%amines the names in the 3ibrar( 3ist,6hi&h are either 'un&tion libraries or 'un&tion
hosts.
&1rts. >%amine the names in the s(stem "orts 3ist.
8' the na#e argument is omitted, the 'un&tion returns a string 6ith the resour&e names separated b(
a blan- spa&e or the pad &hara&ter,i' one 6as supplied. 8' the na#e argument is gi5en, the returned
boolean 5alue indi&ates 6hether the na#e 6as 'ound in the resour&e list. 9he na#e entries are &ase$
sensiti5e.
Onl( the @i$es option is 5alid on all plat'orms. All other 5alues 'or option are onl( appli&able to the
Amiga and AOS ports.
SIGN(n+,-e') - (ANSI)
eturns either -1, < or 1, depending on 6hether nu#ber is negati5e, Hero, or positi5e, respe&ti5el(.
Nu#ber must be a 5alid Rexx number, and are normaliHed a&&ording to the &urrent settings o'
+U3.I$ be'ore &omparison.
SI>+B-1#C /-1/
SI>+B8#C /1/
SI>+B-<.<<<<<<1#C /-1/
SI>+B<.<<<C /</
SI>+B-<.<C /</
SLEEP(%e2#n4%) - (CMS)
"auses 'or the supplied number o' se&onds.
S;PB5C /5 slee6s (or 5 secon1s 5/
SOURCELINE()"inen#*) - (ANSI)
8' lineno F6hi&h must be a positi5e 6hole numberG is spe&i'ied, this 'un&tion 6ill return a string
&ontaining a &op( o' the Rexx s&ript sour&e &ode on that line. 8' lineno is greater than the number o'
lines in the Rexx s&ript sour&e &ode, an error is reported.
8' lineno is unspe&i'ied, the number o' lines in the Rexx s&ript sour&e &ode is returned.
/ote that 'rom Rexx language le5el =.50 to <.00, the reKuirements o' this 'un&tion 6ere rela%ed to
simpli'( e%e&ution 6hen the sour&e &ode is not a5ailable F&ompiled or pre$parsed RexxG. An
implementation might ma-e t6o simpli'i&ations: to return < i' &alled 6ithout a parameter. 8' so, an(
&all to SOU.$;I+BC 6ith a parameter 6ill generate an error. 9he other simpli'i&ation is to
return a nullstring 'or an( &all to SOU.$;I+BC 6ith a legal parameter.
/ote that the &ode e%e&uted b( the I+,.P., &lause &an not be retrie5ed b( SOU.$;I+BC.
109
SOU.$;I+BC /8#/ /53aybe 5/
SOU.$;I+B1C //5 ,!is .e&& scri6' 0ill ... 5//
SOU.$;I+B#7C /var : 1#/ /53aybe 5//
SPACE(%('ing)$ )"eng(&* )$.a42&a'**) - (ANSI)
Dith onl( one parameter string is returned, stripped o' an( trailing or leading blan-s, and an(
&onse&uti5e blan-s inside string translated to a single <spa&e> &hara&ter For padchar i' spe&i'iedG.
Length must be a non$negati5e 6hole number. 8' spe&i'ied, &onse&uti5e blan-s 6ithin string are
repla&ed b( e%a&tl( length instan&es o' <spa&e> For padchar i' spe&i'iedG. !o6e5er, padchar 6ill
onl( be used in the output string, in the input string, blan-s 6ill still be the ;magi&; &hara&ters. As a
&onseKuen&e, i' there e%ist an( padchars in string, the( 6ill remain untou&hed and 6ill not a''e&t
the spa&ing.
SP"$B/ @oo bar /C /@oo bar/
SP"$B/ @oo bar /)#C /@oo bar/
SP"$B/ @oo bar /))/5/C /@oo5bar/
SP"$B/@oo bar/)7) /-/C /@oo---bar/
SP"$B/@oo bar/))/o/C /@ooobar/
STATE(%('ea,i4) - (CMS)
eturns 0 i' the strea#id e%ists, or 1 i' it does not. 0se S9>A,Fstreamid, PCP, PB0>C >A8S9SPG
'or portabilit(.
STORAGE()a44'e%%*$ )%('ing*$ )"eng(&*$ ).a4*) - (AREXX)
Calling S9OA.>FG 6ith no arguments returns the a5ailable s(stem memor(. 8' the address
argument is gi5en, it must be a <$b(te string,and the 'un&tion &opies data 'rom the optional string
into the indi&ated memor( area. 9he length parameter spe&i'ies the ma%imum number o' b(tes to be
&opied,and de'aults to the length o' the string. 8' the spe&i'ied length is longer than the string,the
remaining area is 'illed 6ith the pad &hara&ter or nullsFP00P%.G
9he returned 5alue is the pre5ious &ontents o' the memor( area. 9his &an be used in a subseKuent
&all to restore the original &ontents.
3a#ti1n is adNised in #sing this #ncti1n: *ny area 1 mem1ry can be 1Ner6rittenIp1ssib$y
ca#sing a system crash:
S,O.">BC /#888<</
S,O.">B/<<<8 <<<</&)/,!e ans0er/C /Vues'ion/ /5 %aybe 5/
STREAM(%('ea,i4)$#.(i#n)$2#,,an4**) (ANSI)
9his 'un&tion 6as added to Rexx in language le5el <.00. 8t pro5ides a general me&hanism 'or doing
operations on streams. !o6e5er, 5er( little is spe&i'ied about ho6 the internal o' this 'un&tion
should 6or-, so (ou should &onsult the implementation spe&i'i& do&umentation 'or more
in'ormation.
9he strea#id identi'ies a stream. 9he a&tual &ontents and 'ormat o' this string is implementation
dependent.
110
9he option sele&ts one o' se5eral operations 6hi&h S,."3BC is to per'orm. 9he possible
operations are:
+C,
FCommandG 8' this option is sele&ted, a third parameter must be present, co##and, 6hi&h is
the &ommand to be per'ormed on the stream. 9he &ontents o' co##and is implementation
dependent. 1or egina, the 5alid &ommands 'ollo6. Commands &onsist o' one or more
spa&e separated 6ords.
+D,
F2es&riptionG eturns a des&ription o' the state o' strea#id. 9he return 5alue is
implementation dependent.
+S,
FStatusG eturns a state 6hi&h des&ribes the state o' strea#id. 9he standard reKuires that it is
one o' the 'ollo6ing: ..O., +O,."A*, ."A* and U+_+OJ+. 9he meaning o' these
are des&ribed in the &hapter7 Stream +np#t and O#tp#t.
/ote that the options Aescri6'ion and S'a'us reall( ha5e the same 'un&tion, but that S'a'us
in general is implementation independent, 6hile Aescri6'ion is implementation dependent.
9he co##and spe&i'ies the &ommand to be per'ormed on strea#id. 9he possible operations are:
+READ,
Open 'or read a&&ess. 9he 'ile pointer 6ill be positioned at the start o' the 'ile, and onl( read
operations are allo6ed. 9his &ommand is egina$spe&i'i&7 use OPEN READ in its pla&e.
+WRITE,
Open 'or 6rite a&&ess and position the &urrent 6rite position at the end o' the 'ile. An error
is returned i' it 6as not possible to get appropriate a&&ess. 9his &ommand is egina$spe&i'i&7
use OPEN WRITE in its pla&e.
+APPEND,
Open 'or append a&&ess and position the &urrent 6rite position at the end o' the 'ile. An
error is returned i' it 6as not possible to get appropriate a&&ess. 9his &ommand is egina$
spe&i'i&7 use OPEN WRITE APPEND in its pla&e.
+UPDATE,
Open 'or append a&&ess and position the &urrent 6rite position at the end o' the 'ile. An
error is returned i' it 6as not possible to get appropriate a&&ess. 9his &ommand is egina$
spe&i'i&7 use OPEN OTH in its pla&e.
+CREATE,
Open 'or 6rite a&&ess and position the &urrent 6rite position at the start o' the 'ile. An error
is returned i' it 6as not possible to get appropriate a&&ess. 9his &ommand is egina$spe&i'i&7
use OPEN WRITE REPLACE in its pla&e.
+CLOSE,
Close the stream, 'lushing an( pending 6rites. An error is returned i' it 6as not possible to
get appropriate a&&ess.
+FLUSH,
1lush an( pending 6rite to the stream. An error is returned i' it 6as not possible to get
appropriate a&&ess.
+STATUS,
eturns status in'ormation about the stream in human readable 'orm that egina stores
111
about the stream.
+FSTAT,
eturns status in'ormation 'rom the operating s(stem about the stream. 9his &onsists o' at
least + 6ords:
De:i2e N+,-e' 0nder 2OS, Din=2, OS#2, this represents the dis- number, 6ith
0 being 2ri5e A.
In#4e N+,-e' 0nder 2OS, Din=2, OS#2, this is Hero.
Pe',i%%i#n% 0ser#.roup#Other permissions mas-. Consists o' = o&tal
numbers 6ith < representing read, 2 representing 6rite, and 1
representing e%e&ute. 9here'ore a 5alue o' @50 is
read#6rite#e%e&ute 'or user, read#e%e&ute 'or group, and no
permissions 'or other.
N+,-e' Lin7% 0nder 2OS, Din=2, OS#2, this 6ill al6a(s be 1.
U%e' Na,e 9he o6ner o' the stream. 0nder 2OS, Din=2, OS#2, this 6ill
al6a(s be U0S>V.
G'#+. Na,e 9he group o6ner o' the stream. 0nder 2OS, Din=2, OS#2, this
6ill al6a(s be U.O0"V.
SiCe SiHe o' stream in b(tes.
S('ea, T3.e One or more o' the 'ollo6ing:
>eg#$ar@i$e a normal 'ile.
Direct1ry a dire&tor(.
7$1c;Specia$ a blo&- spe&ial 'ile.
@+@O usuall( a pipe.
Symb1$icLin; a s(mboli& lin-. 8' the stream is a s(mboli& lin-,
the the details returned are details about the lin-, not the 'ile the
lin- points to.
S1c;et a so&-et
Specia$9ame a named spe&ial 'ile.
3haracterSpecia$ a &hara&ter spe&ial 'ile.
+RESET,
esets the stream a'ter an error. Onl( streams that are resettable &an be reset.
+READALE,
eturns 1 i' the stream is readable b( the user or 0 other6ise.
+WRITALE,
eturns 1 i' the stream is 6ritable b( the user or 0 other6ise.
+EXECUTALE,
eturns 1 i' the stream is e%e&utable b( the user or 0 other6ise.
+BUERY,
eturns in'ormation about the named stream. 8' the named stream does not e%ists, then the
empt( string is returned. 9his &ommand is 'urther bro-en do6n into the 'ollo6ing sub$
&ommands:
DATETIME returns the date and time o' last modi'i&ation o' the stream in
Rexx 0S 2ate 'ormat7 ,,$22$CC !!:,,:SS.
EXISTS returns the 'ull($Kuali'ied 'ile name o' the spe&i'ied stream.
HANDLE returns the internal 'ile handle o' the stream. 9his 6ill onl(
return a 5alid 5alue i' the stream 6as opened e%pli&itl( or
impli&itl( b( egina.
SEE; READ CHAR returns the &urrent read position o' the open stream e%pressed in
&hara&ters.
112
SEE; READ LINE returns the &urrent read position o' the open stream e%pressed in
lines.
SEE; WRITE CHAR returns the &urrent 6rite position o' the open stream e%pressed in
&hara&ters.
SEE; WRITE LINE returns the &urrent 6rite position o' the open stream e%pressed in
lines.
SEE; SYS returns the &urrent read position o' the open stream as the
operating reports it. 9his is e%pressed in &hara&ters.
SI=E returns the siHe, e%pressed in &hara&ters, o' the persistent stream.
STREAMTYPE returns the t(pe o' the stream. One o' 9A/S8>/9,
">S8S9>/9 or 0/M/OD/ is returned.
TIMESTAMP returns the date and time o' last modi'i&ation o' the stream. 9he
'ormat o' the string returned is CCCC$,,$22 !!:,,:SS.
Cou &an use &OS+T+O9 in pla&e o' S!!P in the abo5e options.
+OPEN,
Opens the stream in the optional mode spe&i'ied. 8' no optional mode is spe&i'ied, the
de'ault is OPEN OTH.
READ 9he 'ile pointer 6ill be positioned at the start o' the 'ile, and
onl( read operations are allo6ed.
WRITE Open 'or 6rite a&&ess and position the &urrent 6rite pointer at
the end o' the 'ile. On plat'orms 6here it is not possible to open
a 'ile 'or 6rite 6ithout also allo6ing reads, the read pointer 6ill
be positioned at the start o' the 'ile. An error is returned i' it 6as
not possible to get appropriate a&&ess.
OTH Open 'or read and 6rite a&&ess. "osition the &urrent read pointer
at the start o' the 'ile, and the &urrent 6rite pointer at the end o'
the 'ile. An error is returned i' it 6as not possible to get
appropriate a&&ess.
WRITE APPEND Open 'or 6rite a&&ess and position the 6rite pointer at the end o'
the 'ile. On plat'orms 6here it is not possible to open a 'ile 'or
6rite 6ithout also allo6ing reads, the read pointer 6ill be
positioned at the start o' the 'ile.
WRITE REPLACE Open 'or 6rite a&&ess and position the &urrent 6rite position at
the start o' the 'ile. On plat'orms 6here it is not possible to
open a 'ile 'or 6rite 6ithout also allo6ing reads, the read pointer
6ill be positioned at the start o' the 'ile. 9his operation 6ill
&lear the &ontents o' the 'ile. An error is returned i' it 6as not
possible to get appropriate a&&ess.
OTH APPEND Open 'or read and 6rite a&&ess. "osition the &urrent read
position at the start o' the 'ile, and the &urrent 6rite position at
the end o' the 'ile. An error is returned i' it 6as not possible to
get appropriate a&&ess.
OTH REPLACE Open 'or read and 6rite a&&ess. "osition both the &urrent read
and 6rite pointers at the start o' the 'ile. An error is returned i'
it 6as not possible to get appropriate a&&ess.
)SEE; position READ@WRITE )CHAR@LINE**
"ositions the 'ilePs read or 6rite pointer in the 'ile to the spe&i'ied position. SEE; is a
s(non(m 'or POSITION.
.#%i(i#n A position &an be o' the 'ollo6ing 'orms. IrelativeJo&&set.
113
relative &an be one o':
R 9he 'ile pointer is mo5ed to the spe&i'ied o&&set
relati5e to the start o' the 'ile. 9his is the
de'ault.
< 9he 'ile pointer is mo5ed to the spe&i'ied o&&set
relati5e to the end o' the 'ile.
$ 9he 'ile pointer is mo5ed ba&-6ards relati5e to
the &urrent position.
^ 9he 'ile pointer is mo5ed 'or6ards relati5e to the
&urrent position.
o&&set is a positi5e 6hole number.
READ 9he read 'ile pointer 6ill be positioned.
WRITE 9he 6rite 'ile pointer is positioned.
CHAR 9he o&&set spe&i'ied in position abo5e is in terms o' &hara&ters.
LINE 9he o&&set spe&i'ied in position abo5e is in terms o' lines.
Assume a 'ile7 P#home#mar-#m('ileP last &hanged ,ar&h =0th 2002 at 15:0@:5?, 6ith 100 lines, ea&h
line 10 &hara&ters long, and the 'ollo6ing &ommand e%e&uted in seKuen&e.
S,."3B/%y(ile/)/$/)/UU.* -IS,S/C //!o%e/%arT/%y(ile/
S,."3B/%y(ile/)/$/)/UU.* SIR/C 11<<
S,."3B/%y(ile/)/$/)/UU.* ,I3S,"3P/C #<<#-<7-7< 15H<NH5M
S,."3B/%y(ile/)/$/)/UU.* A",,I3/C <7-7<-<# 15H<NH5M
S,."3B/%y(ile/)/A/C
S,."3B/%y(ile/)/S/C U+_+OJ+
S,."3B/%y(ile/)/$/)/UU.* S_ ."A/C
S,."3B/%y(ile/)/$/)/OP+ ."A/C ."A*H
S,."3B/%y(ile/)/A/C
S,."3B/%y(ile/)/S/C ."A*
S,."3B/%y(ile/)/$/)/UU.* S_ ."A/C 1
S,."3B/%y(ile/)/$/)/$;OS/C U+_+OJ+
S,."3B/%y(ile/)/$/)/S,",US/C
S,."3B/%y(ile/)/$/)/@S,",/C NN7 75<<M <M8 1 %arT
%arT 11<< .egular@ile
S,."3B/%y(ile/)/$/)/."A"I;/C 1
S,."3B/%y(ile/)/$/)/J.I,"I;/C 1
S,."3B/%y(ile/)/$/)/-$U,"I;/C <
STRIP(%('ing )$)#.(i#n* )$2&a'**) - (ANSI)
eturns string a'ter possibl( stripping it o' an( number o' leading and#or trailing &hara&ters. 9he
de'ault a&tion is to strip o'' both leading and trailing blan-s. 8' char F6hi&h must be a string
&ontaining e%a&tl( one &hara&terG is spe&i'ied, that &hara&ter 6ill be stripped o'' instead o' blan-s.
114
8nter$6ord blan-s For chars i' de'ined, that are not leading o' trailingG are untou&hed.
8' option is spe&i'ied, it 6ill de'ine 6hat to strip. 9he possible 5alues 'or option are:
+L,
F3eadingG Onl( strip o'' leading blan-s, or chars i' spe&i'ied.
+T,
F9railingG Onl( strip o'' trailing blan-s, or chars i' spe&i'ied.
+,
F:othG Combine the e''e&t o' ; and ,, that is, strip o'' both leading and trailing blan-s, or
chars i' it is spe&i'ied. 9his is the de'ault a&tion.
S,.IPB/ @oo bar /C /@oo bar/
S,.IPB/ @oo bar /)/;/C /@oo bar /
S,.IPB/ @oo bar /)/'/C / @oo bar/
S,.IPB/ @oo bar /)/Io'!/C /@oo bar/
S,.IPB/<.1#785<</))/</C /.1#785/
S,.IPB/<.1#785<< /))/</C /.1#785<< /
SUSTR(%('ing$ %(a'( )$"eng(& )$.a42&a'**) - (ANSI)
eturns the substring o' string that starts at start, and has the length length. Length de'aults to the
rest o' the string. Start must be a positi5e 6hole, 6hile length &an be an( non$negati5e 6hole
number.
SUIS,.B/@oo bar/)7C /o bar/
SUIS,.B/@oo bar/)7)7C /o b/
SUIS,.B/@oo bar/)8)MC / bar /
SUIS,.B/@oo bar/)8)M)/5/C / bar55/
SUIS,.B/@oo bar/)9)8)/5/C /5555/
SUWORD(string$ start )$length*) - (ANSI)
eturns the part o' string that starts at blan- delimited 6ord start F6hi&h must be a positi5e 6hole
numberG. 8' length F6hi&h must be a non$negati5e 6hole numberG is spe&i'ied, that number o' 6ords
are returned. 9he de'ault 5alue 'or length is the rest o' the string.
8t is not an error to spe&i'( length to re'er to more 6ords than string &ontains, or 'or start and length
together to spe&i'( more 6ords than string holds. 9he result string 6ill be stripped o' an( leading
and trailing blan-s, but inter$6ord blan-s 6ill be preser5ed as is.
115
SUIJO.AB/,o be or no' 'o be/)8C /no' 'o be/
SUIJO.AB/,o be or no' 'o be/)8)#C /no' 'o/
SUIJO.AB/,o be or no' 'o be/)8)5C /no' 'o be/
SUIJO.AB/,o be or no' 'o be/)1)7C /,o be or/
SYMOL(%('ing) - (ANSI)
Che&-s i' the string is a 5alid s(mbol Fa positi5e number or a possible 5ariable nameG, and returns a
three letter string indi&ating the result o' that &he&-. 8' string is a s(mbol, and names a &urrentl( set
5ariable, V". is returned, i' string is a legal s(mbol name, but has not a been gi5en a 5alue For is a
&onstant s(mbol, 6hi&h &an not be used as a 5ariable nameG, ;I, is returned to signi'( that it is a
literal. >lse, i' string is not a legal s(mbol name the string I"A is returned.
Dat&h out 'or the e''e&t o' ;double e%pansion;. string is interpreted as an e%pression e5aluating
naming the s(mbol to be &he&-ed, so (ou might ha5e to Kuote the parameter.
S*3IO;B/@oobar/C /V"./ /5 3aybe 5/
S*3IO;B/@oo bar/C /I"A/
S*3IO;B/@oo.@oo bar/C /I"A/
S*3IO;B/7.18/C /;I,/
S*3IO;B/.@oo-Qbar/C /I"A/
TIME()#.(i#n_#+( )$(i,e )#.(i#n_in***) - (ANSI)
eturns a string &ontaining in'ormation about the lo&al time. 9o get the time in a parti&ular 'ormat,
an option3out &an be spe&i'ied. 9he de'ault option3out is +or%al. 9he meaning o' the possible
options are:
+C,
FCi5ilG eturns the time in &i5il 'ormat. 9he return 5alue might be ;!!H%%--;, 6here --
are either a% or 6%. 9he !! part 6ill be stripped o' an( leading Heros, and 6ill be in the
range 1-12 in&lusi5e. FA/S8G
+E,
F>lapsedG eturns the time elapsed in se&onds sin&e the internal stop6at&h 6as started. 9he
result 6ill not ha5e an( leading Heros or blan-s. 9he output 6ill be a 'loating point number
6ith si% digits a'ter the de&imal point. FA/S8G
+H,
F!oursG eturns the number o' &omplete hours that ha5e passed sin&e last midnight in the
'orm ;!!;. 9he output 6ill ha5e no leading Heros, and 6ill be in the range 0-2=. FA/S8G
+>,
FOobG eturns the number o' se&onds o' C"0 time the &urrentl( running pro&ess has
&urrentl( used. 9he output 6ill ha5e no leading Heros, and 6ill ha5e ? de&imal pla&es.
Fegina >%tensionG
+L,
F3ongG eturns the e%a&t time, do6n to the mi&rose&ond. 9his is &alled the long 'ormat. 9he
output might be ;!!H%%Hss.%%%%%%;. :e a6are that most &omputers do not ha5e a
&lo&- o' that a&&ura&(, so the a&tual granularit( (ou &an e%pe&t, 6ill be about a 'e6
millise&onds. 9he !!, %% and ss parts 6ill be identi&al to 6hat is returned b( the options 9,
116
3 and S respe&ti5el(, e%&ept that ea&h part 6ill ha5e leading Heros as indi&ated b( the
'ormat. FA/S8G
+M,
F,inutesG eturns the number o' &omplete minutes sin&e midnight, in a 'ormat ha5ing no
leading spa&es or Heros. FA/S8G
+N,
F/ormalG 9he output 'ormat is ;!!H%%Hss;, and is padded 6ith Heros i' needed. 9he !!,
%% and ss 6ill &ontain the hours, minutes and se&onds, respe&ti5el(. >a&h part 6ill be
padded 6ith leading Heros to ma-e it double$digit. FA/S8G
+O,
FO''setG eturns the number o' mi&rose&onds bet6een 09C time and lo&al time. Dhere
lo&al da(light sa5ings is in e''e&t, this o''set #ay be ad\usted b( the addition o' 1 hour. F/ot
all s(stems reliabl( pro5ide da(ight sa5ings time indi&ationG. 9his option 6as added 6ith the
A/S8 Standard. FA/S8G
+R,
FesetG eturns the 5alue o' the internal stop6at&h \ust li-e the option, and using the same
'ormat. 8n addition, it 6ill reset the stop6at&h to Hero a'ter its &ontents has been read.
FA/S8G
+S,
FSe&ondsG eturns the number o' &omplete se&onds sin&e midnight, in a 'ormat ha5ing no
leading spa&es or Heros. FA/S8G
+T,
Fti#e3tG eturns the &urrent 09C date#time in 0/8A ti#e3t 'ormat. ti#e3t is the number o'
se&onds sin&e Oanuar( 1
st
1*@0. 8t al6a(s represents the 09C date#time, so an( &on5ersion
'rom another time 'ormat F6hi&h is al6a(s assumed to be lo&al timeG 6ill result in a ti#e3t
5alue o''set b( time Hone. Fegina >%tensionG
/ote that the time is ne5er rounded, onl( trun&ated. As sho6n in the e%amples belo6, the se&onds
do not get rounded up6ards, e5en though the de&imal part implies that the( are &loser to 59 than to
58. 9he same applies 'or the minutes, 6hi&h are &loser to 77 than to 7#, but is trun&ated to 7#.
/one o' the 'ormats 6ill ha5e leading or trailing spa&es.
Assuming that the time is e%a&tl( 1<:=2:5+.*+@?5< on ,ar&h =0
th
2002, the 'ollo6ing 6ill be true:
,I3B/$/C /#H7#6%/
,I3B//C /<.<1#<</ /5 3aybe 5/
,I3B/9/C /18/
,I3B/;/C /18H7#H58.98NM58/
,I3B/3/C /7#/
,I3B/+/C /18H7#H58/
,I3B/./C /<.87<##1/ /5 3aybe 5/
,I3B/S/C /58/
,I3B/O/C 7M<<<<<<<<< /5 as' $oas' "us 5/
,I3B/WC 5.78#<<< /5 3aybe 5/
117
8' the ti#e option is spe&i'ied, the 'un&tion pro5ides 'or time &on5ersions. 9he optional option3in
spe&i'ies the 'ormat in 6hi&h ti#e is supplied. 9he possible 5alues 'or option3in are: 3%L09ST:
9he de'ault 5alue 'or option3in is 9.
Dhen a time is &on5erted to 'ormat T, the returned 5alue is the input time 'or the &urrent date.
,I3B/$/)/11H#NH#1/C /11H#Na%/
,I3B/+/)/11H#Na%/)/$/C /11H#NH<</
,I3B/,/C 1#5M8N5##< /5 3aybe 5/
9he time &on5ersion &apabilit( o' the 98,> :81 6as introdu&ed 6ith the A/S8 standard.
TRACE()%e((ing*) - (ANSI)
eturns the &urrent 5alue o' the tra&e setting. 8' the string setting is spe&i'ied, it 6ill be used as the
ne6 setting 'or tra&ing, a'ter the old 5alue ha5e be re&orded 'or the return 5alue. /ote that the
setting is not an option, but ma( be an( o' the tra&e settings that &an be spe&i'ied to the &lause
,."$, e%&ept that the numeri& 5ariant is not allo6ed 6ith ,."$BC. 8n pra&ti&e, this &an be a
6ord, o' 6hi&h onl( the 'irst letter &ounts, optionall( pre&eded b( a Kuestion mar-.
,."$BC /$/ /5 3aybe 5/
,."$B/+/C /$/
,."$B/\/C /+/
TRANSLATE(%('ing )$)(a-"e#+(* )$)(a-"ein* )$.a42&a'***) - (ANSI)
"er'orms a translation on the &hara&ters in string. As a spe&ial &ase, i' neither tablein nor tableout is
spe&i'ied, it 6ill translate string 'rom lo6er &ase to upper &ase. /ote that this operation ma( depend
on the language &hosen, i' (our interpreter supports national &hara&ter sets.
96o translation tables might be spe&i'ied as the strings tablein and tableout. 8' one or both o' the
tables are spe&i'ied, ea&h &hara&ter in string that e%ists in tablein is translated to the &hara&ter in
tableout that o&&upies the same position as the &hara&ter did in tablein. 9he tablein de'aults to the
6hole &hara&ter set Fall 25?G in numeri& seKuen&e, 6hile tableout de'aults to an empt( set.
Chara&ters not in tablein are le't un&hanged.
8' tableout is larger than tablein, the e%tra entries are ignored. 8' it is smaller than tablein it is
padded 6ith padchar to the &orre&t length. -adchar de'aults to <spa&e>.
8' a &hara&ter o&&urs more than on&e in tablein, onl( the 'irst o&&urren&e 6ill matter.
,."+S;",B/@ooIar/C /@OOI"./
,."+S;",B/@ooIar/)/"I@O.ab(or/)/ab(or"I@O./C /(OOb"./
,."+S;",B/@ooIar/)/ab(or/C / /
,."+S;",B/@ooIar/)/ab(or/))/#/C /######/
TRIM(%('ing) - (AREXX)
emo5es trailing blan-s 'rom the string argument. A more portable option is to use the 9railing
option o' the S98" :81.
118
,.I3B/ abc /C / abc/
TRUNC(n+,-e' )$"eng(&*) - (ANSI)
eturns nu#ber trun&ated to the number o' de&imals spe&i'ied b( length. Length de'aults to <, that
is return an 6hole number 6ith no de&imal part.
9he de&imal point 6ill onl( be present i' the is a non$empt( de&imal part, i.e. length is non$Hero.
9he number 6ill al6a(s be returned in simple 'orm, ne5er e%ponential 'orm, no matter 6hat the
&urrent settings o' NUM%RI! might be. 8' length spe&i'ies more de&imals than nu#ber has, e%tra
Heros are appended. 8' length spe&i'ies less de&imals than nu#ber has, the number is trun&ated. /ote
that nu#ber is ne5er rounded, e%&ept 'or the rounding that might ta-e pla&e during normaliHation.
,.U+$B1#.78C /1#/
,.U+$B1#.99C /1#/
,.U+$B1#.78)8C /1#.78<</
,.U+$B1#.785M)#C /1#.78/
UNAME()#.(i#n*) - (REGINA)
eturns details about the &urrent plat'orm. 9his 'un&tion is basi&all( a 6rapper 'or the 0ni%
&ommand7 uname. 4alid 5alues 'or option are:
+A,
FAllG 9he de'ault. eturns a string 6ith the all 'ollo6ing option 5alues. >Kui5alent to:
0/A,>FPSPG 0/A,>FP/PG 0/A,>FPPG 0/A,>FP4PG 0/A,>FP,PG.
+S,
FS(stemG 9he name o' the operating s(stem.
+N,
F/odenameG 9he name o' the ma&hine.
+R,
FeleaseG 9he release o' the operating s(stem.
+!,
F4ersionG 9he 5ersion o' the operating s(stem.
+M,
F,a&hineG 9he ma&hinePs hard6are t(pe.
>%ample running 3inu% edhat ?.1 on Pboo\umP, Athalon M@
U+"3B/S/C ;inu&
U+"3B/+/C boo`u%
U+"3B/./C #.#.1#.-#<
U+"3B/V/C #1 3on Se6 #N 1<H8<H75 A, 1999
U+"3B/3/C iM8M
>%ample running Dindo6s /9 <.0 on P4,L/9P, 8ntel "entium
119
U+"3B/S/C JI++,
U+"3B/+/C V3_+,
U+"3B/./C <
U+"3B/V/C 8
U+"3B/3/C i58M
UNIXERROR(e''#'n#) - (REGINA)
9his 'un&tion returns the string asso&iated 6ith the errno error number that errorno spe&i'ies.
Dhen some 0/8A inter'a&e 'un&tion returns an error, it reall( is a re'eren&e to an error message
6hi&h &an be obtained through U+I-..O..
9his 'un&tion is \ust an inter'a&e to the s'rerrorBC 'un&tion &all in 0/8A, and the a&tual error
messages might di''er 6ith the operating s(stem.
9his 'un&tion is no6 obsolete, instead (ou should use:
..O.,-,B1<< = errorno)
UPPER(%('ing )$%(a'( )$"eng(& )$.a4***) D (AREXX5REGINA)
9ranslates the substring o' string that starts at start, and has the length length to upper &ase. Length
de'aults to the rest o' the string. Start must be a positi5e 6hole number, 6hile length &an be an(
non$negati5e 6hole number. 9he de'ault 5alue 'or start is 1 and 'or length is the length o' string.
8' a spe&i'i& lo&ale is set F5ia the $l s6it&hG, then the string is set to the &orre&t upper&ase 5alues
based on that lo&ale.
Dhile this :81 is an A>AA :81, it is not ne&essar( to ha5e O"98O/S A>AAL:81S set to use it.
9he optional arguments are egina e%tensions.
UPP.B/One @ine Aay/C /O+ @I+ A"*/
UPP.B/(re1/) # C /(.A/
UPP.B/(re1/) 1) 1 C /@re1/
UPP.B/(re1/)1) 1<) /5/ C /@.A555555/
USERID() - (REGINA)
eturns the name o' the &urrent user. A meaning'ul name 6ill onl( be returned on those plat'orms
that support multiple users, other6ise an empt( string is returned.
US.IABC /%arT/ /5 3aybe 5/
120
!ALUE(%3,-#" )$):a"+e*$ ).##"**) - (ANSI)
9his 'un&tion e%pe&ts as 'irst parameter string sy#bol, 6hi&h names an e%isting 5ariable. 9he result
returned 'rom the 'un&tion is the 5alue o' that 5ariable. 8' sy#bol does not name an e%isting
5ariable, the de'ault 5alue is returned, and the +OV";U &ondition is not raised. 8' sy#bol is not a
5alid s(mbol name, and this 'un&tion is used to a&&ess an normal Rexx 5ariable, an error o&&urs. :e
a6are o' the ;double$e%pansion; e''e&t, and Kuote the 'irst parameter i' ne&essar(.
8' the optional se&ond parameter is spe&i'ied, the 5ariable 6ill be set to that 5alue, a'ter the old
5alue has been e%tra&ted.
9he optional parameter pool might be spe&i'ied to sele&t a parti&ular pool o' 5ariables to sear&h 'or
sy#bol. 9he &ontents and 'ormat o' pool is implementation dependent. 9he de'ault is to sear&h in
the 5ariables at the &urrent pro&edural le5el in Rexx. Dhi&h pools that are a5ailable is
implementation dependent, but t(pi&all( one &an set 5ariables in appli&ation programs or in the
operating s(stem.
/ote that i' V";UBC is used to a&&ess 5ariable in pools outside the Rexx interpreter, the
reKuirements to 'ormat Fa 5alid s(mbolG 6ill not in general hold. 9here ma( be other reKuirements
instead, depending on the implementation and the s(stem. 2epending on the 5alidit( o' the name,
the 5alue, or 6hether the 5ariable &an be set or read, the V";UBC 'un&tion &an gi5e error
messages 6hen a&&essing 5ariables in pools other than the normal. Consult the implementation and
s(stem spe&i'i& do&umentation 'or more in'ormation.
8' it is used to a&&ess &ompound 5ariables inside the interpreter the tail part o' this 'un&tion &an ta-e
an( e%pression, e5en e%pression that are not normall( legal in Rexx s&ripts sour&e &ode.
9he 5alid 5alues o' pool in egina are one o' !92+>O90!9T, SOST!0,
OS2!92+>O90!9T, or pool &an be a number representing the &all le5el o' the &urrent
pro&edure, 6ith the 'irst le5el being 1. 8t is there'ore possible to get and set the 5alue o' a 5ariable in
a higher &all le5el pro&edure 'rom the &urrent one 6ithout the need to !)&OS! the 5ariable. 9his
and the &OOL+DFG 7+@ 6hi&h returns the &urrent &all le5el are egina e%tensions.
:( using this 'un&tion, it is possible to per'orm an e%tra le5el o' interpretation o' a 5ariable.
V";UB/@OO/C /bar/
V";UB/@OO/)/ne0/C /bar/
V";UB/@OO/C /ne0/
V";UB/US./)/roo'/)/S*S,3/C /gues'/ /5 I( S*S,3 e&is's 5/
V";UB/US./))/S*S,3/C /roo'/
!ERIFY(%('ing$ 'e0 )$)#.(i#n* )$%(a'(**) - (ANSI)
Dith onl( the 'irst t6o parameters, it 6ill return the position o' the 'irst &hara&ter in string that is
not also a &hara&ter in the string re&. 8' all &hara&ters in string are also in re&, it 6ill return <.
8' option is spe&i'ied, it &an be one o':
+N,
F/omat&hG 9he result 6ill be the position o' the 'irst &hara&ter in string that does not e%ist in
121
re&, or Hero i' all e%ist in re&. 9his is the de'ault option.
+M,
F,at&hG e5erses the sear&h, and returns the position o' the 'irst &hara&ter in string that
e%ists in re&. 8' none e%ists in re&, Hero is returned.
8' start F6hi&h must be a positi5e 6hole numberG is spe&i'ied, the sear&h 6ill start at that position in
string. 9he de'ault 5alue 'or start is 1.
V.I@*B/(oobar/)/bar(o/C /</
V.I@*B/(oobar/)/bar(o/)/3/C /1/
V.I@*B/(oobar/)/(ob/)/+/C /5/
V.I@*B/(oobar/)/bar(/)/+/)7C /7/
V.I@*B/(oobar/)/bar(/)/+/)8C /</
WORD(%('ing$ 8#'4n#) - (ANSI)
eturns the blan- delimited 6ord number "ordno 'rom the string string. 8' "ordno F6hi&h must be
a positi5e 6hole numberG re'ers to a non$e%isting 6ord, then a nullstring is returned. 9he result 6ill
be stripped o' an( blan-s.
JO.AB/,o be or no' 'o be/)7C /or/
JO.AB/,o be or no' 'o be/)8C /no'/
JO.AB/,o be or no' 'o be/)8C //
WORDINDEX(%('ing$ 8#'4n#) - (ANSI)
eturns the &hara&ter position o' the 'irst &hara&ter o' blan- delimited 6ord number "ordno in
string, 6hi&h is interpreted as a string o' blan- delimited 6ords. 8' nu#ber F6hi&h must be a
positi5e 6hole numberG re'ers to a 6ord that does not e%ist in string, then ( is returned.
JO.AI+A-B/,o be or no' 'o be/)7C /N/
JO.AI+A-B/,o be or no' 'o be/)8C /1</
JO.AI+A-B/,o be or no' 'o be/)8C /</
WORDLENGTH(%('ing$ 8#'4n#) - (ANSI)
eturns the number o' &hara&ters in blan- delimited 6ord number nu#ber in string. 8' nu#ber
F6hi&h must be a positi5e 6hole numberG re'ers to an non$e%istent 6ord, then < is returned. 9railing
or leading blan-s do not &ount 6hen &al&ulating the length.
JO.A;+>,9B/,o be or no' 'o be/)7C /#/
JO.A;+>,9B/,o be or no' 'o be/)8C /7/
JO.A;+>,9B/,o be or no' 'o be/)<C /</
WORDPOS(.&'a%e$ %('ing )$%(a'(*) - (ANSI)
eturns the 6ord number in string 6hi&h indi&ates at 6hi&h phrase begins, pro5ided that phrase is
a subphrase o' string. 8' not, < is returned to indi&ate that the phrase 6as not 'ound. A phrase di''ers
122
'rom a substring in one signi'i&ant 6a(7 a phrase is a set o' 6ords, separated b( an( number o'
blan-s.
1or instan&e, ;is a; is a subphrase o' ;,!is is a 6!rase;. /oti&e the di''erent amount o'
6hitespa&e bet6een ;is; and ;a;.
8' start is spe&i'ied, it sets the 6ord in string at 6hi&h the sear&h starts. 9he de'ault 5alue 'or start is
1.
JO.APOSB/or no'/)/'o be or no' 'o be/C /7/
JO.APOSB/no' 'o/)/'o be or no' 'o be/C /8/
JO.APOSB/'o be/)/'o be or no' 'o be/C /1/
JO.APOSB/'o be/)/'o be or no' 'o be/)7C /M/
WORDS(%('ing) - (ANSI)
eturns the number o' blan- delimited 6ords in the string.
JO.ASB/,o be or no' 'o be/C /M/
JO.ASB/9ello 0orl1/C /#/
JO.ASB//C /</
WRITECH(0i"e$ %('ing) - (AREXX)
Drites the string argument to the gi5en logi&al 'ile. 9he returned 5alue is the a&tual number o'
&hara&ters 6ritten.
J.I,$9B/ou'(ile/)/,es'ing/C /N/
WRITELN(0i"e$ %('ing) - (AREXX)
Drites the string argument to the gi5en logi&al 'ile 6ith a ;ne6line; appended. 9he returned 5alue is
the a&tual number o' &hara&ters 6ritten, in&luding theUne6lineV &hara&terFsG.
J.I,;+B/ou'(ile/)/,es'ing/C /8/ /5 Uni& 5/
J.I,;+B/ou'(ile/)/,es'ing/C /9/ /5 AOS 5/
XRANGE()%(a'(* )$en4*) - (ANSI)
eturns a string that &onsists o' all the &hara&ters 'rom start through end, in&lusi5e. 9he de'ault
5alue 'or &hara&ter start is /<</&, 6hile the de'ault 5alue 'or &hara&ter end is /((/&. Dithout
an( parameters, the 6hole &hara&ter set in ;alphabeti&; order is returned. /ote that the a&tual
representation o' the output 'rom -."+>BC depends on the &hara&ter set used b( (our &omputer.
8' the 5alue o' start is larger than the 5alue o' end, the output 6ill 6rap around 'rom /((/& to
/<</&. 8' start or end is not a string &ontaining e%a&tl( one &hara&ter, an error is reported.
123
-."+>B/"/)/W/C /"I$A@>9IW/
-."+>B/@$/&C /@$@A@@@/&
-."+>B)/<5/&C /<<<1<#<7<8<5/&
-."+>B/@A/&)/<8/&C /@A@@@<<<1<#<7<8/&
X/(&e<%('ing) - (ANSI)
9ranslate he$string to a binar( string. >a&h he%ade&imal digits in he$string 6ill be translated to 'our
binar( digits in the result. 9here 6ill be no blan-s in the result.
-#IB//C //
-#IB/8MM(M( 8#M1N#/C /<1<<<11<<11<1111<11<1111<1<<<<1<<11<<<<1
<111<<1</
-#IB/8M M( M(/C /<1<<<11<<11<1111<11<1111/
X/C(&e<%('ing) - (ANSI)
eturns the Fpa&-edG string representation o' he$string. 9he he$string 6ill be &on5erted b(te6ise,
and blan-s ma( optionall( be inserted into the he$string bet6een pairs or he%ade&imal digits, to
di5ide the number into groups and impro5e readabilit(. All groups must ha5e an e5en number o'
he%ade&imal digits, e%&ept the 'irst group. 8' the 'irst group has an odd number o' he%ade&imal
digits, it is padded 6ith an e%tra leading Hero be'ore &on5ersion.
-#$B//C //
-#$B/8MM(M( 8#M1N#/C /@ooIar/ /5 on "S$II %ac!ines 5/
-#$B/8M M( M(/C /@oo/ /5 on "S$II %ac!ines 5/
X/D(&e<%('ing )$"eng(&*) - (ANSI)
eturns a 6hole number that is the de&imal representation o' he$string. 8' length is spe&i'ied, then
he$string is interpreted as a t6oPs &omplement he%ade&imal number &onsisting o' the nu#ber
rightmost he%ade&imal numerals in he$string. 8' he$string is shorter than nu#ber, it is padded to the
le't 6ith </03> &hara&ters Fthat is: /<</&G.
8' length is not spe&i'ied, he$string 6ill al6a(s be interpreted as an unsigned number. >lse, it is
interpreted as an signed number, and the le'tmost bit in he$string de&ides the sign.
-#AB/<7 #8/C /N9#/
-#AB/<71</C /N88/
-#AB/((((/C /M5575/
-#AB/((((/)5C /M5575/
-#AB/((((/)8C /-1/
-#AB/((8</)7C /-1#8/
-#AB/1#785/)7C /87N/
124
3.3 Implementation specific documentation for Regina
3.3.1 $e*iations from the !tandard
1or those built$in 'un&tions 6here the last parameter &an be omitted, egina allo6s the last
&omma to be spe&i'ied, e5en 6hen the last parameter itsel' has been omitted.
9he error messages are slightl( rede'ined in t6o 6a(s. 1irstl(, some o' the ha5e a slightl( more
de'inite te%t, and se&ondl(, some ne6 error messages ha5e been de'ined.
9he en5ironments a5ailable are des&ribed in &hapter Inot (et 6rittenJ.
"arameter &alling
Stream 8#O
Conditions
/ational &hara&ter sets
:lan-s
Sta&-s ha5e the 'ollo6ing e%tra 'un&tionalit(: A.OPIU@BC, ASIU@BC and 3"_IU@BC and
IU@,*PBC.
andomFG
Sour&eline
9ime
Chara&ter sets
3.3.2 Interpreter Internal $ebugging /unctions
ALLOCATED()option*)
eturns the amount o' d(nami& storage allo&ated, measured in b(tes. 9his is the memor( allo&ated
b( the %allocBC &all, and does not &on&ern sta&- spa&e or stati& 5ariables.
As parameter it ma( ta-e an option, 6hi&h is one o' the single &hara&ters:
+A,
8t 6ill return a string that is the number o' b(tes o' d(nami& memor( &urrentl( allo&ated b(
the interpreter.
+",
eturns a number that is the number o' b(tes o' d(nami& memor( that is &urrentl( in use
Fi.e. not lea-edG.
125
+L,
eturns the number o' b(tes o' d(nami& memor( that is supposed to ha5e been lea-ed.
+S,
9his is the de'ault 5alue i' (ou do not spe&i'( an option. eturns a string that is ni&el(
'ormatted and &ontains all the other three options, 6ith labels. 9he 'ormat o' this string is:
;3e%oryH "lloca'e1:---) $urren':***) ;eaTe1:RRR;.
9his 'un&tion 6ill onl( be a5ailable i' the interpreter 6as &ompiled 6ith the ,."$33
prepro&essor ma&ro de'ined.
DUMPTREE()
"rints out the internal parse tree 'or the Rexx program &urrentl( being e%e&uted. 9his output is not
5er( interesting unless (ou ha5e good -no6ledge o' the interpreterPs internal stru&tures.
DUMP!ARS()
9his routine dumps a list o' all the 5ariables &urrentl( de'ined. 8t also gi5es a lot o' in'ormation
6hi&h is rather uninteresting 'or most users.
LISTLEA;ED()
3ist out all memor( that has lea-ed 'rom the interpreter. As a return 5alue, the total memor( that has
been listed is returned. 9here are se5eral option to this 'un&tion:
+N,
2o not list an(thing, \ust &al&ulate the memor(.
+A,
3ist all memor( allo&ations &urrentl( in use, not onl( that 6hi&h has been mar-ed as lea-ed.
+L,
Onl( list the memor( that has been mar-ed as lea-ed. 9his is the de'ault option.
TRACEAC;()
"rints out a tra&eba&-. 9his is the same routine 6hi&h is &alled 6hen the interpreter en&ounters an
error. /i&e 'or debugging, but not reall( use'ul 'or an( other purposes.
126
3.3.3 Rexx ;)! Interface /unctions
FEC!SI
FEC!TIME
FEC!UI
FEDIRECTORY
FEELEMENT
FEEXTRACT
FEFAO
FEFILE_ATTRIUTES
FEGETD!I
FEGET>PI
FEGETBUI
FEGETSYI
FEIDENTIFIER
FEINTEGER
FELENGTH
FELOCATE
FELOGICAL
FEMESSAGE
FEMODE
FEPARSE
FEPID
FEPRI!ILEGE
FEPROCESS
FESEARCH
127
FESETPR!
FESTRING
FETIME
FETRNLNM
FETYPE
FEUSER
128
3.4 Rexx<til for Regina
egina =.5 and abo5e pro5ides "atri&- ,&"heePs egutil e%ternal 'un&tion pa&-age as part o' the
egina distribution. 9he do&umentation 'or egutil is supplied in a separate do&ument.
129
4 Conditions
In this chapter, the Rexx concept o& 4conditions4 is described. !onditions allo" the progra##er to
handle abnor#al control &lo", and enable hi# to assign special pieces o& Rexx code to be e$ecuted
in case o& certain incidences.
In the &irst section the concept o& conditions is e$plained.
Then, there is a description o& ho" a standard condition in Rexx "ould "or, i& it e$isted.
In the third section, all the e$isting conditions in Rexx are presented, and the di&&erences
co#pared to the standard condition described in the previous section are listed.
The &ourth sections contains a collections o& rando# notes on the conditions in Rexx.
The last section describes di&&erences, e$tensions and peculiarities in Regina on the o& sub5ect
conditions, and the lists speci&ic behavior.
4.1 ?hat are Conditions
8n this se&tion, the &on&ept o' ;&onditions; are e%plained: Dhat the( are, ho6 the( 6or-, and 6hat
the( mean in programming.
4.1.1 ?hat $o ?e 'eed Conditions forB
4.1.2 Terminolog&
1irst, letPs loo- at the terminolog( used in this &hapter. 8' (ou donPt get a thorough understanding o'
these terms, (ou 6ill probabl( not understand mu&h o' 6hat is said in the rest o' this &hapter.
+I6-50e64:,
A situation, e%ternal or internal to the interpreter, 6hi&h it is reKuired to respond to in &ertain
pre$de'ined manners. 9he interpreter re&ogniHes in&idents o' se5eral di''erent t(pes. 9he
in&ident 6ill o'ten ha5e a &hara&ter o' ;suddenness;, and 6ill also be independent o' the
normal &ontrol 'lo6.
+9e64:,
2ata Stru&ture des&ribing one in&ident, used as a des&riptor to the in&ident itsel'.
+"o60545o6:,
/ames the Rexx &on&ept that is eKui5alent to the in&ident.
+Ra5(e a "o60545o6:,
9he a&tion o' trans'orming the in'ormation about an in&ident into an e5ent. 9his is done
a'ter the interpreter senses the &ondition. Also in&ludes de&iding 6hether to ignore or
produ&e an e5ent.
130
+'a60le a "o60545o6:,
9he a&t o' e%e&uting some pre$de'ined a&tions as a response to the e5ent generated 6hen a
&ondition 6as raised.
+("o60545o6) Tra%:,
2ata Stru&ture &ontaining in'ormation about ho6 to handle a &ondition.
+(Tra%) S4a4e:,
"art o' the &ondition trap.
+("o60545o6) 'a60ler:,
"art o' the &ondition trap, 6hi&h points to a pie&e o' Rexx &ode 6hi&h is to be used to
handle the &ondition.
+(Tra%) Me4ho0:,
"art o' the &ondition trap, 6hi&h de'ined ho6 the &ondition handler is to be in5o-ed to
handle the &ondition.
+Tr5gger a Tra%:,
9he a&tion o' in5o-ing a &ondition handler b( the method spe&i'ied b( the trap method, in
order to handle a &ondition.
+Tra% a "o60545o6:,
Short o' trigger a trap 'or a parti&ular &ondition.
+"3rre64 Tra%%e0 "o60545o6:,
9he &ondition &urrentl( being handled. 9his is the same as the most re&ent trapped &ondition
on this or higher pro&edure le5el.
+(!e6056g) 9e64 ;3e3e:,
2ata Stru&ture storing Hero or more e5ents in a spe&i'i& order. 9here are onl( one e5ent
Kueue. 9he e5ent Kueue &ontains e5ents o' all &ondition t(pes, 6hi&h ha5e been raised, but
not (et handled.
+Defa3l41A-45o6:,
9he pre$de'ined de'ault 6a( o' handling a &ondition, ta-en i' the trap state 'or the &ondition
raised is O@@.
+Dela)1A-45o6:,
9he pre$de'ined de'ault a&tion ta-en 6hen a &ondition is raised, and the trap state is A;"*.
4.2 The )&thical !tandard Condition
Rexx 3anguage 3e5el <.00 has si% di''erent &onditions, and Rexx 3anguage 3e5el 5.00 has se5en.
!o6e5er, ea&h o' these is a spe&ial &ase o' a m(thi&al, non$e%isting, standard &ondition. 8n order to
better understand the real &onditions, 6e start b( e%plaining ho6 a standard &ondition 6or-.
8n the e%amples belo6, 6e 6ill &all our non$e%isting standard &ondition 3*,9. /ote that these
e%amples 6ill not be e%e&utable on an( Rexx implementation.
4.2.1 Information Regarding Conditions Cdata structuresD
9here are mainl( 'i5e &on&eptual data stru&tures in5ol5ed in &onditions.
+9e64 <3e3e.,
9here is one interpreter$6ide Kueue o' pending &onditions. aising a &ondition is identi&al to
adding in'ormation about the &ondition to this Kueue F181OG. 9he order o' the Kueue is the
same order in 6hi&h the &onditions are to be handled.
>5er( entr( in the Kueue o' pending &onditions &ontains some in'ormation about the e5ent:
the line number o' the Rexx s&ript 6hen the &ondition 6as raised, a des&ripti5e te%t and the
131
&ondition t(pe.
+Defa3l41A-45o6.,
9o ea&h, there e%ists in'ormation about the de'ault$a&tion to ta-e i' this &ondition is raised
but the trap is in state O@@. 9his is &alled the ;de'ault$a&tion;. 9he standard de'ault$a&tion
is to ignore the &ondition, 6hile some &onditions ma( abort the e%e&ution.
+Dela)1A-45o6.,
>a&h &ondition 6ill also ha5e dela($a&tion, 6hi&h tells 6hat to do i' the &ondition is raised
6hen &ondition trap is in state A;"*. 9he standard dela($a&tion is to Kueue the &ondition
in the Kueue o' pending &onditions, 6hile some &onditions ma( ignore it.
+"o60545o6 4ra%(.,
1or ea&h &ondition there is a trap 6hi&h &ontains three pie&es o' status in'ormation: the state7
the handler7 and the method. 9he state &an be O+, O@@ or A;"*.
9he handler names the Rexx label in the start o' the Rexx &ode to handle the e5ent. 9he
method &an be either SI>+"; or $";;, and denotes the method in 6hi&h the &ondition is to
be handled. 8' the state is O@@, then neither handler nor method is de'ined.
+"3rre64 Tra%%e0 "o60545o6.,
9his is the most re&entl( handled &ondition, and is set 6hene5er a trap is triggered. 8t
&ontains in'ormation about method, 6hi&h &ondition, and a &onte%t$dependent des&ription.
8n 'a&t, the in'ormation in the &urrent trapped &ondition is the same in'ormation that 6as
originall( put into the pending e5ent Kueue.
/ote that the e5ent Kueue is a data stru&ture &onne&ted to the interpreter itsel'. Cou operate on the
same e5ent Kueue, independent o' subroutines, e5en e%ternal ones. On the other hand, the &ondition
traps and the &urrent trapped &ondition are data stru&tures &onne&ted to ea&h single routine. Dhen a
ne6 routine is &alled, it 6ill get its o6n &ondition traps and a &urrent trapped &ondition. 1or internal
routines, the initial 5alues 6ill be the same 5alues as those o' the &aller. 1or e%ternal routines, the
5alues are the de'aults.
9he initial 5alue 'or the e5ent Kueue is to be empt(. 9he de'ault$a&tion and the dela($a&tion are
stati& in'ormation, and 6ill al6a(s retain their 5alues during e%e&ution. 9he initial 5alues 'or the
&ondition traps are that the( are all in state O@@. 9he initial 5alue 'or the &urrent trapped &ondition
is that all in'ormation is set to the nullstring to signaliHe that no &ondition is &urrentl( being trapped.
4.2.2 6o to !et up a Condition Trap
!o6 do (ou set the in'ormation in a &ondition trapS Cou do it 6ith a SI>+"; or $";; &lause, 6ith
the O+ or O@@ sub-e(6ord. emember that a &ondition trap &ontain three pie&es o' in'ormationS
!ere are the rules 'or ho6 to set them:
9o set the trap method, use either SI>+"; or $";; as -e(6ord.
9o set state to O+ or O@@, use the appropriate sub-e(6ord in the &lause. /ote that there is no
&lause or 'un&tion in Rexx, &apable o' setting the state o' a trap to A;"*.
9o set the &ondition handler, append the term ;+"3 handler; to the &ommand. /ote that
this term is onl( legal i' (ou are setting the state to O+7 (ou &an not spe&i'( a handler 6hen
setting the state to O@@.
9he trap is said to be ;enabled; 6hen the state is either O+ or A;"*, and ;disabled; 6hen the state
132
is O@@. /ote that neither the e5ent Kueue, nor the &urrent trapped &ondition &an be set e%pli&itl( b(
Rexx &lauses. 9he( &an onl( be set as a result o' in&idents, 6hen raising and trapping &onditions.
8t sounds 5er( theoreti&al, doesnPt itS 3oo- at the 'ollo6ing e%amples, 6hi&h sets the trap 3*,9:
/5 1 5/ SI>+"; O+ 3*,9 +"3 ,."P_I,
/5 # 5/ SI>+"; O@@ 3*,9
/5 7 5/ $";; O+ 3*,9 +"3 3*,9_,."P
/5 8 5/ $";; O+ 3*,9
/5 5 5/ $";; O@@ 3*,9
3ine 1 sets state to O+, method to SI>+"; and handler to ,."P_I,. 3ine 2 sets state to O@@,
handler and method be&omes unde'ined. 3ine = sets state to O+, method to $";;, and handler to
3*,9_,."P. 3ine < sets state to O+, method to $";; and handler to 3*,9 Fthe de'aultG. 3ine 5
sets state to O@@, handler and method be&ome unde'ined.
Dh( should method and handler be&ome unde'ined 6hen the trap in state O@@S 1or t6o reasons:
'irstl(, these 5alues are not used 6hen the trap is in state O@@7 and se&ondl(, 6hen (ou set the trap
to state O+, the( are rede'ined. So it reall( does not matter 6hat the( are in state O@@.
Dhat happens to this in'ormation 6hen (ou &all a subroutineS All in'ormation about traps are
inherited b( the subroutine, pro5ided that it is an internal routine. >%ternal routines do not inherit
an( in'ormation about traps, but use the de'ault 5alues. /ote that the inheritan&e is done b(
&op(ing, so an( &hanges done in the subroutine Finternal or e%ternalG, 6ill onl( ha5e e''e&t until the
routine returns.
4.2.3 6o to Raise a Condition
!o6 do (ou raise a &onditionS Dell, there are reall( no e%pli&it 6a( in Rexx to do that. 9he
&onditions are raised 6hen an in&ident o&&urs. Dhat sort o' situations that is, depends on the
&onte%t. 9here are in general three t(pes o' in&idents, &lassi'ied b( the origin o' the e5ent:
8nternal origin. 9he in&ident is onl( dependent on the beha5iour o' the Rexx s&ript. 9he
S*+,"- &ondition is o' this t(pe.
>%ternal origin. 9he Rexx s&ript and the interpreter has reall( no &ontrol o5er 6hen this
in&ident. 8t happens &ompletel( independent o' the &ontrol o' the Rexx s&ript or interpreter. 9he
9";, &ondition is o' this t(pe.
,i%ed origin. 9he in&ident is o' e%ternal origin, but the situation that &reated the in&ident, 6as
an a&tion b( the Rexx s&ript or the interpreter. 9he ..O. &ondition is o' this t(pe: the in&ident
is a &ommand returning error, but it &an onl( o&&ur 6hen the interpreter is e%e&uting &ommands.
1or &onditions trapped b( method $";;, standard Rexx reKuires an implementation to at least
&he&- 'or in&idents and raise &ondition at &lause boundaries. F:ut it is allo6ed to do so else6here
too7 although the a&tual triggering must onl( be per'ormed at &lause boundaries.G ConseKuentl(,
(ou must be prepared that in some implementations, &onditions trappable b( method $";; might
onl( be raised Fand the trap triggeredG at &lause boundaries, e5en i' the( are &urrentl( trapped b(
method SI>+";.
133
9he se5en standard &onditions 6ill be raised as result o' 5arious situations, read the se&tion
des&ribing ea&h one o' them 'or more in'ormation.
=--------= =----------= /-----O =--------=
DInci1en'D D$on1i'ion D / ,ra6 O O(( DAe(aul' D
D occurs D -Q Dis raise1 D -Q O S'a'e / --Q D ac'ion D
=--------= =----------= O-----/ =--------=
/ D
/On DAelay
/ D
/ v
=--------=/ /---------O
=------=
D Uueue D *es /Aelay"c'ionO +o D
IgnoreD
Dan even'D S-- Ois Vueue\ / --Q D
even'D
=--------= O---------/
=------=
D
v
/-------O
/3e'!o1 isO
O $";;\ /
O-------/ O
/ O
/+o *esO
/ O /--------
-O
/ O /
O
=-----------= =-----------= O Aecision
/
D Se' s'a'e D D Se' s'a'e
D O---------/
D O@@ D D A;"* D
=-----------= =-----------=
=-----------=
D ,rigger D D D D
D
D 'ra6 D D .e'urn D D "c'ion
D
=-----------= =-----------=
=-----------=
The triggering 1 a c1nditi1n
Dhen an in&ident o&&urs and the &ondition is raised, the interpreter 6ill &he&- the state o' the
&ondition trap 'or that parti&ular &ondition at the &urrent pro&edure le5el.
134
8' the trap state is O@@, the de'ault$a&tion o' the &ondition is ta-en immediatel(. 9he ;standard;
de'ault$a&tion is to ignore the &ondition.
8' the trap state is A;"*, the a&tion 6ill depend on the dela($a&tion o' that &ondition. 9he
standard dela($a&tion is to ignore, then nothing 'urther is done. 8' the dela($a&tion is to Kueue,
the interpreter &ontinues as i' the state 6as O+.
8' the state o' the trap is O+, an e5ent is generated 6hi&h des&ribes the in&ident, and it is Kueued
in the pending e5ent Kueue. 9he 'urther a&tion 6ill depend on the method o' trapping.
8' the method is $";;, the state o' the trap 6ill be set to A;"*. 9hen the normal e%e&ution is
resumed. 9he idea is that the interpreter 6ill &he&- the e5ent Kueue later Fat a &lause boundar(G,
and trigger the appropriate trap, i' it 'inds an( e5ents in the e5ent Kueue.
>lse, i' method o' trapping is SI>+";, then the a&tion ta-en is this: 1irst set the trap to state
O@@, then terminate &lause the interpreter 6as e%e&uting at this pro&edure le5el. 9hen it
e%pli&itl( trigger the &ondition trap.
9his pro&ess has be sho6n in the 'igure abo5e. 8t sho6s ho6 an in&ident ma-es the interpreter raise
a &ondition, and that the state o' the &ondition trap determines 6hat to do ne%t. 9he possible
out&omes o' this pro&ess are: to ta-e the de'ault$a&tion7 to ignore i' dela($a&tion is not to Kueue7 to
\ust Kueue and the &ontinue e%e&ution7 or to Kueue and trigger the trap.
4.2.4 6o to Trigger a Condition Trap
Dhat are the situations 6here a &ondition trap might be triggeredS 8t depends on the method
&urrentl( set in the &ondition trap.
8' the method is SI>+";, then the interpreter 6ill e%pli&itl( trigger the rele5ant trap 6hen it has
raised the &ondition a'ter ha5ing sensed the in&ident. /ote that onl( the parti&ular trap in Kuestion
6ill be triggered in this &ase7 other traps 6ill not be triggered, e5en i' the pending e5ent Kueue is
non$empt(.
8n addition, the interpreter 6ill at ea&h &lause boundar( &he&- 'or an( pending e5ents in the e5ent
Kueue. 8' the Kueue is non$empt(, the interpreter 6ill not immediatel( e%e&ute the ne%t normal
statement, but it 6ill handle the &onditionFsG 'irst. 9his pro&edure is repeated until there are no more
e5ents Kueued. Onl( then 6ill the interpreter ad5an&e to e%e&ute the ne%t normal statement.
/ote that the Rexx standard does not reKuire the pending e5ents to be handled in an( parti&ular
order, although the model sho6n in this do&umentation it 6ill be in the order in 6hi&h the
&onditions 6ere raised. ConseKuentl(, i' one &lause generates se5eral e5ents that raise &onditions
be'ore or at the ne%t &lause boundar(, and these &onditions are trapped b( method $";;. 9hen, the
order on 6hi&h the 5arious traps are triggered is implementations$dependent. :ut the order in
6hi&h the di''erent instan&es o' the same &ondition is handled, is the same as the order o' the
&ondition indi&ator Kueue.
4.2.2 Trapping b& )ethod SIGNAL
Assume that a &ondition is being trapped b( method SI>+";, that the state is O+ and the handler is
3*,9_,."P. 9he 'ollo6ing Rexx &lause 6ill setup the trap &orre&tl(:
135
SI>+"; O+ 3*,9 +"3 3*,9_,."P
/o6, suppose the 3*,9 in&ident o&&urs. 9he interpreter 6ill sense it, Kueue an e5ent, set the trap
state to O@@ and then e%pli&itl( trigger the trap, sin&e the method is SI>+";. Dhat happens 6hen
the trap is triggeredS
8t &olle&ts the 'irst e5ent 'rom the Kueue o' pending e5ents. 9he in'ormation is remo5ed 'rom the
Kueue.
9he &urrent trapped &ondition is set to the in'ormation remo5ed 'rom the pending e5ent Kueue.
9hen, the interpreter simulates a SI>+"; &lause to the label named b( trap handler o' the trap
'or the &ondition in Kuestion.
As all SI>+"; &lauses, this 6ill ha5e the side$e''e&ts o' setting the SI>; spe&ial 5ariable, and
terminating all a&ti5e loops at the &urrent pro&edure le5el.
9hatPs it 'or method SI>+";. 8' (ou 6ant to &ontinue trapping &ondition 3*,9, (ou ha5e to
e%e&ute a ne6 SI>+"; O+ 3*,9 &lause to set the state o' the trap to O+. :ut no matter ho6
Kui&- (ou reset the trap, (ou 6ill al6a(s ha5e a short period 6here it is in state O@@. 9his means
that (ou &an not in general use the method SI>+"; i' (ou reall( 6ant to be sure that (ou donPt
loose an( 3*,9 e5ents, unless (ou ha5e some &ontrol o5er 6hen 3*,9 &ondition ma( arise.
Also note that sin&e the statement being e%e&uted is terminated7 all a&ti5e loops on the &urrent
pro&edure le5el are terminated7 and the onl( indi&ation 6here the error o&&urred is the line number
Fthe line ma( &ontain se5eral &lausesG, then it is in general impossible to pi&- up the normal
e%e&ution a'ter a &ondition trapped b( SI>+";. 9here'ore, this method is best suited 'or a
;gra&e'ul death; t(pe o' traps. 8' the trap is triggered, (ou 6ant to terminate 6hat (ou 6ere doing,
and pi&- up the e%e&ution at an earlier stage, e.g. the pre5ious pro&edure le5el.
4.2.3 Trapping b& )ethod CALL
Assume that the &ondition 3*,9 is being trapped b( method $";;, that the state is O+ and the
handler is 3*,9_9"+A;..
9he 'ollo6ing Rexx &lause 6ill setup the trap &orre&tl(:
$";; O+ 3*,9 +"3 3*,9_9"+A;.
/o6, suppose that the 3*,9 in&ident o&&urs. Dhen the interpreter senses that, it 6ill raise the
3*,9 &ondition. Sin&e the trap state is O+ and the trap method is $";;, it 6ill &reate an e5ent and
Kueue it in the pending e5ent Kueue and set the trap state to A;"*. 9hen it &ontinues the normal
e%e&ution. 9he trap is not triggered be'ore the interpreter en&ounters the ne%t &lause boundar(. Dhat
happens thenS
At the e5er( &lause boundaries, the interpreter &he&- 'or an( pending e5ents in the e5ent Kueue.
8' one is 'ound, it is handled. 9his a&tion is done repeatedl(, until the e5ent Kueue is empt(.
8t 6ill simulate a normal 'un&tion &all to the label named b( the trap handler. As 6ith an( $";;
136
&lause, this 6ill set the spe&ial 5ariable SI>; to the line o' 'rom 6hi&h the &all 6as made. 9his
is done prior to the &all. /ote that this is the &urrent line at the time 6hen the &ondition 6as
raised, not 6hen it 6as triggered. All other a&tions normall( per'ormed 6hen &alling a
subroutine are done. /ote that the arguments to the subroutine are set to empt(.
!o6e5er, \ust be'ore e%e&ution o' the routine starts, it 6ill remo5e the 'irst e5ent in the pending
e5ent Kueue, the in'ormation is instead put into the &urrent trapped &ondition. /ote that the
&urrent trapped &ondition is in'ormation that is sa5ed a&ross subroutine &alls. 8t is set ater the
&ondition handler is &alled, and 6ill be lo&al to the &ondition handler Fand 'un&tions &alled b(
the &ondition handlerG. 9o the ;&aller; Fi.e. the pro&edure le5el a&ti5e 6hen the trap 6as
triggeredG, it 6ill seem as i' the &urrent trapped &ondition 6as ne5er &hanged.
9hen the &ondition handler 'inishes e%e&ution, and returns b( e%e&uting the .,U.+ &lause.
An( e%pression gi5en as argument to .,U.+ 6ill be ignored, i.e. the spe&ial 5ariable .SU;,
6ill not be set upon return 'rom a &ondition handler.
At the return 'rom the &ondition handler, the &urrent trapped &ondition and the setup o' all traps
are restored, as 6ith a normal return 'rom subroutine. As a spe&ial &ase, the state o' the trap \ust
triggered, 6ill not be put ba&- into A;"* state, but is set to state O+.
A'ter6ard Fand be'ore the ne%t normal &lauseG, the interpreter 6ill again &he&- 'or more e5ents
in the e5ent Kueue, and it 6ill not &ontinue on the Rexx s&ript be'ore the Kueue is empt(.
2uring the triggering o' a trap b( method $";; at a &lause boundar(, the state o' the trap is not
normall( &hanged, it 6ill &ontinue to be A;"*, as 6as set 6hen the &ondition 6as raised. 8t 6ill
&ontinue to be in state A;"* until return 'rom the &ondition handler, at 6hi&h the state o' the trap
in the &aller 6ill be &hanged to O+. 8', during the e%e&ution o' the &ondition trap, the state o' the
&ondition being trapped is set, that &hange 6ill onl( last until the return 'rom the &ondition handler.
Sin&e ne6 &onditions are generall( dela(ed 6hen an &ondition handler is e%e&uting, ne6 &onditions
are Kueued up 'or e%e&ution. 8' the trap state is &hanged to O+, the pending e5ent Kueue 6ill be
pro&essed as named at the ne%t &lause boundar(. 8' the state is &hanged to O@@, the de'ault a&tion o'
the &onditions 6ill be ta-en at the ne%t &lause boundar(.
4.2.5 The Current Trapped Condition
9he interpreter maintains a data stru&ture &alled the &urrent trapped &ondition. 8t &ontains
in'ormation relating the most re&ent &ondition trapped on this or higher pro&edure le5el. 9he &urrent
trapped &ondition is normall( inherited b( subroutines and 'un&tions, and restored a'ter return 'rom
these.
Dhen trapped b( method SI>+"; the &urrent trapped &ondition o' the &urrent pro&edure le5el
is set to in'ormation des&ribing the &ondition trapped.
Dhen trapped b( method $";;, the &urrent trapped &ondition at the pro&edure le5el 6hi&h the
trap o&&urred at, is not &hanged. 8nstead, the &urrent trapped &ondition in the &ondition handler
is set to in'ormation des&ribing the &ondition.
9he in'ormation stored in the &urrent trapped &ondition &an be retrie5ed b( the built$in 'un&tion
137
$O+AI,IO+BC. 9he s(nta% 'ormat o' this 'un&tion is:
$O+AI,IO+BoptionC
6here option is an option string o' 6hi&h onl( the 'irst &hara&ter matters. 9he 5alid options are:
$on1i'ion na%e, Aescri6'ion, Ins'ruc'ion and S'a'e. 9hese 6ill return: the name o'
the &urrent trapped &ondition7 the des&ripti5e te%t7 the method7 and the &urrent state o' the &ondition,
respe&ti5el(. 9he de'ault option is Ins'ruc'ion. See the do&umentation on the built$in 'un&tions.
See also the des&ription o' ea&h &ondition belo6.
/ote that the S'a'e option do not return the state at the time 6hen the &ondition 6as raised or the
trap 6as triggered. 8t returns the &urrent state o' the trap, and ma( &hange during e%e&ution. 9he
other in'ormation in the &urrent trapped &ondition ma( onl( &hange 6hen a ne6 &ondition is
trapped at return 'rom subroutines.
4.3 The Real Conditions
De ha5e no6 des&ribed ho6 the standard &ondition and &ondition trap 6or-s in Rexx. 3etPs loo- at
the se5en &onditions de'ined 6hi&h do e%ist. /ote that none o' these beha5es e%a&tl( as the
standard &ondition.
4.3.1 The SYNTAX condition
9he S*+,"- &ondition is o' internal origin, and is raised 6hen an( s(nta% or runtime error is
dis&o5ered b( the Rexx interpreter. 8t might be an( o' the situations that 6ould normall( lead to
the abortion o' the program and the report o' a Rexx error message, e%&ept error message number <
F-rogra# interruptedG, 6hi&h is handled b( the 9";, &ondition.
9here are se5eral di''eren&es bet6een this &ondition and the standard &ondition:
8t is not possible to trap this &ondition 6ith the method $";;, onl( method SI>+";. 9he
reason 'or this is partl( that method $";; tries to &ontinue e%e&ution until ne%t boundar( be'ore
triggering the trap. 9hat might not be possible 6ith s(nta% or runtime errors.
Dhen this &ondition is trapped, the spe&ial 5ariable .$ is set to the Rexx error number o' the
s(nta% or runtime error that &aused the &ondition. 9his is done \ust be'ore the setting o' the
spe&ial 5ariable SI>;.
9he de'ault a&tion o' this &ondition i' the trap state is O@@, is to abort the program 6ith a
tra&eba&- and error message.
9here is not dela($a&tion 'or &ondition S*+,"-, sin&e it &an not be trapped b( method $";;,
and &onseKuentl( ne5er &an get into state A;"*.
9he des&ripti5e te%t returned b( $O+AI,IO+BC 6hen &alled 6ith the Aescri6'ion option 'or
&ondition S*+,"-, is implementation dependent, and ma( also be a nullstring. Consult the
implementation$spe&i'i& do&umentation 'or more in'ormation.
138
4.3.2 The HALT condition
9he 9";, &ondition o' e%ternal origin, 6hi&h is raised as a result o' an a&tion 'rom the user,
normall( a &ombination o' -e(s 6hi&h tries to abort the program. Dhi&h &ombination o' -e(s 6ill
5ar( bet6een operating s(stems. Some s(stems might also simulate this e5ent b( other means than
-e( &ombinations. 8n general TC and T$:rea- -e( &ombinations 6ill generate this &ondition.
9he di''eren&es bet6een 9";, and the standard &ondition are:
9he de'ault$a&tion 'or the 9";, &ondition is to abort e%e&ution, as though a Rexx runtime error
number < F-rogra# interruptedG had been reported. :ut note that S*+,"- 6ill ne5er be raised
i' 9";, is not trapped.
9he dela($a&tion o' this &ondition is to ignore, not Kueue.
9he standard allo6s the interpreter to limit the sear&h 'or situations that 6ould set the 9";,
&ondition, to &lause boundaries. As a result, the response time 'rom pressing the -e( &ombination to
a&tuall( raising the &ondition or triggering the trap ma( 5ar(, e5en i' 9";, is trapped b( method
SI>+";. 8' a &lause 'or some reason has blo&-ed e%e&ution, and ne5er 'inish, (ou ma( not be able
to brea- the program.
&ondition 9";,, is implementation dependent, and ma( also be a nullstring. 8n general, it 6ill
des&ribe the 6a( in 6hi&h the interpreter 6as attempted halted, in parti&ular i' there are more than
one 6a( to do raise a 9";, &ondition. Consult the implementation do&umentation 'or more
in'ormation.
4.3.3 The ERROR condition
9he ..O. is a &ondition o' mi%ed origin, it is raised 6hen a &ommand returns a return 5alue
6hi&h indi&ates error during e%e&ution. O'ten, &ommands return a numeri& 5alue, and a parti&ular
5alue is &onsidered to mean su&&ess. 9hen, other 5alues might raise the ..O. &ondition.
2i''eren&es bet6een ..O. and the standard &ondition:
9he dela( a&tion o' ..O. is to ignore, not to Kueue.
9he spe&ial 5ariable .$ is al6a(s set be'ore this &ondition is raised. So e5en i' it is trapped b(
method SI>+";, (ou &an rel( on .$ to be set to the return 5alue o' the &ommand.
0n'ortunatel(, there is no uni5ersal standard on return 5alues. As stated, the( are o'ten numeri&, but
some operating s(stem use non$numeri& return 5alues. 1or those 6hi&h do use numeri& 5alues, there
are no standard telling 6hi&h 5alues and ranges are &onsidered errors and 6hi&h are &onsidered
su&&ess. 8n 'a&t, the interpretation o' the 5alue might di''er bet6een &ommands 6ithin the same
operating s(stem.
9here'ore, it is up to the Rexx implementation to de'ine 6hi&h 5alues and ranges that are
&onsidered errors. Cou must e%pe&t that this in'ormation &an di''er bet6een implementations as 6ell
as bet6een di''erent en5ironments 6ithin one implementation.
139
&ondition ..O., is the &ommand 6hi&h &aused the error. /ote that this is the &ommand as the
en5ironment sa6 it, not as it 6as entered in the Rexx s&ript sour&e &ode.
4.3.4 The FAILURE condition
9he @"I;U. is a &ondition o' mi%ed origin, it is raised 6hen a &ommand returns a return 5alue
6hi&h indi&ates 'ailure during e%e&ution, abnormal termination, or 6hen it 6as impossible to
e%e&ute a &ommand. 8t is a subset o' the ..O. &ondition, and i' it is in state O@@, then the ..O.
&ondition 6ill be raised instead. :ut note that an implementation is 'ree to &onsider all return &odes
'rom &ommands as ..O.s, and none as @"I;U.S. 8n that &ase, the onl( situation 6here a
@"I;U. 6ould o&&ur, is 6hen it is impossible to e%e&ute a &ommand.
2i''eren&es bet6een @"I;U. and the standard &ondition:
9he dela( a&tion o' @"I;U. is to ignore, not to Kueue.
9he spe&ial 5ariable .$ is al6a(s set be'ore this &ondition is raised. So e5en i' it is trapped b(
method SI>+";, (ou &an rel( on .$ to be set to the return 5alue o' the &ommand, or the return
&ode that signaliHe that the &ommand 6as impossible to e%e&ute.
As 'or ..O., there is no standard the de'ines 6hi&h return 5alues are 'ailures and 6hi&h are
errors. Consult the s(stem and implementation independent do&umentation 'or more in'ormation.
&ondition @"I;U., is the &ommand 6hi&h &aused the error. /ote that this is the &ommand as the
en5ironment sa6 it, not as it 6as entered in the Rexx s&ript sour&e &ode.
4.3.2 The NO!ALUE condition
9he +OV";U &ondition is o' internal origin. 8t is raised in some &ir&umstan&es i' the 5alue o' an
unset s(mbol F6hi&h is not a &onstant s(mbolG is reKuested. /ormall(, this 6ould return the de'ault
5alue o' the s(mbol. 8t is &onsidered bad programming pra&ti&e not to initialiHe 5ariables, and
setting the +OV";U &ondition is one method o' 'inding the parts o' (our program that uses this
programming pra&ti&e.
/ote ho6e5er, there are onl( three instan&es 6here this &ondition ma( be raised: that is 6hen the
5alue o' an unset Fnon$&onstantG s(mbol is used reKuested: in an e%pression7 a'ter the V".
sub-e(6ord in a P".S &lause7 and as an indire&t re'eren&e in either a template, a A.OP or a
P.O$AU. &lause. 8n parti&ular, this &ondition is not raised i' the V";UBC or S*3IO;BC built$
in 'un&tions re'er to an unset s(mbol.
2i''eren&es bet6een +OV";U and the standard &ondition are:
8t ma( onl( be trapped b( method SI>+";, ne5er method $";;. 9his reKuirement might seem
some6hat strange, but the idea is that sin&e an implementation is onl( 'or&ed to &he&- 'or
&onditions trapped b( method $";; at &lause boundaries, in&iden&es that ma( o&&ur at an(
point 6ithin &lauses Fli-e +OV";UG &an onl( be trapped b( method SI>+";. F!o6e5er,
&ondition +O,."A* &an o&&ur 6ithin a &lause, and ma( be trapped b( method $";; so this
does not seem to be absolute &onsistent.G
140
9here is not dela($a&tion 'or &ondition +OV";U, sin&e it &an not be trapped b( method $";;,
9he des&ripti5e te%t returned b( &alling $O+AI,IO+BC 6ith the Aescri6'ion option, is the
deri5ed Fi.e. tail has be substituted i' possibleG name o' the 5ariable that &aused the &ondition to be
raised.
4.3.3 The NOTREADY condition
9he &ondition +O,."A* is a &ondition o' mi%ed origin. 8t is raised as a result o' problems 6ith
stream 8#O. >%a&tl( 6hat &auses it, ma( 5ar( bet6een implementations, but some o' the more
probable &auses are: 6aiting 'or more 8#O on transient streams7 a&&ess to streams not allo6ed7 8#O
operation 6ould blo&- i' attempted7 et&. See the &hapter7 Stream +np#t and O#tp#t 'or more
in'ormation.
2i''eren&es bet6een +O,."A* and the standard &ondition are:
8t 6ill be ignored rather than Kueued i' &ondition trap is in state A;"*.
9his &ondition di''ers 'rom the rest in that it &an be raised during e%e&ution o' a &lause, but &an
still be trapped b( method $";;.
&ondition +O,."A*, is the name o' the stream 6hi&h &aused the problem. 9his is probabl( the
same string that (ou used as the 'irst parameter to the 'un&tions that operates on stream 8#O. 1or the
de'ault streams Fde'ault input and output streamG, the string returned b( $O+AI,IO+BC 6ill be the
nullstring.
/ote that i' the +O,."A* trap is in state A;"*, then all 8#O 'or 'iles 6hi&h has tried to raise
+O,."A* 6ithin the &urrent &lause 6ill be simulated as i' operation had su&&eeded.
4.3.5 The #-!T$I,IT! condition
9he &ondition ;OS,AI>I,S 6as introdu&ed in 3anguage 3e5el 5.00. 8t is raised as a result o' an(
arithmeti& operation 6hi&h results in the loss o' an( digits. i.e. 8' the number o' signi'i&ant digits in
the result o' an arithmeti& operation 6ould e%&eed the &urrentl( de'ined number o' digits 5ia
/0,>8C 28.89S, then the ;OS,AI>I,S &ondition is raised.
2i''eren&es bet6een ;OS,AI>I,S and the standard &ondition are:
8t ma( onl( be trapped b( method SI>+";, ne5er method $";;.
9here is not dela($a&tion 'or &ondition +OV";U, sin&e it &an not be trapped b( method $";;,
&ondition +O,."A*, is the name o' the stream 6hi&h &aused the problem. 9his is probabl( the
same string that (ou used as the 'irst parameter to the 'un&tions that operates on stream 8#O. 1or the
de'ault streams Fde'ault input and output streamG, the string returned b( $O+AI,IO+BC 6ill be the
141
nullstring.
4.4 /urther 'otes on Conditions
4.4.1 Conditions under #anguage #e*el 3.2:
9he &on&ept o' &onditions 6as 5er( mu&h e%panded 'rom Rexx language le5el =.50 to le5el <.00.
,an( o' the &entral 'eatures in &onditions are ne6 in le5el <.00, these in&lude:
9he $";; method is ne6, pre5iousl( onl( the SI>+"; method 6as a5ailable, 6hi&h made it
rather di''i&ult to resume e%e&ution a'ter a problem. As a part o' this, the A;"* state has been
added too.
9he &ondition +O,."A* has been added, to allo6 better &ontrol o5er problems in5ol5ing
stream 8#O.
9he built$in 'un&tion $O+AI,IO+BC has been added, to allo6 e%tra&tion o' in'ormation about
the &urrent trapped &ondition.
4.4.2 Pitfalls hen <sing Condition Traps
9here are se5eral pit'alls 6hen using &onditions:
emember that some in'ormation are sa5ed a&ross the 'un&tions. :oth the &urrent trapped
&ondition and the settings o' the traps. ConseKuentl(, (ou &an not set a trap in a pro&edure le5el
'rom a lo6er le5el. Fi.e. &alling a subroutine to set a trap is 6ill not 6or-.G
emember that SI>; is set 6hen trapped b( method $";;. 9his means that 6hene5er a
&ondition might be trapped b( $";;, the SI>; 6ill be set to a ne6 5alue. ConseKuentl(, ne5er
trust the &ontents o' the SI>; 5ariable 'or more than one &lause at a time. 9his is 5er(
'rustrating, but at least it 6ill not happen o'ten. Dhen it do happen, though, (ou 6ill probabl(
ha5e a hard time debugging it.
Also remember that i' (ou use the P.O$AU. &lause in a &ondition handler &alled b( method
$";;, remember to -POS the spe&ial 5ariable SI>; i' (ou 6ant to use it inside the
&ondition handler. >lse it 6ill be shado6ed b( the P.O$AU..
4.4.3 The Correctness of this $escription
8n this des&ription o' &onditions in Rexx, 8 ha5e gone 'urther in the des&ription o' ho6 &onditions
6or-, their internal data stru&tures, the order in 6hi&h things are e%e&uted et&., than the standard
does. 8 ha5e tried to interpret the set o' distin&t statements that is the do&umentation on &ondition,
and design a &omplete and &onsistent s(stem des&ribing ho6 su&h &onditions 6or-. 8 ha5e done
this to tr( to &lari'( an area o' Rexx 6hi&h at 'irst glan&e is 5er( di''i&ult and sometimes non$
intuiti5e.
8 hope that the liberties 8 ha5e ta-en ha5e helped des&ribe &onditions in Rexx. 8 do not 'eel that the
adding o' details that 8 ha5e done in an( 6a( &hange ho6 &onditions 6or-, but at least 8 o6e the
reader to list 6hi&h &on&epts that are genuine Rexx, and 6hi&h ha5e been 'illed in b( me to ma-e
the pi&ture more &omplete. 9hese are not a part o' the standard Rexx.
142
Rexx does not ha5e an(thing &alled a standard &ondition. 9here \ust ;are; a set o' &onditions
ha5ing di''erent attributes and 5alues. Sometimes there are de'ault 5alues to some o' the
attributes, but still the are no de'ault &ondition.
9he terms ;e5ent; and ;in&ident; are not used. 8nstead the term ;&ondition; is some6hat
o5erloaded to mean se5eral things, depending on the situation. 8 ha5e 'ound it ad5antageous to
use di''erent terms 'or ea&h o' these &on&epts.
Standard Rexx does not ha5e &ondition Kueue, although a stru&ture o' su&h a -ind is needed to
handled the Kueuing o' pending &onditions 6hen the trap state is A;"*.
9he 5alues de'ault$a&tion and dela($a&tion are reall( non$e%isting in the Standard Rexx
do&umentation. 8 made them up to ma-e the s(stem more eas( to e%plain.
9he t6o$step pro&ess o' 'irst raising the 'lag, and then Fpossibl( at a later stageG triggering the
trap, is not reall( a Rexx &on&ept. Originall(, Rexx seems to allo6 implementations to sele&t
&ertain pla&es o' the interpreter 6here e5ents are sought 'or. All standard &onditions that &an be
&alled b( method $";;, &an be implemented b( &he&-ing onl( at &lause boundaries.
ConseKuentl(, a Rexx implementation &an &hoose to trigger the trap immediatel( a'ter a
&ondition are raised Fsin&e &onditions are onl( raised immediatel( be'ore the trap 6ould trigger
an(6a(G. 9his is also the &ommon 6a( used in language le5el =.50, 6hen onl( method SI>+";
6as implemented.
0n'ortunatel(, the introdu&tion o' the state A;"* 'or&es the interpreter to -eep a Kueue o'
pending &onditions, so there is nothing to gain on insisting that raising should happen
immediatel( be'ore triggering. And the pi&ture is e5en more muddied 6hen the +O,."A*
&ondition is introdu&ed. Sin&e it e%pli&itl( allo6s raising o' &ondition to be done during the
&lause, e5en though the triggering o' the trap must happen Fi' method is $";;G at the end o' the
&lause.
8 reall( hope that these &hanges has made the &on&ept o' &onditions easier to understand, not harder.
"lease 'eel 'ree to 'lame me 'or an( o' these 6hi&h (ou donPt thin- is representati5e 'or Rexx.
4.2 Conditions in Regina
!ere &omes do&umentation that are spe&i'i& 'or the egina implementation o' Rexx.
4.2.1 6o to Raise the HALT condition
9he implementation &onne&t the 9";, &ondition to an e%ternal e5ent, 6hi&h might be the pressing
o' &ertain -e( &ombination. 9he &ommon &on5entions o' the operating s(stem 6ill di&tate 6hat that
&ombination o' -e(stro-es is.
:elo6 is a list, 6hi&h des&ribes ho6 to in5o-e an e5ent that 6ill raise the 9";, &ondition under
5arious the operating s(stems 6hi&h egina runs under.
0nder 5arious 5ariants o' the (ni" operating s(stem, the 9";, e5ent it &onne&ted to the signal
143
;interrupt; FSI>I+,G. O'ten this signal is bound to spe&ial -e(stro-es. 2epending on (our
5ersion o' 0ni%, this might be <&trl>$<&> Fmostl( :S2$5ariantsG or the <del> -e( Fmostl(
S(stem 4G. 8t is also possible to send this signal 'rom the &ommand line, in general using the
program TillB1C7 or 'rom program, in general using the &all signalB7C. e'er to (our
0ni% do&umentation 'or more in'ormation.
0nder 2*)420S, the -e( seKuen&e <&trl>$<&> is used to raise the 9";, &ondition in the
interpreter.
4.3 Possible /uture extensions
!ere is a list o' possible 'uture e%tensions to Rexx 6hi&h has not been implemented into
egina. Some o' these e%ist in other implementations o' Rexx, and some o' them are \ust
suggestions or ideas thro6n around b( 5arious people.
Another e%tension &ould ha5e been in&luded, but ha5e been le't out so 'ar. 8t is the dela($a&tion,
6hi&h in standard Rexx &an be either to ignore or to Kueue. 9here is at least one other a&tion
that ma-e sense: to repla&e. 9hat is, 6hen a trap is in state A;"*, and a ne6 &ondition has
been raised, the pending Kueue is emptied, be'ore the ne6 &ondition is Kueued. 9hat 6a(, the
ne6 &ondition 6ill e''e&ti5el( repla&e an( &onditions alread( in the Kueue.
8' there are se5eral ne6 &onditions raised 6hile the &ondition handler is e%e&uting Fand the trap
state is A;"*G, onl( the 5er( last o' them is remembered.
8t should be possible to set the state 'or a trap to A;"*, so that an( ne6 instan&es o' the
&ondition is handles b( the dela($a&tion. As a spe&ial &ase, the S*+,"- &ondition trap might
not be set in state A;"*
144
2 !tream Input and -utput
'nd the strea#s thereo& shall be turned into pitch
Isaiah 66*/.
+or every one that aseth receivedth7
and he that seeeth &indth7
and to hi# that noceth it shall be opened.
Matthe" 8*9
9his &hapter treats the topi& o' input 'rom and output to streams using the built$in 'un&tions. An
o5er5ie6 o' the other parts o' the input#output F8#OG s(stem is also gi5en but not dis&ussed in detail.
At the end o' the &hapter there are se&tions &ontaining implementation$spe&i'i& in'ormation 'or this
topi&.
2.1 %ac+ground and 6istorical Remar+s
Stream 8#O is a problem area 'or languages li-e Rexx. 9he( tr( to maintain &ompatibilit( 'or all
plat'orms Fi.e. to be non$s(stem$spe&i'i&G, but the basi& 8#O &apabilities di''er bet6een s(stems, so
the simplest 6a( to a&hie5e &ompatibilit( is to in&lude onl( a minimal, &ommon subset o' the
'un&tionalit( o' all plat'orms. Dith respe&t to the 'un&tionalit( o' the inter'a&e to their surrounding
en5ironment, non$s(stem$spe&i'i& s&ript languages li-e Rexx are inherentl( in'erior to s(stem
spe&i'i& s&ript languages 6hi&h are hard6ired to parti&ular operating s(stems and &an bene'it 'rom
all their 'eatures.
Although Rexx 'ormall( has its o6n 8#O &onstru&ts, it is &ommon 'or some plat'orms that most or
all o' the 8#O is per'ormed as operating s(stem &ommands rather than in Rexx. 9his is ho6 it 6as
originall( done under 4,#C,S, 6hi&h 6as one o' the earliest implementations and 6hi&h did not
support RexxPs 8#O &onstru&ts. 9here, the -$IO program and the sta&- Famong other methodsG
are used to trans'er data to and 'rom a Rexx program.
3ater, the built$in 'un&tions 'or stream 8#O gained territor(, but lots o' implementations still rel( on
spe&ial purpose programs 'or doing 8#O. 9he general re&ommendation to Rexx programmers is to
use the built$in 'un&tions instead o' spe&ial purpose programs 6hene5er possible7 that is the onl(
6a( to ma-e &ompatible programs.
2.2 RexxEs 'otion of a !tream
Rexx regards a stream as a seKuen&e o' &hara&ters, &on&eptuall( eKui5alent to 6hat a user might
t(pe at the -e(board. /ote that a stream is not generall( eKui5alent to a 'ile. I,C.!:28C9J
de'ines a 'ile as ;a &olle&tion o' related re&ords treated as a unit,; 6hile IOA:C28C9J de'ines it as
;8n'ormation held on ba&-ing store I...J in order FaG to enable it to persist be(ond the time o'
e%e&ution o' a single \ob and#or FbG to o5er&ome spa&e limitations in main memor(.; A stream is
de'ined b( IOA:C28C9J as ;a 'lo6 o' data &hara&teriHed b( relati5e long duration and &onstant
rate.;
145
9hus, a 'ile has a 'la5or o' persisten&(, 6hile a stream has a 'la5or o' seKuen&e and momentaril(.
1or a stream, data read earlier ma( alread( ha5e been lost, and the data not (et read ma( not be
&urrentl( de'ined7 'or instan&e the input t(ped at a -e(board or the output o' a program. >5en
though mu&h o' the Rexx literature use these t6o terms inter&hangeabl( Fand a'ter all, there is some
o5erlapG, (ou should bear in mind that there is a di''eren&e bet6een them.
8n this do&umentation, the term ;'ile; means ;a &olle&tion o' persistent data on se&ondar( storage, to
6hi&h random a&&ess and multiple retrie5al are allo6ed.; 9he term ;stream; means a seKuential
'lo6 o' data 'rom a 'ile or 'rom a seKuential de5i&e li-e a terminal, tape, or the output o' a program.
9he term stream is also used in its stri&t Rexx meaning: a handle to#'rom 6hi&h a 'lo6 o' data &an
be 6ritten#read.
2.3 !hort Crash8Course
Rexx 8#O is 5er( simple, and this short &rash &ourse is probabl( all (ou need in a 'irst$time reading
o' this &hapter. :ut note that that, 6e need to \ump a bit ahead in this se&tion.
9o read a line 'rom a stream, use the ;I+I+BC built$in 'un&tion, 6hi&h returns the data read. 9o
6rite a stream, use the ;I+OU,BC built$in 'un&tion, and suppl( the data to be 6ritten as the
se&ond parameter. 1or both operations, gi5e the name o' the stream as the 'irst parameter. Some
small e%amples:
con'en's : lineinB /%y(ile.'&'/ C
call lineou' /your(ile.'&'/) /Aa'a 'o be 0ri''en/
9he 'irst o' these reads a line 'rom the stream %y(ile.'&', 6hile the se&ond 6rites a line to the
stream your(ile.'&'. :oth these &alls operate on lines and the( use a s(stem spe&i'i& end$o'$
line mar-er as a delimiter bet6een lines. 9he mar-er is tagged on at the end o' an( data 6ritten out,
and stripped o'' an( data read.
Opening a stream in Rexx is generall( done automati&all(, so (ou &an generall( ignore that in (our
programs. Another use'ul method is repositioning to a parti&ular line:
call linein /%y(ile.'&'/) 1#) <
call lineou' /your(ile.'&'/)) 17
Dhere the 'irst o' these sets the &urrent read position to the start o' line 12 o' the stream7 the se&ond
sets the &urrent 6rite position to the start o' line 1=. /ote that the se&ond parameter is empt(, that
means no data is to be 6ritten. Also note that the &urrent read and 6rite positions are t6o
independent entities7 setting one does not a''e&t the other.
9he built$in 'un&tions $9".I+BC and $9".OU,BC are similar to the ones \ust des&ribed, e%&ept
that the( are &hara&ter$oriented, i.e. the end$o'$line delimiter is not treated as a spe&ial &hara&ter.
>%amples o' use are:
say c!arinB /%y(ile.'&'/) 1< C
call c!arou' /log(ile/) /so%e 1a'a/
!ere, the 'irst e%ample reads 10 &hara&ters, starting at the &urrent input position, 6hile the se&ond
146
6rites the ele5en &hara&ters o' ;some data; to the 'ile, 6ithout an end$o'$'ile mar-er a'ter6ard.
8t is possible to reposition &hara&ter$6ise too, some e%amples are:
call c!arin /%y(ile/)) 8
call c!arou' /(oo(ile)) 1<
9hese t6o &lauses repositions the &urrent read and 6rite positions o' the named 'iles to the +
th
and
10
th
&hara&ters, respe&ti5el(.
2.4 'aming !treams
0nli-e most programming languages, Rexx does not use 'ile handles7 the name o' the stream is also
in general the handle Falthough some implementations add an e%tra le5el o' indire&tionG. Cou must
suppl( the name to all 8#O 'un&tions operating on a stream. !o6e5er, internall(, the Rexx
interpreter is li-el( to use the nati5e 'ile pointers o' the operating s(stem, in order to impro5e speed.
9he name spe&i'ied &an generall( be the name o' an operating s(stem 'ile, a de5i&e name, or a
spe&ial stream name supported b( (our implementation.
9he 'ormat o' the stream name is 5er( dependent upon (our operating s(stem. 1or portabilit(
&on&erns, (ou should tr( not to spe&i'( it as a literal string in ea&h 8#O &all, but set a 5ariable to the
stream name, and use that 5ariable 6hen &alling 8#O 'un&tions. 9his redu&es the number o' pla&es
(ou need to ma-e &hanges i' (ou need to port the program to another s(stem. 0n'ortunatel(, this
approa&h in&reases the need 'or P.O$AU. -POS, sin&e the 5ariable &ontaining the 'iles
name must be a5ailable to all routines using 'ile 8#O 'or that parti&ular 'ile, and all their non$
&ommon an&estors.
Example" !pecif&ing file names
9he 'ollo6ing &ode illustrates a portabilit( problem related to the naming o' streams. 9he 5ariable
(ilena%e is set to the name o' the stream operated on in the 'un&tion &all.
(ilena%e : //'%6/3y@ile.,&'/
say / (irs' line is/ lineinB (ilena%e C
say /secon1 line is/ lineinB (ilena%e C
say / '!ir1 line is/ lineinB (ilena%e C
Suppose this s&ript, 6hi&h loo-s li-e it is 6ritten 'or 0ni%, is mo5ed to a 4,S ma&hine. 9hen, the
stream name might be something li-e S*SY,3PH3*@I;.,-,, but (ou onl( need to &hange the
s&ript at one parti&ular point: the assignment to the 5ariable (ilena%e7 as opposed to three pla&es
i' the stream name is hard$&oded in ea&h o' the three &alls to ;I+I+BC.
8' the stream name is omitted 'rom the built$in 8#O 'un&tions, a de'ault stream is used: input
'un&tions use the de'ault input stream, 6hile output 'un&tions use the de'ault output stream. 9hese
are impli&it re'eren&es to the de'ault input and output streams, but un'ortunatel(, there is no
standard 6a( to e%pli&itl( re'er to these t6o streams. And &onseKuentl(, there is no standard 6a( to
re'er to the de'ault input or output stream in the built$in 'un&tion S,."3BC.
!o6e5er, most implementations allo6 (ou to a&&ess the de'ault streams e%pli&itl( through a name,
147
ma(be the nullstring or something li-e s'1in and s'1ou'. !o6e5er, (ou must re'er to the
implementation$spe&i'i& do&umentation 'or in'ormation about this.
Also note that standard Rexx does not support the &on&ept o' a de'ault error stream. On operating
s(stems supporting this, it &an probabl( be a&&essed through a spe&ial name7 see s(stem$spe&i'i&
in'ormation. 9he same applies 'or other spe&ial streams.
Sometimes the term ;de'ault input stream; is &alled ;standard input stream,; ;de'ault input
de5i&es,; ;standard input,; or \ust ;stdin.;
9he use o' stream names instead o' stream des&riptors or handles is deepl( rooted in the Rexx
philosoph(: 2ata stru&tures are te%t strings &arr(ing in'ormation, rather than opaKue data blo&-s in
internal, binar( 'ormat. 9his opens 'or some intriguing possibilities. 0nder some operating s(stems,
a 'ile &an be re'erred to b( man( names. 1or instan&e, under 0ni%, a 'ile &an be re'erred to as
(oobar, ./(oobar and ././(oobar. All 6hi&h name the same 'ile, although a Rexx
interpreter ma( be li-el( to interpret them as three di''erent streams, be&ause the names themsel5es
di''er. On the other hand, nothing pre5ents an interpreter 'rom dis&o5ering that these are names 'or
the same stream, and treat them as eKui5alent Fe%&ept &on&erns 'or pro&essing timeG. 0nder 0ni%,
the problem is not \ust &on'ined to the use o' ./ in 'ile names, hard$lin-s and so't$lin-s &an produ&e
similar e''e&ts, too.
Example" Internal file handles
Suppose (ou start reading 'rom a stream, 6hi&h is &onne&ted to a 'ile &alled (oo. Cou read the 'irst
line o' (oo, then (ou issue a &ommand, in order to rename (oo to bar. 9hen, (ou tr( to read the
ne%t line 'rom (oo. 9he Rexx program 'or doing this under 0ni% loo-s something li-e:
signal on no'rea1y
line1 : lineinB /(oo/ C
/%v (oo bar/
line# : lineinB /(oo/ C
9heoreti&all(, the 'ile (oo does not e%ist during the se&ond &all, so the se&ond read should raise the
+O,."A* &ondition. !o6e5er, a Rexx interpreter is li-el( to ha5e opened the stream alread(, so
it is per'orming the reading on the 'ile des&riptor o' the open 'ile. 8t is probabl( not going to &he&-
6hether the 'ile e%ists be'ore ea&h 8#O operation Fthat 6ould reKuire a lot o' e%tra &he&-ingG. 0nder
most operating s(stems, renaming a 'ile 6ill not in5alidate e%isting 'ile des&riptors. ConseKuentl(,
the interpreter is li-el( to &ontinue to read 'rom the original (oo 'ile, e5en though its has &hanged.
Example" <nix temporar& files
On some s(stems, (ou &an delete a 'ile, and still read 'rom and 6rite to the stream &onne&ted to that
'ile. 9his te&hniKue is sho6n in the 'ollo6ing 0ni% spe&i'i& &ode:
148
'%6(ile : //'%6/%y(ile/
call lineou' '%6(ile) //
call lineou' '%6(ile)) 1
/r%/ '%6(ile
call lineou' '%6(ile) /,!is is '!e (irs' line/
0nder 0ni%, this te&hniKue is o'ten used to &reate temporar( 'iles7 (ou are guaranteed that the 'ile
6ill be deleted on &losing, no matter ho6 (our program terminates. 0ni% deletes a 'ile 6hene5er
there are no more re'eren&es to it. Dhether the re'eren&e is 'rom the 'ile s(stem or 'rom an open
des&riptor in a user pro&ess is irrele5ant. A'ter the r% &ommand, the onl( re'eren&e to the 'ile is
'rom the Rexx interpreter. Dhene5er it terminates, the 'ile is deleted$$sin&e there are no more
re'eren&es to it.
Example" /iles in different directories
!ere is (et another e%ample o' ho6 using the 'ilename dire&tl( in the stream 8#O 'un&tions ma( gi5e
strange e''e&ts. Suppose (ou are using a s(stem that has hierar&hi&al dire&tories, and (ou ha5e a
'un&tion $9AI.BC 6hi&h sets a &urrent dire&tor(7 then &onsider the 'ollo6ing &ode:
call c!1ir /../1ir1/
call lineou' /(oobar/) /0ri''en 'o (oobar 0!ile in 1ir1/
call c!1ir /../1ir#/
call lineou' /(oobar/) /0ri''en 'o (oobar 0!ile in 1ir#/
Sin&e the 'ile is impli&itl( opened 6hile (ou are in the dire&tor( 1ir1, the 'ile (oobar re'ers to a
'ile lo&ated there. !o6e5er, a'ter &hanging the dire&tor( to 1ir#, it ma( seem logi&al that the
se&ond &all to ;I+OU,BC operates on a 'ile in 1ir#, but that ma( not be the &ase. Considering
that these &lauses ma( &ome a great number o' lines apart, that Rexx has no standard 6a( o'
&losing 'iles, and that Rexx onl( ha5e one 'ile table Fi.e. open 'iles are not lo&al to subroutinesG7 this
ma( open 'or a signi'i&ant astonishment in &omple% Rexx s&ripts.
Dhether an implementation treats ././(oo and ./(oo as di''erent streams is s(stem$dependent7
that applies to the e''e&ts o' renaming or deleting the 'ile 6hile reading or 6riting, too. See (our
interpreterPs s(stem$spe&i'i& do&umentation.
,ost o' the e''e&ts sho6n in the e%amples abo5e are due to insu''i&ient isolation bet6een the
'ilename o' the operating s(stem and the 'ile handle in the Rexx program. Dhene5er a 'ile &an be
e%pli&itl( opened and bound to a 'ile handle, (ou should do that in order to de&rease the possibilities
'or strange side e''e&ts.
8nterpreters that allo6 this method generall( ha5e an OP+BC 'un&tion that ta-es the name o' the
'iles to open as a parameter, and returns a string that uniKuel( identi'ies that open 'ile 6ithin the
&urrent &onte%t7 e.g. an inde% into a table o' open 'iles. 3ater, this inde% &an be used instead o' the
'ilename.
Some implementations allo6 onl( this indire&t naming s&heme, 6hile others ma( allo6 a mi%
bet6een dire&t and indire&t naming. 9he latter is li-el( to &reate some problems, sin&e some strings
are li-el( to be both 5alid dire&t and indire&t 'ile ids.
149
2.2 Persistent and Transient !treams
Rexx -no6s t6o di''erent t(pes o' streams: persistent and transient. 9he( di''er &on&eptuall( in the
6a( the( &an be operated, 6hi&h is di&tated b( the 6a( the( are stored. :ut there is no di''eren&e in
the data (ou &an read 'rom or 6rite to them Fi.e. both &an used 'or &hara&ter$ or line$6ise dataG, and
both are read and 6ritten using the same 'un&tions.
+!er(5(4e64 (4rea*(,
Fo'ten re'erred to \ust as ;'iles;G are &on&eptuall( stored on permanent storage in the
&omputer Fe.g. a dis-G, as an arra( o' &hara&ters. andom a&&ess to and repeated retrie5al o'
an( part o' the stream are allo6ed 'or persistent streams. 9(pi&al e%ample o' persistent
streams are normal operating s(stem 'iles.
+Tra6(5e64 (4rea*(,
are t(pi&all( not a5ailable 'or random a&&ess or repeated retrie5al, either be&ause it is not
stored permanentl(, but read as a seKuen&e o' data that is generated on the 'l(7 or be&ause
the( are a5ailable 'rom a seKuential storage Fe.g. magneti& tapeG 6here random a&&ess is
di''i&ult or impossible. 9(pi&al e%amples o' transient streams are de5i&es li-e -e(boards,
printers, &ommuni&ation inter'a&es, pipelines, et&.
Rexx does not allo6 an( repositioning on transient streams7 su&h operations are not &on&eptuall(
meaning'ul7 a transient stream must be treated seKuentiall(. 8t is possible to treat a persistent stream
as a transient stream, but not 5i&e 5ersa. 9hus, some implementations ma( allo6 (ou to open a
persistent stream as transient. 9his ma( be use'ul 'or 'iles to 6hi&h (ou ha5e onl( append a&&ess,
i.e. 6rites &an onl( be per'ormed at the end o' 'ile. Dhether (ou &an open a stream in a parti&ular
mode, or &hange the mode o' a stream alread( open depends on (our implementation.
Example" $etermining stream t&pe
0n'ortunatel(, there is no standard 6a( to determine 6hether a gi5en 'ile is persistent or transient.
Cou ma( tr( to reposition 'or the 'ile, and (ou &an assume that the 'ile is persistent i' the
repositioning su&&eeded, li-e in the 'ollo6ing &ode:
s'rea%'y6eH 6roce1ure
signal on no'rea1y
call linein argB1C) 1) <
re'urn /6ersis'en'/ /5 unless (ile is e%6'y 5/
no'rea1yH
re'urn /'ransien'/
Although the idea in this &ode is &orre&t, there are un'ortunatel( a 'e6 problems. 1irst, the
+O,."A* &ondition &an be raised b( other things than tr(ing to reposition a transient stream7 e.g.
b( an( repositioning o' the &urrent read position in an empt( 'ile, i' (ou ha5e 6rite a&&ess onl(, et&.
Se&ond, (our implementation ma( not ha5e +O,."A*, or it ma( not use it 'or this situation.
9he best method is to use a S,."3BC 'un&tion, i' one is a5ailable. 0n'ortunatel(, that is not 5er(
&ompatible, sin&e no standard stream &ommands are de'ined.
150
2.3 -pening a !tream
8n most programming languages, opening a 'ile is the pro&ess o' binding a 'ile Fgi5en b( a 'ile
nameG to an internal handle. Rexx is a bit spe&ial, sin&e &on&eptuall(, it does not use stream
handles, \ust stream names. 9here'ore, the stream name is itsel' also the stream handle, and the
pro&ess o' opening streams be&omes apparentl( redundant. !o6e5er, note that a number o'
implementations allo6 e%pli&it opening, and some e5en reKuire it.
Rexx ma( open streams ;on demand; 6hen the( are used 'or the 'irst time. !o6e5er, this beha5ior
is not de'ined in 93, 6hi&h sa(s the a&t o' opening the stream is not a part o' Rexx I932J. 9his
might be interpreted as open$on$demand or that some s(stem$spe&i'i& program must be e%e&uted to
open a stream.
Although an open$on$demand 'eature is 5er( pra&ti&al, there are situations 6here (ou need to open
streams in parti&ular modes. 9hus, most s(stems ha5e 'a&ilities 'or e%pli&itl( opening a 'ile. Some
Rexx interpreters ma( reKuire (ou to per'orm some implementation$spe&i'i& operation be'ore
a&&essing streams, but most are li-el( to \ust open them the 'irst time the( are re'erred to in an 8#O
operation.
9here are t6o main approa&hes to e%pli&it opening o' streams. 9he 'irst uses a non$standard built$in
'un&tion normall( &alled OP+BC, 6hi&h generall( ta-es the name o' the 'ile to open as the 'irst
parameter, and o'ten the mode as the se&ond parameter. 9he se&ond approa&h is similar, but uses
the standard built$in 'un&tion S,."3BC 6ith a $o%%an1 option.
Example" 'ot closing files
Sin&e there are no open or &lose operation, a Rexx interpreter ne5er -no6s 6hen to &lose a stream,
unless e%pli&itl( told so. 8t &an ne5er predi&t 6hen a parti&ular stream is to be used ne%t, so it has to
-eep the &urrent read and 6rite positions in &ase the stream is to be used again. 9here'ore, (ou
should al6a(s &lose the streams 6hen (ou are 'inished using them. 1ailure to do so, 6ill 'ill the
interpreter 6ith data about unneeded streams, and more serious, it ma( 'ill the 'ile table o' (our
pro&ess or s(stem. As a rule, an( Rexx s&ript that uses more than a &ouple o' streams, should &lose
e5er( stream a'ter use, in order to minimiHe the number o' simultaneousl( open streams. 9hus, the
'ollo6ing &ode might e5entuall( &rash 'or some Rexx interpreters:
1o i:1 'o 7<<
call lineou' /(ile./DDi) /'!is is (ile nu%ber/ i
en1
A Rexx interpreter might tr( to de'end itsel' against this sort o' open$man($&lose$none
programming, using o' 5arious programming te&hniKues7 this ma( lead to other strange e''e&ts.
!o6e5er, the main responsibilit( 'or a5oiding this is 6ith (ou, the Rexx s&ript programmer.
/ote that i' a stream is alread( open 'or reading, and (ou start 6riting to it, (our implementation
ma( ha5e to reopen it in order to open 'or both reading and 6riting. 9here are mainl( t6o strategies
'or handling this. >ither the old 'ile is &losed, and then reopened in the ne6 mode, 6hi&h ma( lea5e
(ou 6ith read and 6rite a&&ess to another 'ile. Or a ne6 'ile handle is opened 'or the ne6 mode,
6hi&h ma( lea5e (ou 6ith read and 6rite a&&ess to t6o di''erent 'iles.
151
9hese are real$6orld problems 6hi&h are not treated b( the ideal des&ription o' 93. A good
implementation should dete&t these situations and raise +O,."A*.
2.5 Closing a !tream
As alread( mentioned, Rexx does not ha5e an e%pli&it 6a( o' opening a stream. /or does it ha5e an
e%pli&it 6a( o' &losing a stream. 9here is one semi$standard method: 8' (ou &all ;I+OU,BC, but
omit both the data to be 6ritten and the ne6 &urrent 6rite position, then the implementation is
de'ined to set the &urrent 6rite position to the end$o'$'ile. 1urthermore, it is allo6ed b( 93 to do
something ;magi&; in addition. 8t is not e%pli&itl( de'ined 6hat this magi& is, but 93 suggests that
it ma( be &losing the stream, 'lushing the stream, or &ommitting &hanges done pre5iousl( to the
stream.
8n SAA, the de'inition is strengthened to state that the ;magi&; is &losing, pro5ided that the
en5ironment supports that operation.
A similar operating &an be per'ormed b( &alling $9".OU,BC 6ith neither data nor a ne6 position.
!o6e5er, in this &ase, both 93 and SAA lea5e it totall( up to the implementation 6hether or not
the 'ile is to be &losed. One &an 6onder 6hether the &hanges 'or ;I+OU,BC in SAA 6ith respe&t
to 93 should also ha5e been done to $9".OU,BC, but that this 6as 'orgotten.
932 does not indi&ate that ;I+I+BC or $9".I+BC &an be used to &lose a string. 9hus, the
&losest one gets to a standard 6a( o' &losing input 'iles is to &all e.g. ;I+OU,BC7 although it is
&on&eptuall( suspe&t to &all an output routine 'or an input 'ile. 9he histori&al reasons 'or this
omission are perhaps that 'lushing output 'iles is 5ital , 6hile the &on&ept o' 'lushing is irrele5ant
'or input 'iles7 'lushing is an important part o' &losing a 'ile, and that e%plains 6h( &losing is onl(
indi&ated 'or output 'iles.
9hus, the statement:
call lineou' /%y(ile.'&'/
might be used to &lose the stream %y(ile.'&' in some implementations. !o6e5er, it is not
guaranteed to &lose the stream, so (ou &annot depend on this 'or s&ripts o' ma%imum portabilit(, but
itPs better than nothing. !o6e5er, note that i' it &loses the stream, then also the &urrent read position
is a''e&ted. 8' it merel( 'lushes the stream, then onl( the &urrent 6rite position is li-el( to be
a''e&ted.
2.7 Character8ise and #ine8ise I.-
:asi&all(, the built$in Rexx librar( o''ers t6o strategies o' reading and 6riting streams: line$6ise
and &hara&ter$6ise. Dhen reading line$6ise, the underl(ing storage method o' the stream must
&ontain in'ormation 6hi&h des&ribes 6here ea&h line starts and ends.
Some 'ile s(stems store this in'ormation as one or more spe&ial &hara&ters7 6hile others stru&ture
the 'ile in a number o' re&ords7 ea&h &ontaining a single line. 9his introdu&es a slightl( subtle point7
e5en though a stream (oo returns the same data 6hen read b( ;I+I+BCon t6o di''erent
ma&hines7 the data read 'rom (oo ma( di''er bet6een the same t6o ma&hines 6hen the stream is
read b( $9".I+BC, and 5i&e 5ersa. 9his is so be&ause the end$o'$line mar-ers &an 5ar( bet6een
the t6o operating s(stems.
152
Example" Character8ise handling of E-#
Suppose a te%t 'ile &ontains the 'ollo6ing three lines FASC88 &hara&ter set is assumedG:
(irs'
secon1
'!ir1
and (ou 'irst read it line$6ise and then &hara&ter$6ise. Assume the 'ollo6ing program:
(ile : /A","@I;/
(oo : //
1o i:1 0!ile c!arsB(ileCQ<
(oo : (oo DD c#&Bc!arinB(ileCC/ /
en1
say (oo
Dhen the 'ile is read line$6ise, the output is identi&al on all ma&hines, i.e. the three lines sho6n
abo5e. !o6e5er, the &hara&ter$6ise reading 6ill be dependent on (our operating s(stem and its 'ile
s(stem, thus, the output might e.g. be an( o':
MM M9 N# N7 N8 N7 M5 M@ M7 M M8 N8 M8 M9 N# M8 MM M9 N# N7
N8 <"
MM M9 N# N7 N8 <"
N7 M5 M@ M7 M M8 <"
N8 M8 M9 N# M8 <"
MM M9 N# N7 N8 <A <"
N7 M5 M@ M7 M M8 <A <"
N8 M8 M9 N# M8 <A <"
8' the ma&hine uses re&ords to store the lines, the 'irst one ma( be the result7 here, onl( the data in
the lines o' the 'ile is returned. /ote that the bo%es in the output are put around the data generated
b( the a&tual line &ontents. Dhat is outside the bo%es is generated b( the end$o'$line &hara&ter
seKuen&es.
9he se&ond output line is t(pi&al 'or 0ni% ma&hines. 9he( use the ne6line ASC88 &hara&ter as line
separator, and that &hara&ter is read immediatel( a'ter ea&h line. 9he last line is t(pi&al 'or ,S$
2OS, 6here the line separator &hara&ter seKuen&e is a &arriage return 'ollo6ing b( a ne6line
FASC88 /<A/& and /<"/&G.
1or ma%imum portabilit(, the line$6ise built$in 'un&tions F;I+I+BC, ;I+OU,BC and
;I+SBCG should onl( be used 'or line$6ise streams. And the &hara&ter$6ise built$in 'un&tions
F$9".I+BC, $9".OU,BC and $9".SBCG should onl( be used 'or &hara&ter$6ise data. Cou should
in general be 5er( &are'ul 6hen mi%ing &hara&ter$ and line$6ise data in a single stream7 it does
6or-, but ma( easil( lead to portabilit( problems.
153
9he di''eren&e bet6een &hara&ter$ and line$6ise streams are roughl( eKui5alent to the di''eren&e
bet6een binar( and te%t streams, but the t6o &on&epts are not totall( eKui5alent. 8n a binar( 'ile, the
data read is the a&tual data stored in the 'ile, 6hile in a te%t 'ile, the &hara&ter seKuen&es used 'or
denoting end$o'$line and end$o'$'ile mar-ers ma( be translated to a&tions or other &hara&ters during
reading.
9he end$o'$'ile mar-er ma( be di''erentl( implemented on di''erent s(stems. On some s(stems, this
mar-er is onl( impli&itl( present at the end$o'$'ile$$6hi&h is &al&ulated 'rom the 'ile siHe Fe.g.
0ni%G. Other s(stems ma( put a &hara&ter signi'(ing end$o'$'ile at the end For e5en in the middleG o'
the 'ile Fe.g. <Ctrl$N> 'or ,S$2OSG. 9hese &on&epts 5ar( bet6een operating s(stems, interpreters
should handle ea&h &on&ept a&&ording to the &ustoms o' the operating s(stem. Che&- the
implementation$spe&i'i& do&umentation 'or 'urther in'ormation. 8n an( &ase, i' the interpreter treats
a parti&ular &hara&ter as end$o'$'ile, then it onl( gi5es spe&ial treatment to this &hara&ter during line$
6ise operations. 2uring &hara&ter$6ise operations, no &hara&ters ha5e spe&ial meanings.
2.9 Reading and ?riting
1our built$in 'un&tions pro5ide line$ and &hara&ter$oriented stream reading and 6riting &apabilities:
$9".I+BC, $9".OU,BC, ;I+I+BC, ;I+OU,BC.
+"'ARIN(),
is a built$in 'un&tion that ta-es up to three parameters, 6hi&h are all optional: the name o'
the stream to read 'rom, the start point, and the number o' &hara&ters to read. 9he stream
name de'aults to the de'ault input stream, the start point de'aults to the &urrent read position,
the number o' &hara&ters to read de'aults to one &hara&ter. 3ea5e out the se&ond parameter in
order to a5oid all repositioning. 2uring e%e&ution, data is read 'rom the stream spe&i'ied,
and returned as the return 5alue.
+LININ(),
is a built$in 'un&tion that ta-es three parameters too, and the( are eKui5alent to the
parameters o' $9".I+BC. !o6e5er, i' the se&ond parameter is spe&i'ied, it re'er to a line
position, rather than a &hara&ter position7 it re'ers to the &hara&ter position o' the 'irst
&hara&ter o' that line. 1urther, the third parameter &an onl( be < or 1, and re'ers to the
number o' lines to read7 i.e. (ou &annot read more than one line in ea&h &all. 9he line read is
returned b( the 'un&tion, or the nullstring i' no reading 6as reKuested.
+LINOUT(),
is a built$in 'un&tion that ta-es three parameters too, the 'irst is the name o' the stream to
6rite to, and de'aults to the de'ault output stream. 9he se&ond parameter is the data to be
6ritten to the 'ile, and i' not spe&i'ied, no 6riting o&&urs. 9he third parameter is a line$
oriented position in the 'ile7 i' the third parameter is spe&i'ied, the &urrent position is
repositioned at be'ore the data Fi' an(G is 6ritten. 8' data is 6ritten, an end$o'$line &hara&ter
seKuen&e is appended to the output stream.
+"'AROUT(),
is a built$in 'un&tion that is used to 6rite &hara&ters to a 'ile. 8t is identi&al to ;I+OU,BC,
e%&ept that the third parameter re'ers to a &hara&ter position, instead o' a line position. 9he
se&ond di''eren&e is that an end$o'$line &hara&ter seKuen&e is not appended at the end o' the
data 6ritten.
Example" Counting lines1 ords1 and characters
154
9he 'ollo6ing Rexx program emulates the &ore 'un&tionalit( o' the 0c program under 0ni%. 8t
&ounts the number o' lines, 6ords, and &hara&ters in a 'ile gi5en as the 'irst argument.
(ile : argB1C
6arse value < < < 0i'! lines 0or1s c!ars
1o 0!ile linesB(ileCQ<
line : lineinB(ileC
lines : lines = 1
0or1s : 0or1s = 0or1sBlineC
c!ars : c!ars = leng'!BlineC
en1
say /lines:/lines /0or1s:/0or1s /c!ars:/c!ars
9here are some problems. 1or instan&e, the end$o'$line &hara&ters are not &ounted, and a last
improperl( terminated line is not &ounted either.
155
2.1: $etermining the Current Position
Standard Rexx does not ha5e an( see- &all that returns the &urrent position in a stream. 8nstead, it
pro5ides t6o &alls that returns the amount o' data remaining on a stream. 9hese t6o built$in
'un&tions are ;I+SBC and $9".SBC.
9he ;I+SBC built$in 'un&tion returns the number o' &omplete lines le't on the stream gi5en as
its 'irst parameter. 9he term ;&omplete lines; does not reall( matter mu&h, sin&e an
implementation &an assume the end$o'$'ile to impli&itl( mean an end$o'$line.
9he $9".SBC built$in 'un&tion returns the number o' &hara&ter le't in the stream gi5en as its
'irst parameter.
9his is one o' the &on&epts 6here Rexx 8#O does not map 5er( 6ell to C 8#O and 5i&e 5ersa. Dhile
Rexx reports the amount o' data 'rom the &urrent read position to the end o' stream, C reports the
amount o' data 'rom the start o' the 'ile to the &urrent position. 1urther, the Rexx method onl(
6or-s 'or input streams, 6hile the C method 6or-s 'or both input and output 'iles. On the other
hand, C has no basi& &onstru&ts 'or &ounting remaining or reposition at lines o' a 'ile.
Example" Retrie*ing current position
So, ho6 does one 'ind the &urrent position in a 'ile, 6hen onl( allo6ed to do normal repositioningS
9he tri&- is to reposition t6i&e, as sho6n in the &ode belo6.
('ellH 6roce1ure
6arse arg (ilena%e
no0 : c!arsB(ilena%eC
call c!arin (ilena%e) <) 1
'o'al : c!arsB(ilena%eC
call c!arin (ilena%e) <) 'o'al-no0
re'urn 'o'al-no0
0n'ortunatel(, there are man( potential problems 6ith this &ode. 1irst, it onl( 6or-s 'or input 'iles,
sin&e there is no eKui5alent to $9".SBC 'or output 'iles. Se&ond, i' the 'ile is empt(, none o' the
repositioning 6or-, sin&e it is illegal to reposition at or a'ter end$o'$'ile 'or input 'iles$$and the end$
o'$'ile is the 'irst position o' the 'ile. 9hird, i' the &urrent read position o' the 'ile is at the end o' 'ile
Fe.g. all &hara&ters ha5e been readG it 6ill not 6or- 'or similar reasons as 'or the se&ond &ase. And
'ourth, it onl( 6or-s 'or persistent 'iles, sin&e transient 'iles do not allo6 repositioning.
!"amp$eA +mpr1Ned 0(e"" #ncti1n
An impro5ed 5ersion o' the &ode 'or the ('ell routine Fgi5en abo5eG, 6hi&h tries to handle these
problems is:
156
('ellH 6roce1ure
6arse arg (ilena%e
signal on no'rea1y na%e no'_6ersis'
no0 : c!arsB(ilena%eC
signal on no'rea1y na%e is_e%6'y
call c!arin (ilena%e) <) 1
'o'al : c!arsBC
i( no0Q< '!en
call c!arin (ilena%e) <) 'o'al-no0=1
else i( 'o'alQ< '!en
call c!arin (ilena%e) 1) 'o'al
else
no6 /5 e%6'y (ile) s!oul1 !ave raise1 +O,."A* 5/
re'urn 'o'al-no0=1
no'_6resis'H say (ilena%e /is no' 6ersis'en'/E re'urn <
is_e%6'yH say (ilena%e /is e%6'y/E re'urn <
9he same method &an be used 'or line$oriented 8#O too, in order to return the &urrent line number o'
an input 'ile. !o6e5er, a potential problem in that &ase is that the routine lea5es the stream
repositioned at the start o' the &urrent line, e5en i' it 6as initiall( positioned to the middle o' a line.
8n addition, the line$oriented 5ersion o' this ('ell routine ma( pro5e to be 'airl( ine''i&ient, sin&e
the interpreter ma( ha5e to s&an the 6hole 'ile t6i&e 'or end$o'$line &hara&ter seKuen&es.
2.11 Positioning ?ithin a /ile
Rexx supports t6o strategies 'or reading and 6riting streams: &hara&ter$6ise, and line$6ise, this
se&tion des&ribes ho6 a program &an reposition the &urrent positions 'or ea&h these strategies. /ote
that positioning is onl( allo6ed 'or persistent streams.
1or ea&h open 'ile, there is a &urrent read position or a &urrent 6rite position, depending on 6hether
the 'ile is opened 'or reading or 6riting. 8' the 'ile is opened 'or reading and 6riting simultaneousl(,
it has both a &urrent read position and a &urrent 6rite position, and the t6o are independent and in
general di''erent. A position 6ithin a 'ile is the seKuen&e number o' the b(te or line that 6ill be read
or 6ritten in the ne%t su&h operation.
/ote that Rexx starts numbering at one, not Hero. 9here'ore, the 'irst &hara&ter and the 'irst line o' a
stream are both numbered one. 9his di''ers 'rom se5eral other programming languages, 6hi&h
starts numbering at Hero.
Oust a'ter a stream has been opened, the initial 5alues o' the &urrent read position is the 'irst
&hara&ter in the stream, 6hile the &urrent 6rite position is the end$o'$'ile, i.e. the position \ust a'ter
the last &hara&ter in the stream. 9hen, reading 6ill return the 'irst &hara&ter For lineG in the stream,
and 6riting 6ill append a ne6 &hara&ter For lineG to the stream.
9hese initial 5alues 'or the &urrent read and 6rite positions are the de'ault 5alues. 2epending on
(our Rexx implementation, other me&hanisms 'or e%pli&itl( opening streams Fe.g. through the
S,."3BC built$in 'un&tionG ma( be pro5ided, and ma( set other initial 5alues 'or these positions.
See the implementation$spe&i'i& do&umentation 'or 'urther in'ormation.
157
Dhen setting the &urrent read position, it must be set to the position o' an e%isting &hara&ter in the
stream7 i.e. a positi5e 5alue, not greater than the total number o' &hara&ters in the stream. 8n
parti&ular, it is illegal to set the &urrent read position to the position immediatel( a'ter the last
&hara&ter in the stream7 although this is legal in man( other programming languages and operating
s(stems, 6here it is -no6n as ;see-ing to the end$o'$'ile;.
Dhen setting the &urrent 6rite position, it too must be set to the position o' an e%isting &hara&ter in
the stream. 8n addition, and unli-e the &urrent read position, the &urrent 6rite position ma( also be
set to the position immediatel( 'ollo6ing the last &hara&ter in the stream. 9his is -no6n as
;positioning at the end$o'$'ile;, and it is the initial 5alue 'or the &urrent 6rite position 6hen a
stream is opened. /ote that (ou are not allo6ed to reposition the &urrent 6rite position 'urther out
be(ond the end$o'$'ile$$6hi&h 6ould &reate a ;hole; in the stream$$e5en though this is allo6ed in
man( other languages and operating s(stems.
2epending on (our operating s(stem and Rexx interpreter, repositioning to a'ter the end$o'$'ile
ma( be allo6ed as an e%tension, although it is illegal a&&ording to 932. Cou should a5oid this
te&hniKue i' (ou 6ish to 6rite portable programs.
Rexx onl( -eeps one &urrent read position and one &urrent 6rite position 'or ea&h stream. So both
line$6ise and &hara&ter$6ise reading as 6ell as positioning o' the &urrent read position 6ill operate
on the same &urrent read position, and similarl( 'or the &urrent 6rite position.
Dhen repositioning line$6ise, the &urrent 6rite position is set to the 'irst &hara&ter o' the line
positioned at. !o6e5er, i' positioning &hara&ter$6ise so that the &urrent read position is in the
middle o' a line in the 'ile, a subseKuent &all to ;I+I+BC 6ill read 'rom Fand in&ludingG the
&urrent position until the ne%t end$o'$line mar-er. 9hus, ;I+I+BC might under some
&ir&umstan&es return onl( the last part o' a line. Similarl(, i' the &urrent 6rite position has been
positioned in the middle o' an e%isting line b( &hara&ter$6ise positioning, and ;I+OU,BC is
&alled, then the line 6ritten out be&omes the last part o' the line stored in the stream.
/ote that i' (ou 6ant to reposition the &urrent 6rite position using a line &ount, the stream ma(
ha5e to be open 'or read, too. 9his is be&ause the interpreter ma( ha5e to read the &ontents o' the
stream in order to 'ind 6here the lines start and end. 2epending on (our operating s(stem, this ma(
e5en appl( i' (ou reposition using &hara&ter &ount.
Example" Repositioning in empt& files
Sin&e the &urrent read position must be at an e%isting &hara&ter in the stream, it is impossible to
reposition in or read 'rom an empt( stream. Consider the 'ollo6ing &ode:
(ilena%e : //'%6/'es'ing/
call lineou' (ilena%e)) 1 /5 assu%ing 'runca'ion 5/
call linein (ilena%e) 1) <
One might belie5e that this 6ould set the &urrent read and 6rite positions to the start o' the stream.
!o6e5er, assume that the ;I+OU,BC &all trun&ates the 'ile, so that it is Hero b(tes long. 9hen,
the last &all &an ne5er be legal, sin&e there is no b(te in the 'ile at 6hi&h it is possible to position the
&urrent read position. 9here'ore, a +O,."A* &ondition is probabl( raised.
158
Example" Relati*e repositioning
8t is rather di''i&ult to reposition a &urrent read or 6rite position relati5e to the &urrent position. 9he
onl( 6a( to do this 6ithin the de'inition o' the standard is to -eep a &ounter 6hi&h tells (ou the
&urrent position. 9hat is, i' (ou 6ant to mo5e the &urrent read position 'i5e lines ba&-6ards, (ou
must do it li-e this:
(ilena%e : //'%6/1a'a/
linenu% : < E
say lineinB(ilena%e)1<CE linenu% : 1<
1o 0!ile ran1o%B1<<CQ7
say lineinB(ilena%eCE linenu% : linenu%=1
en1
call lineinB(ilena%e)linenu%-5)<CE linenu% : linenu%-5
!ere, the 5ariable linenu% is updated 'or ea&h time the &urrent read position is altered. 9his ma(
not seem to di''i&ult, and it is not in most &ases. !o6e5er, it is nearl( impossible to do this in the
general &ase, sin&e (ou must -eep an a&&ount o' both line numbers and &hara&ter numbers. Setting
one ma( in5alidate the other: &onsider the situation 6here (ou 6ant to reposition the &urrent read
position to the 10
th
&hara&ter be'ore the 100
th
line in the stream. >%&ept 'rom mi%ing line$6ise and
&hara&ter$6ise 8#O F6hi&h &an ha5e strange e''e&tsG, this is nearl( impossible. Dhen repositioning
&hara&ter$6ise, the line number &ount is in5alidated, and 5i&e 5ersa.
9he ;onl(; proper 6a( o' handling this is to allo6 one or more Fnon$standardG S,."3BC built$in
'un&tion operations that returns the &urrent &hara&ter and line &ount o' the stream in the interpreter.
Example" $estro&ing linecount
9his e%ample sho6s ho6 o5er6riting te%t to the middle o' a 'ile &an destro( the line &ount. 8n the
'ollo6ing &ode, 6e assume that the 'ile (oobar e%ists, and &ontains ten lines 6hi&h are ;(irs'
line;, secon1 line, et&. up to ;'en'! line;. 9hen &onsider the 'ollo6ing &ode:
(ilena%e : /(oobar/
say lineinB(ilena%e) 5C /5 says /(i('! line/ 5/
say lineinB(ilena%eC /5 says /si&'! line/ 5/
say lineinB(ilena%eC /5 says /seven'! line/ 5/
call lineou' (ilena%e) /,!is is a very long line/) 5
say lineinB(ilena%e) 5C /5 says /,!is is a very long line/
5/
say lineinB(ilena%eC /5 says /ven'! line/ 5/
say lineinB(ilena%eC /5 says /eig!' line/ 5/
As (ou &an see 'rom the output o' this e%ample, the &all to ;I+OU,BC inserts a long line and
o5er6rites the 'i'th and si%th lines &ompletel(, and the se5enth line partiall(. A'ter6ard, the si%th
line is the remaining part o' the old se5enth line, and the ne6 se5enth line is the old eighth line, et&.
159
2.12 Errors" $isco*er&1 6andling1 and Reco*er&
932 &ontains t6o important impro5ements o5er 931 in the area o' handling errors in stream 8#O:
the +O,."A* &ondition and the S,."3BC built$in 'un&tion. 9he +O,."A* &ondition is
raised 6hene5er a stream 8#O operation did not su&&eed. 9he S,."3BC 'un&tion is used to
retrie5e status in'ormation about a parti&ular stream or to e%e&ute a parti&ular operation 'or a
stream.
Cou &an dis&o5er that an error o&&urred during an 8#O operation in one o' the 'ollo6ing 6a(s: aG it
ma( trigger a S*+,"- &ondition7 bG it ma( trigger a +O,."A* &ondition7 or &G it ma( \ust not
return that data it 6as supposed to. 9here is no &lear border bet6een 6hi&h situations should trigger
S*+,"- and 6hi&h should trigger +O,."A*. >rrors in parameters to the 8#O 'un&tions, li-e a
negati5e start position, is &learl( a S*+,"- &ondition, 6hile reading o'' the end$o'$'ile is eKuall(
&learl( a +O,."A* &ondition. 8n bet6een la( more un&ertain situations li-e tr(ing to position the
&urrent 6rite position a'ter the end$o'$'ile, or tr(ing to read a non$e%istent 'ile, or using an illegal
'ile name.
Some situations are li-el( to be di''erentl( handled in 5arious implementations, but (ou &an assume
that the( are handled as either S*+,"- or +O,."A*. 2e'ensi5e, portable programming reKuires
(ou to &he&- 'or both. 0n'ortunatel(, +O,."A* is not allo6ed in 931, so (ou ha5e to a5oid that
&ondition i' (ou 6ant ma%imum &ompatibilit(. And due to the 5er( la% restri&tions on
implementations, (ou should al6a(s per'orm 5er( stri&t 5eri'i&ation on all data returned 'rom an(
'ile 8#O built$in 'un&tion.
8' neither are trapped, S*+,"- 6ill terminate the program 6hile +O,."A* 6ill be ignored, so the
implementorPs de&ision about 6hi&h o' these to use ma( e5en depend on the se5erit( o' the problem
Fi.e. i' the problem is small, raising S*+,"- ma( be a little too stri&tG. "ersonall(, 8 thin- S*+,"-
should be raised in this &onte%t onl( i' the 5alue o' a parameter is outside its 5alid range 'or all
&onte%ts in 6hi&h the 'un&tion might be &alled.
!"amp$eA .enera$ NOTREADY c1nditi1n hand$er
0nder 932 the ;&orre&t; 6a( to handle +O,."A* &onditions and errors 'rom 8#O operations is
un'ortunatel( 5er( &omple%. 8t is sho6n in this e%ample, in order to demonstrate the pro&edure:
160
%y(ile : /3*@I;.A",/
signal on syn'a& na%e syn_!an1ler
call on no'rea1y na%e IO_!an1ler
1o i:1 'o 1< un'il res:<
res : lineou'B%y(ile) /line #/iC
i( Bres:<C '!en
say /$all 'o ;I+OU,BC 1i1n4' %anage 'o 0ri'e ou'
1a'a/
en1
e&i'
IO_!an1lerH
syn_!an1lerH
(ile : con1i'ionB/A/C
say con1i'ionB/$/C /raise1 (or (ile/ (ile /a' line/
sigl/H/
say / / sourcelineBsiglC
say / S'a'e:/s'rea%B(ile)/S/C /reasonH/ s'rea%B(ile)/A/C
call lineou'B con1i'ionB /A/ CC /5 'ry 'o close 5/
i( con1i'ionB/$/C::/S*+,"-/ '!en
e&i' 1
else
re'urn
/ote the double &he&-ing in this e%ample: 'irst the &ondition handler is set up to trap an(
+O,."A* &onditions, and then the return &ode 'rom ;I+OU,BC is &he&-ed 'or ea&h &all.
As (ou &an see, there is not reall( that mu&h in'ormation that (ou &an retrie5e about 6hat 6ent
6rong. Some s(stems ma( ha5e additional sour&es 'rom 6hi&h (ou &an get in'ormation, e.g. spe&ial
&ommands 'or the S,."3BC built$in 'un&tion, but these are non$standard and should be a5oided
6hen 6riting &ompatible programs.
2.13 Common $ifferences and Problems ith !tream
I.-
9his se&tion des&ribes some o' the &ommon traps and pit'alls o' Rexx 8#O.
2.13.1 ?here Implementations are (lloed to $iffer
93 is rather rela%ed in its spe&i'i&ations o' 6hat an interpreter must implement o' the 8#O s(stem.
8t re&ogniHes that operating s(stems di''er, and that some details must be le't to the implementor to
de&ide, i' Rexx is to be e''e&ti5el( implemented. 9he parts o' the 8#O subs(stem o' Rexx 6here
implementations are allo6ed to di''er, are:
9he 'un&tions ;I+SBC and $9".SBC are not reKuired to return the number o' lines or
&hara&ters le't in a stream. 93 sa(s that i' it is impossible or di''i&ult to &al&ulate the numbers,
these 'un&tions ma( return 1 unless it is absolutel( &ertain that there are no more data le't. 9his
leads to some rather -ludge( programming te&hniKues.
8mplementations are allo6ed to ignore &losing streams, sin&e 93 does not spe&i'( a 6a( to do
161
this. O'ten, the &losing o' streams is implemented as a &ommand, 6hi&h onl( ma-es it more
in&ompatible.
Che&- the implementation$spe&i'i& do&umentation be'ore using the 'un&tion ;I+OU,B(ileC
'or &losing 'iles.
9he di''eren&e in the a&tion o' &losing and 'lushing a 'ile, &an ma-e a Rexx s&ript that 6or-s
under one implementation &rash under another, so this 'eature is o' 5er( limited 5alue i' (ou are
tr(ing to 6rite portable programs.
93 sa(s that be&ause the operating s(stem en5ironments 6ill di''er a lot, and an e''i&ient and
use'ul interpreter is the most important goal, implementations are allo6ed to de5iate 'rom the
standard in an( respe&t ne&essar( in the domain o' 8#O I932J. 9hus, (ou should ne5er assume
an(thing about the 8#O s(stem, as the ;rules; listed in 93 are onl( ad5isor(.
2.13.2 ?here Implementations might $iffer an&a&
8n the se&tion abo5e, some areas 6here the standard allo6s implementations to di''er are listed. 8n
an ideal 6orld, that ought to be the onl( traps that (ou should need to loo- out 'or, but
un'ortunatel(, the 6orld is not ideal. 9here are se5eral areas 6here the reKuirements set up b( the
standard is Kuite high, and 6here implementations are li-el( to di''er 'rom the standard.
9hese areas are:
epositioning at F'or the &urrent 6rite positionG or be(ond the end$o'$'ile ma( be allo6ed. On
some s(stems, to prohibit that 6ould reKuire a lot o' &he&-ing, so some s(stems 6ill probabl(
s-ip that &he&-. At least 'or some operating s(stems, the a&t o' repositioning a'ter end$o'$'ile is
a use'ul 'eature.
0nder 0ni%, it &an be used 'or &reating a d(nami&all( siHed random a&&ess 'ile7 do not bother
about ho6 mu&h spa&e is allo&ated 'or the 'ile, \ust position to the &orre&t ;sloth; and 6rite the
data there. 8' the data 'ile is sparse, holes might o&&ur in the 'ile7 that is parts o' the 'ile 6hi&h
has not been 6ritten, and 6hi&h is all Heros Fand 6hi&h are there'ore not stored on dis-.
Some implementations 6ill use the same position 'or both the &urrent read position and the
&urrent 6rite position to o5er&ome these implementations. Dhene5er (ou are doing a read, and
the pre5ious operation 6as a 6rite For 5i&e 5ersaG, it is ma( pro5e use'ul to reposition the
&urrent read For 6riteG position.
9here might be a ma%imum linesiHe 'or (our Rexx interpreter. At least the 50Mb limit on string
length ma( appl(.
!andling the situation 6here another program 6rites data to a 'ile 6hi&h is used b( the Rexx
interpreter 'or reading.
2.13.3 LINES() and CHARS() are Inaccurate
:e&ause o' the large di''eren&es bet6een 5arious operating s(stems, Rexx allo6s some 'uHH in the
implementation o' the ;I+SBC and $9".SBC built$in 'un&tions. Sometimes, it is di''i&ult to
&al&ulate the number o' lines or &hara&ters in a stream7 generall( be&ause the storage 'ormat o' the
'ile o'ten reKuires a linear sear&h through the 6hole stream to determine that number. 9hus, Rexx
162
allo6s an implementation to return the 5alue 1 'or an( situation 6here the real number is di''i&ult
or impossible to determine. >''e&ti5el(, an implementation &an restri&t the domain o' return 5alues
'or these t6o 'un&tions onl( 1 and < 'rom these t6o 'un&tions.
,an( operating s(stems store lines using a spe&ial end$o'$line &hara&ter seKuen&e. 1or these
s(stems, it is 5er( time$&onsuming to &ount the number o' lines in a 'ile, as the 'ile must be s&anned
'or su&h &hara&ter seKuen&es. 9hus, it is 5er( tempting 'or an implementor to return the 5alue 1 'or
an( situation 6here there are more than Hero lines le't.
A similar situation arises 'or the number o' &hara&ters le't, although it is more &ommon to -no6 this
number, thus it is generall( a better &han&e o' $9".SBC returning the true number o' &hara&ters le't
than ;I+SBC returning the true number o' lines le't.
!o6e5er, (ou &an be 'airl( sure that i' an implementation returns a number greater than 1, then that
number is the real number o' lines For &hara&tersG le't in the stream. And simultaneousl(, i' the
number returned is <, then there is no lines For &hara&tersG le't to be read in the stream. :ut i' the
number is 1, then (ou 6ill ne5er -no6 until (ou ha5e tried.
Example" /ile reading idiom
9his e%ample sho6s a &ommon idiom 'or reading all &ontents o' a 'ile into Rexx 5ariables using the
;I+SBC and ;I+I+BC built$in 'un&tions.
i : 1
signal on no'rea1y
lle(' : linesB(ileC
1o 0!ile lle('Q<
1o i:i 'o i=lle('
line.i : lineinB(ileC
en1
lle(' : linesB(ileC
en1
no'rea1yH
lines.< : i-1
!ere, the t6o nested loops iterates o5er all the data to be read. 9he innermost loop reads all data
&urrentl( a5ailable, 6hile the outermost loop &he&-s 'or more a5ailable data. 8mplementations
ha5ing a ;I+SBC that return onl( < and 1 6ill generall( iterate the outermost loop man( times7
6hile implementations that returns the ;true; number 'rom ;I+SBC generall( onl( iterates the
outermost loop on&e.
9here is onl( one pla&e in this &ode that ;I+I+BC is &alled. 9he I 5ariable is in&remented at
onl( one pla&e, and the 5ariable ;I+S.< is set in one &lause, too. Some redundan&( &an be
remo5ed b( setting the J9I; e%pression to:
1o 0!ile 0or1BvalueB/lle('/)linesB(ileCC lle(')#CQ<
9he t6o assignments to the ;;@, 5ariable must be remo5ed. 9his ma( loo- more &ompli&ated,
163
but it de&reases the number o' &lauses ha5ing a &all to ;I+SBC 'rom t6o till one. !o6e5er, it is
less &ertain that this se&ond solution is more e''i&ient, sin&e using V";UBC built$in 'un&tion &an
be ine''i&ient o5er ;normal; 5ariable re'eren&es.
2.13.4 The #ast #ine of a !tream
!o6 to handle the last line in a stream is sometimes a problem. 8' (ou use a s(stem that stores end$
o'$lines as spe&ial &hara&ter seKuen&es, and the last part o' the data o' a stream is an unterminated
line, then 6hat is returned 6hen (ou tr( to read that part o' dataS
9here are three possible solutions: 1irst, it ma( interpret the end$o'$'ile itsel' as an impli&it end$o'$
line, in this &ase, the partial part o' the line is returned, as i' it 6as properl( terminated. Se&ond, it
ma( raise the +O,."A* &ondition, sin&e the end$o'$'ile 6as en&ountered during reading. 9hird, i'
there is an( &han&e o' additional data being appended, it ma( 6ait until su&h data are a5ailable. 9he
se&ond and third approa&hes are suitable 'or persistent and transient 'iles, respe&ti5el(.
9he 'irst approa&h is sometimes en&ountered. 8t has some problems though. 8' the end o' a stream
&ontains the data "I$S+;Q-*R, then it might return the string -*R as the last line o' the stream.
!o6e5er, suppose the last line 6as an empt( line, then the last part o' the stream 6ould be:
"I$S+;Q. 1e6 6ould argue that there is an( line in this stream a'ter the line "I$. 9hus, the
de&ision 6hether the end$o'$'ile is an impli&it end$o'$line depends on 6hether the 6ould$be last line
has Hero length or not.
An pragmati& solution is to let the end$o'$'ile onl( be an impli&it end$o'$'ile i' the &hara&ters
immediatel( in 'ront o' it are not an e%pli&it end$o'$line &hara&ter seKuen&e.
!o6e5er, 93 gi5es some indi&ations that an end$o'$'ile is not an impli&it end$o'$line. 8t sa(s that
;I+SBC returns the number o' &omplete lines le't, and that ;I+I+BC returns a &omplete line.
On the other hand, the end$o'$line seKuen&e is not rigidl( de'ined b( 93, so an implementor is
almost 'ree to de'ine end$o'$line in \ust about an( terms that are &om'ortable. 9hus, the last line o' a
stream ma( be a sour&e o' problem i' it is not e%pli&itl( terminated b( an end$o'$line.
2.13.2 -ther Parts of the I.- !&stem
9his se&tion lists some o' the other parts o' Rexx and the en5ironments around Rexx that ma( be
&onsidered a part o' the 8#O s(stem.
+S4a-=.,
9he sta&- be used to &ommuni&ate 6ith e%ternal en5ironments. At the Rexx side, the
inter'a&e to the sta&- is the instru&tions PUS9, PU;;, P".S PU;;, and UUU7 and the
built$in 'un&tion UUUABC. 9hese &an be used to &ommuni&ate 6ith e%ternal programs b(
storing data to be trans'erred on the sta&-.
+The STREAM() b35l4156 f36-45o6.,
9his 'un&tion is used to &ontrol 5arious aspe&ts about the 'iles manipulated 6ith the other
standard 8#O 'un&tions. 9he standard sa(s 5er( little about this 'un&tion, and lea5es it up to
the implementor to spe&i'( the rest. Operations li-e opening, &losing, trun&ating, and
&hanging modes
+The SAY 56(4r3-45o6.,
9he S"* instru&tion &an be used to 6rite data to the de'ault output stream. 8' (ou use
redire&tion, (ou &an indire&tl( use it to 6rite data to a 'ile.
164
+The ADDRESS 56(4r3-45o6.,
9he "AA.SS instru&tion and &ommands &an be used to operate on 'iles, depending on the
po6er o' (our host en5ironments and operating s(stem.
+The !ALUE() b35l4156 f36-45o6.,
9he 'un&tion V";UBC, 6hen used 6ith three parameters, &an be used to &ommuni&ate 6ith
e%ternal host en5ironments and the operating s(stem. !o6e5er, this depends on the
implementation o' (our interpreter.
+SAA A!I.,
9he SAA A"8 pro5ides se5eral operations that &an be used to &ommuni&ate bet6een
pro&esses. 8n general, SAA A"8 allo6s (ou to per'orm the operations listed abo5e 'rom a
binar( program 6ritten in a language other than Rexx.
And o' &ourse, 8#O is per'ormed 6hene5er a Rexx program or e%ternal 'un&tion is started.
2.13.3 Implementation8!pecific Information
9his se&tion des&ribes some implementations o' stream 8#O in Rexx. 0n'ortunatel(, this has
be&ome a 5er( large se&tion, re'le&ting the 'a&t that stream 8#O is an area o' man( s(stem$spe&i'i&
solutions.
8n addition, the 5ariations 6ithin this topi& are rather large. egina implements a set o' 'un&tions
that are 5er( &lose to that o' 932. 9he other e%treme are Ae%% and :e%%, 6hi&h &ontain a set o'
'un&tions 6hi&h is 5er( &lose to the standard 8#O librar( o' the C programming language.
2.13.5 !tream I.- in Regina :.:5a
egina implements stream 8#O in a 'ashion that &losel( resembles ho6 it is des&ribed in 932. 9he
'ollo6ing list gi5es the rele5ant s(stem$spe&i'i& in'ormation.
+Na*e( for (4a60ar0 (4rea*(.,
egina uses Ss'1ou'Q and Ss'1inQ as names 'or the standard output and input streams.
/ote that the angle bra&-ets are part o' the names. Cou ma( also a&&ess the standard error
stream Fon s(stems supporting this streamG under the name Ss'1errQ. 8n addition, the
nullstring is ta-en to be eKui5alent to an empt( 'irst parameter in the 8#O$related built$in
'un&tions.
+I*%l5-54 o%e656g.,
egina impli&itl( opens an( 'ile 6hene5er it is 'irst used.
8' the 'irst operation is a read, it 6ill be opened in read$onl( mode. 8' the 'irst operation is a
6rite, it is opened in read$6rite mode. 8n this &ase i' the read$6rite opening does not
su&&eed, the 'ile is opened in 6rite$onl( mode. 8' the 'ile e%ists, the opening is non$
destru&ti5e, i.e. that the 'ile is not trun&ated or o5er6ritten 6hen opened, else it is &reated i'
opened in read$6rite mode.
8' (ou name a 'ile &urrentl( open in read$onl( mode in a 6rite operation, egina &loses the
'ile, and reopens it in read$6rite mode. 9he onl( e%&eption is 6hen (ou &all ;I+OU,BC
6ith both se&ond and third arguments unspe&i'ied, 6hi&h al6a(s &loses a 'ile, both 'or
reading and 6riting. Similarl(, i' the 'ile 6as opened in 6rite$onl( mode, and (ou use it in a
read operation, egina &loses and reopens in read$6rite mode.
9his impli&it reopening is enabled b( de'ault. Cou &an turn it o'' b( unsetting the e%tension
165
&6lici'O6en.
+Se%ara4e -3rre64 %o(545o6(.,
9he en5ironment in 6hi&h egina operates FA/S8 C and "OS8AG does not allo6 separate
read and 6rite positions, but onl( supplies one position 'or both operations. egina handles
this b( maintaining the t6o positions internall(, and mo5e the ;real; &urrent position ba&-
and 'orth depending on 6hether a read or 6rite operation is ne%t.
+S>a%%56g o34 f5le 0e(-r5%4or(.,
8n order to de'end itsel' against ;open$man($&lose$none; programming, egina tries to
;s6ap out; 'iles that ha5e been unused 'or some time. Assume that (our operating s(stem
limits egina to 100 simultaneousl( open 'iles7 6hen (our tr( to open (our 101
st
'ile, egina
&loses the least re&entl( used stream, and re&(&les its des&riptor 'or the ne6 'ile. Cou &an
enable or disable this re&(&ling 6ith the S0a6@ileP'r e%tension.
2uring this re&(&ling, egina onl( &loses the 'ile in the operating s(stem, but retains all 5ital
in'ormation about the 'ile itsel'. 8' (ou re$a&&ess the 'ile later, egina reopens it, and
positions the &urrent read and 6rite positions at the &orre&t Fi.e. pre5iousG positions. 9his
introdu&es some un&ertainties into stream pro&essing. enaming a 'ile a''e&ts it onl( i' it
gets s6apped out. Sin&e the s6ap operation is something the users do not see, it &an &ause
some strange e''e&ts.
egina 6ill not allo6 a transient stream to be s6apped out, sin&e the( o'ten are &onne&ted to
some sort o' a&ti5e partner in the other end, and &losing the 'ile might -ill the partner or
ma-e it impossible to reestablish the stream. So onl( persistent 'iles are s6apped out. 9hus,
(ou &an still 'ill the 'ile table in egina.
+$%l5-54 o%e656g a60 -lo(56g.,
egina allo6s streams to be e%pli&itl( opened or &losed through the use o' the built$in
'un&tion S,."3BC. 9he e%a&t s(nta% o' this 'un&tion is des&ribed in se&tion stream. Old
5ersions o' egina supported t6o non$standard built$in 'un&tions OP+BC and $;OSBC
'or these operations. 9hese 'un&tions are still supported 'or &ompatibilit( reasons, but might
be remo5ed in 'uture releases. 9heir a5ailabilit( is &ontrolled b( the O6enIi( and
$loseIi( e%tensions.
+Tr36-a45o6 af4er >r5456g l56e(.,
8' (ou reposition line$6ise the &urrent 6rite position to the middle o' a 'ile, egina trun&ates
the 'ile at the ne6 position. 9his happens 6hether data is 6ritten during the ;I+OU,BC or
not. 8' not, the 'ile might &ontain hal' a line, some lines might disappear, and the line&ount
6ould in general be disrupted. 9he a5ailabilit( o' this beha5ior is &ontrolled b(
;ineOu',runc, 6hi&h is turned on b( de'ault.
0n'ortunatel(, the operation o' trun&ating a 'ile is not part o' "OS8A, and it might not e%ist
on all s(stems, so on some rare s(stems, this trun&ating 6ill not o&&ur. 8n order to be able to
trun&ate a 'ile, (our ma&hine must ha5e the ('runca'eBC s(stem &all in $. 8' (ou donPt
ha5e this, the trun&ating 'un&tionalit( is not a5ailable.
+"a-h56g 56fo o6 l56e( lef4.,
Dhen egina e%e&utes the built$in 'un&tion ;I+SBC 'or a persistent stream, it &a&hes the
number o' lines le't as an attribute to the stream. 8n subseKuent &alls to ;I+I+BC, this
number is updated, so that subseKuent &alls to ;I+SBC &an retrie5e the &a&hed number
instead o' ha5ing to re$s&an the rest o' the stream, pro5ided that the number is still 5alid.
Some operations 6ill in5alidate the &ount: repositioning the &urrent read position7 reading
using the &hara&ter oriented 8#O, i.e. $9".I+BC7 and an( 6rite operation b( the same
166
interpreter on the stream. 8deall(, an( 6rite operation should in5alidate the &ount, but that
might reKuire a large o5erhead be'ore an( operation, in order to &he&- 6hether the 'ile has
been 6ritten to b( other programs.
9his 'un&tionalit( &an be &ontrolled b( the e%tension &alled $ac!e;ine+o, 6hi&h is
turned on b( de'ault. /ote that i' (ou turn that o'', (ou &an e%perien&e a serious de&rease in
per'orman&e.
9he 'ollo6ing e%tra built$in 'un&tions relating to stream 8#O are de'ined in egina. 9he( are
pro5ided 'or e%tra support and &ompatibilit( 6ith other s(stems. 9heir support ma( be dis&ontinued
in later 5ersions, and the( are li-el( to be mo5ed to a librar( o' e%tra support.
CLOSE(%('ea,i4)
Closes the stream named b( strea#id. 9his stream must ha5e been opened b( impli&it open or b(
the OP+ 'un&tion &all earlier. 9he 'un&tion returns 1 i' there 6as an( 'ile to &lose, and < i' the 'ile
6as not opened. /ote that the return 5alue does not indi&ate 6hether the &losing 6as su&&ess'ul.
Cou &an use the e%tension named $loseIi( 6ith the OP,IO+S instru&tion to sele&t or remo5e
this 'un&tion. 9his 'un&tion is no6 obsolete, instead (ou should use:
S,."3B s'rea%i1) /$o%%an1/) /$;OS/ C
C3OS>F#y&ileG 1 i' stream 6as open
C3OS>FP/OS0C!183>PG 0 i' stream didnPt e%ist
OPEN(%('ea,i4$a22e%%)
Opens the stream named strea#id 6ith the a&&ess access. 8' access is not spe&i'ied, the a&&ess .
6ill be used. access ma( be the 'ollo6ing &hara&ters. Onl( the 'irst &hara&ter o' the access is
needed.
+R,
FeadG Open 'or read a&&ess. 9he 'ile pointer 6ill be positioned at the start o' the 'ile, and
onl( read operations are allo6ed.
+W,
FDriteG Open 'or 6rite a&&ess and position the &urrent 6rite position at the end o' the 'ile.
An error is returned i' it 6as not possible to get appropriate a&&ess.
9he return 5alue 'rom this 'un&tion is either 1 or <, depending on 6hether the named stream is in
opened state a'ter the operation has been per'ormed.
/ote that i' (ou open the 'iles ;(oobar; and ;./(oobar; the( 6ill point to the same ph(si&al
'ile, but egina interprets them as t6o di''erent streams, and 6ill open a internal 'ile des&riptor 'or
ea&h one. 8' (ou tr( to open an alread( open stream, using the same name, it 6ill ha5e no e''e&t.
167
Cou &an use the e%tension O6enIi( 6ith the OP,IO+S instru&tion to &ontrol the a5ailabilit( o'
this 'un&tion. 9his 'un&tion is no6 obsolete, but is still -ept 'or &ompatibilit( 6ith other interpreters
and older 5ersions o' egina. 8nstead, 6ith egina (ou should use:
S,."3B s'rea%i1) /$/) /."A/D/J.I,/D/"PP+A/D/UPA",/ C
O">/Fm('ile, P6ritePG 1 ma(be, i' su&&ess'ul
O">/Fpass6d, PDritePG 0 ma(be, i' no 6rite a&&ess
O">/FP2A9AP, P>A2PG 0 ma(be, i' su&&ess'ul
9he return 5alue 'rom this 'un&tion is either 1 or <, depending on 6hether the named stream is in
opened state a'ter the operation has been per'ormed.
2.13.7 /unctionalit& to be Implemented #ater
9his se&tion lists the 'un&tionalit( not (et in egina, but 6hi&h is intended to be added later. ,ost
o' these are 'i%es to problems, &ompatibilit( modes, et&.
+I605re-4 6a*56g of (4rea*(.,
Currentl(, streams are named dire&tl(, 6hi&h is a &on5enient. !o6e5er, there are a 'e6
problems: 'or instan&e, it is di''i&ult to 6rite to a 'ile 6hi&h name is Ss'1ou'Q, simpl(
be&ause that is a reser5ed name. 9o 'i% this, an indire&t naming s&heme 6ill be pro5ided
through the S,."3BC< built$in 'un&tion. 9he 'un&tionalit( 6ill resemble the OP+BC
built$in 'un&tion o' Ae%%.
+"o6(5(4e6-e 56 f5leha60le (>a%%56g.,
Dhen a 'ile handle is &urrentl( s6apped out in order to a5oid 'illing the s(stem 'ile table,
5er( little &he&-ing o' &onsisten&( is &urrentl( per'ormed. At least, 5ital in'ormation about
the 'ile should be retained, su&h as the inode and 'ile s(stem 'or 0ni% ma&hines retrie5al b(
the (s'a'BC &all. Dhen the 'ile is s6apped in again, this in'ormation must be &he&-ed
against the 'ile 6hi&h is reopened. 8' there is a mismat&h, +O,."A* should be raised.
Similarl(, 6hen reopening a 'ile be&ause o' a ne6 a&&ess mode is reKuested, the same
&he&-ing should be per'ormed.
+F5le( >54h hole(.,
egina 6ill be &hanged to allo6 it to generate 'iles 6ith holes 'or s(stem 6here this is
rele5ant. Although standard Rexx does not allo6 this, it is a 5er( &ommon programming
idiom 'or &ertain s(stems, and should be allo6ed. 8t 6ill, ho6e5er, be &ontrollable through a
e%tension &alled S6arse@iles.
2.13.9 !tream I.- in (Rexx 1.12
Ae%% di''ers &onsiderabl( 'rom standard Rexx 6ith respe&t to stream 8#O. 8n 'a&t, none o' the
standard stream 'un&tionalit( o' Rexx is a5ailable in Ae%%. 8nstead, a &ompletel( distin&t set o'
'un&tions are used. 9he di''eren&es are so big, that it is useless to des&ribe Ae%% stream 8#O in
terms o' standard Rexx stream 8#O, and e5er(thing said so 'ar in this &hapter is irrele5ant 'or
Ae%%. 9here'ore, 6e e%plain the Ae%% 'un&tionalit( 'rom s&rat&h.
All in all, the Ae%% 'ile 8#O inter'a&e resembles the 'un&tions o' the Standard C 8#O librar(,
probabl( be&ause Ae%% is 6ritten in C, and the Ae%% 8#O 'un&tions are ;\ust; inter'a&es to the
underl(ing C 'un&tions. Cou ma( 6ant to &he&- up the do&umentation 'or the A/S8 C 8#O librar( as
des&ribed in IA/S8CJ, IMJ, and I"O"laugerJ.
168
Ae%% uses a t6o le5el naming s&heme 'or streams. 9he 'ile names are bound to a stream name
using the OP+BC built$in 'un&tion. 8n all other 8#O 'un&tions, onl( the stream name is used.
OPEN(name$filename)$mode*)
Cou use the OP+BC built$in 'un&tion to open a stream &onne&ted to a 'ile &alled &ilena#e in
Amiga2OS. 8n subseKuent 8#O &alls, (ou re'er to the stream as na#e. 9hese t6o names &an be
di''erent.
9he na#e parameter &annot alread( be in use b( another stream. 8' so, the OP+BC 'un&tion 'ails.
/ote that the na#e parameter is &ase$sensiti5e. 9he &ilena#e parameter is not stri&tl( &ase$sensiti5e:
the &ase used 6hen &reating a ne6 'ile is preser5ed, but 6hen re'erring to an e%isting 'ile, the name
is &ase$insensiti5e. 9his is the usual beha5ior o' Amiga2OS.
8' an( o' the other 8#O operations uses a stream name that has not been properl( opened using
OP+BC, that operation 'ails, be&ause Ae%% has no auto$open$on$demand 'eature.
9he optional parameter #ode &an be an( o' .ea1, Jri'e, or "66en1. 9he mode .ea1 opens an
e%isting 'ile and sets the &urrent position to the start o' the 'ile. 9he mode "66en1 is identi&al to
.ea1, but sets the &urrent positions to the end$o'$'ile. 9he mode Jri'e &reates a ne6 'ile, i.e. i' a
'ile 6ith that name alread( e%ists, it is deleted and a ne6 'ile is &reated. 9hus, 6ith Jri'e (ou
al6a(s start 6ith an empt( 'ile. /ote that the terms ;read,; ;6rite,; and ;append; are onl( remotel(
&onne&ted to the mode in 6hi&h the 'ile is opened. :oth reading and 6riting are allo6ed 'or all o'
these three modes7 the mode names onl( re'le&t the t(pi&al operations o' these modes.
9he result 'rom OP+BC is a boolean 5alue, 6hi&h is 1 i' a 'ile b( the spe&i'ied na#e 6as
su&&ess'ull( opened during the OP+BC &all, and < other6ise.
9he number o' simultaneousl( open 'iles is no problem be&ause Amiga2OS allo&ates 'iles handles
d(nami&all(, and thus onl( limited b( the a5ailable memor(. One s(stem managed 2000
simultaneousl( open 'iles during a test.
O">/FPin'ileP, P6or-:2ata1ilePG 1 i' su&&ess'ul
O">/FP6or-P, PA,:1oo:arP, PeadPG 0 i' didnPt e%ist
O">/FPoutputP, P9mp1ileP, PDPG 1 FreG&reates 'ile
CLOSE(name)
Cou use the $;OSBC built$in 'un&tion to &lose a stream. 9he parameter na#e must mat&h the 'irst
parameter in a &all to OP+BC earlier in the same program, and must re'er to an open stream. 9he
return 5alue is a boolean 5alue that re'le&ts 6hether there 6as a 'ile to &lose Fbut not 6hether it 6as
su&&ess'ull( &losedG.
C3OS>FPin'ilePG 1 i' stream 6as pre5iousl( open
169
C3OS>FPout'ilePG 0 i' stream 6asnPt pre5iousl( open
WRITELN(name$string)
9he J.I,;+BC 'un&tion 6rites the &ontents o' string as a line to the stream na#e. 9he na#e
parameter must mat&h the 5alue o' the 'irst parameter in an earlier &all to OP+BC, and must re'er
to an open stream. 9he data 6ritten is all the &hara&ters in string immediatel( 'ollo6ed b( the
ne6line &hara&ter FASC88 <Ctrl$O> 'or Amiga2OSG.
9he return 5alue is the number o' &hara&ters 6ritten, in&luding the terminating ne6line. 9hus, a
return 5alue o' < indi&ates that nothing 6as 6ritten, 6hile a 5alue 6hi&h is one more than the
number o' &hara&ters in string indi&ates that all data 6as su&&ess'ull( 6ritten to the stream.
Dhen 6riting a line to the middle o' a stream, the old &ontents is 6ritten o5er, but the stream is not
trun&ated7 there is no 6a( to trun&ate a stream 6ith the Ae%% built$in 'un&tions. 9his o5er6riting
&an lea5e partial lines in the stream.
D89>3/FPtmpP, P!ello, 6orldYPG 1< i' su&&ess'ul
D89>3/FP6or-P, P!i therePG 0 nothing 6as 6ritten
D89>3/FPtmpP, P!i therePG 5 partiall( su&&ess'ul
WRITECH(name$string)
9he J.I,$9BC 'un&tion is identi&al to J.I,;+BC, e%&ept that the terminating ne6line
&hara&ter is not added to the data 6ritten out. 9hus, J.I,;+BC is suitable 'or line$6ise output,
6hile J.I,$9BC is use'ul 'or &hara&ter$6ise output.
D89>C!FPtmpP, P!ello, 6orldYPG 1= i' su&&ess'ul
D89>C!FP6or-P, P!i therePG 0 nothing 6as 6ritten
D89>C!FPtmpP, P!i therePG 5 partiall( su&&ess'ul
READLN(name)
9he ."A;+BC 'un&tion reads a line o' data 'rom the stream re'erred to b( na#e. 9he parameter
na#e must mat&h the 'irst parameter o' an earlier &all to OP+BC, i.e. it must be an open stream.
9he return 5alue is a string o' &hara&ters 6hi&h &orresponds to the &hara&ters in the stream 'rom and
in&luding the &urrent position 'or6ard to the 'irst subseKuent ne6line &hara&ter 'ound. 8' no ne6line
&hara&ter is 'ound, the end$o'$'ile is impli&itl( interpreted as a ne6line and the end$o'$'ile state is
set. !o6e5er, the data returned to the user ne5er &ontains the terminating end$o'$line.
9o di''er bet6een the situation 6here the last line o' the stream 6as impli&itl( terminated b( the
170
end$o'$'ile and 6here it 6as e%pli&itl( terminated b( an end$o'$line &hara&ter seKuen&e, use the
O@BC built$in 'un&tion. 9he O@BC returns 1 in the 'ormer &ase and < in the latter &ase.
9here is a limit in Ae%% on the length o' lines that (ou &an read in one &all to ."A;+BC. 8' the
length o' the line in the stream is more than 1000 &hara&ters, then onl( the 'irst 1000 &hara&ters are
returned. 9he rest o' the line &an be read b( additional ."A;+BC and ."A$9BC &alls. /ote that
6hene5er ."A;+BC returns a string o' e%a&tl( 1000 &hara&ters, then no terminating end$o'$line
6as 'ound, and a ne6 &all to ."A;+BC must be e%e&uted in order to read the rest o' the line.
>A23/FPtmpPG !ello
6orldY
ma(be
>A23/FP6or-PG ma(be, i' unsu&&ess'ul
READCH(name)$length*)
9he ."A$9BC built$in 'un&tion reads &hara&ters 'rom the stream named b( the parameter na#e,
6hi&h must &orrespond to the 'irst parameter in a pre5ious &all to OP+BC. 9he number o'
&hara&ters read is gi5en b( length, 6hi&h must be a non$negati5e integer. 9he de'ault 5alue o'
length is 1.
9he 5alue returned is the data read, 6hi&h has the length &orresponding to the length parameter i' no
errors o&&urred.
9here is a limit in Ae%% 'or the length o' strings that &an be read in one &all to ."A$9BC. 9he
limit is ?55=5 b(tes, and is a limitation in the ma%imum siHe o' an Ae%% string.
>A2C!FPtmpP,=G !el ma(be
>A2C!FPtmpPG l ma(be
>A2C!FPtmpP,?G o 6orl ma(be
EOF(name)
9he O@BC built$in 'un&tion tests to see 6hether the end$o'$'ile has been seen on the stream
spe&i'ied b( na#e, 6hi&h must be an open stream, i.e. the 'irst parameter in a pre5ious &all to
OP+BC.
9he return 5alue is 1 i' the stream is in end$o'$'ile mode, i.e. i' a read operation Feither ."A;+BC
or ."A$9BCG has seen the end$o'$'ile during its operation. !o6e5er, reading the last &hara&ter o'
the stream does not put the stream in end$o'$'ile mode7 (ou must tr( to read at least one &hara&ter
past the last &hara&ter. 8' the stream is not in end$o'$'ile mode, the return 5alue is <.
Dhene5er the stream is in end$o'$'ile mode, it sta(s there until a &all to S_BC is made. /o read
or 6rite operation &an remo5e the end$o'$'ile mode, onl( S_BC Fand &losing 'ollo6ed b(
reopeningG.
171
>O1FPtmpPG 0 ma(be
>O1FP6or-PG 1 ma(be
SEE;(name$offset)$mode*)
9he S_BC built$in 'un&tion repositions the &urrent position o' the 'ile spe&i'ied b( the parameter
na#e, 6hi&h must &orrespond to an open 'ile, i.e. to the 'irst parameter o' a pre5ious &all to
OP+BC. 9he &urrent position in the 'ile is set to the b(te re'erred to b( the parameter o&&set. /ote
that o&&set is Hero$based, so the 'irst b(te in the 'ile is numbered <. 9he 5alue returned is the &urrent
position in the 'ile a'ter the see- operation has been &arried through, using Ieginning mode.
8' the &urrent position is attempted set past the end$o'$'ile or be'ore the beginning o' the 'ile, then
the &urrent position is not mo5ed, and the old &urrent position is returned. /ote that it is legal to
position at the end$o'$'ile, i.e. the position immediatel( a'ter the last &hara&ter o' the 'ile. 8' a 'ile
&ontains 12 &hara&ters, the 5alid range 'or the resulting ne6 &urrent position is 0$12.
9he last parameter, #ode, &an ta-e an( o' the 'ollo6ing 5alues:
Ieginning, $urren', or n1. 8t spe&i'( the base o' the see-ing, i.e. 6hether it is relati5e to the
'irst b(te, the end$o'$'ile position, or the old &urrent position. 1or instan&e: 'or a 20 b(te 'ile 6ith
&urrent position =, then o''set @ 'or base Ieginning is eKui5alent to o''set $1= 'or base n1 and
o''set < 'or $urren'. /ote that onl( the 'irst &hara&ter o' the #ode parameter is reKuired, the rest
o' that parameter is ignored.
S>>MFPtmpP, 12, P:PG 12 i' su&&ess'ul
S>>MFPtmpP, $<, P:eginPG 12 i' pre5iousl( at 12
S>>MFPtmpP, $10, P>PG 20 i' length is =0
S>>MFPtmpP, 5G 1@ i' pre5iousl( at 12
S>>MFPtmpP, 5, PCel&iusPG 1@ onl( 'irst &hara&ter in mode matters
S>>MFPtmpP, 0, P:PG 0 al6a(s to start o' 'ile
2.13.1: )ain $ifferences from !tandard Rexx
/o6, as the 'un&tionalit( has been e%plained, let me point out the main &on&eptual di''eren&es 'rom
standard Rexx7 the( are:
+"3rre64 %o(545o6.,
Ae%% does not di''er bet6een a &urrent read and 6rite position, but uses a &ommon &urrent
position 'or both reading and 6riting. 1urther, this &urrent position F6hi&h it is &alled in this
do&umentationG &an be set to an( b(te 6ithin the 'ile, and to the end$o'$'ile position. /ote
that the &urrent position is Hero$based.
+I605re-4 6a*56g.,
9he stream 8#O operations in Ae%% do not get a parameter 6hi&h is the name o' the 'ile.
8nstead, Ae%% uses an indire&t naming s&heme. 9he OP+BC built$in 'un&tion binds a
Rexx stream name 'or a 'ile to a named 'ile in the Amiga2OS operating s(stem7 and later,
172
onl( the Rexx stream name is used in other stream 8#O 'un&tions operating on that 'ile.
+S%e-5al (4rea* 6a*e(.,
9here are t6o spe&ial 'ile names in Ae%%: S,AOU, and S,AI+, 6hi&h re'er to the
standard input 'ile and standard output 'ile. Dith respe&t to the indire&t naming s&heme,
these are not 'ile names, but names 'or open streams7 i.e. the( &an be used in stream 8#O
operations other than OP+BC. 1or some reason, is it possible to &lose S,AI+ but not
S,AOU,.
+NOTREADY 6o4 (3%%or4e0.,
Ae%% has no +O,."A* &ondition. 8nstead, (ou must dete&t errors b( &alling O@BC and
&he&-ing the return &odes 'rom ea&h 8#O operations.
+O4her 4h56g( *5((56g.,
8n Ae%%, all 'iles must be e%pli&itl( opened. 9here is no 6a( to reposition line$6ise, e%&ept
'or reading lines and -eeping a &ount (oursel'.
O' &ourse, Ae%% also has a lot o' 'un&tionalit( 6hi&h is not part o' standard Rexx, li-e relati5e
repositioning, e%pli&it opening, an end$o'$'ile indi&ator, et&. :ut this 'un&tionalit( is des&ripti5e
abo5e in the des&riptions o' e%tended built$in 'un&tions, and it is o' less interest here.
Dhen an Ae%% s&ript has opened a 'ile in Jri'e mode, other Ae%% s&ripts are not allo6ed to
a&&ess that 'ile. !o6e5er, i' the 'ile is opened in .ea1 or "66en1 mode, then other Ae%% s&ripts
&an open the 'ile too, and the same state o' the &ontents o' the 'ile is seen b( all s&ripts.
/ote that it is di''i&ult to translate bet6een using standard Rexx stream 8#O and Ae%% stream 8#O.
8n parti&ular, the main problem Fother than missing 'un&tionalit( in one o' the s(stemsG is the
pro&essing o' end$o'$lines. 8n standard Rexx, the end$o'$'ile is dete&ted b( &he&-ing 6hether there
is more data le't, 6hile in Ae%% one &he&-s 6hether the end$o'$'ile has been read. 9he 'ollo6ing
is a &ommon standard Rexx idiom:
6hile linesFP'ilePG>0 #X 'or ea&h line a5ailable X#
sa( lineinFP'ilePG #X pro&ess it X#
end
8n Ae%% this be&omes:
'%6 : rea1lnB/(ile/C /5 a''e%6' 'o rea1 (irs' line 5/
1o un'il eo(B/(ile/C /5 i( O@ 0as no' seen 5/
say '%6 /5 6rocess line 5/
'%6 : rea1lnB/(ile/C /5 a''e%6' 'o rea1 ne&' line 5/
en1
8t is hard to me&hani&all( translate bet6een them,
be&ause o' the la&- o' an O@BC built$in 'un&tion in standard Rexx, and the la&- o' a ;I+SBC
built$in 'un&tion in Ae%%.
/ote that in the Ae%% e%ample, an improperl( terminated last line is not read as an independent
line, sin&e ."A;+BC sear&hes 'or an end$o'$line &hara&ter seKuen&e. 9hus, in the last in5o&ation
'%6 is set to the last unterminated line, but O@BC returns true too. 9o ma-e this di''erent, ma-e
the U+,I; subterm o' the AO loop &he&- 'or the e%pression O@B/(ile/C XX ,3PSQ4.
173
9he limit o' 1000 &hara&ters 'or ."A;+BC means that a generi& line reading routine in Ae%%
must be similar to this:
rea1lineH 6roce1ure
6arse arg (ilena%e
line : //
1o un'il leng'!B'%6lineCS1<<<
'%6line : rea1lnB(ilena%eC
line : line DD '%6line
en1
re'urn line
9his routine &alls ."A;+BC until it returns a line that is shorter than 1000 &hara&ters. /ote that
end$o'$'ile &he&-ing is ignored, sin&e ."A;+BC returns an empt( string a the end$o'$stream.
2.13.11 !tream I.- in %Rexx 1.:b
:e%% &ontains a set o' 8#O 6hi&h sho6s 5er( &lose relations 6ith the C programming language 8#O
librar(. 8n 'a&t, (ou should &onsider &onsulting the C librar( do&umentation 'or in$depth
do&umentation on this 'un&tionalit(.
:e%% &ontains a t6o$le5el naming s&heme: in Rexx, streams are re'erred to b( a stream handle,
6hi&h is an integer7 in the operating s(stem 'iles are re'erred to b( a 'ile name, 6hi&h is a normal
string. 9he 'un&tion OP+BC is used to bind a 'ile name to a stream handle. !o6e5er, :e%% 8#O
'un&tions generall( ha5e the abilit( to get a re'eren&e either as a 'ile name and a stream handle, and
open the 'ile i' appropriate. !o6e5er, i' the name o' a 'ile is an integer 6hi&h &an be interpreted as a
'ile des&riptor number, it is interpreted as a des&riptor rather than a name. Dhene5er (ou use :e%%
and 6ant to program robust &ode, al6a(s use OP+BC and the des&riptor.
8' a 'ile is opened b( spe&i'(ing the name in a 8#O operation other than OP+BC, and the name is an
integer and onl( one or t6o higher than the highest &urrent 'ile des&riptor, strange things ma(
happen.
1i5e spe&ial streams are de'ined, ha5ing the pseudo 'ile names: SS,AI+Q, SS,AOU,Q,
SS,A..Q, SS,A"U-Q, and SS,AP.+Q7 and are assigned pre$de'ined stream handles 'rom < to
8, respe&ti5el(. 9hese re'er to the de'ault input, de'ault output, and de'ault error output, de'ault
au%iliar( output, and printer output. 9he t6o last generall( re'er to the $O31H and ;P,1H de5i&es
under ,S$2OS. >ither upper or lo6er &ase letter &an be used 6hen re'erring to these 'our spe&ial
names.
!o6e5er, note that i' an( o' these 'i5e spe&ial 'iles are &losed, the( &an not be reopened again. 9he
reopened 'ile 6ill be \ust a normal 'ile, ha5ing the name e.g. SS,AOU,Q.
9here is a 'e6 things (ou should 6at&h out 'or 6ith the spe&ial 'iles. 8#O in5ol5ing the SS,A"U-Q
and SS,AP.+Q &an &ause the "bor') .e'ry) Ignore message to be sho6n on&e 'or ea&h
&hara&ter that 6as attempted read or 6ritten. 8t &an be boring and tedious to ans6er . or I i' the te%t
string is long. 8' " is ans6ered, :e%% terminates.
Cou should ne5er 6rite data to 'ile des&riptor 0 FSS,AI+QG, apparentl(, it 6ill onl( disappear.
174
3i-e6ise, ne5er read data to 'ile des&riptors 1 and 2 FSS,AOU,Q and SS,A..QG, the 'ormer
seems to terminate the program 6hile the latter apparentl( \ust returns the nullstring. Also be &are'ul
6ith reading 'rom 'ile des&riptors = and <, sin&e (our program ma( hang i' no data is a5ailable.
OPEN(file$mode)
9he OP+BC built$in 'un&tion opens a 'ile named b( &ile, in mode #ode, and returns an integer
6hi&h is the number o' the stream handle assigned to the 'ile. 8n general, the stream handle is a non$
negati5e integer, 6here < to 8 are pre$de'ined 'or the de'ault streams. 8' an error o&&urred during
the open operation, the 5alue -1 is returned.
9he #ode parameter spe&i'ies the mode in 6hi&h the 'ile is opened. 8t &onsists o' t6o parts: the
a&&ess mode, and the 'ile mode. 9he a&&ess mode part &onsists o' one single &hara&ter, 6hi&h &an
be r 'or read, 0 'or 6rite, and a 'or append. 8n addition, the = &hara&ter &an be appended to open a
'ile in both read and 6rite mode. 9he 'ile mode part &an also ha5e o' one additional &hara&ter
6hi&h &an be ' 'or te%t 'iles and b 'or binar( 'iles. 9he ' mode is de'ault.
9he 'ollo6ing &ombinations o' = and a&&ess mode are possible:
r is non$destru&ti5e open 'or reading7 0 is destru&ti5e open 'or 6rite$onl( mode7 a is non$
destru&ti5e open 'or in append$onl( mode, i.e. onl( 6rite operations are allo6ed, and all 6rite
operations must be per'ormed at the end$o'$'ile7 r= is non$destru&ti5e open 'or reading and 6riting7
0= is destru&ti5e open 'or reading and 6riting7 and a= is non$destru&ti5e open in append update,
i.e. reading is allo6ed an(6here, but 6riting is allo6ed onl( at end$o'$'ile. 2estru&ti5e mode means
that the 'ile is trun&ated to Hero length 6hen opened.
8n addition, the b and ' &hara&ters &an be appended in order to open the 'ile in binar( or te%t mode.
9hese modes are the same as under C, although the ' mode &hara&ter is stri&tl( not in A/S8 C. Also
note that r, 0, and a are mutuall( e%&lusi5e, but one o' them must al6a(s be present. 9he mode = is
optional, but i' present, it must al6a(s &ome immediatel( a'ter r, 0, or a. 9he ' and b modes are
optional and mutuall( e%&lusi5e7 the de'ault is '. 8' present, ' or b must be the last &hara&ter in the
mode string.
openFPm('ileP,P6PG @ perhaps
openFPno.su&h.'ileP,PrPG $1 i' non$e%istent
openFP&:tmpP,Pr^bPG ? perhaps
8' t6o 'ile des&riptors are opened to the same 'ile, onl( the most re&entl( o' them 6or-s. !o6e5er,
i' the most re&entl( des&riptor is &losed, the least re&entl( starts 6or-ing again. 9here ma( be other
strange e''e&ts too, so tr( a5oid reopening a 'ile that is alread( open.
CLOSE(file)
175
9he $;OSBC built$in 'un&tion &loses a 'ile that is alread( open. 9he parameter &ile &an be either a
stream handle returned 'rom OP+BC or a 'ile name 6hi&h has been opened Fbut 'or 6hi&h (ou do
not -no6n the &orre&t stream handleG.
9he return 5alue o' this 'un&tion seems to be the nullstring in all &ases.
&loseF?G i' open
&loseF@G i' not open
&loseFP'oobarPG perhaps
EOF(file)
9he O@BC built$in 'un&tion &he&-s the end$o'$'ile state 'or the stream gi5en b( &ile, 6hi&h &an be
either a stream des&riptor or a 'ile name. 9he 5alue returned is 1 i' the end$o'$'ile status is set 'or
the stream, and < i' it is &leared. 8n addition, the 5alue -1 is returned i' an error o&&urred, 'or
instan&e i' the 'ile is not open.
9he end$o'$'ile indi&ator is set 6hene5er an attempt 6as made to read at least one &hara&ter past the
last &hara&ter o' the 'ile. /ote that reading the last &hara&ter itsel' 6ill not set the end$o'$'ile
&ondition.
eo'F'ooG 0 i' not at eo'
eo'FP+PG 1 i' at eo'
eo'FPno.su&h.'ilePG $1 i' 'ile isnPt open
READ()file*)$length*)
9he ."ABC built$in 'un&tion reads data 'rom the 'ile re'erred to b( the &ile parameter, 6hi&h &an
be either a 'ile name or a stream des&riptor. 8' it is a 'ile name, and that 'ile is not &urrentl( open,
then :e%% opens the 'ile in mode r'. 9he de'ault 5alue o' the 'irst parameter is the de'ault input
stream. 9he data is read 'rom and in&luding the &urrent position.
8' the length parameter is not spe&i'ied, a 6hole line is read, i.e. reading 'or6ards to and in&luding
the 'irst end$o'$line seKuen&e. !o6e5er, the end$o'$line seKuen&e itsel' is not returned. 8' the
length parameter is spe&i'ied, it must be a non$negati5e integer, and spe&i'ied the number o'
&hara&ters to read.
9he data returned is the data read, e%&ept that i' length is not spe&i'ied, the terminating end$o'$line
seKuen&e is stripped o''. 8' the last line o' a 'ile &ontains a string unterminated b( the end$o'$string
&hara&ter seKuen&e, then the end$o'$'ile is impli&itl( interpreted as an end$o'$line. !o6e5er, in this
&ase the end$o'$'ile state is entered, sin&e the end$o'$stream 6as 'ound 6hile loo-ing 'or an end$o'$
line.
readFP'ooPG one line reads a &omplete line
176
readFP'ooP,5G anoth reads parts o' a line
readF?G er line using a 'ile des&riptor
readFG hello
there
perhaps, reads line 'rom de'ault input
stream
WRITE()file*)$)string*)$dummy**)
9he J.I,BC built$in 'un&tion 6rites a string o' data to the stream spe&i'ied b( the &ile parameter,
or b( de'ault the de'ault output stream. 8' spe&i'ied, &ile &an be either a 'ile name or a stream
des&riptor. 8' it is a 'ile name, and that 'ile is not alread( open, it is opened using 0' mode.
9he data 6ritten is spe&i'ied b( the string parameter.
9he return 5alue is an integer, 6hi&h is the number o' b(tes 6ritten during the operation. 8' the 'ile
is opened in te%t mode, all ASC88 ne6line &hara&ters are translated into ASC88 $.;@ &hara&ter
seKuen&es. !o6e5er, the number returned is not a''e&ted b( this translation7 it remains independent
o' an( te%t o' binar( mode. 0n'ortunatel(, errors 6hile 6riting is seldom trapped, so the number
returned is generall( the number o' &hara&ter that 6as supposed to be 6ritten, independent o'
6hether the( 6as a&tuall( 6ritten or not.
8' a third parameter is spe&i'ied, the data is 6ritten as a line, i.e. in&luding the end$o'$line seKuen&e.
>lse, the data is 6ritten as$is, 6ithout an( end$o'$line seKuen&e. /ote that 6ith :e%%, the third
parameter is &onsidered present i' at least the &omma in 'ront o' it$$the se&ond &omma$$is present.
9his is a bit in&onsistent 6ith the standard operations o' the ".>BC built$in 'un&tion. 9he 5alue o'
the third parameter is al6a(s ignored, onl( its presen&e is &onsidered.
8' the se&ond parameter is omitted, onl( an end$o'$line a&tion is 6ritten, independent o' 6hether the
third parameter is present or not.
6riteFPbarP,PdataPG < 6rites 'our b(tes
6riteFPbarP,PdataP,PnlPG <^SS 6rite a line
6riteFPbarP,PdataP,G <^SS same as pre5ious
SEE;(file)$)offset*)$origin**)
9he S_BC built$in 'un&tion mo5es the &urrent position to a lo&ation in the 'ile re'erred to b( &ile.
9he parameter &ile &an be either a 'ile name F6hi&h must alread( be openG or a stream des&riptor.
9his 'un&tion does not impli&itl( open 'iles that is not &urrentl( open.
9he parameter o&&set determines the lo&ation o' the stream and must be an integer. 8t de'aults to
Hero. /ote that the addressing o' b(tes 6ithin the stream is Hero$based.
9he third parameter &an be an( o' ,O@, $U., or O@, in order to set the re'eren&e point in 6hi&h to
re&on the o&&set lo&ation. 9he three strings re'er to top$o'$'ile, &urrent position, and end$o'$'ile, and
177
either upper or lo6er &ase &an be used. 9he de'ault 5alue is SSS.
9he return 5alue o' this 'un&tion is the absolute position o' the position in the 'ile a'ter the see-
operation has been per'ormed.
9he S_BC 'un&tion pro5ides a 5er( important additional 'eature. Dhene5er a 'ile opened 'or
both reading and 6riting has been used in a read operation and is to be used in a 6rite operation
ne%t For 5i&e 5ersaG, then a &all to S_BC must be per'ormed bet6een the t6o 8#O &alls. 8n other
6ords, a'ter a read onl( a see-ing and reading ma( o&&ur7 a'ter a 6rite, onl( see-ing and 6riting
ma( o&&ur7 and a'ter a see-, reading, 6riting, and see-ing ma( o&&ur.
2.13.12 Problems ith %inar& and Text )odes
0nder the ,S$2OS operating s(stem, the end$o'$line &hara&ter seKuen&e is S$.QS;@Q, 6hile in
C, the end$o'$line seKuen&e is onl( S;@Q. 9his opens 'or some 5er( strange e''e&ts.
Dhen an ,S$2OS 'ile is opened 'or read in te%t mode b( :e%%, all S$.QS;@Q &hara&ter
seKuen&es in 'ile data are translated to S;@Q 6hen trans'erred into the C program. 1urther, :e%%,
6hi&h is a C program, interprets S;@Q as an end$o'$line &hara&ter seKuen&e. !o6e5er, i' the 'ile is
opened in binar( mode, then the 'irst translation 'rom S$.QS;@Q in the 'ile to S;@Q into the C
program is not per'ormed. ConseKuentl(, i' a 'ile that reall( is a te%t 'ile is opened as a binar( 'ile
and read line$6ise, all lines 6ould appear to ha5e a trailing S$.Q &hara&ter.
Similarl(, S;@Q 6ritten b( the C program is translated to S$.QS;@Q in the 'ile. 9his is al6a(s
done 6hen the 'ile is opened in te%t mode. Dhen the 'ile is opened in binar( mode, all data is
trans'erred 6ithout an( alterations. 9hus, 6hen 6riting lines to a 'ile 6hi&h is opened 'or 6rite in
binar( mode, the lines appear to ha5e onl( S;@Q, not S$.QS;@Q. 8' later opened as a te%t 'ile, this
is not re&ogniHed as an end$o'$line seKuen&e.
Example" $iffering end8of8lines
!ere is an e%ample o' ho6 an in&orre&t &hoi&e o' 'ile t(pe &an &orrupt data. Assume :e%% running
under ,S$2OS, using S$.QS;@Q as a end$o'$line seKuen&e in te%t 'iles, but the s(stem &alls
translating this to S;@Q in the 'ile 8#O inter'a&e. Consider the 'ollo6ing &ode.
(ile : o6enB/'es'(ile.1a'/) /0'/C /5 'e&' %o1e 5/
call 0ri'e (ile) /858M8N88/&) /1u%%y/ /5 i.e. /abc1/ 5/
call 0ri'e (ile) /M5MMMNM8/&) /1u%%y/ /5 i.e. /"I$A/ 5/
call close (ile
(ile : o6enB/'es'(ile.1a'/) /rb/C /5 binary %o1e 5/
say c#&Brea1B(ileCC /5 says /858M8N88<A/
5/
say c#&Brea1B(ileCC /5 says /M5MMMNM8<A/
5/
call close (ile
!ere, t6o lines o' 'our &hara&ters ea&h are 6ritten to the 'ile, 6hile 6hen reading, t6o lines o' 'i5e
&hara&ters are read. 9he reason is simpl( that the 6riting 6as in te%t mode, so the end$o'$line
&hara&ter seKuen&e 6as S$.QS;@Q7 6hile the reading 6as in binar( mode, so the end$o'$line
178
&hara&ter seKuen&e 6as \ust S;@Q. 9hus, the S$.Q pre&eding the S;@Q is ta-en to be part o' the
line during the read.
9o a5oid this, be 5er( &are'ul about using the &orre&t mode 6hen opening 'iles. 1ailure to do so 6ill
almost &ertainl( gi5e strange e''e&ts.
179
3 Extensions
This chapter describes ho" e$tensions to Regina are i#ple#ented. The "hole contents o& this
chapter is speci&ic &or Regina.
3.1 ?h& 6a*e Extensions
Dh( do 6e need e%tensionsS Dell, there are a number o' reasons, although not all o' these are 5er(
good reasons:
Adaptations to ne6 en5ironments ma( reKuire ne6 'un&tionalit( in order to easil( inter'a&e to
the operating s(stem.
>%tending the language 6ith more po6er, to 'a&ilitate programming.
Sometimes, a lot o' time &an be sa5ed i' &ertain assumptions are met, so an e%tension might be
implemented to allo6 programmers to ta-e short&uts.
Dhen a program is ported 'rom one plat'orm to another, parts o' the &ode ma( depend o' non$
standard 'eatures not a5ailable on the plat'orm being ported to. 8n this situation, the a5ailabilit(
o' e%tensions that implement the 'eature ma( be o' great help to the programmer.
9he implementor had some good idea during de5elopment.
:a&-6ards &ompatibilit(.
>%tensions arise 'rom holes in the 'un&tionalit(. Dhether the( 6ill sur5i5e or not depends on ho6
the( are per&ei5ed b( programmers7 i' per&ei5ed as use'ul, the( 6ill probabl( be used and thus
supported in more interpreters.
3.2 Extensions and !tandard Rexx
8n standard Rexx, the OP,IO+S instru&tion pro5ides a ;hoo-; 'or e%tensions. 8t ta-es an( t(pe o'
parameters, and interprets them in a s(stem$dependent manner.
9he 'ormat and legal 5alues o' the parameters 'or the OP,IO+S instru&tion is &learl(
implementation dependent I932, p?2J.
3.3 !pecif&ing Extensions in Regina
8n egina there are three le5el o' e%tensions. >a&h independent e%tension has its o6n name. >%a&tl(
6hat an independent e%tension is, 6ill depend on the 5ie6er, but a &lassi'i&ation has been done, and
is listed at the end o' this &hapter.
At the lo6est le5el are these ;atomi&; e%tensions. 9hen there are some ;meta$e%tensions;. 9hese
are &olle&tions o' other e%tensions 6hi&h belong together in some manner. 8' (ou need the e%tension
'or &reating ;bu''ers; on the sta&-, it 6ould be logi&al to use the e%tension to remo5e bu''ers 'rom
180
the sta&- too. 9here'ore, all the indi5idual e%tensions 'or operations that handle bu''ers in the sta&-
&an be named b( su&h a ;meta$e%tensions;. At the end o' this &hapter, there is a list o' all the meta$
e%tensions, and 6hi&h e%tensions the( in&lude.
At the top is ;standards;. 9hese are sets o' e%tensions that ma-es the interpreter beha5e in a 'ashion
&ompatible 6ith some standard. /ote that ;standard; is used 5er( liberall(, sin&e it ma( re'er to
other implementations o' Rexx. !o6e5er, this des&ription o' ho6 the e%tensions are stru&tured is
onl( 'ollo6ed to some e%tent. Dhere pra&ti&al, the stru&ture has been de5iated.
3.4 The Trouble %egins
9here is one 5er( big problem 6ith e%tensions. 8' (ou 6ant to be able to turn them on and o'' during
e%e&ution, then (our program has to be a bit &are'ul.
,ore and more Rexx interpreters Fin&luding egina parsing the program 6hen the interpreter is
started. 9he ;old; 6a( 6as to postpone the parsing o' ea&h &lause until it 6as a&tuall( e%e&uted.
9his leads to the problem mentioned.
Suppose (ou 6ant to use an e%tension that allo6s a slightl( di''erent s(nta%, 'or the sa-e o' the
argument, let us assume that (ou allo6 an e%pression a'ter the S;$, -e(6ord. Also assume that
this e%tension is onl( allo6ed in e%tended mode, not in ;standard mode;. !o6e5er, sin&e egina
parses the sour&e &ode onl( on&e Ft(pi&all( at the starts o' the programG, the problem is a &at&h$22:
the e%tension &an onl( be turned on a'ter parsing the program, but it is needed be'ore parsing. 9his
also applies to a lot o' other Rexx interpreters, and all Rexx &ompilers and prepro&essors.
8' the e%tension is not turned on during parsing, it 6ill generate a s(nta% error, but the parsing is all
done be'ore the 'irst &lause is e%e&uted. ConseKuentl(, this e%tension &an not be turned on during
e%e&ution, it has to be set be'ore the parsing starts.
9here'ore, there are t6o alternati5e 6a(s to in5o-e a set o' e%tensions be'ore the Rexx program is
parsed:
8t &an be in5o-ed b( setting an en5ironment 5ariable, 6hi&h must be a string o' the same 'ormat
as the parameters to the OP,IO+S &lause. egina supports this me&hanism b( the use o' the
.>I+"_OP,IO+S en5ironment 5ariable.
8t &an be in5o-ed b( using a &ommand line option to the interpreter $o7 6hi&h must be a string
o' the same 'ormat as the parameters to the OP,IO+S &lause. 9he &ommand line s6it&h
o5er6rites an( option spe&i'ied in the .>I+"_OP,IO+S en5ironment 5ariable.
3.2 The /ormat of the OPTIONS clause
9he 'ormat o' the OP,IO+S &lause is 5er( simple, it is 'ollo6ed b( an( Rexx string e%pression,
6hi&h is interpreted as a set o' spa&e separated 6ords. 9he 6ords are treated stri&tl( in order 'rom
le't to right, and ea&h 6ord &an &hange Hero or more e%tension settings.
>a&h e%tension has a name. 8' the 6ord being treated mat&hes that name, that e%tension 6ill be
turned on. !o6e5er, i' the 6ord being treated mat&hes the name o' an e%tension but has the pre'i%
+O, then that e%tension is turned o''. 8' the 6ord does not mat&h an( e%tensions, then it is simpl(
ignored, 6ithout &reating an( errors or raising an( &onditions.
181
Example" Extensions changing parsing
An e%ample o' this is the ;I+S :81. 8n the 'ollo6ing pie&e o' &ode the same :81 returns di''erent
data:
/5 (ile /aa/ con'ains 5 lines 5/
o6'ions @"S,_;I+S_II@_A@"U;,
1o i:1 'o #
i( i:# '!en OP,IO+S +O@"S,_;I+S_II@_A@"U;,
say linesB/aa/C
en1
8n the 'irst iteration o' the loop, ;I+SFPaaPG returns 1, indi&ating that there is at least 1 line
remaining the the stream PaaP. !o6e5er, in the se&ond iteration o' the loop, ;I+SFPaaPG 6ill return
5, indi&ating that there are 5 lines remaining in the stream.
eginaPs 'reKuent usage o' e%tensions ma( slo6 do6n e%e&ution. 9o illustrate ho6 this &an happen,
&onsider the OP+BC e%tra built$in 'un&tion. As this is an e%tension, it might be d(nami&all(
in&luded and e%&luded 'rom the s&ope o' &urrentl( de'ined 'un&tion. 9hus, i' the 'un&tion is used in
a loop, it might be in the s&ope during the 'irst iteration, but not the se&ond. 9hus, egina &an not
&a&he an(thing relating to this 'un&tion, sin&e the &a&hed in'ormation ma( be outdated later. As a
&onseKuen&e, egina must loo- up the 'un&tion in the table o' 'un&tions 'or ea&h in5o&ation. 9o
a5oid this, (ou &an set the e%tension $"$9-,, 6hi&h tells egina to &a&he in'o 6hene5er
possible, 6ithout regards to 6hether this ma( render useless later e%e&utions o' OP,IO+S.
3.3 The /undamental Extensions
!ere is a des&ription o' all ;atomi&; e%tensions in egina:
+AR??@AIFS,
9his option allo6s the user to enable or disable the A>AA :81s introdu&ed into egina
=.1. 9he de'ault is ".--_II@S on Amiga and AOS, but +O".--_II@S on all other
plat'orms.
+AR??@SMANTI"S,
Dith the introdu&tion o' A>AA :81s into egina =.1, di''eren&es in the semanti&s o' a
number o' :81s resulted. 9hese :81s that di''er bet6een Standard Regina and 'R%:: are
OP+BC, $;OSBC and O@BC. 9his O"98O/ spe&i'ies that the A>AA semanti&s be
used 'or these :81s. 9he de'ault is to use egina semanti&s 'or these :81s.
+AUFTB!@AIF,
Allo6s &alling the built$in 'un&tion IU@,*PBC, 6hi&h 6ill 6rite out all the &ontents o'
the sta&-, indi&ating the bu''ers, i' there are an(. 9he idea is ta-en 'rom 4,#C,S, and its
&ommand named IU@,*P.
+"ALLS@AS@FUN"S,
Allo6s the old bro-en s(nta% o' :
call %y(uncBarg1)arg#C
/e6 programs should use the standard s(nta% 'or the $";; instru&tion. As the
determination o' in5alid s(nta% is done be'ore the &ode is e%e&uted, then this O"98O/ &an
onl( be spe&i'ied using the >.8/ALO"98O/S en5ironment 5ariable.
+O$";;S_"S_@U+$S is the de'ault.
182
+"A"'?T,
9ells egina that in'ormation should be &a&hed 6hene5er possible, e5en 6hen this 6ill
render 'uture e%e&ution o' the OP,IO+S instru&tion useless. 9hus, i' (ou use e.g. the
OP+BC e%tra built$in 'un&tion, and (ou set $"$9-,, then (ou ma( e%perien&e that the
OP+BC 'un&tion does not disappear 'rom the &urrent s&ope 6hen (ou set the
+OOP+_II@ e%tension.
Dhether or not a remo5al o' an e%tension reall( does happen is unspe&i'ied 6hen
$"$9-, has been &alled at least on&e. >''e&ti5el(, in'o &a&hed during the period 6hen
$"$9-, 6as in e''e&t might not be ;un&a&hed;. 9he ad5antage o' $"$9-, is
e''i&ien&( 6hen (ou do not need to do a lot o' toggling o' some e%tension.
+DSAUF@AIF,
Allo6s &alling the built$in 'un&tion ASIU@BC, to remo5e all &ontents and all bu''ers 'rom
the sta&-. 9his 'un&tion is an idea ta-en 'rom the program b( the same name under
4,#C,S.
+DRO!AUF@AIF,
Allo6s &alling the built$in 'un&tion A.OPIU@BC, to remo5ed one o' more bu''ers 'rom the
sta&-. 9his 'un&tion is an idea ta-e 'rom the program b( the same name under 4,#C,S.
+?T@"OMMANDS@AS@FUN"S,
Dhen egina resol5es an e%pression to a 'un&tion, and that 'un&tion is not a built$in or a
registered e%ternal 'un&tion, egina attempts to e%e&ute the 'un&tion as an operating s(stem
&ommand. Dith +O-,_$O33"+AS_"S_@U+$S set, egina 6ill return error <=7 ;outine
not 'ound;. -,_$O33"+AS_"S_@U+$S is the de'ault.
+FAST@LINS@AIF@DFAULT,
9he ;I+SBC :81 in 5ersions o' egina prior to 0.0+g returned the a&tual number o' lines
a5ailable in a stream. Sin&e then, the ;I+SBC :81 has been &hanged to onl( return 0 or 1.
9his 6as done 'or t6o reasons. 1irst, it is 'aster, and se&ondl(. the A/S8 standard allo6s 'or
an option to return the a&tual number o' lines. 9his O"98O/ is 'or ba&-6ards &ompatibilit(
6ith programs 6ritten assuming the prior beha5ior o' the ;I+SBC :81.
@"S,_;I+S_II@_A@"U;, is the de'ault.
+FLUS'STA"C,
9ells the interpreter that 6hene5er a &ommand &lause instru&ts the interpreter to 'lush the
&ommands output on the sta&-, and simultaneousl( ta-e the input 'rom the sta&-, then the
interpreter 6ill not bu''er the output but 'lush it to the real sta&- be'ore the &ommand has
terminated. 9hat 6a(, the &ommand ma( read its o6n output. 9he de'ault setting 'or egina
is not to 'lush, i.e. +O@;US9S,"$_, 6hi&h tells interpreter to temporar( bu''er all output
lines, and 'lush them to the sta&- 6hen the &ommand has 'inished.
+'ALT@ON@?T@"ALL@FAIL,
9his options tells the interpreter that 6hen a &alled e%ternal routine 'ails the &aller halts 6ith
a s(nta% error <0.1. 9his beha5iour also o&&urs 6ith the S,.I$,_"+SI option.
+O9";,_O+_-,_$";;_@"I; is the de'ault.
+INTRNAL@;UUS,
egina implements multiple named Kueues both as part o' the interpreter, and as an e%ternal
resour&e. 8' a Kueue name has the &hara&ter P@P embedded, egina 6ill assume this to be an
e%ternal Kueue name. 9his O"98O/ allo6s the e%&lusi5e use o' eginaPs internal Kueuing
me&hanism regardless o' the Kueue name. +OI+,.+";_UUUS is the de'ault.
+LINOUTTRUN",
9his options tells the interpreter that 6hene5er the ;I+OU,BC built$in 'un&tion is
183
e%e&uted 'or a persistent 'ile, the 'ile 6ill be trun&ated a'ter the ne6l( 6ritten line, i'
ne&essar(. 9his is the de'ault setting o' egina, unless (our s(stem does not ha5e the
('runca'eBC s(stem &all.
+MACAUF@AIF,
Allo6s &alling the built$in 'un&tion 3"_IU@BC, to &reate a bu''er on the sta&-. 9his
'un&tion is an idea ta-en 'rom a program b( the same name under 4,#C,S.
+!RUN@TRA",
,a-es deepl( nested routines be displa(ed at one line. 8nstead o' indenting the tra&e output
at a 5er( long line Fpossibl( 6rapping o5er se5eral lines on the s&reenG. 8t displa(s F...G at
the start o' the line, indi&ating that parts o' the 6hite spa&e o' the line has been remo5ed.
P.U+_,."$ is the de'ault.
+;UUS@3DE,
9his O"98O/ &hanges the beha5iour o' e%ternal Kueue names. 8n egina =.1 meaning 6as
gi5en to Kueue names. 8' a Kueue name had P@P in its name, it 6as identi'ied as an e%ternal
Kueue FreKuiring r%sta&- to be runningG. :e'ore =.1, an( time .-UUU :81 6as used, it
al6a(s re'eren&ed an e%ternal Kueue. /e6 programs should use the naming &on5ention to
identi'( e%ternal Kueues, be&ause (ou 6ill be able to use internal o' e%ternal Kueues in other
instru&tions li-e A22>SS.D89!. 9he de'ault is +OUUUS_7<1.
+RGINA@AIFS,
9his O"98O/ allo6s the user to turn on all non$A/S8 e%tension :81s. 9he de'ault is
.>I+"_II@S.
+SINGL@LIN@"OMMNTS,
:( de'ault egina supports the /ete%% and ooe%% single line &omment mar-er7 PEP. Ft6o
minus signs abuttedG. 9his 6ill brea- &ode that e%pe&ts PEP to be semanti&all( eKui5alent to
P^P. 9o remo5e single line &omments, use +OSI+>;_;I+_$O33+,S. As the
determination o' single line &omments is done be'ore &ode is e%e&uted then this O"98O/
&an onl( be spe&i'ied using the >.8/ALO"98O/S en5ironment 5ariable or the P$oP
&ommand line s6it&h. 9he de'ault is SI+>;_;I+_$O33+,S.
+STDOUT@FOR@STDRR,
All output that egina 6ould normall( 6rite to stderr, su&h as 9AC> output and errors, are
6ritten to stdout instead. 9his is use'ul i' (ou need to &apture 9AC> output and normal
output 'rom SAC to a 'ile in the order in 6hi&h the lines 6ere generated. 9he de'ault is
+OS,AOU,_@O._S,A...
+STRI"T@ANSI,
9his O"98O/ results in interpretation o' a program to stri&t A/S8 standards, and 6ill re\e&t
an( egina e%tensions. +OS,.I$,_"+SI is the de'ault. As this O"98O/ a''e&ts the
initial parsing o' the Rexx program, it must be spe&i'ied using the >.8/ALO"98O/S
en5ironment 5ariable or the P$oP &ommand line s6it&h.
+STRI"T@&'IT@S!A"@"OM!ARISONS,
9his O"98O/ spe&i'ies i' A/S8 rules 'or non$stri&t &omparisons are applied. 0nder A/S8,
6hen doing non$stri&t &omparisons, onl( the spa&e &hara&ter is stripped 'rom the t6o
&omparators. 0nder ReginaPs de'ault beha5ior, all 6hitespa&e &hara&ters are stripped.
+OS,.I$,_J9I,_SP"$_$O3P".ISO+S is the de'ault.
+TRA"@'TML,
9his O"98O/ generates !9,3 <">> and <#">> tags around 9AC> output, to enable
tra&ing 'rom 6ithin C.8 s&ripts. 9he de'ault is +O,."$_9,3;. 9he 'ollo6ing &ode sho6s
the ne&essar( header in'ormation to enable this 'eature:
184
#!/usr/bin/re&&
OP,IO+S S,AOU,_@O._S,A.. ,."$_9,3;
Parse Version ver
/5 (ollo0ing # lines 3US, be /saye1/ be(ore ,."$ 'urne1 on
5/
Say /$on'en'-'y6eH 'e&'/!'%l/
Say
Say ver
,race i
Say /Ji'! 'racing on/
,race o
Say /Ji'! 'racing o((/
.e'urn <
9he output 'rom this 6ould loo- li-e:
91te: OP+_II@, @I+A_II@, $;OS_II@ and @I;IO O"98O/s ha5e been remo5ed in
egina =.1
3.5 )eta8extensions
+ANSI,
Combination o' S,.I$,_"+SI and S,.I$,_J9I,_SP"$_$O3P".ISO+S .
+AUFFRS,
Combination o' IU@,*P_II@, ASIU@_II@, A.OPIU@_II@ and 3"_IU@_II@.
185
3.7 !emi8standards
+"MS,
A set o' e%tensions that stems 'rom the 4,#C,S operating s(stem. :asi&all(, this in&ludes
the most &ommon e%tensions in the 4,#C,S 5ersion o' Rexx, in addition o' some
'un&tions that per'orm tas-s normall( done 6ith &ommands under 4,#C,S.
+#MS,
A set o' inter'a&e 'un&tions to the 4,S operating s(stem. :asi&all(, this ma-es the Rexx
programming under 4,S as po6er'ul as programming dire&tl( in 2C3.
+UNI?,
A set o' inter'a&e 'un&tionalit( to the 0ni% operating s(stem. :asi&all(, this in&ludes some
'un&tions that are normall( &alled as &ommands 6hen programming 0ni% shell s&ripts.
Although it is possible to &all these as &ommands in egina, there are &onsiderable speed
impro5ements in implementing them as built$in 'un&tions.
3.9 !tandards
9he 'ollo6ing table sho6s 6hi&h options are a5ailable in di''erent Rexx (ang'age 3e5els, and
the de'ault settings appli&able 'or Regina.
+ANSI,
Rexx 3anguage le5el 5.0, as des&ribed in IA/S8J.
+RGINA,
Rexx 3anguage le5el 5.0, plus e%tensions, as implemented b( egina =.1 and abo5e.
+SAA,
Rexx 3anguage le5el SS, as de'ined b( 8:,Ps S(stem Appli&ation Ar&hite&ture ISAAJ.
+TRLE,
Rexx 3anguage le5el =.50, as des&ribed in I931J.
+TRLF,
Rexx 3anguage le5el <.00, as des&ribed in I932J.
186
Opti1n *9S+ >!.+9* S** T>L1 T>L2
".--_II@S
no (es no no no
".--_S3"+,I$S
no no no no no
IU@,*P_II@
no (es no no no
$"$9-,
no no no no no
$";;S_"S_@U+$S
no (es no no no
ASIU@_II@
no (es no no no
A.OPIU@_II@
no (es no no no
-,_$O33"+AS_"S_@U+$S
no (es no no no
@"S,_;I+S_II@_A@"U;,
(es (es no no no
@;US9S,"$_
no no no no no
9";,_O+_-,_$";;_@"I;
no (es no no no
I+,.+";_UUUS
no no no no no
;I+OU,,.U+$
no (es no no no
3"_IU@_II@
no (es no no no
P.U+_,."$
no (es no no no
UUUS_7<1
no (es no no no
.>I+"_II@S
no (es no no no
SI+>;_;I+_$O33+,S
no (es no no no
S,AOU,_@O._S,A..
no no no no no
S,.I$,_"+SI
(es no no no no
S,.I$,_J9I,_SP"$_$O3P".ISO+S
(es no no no no
,."$_9,3;
no no no no no
187
5 The !tac+
In this chapter, the stac and operations #anipulating the stac are discussed. Since the stac is
e$ternal to the Rexx language, there are large di&&erences bet"een i#ple#entations "ith respect to
the stac. These di&&erences are atte#pted described in the latter part o& this chapter.
'nother goal o& this chapter is to try to describe both the 4real4 standards and so#e o& the #ost
co##only used de &acto standards related to stac operation. ;here so#ething is not a part o& any
de&ined standard, this is clearly labelled. 'lso, so#e liberties have been taen in order to create a
coherent vocabulary on a &ield "here very little standardi<ation has taen place.
5.1 %ac+ground and histor&
8n the 5arious de'initions o' Rexx, there are numerous re'eren&es to the ;sta&-; Fo'ten &alled the
;e%ternal data Kueue;, or \ust the ;Kueue;G. 8t is a stru&ture &apable o' storing in'ormation, but it is
not a part o' the Rexx language itsel'. ather, it is a part o' the e%ternal en5ironment supporting a
Rexx implementation.
Originall(, the re'eren&es to the sta&- 6as introdu&ed into Rexx be&ause o' the strong binding
bet6een Rexx and 8:, main'rames in the earl( histor( o' Rexx I:,AMSJ. ,ost FallSG o' the
operating s(stems 'or these ma&hines support a sta&-, and man( o' their s&ript programming idioms
in5ol5e the sta&-. 9here'ore, it 6as Kuite natural to introdu&e an inter'a&e to the sta&- into Rexx,
and &onseKuentl( toda( man( o' the programming paradigms o' Rexx in5ol5e a sta&-.
0n'ortunatel(, this introdu&ed an element o' in&ompatibilit( into Rexx, as the sta&- is not in
general supported 'or other operating s(stems. ConseKuentl(, Rexx implementers o'ten must
implement a sta&- as 6ell o' the &ore Rexx interpreter. Sin&e no authoritati5e de'inition o' the sta&-
e%ists, &onsiderable di''eren&es bet6een 5arious implementations. 8roni&all(, although the sta&-
6as introdu&ed to help &ommuni&ation bet6een separate programs, the interpreter$spe&i'i&
implementations o' sta&-s ma( a&tuall( be a hindran&e against &ompatibilit( bet6een di''erent
interpreters.
9he sta&- ma( ha5e ;seemed li-e a good idea at the time;, but in hindsight, it 6as probabl( a bad
mo5e, sin&e it made Rexx more dependent on the host operating s(stem and its inter'a&es.
5.2 ,eneral functionalit& of the stac+
9his se&tion des&ribes the 'un&tionalit( generall( a5ailable in implementations o' sta&-s. 9he basi&
'un&tionalit( des&ribed here 6ill be &omplemented 6ith in'ormation on spe&i'i& implementations
later. 0nless e%pli&itl( labelled other6ise, this 'un&tionalit( is a5ailable in all standards treated in
this do&umentation.
5.2.1 %asic functionalit&
:elo6 is listed the general 'un&tionalit( o' the sta&-, in order o' de&reasing &ompatibilit(. 8.e. the
'un&tionalit( listed 'irst is more li-el( to be a part o' all implementations than the ones listed at the
end o' the list.
188
9he sta&- is a data stru&ture, 6hi&h strings &an either be inserted into or e%tra&ted 'rom. 9he
strings in the sta&- are stored in a linear order. >%tra&tion and insertion 6or-s at a granularit( o'
a &omplete string, i.e. it is not possible to insert or e%tra&t parts o' string.
9he sta&- has t6o ends: a top and a bottom. /e6 strings &an be inserted into the sta&- in both
ends, but strings &an onl( be e%tra&ted 'rom the top o' the sta&-.
9here e%ists a 6a( o' &ounting the number o' strings &urrentl( stored in the sta&-.
A sta&- is o'ten &ompared 6ith the pile o' plates (ou o'ten 'ind in &antinas. 8t allo6s (ou to either
add ne6 plates at the top o' the pile or ta-e old plates 'rom the top. Dhen a plate is ta-en 'rom the
pile, it 6ill be the most re&entl( plate Fthat is still presentG added to the pile. Sta&- operating in
Rexx 6or-s the same 6a(, although it also allo6s ;plates; to be added to the bottom o' the pile.
9here might be an implementation$spe&i'i& limit on the length and number o' strings stored in
the sta&-. 8deall(, the ma%imum length 6ill be 'airl( large, at least 2XX1?, although some
implementations are li-el( to en'or&e shorter limits. Similarl(, there might be a limit on the
number o' strings that &an be simultaneousl( stored in the sta&-. 8deall(, there should be no su&h
limit.
8t is natural that there are limits imposed on the amount o' memor( o&&upied b( the strings in
the sta&-. Some implementations are li-el( to reser5e a 'i%ed Fbut perhaps &on'igurableG amount
o' memor( 'or this purpose 6hile others &an d(nami&all( re$siHe the sta&- as long as enough
memor( is a5ailable.
Some implementations might restri&t the set o' &hara&ters allo6ed in strings in the sta&-,
although ideall(, all &hara&ters should be allo6ed, e5en &hara&ters normall( used 'or end$o'$line
or end$o'$string.
9his do&umentation use the term ;string;, 6hile ;line; is in &ommon use else6here. 9he term is
used be&ause the strings in the sta&- are not inherentl( interpreted as lines Fha5ing an implied end$
o'$lineG, onl( as a string.
/ote that the sta&- itsel' is not a part o' Rexx, onl( the parts 6hi&h inter'a&e to the sta&-.
Example" <sing the stac+ to transfer parameters
9his is a &ommon Rexx idiom used in se5eral situations 'or spe&ial parameter passing. 9he
'ollo6ing &ode illustrates its use:
189
1o i:1 'o 1< /5 (or eac! 6ara%e'er s'ring
5/
Vueue s'ring.1 /5 6u' '!e s'ring on '!e s'acT 5/
en1
call subrou' 1< /5 call '!e subrou'ine
5/
e&i'
subrou'H 6roce1ure /5 '!e 1e(ini'ion o( '!e subrou'ine
5/
1o `:1 'o argB1C /5 (or eac! 6ara%e'er 6asse1 5/
6arse 6ull line.` /5 re'rieve '!e 6ara%e'er 5/
en1
... /51o so%e'!ing 0i'! '!e
6ara%e'ers5/
re'urn
8n this e%ample, ten parameter strings are trans'erred to the subroutine SUI.OU,. 9he parameters
are stored in the sta&-, and onl( the number o' parameters are trans'erred as a ;real; argument.
9here are se5eral ad5antages: 'irst, one a5oids problems related to e%posing 5ariable names. Sin&e
the data is stored on the sta&-, there is no need to re'er to the 5ariable names and bind the 5ariables
in the subroutine to 5ariables in the &aller routine. 8n I931J, indire&t re'eren&es to 5ariables in
P.O$AU. -POS is illegal, and this method &ir&um5ent the problem.
96o other 6a(s around this problem is to use I+,.P., 'or the P.O$AU. -POS
instru&tion in order to d(nami&all( determine 6hi&h 5ariables to e%pose7 or to use the V";UBC
built$in 'un&tion F6ith its t6o 'irst parametersG. 9he 'ormer is in&ompatible 6ith 932, 6hile the
latter is in&ompatible 6ith 931. 0sing the sta&- &an sol5e the problem in a 'ashion &ompatible
6ith both standards. An(6a(, i' the &alled routine is an e%ternal routine, then e%posing does not
6or-, so using the sta&- to trans'er 5alues ma( be the onl( solution.
Another ad5antage o' this idiom7 93 onl( reKuires implementations to support 10 parameters 'or
subroutines. Although there are no reasons 6h( an implementation should set a limit 'or the number
o' parameters a routine &an get, (ou should use another me&hanism than arguments 6hen the
number o' strings is greater than 10. 0sing the sta&- 'i%es this.
5.2.2 #I/- and /I/- stac+ operations
As alread( mentioned, the sta&- is a linear list o' strings. Ob5iousl(, this list has t6o ends. Strings
&an onl( be e%tra&ted 'rom one end, 6hile strings &an be added to both ends.
8' a set o' ne6 strings are added to the same end as the( are later e%tra&ted 'rom, the strings 6ill be
e%tra&ted in the re5ersed order 6ith respe&t to the order in 6hi&h the( 6ere added. 9his is &alled
sta&-ing ;381O;, 6hi&h means ;last$in$'irst$out;, meaning that the last string sta&-ed, 6ill be the
'irst string e%tra&ted, i.e. re5ersal o' the order.
Similarl(, 6hen a set o' strings are sta&-ed in the end opposite to the end 6hi&h the( are later
e%tra&ted 'rom, the( 6ill be e%tra&ted in the same order in 6hi&h the( 6ere sta&-ed. 9his is re'erred
to as ;181O; sta&-ing, meaning ;'irst$in$'irst$out;.
190
9he 181O method o' sta&-ing is also sometimes re'erred to as ;Kueueing;, 6hile the 381O method
is sometimes re'erred to as ;sta&-ing; or ;pushing;.
5.2.3 <sing multiple buffers in the stac+
The concept o& bu&&ers and everything directly related to bu&&ers lay "ithout the do#ain o& standard
Rexx. Thus, this section describes a de &acto standard.
Note that Regina supports #ultiple bu&&ers only in internal stacs.
Some implementations support ;bu''ers;, 6hi&h are a means o' 'o&using on a part o' the sta&-.
Dhen &reating a ne6 bu''er, the old &ontents o' the sta&- is some6hat insulated 'rom the e''e&ts o'
sta&- operations. Dhen the bu''er is remo5ed, the state o' the old bu''er i restored, to some e%tent:
Dhene5er a string is read 'rom the sta&-, and the topmost bu''er on the sta&- is empt(, then that
bu''er 6ill be destro(ed. ConseKuentl(, i' this situation has arisen, dropping bu''ers 6ill not restore
the state o' the sta&- be'ore the bu''er 6as &reated.
9he 'un&tionalit( o' bu''ers, and their e''e&t on other sta&- operations ma( di''er &onsiderabl(
bet6een implementations.
Dhene5er a Kueuing operations is per'ormed Fe.g. b( the UUU instru&tionG, then the ne6 string is
inserted into the bottom o' the topmost bu''er, not the bottom o' the sta&-. 9his is the same i' the
sta&- has no bu''ers, but else, the out&ome o' the Kueuing operation &an be 5er( di''erent.
Dith 8:, main'rame operating s(stems li-e C,S, bu''ers &an be inserted on the top o' the sta&-.
9o per'orm bu''er operations, operating s(stem &ommands are used. 8t ma( be instru&tional to list
the bu''er operations o' C,S:
+DSAUF,
emo5es all strings and bu''ers 'rom the sta&-, and lea5es the sta&- &lean and empt(. 8t is
o'ten used instead o' repeated &alls to A.OPIU@. 8t al6a(s returns the 5alue Hero.
+DRO!AUF,
emo5es Hero or more bu''ers 'rom the sta&-. 8t ta-es one parameter 6hi&h &an be omitted,
and 6hi&h must be an integer position i' spe&i'ied, and is the assigned number o' the
bottom$most bu''er to be remo5ed, i.e. that bu''er and all bu''ers abo5e it Fand o' &ourse, all
the strings in these bu''ersG are to be remo5ed. 8' the parameter is not spe&i'ied, onl( the
topmost bu''er is remo5ed. 9he return 5alued is al6a(s Hero, unless an error o&&urred.
+MACAUF,
,a-es a ne6 bu''er on the sta&-, starting at the &urrent top o' the sta&-. 9he return &ode Fas
stored in the spe&ial 5ariable .$G is the number o' bu''ers &urrentl( on the sta&- a'ter the
ne6 bu''er has been added. Ob5iousl(, this 6ill be a positi5e integer. 9his program ta-es
no parameters.
One might regard a bu''er as a sort o' boo-mar-, 6hi&h is inserted into the sta&-, so that a
subseKuent A.OPIU@ &ommand &an remo5e the sta&- do6n to a parti&ular su&h boo-mar-.
Dhen su&h a mar- is lo&ated on the top o' the sta&-, and a PU;; instru&tion is e%e&uted, the bu''er
mar- is impli&itl( destro(ed 6hen the PU;; instru&tion reads the string belo6 the bu''er mar-.
9his is to sa( that a bu''er &an be destro(ed b( either a ASIU@ &ommand, a A.OPIU@ &ommand,
or a read 'rom the sta&- Fb( either the PU;; or P".S PU;; instru&tionsG.
191
5.2.4 The Aeroth buffer
/ormall(, data pushed on the sta&- is added to the top o' the sta&-. Dhen a sta&- &ontains onl( one
bu''er, the strings in that bu''er are the strings stored abo5e that bu''er$mar-. 9he strings belo6 it
are not part o' the 'irst bu''er7 instead, the( are said to belong to the Heroth bu''er.
9hus, all strings 'rom the bottom o' the sta&-, up till the 'irst bu''er mar- For the top o' the sta&- i'
no bu''ers e%istG is said to be the strings in the Heroth bu''er. !o6e5er, note that the Heroth bu''er is
onl( de'ined impli&itl(. 9hus, it &an not reall( be remo5ed b( &alling A.OP7 onl( the strings in the
Heroth bu''er are remo5ed. A'ter6ards, the Heroth bu''er 6ill still &ontain all strings at the bottom o'
the sta&-, up till the 'irst bu''er mar- Fi' e%istingG.
Example" Process all strings in the stac+
9his is a &ommon Rexx idiom, 6here a loop iterates o5er all the strings &urrentl( in the sta&-, but
other6ise lea5e the sta&- untou&hed. Supposing the routine P.O$SSBC e%ists, and do to
pro&essing 6ith its parameter and return the pro&essed string:
1o i:1 'o 5 /5 `us' 'o (ill '!e s'acT 5/
6us! /line #/ i
en1
1o Vueue1BC /5 (oreac! line in '!e s'acT 5/
6arse 6ull line /5 (e'c! '!e line 5/
Vueue 6rocessBlineC /5 6u' bacT '!e 6rocesse1 line 5/
en1
!ere, it is important to use UUU to put the strings ba&- into the sta&-, not PUS9, else the loop
6ill iterate the &orre&t number o' times, but onl( operate on the same data string. 8t is also important
that the sta&- does not &ontain an( bu''ers. Sin&e UUU 6ill insert into the bottom o' the topmost
bu''er, the loop 6ould iterate the &orre&t number o' times, but onl( on a part o' the sta&-. 9hus, the
topmost part o' the strings in the sta&- 6ould be pro&essed multiple times.
Example" 6o to empt& the stac+
9he 'ollo6ing short e%ample sho6s ho6 (ou &an most easil( empt( the sta&-:
1o i:1 'o 5 /5 Wus' 'o (ill '!e s'acT 5/
6us! /line #/ i
en1
1o Vueue1BC /5 @or eac! line in '!e s'acT 5/
6ull /5 .e%ove '!e line (ro% '!e s'acT
5/
en1
9his is tri5iall( simple, but there are se5eral interesting and subtle notes to ma-e about this
e%ample. 1irst, i' the number o' strings in the sta&- is li-el( to &hange, due to some e%ternal
pro&ess, then the AO &lause should perhaps better be 6ritten as:
192
1o i:1 'o 5 /5 Wus' 'o (ile '!e s'acT 5/
6us! /line #/ i
en1
1o 0!ile Vueue1BCQ< /5 J!ile '!e s'acT is no' e%6'y 5/
6ull /5 .e%ove a line (ro% '!e s'acT 5/
en1
9his 6ill in general mean more 6or- 'or the interpreter, as it is no6 reKuired to &he&- the number o'
strings in the sta&- 'or ea&h iteration, 6hile 'or the pre5ious &ode 'ragment, the number o' strings is
onl( &he&-ed on&e. Another point is that this might not remo5e all bu''ers 'rom the sta&-. Suppose
the Heroth bu''er is empt(, i.e. there e%ists an bu''er 6hi&h 6as put on the sta&- 6hen the sta&- 6as
empt(. 9his bu''er is remo5ed in an( o' the 'ollo6ing situations: &alling ASIU@, &alling
A.OPIU@ FsometimesG, or reading a string belo6 the bu''er mar-. Sin&e there are no strings belo6
the bu''er mar-, pulling a string 'rom the sta&- 6ould ma-e the interpreter read 'rom the -e(board,
and hang the interpreter.
9hus, the onl( ;sa'e; 6a( to remo5e the string and bu''ers 'rom the sta&-, 6ithout side e''e&ts, is to
&all ASIU@ or A.OPIU@. On the other hand, i' (ou onl( 6ant to ma-e sure that there are no
strings in the bu''er, the method des&ribed here is more suitable, sin&e it is 'ar more &ompatible
Falthough possibl( not so e''i&ientG. :ut an(6a(, bu''ers are not a &ompatible &onstru&t, so it does
not matter so mu&h.
5.2.2 Creating ne stac+s
The description o& #ultiple stac operations in this section, is not part o& standard Rexx, nor is it
implemented in Regina. Thus, this section describes a de &acto standard and you #ay &ind that
&e" i#ple#entations support these operations.
Oust as the operations des&ribed abo5e let the Rexx programmer use multiple bu''ers 6ithin one
sta&-, there e%ists another set o' operations 6hi&h let the programmer &reate multiple sta&-s. 9here
is reall( nothing 'an&( about this, e%&ept that a &ommand 6ill s6ap the sta&- the interpreter
&orre&tl( uses 6ith another sta&-.
9o the interpreter this is reall( eKui5alent to a situation 6here a &ommand empties the &urrent sta&-,
and sets up a ne6 sta&-. Dhen one sta&- is empt(, and the Rexx program tries to read 'rom the
sta&-, the reKuest 6ill not ;o5er'lo6; to the pre5ious sta&- Fas reKuests to an empt( bu''er
;o5er'lo6s; to the pre5ious bu''erG. 9hus, the use o' multiple sta&-s has e5en less dire&t impa&t on
Rexx interpreters than multiple bu''ers.
!ere, it is instru&ti5e to list the &ommands operating multiple sta&-s that e%ists. 9his list has been
ta-en 'rom the ,4S en5ironment, a&&ording to I>AASAAJ.
+DLSTA"C,
8s used to remo5e the most &urrentl( sta&-, and ma-e the most re&ent o' the sa5ed sta&-s the
&urrent sta&-. Dhen there are no sa5ed sta&-s, the &urrent sta&- is emptied.
+N&STA"C,
Creates a ne6 sta&-, 6hi&h be&omes the &urrent sta&-. 9he old &urrent sta&- is put on the top
o' the list o' sa5ed sta&-s, and &an be retrie5ed as the &urrent sta&- b( a subseKuent
A;S,"$_.
193
+;AUF,
Counts the number o' bu''ers in the &urrent sta&-, and returns that number as the return
5alue. A Rexx program starting this &ommand &an retrie5e this 5alue as the spe&ial 5ariable
.$.
+;LM,
Counts the number o' strings Fi.e. elementsG in the &urrent sta&-, and returns that 5alue as the
return 5alue o' the &ommand. 9his 5alue &an be retrie5ed in Rexx as the spe&ial 5ariable .$.
9his operation is eKui5alent to the UUUABC built$in 'un&tion in Rexx7 it has been
probabl( in&luded 'or the bene'it o' other s&ript languages that ha5e less 'un&tionalit( than
Rexx.
+;STA"C,
Counts the number o' sta&-s Fin&luding the &urrent sta&-G and returns the 5alue as the return
5alue 'rom the &ommand. 9his number &an be retrie5ed in Rexx as the spe&ial 5ariable .$.
One &an regard multiple bu''ers and sta&-s as t6o 6a(s o' insulating the sta&-7 6here multiple
sta&-s are a deeper and more insulating method than bu''ers. /ote that ea&h sta&- &an &ontain
multiple bu''ers, 6hile a bu''er &an not &ontain an( sta&-s. 9he term ;hard bu''ers; has been used
about multiple sta&-s, as opposed to normal bu''ers, 6hi&h are sometimes &alled ;so't bu''ers;.
Also note that neither multiple sta&-s nor bu''ers are part o' standard Rexx, so (ou might &ome
a&ross implementations that support onl( multiple sta&-s, onl( bu''ers, or e5en none o' them.
Example" Counting the number of buffers
8n order to &ount the number o' bu''ers on the sta&-, the 'ollo6ing method &an be used FRegina
s(nta% has been used 'or bu''er handlingG. 9his method is eKui5alent to the UIU@ &ommand
des&ribed abo5e.
bu((ers : %aTebu(BC - 1
call 1ro6bu(
9his 6ill store the number o' bu''ers in the sta&- in the 5ariable bu((ers. !o6e5er, \ust as 'or the
other e%amples using bu''ers, this e%ample also su''ers 'rom the 'a&t that bu''er handling is 'airl(
non$standard. 9hus, (ou 6ill ha5e to adapt the &ode to 6hate5er s(stem (ou 6ant to use.
5.3 The interface beteen Rexx and the stac+
As de'ined in 93, the inter'a&e to the sta&- &onsists o' the P".S PU;;, PU;;, PUS9, and
UUU instru&tions7 and the UUUABC built$in 'un&tion.
9here e%ists a binar( inter'a&e to the sta&- in SAA, see the &hapter on the SAA A"8 inter'a&e. 9his
inter'a&e &onsists o' the .-3SU e%it handler and the UU+"3 5alue o' the .-S9V_P.IV reKuest
o' the .e&&VariablePoolBC 'un&tion o' the 5ariable pool inter'a&e.
5.4 !trategies for implementing stac+s
As mentioned, sta&-s are rarel( a part o' the operating s(stem. 9here'ore, under most operating
s(stems, Rexx interpreters ha5e to implement their o6n sta&-s. 9here are se5eral strategies 'or
doing this, some 6hi&h are listed belo6.
194
+I6 4he o%era456g ()(4e*.,
9his is o' &ourse ;the right 6a(; to do it. !o6e5er, it reKuires that the de'inition o' the
operating s(stem is su&h that sta&-s are supported. Currentl(, onl( 8:, main'rame$based
s(stems support sta&-, together 6ith a 'e6 other s(stems that ha5e in&luded sta&-s as a
&onseKuen&e o' ma-ing Rexx a main s&ripting language FAmiga and OS#2 &ome to mindG.
+A( a 0e95-e 0r59er.,
9his is reall( \ust a 5ariation o' ma-ing the sta&- a part o' the operating s(stem. !o6e5er, in
some s(stems, dri5ers &an be added 5er( easil( to the s(stem. 2ri5ers are o'ten 'iles(stem$
based, in 6hi&h &ase dri5er$based sta&- operations must operate on a 'ile or pseudo$'ile. :ut
'or some s(stems, adding a dri5er reKuires mu&h more pro'ound &hanges, re&on'iguration,
and o'ten s(stem pri5ileges. 8n all &ases, dri5ers are li-el( to be 5er( s(stem spe&i'i&.
+A( a 0ae*o6.,
A ;daemon; is ba&-ground pro&ess that does some house-eeping ser5i&e, e.g. handling mail
'rom remote s(stems. 8mplementing a sta&- as a daemon is onl( slightl( simpler than using
a dri5er, but the main idea is the same 'or both approa&hes.
+I6 4he 564er%re4er.,
0sing this approa&h, the sta&- is built into the interpreter as a sort o' e%tension. 9his is o'ten
the simplest 6a(, sin&e it reKuire 5er( little &oordination 6ith other programs during run$
time. 9he main problem is that the sta&- be&omes pri5ate to the interpreter, so t6o
interpreters &an not use the same sta&-7 not e5en i' the( are t6o in5o&ations o' the same
interpreter.
9hese items are listed in the order o' ho6 &losel( the( are &oupled to the operating s(stem: the 'irst
items are 5er( &losel(, 6hile the last items are loosel( &oupled. 9he more &losel( &oupled the
implementation o' a sta&- is &oupled to the operating s(stem, the better is the &han&e that se5eral
interpreters on the same s(stem &an &ommuni&ate in a &ompatible 6a(, using the sta&-.
9here is room 'or se5eral h(brid solutions, based on the 'our 'undamental approa&hes. 1or instan&e,
a built$in sta&- &an also a&t as a daemon.
egina supports the sta&- as both a daemon and internal to the interpreter.
Example" Commands ta+es input from the stac+
8n the e%ample abo5e, the routine that is &alled ta-es its arguments 'rom the sta&-. Similarl(,
&ommands to an e%ternal en5ironment &an get their arguments in the same 6a(. !ere is an e%ample
o' ho6 to do it:
Vueue /anony%ous/ /5 '!e userna%e 5/
Vueue /userPno1e/ /5 '!e 6ass0or1 5/
Vueue /1ir/ /5 (irs' co%%an1 5/
Vueue /e&i'/ /5 secon1 co%%an1 5/
a11ress co%%an1 /@,P (li66er.6vv.uni'.no/
Although this is 5er( &on5enient in some situations, there is also &onsiderable disad5antages 6ith
this method: 9here is no real intera&ti5e &ommuni&ation bet6een the interpreter and the &ommand7
i.e. all input meant 'or the &ommand must be set up be'ore the &ommand itsel' is in5o-ed.
ConseKuentl(, i' one o' the input lines to the &ommand pro5o-es an error, there is 5er( little error
195
handling 'a&ilit(. Commonl(, su&h an error might start a &as&ade o' errors, as the remaining input
lines are li-el( to be in5alid, or e5en be interpreted in a &onte%t di''erent 'rom 6hat the( 6ere
intended.
As 6ith all &ommands in5ol5ing the sta&-, it is important to push or Kueue the &orre&t order.
0sing this te&hniKue, a program &an ;'ool; a &ommand to do almost an(thing, b( storing the &orre&t
input on the sta&-. !o6e5er, there is a big disad5antage: Sin&e the sta&- is implementation$
dependent, it is not &ertain that a &ommand 6ill ta-e its input 'rom the sta&-. 1or some s(stems, this
is the de'ault, 6hile 'or other s(stems, this is onl( possible through some e%pli&it a&tion. Some
s(stems might not e5en allo6 &ommands to ta-e their input 'rom the sta&- at all.
Example" FExecingF commands
,an( s&ript programming languages &an onl( e%e&ute &ommands 6hile still running, or at most
start a ne6 &ommand immediatel( a'ter the termination Fli-e the e&ecBC s(stem &all in 0ni%G.
!o6e5er, the sta&- &an be used on some s(stems to set up the s(stem to e%e&ute one or more
&ommands a'ter the &urrent s&ript terminates. !ere is an e%ample:
6us! /ls/ /5 (inally e&ecu'e /ls/ 5/
6us! /0!o/ /5 '!en e&ecu'e /0!o/ 5/
6us! /601/ /5 (irs' e&ecu'e /601/ 5/
e&i' <
Supposing that the s(stem reads its &ommands 'rom the sta&- i' the sta&- is not empt(, then this
s&ript 6ill terminate a'ter ha5ing set up the sta&- so that the three &ommands 601, 0!o and ls 6ill
be run in that seKuen&e. /ote the order, i' UUU had been used, the order 6ould be the opposite,
6hi&h is perhaps more intuiti5e Fassuming the topmost bu''er is empt(G.
As 6ith the e%ample abo5e, this too is onl( rele5ant 'or some s(stems, thus is not 5er( &ompatible,
and (ou should be &are'ul 6hen using it. 8t also su''ers 'rom the la&- o' intera&ti5it(, error handling,
and the importan&e o' the order in 6hi&h the strings are pushed or Kueued. 1or all pra&ti&al reasons,
this is \ust a spe&ial &ase.
0sing the sta&- to ;lea5e behind; &ommand names and input onl( 6or-s 'or s(stems 6here
&ommand interpreters and &ommands reads their input 'rom the sta&-. 9his is in general true 'or
8:, main'rame s(stems, but 5er( 'e6 other s(stems.
5.2 Implementations of the stac+ in Regina
8n Regina, the sta&- is implemented as both an integral, pri5ate part o' the interpreter and as a
&ross$plat'orm e%ternal sta&- able to be used b( multiple &lients on multiple ma&hines. 8nternal
sta&-s pro5ide the ob5ious ad5antage o' speed at the e%pense o' data sharing. >%ternal sta&-s are
&onsiderabl( slo6er, but do enable data sharing bet6een instan&es o' egina and#or other programs.
Regina supports the standard 93 Fand A/S8G Rexx sta&- inter'a&e 'un&tionalit(, li-e P".S
PU;;, PU;;, UUU, PUS9, the UUUABC built$in 'un&tion, and in 'uture 5ersions, support the
SAA A"8 sta&- inter'a&e. 9hese &ommands and 'un&tions operate on both the internal and e%ternal
sta&-s.
196
5.2.1 Implementation of the internal stac+ in Regina 2.2 and abo*e
Dhene5er the Rexx programmer 6ants to e%e&ute a &ommand and let that &ommand either 'lush
the output to the internal sta&-, or read its input 'rom the internal sta&-, this has to be arranged b(
the interpreter itsel'. 8n Regina this is normall( done b( pre pending or appending &ertain terms to
the &ommand to be e%e&uted.
Consider the 'ollo6ing &ommand &lauses 'or Regina:
/ls Q;I@O/
/0!o Q@I@O/
/;I@OQ 0c/
/;I@OQ sor' Q@I@O/
1or all these &ommands, the ;piping; terms are stripped o'' the &ommand string be'ore the
&ommand is sent to the &ommand interpreter o' the operating s(stem. 9hus, the &ommand
interpreter onl( sees the &ommands ls, 0!o, 0c, and sor'. 9he terms stripped o'', are used as
indi&ators o' ho6 the input and output is to be &oupled 6ith the sta&-. 9he use o' input#output
redire&tion as abo5e is onl( a5ailable 6ith the internal sta&-.
/ote that it is important not to &on'use the redire&tion o' output to the sta&- and input 'rom the
sta&- in Regina 6ith the redire&tion o' the 0ni% shells. 9he t6o &an be mi%ed in &ommand lines,
but are still t6o di''erent &on&epts.
9he 'irst &ommand 6ill e%e&ute the ls &ommand, and redire&t the output 'rom it to the sta&- in a
381O 'ashion. 9he se&ond e%e&utes the &ommand 0!o and redire&ts the output to the sta&- to, but
in a 181O 'ashion. 9he third &ommand e%e&utes the 0c, but lets the standard input o' that &ommand
&ome 'rom the sta&-. A&tuall(, it is irrele5ant 6hether @I@OQ or ;I@OQ is used 'or input7 the
strings are read 'rom the top o' the sta&- in both &ases. 9he 'ourth &ommand is a plain 6s
&ommand 6ithout an( redire&tion to or 'rom the sta&-. 9he last &ommand e%e&utes the sor'
program and lets it read its input 'rom the sta&-, and redire&t the output to the sta&-.
Regina allo6s a &ommand to ta-e both an input and an output ;redire&tion; to a sta&-, as sho6ed in
the last e%ample abo5e. !o6e5er, it also guarantees that the output is not a5ailable in the sta&-
be'ore the &ommand has terminated. 9he output 'rom the &ommand is stored in a temporar( sta&-,
and 'lushed to the ordinar( sta&- a'ter the &ommand is terminated. 9hus, the &ommand 6ill not start
to read its o6n output.
/ote that this temporar( bu''ering o' &ommand output is the de'ault beha5ior, 6hi&h might be set
up to something di''erent at (our site.
8n addition, (ou &an &hange it through the OP,IO+S instru&tion, b( using either @;US9S,"$_ or
IU@@.S,"$_ as ;parameters;.
/ote the di''eren&e bet6een ReginaPs redire&tion and 0ni% redire&tion. 8n Regina, onl( the term
;I@OQ F6hen 'irst in the &ommand stringG, and the terms Q;I@O and Q@I@O F6hen last in the
&ommand stringG, 6ill be interpreted as redire&tion dire&ti5es. 9hese terms 6ill be stripped o'' the
&ommand string. All other redire&tion dire&ti5es 6ill be le't untou&hed. 8' (ou should happen to
need to redire&t output 'rom a 0ni% &ommand to the 'ile @I@O or ;I@O, then (ou &an append a
spa&e at the end or spe&i'( the 'ile as .#181O o' .#381O. 9hat 6ill ma-e Regina ignore the
197
redire&tion term.
/ote that this parti&ular 'orm o' redire&tion o' &ommand input and output 6ill most probabl(
disappear in 'uture 5ersions o' Regina, 6here it 6ill probabl( be repla&ed b( an e%tended
"AA.SS instru&tion.
8n addition to the A/S8 standard, there are a 'e6 e%tra built$in 'un&tions, 6hi&h are supposed to
pro5ide &ompatibilit( 6ith other Rexx implementations, prin&ipall( C,S Rexx. 9hese are
:019C">, 2>S:01, 2O":01 and ,AM>:01. See the des&riptions o' these 'un&tion in the
built$in 'un&tions se&tion abo5e.
5.2.2 Implementation of the external stac+ in Regina 2.2 and abo*e
9he implementation o' the e%ternal sta&- 'ollo6s the model used b( OS#2 Rexx) but is
implemented as an operating s(stem daemon. 9his daemon is rxs#ack.
rxstac+
0nder most operating s(stems, rxs#ack is started 'rom the operating s(stemPs startup pro&ess and
terminates 6hen the ma&hine is shutdo6n. 0nder Dindo6s /9#2-#A"#4ista, it runs as a Ser5i&e.
Communi&ation bet6een rxs#ack and Regina is done 5ia 9C"#8" so&-ets. 0sing so&-ets as the
8"C me&hanism on a lo&al ma&hine is some6hat slo6 &ompared to other me&hanisms su&h as
shared memor( or named pipes. 8t does ho6e5er enable operation bet6een ma&hines on di''erent
operating s(stems to 'un&tion seamlessl(.
9he 'ull s(nta% o' the r%sta&- &ommand is:
rxs#ack *s+i#c",
s6itch is one o' the 'ollo6ing s6it&hes
'insta$$ installs the /9 Ser5i&e7 Rexx Sta&- $ Dindo6s /9#2000 onl(
'rem1Ne remo5es the /9 Ser5i&e7 Rexx $Sta&- $ Dindo6s /9#2000 onl(
'r#n runs rxs#ack in a &ommand prompt $ Dindo6s /9#2000 onl(
'd run rxs#ack as a daemon $ 0ni% onl(
'; -ills FstopsG r%sta&- $ sub\e&t to being a 5alid -iller $ see Se&urit( o'
>%ternal Bueues
9o stop rxs#ack, the pro&ess &an be -illed 6ith a S8.8/9 or S8.9>, or b( running rxs#ack 6ith
the '; s6it&h.
rxGueue
9o allo6 non$Rexx program to inter'a&e to the rxs#ack daemon, a &ompanion program7 rx-'e'e,
is pro5ided. rx-'e'e &ommuni&ates 6ith non$Rexx programs 5ia its stdin and stdout.
Consider the 'ollo6ing eKui5alents 'or Regina's internal and e%ternal sta&-
/ls Q;I@O/ /ls D r&Vueue /li(o/
/0!o Q@I@O/ /0!o D r&Vueue /(i(o/
/;I@OQ 0c/ r&Vueue /6ull D 0c/
/;I@OQ sor' Q@I@O/ r&Vueue /6ull D sor' D r&Vueue /(i(o/
9he 'ull s(nta% o' the rx-'e'e &ommand is:
198
rx-'e'e *-'e'e, *s+i#c",
Q#e#e is a Regina e%ternal Kueue name E see the ne%t se&tion 'or stru&ture. 8' no Kueue is
spe&i'ied, rx-'e'e uses r%Kueue :uilt$in 1un&tionthe Kueue name7 S>SS8O/
s6itch is one o' the 'ollo6ing s6it&hes E as per OS#2 Rexx
4i1 Kueue lines 'rom stdin 381O onto the Kueue
4$i1 Kueue lines 'rom stdin 181O onto the Kueue
4c$ear remo5e all lines 'rom the Kueue
the 'ollo6ing s6it&hes are Regina e%tensions
4Q#e#ed return the number o' lines on the Kueue
4p#$$ pull all lines 'rom the Kueue and displa( on stdout
rxGueue %uilt8in /unction
Rexx programs &ommuni&ate 6ith rxs#ack 5ia the normal Kueueing me&hanisms o' B0>0>,
"0S!, "033 and B0>0>2FG. 9hese &ommands operate on the &urrent Kueue and ha5e no
me&hanism 'or &hanging the Kueue to use. 9his is 6hereR./0101FG is used. 8ts primar( purpose
is to &ontrol the Kueue that the remainder o' the Rexx program operates on.
=ueue 'ames
9o enable the use o' the Rexx sta&- as a &ross$plat'orm, multi$ma&hine 8"C, the naming
&on5entions adopted b( OS#2 Rexx has been modi'ied. As OS#2 Rexx Kueues are lo&al to a single
ma&hine, Kueue names ha5e no stru&ture. 9o enable identi'i&ation o' Kueues on di''erent ma&hines,
some stru&ture must be built into e%ternal Kueue names on Regina. An e%ternal Kueue name on
Regina has the 'ollo6ing 'ormat:
*-'e'e,*@mac"ine*%$or#,,
9he &omponents o' the Kueue name are:
Q#e#e the name o' the Kueue. 9he onl( &riteria 'or the name is that it &ontains none o' the
'ollo6ing &hara&ters: @, . or :. 9he Kueue &omponent &an be blan-, 6hen spe&i'(ing
the de'ault Kueue on a spe&i'ied ma&hine.
machine the ma&hine that hosts the spe&i'ied Kueue. 9his &an either be a standard 8"5< 8"
address or a ma&hine name that &an be resol5ed to a standard 8"5< 8" address. 9he
ma&hine name is optional, and de'aults to 12@.0.0.1
p1rt 9he port number that rxs#ack on ma&hine is listening to. 9he de'ault port number 'or
rxs#ack is 5@5@.
Dhen re'erring to Kueues on the lo&al ma&hine, the ma&hine and port &omponents need not be
spe&i'ied. 9he beha5iour o' the e%ternal sta&- is then the same as 'or OS#2 Rexx, 6ith the e%&eption
that the Kueues on the lo&al ma&hine &an still be manipulated b( Regina on another ma&hine.
Some e%amples ma( ma-e this &learer. 9:2
!ecurit& of External =ueues
F/ot implemented (etG
A daemon pro&ess li-e rxs#ack, 6aiting on a 9C"#8" so&-et 'or an(one to &onne&t to and use is
open to abuse. 9o redu&e the openness o' rxs#ack, it uses a se&urit( me&hanism mu&h li-e the
0ni% hosts.allo6 and hosts.den( 'iles is used to &ontrol a&&ess to rxs#ack.
199
En*ironment ;ariables
AB0>0>
AS9ACM
200
7 Interfacing Rexx to other programs
This chapter describes an inter&ace bet"een a Rexx interpreter and another progra#, typically
"ritten in ! or another high level, co#piled language. It is intended &or application progra##ers
"ho are i#ple#enting Rexx support in their progra#s. It describes the inter&ace no"n as the
Rexx S'' '-I.
7.1 -*er*ie of functions in !((
9he 'un&tionalit( o' the inter'a&e is di5ided into some main areas:
Sub&ommand handlers
6hi&h trap and handle a &ommand to an e%ternal en5ironment.
>%ternal 'un&tion handlers
e%tend the Rexx language 6ith e%ternal 'un&tions
8nterpreting
Rexx s&ripts, either 'rom a dis- 'ile, or 'rom memor(.
4ariable inter'a&e
6hi&h ma-es it possible to a&&ess the 5ariables in the interpreter, and allo6s operations li-e
setting, 'et&hing and dropping 5ariables.
S(stem e%its
6hi&h are used to hoo- into &ertain -e( points in the interpreter 6hile it e%e&utes a s&ript.
>%ternal Bueue inter'a&e
6hi&h allo6s a&&ess to ReginaPs e%ternal Kueuing me&hanism.
,a&rospa&e 'un&tions
6hi&h are used to load and sa5e e%ternal ma&ros into ReginaPs ma&rospa&e 'or 'aster
e%e&ution.
,emor( Allo&ation 'un&tions
6hi&h pro5ide 'or plat'orm$independent memor( allo&ating#deallo&ation 'un&tions.
Callba&- 'un&tions
6hi&h are used to allo6 the A"8 program to e%e&ute a pro&edure 6ithin the running s&ript.
8n the 'ollo6ing se&tions ea&h o' these areas are des&ribed in detail, and a number o' brie' but
&omplete e%amples are gi5en at the end o' the &hapter.
9he des&ription is o' a highl( te&hni&al nature, sin&e it is assumed that the reader 6ill be an
appli&ation programmer see-ing in'ormation about the inter'a&e. 9here'ore, mu&h o' the &ontent is
gi5en as protot(pes and C st(le datat(pe de'initions. Although this 'ormat is &r(pti& 'or non$C
programmers, it 6ill &on5e( e%a&t, &ompa&t, and &omplete in'ormation to the intended readers.
Also, the problems 6ith
ambiguit( and in&ompleteness that o'ten a&&ompan( a des&ripti5e prose te%t are a5oided.
7.1.1 Include /iles and #ibraries
All the C &ode that uses the Rexx appli&ation inter'a&e, must in&lude a spe&ial header 'ile that
&ontains the ne&essar( de'initions. 9his 'ile is &alled rexxsaa.". Dhere (ou 6ill 'ind this 'ile,
6ill depend on (ou s(stem and 6hi&h &ompiler (ou use.
201
Also, the inter'a&e part bet6een the appli&ation and the Rexx interpreter ma( be implemented as a
librar(, 6hi&h (ou lin- 6ith the appli&ation using the 'un&tions des&ribed in this &hapter. 9he name
o'
this librar(, and its lo&ation might di''er 'rom s(stem to s(stem. 0nder 0ni%, this librar( &an be
implemented as a stati& 2li3regina.a4 or d(nami& librar( 2li3regina.*so5sl,4. 0nder other plat'orms
egina is also be implemented as a stati& or d(nami& librar(.
7.1.2 Preprocessor !&mbols
8n&luding a header 'ile ought to be enough7 un'ortunatel(, that is not so. >a&h o' the domains o'
'un&tionalit( listed abo5e are de'ined in separate sections, in the rexxsaa." header 'ile. 8n order 'or
these to be made a5ailable, &ertain prepro&essor s(mbols ha5e to be set. 1or instan&e, (ou ha5e to
in&lude the 'ollo6ing de'inition:
`de'ine 8/C3LAS!4
in order to ma-e a5ailable the de'initions and datat(pes &on&erning the 5ariable pool inter'a&e. 9he
5arious de'initions that &an be set are:
8/C3LAS0:CO,
,ust be de'ined in order to get the protot(pes, datat(pes and s(mbols needed 'or the
sub&ommand inter'a&e o' the A"8.
8/C3LA10/C
,ust be de'ined in order to get the protot(pes, datat(pes and s(mbols needed 'or the
e%ternal 'un&tion inter'a&e o' the A"8.
8/C3LASCS>A89
,ust be de'ined in order to get the protot(pes, datat(pes, and s(mbols needed 'or the
s(stem e%it 'un&tions
8/C3LAS!4
,ust be set in order to get the protot(pes, s(mbols and datat(pe de'initions ne&essar( to use
the Rexx 5ariable pool.
8/C3LAB0>0>
the Rexx e%ternal Kueues.
8/C3LA,ACO
the Rexx ma&rospa&e inter'a&e o' the A"8.
7.1.3 $ata structures and data t&pes
8n this se&tion, some data stru&tures and datat(pes rele5ant to the appli&ation inter'a&e to Rexx are
de'ined and des&ribed. 9he datat(pes de'ined are:
R.6R!NG
!olds a Rexx string.
R.71.!6
!olds a de'inition o' a s(stem e%it handler. 0sed 6hen starting a Rexx s&ript 6ith
Rexx#ar#24, and 6hen de'ining the s(stem e%it handlers.
9he datat(pes used in the AA A8! are de'ined in rexxsaa.". 9he( are:
t(pede' &har C!A 7
202
t(pede' short S!O9 7
t(pede' long 3O/. 7
t(pede' &har X"SN 7
t(pede' C!A X"C!A 7
t(pede' S!O9 X"S!O9 7
t(pede' 3O/. X"3O/. 7
t(pede' unsigned &har 0C!A 7
t(pede' unsigned short 0S!O9 7
t(pede' unsigned long 03O/. 7
t(pede' 0S!O9 X"0S!O9 7
t(pede' &har X"C! 7
t(pede' unsigned &har X"0C!A 7
t(pede' 5oid 4O827
t(pede' 5oid X"4O827
t(pede' 03O/. A"8>97
t(pede' A"8>9 FA"8>/9C X"1/GFG7
One other item needs mentioning7 A8!1N6R7. 9his 5alue is used to spe&i'( the lin-age t(pe on
OS#2 and Din=2 plat'orms. 8t is assumed that this 5alue 9defined b( in&lusion o' &ompiler$spe&i'i&
header 'iles in rexxsaa.". 0nder 0ni%, this is 9defined to nothing.
1.1.1.1 The R4!TRI', structure
9he SAA A"8 inter'a&e uses Rexx string 6hi&h are stored in the stru&ture R.6R!NG. 9here is
also a datat(pe 8R.6R!NG, 6hi&h is a pointer to R.6R!NG. 9heir de'initions are:
t(pede' stru&t Z
unsigned &har Xstrptr 7 #X "ointer to string &ontents X#
unsigned long strlength 7 #X 3ength o' string X#
[ AS98/. 7
t(pede' AS98/. X"AS98/. 7
9he s#r$#r 'ield is a pointer to an arra( o' &hara&ters ma-ing up the &ontents o' the Rexx stringP,
6hile s#rleng#" holds the number o' &hara&ters in that arra(.
0n'ortunatel(, there are some in&onsisten&ies in naming o' 5arious spe&ial -inds o' strings. 8n Rexx
F93G, a ==null string,P is a string that has Hero length. On the other hand, the SAA A"8 operates 6ith
t6o -inds o' spe&ial strings: null strings and <ero length strings. 9he latter is a string 6ith Hero
length FeKuals null strings in RexxG, 6hile the 'ormer is a sort o' unde&ined or e#pty string, 6hi&h
denotes a string 6ithout a 5alue. 9he null strings o' SAA A"8 are used to denote unspe&i'ied 5alues
Fe.g. a parameter le't out in a subroutine &allG. 8n this &hapter, 6hen the terms null strings and <ero
length strings are itali&iHed, the( re'er to the SAA A"8 st(le meaning.
A number o' ma&ros are de'ined, 6hi&h simpli'ies operations on R.6R!NGs 'or the programmer.
8n the list belo6, all parameters &alled x are o' t(pe R.6R!NG.
,AM>AS98/.F%,&ontent,lengthGJ
9he parameter con#en# must be a pointer to c"ar, 6hile leng#" is integer. 9he x parameter
6ill be set to the &ontents and length supplied. 9he onl( operations are assignments7 no ne6
spa&e is allo&ated and the &ontents o' the string is not &opied.
A/033S98/.F%GJ
203
eturns true onl( i' x is a null string.
i.e. x.s#r$#r is N0((.
AS93>/F%GJ
eturns the length o' the string x as an unsigned long. Nero is returned both 6hen x is a null
string or a <ero length string.
AS9"9F%GJ
eturns a pointer to the 'irst &hara&ter in the string x, or N0(( i' x is a null string. 8' x is a
<ero length string, and non$N0(( pointer is returned.
A4A382S98/.F%GJ
eturns true onl( i' x is neither a null string nor a <ero length string
i.e. x must ha5e non$empt( &ontents.
AN>O3>/S98/.F%GJ
eturns true onl( i' x is a <ero length string.
i.e. x.s#r$#r is non$N0((, and x.s#rleng#" is Hero.
9hese de'initions are most li-el( to be de'ined as prepro&essor ma&ros, so (ou should ne5er call
them 6ith para#eters ha5ing an( side e''e&ts. Also note that at least MA:1R.6R!NG24 is li-el(
to be implemented as t6o statements, and might not 6or- properl( i' 'ollo6ing
e.g. an if statement. Che&- the a&tual de'initions in the rexxsaa." header 'ile be'ore using them in a
'an&( &onte%t.
One de'inition o' these might be FdonPt rel( on this to be the &ase 6ith (our implementationG:
`de'ine ,AM>AS98/.F%,&,lG FF%G.strptrRF&G,F%G.strlengthRFlGG
`de'ine A/033S98/.F%G FYF%G.strptrG
`de'ine AS93>/F%G FF%G.strptr S F%G.strlength : 003G
`de'ine AS9"9F%G FF%G.strptrG
`de'ine A4A382S98/.F%G FF%G.strptr ]] F%G.strlengthG
`de'ine AN>O3>/S98/.F%G FF%G.strptr ]] YF%G.strlengthG
/ote that these de'initions o' strings di''er 'rom the normal de'inition in C programs7 6here a string
is an arra( o' &hara&ters, and its length is impli&itl( gi5en b( a terminating ASC88 /03 &hara&ter. 8n
the R.6R!NG de'inition, a string &an &ontain an( &hara&ter, in&luding an ASC88 /03, and the
length is e%pli&itl( gi5en.
1.1.2 The R4!>!E4IT structure
9his stru&ture is used 'or de'ining 6hi&h s(stem e%it handlers are to handle 6hi&h s(stem e%its. 9he
t6o rele5ant datat(pes are de'ined as:
t(pede' stru&t Z
unsigned &har Xs(se%itLname 7
short s(se%itL&ode 7
[ ASCS>A89 7
t(pede' ASCS>A89 X"ASCS>A89 7
8n this stru&ture, s;sexi#<name is a pointer to the ASC88 /03 terminated string &ontaining the
name o' a pre5iousl( registered Fand &urrentl( a&ti5eG s(stem e%it handler. 9he s;sexi#<code 'ield
is main 'un&tion &ode o' a s(stem e%it.
9he s(stem e%its are di5ided into main 'un&tions and sub$'un&tions. An e%it is de'ined to handle a
204
main 'un&tion, and must thus handle all the sub$'un&tions 'or that main 'un&tion. All the 'un&tions
and sub$'un&tions are listed in the des&ription o' the 1.!6 stru&ture.
205
7.2 The !ubcommand 6andler Interface
9his se&tions des&ribes the sub&ommand handler inter'a&e, 6hi&h enables the appli&ation to trap
&ommands in a Rexx s&ript being e%e&uted and handle this &ommands itsel'.
7.2.1 ?hat is a !ubcommand 6andler
A sub&ommand handler is a pie&e o' &ode, that is &alled to handle a &ommand to an e%ternal
en5ironment in Rexx. 8t must be either a subroutine in the appli&ation that started the interpreter, or
a subroutine in a d(nami& lin- librar(. 8n an( &ase, 6hen the interpreter needs to e%e&ute a
&ommand to an e%ternal en5ironment, it 6ill &all the sub&ommand handler, passing the &ommand as
a parameter.
9(pi&all(, an appli&ation 6ill set up a sub&ommand handler be'ore starting a Rexx s&ript. 9hat 6a(,
it &an trap and handle an( &ommand being e%e&uted during the &ourse o' the s&ript.
>a&h sub&ommand handler handles one en5ironment, 6hi&h is re'erred to b( a name. 8t seems to be
unde'ined 6hether upper and lo6er &ase letters di''er in the en5ironment name, so (ou should
assume the( di''er. Also, there might be an upper limit 'or the length o' an en5ironment name, and
some letters ma( be illegal as part o' an en5ironment name.
egina allo6s an( letter in the en5ironment name, e%&ept ASC88 /037 and sets no upper limit 'or
the length o' an en5ironment name. !o6e5er, 'or &ompatibilit( reasons, (ou should a5oid
unco##on letters and -eep the length o' the name 'airl( short.
9he protot(pe o' a sub&ommand handler 'un&tion is:
A"8>9 A"8>/9C handlerF
"AS98/. &ommand,
0S!O9 'lags,
"AS98/. returnstring
G 7
A'ter registration, this 'un&tion is &alled 6hene5er the appli&ation is to handle a sub&ommand 'or a
gi5en en5ironment. 9he 5alue o' the parameters are:
I&ommandJ
9he command string that is to be e%e&uted. 9his is the resulting string a'ter the
&ommand e%pression has been e5aluated in the Rexx interpreter. 8t &an not be empt(,
although it &an be a <ero)length)string.
I'lagsJ
"oints to an 'nsigned s"or# 6hi&h is to re&ei5e the status o' the &ompletion o' the
handler. 9his &an be one o' the 'ollo6ing: AS0:CO,LOM,
AS0:CO,L>O, or AS0:CO,L1A830>. 9he &ontents 6ill be used to
determine 6hether to raise an( &ondition at return o' the sub&ommand. 2o not
&on'use it 6ith the return 5alue.
IreturnstringJ
"oints to a R.6R!NG 6hi&h is to re&ei5e the return 5alue 'rom the sub&ommand.
"assing the return 5alue as a string ma-es it possible to return non$numeri& return
&odes. As a spe&ial &ase, (ou might set re#'rns#ring.s#r$#r to N0((, instead o'
spe&i'(ing a return string o' the ASC88 representation o' Hero.
206
/ote that it is not possible to return nothing in a sub&ommand, sin&e this is interpreted as Hero. /or
is it possible to return a numeri& return &ode as su&h7 (ou must &on5ert it to ASC88 representation
be'ore (ou return.
9he re#'rns#ring string 6ill pro5ide a 25? b(te arra( 6hi&h the programmer might use i' the return
data is not longer that that. 8' that spa&e is not su''i&ient, the handler &an pro5ide another area itsel'.
8n that &ase, the handler should not de$allo&ate the de'ault area, and the ne6 area should be
allo&ated in a standard 'ashion.
7.2.2 The RexxRegister!ubcomExeCD function
9his 'un&tion is used to register a sub&ommand handler 6ith the inter'a&e. 9he sub&ommand
handler must be a pro&edure lo&ated 6ithin the &ode o' the appli&ation. A'ter registration, the Rexx
interpreter &an e%e&ute sub&ommands b( &alling the sub&ommand handler 6ith parameters
des&ribing the sub&ommand.
9he protot(pe 'or RexxRegis#er'3com1xe24 is:
A"8>9 A"8>/9C e%%egisterSub&om>%eF
"SN >n5/ame,
"1/ >ntr("oint,
"0C!A 0serArea
G 7
All the parameters are input, and their signi'i&an&e are:
I>n5/ameJ
"oints to an ASC88 /03 terminated &hara&ter string 6hi&h de'ines the name o' the
en5ironment to be registered. 9his is the same name as the Rexx interpreter uses
6ith the A==R1 &lause in order to sele&t an e%ternal en5ironment.
I>ntr("ointJ
"oints to the entr(point o' the sub&ommand handler routine 'or the en5ironment to
be registered. See the se&tion on Sub&ommand !andlers 'or more in'ormation.
9here is an upper limit 'or the length o' this name.
I0serAreaJ
"ointer to an + b(te area o' in'ormation that is to be asso&iated 6ith this
en5ironment. 9his pointer &an be N0(( i' no su&h area is ne&essar(.
9he areas pointed to b( 1n>Name and 0serArea are &opied to a pri5ate area in the inter'a&e, so
the programmer ma( de$allo&ate or reuse the area used 'or these parameters a'ter the &all has
returned.
RexxRegis#er'3com1xe24 returns an 'nsigned long, 6hi&h &arries status in'ormation
des&ribing the out&ome o' the operation. 9he status 6ill be one o' the R.0?C@M 5alues:
I AS0:CO,LOMJ
9he sub&ommand handler 6as su&&ess'ull( registered.
IAS0:CO,L20"J
9he sub&ommand handler 6as su&&ess'ull( registered. 9here alread( e%isted another
sub&ommand handler 6hi&h 6as registered 6ith RexxRegis#er'3com1xe24, but
207
this 6ill be shado6ed b( the ne6l( registered handler.
IAS0:CO,L/O9>.J
2ue to some error, the handler 6as not registered. "robabl( be&ause a handler 'or
1n>Name 6as alread( de'ined at a pre5ious &all to RexxRegis#er'3com1xe24.
IAS0:CO,L/O>,>,J
9he handler 6as not registered, due to la&- o' memor(.
IAS0:CO,L:A29C">J
8ndi&ates that the handler 6as not registered, due to one or more o' the parameters
ha5ing in5alid 5alues.
7.2.3 The RexxRegister!ubcom$llCD function
9his 'un&tion is used to set up a routine that is lo&ated in a module in a d(nami& lin- librar(, as a
sub&ommand handler. A'ter registration, the Rexx interpreter &an e%e&ute sub&ommands b( &alling
the sub&ommand handler 6ith parameters des&ribing the sub&ommand.
Some operating s(stems donPt ha5e d(nami& lin-ing, and thus &annot ma-e use o' this 'a&ilit(. 9he
protot(pe o' this 'un&tion is:
A"8>9 A"8>/9C e%%egisterSub&om2llF
"SN >n5/ame,
"SN ,odule/ame,
"1/ >ntr("oint,
"0C!A 0serArea,
03O/. 2ropAuth
G 7
I>n5/ameJ
en5ironment to be registered. 9his is the same name as the Rexx interpreter uses
6ith the A==R1 &lause in order to sele&t an e%ternal en5ironment.
I,odule/ameJ
d(nami& or shared librar( in 6hi&h the >ntr("oint to the sub&ommand e%ists.
I>ntr("ointJ
"oints to the entr(point o' the sub&ommand handler routine 'or the en5ironment to
be registered. See the se&tion on Sub&ommand !andlers 'or more in'ormation.
9here is an upper limit 'or the length o' this name.
I0serAreaJ
"ointer to an + b(te area o' in'ormation that is to be asso&iated 6ith this
en5ironment. 9his pointer &an be N0(( i' no su&h area is ne&essar(.
I2ropAuthJ
8s either R.0?C@M<=R@8A?(1 or R.0?C@M<N@N=R@8. 9his
argument is ignored b( Regina as sub&ommands onl( e%ists 6ithin the &urrent
pro&ess.
9he areas pointed to b( 1n>Name) Mod'leName and 0serArea are &opied to a pri5ate area in
the inter'a&e, so the programmer ma( de$allo&ate or reuse the area used 'or these parameters a'ter
the &all has returned.
208
RexxRegis#er'3com=ll24 returns an 'nsigned long, 6hi&h &arries status in'ormation des&ribing
the out&ome o' the operation. 9he status 6ill be one o' the R.0?C@M 5alues:
I AS0:CO,LOMJ
9he sub&ommand handler 6as su&&ess'ull( registered.
IAS0:CO,L20"J
9he sub&ommand handler 6as su&&ess'ull( registered. 9here alread( e%isted another
sub&ommand handler 6hi&h 6as registered 6ith RexxRegis#er'3com=ll24, but
this 6ill be shado6ed b( the ne6l( registered handler.
IAS0:CO,L/O9>.J
2ue to some error, the handler 6as not registered. "robabl( be&ause a handler 'or
1n>Name 6as alread( de'ined at a pre5ious &all to RexxRegis#er'3com=ll24.
IAS0:CO,L/O>,>,J
IAS0:CO,L:A29C">J
8ndi&ates that the handler 6as not registered, due to one or more o' the parameters
ha5ing in5alid 5alues.
7.2.4 The Rexx$eregister!ubcomCD function
9his 'un&tion is used to remo5e a parti&ular en5ironment 'rom the list o' registered en5ironments.
9he protot(pe o' the 'un&tion is:
A"8>9 A"8>/9C e%%2eregisterSub&omF
"SN >n5/ame,
"SN ,odule/ame
G 7
:oth parameters are input 5alues:
I>n5/ameJ
"ointer to ASC88 /03 terminated string, 6hi&h represents the name o' the
en5ironment to be remo5ed.
I,odule/ameJ
Also an ASC88 /03 terminated string, 6hi&h points to the name o' the module
&ontaining the sub&ommand handler o' the en5ironment to be deleted.
9he list o' de'ined en5ironments is sear&hed, and i' an en5ironment mat&hing the one named b( the
'irst parameter are 'ound, it is deleted.
9he returned 5alue 'rom Rexx=eregis#er'3com24 &an be one o':
IAS0:CO,LOMJ
9he sub&ommand handler 6as su&&ess'ull( deleted.
IAS0:CO,L/O9>.J
9he sub&ommand handler 6as not 'ound.
IAS0:CO,L:A29C">J
One or more o' the parameters had illegal 5alues, and the operation 6as not &arried
through.
209
,ost s(stems that do ha5e d(nami& lin-ing ha5e no method 'or re&laiming the spa&e used b(
d(nami&all( lin-ed routines. So, e5en i' (ou 6ere able to load a dll, there are no guarantees that (ou
6ill be able to unload it.
7.2.2 The Rexx=uer&!ubcomCD function
9his 'un&tion retrie5es in'ormation about a pre5iousl( registered sub&ommand handler. 9he
protot(pe o' the 'un&tion is:
A"8>9 A"8>/9C e%%Buer(Sub&omF
"SN >n5/ame,
"SN ,odule/ame,
"0S!O9 1lag,
"0C!A 0serDord
G 7
9he signi'i&an&e o' the parameters are:
I>n5/ameJ
"ointer to an ASC88 /03 terminated &hara&ter string, 6hi&h names the sub&ommand
handler about 6hi&h in'ormation is to be returned.
I,odule/ameJ
"ointer to an ASC88 /03 terminated &hara&ter string, 6hi&h names a d(nami& lin-
librar(. Onl( the named librar( 6ill be sear&hed 'or the sub&ommand handler named
b( 1n>Name. 9his parameter must be N0(( i' all sub&ommand handlers are to be
sear&hed.
I1lagJ
"ointer to a short 6hi&h is to re&ei5e the 5alue R.0?C@M<@: or
R.0?C@M<N@6R1G. 8n 'a&t, this is the same as the return 5alue 'rom the
'un&tion.
I0serDordJ
"ointer to an area o' + b(tes. 9he userarea o' the sub&ommand handler is &opied to
the area pointed to b( 0serAord. 9his parameter might be N0(( i' the data o' the
userarea is not needed.
9he returned 5alue 'rom Rexx/'er;'3com24 &an be one o':
IAS0:CO,LOMJ
9he sub&ommand handler 6as 'ound, and the reKuired in'ormation has been
returned in the Flag and 0serAord 5ariables.
IAS0:CO,L/O9>.J
9he sub&ommand handler 6as not 'ound. 9he Flag 5ariable 6ill also be set to this
5alue, and the 0serAord 5ariable is not &hanged.
IAS0:CO,L:A29C">J
One or more o' the parameters had illegal 5alues, and the operation 6as not &arried
through.
210
7.3 The External /unction 6andler Interface
9his se&tions des&ribes the e%ternal 'un&tion handler inter'a&e, 6hi&h e%tends the language b(
enabling e%ternal 'un&tions to be 6ritten in a language other than Rexx.
7.3.1 ?hat is an External /unction 6andler
An e%ternal 'un&tion handler is a pie&e o' &ode, that is &alled to handle e%ternal 'un&tions and
subroutine &alls in Rexx. 8t must be either a subroutine in the appli&ation that started the interpreter,
or a subroutine in a d(nami& lin- librar(. 8n an( &ase, 6hen the interpreter needs to e%e&ute a
'un&tion registered as an e%ternal 'un&tion, it 6ill &all the e%ternal 'un&tion handler, passing the
'un&tion name as a parameter.
All e%ternal 'un&tions 6ritten in a language other than Rexx must be registered 6ith the interpreter
be'ore starting a Rexx s&ript.
An e%ternal 'un&tion handler &an handle one or more 'un&tions. 9he handler &an determine the
'un&tion a&tuall( &alled b( e%amining one o' the parameters passed to the handler and a&t
a&&ordingl(.
9he protot(pe o' a sub&ommand handler 'un&tion is:
A"8>9 A"8>/9C handlerF
"SN name,
03O/. arg&,
"AS98/. arg5,
"SN Kueuename,
"AS98/. returnstring
G 7
A'ter a 'un&tion is registered 6ith this 'un&tion de'ined as the handler, this 'un&tion is &alled
6hene5er the appli&ation &alls the 'un&tion. 9he 5alue o' the parameters are:
InameJ
9he 'un&tion &alled.
Iarg&J
9he number o' parameters passed to the 'un&tion. Arg> 6ill &ontain argc
R.6R!NGs.
IKueuenameJ
9he name o' the &urrentl( de'ine data Kueue.
IreturnstringJ
"oints to a R.6R!NG 6hi&h is to re&ei5e the return 5alue 'rom the 'un&tion.
"assing the return 5alue as a string ma-es it possible to return non$numeri& return
&odes. As a spe&ial &ase, (ou might set re#'rns#ring.s#r$#r to N0((, instead o'
spe&i'(ing a return string o' the ASC88 representation o' Hero.
9he re#'rns#ring string 6ill pro5ide a 25? b(te arra( 6hi&h the programmer might use i' the return
data is not longer that that. 8' that spa&e is not su''i&ient, the handler &an pro5ide another area itsel'.
8n that &ase, the handler should not de$allo&ate the de'ault area, and the ne6 area should be
allo&ated in a standard 'ashion. i' the e%ternal 'un&tion does not return a 5alue, it should set
re#'rns#ring to an empt( R.6R!NG. 9his 6ill enable the interpreter to raise error <<7 +unction
211
did not return data, i' the e%ternal 'un&tion is &alled as a 'un&tion. 8' the e%ternal 'un&tion is
in5o-ed 5ia a CA(( &ommand, the interpreter drops the spe&ial 5ariable R10(6.
9he handler returns Hero i' the 'un&tion &ompleted su&&ess'ull(. Dhen the handler returns a non$
Hero 5alue, the interpreter 6ill raise error <07 Invalid call to routine.
7.3.2 The RexxRegister/unctionExeCD function
9his 'un&tion is used to register an e%ternal 'un&tion handler 6ith the inter'a&e. 9he e%ternal
'un&tion handler must be a pro&edure lo&ated 6ithin the &ode o' the appli&ation. A'ter registration,
the Rexx interpreter &an e%e&ute e%ternal 'un&tions as i' the( 6ere built$ins.
9he protot(pe 'or RexxRegis#erF'nc#ion1xe24 is:
A"8>9 A"8>/9C e%%egister1un&tion>%eF
"SN 1un&/ame,
"1/ >ntr("oint
G 7
I1un&/ameJ
e%ternal 'un&tion to be registered. 9his is the same name as the Rexx interpreter uses
6ith a 'un&tion &all or 5ia the CA(( &ommand.
I>ntr("ointJ
"oints to the entr(point o' the e%ternal 'un&tion handler routine 'or the 'un&tion to be
registered. See the se&tion on >%ternal 1un&tion !andlers 'or more in'ormation.
9he area pointed to b( F'ncName is &opied to a pri5ate area in the inter'a&e, so the programmer
ma( de$allo&ate or reuse the area used 'or this parameter a'ter the &all has returned.
9he RexxRegis#erF'nc#ion1xe24 returns an 'nsigned long, 6hi&h &arries status in'ormation
des&ribing the out&ome o' the operation. 9he status 6ill be one o' the R.F0NC 5alues:
I A10/CLOMJ
9he handler 6as su&&ess'ull( registered.
IA10/CL20"J
9he handler 6as su&&ess'ull( registered. 9here alread( e%isted another e%ternal
'un&tion handler 6hi&h 6as registered 6ith RexxRegis#erF'nc#ion1xe24, but this
6ill be shado6ed b( the ne6l( registered handler.
IA10/CL/O>,>,J
7.3.3 The RexxRegister/unction$llCD function
9his 'un&tion is used to set up an e%ternal 'un&tion handler that is lo&ated in a module in a d(nami&
lin- librar(. Some operating s(stems donPt ha5e d(nami& lin-ing, and thus &annot ma-e use o' this
'a&ilit(. 9he protot(pe o' this 'un&tion is:
A"8>9 A"8>/9C e%%egister1un&tion2llF
"SN >%ternal/ame,
212
"SN 3ibrar(/ame,
"SN 8nternal/ame
G 7
I>%ternal/ameJ
I3ibrar(/ameJ
d(nami& librar(. 9his string ma( reKuire a dire&tor( spe&i'i&ation.
I8nternal/ameJ
entr(point 6ithin the d(nami& librar(. On s(stems 6here the &ase o' 'un&tion names
in d(nami& libraries is rele5ant, this name m#st be spe&i'ied in the same &ase as the
'un&tion name 6ithin the d(nami& librar(.
9he areas pointed to b( all parameters are &opied to a pri5ate area in the inter'a&e, so the
programmer ma( de$allo&ate or reuse the area used 'or these parameters a'ter the &all has returned.
9he RexxRegis#erF'nc#ion=ll24 returns an 'nsigned long, 6hi&h &arries status in'ormation
des&ribing the out&ome o' the operation. 9he status 6ill be one o' the R.F0NC 5alues:
I A10/CLOMJ
9he handler 6as su&&ess'ull( registered.
IA10/CL20"J
9he handler 6as su&&ess'ull( registered. 9here alread( e%isted another e%ternal
'un&tion handler 6hi&h 6as registered 6ith RexxRegis#erF'nc#ion=ll24, but this
6ill be shado6ed b( the ne6l( registered handler.
IA10/CL/O>,>,J
7.3.4 The Rexx$eregister/unctionCD function
9his 'un&tion is used to remo5e a parti&ular e%ternal 'un&tion handler 'rom the list o' registered
e%ternal 'un&tion handlers. 9he protot(pe o' the 'un&tion is:
A"8>9 A"8>/9C e%%2eregister1un&tionF
"SN 1un&/ame
G 7
9he parameter is an input 5alue:
I1un&/ameJ
9he list o' de'ined 'un&tion handlers is sear&hed, and i' an en5ironment mat&hing the one named b(
213
the parameter are 'ound, it is deleted. 9his &all is used to de$register 'un&tion handlers registered
6ith either RexxRegis#erF'nc#ion1xe24 or RexxRegis#erF'nc#ion=ll24.
9he returned 5alue 'rom Rexx=eregis#erF'nc#ion24 &an be one o':
IA10/CLOMJ
9he handler 6as su&&ess'ull( deleted.
IA10/CL/O9>.J
9he handler 6as not 'ound.
,ost s(stems that do ha5e d(nami& lin-ing ha5e no method 'or re&laiming the spa&e used b(
d(nami&all( lin-ed routines. So, e5en i' (ou 6ere able to load a dll, there are no guarantees that (ou
6ill be able to unload it.
7.3.2 The Rexx=uer&/unctionCD function
9his 'un&tion retrie5es the status o' an e%ternal 'un&tion handler. 9he protot(pe o' the 'un&tion is:
A"8>9 A"8>/9C e%%Buer(1un&tionF
"SN 1un&/ame
G 7
9he signi'i&an&e o' the parameters is:
I1un&/ameJ
9he returned 5alue 'rom Rexx/'er;F'nc#ion24 &an be one o':
IA10/CLOMJ
9he e%ternal 'un&tion handler 6as 'ound.
IA10/CL/O9>.J
9he handler 6as not 'ound.
214
7.4 Executing Rexx Code
9his se&tions des&ribes the Rexx#ar#24 'un&tion, 6hi&h allo6s the appli&ation to startup the
interpreter and ma-e it interpret pie&es o' Rexx &ode.
7.4.1 The Rexx!tartCD function
9his 'un&tion is used to in5o-e the Rexx interpreter in order to e%e&ute a pie&e o' Rexx &ode,
6hi&h ma( be lo&ated on dis-, as a pre$to-eniHed ma&ro, or as ASC88 sour&e &ode in memor(.
A"8>9 A"8>/9C e%%StartF
3O/. ArgCount,
"AS98/. Arg3ist,
"SN "rogram/ame,
"AS98/. 8nstore,
"SN >n5/ame,
3O/. Call9(pe,
"ASCS>A89 >%its,
"0S!O9 eturnCode,
"AS98/. esult
G 7
O' these parameters, Re#'rnCode and Res'l# are output$onl(, 6hile !ns#ore is both input and
output. 9he rest o' the parameters are input$onl(. 9he signi'i&an&e o' the parameters are:
IArgCountJ
9he number o' parameter strings gi5en to the pro&edure. 9his is the number o'
de'ined Rexx$strings pointed to b( the Arg(is# parameter. 9he de'ault ma%imum
number o' arguments that &an be passed is =2, but this &an be &hanged b( the
MA.<ARG<6@<R1..6AR6 ma&ro in re%%.h.
*Arg3istJ
"ointer to an arra( o' Rexx$strings, &onstituting the parameters to this &all to Rexx.
9he siHe o' this arra( is gi5en b( the parameter ArgCo'n#. 8' ArgCo'n# is greater
than one, the 'irst and last parameters are Arg(is#*B, and Arg(is#*ArgCo'n#-C,. 8'
ArgCount is 0, the 5alue o' Arg(is# is irrele5ant.
8' the s#r$#r o' one o' the elements in the arra( pointed to b( Arg(is# is /033, that
means that this parameter is empt( Fi.e. unspe&i'ied, as opposed to a string o' Hero
siHeG.
*"rog/ameJ
An ASC88 /03 terminated string, spe&i'(ing the name o' the Rexx s&ript to be
e%e&uted. 9he 5alue o' !ns#ore 6ill determine 6hether this 5alue is interpreted as the
name o' a Fon$dis-G s&ript, or a pre$to-eniHed ma&ro. 8' it re'ers to a 'ilename, the
s(nta% o' the &ontents o' this parameter depends on the operating s(stem.
I8nstoreJ
"arameter used 'or storing to-eniHed Rexx s&ripts. 9his parameter might either be
N0((, else it 6ill be a pointer to t6o R.6R!NG stru&tures, the 'irst holding the
ASC88 5ersion o' a Rexx program, the other holding the to-eniHed 5ersion o' that
program. See belo6 'or more in'ormation about ho6 to use !ns#ore.
I>n5/ameJ
215
"ointer to ASC88 /03 terminated string naming the en5ironment 6hi&h is to be the
initial &urrent en5ironment 6hen the s&ript is started. 8' this parameter is set to
N0((, the 'ilet(pe is used as the initial en5ironment name. Dhat the 'ilet(pe is, ma(
depend on (our operating s(stem, but in general it is e5er(thing a'ter the last period
P.P in the 'ilename.
ICall9(peJ
A 5alue des&ribing 6hether the Rexx interpreter is to be in5o-ed in &ommand,
'un&tion or subroutine mode. A&tuall(, this has little signi'i&an&e. 9he main
di''eren&e is that in &ommand mode, onl( one parameter string &an be passed, and in
'un&tion mode, a 5alue must be returned. 8n addition, the mode &hosen 6ill a''e&t
the output o' the 8AR1 @0RC1 instru&tion in Rexx.
9hree s(mboli& 5alues o' integral t(pe are de'ined, 6hi&h &an be used 'or this
parameter: R.C@MMAN=, R.F0NC6!@N and R.0?R@06!N1.
A 5alue o' R.R16R!C61= &an be OPed 6ith one o' the abo5e t(pes to spe&i'(
that Regina 6ill run in restricted mode. 9his is parti&ularl( use'ul 6hen Regina is
used as an embedded interpreter in appli&ations su&h as a database pro&edural
language or a 6eb$bro6ser s&ripting language.
IS(s>%istsJ
A pointer to an arra( o' e%it handlers to be used. 8' no e%it handlers are to be
de'ined, N0(( ma( be spe&i'ied. >a&h element in the arra( de'ines one e%it handler,
and the element immediatel( 'ollo6ing the last de'inition must ha5e a
s;sexi#<code set to R.1N=(6.
IeturnCodeJ
"ointer to a H@R6 integer 6here the return &ode is stored, pro5ided that the
returned 5alue is numeri&, and 6ithin the range $F2XX15G to 2XX15$1. 8 donPt -no6
6hat happens to Re#'rnCode i' either o' these &onditions is not satis'ied. 8t
probabl( be&omes unde'ined, 6hi&h means that it is totall( useless sin&e the program
has to inspe&t the return string in order to determine 6hether Re#'rnCode is 5alid.
egina allo6s the 5alue o' this parameter to be /033 i' the user is not interested in
it.
IesultJ
"oints to a Rexx string into 6hi&h the result string is 6ritten. 9he &aller ma( or ma(
not let the s#r$#r 'ield be supplied. 8' supplied Fi.e. it is non$/033G, that area 6ill be
used, else a ne6 area 6ill be allo&ated. 8' the supplied area is used, its siHe is
supposed to be gi5en b( the s#rleng#" 'ield. 8' the siHe i' not su''i&ient, a ne6 area
6ill be allo&ated, b( RexxAlloca#eMemor;24, and the &aller must see to that it is
properl( de$allo&ated using RexxFreeMemor;24.
it.
/ote that the ArgCo'n# parameter need not be the same as the ARG24 built$in 'un&tion 6ould
return. 2i''eren&es 6ill o&&ur i' the last entries in Arg(is# are null strings.
9he !ns#ore parameter needs some spe&ial attention. 8t is used to dire&tl( or indire&tl( spe&i'(
6here to 'et&h the &ode to e%e&ute. 9he 'ollo6ing algorith# is used to determine 6hat to e%e&ute:
8' !ns#ore is N0((, then 8rogName names the 'ilename o' an on$dis- Rexx s&ript 6hi&h
it to be read and e%e&uted.
216
>lse, i' !ns#ore is not N0((, the s&ript is some6here in memor(, and no reading 'rom dis-
is per'ormed. 8' both 8ns#ore*B,.s#r$#r and !ns#ore*C,.s#r$#r are N0((, then the s&ript to
e%e&ute is a pre$loaded ma&ro 6hi&h must ha5e been loaded 6ith a &all to either
RexxAddMacro24 or Rexx(oadMacro$ace247 and 8rogName is the name o' the ma&ro
to e%e&ute.
>lse, i' !ns#ore*C,.s#r$#r is non$N0((, then !ns#ore*C, &ontains the pre$to-eniHed image o'
a Rexx s&ript, and it is used 'or the e%e&ution.
>lse, i' !ns#ore*B,.s#r$#r is non$N0((, then !ns#ore*B,[ &ontains the ASC88 image o' a
Rexx s&ript, \ust as i' the s&ript had been read dire&tl( 'rom the dis- Fi.e. in&luding
line'eeds and su&hG. 9his image is passed to the interpreter, 6hi&h to-eniHes it, and stores the
to-eniHed s&ript in the !ns#ore*C, string, and then pro&eeds to e%e&ute that s&ript. 0pon
return, the !ns#ore*CJ 6ill be set, and &an later be used to re$e%e&ute the s&ript 6ithin the
same pro&ess, 6ithout the o5erhead o' to-eniHing.
9he user is responsible 'or de$allo&ating an( storage used b( !ns#ore*C,. /ote that a'ter
to-eniHing, the sour&e &ode in !ns#ore*B, is stri&tl( spea-ing not needed an(more. 8t 6ill
onl( be &onsulted i' the user &alls the @0RC1(!N124 built$in 'un&tion. 8t is not an error to
use @0RC1(!N124 i' the sour&e is not present, but nullstring and Hero 6ill be returned.
9o to-enise a Rexx s&ript and sa5e it 'or e%e&ution b( a later e%e&ution b( Rexx#ar#24
either in the &urrentl( running pro&ess or outside the &urrent pro&ess, (ou need to &all
Rexx#ar#24 6ith the 'ollo6ing arguments:
Parameter Value Notes
ArgCount 1
Arg3ist.strlength =
Arg3ist.strptr ##9
"rog/ame 8gnored
8nstoreI0J.strptr ASC88 image o' Rexx s&ript
8nstroreI0J.strlength 3ength o' 8nstoreI0J.strptr
8nstroreI1J.strptr 8gnored 9his 6ill be populated 6ith the
to-enised &ode.
8nstoreI1J.strlength 8gnored 9his 6ill be set to the length o'
8nstoreI1J.strptr
>n5/ame SCS9>,
Call9(pe ACO,,A/2
S(s>%its /033
217
Parameter Value Notes
eturnCode 8gnored
esult.strptr 8gnored
esult.strlength 8gnored
9he 5alid return 5alues 'rom Rexx#ar#24 are:
I/egati5eJ
indi&ates that a s(nta% error o&&urred during interpretation. 8n general, (ou &an
e%pe&t the error 5alue to ha5e the same absolute 5alue as the Rexx s(nta% error Fbut
opposite signs, o' &ourseG.
INeroJ
indi&ates that the interpreter 'inished e%e&uting the s&ript 6ithout errors.
I"ositi5eJ
indi&ates probabl( that some problem o&&urred, that made it impossible to e%e&ute
the s&ript, e.g. a bad parameter 5alue. !o6e5er, 8 &anPt 'ind an( re'eren&es in the
do&umentation 6hi&h states 6hi&h 5alues it is supposed to return.
2uring the &ourse o' an e%e&ution o' Rexx#ar#24, sub&ommand handlers and e%it handlers might
be &alled. 9hese ma( &all an( 'un&tion in the appli&ation inter'a&e, in&luding another in5o&ation o'
Rexx#ar#24.
O'ten, the appli&ation programmer is interested in pro5iding support simpli'(ing the spe&i'i&ation o'
'ilenames, li-e an en5ironment 5ariable sear&h path or a de'ault 'ile t(pe. 9he Rexx inter'a&e does
support a de'ault 'ile t(pe: .CM=, but the user ma( not set this to an(thing else. 9here'ore, it is
generall( up to the appli&ation programmer to handle sear&h paths, and also de'ault 'ile t(pes
Funless .CM= is OMG.
8' the initial en5ironment name F1>nNameG is N0((, then the initial en5ironment during
interpretation 6ill be set eKual to the 'ile t(pe o' the s&ript to e%e&ute. 8' the s&ript does not ha5e a
'ile
t(pe, it is probabl( set to some interpreter spe&i'i& 5alue.
218
7.2 ;ariable Pool Interface
9his se&tion des&ribes the 5ariable pool part o' the appli&ation inter'a&e, 6hi&h allo6s the
appli&ation programmer to set, retrie5e and drop 5ariables in the Rexx interpreter 'rom the
appli&ation program. 8t also allo6s a&&ess to other in'ormation.
9he C prepro&essor s(mbol !NC(<R.HD must be de'ined i' the de'initions 'or the 5ariable pool
inter'a&e are to be made a5ailable 6hen rexxsaa." is in&luded.
7.2.1 !&mbolic or $irect
1irst, let us de'ine t6o terms, sy#bolic 5ariable name and direct 5ariable name, 6hi&h are used in
&onne&tion 6ith the 5ariable pool.
A s(mboli& 5ariable name is the name o' a 5ariable, but it needs normaliHation and tail substitution
be'ore it names the real 5ariable. 9he name foo.3ar is a s(mboli& 5ariable name, and it is
trans'ormed b( normaliHation, to F@@.?AR, and then b( tail substitution to F@@.EF Fassuming
that the &urrent 5alue o' ?AR is <2G.
/ormaliHation is the pro&ess o' upper&asing all &hara&ters in the s(mboli& name7 and tail
substitution is the pro&ess o' substituting ea&h distin&t simple s(mbol in the tail 'or its 5alue.
On the other hand, a dire&t 5ariable re'ers dire&tl( to the name o' the 5ariable. 8n a sense, it is a
s(mboli& 5ariable that has alread( been normaliHed and tail substituted. 1or instan&e, foo.3ar is not
a 5alid dire&t 5ariable name, sin&e lo6er &ase letters are not allo6ed in the 5ariable stem. 9he dire&t
5ariable F@@.EF is the same as the 5ariable abo5e. 1or simple 5ariables, the onl( di''eren&e
bet6een dire&t and s(mboli& 5ariable names is that lo6er &ase letters are allo6ed in s(mboli&
names
/ote that the t6o dire&t 5ariable names F@@.3ar and F@@.?AR re'er to di''erent 5ariables, sin&e
upper and lo6er &ase letters di''er in the tail. 8n 'a&t, the tail o' a &ompound dire&t 5ariable ma(
&ontain an( &hara&ter, in&luding ASC88 /03. 9he stem part o' a 5ariable, and all simple 5ariables
&an not &ontain an( lo6er &ase letters.
As a remar-, 6hat 6ould the dire&t 5ariable F@@. re'er to: the stem F@@. or the &ompound
5ariable ha5ing stem F@@. and a nullstring as tailS Dell, 8 suppose the 'ormer, sin&e it is the more
use'ul. 9hus, the latter is ina&&essible as a dire&t 5ariable.
7.2.2 The !6;%#-CH structure
All reKuests to manipulate the Rexx 5ariable pool are &ontrolled b( a stru&ture 6hi&h is &alled
HD?(@C:, ha5ing the de'inition:
t(pede' stru&t sh5node Z
stru&t sh5node Xsh5ne%t 7 #X ptr to ne%t in bl- in &hain X#
AS98/. sh5name 7 #X name o' 5ariable X#
AS98/. sh55alue 7 #X 5alue o' 5ariable X#
03O/. sh5namelen 7 #X length o' sh5name.strptr X#
03O/. sh55aluelen 7 #X length o' sh55alue.strptr X#
0C!A sh5&ode 7 #X operation &ode X#
0C!A sh5ret 7 #X return &ode X#
219
[ S!4:3OCM 7
t(pede' S!4:3OCM X"S!4:3OCM 7
9he 'ields s">nex# and s">code are purel( input, 6hile s">re# is purel( output. 9he rest o' the
'ields might be input or output, depending on the reKuested operation, and the 5alue o' the 'ields.
9he signi'i&an&e o' ea&h 'ield is:
Ish5ne%tJ
One &all to RexxDaria3le8ool24 ma( seKuentiall( pro&ess man( reKuests. 9he
s">nex# 'ield lin-s one reKuest to the ne%t in line. 9he last reKuest must ha5e set
s">nex# to N0((. 9he reKuests are handled indi5iduall( and thus, &alling
RexxDaria3le8ool24 6ith se5eral reKuests is eKui5alent to ma-ing one &all to
RexxDaria3le8ool24 'or ea&h reKuest.
*sh5nameJ
Contains the name o' the 5ariable to operate on, as a R.6R!NG. 9his 'ield is onl(
rele5ant 'or some reKuests, and its use ma( di''er.
Ish55alueJ
Contains the 5alue o' the 5ariable to operate on as a R.6R!NG. 3i-e s">name,
this might not be rele5ant 'or all t(pes o' reKuests.
Ish5namelenJ
9he length o' the arra( that s">name.s#r$#r points to. 9his 'ield holds the
ma%imum possible number o' &hara&ters in s">name.s#r$#r. Dhile
s">name.s#rleng#" holds the number o' &hara&ters that are a&tuall( in use Fi.e.
de'inedG.
Ish55aluelenJ
9he length o' the arra( that s">>al'e.s#r$#r points to. elates to s">>al'e, li-e
s">namelen relates to s">name.
Ish5&odeJ
9he &ode o' operation7 de&ides 6hat t(pe o' reKuest to per'orm. A list o' all the
a5ailable reKuests is gi5en belo6.
Ish5retJ
A return &ode des&ribing the out&ome o' the reKuest. 9his &ode is a bit spe&ial. 9he
lo6er se5en bits are 'lags 6hi&h are set depending on 6hether some &ondition is met
or not. 4alues abo5e 12@ are not used in this 'ield.
9here is a di''eren&e bet6een s">namelen and s">name.s#rleng#". 9he 'ormer is the total length
o' the arra( o' &hara&ters pointed to b( s">name.s#r$#r Fi' setG. Dhile the latter is the number o'
these &hara&ters that are a&tuall( in use. Dhen a HD?(@C: is used to return data 'rom
RexxDaria3le8ool24, and a pre$allo&ated string spa&e has been supplied, both these 6ill be used7
s">name.s#rleng#" 6ill be set to the length o' the data returned, 6hile s">namelen is ne5er
&hanged, onl( read to 'ind the ma%imum number o' &hara&ters that s">name &an hold.
>5en though s">namelen is not reall( needed 6hen s">name is used 'or input, it is 6ise to set it
to its proper 5alue For at least set it to the same as s">name.s#rleng#"G. 9he same applies 'or
s">>al'e and s">>al'elen.
9he 'ield s">code &an ta-e one o' the 'ollo6ing s(mboli& 5alues:
IAS!4L2O"4J
220
9he 5ariable named b( the dire&t 5ariable name s">name is dropped Fi.e. be&omes
unde'inedG. 9he 'ields s">>al'e and s">>al'elen do not matter.
IAS!4L>A89J
9his is used to set the return 5alue 'or an e%ternal 'un&tion or e%it handler.
IAS!4L1>9C!J
9he 5alue o' the 5ariable named b( the dire&t 5ariable name s">name is retrie5ed
and stored in s">>al'e. 8' s">>al'e.s#r$#r is N0((, the interpreter 6ill allo&ate
su''i&ient spa&e to store the 5alue Fbut it is the responsibilit( o' the appli&ation
programmer to release that spa&eG. >lse, the 5alue 6ill be stored in the area allo&ated
'or s">>al'e, and s">>al'elen is ta-en to be the ma%imum siHe o' that area.
IAS!4L/>A94J
9his &ode is used to retrie5e the names and 5alues o' all 5ariables at the &urrent
pro&edure le5el7 i.e. e%&luding 5ariables shado6ed b( 8R@C1=0R1. 9he name
and 5alue o' ea&h 5ariable are retrie5ed
simultaneousl( into s">name and s">>al'e, respe&ti5el(.
Su&&essi5e reKuests 'or R.HD<N1.6D 6ill tra5erse the interpreterPs internal data
stru&ture 'or storing 5ariables, and return a ne6 pair o' 5ariable name and 5alue 'or
ea&h reKuest. >a&h 5ariable that is 5isible in the &urrent s&ope, is returned on&e and
onl( on&e, but the order is non$deterministi&.
Dhen all a5ailable 5ariables in the Rexx interpreter ha5e alread( been retrie5ed,
subseKuent R.HD<N1.6D reKuests 6ill set the 'lag R.HD<(DAR in the
s">re# 'ield. 9here are a 'e6 restri&tions. 9he tra5ersal 6ill be reset 6hene5er the
interpreter resumes e%e&ution, so an in&omplete tra5ersal &an not be &ontinued in a
later e%ternal 'un&tion, e%it handler, or sub&ommand handler. Also, an( set, 'et&h or
drop operation 6ill reset the tra5ersal. 9hese restri&tions ha5e been added to ensure
that the 5ariable pool is stati& throughout one tra5ersal.
IAS!4L"84J
etrie5es some pie&e o' in'ormation 'rom the interpreter, other than a 5ariable 5alue,
based on the 5alue o' the s">name 'ield. 9he 5alue is stored in s">>al'e as 'or a
nor#al 'et&h. A list o' possible names is sho6n belo6.
IAS!4LS>9J
9he 5ariable named b( the dire&t 5ariable name s">name is set to the 5alue gi5en
b( s">>al'e.
IAS!4LSC1>9J
3i-e R.HD<F16CH, e%&ept that s">name is a s(mboli& 5ariable name.
IAS!4LSC2OJ
3i-e R.HD<=R@8D, e%&ept that s">name is a s(mboli& 5ariable name.
IAS!4LSCS>9J
3i-e R.HD<16, e%&ept that s">name is a s(mboli& 5ariable name.
One t(pe o' reKuest that needs some spe&ial attention is the R.HD<8R!D, 6hi&h retrie5es a -ind
o' #eta)variable. 2epending on the 5alue o' s">name, it returns a 5alue in s">>al'e des&ribing
some aspe&t o' the interpreter. 1or R.HD<8R!D the possible 5alues 'or s">name are:
I"A,J
eturns the ASC88 representation o' the number o' parameters to the &urrentl( a&ti5e
Rexx pro&edure. 9his ma( not be the same 5alue as the built$in 'un&tion ARG24
returns, but is the number ArgCo'n# in Rexx#ar#24. 9he t6o might di''er i' a
routine 6as &alled 6ith trailing omitted parameters.
I"A,.nJ
221
9he n must be a positi5e integer7 and the 5alue returned 6ill be the n'#" parameter at
the &urrent pro&edure le5el. 9his is not &ompletel( eKui5alent to the in'ormation
that the built$in 'un&tion ARG24 returns. 1or parameters 6here ARG24 6ould
return the state omitted, the returned 5alue is a null string, 6hile 'or parameters
6here ARG24 6ould return the state e$isting, the return 5alue 6ill be the parameter
string F6hi&h ma( be a <ero length string.
IB0>/A,>J
9he name o' the &urrentl( a&ti5e e%ternal data Kueue. 9his 'eature has not (et been
implemented in Regina, 6hi&h al6a(s return de&ault.
*SO0C>J
eturns the same string that is used in the 8AR1 @0RC1 &lause in Rexx, at the
&urrent pro&edure le5el o' interpretation.
I4>S8O/J
eturns the same string that is used in the 8AR1 D1R!@N &lause in Rexx.
9he 5alue returned b( a 5ariable pool reKuest is a bit un&ommon. A return 5alue is &omputed 'or
ea&h reKuest, and stored in the s">re# 'ield. 9his is a one$b(te 'ield, o' 6hi&h the most signi'i&ant
bit is ne5er set. A s(mboli& 5alue R.HD<@: is de'ined as the 5alue Hero, and the s">re# 'ield
6ill be eKual to this name i' none i' the 'lags listed belo6 is set. 9he s(mboli& 5alue 'or these 'lags
are:
IAS!4L:A21J
9he s">code o' this reKuest &ontained a bad 'un&tion &ode.
IAS!4L:A2/J
9he s">name 'ield &ontained a string that is not 5alid in this &onte%t. Dhat e%a&tl(
is a 5alid 5alue depends on 6hether the operation is a pri5ate, a s(mboli& 5ariable, or
dire&t 5ariable operation.
IAS!4L34AJ
Set i' and onl( i' the reKuest 6as R.HD<N16.D, and all a5ailable 5ariables ha5e
alread( been retrie5ed b( earlier reKuests.
IAS!4L,>,13J
9here 6as not enough memor( to &omplete this reKuest.
IAS!4L/>D4J
Set i' and onl( i' the re'eren&ed 5ariable did not pre5iousl( ha5e a 5alue. 8t &an be
returned 'or an( set, 'et&h or drop operation.
IAS!4L90/CJ
Set i' the retrie5ed 5alue 6as trun&ated 6hen it 6as &opied into either the s">name
or s">>al'e 'ields. See belo6.
9hese 'lags are dire&tl( suitable 'or logi&al O, 6ithout shi'ting, e.g. to &he&- 'or trun&ation and no
5ariables le't, (ou &an do something li-e:
i' FreK$>sh5ret ] FAS!4L90/C Q AS!4L34AGG
print'F;9run&ation or no 5ars le'tWn;G 7
R.HD<6R0NC &an onl( o&&ur 6hen the inter'a&e is storing a retrie5ed 5alue in a HD?(@C:,
and the pre$allo&ated spa&e is present, but not su''i&ientl( large. As des&ribed 'or R.HD<F16CH,
the interpreter 6ill allo&ate enough spa&e i' s">>al'e.s#r$#r is N0((, and then R.HD<6R0NC
6ill ne5er be set. >lse the spa&e supplied b( s">>al'e.s#r$#r is used, and s">>al'elen is ta-en as
the ma%imum length o' s">>al'e, and trun&ation 6ill o&&ur i' the supplied spa&e is too small.
222
Some implementations 6ill &onsider HD<M1MF( to be so se5ere as to s-ip the rest o' the
operations in a &hain o' reKuests. 8n order to 6rite &ompatible so't6are, (ou should ne5er assume
that reKuests
'ollo6ing in a &hain a'ter a reKuest that returned HD<M1MF( ha5e been per'ormed.
R.HD<?A=N is returned i' the supplied s">name &ontains a 5alue that is not legal in this
&onte%t. 1or the s(mboli& set, 'et&h and drop operations, that means a s(mbol that is a legal 5ariable
name7 both upper and lo6er &ase letters are allo6ed. 1or the dire&t set, 'et&h and drop operations,
that means a 5ariable name a'ter normaliHation and tail substitution is not a legal 5ariable name. 1or
.HD<8R!D, it must be one o' the 5alues listed abo5e.
9here is a small subtlet( in the abo5e des&ription. 93 states that 6hen a Rexx assignment assigns
a 5alue to a stem 5ariable, all possible 5ariables ha5ing that stem are assigned a ne6 5alue
Findependent o' 6hether the( had an e%pli&it 5alue be'oreG. So, stri&tl( spea-ing, i' a stem is set,
then a R.HD<N16D seKuen&e should return an FalmostG in'inite seKuen&e o' &ompound 5ariables
'or that stem. O' &ourse, that is &ompletel( useless, so (ou &an assume that onl( &ompound
5ariables o' that stem gi5en an e%pli&it 5alue a'ter the stem 6as assigned a 5alue 6ill be returned b(
R.HD<N1.6D. !o6e5er, be&ause o' that subtlet(, the 5ariables returned b( R.HD<N1.6D
'or &ompound 5ariables might not be representati5e 'or the state o' the 5ariables.
e.g. 6hat 6ould a seKuen&e o' R.HD<N1.6 reKuests return a'ter the 'ollo6ing Rexx &ode S:
'oo. R PbarP
drop 'oo.bar
9he se&ond statement here, might not &hange the returned 5aluesY A'ter the 'irst statement, onl( the
stem foo. 6ould probabl( ha5e been returned, and so also i' all 5ariables 6ere 'et&hed a'ter the
se&ond statement.
7.2.3 Regina 'otes for the ;ariable Pool
2ue to the subtleties des&ribed at the end o' the pre5ious subse&tion, some notes on ho6 Regina
handles R.HD<N1.6D reKuests 'or &ompound 5ariables are in order. 9he 'ollo6ing rules
applies:
:oth the stem 5ariable F@@. and the &ompound 5ariable ha5ing F@@. as stem and a nullstring
as tail, are returned 6ith the name o' F@@.. 8n this situation, a seKuen&e o' R.HD<N1.6D
reKuests ma( seem to return 5alues 'or the same 5ariable t6i&e. 9his is un'ortunate, but it seems
to be the onl( 6a(. 8n an( &ase, (ouPll ha5e to per'orm the R.HD<7F16 in order to
determine 6hi&h is 6hi&h.
8' a stem 5ariable has not been assigned a 5alue, its &ompound 5ariables are onl( returned i'
the( ha5e been assigned an e%pli&it 5alue. i.e. &ompound 5ariables 'or that stem that ha5e either
ne5er been assigned a 5alue, or ha5e been dropped, 6ill not be reported b( AS!4L/>A94.
9here is nothing strange about this.
8' a stem 5ariable has been assigned a 5alue, then its &ompound 5ariables 6ill be reported in
t6o &ases: 1irstl(, the &ompound 5ariables ha5ing e%pli&itl( been assigned a 5alue a'ter6ard.
Se&ondl(, the &ompound 5ariables 6hi&h ha5e been dropped a'ter6ard, 6hi&h are reported to
ha5e their initial 5alue, and the 'lag R.HD<N1AD is set in s">re#.
8t ma( sound a bit stupid that unset 5ariables are listed 6hen the reKuest is to list all 5ariables 6hi&h
223
ha5e been set, but that is about the best 8 &an do, i' 8 am to sta( 6ithin the standard de'inition and
return a &omplete and e%a&t status o' the 5ariable pool.
8' the return &ode 'rom RexxDaria3le8ool24 is less than 12+, Regina is guaranteed to ha5e tried to
pro&ess all reKuests in the &hain. 8' the return &ode is abo5e 12@, some reKuests ma( not ha5e been
pro&essed. A&tuall(, the number 12@ For 12+G is a bit in&on5enient, sin&e it 6ill be an problem 'or
later e%pansion o' the standard. A mu&h better approa&h 6ould be to ha5e a prepro&essor s(mbol
Fsa(,
R.HD<FA6A(, and i' the return &ode 'rom the RexxDaria3le8ool24 'un&tion 6as larger than
that, it 6ould be a direct error &ode, and not a co#posite error &ode built 'rom the s">re# 'ields o'
the reKuests. 9he R.HD<FA6A( 6ould then ha5e to be the addition o' all the atomi& &omposite
error &odes.
,5arningA a#th1r m1#nting the s1apb1":/
9he right 6a( to 'i% this, is to let the 'un&tion RexxDaria3le8ool24 set another 'lag in
s">re# Fe.g. named R.HD<61MG during R.HD<N1.6D i' and onl( i' the 5alue
returned is a stem 5ariable. 9hat 6a(, the appli&ation programmer 6ould be able to di''er
bet6een stem 5ariables and &ompound 5ariable 6ith a null string tail.
9o handle the other problem 6ith &ompound 5ariables and R.HD<N1.6D, 8 6ould ha5e
li-ed to return a null string in s">>al'e i' and onl( i' the 5ariable is a &ompound 5ariable
ha5ing its initial 5alue, and the stem o' that &ompound 5ariable has been assigned a 5alue.
9hen, the 5alue o' the &ompound 5ariable is eKual to its name, and is a5ailable in the
s">name 'ield.
8Pd also li-e to see that the s">re# 5alue &ontained other in'ormation &on&erning the
5ariables, e.g. 6hether the 5ariable 6as e%posed at the &urrent pro&edure le5el. O' &ourse,
Regina does not &ontain an( o' these e%tra, non$standard 'eatures.
,*#th1r is dism1#nting the s1apb1":/
Dhen Regina is returning 5ariables 6ith R.HD<N1.6D, the 5ariables are returned in the order
in 6hi&h the( o&&ur in the open hash table in the interpreter. i.e. the order in 6hi&h 5ariables
belonging to di''erent bins are returned is &onsistent, but the order in 6hi&h 5ariables hashed to the
same bin are returned, is non$deterministi&. /ote that all &ompound 5ariables belonging to the same
stem are returned in one seKuen&e.
7.2.4 The Rexx;ariablePoolCD function
9his 'un&tion is used to pro&ess a seKuen&e o' 5ariable reKuests, and pro&ess them seKuentiall(. 9he
protot(pe o' this 'un&tion is:
A"8>9 A"8>/9C 03O/. e%%4ariable"oolF
S!4:3OCM XeKuest
G 7
8ts onl( parameter is a pointer to a HD?(@C: stru&ture, 6hi&h ma( be the 'irst o' the lin-ed list.
9he 'un&tion per'orms the operation spe&i'ied in ea&h blo&-. 8' an error should o&&ur, the &urrent
reKuest is terminated, and the 'un&tion mo5es on to the ne%t reKuest in the &hain.
9he result 5alue is a bit pe&uliar. 8' the returned 5alue is less than 12+, it is &al&ulated b( logi&all(
OPing the returned s">re# 'ield o' all the reKuests in the &hain. 9hat 6a(, (ou &an easil( &he&-
224
6hether an( o' the reKuests 6as e.g. s-ipped be&ause o' la&- o' memor(. 9o determine 6hi&h
reKuest, (ou ha5e to iterate through the list.
8' the result 5alue is higher than 12@, it signi'ies an error. 8' an( o' these 5alues are set, (ou &an not
assume that an( o' the reKuests ha5e been pro&essed. 9he 'ollo6ing s(mboli& name gi5es its
meaning.
*AS!4L/OA43J
,eans that the inter'a&e is not a5ailable 'or this reKuest. 9his might o&&ur i' the
inter'a&e 6as not able to start the interpreter, or i' an operation reKuested a 5ariable
6hen the interpreter is not &urrentl( e%e&uting an( s&ript Fi.e. idle and 6aiting 'or a
s&ript to e%e&uteG.
225
7.3 The !&stem Exit 6andler Interface
9he e%it handlers pro5ide a me&hanism 'or go5erning important aspe&ts o' the Rexx interpreter
'rom the appli&ation: 8t &an trap situations li-e the interpreter 6riting out te%t, and then handle them
itsel', e.g. b( displa(ing the te%t in a spe&ial 6indo6. Cou &an regard s(stem e%its as a sort o'
hoos.
7.3.1 The !&stem Exit 6andler
Oust li-e the sub&ommand handler, the s(stem e%it handler is a routine supplied b( the appli&ation,
and is &alled b( the interpreter 6hen &ertain situations o&&ur. 9hese situations are des&ribed in detail
later. 1or the e%amples belo6, 6e 6ill use the output 'rom A7 as an e%ample.
8' a s(stem e%it handler is enabled 'or the A7 instru&tion, it 6ill be &alled 6ith a parameter
des&ribing the te%t that is to be 6ritten out. 9he s(stem e%it handler &an &hoose to handle the
situation Fe.g. b( 6riting the te%t itsel'G, or it &an ignore it and let the interpreter per'orm the output.
9he return &ode 'rom the s(stem e%it tells the interpreter 6hether a s(stem e%it handled the situation
or not.
A s(stem e%it handler must be a routine de'ined a&&ording to the protot(pe:
3O/. A"8>/9C m(Le%itLhandlerF
3O/. >%it/umber,
3O/. Sub'un&tion,
">A89 "arm:lo&-
G 7
8n this protot(pe, the t(pe 81.!6 is a pointer to a parameter blo&- &ontaining all the parameters
ne&essar( to handle the situation. 9he a&tual de'inition o' this parameter blo&- 6ill 5ar(, and is
des&ribed in detail in the list o' ea&h s(stem e%it.
9he e%its are de'ined in a t6o$le5el hierar&h(. 9he 1xi#N'm3er de'ines the main 'un&tion 'or a
s(stem e%it, 6hile the '3f'nc#ion de'ines the sub'un&tion 6ithin that main 'un&tion. e.g. 'or
A7, the main 'un&tion 6ill be R.!@ Fthe s(stem e%it 'or standard 8#OG and the sub'un&tion 6ill
be R.!@A7. 9he R.!@ main 'un&tion has other sub$'un&tions 'or handling tra&e output,
intera&ti5e tra&e input, and 80(( input 'rom standard input.
9he 5alue returned 'rom the s(stem e%it handler must be one o' the 'ollo6ing s(mboli& 5alues:
IA>A89L!A/23>2J
Signals that the s(stem e%it handler too- &are o' the situation, and that the
interpreter should not pro&eed to do the de'ault a&tion. 1or the A7 instru&tion, this
means that the interpreter 6ill not print out an(thing.
IA>A89L/O9L!A/23>2J
Signals that the s(stem e%it handler did not ta-e &are o' the situation, and the
interpreter 6ill pro&eed to per'orm the de'ault a&tion. 1or the A7 instru&tion, this
means that it must print out the argument to A7.
IA>A89LA8S>L>OJ
Signals that the interpreterPs de'ault a&tion 'or this situation should not be per'ormed,
but instead a 7N6A. &ondition should be raised. 2onPt get &on'used b( the name,
it is not the 1RR@R &ondition, but the 7N6A. &ondition is raised, using the
226
s(nta% error +ailure in syste# service Fnormall( numbered <+G.
8n addition to returning in'ormation as the numeri& return 5alue, in'ormation ma( also be returned
b( setting 5ariables in the parameter blo&-. 1or instan&e, i' the s(stem e%it is to handle intera&ti5e
tra&e input, that is ho6 it 6ill suppl( the interpreter 6ith the input string.
8t is a good and dis&iplined pra&ti&e to let (our e%it handlers start b( 5eri'(ing the 1xi#N'm3er and
'3f'nc#ion &odes, and immediatel( return R.1.!6<N@6<HAN=(1= i' it does not re&ogniHe
both o' them. 9hat 6a(, (our appli&ation 6ill be up6ards &ompatible 6ith 'uture interpreters 6hi&h
might ha5e more sub$'un&tions 'or an( gi5en main 'un&tion.
7.3.2 #ist of !&stem Exit 6andlers
1.1.2.1.1R4/'C 8 The External /unction Exit 6andler
9he R.FNC s(stem e%it handler pro5ides hoo-s 'or e%ternal 'un&tions. 8t has onl( one
sub'un&tion7 R.FNCCA(, 6hi&h allo6s an appli&ation program to inter5ene and handle an(
e%ternal 'un&tion or subroutine.
2o not &on'use this e%it handler 6ith the e%ternal 'un&tion routines 6hi&h allo6 (ou to de'ine ne6
Rexx, semi$built$in 'un&tions. 9he e%it handler is &alled 'or all in5o&ations o' e%ternal routines,
and &an be &alled 'or 'un&tion names 6hi&h (ou 6ere una6are o'.
9he parameter 8arm?lock 'or R.FNCCA( is de'ined as:
t(pede' stru&t Z
t(pede' stru&t Z
unsigned int r%''err:1 7
unsigned int r%''n'nd1 7
unsigned int r%''sub: 17
[ r%'n&L'lags 7
unsigned &har Xr%'n&Laddress 7
unsigned short r%'n&Laddressl 7
unsigned &har Xr%'n&LKue 7
unsigned short r%'n&LKuel 7
unsigned short r%'n&Larg&7
AS98/. Xr%'n&Larg5 7
AS98/. r%'n&Lret& 7
[ A1/CCA3L"A, 7
9he signi'i&an&e o' ea&h 5ariable is:
Ir%'n&L'lags.r%''errJ
8s an output parameter that is set on return in order to in'orm the interpreter that the
'un&tion or subroutine 6as in&orre&tl( &alled, and thus the 7N6A. &ondition
should be raised.
Ir%'n&L'lags.r%''n'ndJ
8s an output parameter that tells the interpreter that the 'un&tion 6as not 'ound. /ote
the in&onsisten&(: it is onl( e''e&ti5e i' the e%it handler returns
R.1.!6<HAN=(1=, 6hi&h loo-s li-e a logi& &ontradi&tion to setting the not$'ound
'lag.
Ir%'n&L'lags.r%''subJ
8s an input parameter that tells the e%it handler 6hether it 6as &alled 'or a 'un&tion or
227
subroutine &all. 8' set, the &all being handled is a subroutine &all and returning a
5alue is optional7 else it 6as &alled 'or a 'un&tion, and must return a 5alue in
rxfnc<re#c i' R.1.!6<HAN=(1= is to be returned.
Ir%'n&LnameJ
8s a pointer to the name o' the 'un&tion or subroutine to be handled, stored as a
&hara&ter arra(. 9his is an input parameter, and its length is gi5en b( the
rxfnc<namel parameter.
Ir%'n&LnamelJ
!olds the length o' rxfnc<name. /ote that the last &hara&ter is the letter ell, not the
number one.
Ir%'n&LKueJ
"oints to a &hara&ter arra( holding the name o' the &urrentl( a&ti5e Kueue. 9his is an
input parameter. 9he length o' this name is gi5en b( the rxfnc<-'el 'ield.
*r%'n&LKue1J
!olds the length o' rxfnc<-'e. /ote that the last &hara&ter is the letter ell, not the
number one.
Ir%'n&Larg&J
8s the number o' arguments passed to the 'un&tion or subroutine. 8t de'ines the siHe
o' the arra( pointed to b( the rxfnc<arg> 'ield.
Ir%'n&Larg5J
"oints to an arra( holding the parameters 'or the routines. 9he siHe o' this arra( is
gi5en b( the rxfnc<argc 'ield. 8' rxfnc<argc is Hero, the 5alue o' rxfnc<arg> is
unde'ined.
Ir%'n&Lret&J
!olds an R.6R!NG stru&ture suitable 'or storing the return 5alue o' the handler.
8t is the responsibilit( o' the handler to allo&ate spa&e 'or the &ontents o' this string
Fi.e. the arra( pointed to b( the rxfnc<re#c.s#r$#rG.
1.1.2.2 R4C)$ 8 The !ubcommand Exit 6andler
9he main 'un&tion &ode 'or this e%it handler is gi5en b( the s(mboli& name R.CM=. 8t is &alled
6hene5er the interpreter is about to &all a sub&ommand, i.e. a &ommand to an e%ternal en5ironment.
8t has onl( one sub'un&tion: R.CM=H6.
9he 8arm?lock parameter 'or this sub'un&tion has the 'ollo6ing de'inition:
t(pede' stru&t Z
t(pede' stru&t Z
unsigned int r%'&'ail:1 7
unsigned int r%'&err:1 7
[ r%&mdL'lags 7
unsigned &har Xr%&mdLaddress 7
unsigned short r%&mdLaddressl 7
unsigned &har Xr%&mdLdll 7
unsigned short r%&mdLdllLlen 7
AS98/. r%&mdL&ommand 7
AS98/. r%&mdLret& 7
[ AC,2!S9L"A, 7
9he signi'i&an&e o' ea&h 5ariable is:
Ir%&mdL'lags.r%'&'ailJ
8' this 'lag is set, the interpreter 6ill raise a FA!(0R1 &ondition at the return o' the
228
e%it handler.
Ir%&mdL'lags.r%'&errJ
3i-e the pre5ious, but the >O &ondition is raised instead.
Ir%&mdLaddressJ
"oints to a &hara&ter arra( &ontaining the name o' the en5ironment to 6hi&h the
&ommand normall( 6ould be sent.
Ir%&mdLaddresslJ
!olds the length o' rxcmd<address. /ote that the last &hara&ter is the letter ell, not
the number one.
Ir%&mdLdllJ
2e'ines the name 'or the 233 6hi&h is to handle the &ommand. 8Pm not sure 6hat
this entr( is used 'or. 8t is not &urrentl( in use 'or Regina.
*r%&mdLdllLlenJ
!olds the length o' rxcmd<dll. 8' this length is set to Hero, the sub&ommand handler
'or this en5ironment is not a 233, but an >A> handler.
Ir%&mdL&ommandJ
!olds the &ommand string to be e%e&uted, in&luding &ommand name and
parameters.
Ir%&mdLret&J
Set b( the e%it handler to the string 6hi&h is to be &onsidered the return &ode 'rom
the &ommand. 8t is assigned to the spe&ial 5ariable RC at return 'rom the e%it
handler. 9he user is responsible 'or allo&ating spa&e 'or this 5ariable. 8 ha5e no
&lear idea 6hat happens i' rxcmd<re#c.s#r$#r is set to /0337 it might set RC to
Hero, to the null string, or e5en drop it.
8t seems that this e%it handler is &apable o' raising both the 1RR@R and the FA!(0R1 &onditions
simultaneousl(. 8 donPt -no6 6hether that is legal, or 6hether onl( the FA!(0R1 &ondition is
raised, sin&e the 1RR@R &ondition is a sort o' subset o' FA!(0R1.
/ote that the return 'ields o' the parameter blo&- are onl( rele5ant i' the 5alue
R.1.!6<HAN=(1= 6as returned. 9his applies to the rxcmd<flags and rxcmd<re#c 'ields o' the
stru&ture.
1.1.2.3 R4)!= 8 The External $ata =ueue Exit 6andler
9he e%ternal data Kueue e%it handler is used as a hoo- 'or operations manipulating the e%ternal data
Kueue For the sta&-G. 0n'ortunatel(, the sta&- is a borderline &ase o' 6hat is rele5ant to the Rexx
AA A8!. Operations li-e putting something on, retrie5ing a string 'rom, obtaining the siHe, et&. o'
the sta&- is not part o' the AA A8!.
!o6e5er, some o' this 'un&tionalit( is seemingl( here7 but not all. 1or instan&e 'or the
R.M/8(( sub'un&tion, AA A8! is &alled b( the interpreter be'ore the interpreter &alls 6hate5er
s(stem$spe&i'i& &all is a5ailable 'or retrie5ing a string 'rom the sta&-.
9hus the AA A8! &an be used b( an appli&ation to pro5ide the interpreter 6ith a 'a-e sta&-, but it
is not a suitable means 'or the appli&ation itsel' to manipulate the real sta&-.
9he R.MG e%it has 'our sub'un&tions:
IA,SB"33J
9his is &alled be'ore a line is retrie5ed 'rom the sta&- and the appli&ation ma( itsel'
pro5ide the interpreter 6ith an alternati5e line. On entr(, the third parameter points
to a stru&ture ha5ing the 'ollo6ing de'inition:
t(pede' stru&t Z
229
AS98/. r%msKLret&7
[ A,SB"33L"A,7
9he rxms-<re#c 'ield holds the string to be retrie5ed 'rom the sta&-. /ote that it is
an output parameter, so its 5alue on entr( is unde'ined.
IA,SB"S!J
9his is &alled be'ore the interpreter puts a line on the sta&-, and it ma( grab the line
itsel', and thus pre5ent the interpreter 'rom putting the line on the sta&-. /ote that
this e%it handles both pushing and Kueuing. 9he third parameter is:
t(pede' stru&t Z
stru&t Z
unsigned r%'mli'o: 17
[ r%msKL'lags7
AS98/. r%msKL5alue7
[ A,SB"S!L"A,7
!ere the 'ield rxms-<>al'e holds the string to be put on the sta&-. Dhether the
string is to be pushed or Kueued is determined b( the boolean 5alue
rxms-<flags.rxmlfifo, 6hi&h is 6R01 i' the string is to be pushed.
All 5alues are input 5alues. Dhat happens i' (ou &hange them is not de'ined in the
AA A8!. Some implementations ma( let (ou modi'( the &ontents o' rxms-<>al'e
and return R.1.!6<N@6<HAN=(1= and the string push b( the interpreter
&ontains the modi'ied string. !o6e5er, (ou should not rel( on this sin&e it is highl(
in&ompatible. Cou ma( not de$allo&ate rxms-<>al'e.
IA,SBS8NJ
this is &alled be'ore the interpreter tries to determine the siHe o' the sta&-, and it ma(
present an alternati5e siHe to the interpreter. 9he third parameter is:
t(pede' stru&t Z
03O/. r%msKLsiHe7
[ A,SBS8NL"A,7
9he 'ield rxms-<siGe &an be set to the number the appli&ation 6ants the
/0101=24 'un&tion to return. /ote that this parameter is unde'ined on entr(, so it
&annot be used to retrie5e the number o' lines on the sta&-.
IASB/A,J
9his is &alled be'ore the interpreter tries to retrie5e the name o' the &urrent sta&-, and
it ma( present the interpreter 6ith an alternati5e name. /ote that this 'un&tionalit( is
part o' AA but not 6R(7 it supports the .et option o' the R./010124 built$in
'un&tion. /ote that there are no other e%its supporting the other options o'
R./010124. 9he third parameter 'or this e%it is:
t(pede' stru&t Z
AS98/. r%msKLname7
[ A,SB/A,L"A,7
As 6ith R./M!H, the 'ield rxms-<name &an be set to the name 6hi&h the
appli&ation 6ants to return to the interpreter as the name o' the &urrent sta&-. /ote
that this is an output$onl( parameter7 its 5alue on input is unde'ined, and in parti&ular
230
is not the name o' the real sta&-.
/ote that this area is troublesome. 8n 6R(, e%ternal data Kueues are not de'ined as part o' the
language, 6hile in AA it is. 9hus, 6R($&ompliant interpreters are li-el( to implement sta&-s in
5arious 6a(s that ma( not be &ompatible 6ith the AA.
1.1.2.4 R4!I- 8 The !tandard I.- Exit 6andler
9he main &ode 'or this e%it handler has the s(mboli& 5alue R.!@. 9here are 'our sub$'un&tions:
IAS8O29J
Called 6hene5er the interpreter needs to read a line 'rom the user during intera&ti5e
tra&ing. /ote the di''eren&e bet6een this sub'un&tion and R.!@6R=.
IAS8OSACJ
Called 6hene5er the interpreter tries to 6rite something to standard output in a A7
instru&tion, e5en a A7 instru&tion 6ithout a parameter.
IAS8O9CJ
Called 6hene5er the interpreter tries to 6rite out debugging in'ormation, e.g. during
tra&ing, as a tra&e ba&-, or as a s(nta% error message.
IAS8O92J
Called 6hene5er the interpreter need to read 'rom the standard input stream during a
80(( or 8AR1 80(( instru&tion. /ote that it 6ill not be &alled i' there is
su''i&ient data on the sta&- to satis'( the operation.
/ote that these 'un&tion are onl( &alled 'or the e%a&t situations that are listed abo5e. e.g. the
R.!@A7 is not &alled during a &all to the Rexx built$in 'un&tion (!N1@0624 that 6rites to the
de'ault output stream. 6R( sa(s that A7 is identi&al to &alling (!N1@0624 'or the standard output
stream, but SAA A"8 still manages to see the di''eren&e bet6een stem 5ariables and &ompound
5ariables 6ith a aa<ero)length)stringPP tail. "lease bear 6ith this in&onsisten&(.
2epending on the sub'un&tion, the 8arm?lock parameter 6ill ha5e 'our onl( slightl( di''erent
de'initions. 8t is -ind o' 'rustrating that the 8arm?lock ta-es so man( di''erent datat(pes, but it &an
be handled easil( using 'nions, see a later se&tion. 9he de'initions are:
t(pede' stru&t Z
AS98/. r%siodtrLret& 7 #X the intera&ti5e tra&e input X#
[ AS8O29L"A, 7
t(pede' stru&t Z
AS98/. r%sioLstring 7 #X the SAC line to 6rite out X#
[ AS8OSACL"A, 7
t(pede' stru&t Z
AS98/. r%sioLstring 7 #X the debug line to 6rite out X#
[ AS8O9CL"A, 7
t(pede' stru&t Z
AS98/. r%siotrdLret& 7 #X the line to read in X#
[ AS8O92L"A, 7
8n all o' these, the R.6R!NG stru&ture either holds the 5alue to be 6ritten out F'or R.!@A7
and R.!@6RCG, or the 5alue to be used instead o' reading standard input stream F'or
R.!@6R= and R.!@=6RG. /ote that the 5alues set b( R.!@6R= and R.!@=6R are
231
ignored i' the e%it handler does not return the 5alue R.1.!6<HAN=(1=.

An( end$o'$line mar-er are stripped o'' the strings in this &onte%t. 8' the e%it handler 6rites out the
string during R.!@A7 or R.!@6RC, it must suppl( an( end$o'$line a&tion itsel'. Similarl(,
the interpreter does not e%pe&t a end$o'$line mar-er in the data returned 'rom R.!@=6R and
R.!@6R=.
9he spa&e used to store the return data 'or the R.!@=6R and R.!@6R= sub$'un&tions, must be
pro5ided b( the e%it handler itsel', and the spa&e is not de$allo&ated b( the interpreter. 9he spa&e
&an be reused b( the appli&ation at an( later time. 9he spa&e allo&ated to hold the data gi5en b( the
R.!@A7 and R.!@6RC sub$'un&tions, 6ill be allo&ated b( the interpreter, and must neither
be de$allo&ated b( the e%it handler, nor used a'ter the e%it handler has terminated.
1.1.2.2 R46#T 8 The 6alt Condition Exit 6andler
/ote: :e&ause the R.H(6 e%it handler is &alled a'ter e5er( Rexx instru&tion, enabling this e%it
slo6s Rexx program e%e&ution.
9he main &ode 'or this e%it handler has the s(mboli& 5alue R.H(6. 9here are t6o sub$'un&tions:
IA!399S9J
Called 6hene5er the interpreter polls e%ternall( raised HA(6 &onditions7 i.e. a'ter
e5er( Rexx instru&tion.
9he de'inition o' the 8arm?lock is:
t(pede' stru&t Z
unsigned r%'hhlt : 1 7
[ A!399S9L"A, 7
9he rxf""l# parameter is set to the state o' the HA(6 &ondition in the interpreter7
either 6R01 or FA(1.
IA!39C3J
Called to a&-no6ledge pro&essing o' the !A39 &ondition 6hen the interpreter has
re&ogniHed and raised a !A39 &ondition.
1.1.2.3 R4TRC 8 The Trace !tatus Exit 6andler
/ot implemented.
1.1.2.5 R4I'I 8 The InitialiAation Exit 6andler
R.61R and this e%it handler are a bit di''erent 'rom the others. R.!N! pro5ides the appli&ation
programmer 6ith a method o' getting &ontrol be'ore the e%e&ution o' the s&ript starts. 8ts main
purpose is to enable manipulation o' the 5ariable pool in order to set up &ertain 5ariables be'ore the
s&ript starts, or set the tra&e mode.
8t has onl( one sub'un&tion, R.!N!1.6, &alled on&e during ea&h &all to Rexx#ar#24: \ust be'ore
the 'irst Rexx statement is interpreted. 4ariable manipulations per'ormed during this e%it 6ill ha5e
e''e&t 6hen the s&ript starts.
As there is no in'ormation to be &ommuni&ated during this e%it, the 5alue o' 8arm?lock is
unde'ined. 8t ma-es no di''eren&e 6hether (ou return R.1.!6<HAN=(1= or
R.1.!6<N@6<HAN=(1=, sin&e there is no situation to handle.
1.1.2.7 R4TER 8 The Termination Exit 6andler
9his e%it resembles R.!N!. 8ts sole sub'un&tion is R.61R1.6, 6hi&h is &alled on&e, \ust a'ter the
232
last statement o' the Rexx s&ript has been interpreted. 9he state o' all 5ariables are inta&t during this
&all7 so it &an be used to retrie5e the 5alues o' the 5ariables at the e%it o' a s&ript. F8n 'a&t, that is the
6hole purpose o' this e%it handler.G
3i-e R.!N!, there is no in'ormation to be &ommuni&ated during the e%it, so 8aram?lock is
unde'ined in this &all. And also li-e R.!N!, it is more o' a hoo- than an e%it handler, so it does not
matter 6hether (ou return R.1.!6<HAN=(1= or R.1.!6<N@6<HAN=(1=.
1.1.2.9 R4E'; 8 The External En*ironment Exit 6andler
9his S(stem >%it is spe&i'i& to Regina, so &aution should be e%er&ised i' (ou plan on ma-ing (our
&ode portable to other Rexx interpreters.
9he main &ode 'or this e%it handler has the s(mboli& 5alue R.1ND. 9here are 'our sub$'un&tions:
IA.>9>/4J
Called 6hene5er the :817 V";UFG is &alled to obtain a 5alue 'rom the e%ternal
en5ironment. i.e. the &all to V";UFG is o' the 'orm:
V";UB/V".+"3/) )/+VI.O+3+,/C.
IAS>9>/4J
Called 6hene5er the :817 V";UFG is &alled to set a 5alue in the e%ternal
en5ironment. i.e the &all to V";UFG is o' the 'orm:
V";UB/V".+"3/)ne0value)/+VI.O+3+,/C.
IA.>9CD2J
Called 6hene5er the &urrent 6or-ing dire&tor( is needed to be obtained 'rom the
en5ironment. 9he AI.$,O.*FG :81 respe&ts this s(stem e%it.
IAS>9CD2J
Called 6hene5er the &urrent 6or-ing dire&tor( is &hanged b( a &all to
AI.$,O.*FG or $9AI.FG :81s.
9he 8arm?lock parameter has the 'ollo6ing de'initions 'or ea&h sub$'un&tion t(pe:
t(pede' stru&t Z
AS98/. r%en5Lname 7 #X the name o' the e%ternal en5ironment 5ariable X#
AS98/. r%en5L5alue 7 #X the returned 5alue o' the e%ternal en5ironment
5ariable X#
[ A.>9>/4L"A, 7
t(pede' stru&t Z
AS98/. r%en5Lname 7 #X the name o' the e%ternal en5ironment 5ariable X#
AS98/. r%en5L5alue 7 #X the 5alue o' the e%ternal en5ironment 5ariable X#
[ AS>9>/4L"A, 7
8n both o' these, the R.6R!NGI r%en5Lname stru&ture holds the name o' the en5ironment
5ariable as -no6n b( the e%ternal en5ironment. /ote that the 5alues set b( R.!@6R= and
R.!@=6R are ignored i' the e%it handler does not return the 5alue R.1.!6<HAN=(1=.

9he spa&e used to store the return data 'or the R.!@=6R and R.!@6R= sub$'un&tions, must be
pro5ided b( the e%it handler itsel', and the spa&e is not de$allo&ated b( the interpreter. 9he spa&e
&an be reused b( the appli&ation at an( later time. 9he spa&e allo&ated to hold the data gi5en b( the
R.!@A7 and R.!@6RC sub$'un&tions, 6ill be allo&ated b( the interpreter, and must neither
be de$allo&ated b( the e%it handler, nor used a'ter the e%it handler has terminated.
233
7.5 The External =ueue Interface
9he e%ternal Kueue inter'a&e pro5ide a me&hanism 'or intera&ting 6ith the interpreterPs e%ternal
Kueues. 9his inter'a&e is analogous to a Rexx programPs use o' "0S!, B0>0>, "033, and
AB0>0>FG. /ote that this inter'a&e onl( 6or-s 6ith the e%ternal Kueues, it &annot inter'a&e to the
internal named Kueues that e%ists 6ithin the interpreter.
7.5.1 The RexxCreate=ueueCD function
9his 'un&tion is used to &reate a ne6, named, e%ternal Kueue.
9he protot(pe 'or RexxCrea#e/'e'e24 is:
A"8>9 A"8>/9C e%%CreateBueueF
"SN :u''er,
03O/. :u''3en,
"SN eKuested/ame,
03O/. X2up1lag
G 7
9he 'ollo6ing parameters are input, and their signi'i&an&e are:
IeKuested/ameJ
"oints to an ASC88 /03 terminated &hara&ter string 6hi&h spe&i'ies the name o' the
Kueue to be &reated. See Bueue /ames 'or the stru&ture o' a Kueue name. 8' the user
6ishes to ha5e the interpreter &reate a uniKue Kueue name on the lo&al Kueue ser5er
at the de'ault port number, then this 5alue should be set to /033. 9o reKuest an
interpreter$generated Kueue name, on the ma&hine &red listening on port >9>9, then
spe&i'( ?&red*>9>9. i.e. lea5e the Kueue name portion blan-.
9he 'ollo6ing parameters are output, and their signi'i&an&e are:
I:u''erJ
"oints to an ASC88 /03 terminated &hara&ter string allo&ated b( the user. 9he name
o' the Kueue that is &reated 6ill be &opied into this area.
I:u''3enJ
Spe&i'ies the siHe o' the memor( area pointed to b( 0u&&er.
I2up1lagJ
8ndi&ates i' the Kueue name spe&i'ied alread( e%ists. 8' a Kueue name alread( e%ists,
2up1lag is set to 1, other6ise it is set to 0.

9he RexxCrea#e/'e'e24 returns an 'nsigned long, 6hi&h &arries status in'ormation des&ribing
the out&ome o' the operation. 9he status 6ill be one o' the R./0101 5alues:
IAB0>0>LOMJ
9he Kueue 6as su&&ess'ull( &reated.
IAB0>0>L/O>,>,J
9he Kueue 6as not &reated, due to la&- o' memor(.
IAB0>0>L:A2B/A,>J
234
9he Kueue name is in5alid or US>SS8O/V is spe&i'ied.
7.5.2 The Rexx$elete=ueueCD function
9his 'un&tion is used to delete a named, e%ternal Kueue.
9he protot(pe 'or Rexx=ele#e/'e'e24 is:
A"8>9 A"8>/9C e%%2eleteBueueF
"SN Bueue/ame
G 7
9he onl( parameters is an input, and its signi'i&an&e is:
IBueue/ameJ
Kueue to be deleted. See Bueue /ames 'or the stru&ture o' a Kueue name.
9he Rexx=ele#e/'e'e24 returns an 'nsigned long, 6hi&h &arries status in'ormation des&ribing
IAB0>0>LOMJ
9he Kueue 6as su&&ess'ull( deleted.
IAB0>0>L/O9>.J
9he Kueue name spe&i'ied does not e%ist.
IAB0>0>L:A2B/A,>J
9he Kueue name 6as not spe&i'ied.
7.5.3 The Rexx=uer&=ueueCD function
9his 'un&tion is used to determine the number o' items that are a5ailable on the named, e%ternal
Kueue.
9he protot(pe 'or Rexx/'e'e/'e'e24 is:
A"8>9 A"8>/9C e%%Buer(BueueF
"SN Bueue/ame,
03O/. XCount
G 7
One parameters is an input, and its signi'i&an&e is:
IBueue/ameJ
Kueue to be Kueried. See Bueue /ames 'or the stru&ture o' a Kueue name.
9he 'ollo6ing parameter is output, and its signi'i&an&e is:
ICountJ
"oints to an unsigned long 6hi&h indi&ates the number o' items on the spe&i'ied
Kueue.
235
9he Rexx/'er;/'e'e24 returns an 'nsigned long, 6hi&h &arries status in'ormation des&ribing
IAB0>0>LOMJ
9he Kueue 6as su&&ess'ull( Kueried, and !ount &ontains the number o' items on the
Kueue.
IAB0>0>L/O9>.J
IAB0>0>L:A2B/A,>J
9he Kueue name 6as not spe&i'ied
7.5.4 The Rexx(dd=ueueCD function
9his 'un&tion is used to determine add an item to a named, e%ternal Kueue.
9he protot(pe 'or RexxAdd/'e'e24 is:
A"8>9 A"8>/9C e%%AddBueueF
"SN Bueue/ame,
"AS98/. >ntr(2ata,
03O/. Add1lag
G 7
All parameters are input, and their signi'i&an&e are:
IBueue/ameJ
Kueue on 6hi&h the data is to be added. See Bueue /ames 'or the stru&ture o' a
Kueue name.
I>ntr(2ataJ
"oints to a AS98/. stru&ture &ontaining the data to be added to the Kueue.
IAdd1lagJ
8ndi&ates ho6 the data is to be added. Can be one o':
AB0>0>L181O, to indi&ate that the data is to be added in a 'irst$in$'irst$out order.
9his is eKui5alent to the B0>0> -e(6ord.
AB0>0>L381O, to indi&ate that the data is to be added in a last$in$'irst$out order.
9his is eKui5alent to the "0S! -e(6ord.
9he RexxAdd/'e'e24 returns an 'nsigned long, 6hi&h &arries status in'ormation des&ribing the
out&ome o' the operation. 9he status 6ill be one o' the R./0101 5alues:
IAB0>0>LOMJ
9he data 6as su&&ess'ull( added to the spe&i'ied Kueue.
IAB0>0>L/O9>.J
IAB0>0>L:A2B/A,>J
7.5.2 The RexxPull=ueueCD function
9his 'un&tion is used to e%tra&t an item 'rom the spe&i'ied named, e%ternal Kueue. Dhen su&&ess'ul,
the item 'rom the Kueue is returned, and that item deleted 'rom the Kueue.
236
9he protot(pe 'or Rexx8'll/'e'e24 is:
A"8>9 A"8>/9C e%%"ullBueueF
"SN Bueue/ame,
"AS98/. 2ata:u',
"2A9>98,> 9imeStamp,
03O/. Dait1lag
G 7
9he 'ollo6ing parameters are input, and their signi'i&an&e are:
IBueue/ameJ
Kueue 'rom 6hi&h the data is to be e%tra&ted. See Bueue /ames 'or the stru&ture o'
a Kueue name.
IDait1lagJ
8ndi&ates i' the pro&ess should 6ait until there is data in the spe&i'ied Kueue be'ore
returning. 9his &ould &ause the pro&ess to blo&- 'ore5er, i' no data is due in the
Kueue. Regina does not support this option at this stage7 AB0>0>L/ODA89 is
assumed 4alue &an be one o':
AB0>0>LDA89, the pro&ess is to blo&- and 6ait 'or data i' the Kueue is &urrentl(
empt(.
AB0>0>L/ODA89, the pro&ess does not 6ait 'or data in the Kueue i' it is
&urrentl( empt(. e%%"ullBueueFG 6ill return AB0>0>L>,"9C i' there is no
data in the Kueue.
9he 'ollo6ing parameters are output, and their signi'i&an&e are:
I2ata:u'J
"oints to a AS98/. stru&ture into 6hi&h the &ontents o' the e%tra&ted item are
pla&ed. 9he memor( asso&iated 6ith the AS98/. strptr, should be deallo&ated
using e%%1ree,emor(FG.
I9imeStampJ
"oints to a "2A9>98,> stru&ture, 6hi&h on return, &ontains the time details o'
6hen the item 6as added to the e%ternal Kueue. Regina does not support this option
at this stage.
9he Rexx8'll/'e'e24 returns an 'nsigned long, 6hi&h &arries status in'ormation des&ribing the
out&ome o' the operation. 9he status 6ill be one o' the R./0101 5alues:
IAB0>0>LOMJ
9he data 6as su&&ess'ull( added to the spe&i'ied Kueue.
IAB0>0>L/O9>.J
IAB0>0>L:A2B/A,>J
IAB0>0>L>,"9CJ
9he Kueue 6as empt( and AB0>0>L/ODA89 6as spe&i'ied.
IAB0>0>L:A2DA8913A.J
9he 5alue o' the ;ait+lag parameter 6as not AB0>0>LDA89 or
237
AB0>0>L/ODA89.
238
7.7 The )acro !pace Interface
9he ma&ro spa&e inter'a&e pro5ide a me&hanism 'or pre$loading e%ternal Rexx programs into the
&urrent interpreterPs ma&ro spa&e, so that the ma&ros &an be e%e&uted 'aster than reading them 'rom
dis- ea&h time the( are &alled. 9his inter'a&e is not a5ailable in Regina at this stage.
7.7.1 The Rexx(dd)acroCD function
7.7.2 The Rexx$rop)acroCD function
7.7.3 The Rexx!a*e)acro!paceCD function
7.7.4 The Rexx#oad)acro!paceCD function
7.7.2 The Rexx=uer&)acroCD function
7.7.3 The RexxReorder)acroCD function
7.7.5 The RexxClear)acro!paceCD function
239
7.9 (llocating and $e8allocating !pace
1or se5eral o' the 'un&tions des&ribed in this &hapter, the appli&ation &alling them must allo&ate or
de$allo&ate d(nami& memor(. 2epending on the operating s(stem, &ompiler and Rexx interpreter,
the method 'or these allo&ations and de$allo&ations 5ar(. :e&ause o' this, Regina supplies the A"8
'un&tion &alls e%%Allo&ate,emor(FG and e%%1ree,emor(FG. 9hese 'un&tions are 6rappers 'or
the appropriate &ompiler or operating s(stem memor( 'un&tions.
7.9.1 The Rexx(llocate)emor&CD function
9he protot(pe 'or RexxAlloca#eMemor;24 is:
"4O82 A"8>/9C e%%Allo&ate,emor(F
03O/. siHe
G 7
9he parameter is an input, and its signi'i&an&e is:
IsiHeJ
9he number o' b(tes o' d(nami& memor( reKuested.
RexxAlloca#eMemor;FG returns a pointer to the ne6l( allo&ated blo&- o' memor(, or /033 i' no
memor( &ould be allo&ated.
7.9.2 The Rexx/ree)emor&CD function
9he protot(pe 'or RexxFreeMemor;24 is:
A"8>9 A"8>/9C e%%1ree,emor(F
"4O82 ,emor(:lo&-
G 7
9he parameter is an input, and its signi'i&an&e is:
I,emor(:lo&-J
A 5oid pointer to the blo&- o' memor( allo&ated b( the interpreter, or allo&ated b( a
pre5ious &all to RexxAlloca#eMemor;FG.
RexxFreeMemor;FG al6a(s return 0.
240
7.1: Calling bac+ into running Rexx Code
9his se&tion des&ribes the RexxCall?ack24 'un&tion, 6hi&h allo6s the appli&ation to e%e&ute a
pro&edure 6ithin the running Rexx program. 9his 'un&tion is parti&ularl( use'ul 'or building a
Rexx inter'a&e to those librar( appli&ations that operate using a &allba&- me&hanism.
A &allba&- me&hanism is one 6here &ertain e5ents 6ithin a parti&ular appli&ation &an be connected
to a parti&ular 'un&tion, so that 6hen a parti&ular e5ent o&&urs, the connected 'un&tion is e%e&uted.
,an( C librar( appli&ations use a &allba&- me&hanism.
9his 'un&tion is spe&i'i& to Regina, so &aution should be e%er&ised i' (ou plan on ma-ing (our &ode
portable to other Rexx interpreters.
7.1:.1 The RexxCall%ac+CD function
9his 'un&tion is used to e%e&ute an internal pro&edure 6ithin the running Rexx s&ript. 9he
pro&edure is e%e&uted 6ith the same &onte%t as i' the pro&edure 6ere &alled 'rom 6ithin the Rexx
program as a 'un&tion &all.
A"8>9 A"8>/9C e%%Call:a&-F
"SN "ro&edure/ame,
3O/. ArgCount,
"AS98/. Arg3ist,
"0S!O9 eturnCode,
"AS98/. esult
G 7
O' these parameters, Re#'rnCode and Res'l# are output$onl(. 9he rest o' the parameters are input$
onl(. 9he signi'i&an&e o' the parameters are:
*"ro&edure/ameJ
An ASC88 /03 terminated string, spe&i'(ing the name o' the internal pro&edure o'
the running Rexx s&ript to be e%e&uted. 9his internal pro&edure name must e%ist or
this 'un&tion 6ill return 6ith R.<C?<?A=N.
IArgCountJ
9he number o' parameter strings gi5en to the pro&edure. 9his is the number o'
de'ined Rexx$strings pointed to b( the Arg(is# parameter. 9he de'ault ma%imum
number o' arguments that &an be passed is =2, but this &an be &hanged b( the
MA.<ARG<6@<R1..6AR6 ma&ro in re%%.h.
*Arg3istJ
"ointer to an arra( o' Rexx$strings, &onstituting the parameters to this &all to Rexx.
9he siHe o' this arra( is gi5en b( the parameter ArgCo'n#. 8' ArgCo'n# is greater
than one, the 'irst and last parameters are Arg(is#*B, and Arg(is#*ArgCo'n#-C,. 8'
ArgCount is 0, the 5alue o' Arg(is# is irrele5ant.
8' the s#r$#r o' one o' the elements in the arra( pointed to b( Arg(is# is /033, that
means that this parameter is empt( Fi.e. unspe&i'ied, as opposed to a string o' Hero
siHeG.
IeturnCodeJ
"ointer to a H@R6 integer 6here the return &ode 'rom the &alled 8roced'reName
is stored, pro5ided that the returned 5alue is numeri&, and 6ithin the range $F2XX15G
241
to 2XX15$1. 8 donPt -no6 6hat happens to Re#'rnCode i' either o' these &onditions
is not satis'ied. 8t probabl( be&omes unde'ined, 6hi&h means that it is totall( useless
sin&e the program has to inspe&t the return string in order to determine 6hether
Re#'rnCode is 5alid.
it.
IesultJ
"oints to a Rexx string into 6hi&h the result string 'rom the &alled 8roced'reName
is 6ritten. 9he &aller ma( or ma( not let the s#r$#r 'ield be supplied. 8' supplied Fi.e.
it is non$/033G, that area 6ill be used, else a ne6 area 6ill be allo&ated. 8' the
supplied area is used, its siHe is supposed to be gi5en b( the s#rleng#" 'ield. 8' the
siHe i' not su''i&ient, a ne6 area 6ill be allo&ated, b( RexxAlloca#eMemor;24, and
the &aller must see to that it is properl( de$allo&ated using RexxFreeMemor;24.
it.
/ote that the ArgCo'n# parameter need not be the same as the ARG24 built$in 'un&tion 6ould
return. 2i''eren&es 6ill o&&ur i' the last entries in Arg(is# are null strings.
9he arguments passed to the 8roced'reName 6ill be passed indi5iduall(. i.e. the 8AR1 ARG
&ommand in the 8roced'reName must use &ommas to separate the arguments.
9he 5alid return 5alues 'rom RexxCall?ack24 are:
I/egati5eJ
indi&ates that a s(nta% error o&&urred during interpretation. 8n general, (ou &an
e%pe&t the error 5alue to ha5e the same absolute 5alue as the Rexx s(nta% error Fbut
opposite signs, o' &ourseG.
INero, or R.<C?<@:J
indi&ates that the interpreter 'inished e%e&uting the pro&edure 6ithout errors.
I"ositi5eJ
indi&ates probabl( that some problem o&&urred, that made it impossible to e%e&ute
the pro&edure, e.g. a bad parameter 5alue. 9he 5alues that &an be return are:
R.<C?<?A=8 bad parameters
R.<C?<N@66AR61= there is no running Rexx program
R.<C?<6@@MAN78 too man( parameters supplied
R.<C?<?A=N the 8roced'reName does not e%ist
2uring the &ourse o' an e%e&ution o' RexxCall?ack24, sub&ommand handlers and e%it handlers
might be &alled. 9hese ma( &all an( 'un&tion in the appli&ation inter'a&e, in&luding another
in5o&ation o' RexxCall?ack24.
242
9 Implementation #imits
This chapter lists the i#ple#entation li#its re1uired by the Rexx standard. 'll i#ple#entations are
supposed to support at least these li#its.
9.1 ?h& <se #imitsB
Dh( use implementation limits at allS O'ten, a program FabGuses a 'eature in a language to an e%tent
that the implementor did not 'oresee. Suppose an implementor de&ides that 5ariable names &an not
be longer than ?< b(tes. Sooner or later, a programmer gets the idea o' using 5er( long 5ariable
names to en&ode spe&ial in'ormation in the name7 ma(be as the output o' a ma&hine generated
program. 9he result 6ill be a program that 6or-s onl( 'or some interpreters or onl( 'or some
problems.
:( introdu&ing implementation limits, Rexx tells the implementors to 6hat e%tent a implementation
is reKuired to support &ertain 'eatures, and simultaneousl( it tells the programmers ho6 mu&h
'un&tionalit( the( &an assume is present.
/ote that these limited are reKuired minimums 'or 6hat an implementation must allo6. An
interpreter is not supposed to en'or&e these limits unless there is a good reason to.
9.2 ?hat #imits to ChooseB
A limit must not be per&ei5ed as an absolute limit, the implementer is 'ree to in&rease the limit. 9o
some e%tent, the implementer ma( also de&rease the limit, in 6hi&h &ase this must be properl(
do&umented as a non$standard 'eature. Also, the reason 'or this should be noted in the
do&umentation.
,an( interpreters are li-el( to ha5e ;memor(; as an implementation limit, meaning that the( 6ill
allo6 an( siHe as long as there is enough memor( le't. A&tuall(, this is eKui5alent to no limit, sin&e
running out o' memor( is an error 6ith limit en'or&ing interpreters as 6ell. Some interpreters let the
user set the limits, o'ten &ontrolled through the OP,IO+S instru&tion.
1or &omputers, limit &hoi&es are li-el( to be po6ers o' t6o, li-e 25?, 102<, +1*2, et&. !o6e5er, the
Rexx language ta-es the side o' the user, and de'ines the limits in units 6hi&h loo-s as more
;sensible; to &omputer non$e%perts: most o' the limits in Rexx are numbers li-e 250, 500, 1000,
et&.
9.3 ReGuired #imits
9hese are the implementation minimums de'ined b( Rexx:
+A56ar) (4r56g(,
,ust be able to hold at least 50 &hara&ters a'ter pa&-ing. 9hat means that the unpa&-ed siHe
might be at least <00 &hara&ters, plus embedded 6hite spa&e.
+la%(e 45*e -lo-=,
,ust be able to run 'or at least 10XX10$1 se&onds, 6hi&h is appro%imatel( =1.? (ears. 8n
general, this is reall( a big o5er-ill, sin&e 5irtuall( no program 6ill run 'or a su&h a period.
243
A&tuall(, 'e6 &omputers 6ill be operational 'or su&h a period.
+'e$a0e-5*al (4r56g(,
,ust be able to hold at least 50 &hara&ters a'ter pa&-ing. 9his means that the unpa&-ed siHe
might be at least 100 &hara&ters, plus embedded 6hite spa&e.
+L54eral (4r56g(,
,ust be able to hold at least 100 &hara&ters. /ote that a double o&&urren&e o' the Kuote
&hara&ter Fthe same &hara&ter used to delimit the stringG in a literal string &ounts as a single
&hara&ter. 8n parti&ular, it does not &ount as t6o, nor does it start a ne6 string.
+Ne(456g of -o**e64(,
,ust be possible to in at least 10 le5els. Dhat happens then is not reall( de'ined. ,a(be one
o' the s(nta% errors is issued, but none is ob5ious 'or this use. Another, more dangerous 6a(
o' handling this situation 6ould be to ignore ne6 start$o'$&omments designators 6hen on
le5el 10. 9his &ould, under &ertain &ir&umstan&es, lead to running o' &ode that is a&tuall(
&ommented out. !o6e5er, most interpreter are li-el( to support nesting o' &omments to an
arbitrar( le5el.
+The N3*ber of !ara*e4er(,
8n &alls must be supported up to at least 10 parameters. ,ost implementations support
some6hat more than that, but Kuite a 'e6 en'or&e some sort o' upper limit. 1or the built$in
'un&tion, this ma( be a problem onl( 'or 3I+BC and 3"-BC.
+S5g65f5-a64 05g54(,
,ust be supported to at least * de&imal digits. Also, i' an implementation supports 'loating
point numbers, it should allo6 e%ponents up to * de&imal digits. An implementation is
allo6ed to operate 6ith di''erent limits 'or the number o' signi'i&ant digits and the numbers
o' digits in e%ponents.
+S3bro3456e le9el(,
,a( be nested to a total o' 100 le5els, 6hi&h &ounts both internal and e%ternal 'un&tions, but
probabl( not built$in 'un&tions. Cou ma( a&tuall( trip in this limit i' (ou are using re&ursi5e
solution 'or large problems. Also, some tail$re&ursi5e approa&hes ma( &rash in this limit.
+S)*bol (6a*e) le6g4h,
Can be at least 50 &hara&ters. 9his is the name o' the s(mbol, not the length o' the 5alue i' it
names a 5ariable. /or is it the name o' the 5ariable a'ter tail substitution. 8n other 6ords, it
is the s(mbol as it o&&urs in the sour&e &ode. /ote that this applies not onl( to simple
s(mbols, but also &ompound s(mbols and &onstant s(mbols. ConseKuentl(, (ou &an not
6rite numbers o' more than 50 digits in the sour&e &ode, e5en i' +U3.I$ AI>I,S is set
high.
+#ar5able 6a*e le6g4h,
O' at least 50 &hara&ters. 9his is the name o' a 5ariable F6hi&h ma( or ma( not be setG a'ter
tail substitution.
9.4 -lder C-bsoleteD #imits
1irst edition o' 931 &ontained some additional limits, 6hi&h ha5e been rela%ed in the se&ond
edition in order to ma-e implementation possible 'or a large set o' &omputers. 9hese limits are:
+"lo-= gra63lar54),
Das de'ined to be at least o' a millise&ond.
1ar 'rom all &omputers pro5ide this granularit(, so the reKuirement ha5e been rela%ed. 9he
&urrent reKuirement is a granularit( o' at least one se&ond, although a millise&ond
granularit( is ad5ised.
244
9.2 ?hat the !tandard does not !a&
An implementation might en'or&e a &ertain limit e5en though one is not spe&i'ied in the standard.
9his se&tion tries to list most o' the pla&es 6here this might be the &ase:
+The (4a-=,
FAlso &alled: the e%ternal data KueueG is not 'ormall( de'ined as a &on&ept o' the language
itsel', but a &on&ept to 6hi&h the Rexx language has an inter'a&e. Se5eral limits might appl(
to the sta&-, in parti&ular the ma%imum length o' a line in the sta&- and the ma%imum
number o' lines the sta&- &an hold at on&e.
9here might also be also be other limits related to the sta&-, li-e a ma%imum number o'
bu''ers or a ma%imum number o' di''erent sta&-. 9hese &on&epts are not re'erred to b(
Rexx, but the programmer ought to be a6are o' them.
+F5le(,
,a( ha5e se5eral limits not spe&i'ied b( the de'inition o' Rexx, e.g. the number o' 'iles
simultaneousl( open, the ma%imum siHe o' a 'ile, and the length and s(nta% o' 'ile names.
Some o' these limits are en'or&ed b( the operating s(stem rather than an implementation.
9he programmer should be parti&ularl( a6are o' the ma%imum number o' simultaneousl(
open 'iles, sin&e Rexx does not ha5e a standard &onstru&t 'or &losing 'iles.
+$%re((5o6 6e(456g,
Can in some interpreters onl( be per'ormed to a &ertain le5el. /o e%pli&it minimum limit has
been put 'orth, so ta-e &are in &omple% e%pressions, in parti&ular ma&hine generated
e%pressions.
+695ro6*e64 6a*e le6g4h,
,a( ha5e some restri&tions, depending on (our operating s(stem. 9here is not de'ined an(
limit, but there e%ists an error message 'or use 6ith too long en5ironment names.
+"la3(e le6g4h,
,a( ha5e an upper limit. 9here is de'ined an error message ;Clause too long; 6hi&h is
supposed to be issued i' a &lause e%&eeds a parti&ular implementation dependent siHe. /ote
that a ;&lause; does not mean a ;line; in this &onte%t7 a line &an &ontain multiple &lauses.
+So3r-e l56e le6g4h,
,ight ha5e an upper limit. 9his is not the same as a ;&lause; Fsee abo5eG. 9(pi&all(, the
sour&e line limit 6ill be mu&h larger than the &lause limit. 9he sour&e line limit ought to be
as large as the string limit.
+S4a-= o%era45o6(,
,ight be limited b( se5eral limits7 'irst there is the number o' strings in the sta&-, then there
is the ma%imum length o' ea&h string, and at last there might be restri&tions on the &hara&ter
set allo6ed in strings in the sta&-. 9(pi&all(, the sta&- 6ill be able to hold an( &hara&ter. 8t
6ill either ha5e ;memor(; as the limit 'or the number o' string and the length o' ea&h string,
or it might ha5e a 'i%ed amount o' memor( set aside 'or sta&- strings. Some
implementations also set a ma%imum length o' sta&- strings, o'ten 2X+ or 2X1?.
9.3 ?hat an Implementation is (lloed to FIgnoreF
8n order to ma-e the Rexx language implementable on as man( ma&hines as possible, the Rexx
standard allo6 implementation to ignore &ertain 'eatures. 9he e%isten&e o' these 'eatures are
re&ommended, but not reKuired. 9hese 'eatures are:
245
+Floa456g %o564 63*ber(,
Are not reKuired7 integers 6ill su''i&e. 8' 'loating points are not supported, numbers &an
ha5e not 'ra&tional or e%ponential part. And the normal di5ision 6ill not be a5ailable, i.e. the
operator ;/; 6ill not be present. 0se integer di5ision instead.
+F5le o%era45o6(,
Are de'ined in Rexx, but an implementation seems to be allo6ed to di''er in \ust about an(
'ile operation 'eature.
9.5 #imits in Regina
Regina tries not to en'or&e an( limits. Dhere5er possible, ;memor(; is the limit, at the &ost o'
some C"0 6hene5er internal data stru&tures must be e%panded i' their initial siHe 6ere too small.
/ote that Regina 6ill onl( in&rease the internal areas, not de&rease them a'ter6ards. 9he rationale
is that i' (ou happen to need a large internal area on&e, (ou ma( need it later in the same program
too.
8n parti&ular, Regina has the 'ollo6ing limits:
:inar( Strings sour&e line length
Clo&- .ranularit( 0.001$1 se&ond Fnote 2G
>lapsed 9ime &lo&- until &a. 20=+ Fnote 1G
/amed Bueues 100
!e%ade&imal Strings sour&e line length
8nterpretable String sour&e line length
3iteral String 3ength sour&e line length
/esting o' Comments memor(
"arameters memor(
Signi'i&ant 2igits sour&e line length
Sour&e 3ine 3ength 100,000 Fnote =G
Subroutine 3e5els memor(
S(mbol 3ength sour&e line length
4ariable /ame 3ength sour&e line length
91tesA
1. Regina uses the 0ni%$deri5ed &all 'i%eBC 'or the elapsed time Fand time in generalG. 9his
is a 'un&tion 6hi&h returns the number o' se&onds sin&e Oanuar( 1
st
1*@0. A&&ording to the A/S8 C
standard, in 6hi&h Regina is 6ritten, this is a number 6hi&h 6ill at least hold the number 2XX=1$1.
9here'ore, these ma&hines 6ill be able to 6or- until about 20=+, and Regina 6ill satis'( the
reKuirement o' the elapse time &lo&- until 200?. :( then, &omputers 6ill hope'ull( be ?< bit.
0n'ortunatel(, the 'i%eBC C 'un&tion &all onl( returns 6hole se&onds, so Regina is 'or&ed to use
other Fless standardisedG &alls to get a 'iner granularit(. !o6e5er, most o' 6hat is said about
246
'i%eBC applies 'or these too.
2. 9he &lo&- granularit( is a bit o' a problem to de'ine. All s(stems &an be trusted to ha5e a
granularit( o' about 1 se&ond. >%&ept 'rom that, itPs 5er( di''i&ult to sa( an(thing more spe&i'i& 'or
&ertain. ,ost s(stems allo6s alternati5e 6a(s to retrie5e the time, gi5ing a more a&&urate result.
Dhere5er these alternati5es are a5ailable, Regina 6ill tr( to use them. 8' e5er(thing else 'ails,
Regina 6ill use 1 se&ond granularit(.
1or most ma&hines, the granularit( are in the range o' a 'e6 millise&onds. Some t(pi&al e%amples
are: 20 ms 'or Sun=, < ms 'or 2e&stations =100, and 10 ms 'or S.8 8ndigo. Sin&e this is a hard6are
restri&tion, this is the best measure an(one &an get 'or these ma&hines.
=. 9he line length limit is de'ined 6hen egina is built. 2ue to the nature o' implementation
o' the sour&e parser, it is not possible to ma-e this a d(nami&all( in&rease as the sour&e line is read.
8' (ou need a line length longer than the &urrent de'ault 5alue, (ou need to ma-e t6o &hanges:
=.1. &hange CCL:01L3>/ in le%sr&.&
=.2. &hange :011>S8N> in re%%.h
See the notes in re%%.h that e%plain that CCL:01L3>/ must be larger than :011>S8N>
247
1: Regina /eatures and Implementation
This chapter lists &eatures o& Regina and speci&ic i#ple#entation capabilities.
1:.1 Regina Restricted )ode
,an( language interpreters pro5ide a me&hanism 6here &ode e%e&uted 6ithin that interpreter is
limited to a''e&ting the en5ironment o' the interpreter and &annot &hange the e%ternal en5ironment
in 6hi&h the interpreter runs.
estri&ted mode is used in situations 6here (ou need to guarantee that the author o' a Rexx
program is unable to a''e&t the userPs en5ironment.
Situations 6here a restri&ted mode is appli&able in&lude, using egina as a database pro&edural
language, or as a language plug$in 'or a Deb bro6ser.
1eatures o' egina that are disabled in restri&ted mode are:
38/>O09, C!AO09, "O">/, A10/CA22 :81s
;O">/ D89>;, ;O">/ :O9!; sub&ommands o' S9>A, :81
9he ;built$in; en5ironments eg. SCS9>,, C,2 or "A9! o' A22>SS &ommand
Setting the 5alue o' a 5ariable in the e%ternal en5ironment 6ith 4A30> :81.
Calling e%ternal 'un&tions
9o run Regina in restri&ted mode, (ou &an start the Regina interpreter 'rom the &ommand line 6ith
the P$rP s6it&h, or 6hen using the Rexx SAA A"8, or$ing A>S98C9>2 to the Call9(pe
parameter o' e%%StartFG 'un&tion.
1:.2 'ati*e #anguage !upport
egina pro5ides nati5e language support in the 'ollo6ing 6a(s:
>rror messages &an be displa(ed in a user$sele&table nati5e language.
3o&ale support 'or 6hitespa&e and &hara&ter translations.
1:.2.1 Error )essages
All nati5e language error messages are &ontained in binar( 'iles FX.mtbG that are built 6ith the
egina e%e&utables 'rom sour&e 'iles FX.mtsG.
9he me&hanism Regina uses to determine 6hat nati5e language to use to displa( error messages
depends on the operating s(stem.
On >"OC=2, the language is supplied 6hen installing7 the sele&ted language is &ontained in
de'ault.mtb. On all other plat'orms, egina uses en5ironment 5ariables i' (ou 6ant to use a
language other than >nglish.
9he >nglish language messages are built into the interpreter 'or t6o reasons:
1. to satis'( the A/S8 reKuirement that error messages &an be obtained in >nglish using the
>O9>A9 :81 and spe&i'(ing a 5alue o' PSP 'or argument 2.
248
2. used as a 'allba&- position 6hen no nati5e language support is a5ailable
1:.2.2 #ocale !upport
3o&ale support is 5er( limited in egina &urrentl(. 9here is no A/S8 spe&i'i&ation about it and &are
has been ta-en to a5oid une%pe&ted beha5iour 'or multi$language s&ripts. 9he basi& intention o' the
support 6as the abilit( to handle spe&ial &hara&ters in some 6estern lo&ales or on some s(stems.
/on$brea-able spa&es are part o' nearl( e5er( &hara&ter set, but the( are hard to implement in Rexx
programs be&ause o' the missing in'ormation about the runtime &hara&ter set 6hen 6riting the
program. Another t(pi&al problem &ame 'rom e%tra &hara&ters in the &hara&ter sets 6hi&h allo6 the
translation in some &ases. 9his problem is unsol5able in ad5an&e, be&ause some gl(phs are
&hara&ters in one language and the( are s(mbols in other languages. 9hese problems &an be sol5ed
at runtime onl( 6ith the -no6ledge o' the &ountr( and language.
egina implements some &ode 6hi&h is e%e&uted on&e 6hen the interpreter starts up. 9his &ode
e5aluates the &ommand line parameter or the en5ironment 5ariables and e%tra&ts the in'ormation
about the &hara&ter set. /ote that this operation is not done on a per$thread basis and it is done
be'ore an( other operation happens. So no &hange &an be done on&e a program has been loaded into
memor( and parsed. 9he use o' "AA.SS .-- is re&ommended 'or &ases 6here a di''erent
&hara&ter set is reKuired 'or a &alled program.
A''e&ted operations o' the lo&ale support are:
string &omparison i' options S98C9LA/S8 and S98C9LD!89>S"AC>LCO,"A8SO/ are
not set.
upper$&ase translation o' 5ariable names, see 4A30> :81 or the A"8 'un&tions.
6hite spa&e delimiter dete&tion and elimination at 6ord boundaries or number boundaries at all
possible pla&es in&luding &ases o' reading Rexx programs and pro&essing P".S operations.
$"S;SS translation in P".S operations.
&ase translation o' the builtin 'un&tions 9A/S3A9>, 3OD>, 0""> and the instru&tion
UPP.
2A9A9C"> :81 results.
'ile name &ase translation 6hen sear&hing e%ternal pro&edures or 6hen using the A"8 'or loading
e%ternal libraries.
1:.2.3 <sing 'ati*e #anguage !upport
9o spe&i'( a nati5e language, up to 2 en5ironment 5ariables are used.
>!.+9*?L*9. en5ironment 5ariable is set to an 8SO ?=*, 2 &hara&ter language abbre5iation as
de'ined in the 'ollo6ing table 'or error messages, optionall( 'ollo6ed b( a &omma and the locale.
9he locale is e%plained in Se&tion 17 U>%e&uting Rexx programs Dith eginaV. 9he 5alue gi5en at
the &ommand line b( the parameter ;-l; ta-es pre&eden&e i' it is gi5en at all, e5en i' the empt(
string is used.
249
>!.+9*?L*9. Lang#age Trans$ati1n 7y
de .erman 1loran .rosse$Coosmann
es Spanish "ablo .ar&ia$Abia
no /or6egian 4idar 9(sse
pl "olish :artosH MoHlo6s-i
pt "ortuguese Susana and :rian Carpenter,
Oosie ,edeiros
s5 S6edish Oan$>ri- 3br-a
tr 9ur-ish !alu- "olat
@to get your na#e in this table, contact the #aintainer "ith the language you "ish to support2
8' >!.+9*?L*9. is not set, the de'ault is en. 9he &ase o' the 5alue is irrele5ant7 !9 is the same
as en.
>!.+9*?L*9.?D+> is reKuired i' egina does not -no6 6here the language 'iles 6ill be at
runtime.
An( binar( distribution that in&ludes an installation routine7 ",, deb, Dindo6s /S8S or
>"OC=2, 6ill set the lo&ation o' the .mtb 'iles automati&all(. Similarl( building and installing
egina on 0ni%$li-e plat'orms using con&igure7#ae install &ombination 6ill also set the lo&ation
automati&all(. All other plat'orms 6ill reKuire this en5ironment 5ariable to bet set manuall(.
1:.3 Rexx and Regina binaries" ?h&B
9O2O: stati& librar(, d(nami& librar( and r%'un&addFG.
Cannot use r%'un&addFG in a stati& librar( to load an e%ternal 'un&tion pa&-age as the d(nami&
librar( that is loaded 6ith the e%ternal 'un&tion pa&-age uses the e%%egister1un&tion2ll that the
shared librar( is lin-ed 6ith7 this is the one in libregina.so and it updates the internal table o'
e%ternal 'un&tions in its address spa&e, so the internal table o' e%ternal 'un&tions in libregina.a For
re%% binar(G 6ill not &ontain the pointers.
250
11 (ppendixes
11.1 $efinitions
8n order to ma-e the de'initions more readable, but still ha5e a rigid de'inition o' the terms, some
e%tra &omments ha5e been added to some o' the de'initions. 9hese &omments are en&losed in sKuare
bra&-ets.
*rg#ment is an e$pression supplied to a &unction or subroutine, and it pro5ides data on 6hi&h the
&all &an 6or- on.
*ssignment is a clause in 6hi&h se&ond toen is the eKual sign. I/ote that the statements ;a::b;
and ;7:8; are an Fin5alidG assignment, not an e%pression. 9he t(pe o' the 'irst to-en is irrele5ant7 i'
the se&ond to-en is the eKual sign, then the &lause is assumed to be an assignment.J
7$an;s are &hara&ters 6hi&h glyphs are empt( spa&e, either 5erti&all( or horiHontall(. A blan- is not
a toen Fbut ma( sometimes be embedded in to-ensG, but a&ts as toen separators. I>%a&tl( 6hi&h
&hara&ters are &onsidered blan-s 6ill di''er bet6een operating s(stems and implementations, but the
<spa&e> &hara&ter is al6a(s a blan-. 9he <tab> &hara&ter is also o'ten &onsidered a blan-. Other
&hara&ters &onsidered blan- might be the end$o'$line <eol>G, 5erti&al tab F<5t>G, and 'orm'eed
F<''>G. See spe&i'i& do&umentation 'or ea&h interpreter 'or more in'ormation.J
7#er
3a$$er r1#tine
3haracter is a pie&e o' in'ormation about a mapping 'rom a storage unit Fnormall( a b(teG and a
glyph. O'ten used as ;the meaning o' the gl(ph mapped to a parti&ular storage unit;. I9he gl(ph ;A;
is the same in >:C28C and ASC88, but the &hara&ter ;A; Fi.e. the mapping 'rom gl(ph to storage
unitG di''ers.J
3haracter string is an 'inite, ordered, and possibl( empt( set o' characters.
3$a#se is a non$empt( &olle&tion o' toens in a Rexx s&ript. 9he to-ens ma-ing up a &lause are all
the &onse&uti5e to-ens delimited b( t6o &onse&uti5e clause deli#iters. IClauses are 'urther di5ided
into null clauses, instructions, assign#ents, and co##ands.J
3$a#se de$imiter is a non$empt( seKuen&e o' elements o' a subset o' toens, normall( the line'eed
and the semi&olon. Also the start and end o' a Rexx script are &onsidered &lause delimiters. Also
&olon is a &lause separator, but it is onl( 5alid a'ter a label.
31mmand
31mp1#nd Nariab$e is a variable 6hi&h name has at least one ;.; &hara&ter that isnPt positioned at
the end o' the name.
3#rrent enNir1nment is a parti&ular environ#ent to 6hi&h co##ands is routed i' no e%pli&it
251
en5ironment is spe&i'ied 'or their routing.
3#rrent pr1ced#re $eNe$ is the procedure level in e''e&t at a &ertain point during e%e&ution.
Daem1n
Decima$ digit
DeNice driNer
Digit is a single &hara&ter ha5ing a numeri& 5alue asso&iate 6ith its gl(ph.
!mpty string
!nNir1nment is a inter'a&e to 6hi&h Rexx &an route co##ands and a'ter6ards retrie5e status
in'ormation li-e return values.
!Na$#ati1n is the pro&ess applied to an e$pression in order to deri5e a character string.
!"p1sing is the binding o' a variable in the current procedure level to the 5ariable ha5ing the same
name in the caller routine. 9his binding 6ill be in e''e&t 'or as long as the &urrent pro&edure le5el is
a&ti5e.
!"p1nentia$ 1rm is a 6a( o' 6riting parti&ularl( large or small nu#bers in a 'ashion that ma-es
them more readable. 9he number is di5ided into a mantissa and an e%ponent o' base 10.
!"pressi1n is a non$empt( seKuen&e o' toens, 'or 6hi&h there e%ists s(nta&ti& restri&tions on
6hi&h to-ens &an be members, and the order in 6hi&h the to-ens &an o&&ur. I9(pi&all(, an
e%pression ma( &onsist o' literal strings or s(mbols, &onne&ted b( &on&atenation and operators.J
!"terna$ data Q#e#e see ;sta&-;.
!"terna$ s#br1#tine is a script o' Rexx &ode, 6hi&h is e%e&uted as a response to a subroutine or
&unction &all that is neither internal nor built$in.
@+@O
.$yph is an atomi& element o' te%t, ha5ing a meaning and an appearan&e7 li-e a letter, a digit, a
pun&tuation mar-, et&.
%e" is used as a general abbre5iation 'or term he$adeci#al 6hen used in &ompound 6ords li-e he%
digit and he% string.
%e"adecima$ digit is a digit in the number s(stem ha5ing a base o' 1?. 9he 'irst ten digits are
identi&al 6ith the deci#al digits F0$*G, 6hile 'or the last si% digits, the 'irst si% letters o' the 3atin
alphabet FA$1G are used.
%e"adecima$ string is a character string that &onsists onl( o' the he$adeci#al digits, and 6ith
optional "hitespace to di5ide the he%ade&imal digits into groups. 3eading or trailing 6hitespa&e is
illegal. All groups e%&ept the 'irst must &onsist o' an e5en number o' digits. 8' the 'irst group ha5e
252
an odd number o' digits, an e%tra leading Hero is implied under some &ir&umstan&es.
+nstr#cti1n is a clause that is re&ogniHed b( the 'a&t that the 'irst toen is a spe&ial ey"ord, and
that the &lause is not an assign#ent or label. 8nstru&tions t(pi&all( are 6ell$de'ined Rexx language
&omponents, su&h as loops and 'un&tion &alls.
+nteractiNe trace is a trace mode, 6here the interpreter halts e%e&ution bet6een ea&h clause, and
o''er the user the possibilit( to spe&i'( arbitrar( Rexx state#ents to be e%e&uted be'ore the
e%e&ution &ontinues.
Labe$
L+@O
Line c1ntin#ati1n is the &omma7 P,P &hara&ter. Dhen it is the last to-en on a line, then the end o'
&lause implied b( the end o' line is ignored and the &lause &ontinues on the ne%t line.
Litera$ name is a name 6hi&h 6ill al6a(s be interpreted as a &onstant, i.e. that no 5ariable
substitution 6ill ta-e pla&e.
Litera$ string is a toen in a Rexx script, that basi&all( is surrounded b( Kuotation mar-s, in order
to ma-e a character string &ontaining the same characters as the literal string.
Pey61rd is a element 'rom 'inite set o' s(mbols.
0ain $eNe$
0ain pr1gram
9ame space is a &olle&tion o' named variables. 8n general, the e%pression is used 6hen re'erring to
the set o' 5ariables a5ailable to the progra# at some point during interpretation.
9#$$string is a character string ha5ing the length Hero, i.e. an empt( &hara&ter string. I/ote the
di''eren&e 'rom the unde'ined string.J
Operating system
&arameters
&arsing
&r1ced#re $eNe$
&r1gram is a &olle&tion o' Rexx &ode, 6hi&h ma( be Hero or more scripts, or other repositories o'
Rexx &ode. !o6e5er, a program must &ontain a all the &ode to be e%e&uted.
8#e#e see ;e%ternal data Kueue; or ;sta&-;.
>1#tine is a unit during run$time, 6hi&h is a pro&edural le5el. Certain settings are sa5ed a&ross
routines. One routine Fthe &aller routineG &an be temporaril( suspended 6hile another routine is
253
e%e&uted Fthe &alled routineG. Dith su&h nesting, the &alled routine must be terminated be'ore
e%e&ution o' the &aller routine &an be resumed. /ormall(, the $";; instru&tion or a 'un&tion &all is
used to do this. /ote that the main le5el o' a Rexx s&ript is also a routine.
Script is a single 'ile &ontaining Rexx &ode.
Space separated
Stac;
Statement is a clause ha5ing in general some a&tion, i.e. a &lause other than a null clause.
IAssignments, &ommands and instru&tions are statements.J
Stem c1$$ecti1n
Stem Nariab$e
Strict$y 1rder
S#b;ey61rd is a ey"ord, but the pre'i% ;sub; stresses the 'a&t that a sy#bol is a -e(6ord onl( in
&ertain &onte%ts Ie.g. inside a parti&ular instru&tionJ.
S#br1#tine is a routine 6hi&h has been in5o-ed 'rom another Rexx routine7 i.e. it &an not be the
;main; program o' a Rexx s&ript.
Symb1$
Symb1$ tab$e
Tai$ s#bstit#ti1n
Term
T1;en
T1;en separat1r
(ninitia$iRed
2ariab$e name
2ariab$e symb1$
5hitespace One or se5eral &onse&uti5e blan &hara&ters.
he" $itera$
n1rm: he" string
bin SdigitIstringI$itera$T
254
n1rm: bin string
pac;ed char string
Chara&ter strings is the onl( t(pe o' data a5ailable in Rexx, but to some e%tent there are Psubt(pesP
o' &hara&ter strings7 &hara&ter strings 6hi&h &ontents has &ertain 'ormat. 9hese spe&ial 'ormats is
dis&ussed belo6.
11.2 %ibliograph&
IM8>S>3J
"eter C. Miesel, R%:: ) 'dvanced Techni1ues &or -rogra##ers. ,&.ra6$!ill, 1**=, 8S:/
0$0@$0=<?00$=
ICA33ADACJ
,erill Calla6a(, The 'Re$$ !ooboo. 511$A .irard :l5d. S>, AlbuKuerKue, /, +@10?:
Dhitestone,1**2, 8S:/ 0$*?=2@@=$0$+
I932J
,. 1. Co6lisha6, The R%:: Language) Second %dition. >ngle6ood Cli''s: "renti&e$!all,
1**0, 8S:/ 0$1=$@+0?51$5
I931J
,. 1. Co6lisha6, The R%:: Language ) +irst %dition. >ngle6ood Cli''s: "renti&e$!all,
1*+5, 8S:/ 0$1=$@+0@=5$A
ISC,"OS=J
-roceedings o& the Re$$ Sy#posiu# &or Aevelopers and Users. Stan'ord: Stan'ord 3inear
A&&elerator Center, 1**2
I9!:"8C>J
Stephen .. "ri&e, S'' -ortability, &hapter =@, pp <@@$<*+. 8n .oldberg ans Smith 888
I9!J, 1**2
I9!J
.abriel .oldberg and Smith 888, "hilip !., The R%:: Bandboo. ,&.ra6$!ill, 1**2, 8S:/
0$0@$02=?+2$+
I2A/>CJ
Charles 2ane(, -rogra##ing in R%::. ,&.ra6$!ill, 1**2, 8S:/ 0$0@$015=05$1
I:,AMSJ
:rian ,ar-s, 'dvanced R%:: progra##ing. ,&.ra6$!ill, 1**2
INA,AAJ
Chris Namara and /i&- Sulli5an, Using 'Re$$ on the '#iga. Aba&us, 1**1, 8S:/ 1$55@55$
11<$?
I>AASAAJ
255
D. 2a5id Ashle(, S'' -rocedure Language R%:: Re&erence. 5 9imberline 2r., 9roph(
Club, 9% @?2?2: "edagogi& So't6are, 1**1
I,C.!:28C9J
S(bil ". "ar-er, McGr")Bill Aictionary o& !o#puters. ,&.ra6$!ill, 1*+<, 8S:/ 0$0@$
0<5<15$*
I"O"3A0.>J
". O. "lauger, The Standard ! Library. >ngle6ood Cli''s: "renti&e !all, 1**2, 8S:/ 0$1=$
1=150*$*
IMJ
:rian D. Mernighan and 2ennis ,. it&hie, The ! -rogra##ing Language ) Second
%dition. >ngle6ood Cli''s: "renti&e !all, 1*++, 8S:/ 0$1=$110=?2$+
IA/S8CJ
-rogra##ing languages ) !. , 9e&hni&al eport 8SO#8>C *+**:1**0, 8SO, Case postale
5?, C!$1211 .ene5e 20, S6itHerland, 1**0
IOA:C28C9J
>d6ard 3. .laser and 8. C. "(le and 4alerie 8llings6orth, O$&ord Re&erence Aictionary o&
!o#puting ) Third %dition. O%'ord 0ni5ersit( "ress, 1**0, 8S:/ 0$1*$2+?1=1$A
IA/S8J
-rogra##ing Languages ) R%::. , A/S8 A=.2@<$1**?, 11 Dest <2nd Street, /e6 Cor-,
/e6 Cor- 100=?
256
11.3 ,'< /ree $ocumentation #icense
./0 1ree 2o&umentation 3i&ense
4ersion 1.1, ,ar&h 2000
Cop(right FCG 2000 1ree So't6are 1oundation, 8n&.
5* 9emple "la&e, Suite ==0, :oston, ,A 02111$1=0@ 0SA
>5er(one is permitted to &op( and distribute 5erbatim &opies o' this li&ense do&ument, but &hanging
it is not allo6ed.
B. 8R1AM?(1
9he purpose o' this 3i&ense is to ma-e a manual, te%tboo-, or other 6ritten do&ument ;'ree; in the
sense o' 'reedom: to assure e5er(one the e''e&ti5e 'reedom to &op( and redistribute it, 6ith or
6ithout modi'(ing it, either &ommer&iall( or non&ommer&iall(. Se&ondaril(, this 3i&ense preser5es
'or the author and publisher a 6a( to get &redit 'or their 6or-, 6hile not being &onsidered
responsible 'or modi'i&ations made b( others.
9his 3i&ense is a -ind o' ;&op(le't;, 6hi&h means that deri5ati5e 6or-s o' the do&ument must
themsel5es be 'ree in the same sense. 8t &omplements the ./0 .eneral "ubli& 3i&ense, 6hi&h is a
&op(le't li&ense designed 'or 'ree so't6are.
De ha5e designed this 3i&ense in order to use it 'or manuals 'or 'ree so't6are, be&ause 'ree
so't6are needs 'ree do&umentation: a 'ree program should &ome 6ith manuals pro5iding the same
'reedoms that the so't6are does. :ut this 3i&ense is not limited to so't6are manuals7 it &an be used
'or an( te%tual 6or-, regardless o' sub\e&t matter or 6hether it is published as a printed boo-. De
re&ommend this 3i&ense prin&ipall( 'or 6or-s 6hose purpose is instru&tion or re'eren&e.
C. A88(!CA?!(!67 AN= =1F!N!6!@N
9his 3i&ense applies to an( manual or other 6or- that &ontains a noti&e pla&ed b( the &op(right
holder sa(ing it &an be distributed under the terms o' this 3i&ense. 9he ;2o&ument;, belo6, re'ers
to an( su&h manual or 6or-. An( member o' the publi& is a li&ensee, and is addressed as ;(ou;.
A ;,odi'ied 4ersion; o' the 2o&ument means an( 6or- &ontaining the 2o&ument or a portion o' it,
either &opied 5erbatim, or 6ith modi'i&ations and#or translated into another language.
A ;Se&ondar( Se&tion; is a named appendi% or a 'ront$matter se&tion o' the 2o&ument that deals
e%&lusi5el( 6ith the relationship o' the publishers or authors o' the 2o&ument to the 2o&umentPs
o5erall sub\e&t For to related mattersG and &ontains nothing that &ould 'all dire&tl( 6ithin that o5erall
sub\e&t. F1or e%ample, i' the 2o&ument is in part a te%tboo- o' mathemati&s, a Se&ondar( Se&tion
ma( not e%plain an( mathemati&s.G 9he relationship &ould be a matter o' histori&al &onne&tion 6ith
the sub\e&t or 6ith related matters, or o' legal, &ommer&ial, philosophi&al, ethi&al or politi&al
position regarding them.
9he ;8n5ariant Se&tions; are &ertain Se&ondar( Se&tions 6hose titles are designated, as being those
o' 8n5ariant Se&tions, in the noti&e that sa(s that the 2o&ument is released under this 3i&ense.
257
9he ;Co5er 9e%ts; are &ertain short passages o' te%t that are listed, as 1ront$Co5er 9e%ts or :a&-$
Co5er 9e%ts, in the noti&e that sa(s that the 2o&ument is released under this 3i&ense.
A ;9ransparent; &op( o' the 2o&ument means a ma&hine$readable &op(, represented in a 'ormat
6hose spe&i'i&ation is a5ailable to the general publi&, 6hose &ontents &an be 5ie6ed and edited
dire&tl( and straight'or6ardl( 6ith generi& te%t editors or F'or images &omposed o' pi%elsG generi&
paint programs or F'or dra6ingsG some 6idel( a5ailable dra6ing editor, and that is suitable 'or input
to te%t 'ormatters or 'or automati& translation to a 5ariet( o' 'ormats suitable 'or input to te%t
'ormatters. A &op( made in an other6ise 9ransparent 'ile 'ormat 6hose mar-up has been designed
to th6art or dis&ourage subseKuent modi'i&ation b( readers is not 9ransparent. A &op( that is not
;9ransparent; is &alled ;OpaKue;.
>%amples o' suitable 'ormats 'or 9ransparent &opies in&lude plain ASC88 6ithout mar-up, 9e%in'o
input 'ormat, 3a9eA input 'ormat, S.,3 or A,3 using a publi&l( a5ailable 292, and standard$
&on'orming simple !9,3 designed 'or human modi'i&ation. OpaKue 'ormats in&lude "ostS&ript,
"21, proprietar( 'ormats that &an be read and edited onl( b( proprietar( 6ord pro&essors, S.,3 or
A,3 'or 6hi&h the 292 and#or pro&essing tools are not generall( a5ailable, and the ma&hine$
generated !9,3 produ&ed b( some 6ord pro&essors 'or output purposes onl(.
9he ;9itle "age; means, 'or a printed boo-, the title page itsel', plus su&h 'ollo6ing pages as are
needed to hold, legibl(, the material this 3i&ense reKuires to appear in the title page. 1or 6or-s in
'ormats 6hi&h do not ha5e an( title page as su&h, ;9itle "age; means the te%t near the most
prominent appearan&e o' the 6or-Ps title, pre&eding the beginning o' the bod( o' the te%t.
F. D1R?A6!M C@87!NG
Cou ma( &op( and distribute the 2o&ument in an( medium, either &ommer&iall( or
non&ommer&iall(, pro5ided that this 3i&ense, the &op(right noti&es, and the li&ense noti&e sa(ing
this 3i&ense applies to the 2o&ument are reprodu&ed in all &opies, and that (ou add no other
&onditions 6hatsoe5er to those o' this 3i&ense. Cou ma( not use te&hni&al measures to obstru&t or
&ontrol the reading or 'urther &op(ing o' the &opies (ou ma-e or distribute. !o6e5er, (ou ma(
a&&ept &ompensation in e%&hange 'or &opies. 8' (ou distribute a large enough number o' &opies (ou
must also 'ollo6 the &onditions in se&tion =.
Cou ma( also lend &opies, under the same &onditions stated abo5e, and (ou ma( publi&l( displa(
&opies.
J. C@87!NG !N /0AN6!67
8' (ou publish printed &opies o' the 2o&ument numbering more than 100, and the 2o&umentPs
li&ense noti&e reKuires Co5er 9e%ts, (ou must en&lose the &opies in &o5ers that &arr(, &learl( and
legibl(, all these Co5er 9e%ts: 1ront$Co5er 9e%ts on the 'ront &o5er, and :a&-$Co5er 9e%ts on the
ba&- &o5er. :oth &o5ers must also &learl( and legibl( identi'( (ou as the publisher o' these &opies.
9he 'ront &o5er must present the 'ull title 6ith all 6ords o' the title eKuall( prominent and 5isible.
Cou ma( add other material on the &o5ers in addition.
Cop(ing 6ith &hanges limited to the &o5ers, as long as the( preser5e the title o' the 2o&ument and
satis'( these &onditions, &an be treated as 5erbatim &op(ing in other respe&ts.
8' the reKuired te%ts 'or either &o5er are too 5oluminous to 'it legibl(, (ou should put the 'irst ones
listed Fas man( as 'it reasonabl(G on the a&tual &o5er, and &ontinue the rest onto ad\a&ent pages.
8' (ou publish or distribute OpaKue &opies o' the 2o&ument numbering more than 100, (ou must
either in&lude a ma&hine$readable 9ransparent &op( along 6ith ea&h OpaKue &op(, or state in or
258
6ith ea&h OpaKue &op( a publi&l($a&&essible &omputer$net6or- lo&ation &ontaining a &omplete
9ransparent &op( o' the 2o&ument, 'ree o' added material, 6hi&h the general net6or-$using publi&
has a&&ess to do6nload anon(mousl( at no &harge using publi&$standard net6or- proto&ols. 8' (ou
use the latter option, (ou must ta-e reasonabl( prudent steps, 6hen (ou begin distribution o'
OpaKue &opies in Kuantit(, to ensure that this 9ransparent &op( 6ill remain thus a&&essible at the
stated lo&ation until at least one (ear a'ter the last time (ou distribute an OpaKue &op( Fdire&tl( or
through (our agents or retailersG o' that edition to the publi&.
8t is reKuested, but not reKuired, that (ou &onta&t the authors o' the 2o&ument 6ell be'ore
redistributing an( large number o' &opies, to gi5e them a &han&e to pro5ide (ou 6ith an updated
5ersion o' the 2o&ument.
E. M@=!F!CA6!@N
Cou ma( &op( and distribute a ,odi'ied 4ersion o' the 2o&ument under the &onditions o' se&tions 2
and = abo5e, pro5ided that (ou release the ,odi'ied 4ersion under pre&isel( this 3i&ense, 6ith the
,odi'ied 4ersion 'illing the role o' the 2o&ument, thus li&ensing distribution and modi'i&ation o'
the ,odi'ied 4ersion to 6hoe5er possesses a &op( o' it. 8n addition, (ou must do these things in the
,odi'ied 4ersion:
A. 0se in the 9itle "age Fand on the &o5ers, i' an(G a title distin&t 'rom that o' the 2o&ument, and
'rom those o' pre5ious 5ersions F6hi&h should, i' there 6ere an(, be listed in the !istor( se&tion o'
the 2o&umentG. Cou ma( use the same title as a pre5ious 5ersion i' the original publisher o' that
5ersion gi5es permission.
:. 3ist on the 9itle "age, as authors, one or more persons or entities responsible 'or authorship o'
the modi'i&ations in the ,odi'ied 4ersion, together 6ith at least 'i5e o' the prin&ipal authors o' the
2o&ument Fall o' its prin&ipal authors, i' it has less than 'i5eG.
C. State on the 9itle page the name o' the publisher o' the ,odi'ied 4ersion, as the publisher.
2. "reser5e all the &op(right noti&es o' the 2o&ument.
>. Add an appropriate &op(right noti&e 'or (our modi'i&ations ad\a&ent to the other &op(right
noti&es.
1. 8n&lude, immediatel( a'ter the &op(right noti&es, a li&ense noti&e gi5ing the publi& permission to
use the ,odi'ied 4ersion under the terms o' this 3i&ense, in the 'orm sho6n in the Addendum
belo6.
.. "reser5e in that li&ense noti&e the 'ull lists o' 8n5ariant Se&tions and reKuired Co5er 9e%ts gi5en
in the 2o&umentPs li&ense noti&e.
!. 8n&lude an unaltered &op( o' this 3i&ense.
8. "reser5e the se&tion entitled ;!istor(;, and its title, and add to it an item stating at least the title,
(ear, ne6 authors, and publisher o' the ,odi'ied 4ersion as gi5en on the 9itle "age. 8' there is no
se&tion entitled ;!istor(; in the 2o&ument, &reate one stating the title, (ear, authors, and publisher
o' the 2o&ument as gi5en on its 9itle "age, then add an item des&ribing the ,odi'ied 4ersion as
stated in the pre5ious senten&e.
O. "reser5e the net6or- lo&ation, i' an(, gi5en in the 2o&ument 'or publi& a&&ess to a 9ransparent
&op( o' the 2o&ument, and li-e6ise the net6or- lo&ations gi5en in the 2o&ument 'or pre5ious
5ersions it 6as based on. 9hese ma( be pla&ed in the ;!istor(; se&tion. Cou ma( omit a net6or-
lo&ation 'or a 6or- that 6as published at least 'our (ears be'ore the 2o&ument itsel', or i' the
original publisher o' the 5ersion it re'ers to gi5es permission.
259
M. 8n an( se&tion entitled ;A&-no6ledgements; or ;2edi&ations;, preser5e the se&tionPs title, and
preser5e in the se&tion all the substan&e and tone o' ea&h o' the &ontributor a&-no6ledgements
and#or dedi&ations gi5en therein.
3. "reser5e all the 8n5ariant Se&tions o' the 2o&ument, unaltered in their te%t and in their titles.
Se&tion numbers or the eKui5alent are not &onsidered part o' the se&tion titles.
,. 2elete an( se&tion entitled ;>ndorsements;. Su&h a se&tion ma( not be in&luded in the ,odi'ied
4ersion.
/. 2o not retitle an( e%isting se&tion as ;>ndorsements; or to &on'li&t in title 6ith an( 8n5ariant
Se&tion.
8' the ,odi'ied 4ersion in&ludes ne6 'ront$matter se&tions or appendi&es that Kuali'( as Se&ondar(
Se&tions and &ontain no material &opied 'rom the 2o&ument, (ou ma( at (our option designate
some or all o' these se&tions as in5ariant. 9o do this, add their titles to the list o' 8n5ariant Se&tions
in the ,odi'ied 4ersionPs li&ense noti&e.
9hese titles must be distin&t 'rom an( other se&tion titles.
Cou ma( add a se&tion entitled ;>ndorsements;, pro5ided it &ontains nothing but endorsements o'
(our ,odi'ied 4ersion b( 5arious parties$$'or e%ample, statements o' peer re5ie6 or that the te%t
has been appro5ed b( an organiHation as the authoritati5e de'inition o' a standard.
Cou ma( add a passage o' up to 'i5e 6ords as a 1ront$Co5er 9e%t, and a passage o' up to 25 6ords
as a :a&-$Co5er 9e%t, to the end o' the list o' Co5er 9e%ts in the ,odi'ied 4ersion. Onl( one
passage o' 1ront$Co5er 9e%t and one o' :a&-$Co5er 9e%t ma( be added b( For through
arrangements made b(G an( one entit(. 8' the 2o&ument alread( in&ludes a &o5er te%t 'or the same
&o5er, pre5iousl( added b( (ou or b( arrangement made b( the same entit( (ou are a&ting on behal'
o', (ou ma( not add another7 but (ou ma( repla&e the old one, on e%pli&it permission 'rom the
pre5ious publisher that added the old one.
9he authorFsG and publisherFsG o' the 2o&ument do not b( this 3i&ense gi5e permission to use their
names 'or publi&it( 'or or to assert or impl( endorsement o' an( ,odi'ied 4ersion.
K. C@M?!N!NG =@C0M1N6
Cou ma( &ombine the 2o&ument 6ith other do&uments released under this 3i&ense, under the terms
de'ined in se&tion < abo5e 'or modi'ied 5ersions, pro5ided that (ou in&lude in the &ombination all
o' the 8n5ariant Se&tions o' all o' the original do&uments, unmodi'ied, and list them all as 8n5ariant
Se&tions o' (our &ombined 6or- in its li&ense noti&e.
9he &ombined 6or- need onl( &ontain one &op( o' this 3i&ense, and multiple identi&al 8n5ariant
Se&tions ma( be repla&ed 6ith a single &op(. 8' there are multiple 8n5ariant Se&tions 6ith the same
name but di''erent &ontents, ma-e the title o' ea&h su&h se&tion uniKue b( adding at the end o' it, in
parentheses, the name o' the original author or publisher o' that se&tion i' -no6n, or else a uniKue
number.
,a-e the same ad\ustment to the se&tion titles in the list o' 8n5ariant Se&tions in the li&ense noti&e
o' the &ombined 6or-.
8n the &ombination, (ou must &ombine an( se&tions entitled ;!istor(; in the 5arious original
do&uments, 'orming one se&tion entitled ;!istor(;7 li-e6ise &ombine an( se&tions entitled
;A&-no6ledgements;, and an( se&tions entitled ;2edi&ations;. Cou must delete all se&tions entitled
;>ndorsements.;
260
L. C@((1C6!@N @F =@C0M1N6
Cou ma( ma-e a &olle&tion &onsisting o' the 2o&ument and other do&uments released under this
3i&ense, and repla&e the indi5idual &opies o' this 3i&ense in the 5arious do&uments 6ith a single
&op( that is in&luded in the &olle&tion, pro5ided that (ou 'ollo6 the rules o' this 3i&ense 'or
5erbatim &op(ing o' ea&h o' the do&uments in all other respe&ts.
Cou ma( e%tra&t a single do&ument 'rom su&h a &olle&tion, and distribute it indi5iduall( under this
3i&ense, pro5ided (ou insert a &op( o' this 3i&ense into the e%tra&ted do&ument, and 'ollo6 this
3i&ense in all other respe&ts regarding 5erbatim &op(ing o' that do&ument.
M. AGGR1GA6!@N A!6H !N=181N=1N6 A@R:
A &ompilation o' the 2o&ument or its deri5ati5es 6ith other separate and independent do&uments or
6or-s, in or on a 5olume o' a storage or distribution medium, does not as a 6hole &ount as a
,odi'ied 4ersion o' the 2o&ument, pro5ided no &ompilation &op(right is &laimed 'or the
&ompilation. Su&h a &ompilation is &alled an ;aggregate;, and this 3i&ense does not appl( to the
other sel'$&ontained 6or-s thus &ompiled 6ith the 2o&ument, on a&&ount o' their being thus
&ompiled, i' the( are not themsel5es deri5ati5e 6or-s o' the 2o&ument.
8' the Co5er 9e%t reKuirement o' se&tion = is appli&able to these &opies o' the 2o&ument, then i' the
2o&ument is less than one Kuarter o' the entire aggregate, the 2o&umentPs Co5er 9e%ts ma( be
pla&ed on &o5ers that surround onl( the 2o&ument 6ithin the aggregate.
Other6ise the( must appear on &o5ers around the 6hole aggregate.
N. 6RAN(A6!@N
9ranslation is &onsidered a -ind o' modi'i&ation, so (ou ma( distribute translations o' the 2o&ument
under the terms o' se&tion <.
epla&ing 8n5ariant Se&tions 6ith translations reKuires spe&ial permission 'rom their &op(right
holders, but (ou ma( in&lude translations o' some or all 8n5ariant Se&tions in addition to the
original 5ersions o' these 8n5ariant Se&tions. Cou ma( in&lude a translation o' this 3i&ense
pro5ided that (ou also in&lude the original >nglish 5ersion o' this 3i&ense. 8n &ase o' a
disagreement bet6een the translation and the original >nglish 5ersion o' this 3i&ense, the original
>nglish 5ersion 6ill pre5ail.
O. 61RM!NA6!@N
Cou ma( not &op(, modi'(, subli&ense, or distribute the 2o&ument e%&ept as e%pressl( pro5ided 'or
under this 3i&ense. An( other attempt to &op(, modi'(, subli&ense or distribute the 2o&ument is
5oid, and 6ill automati&all( terminate (our rights under this 3i&ense. !o6e5er, parties 6ho ha5e
re&ei5ed &opies, or rights, 'rom (ou under this 3i&ense 6ill not ha5e their li&enses terminated so
long as su&h parties remain in 'ull &omplian&e.
CB. F060R1 R1D!!@N @F 6H! (!C1N1
9he 1ree So't6are 1oundation ma( publish ne6, re5ised 5ersions o' the ./0 1ree 2o&umentation
3i&ense 'rom time to time. Su&h ne6 5ersions 6ill be similar in spirit to the present 5ersion, but
ma( di''er in detail to address ne6 problems or &on&erns. See http:##666.gnu.org#&op(le't#.
>a&h 5ersion o' the 3i&ense is gi5en a distinguishing 5ersion number. 8' the 2o&ument spe&i'ies that
a parti&ular numbered 5ersion o' this 3i&ense ;or an( later 5ersion; applies to it, (ou ha5e the
261
option o' 'ollo6ing the terms and &onditions either o' that spe&i'ied 5ersion or o' an( later 5ersion
that has been published Fnot as a dra'tG b( the 1ree So't6are 1oundation. 8' the 2o&ument does not
spe&i'( a 5ersion number o' this 3i&ense, (ou ma( &hoose an( 5ersion e5er published Fnot as a
dra'tG b( the 1ree So't6are 1oundation.
A==1N=0M% Ho+ #o 'se #"is (icense for ;o'r doc'men#s
9o use this 3i&ense in a do&ument (ou ha5e 6ritten, in&lude a &op( o' the 3i&ense in the do&ument
and put the 'ollo6ing &op(right and li&ense noti&es \ust a'ter the title page:
Cop(right F&G C>A CO0 /A,>.
"ermission is granted to &op(, distribute and#or modi'( this do&ument under the terms o' the
./0 1ree 2o&umentation 3i&ense, 4ersion 1.1 or an( later 5ersion published b( the 1ree So't6are
1oundation7 6ith the 8n5ariant Se&tions being 38S9 9!>8 9893>S, 6ith the 1ront$Co5er 9e%ts
being 38S9, and 6ith the :a&-$Co5er 9e%ts being 38S9.
A &op( o' the li&ense is in&luded in the se&tion entitled ;./0 1ree 2o&umentation 3i&ense;.
8' (ou ha5e no 8n5ariant Se&tions, 6rite ;6ith no 8n5ariant Se&tions; instead o' sa(ing 6hi&h ones
are in5ariant. 8' (ou ha5e no 1ront$Co5er 9e%ts, 6rite ;no 1ront$Co5er 9e%ts; instead o' ;1ront$
Co5er 9e%ts being 38S9;7 li-e6ise 'or :a&-$Co5er 9e%ts.
8' (our do&ument &ontains nontri5ial e%amples o' program &ode, 6e re&ommend releasing these
e%amples in parallel under (our &hoi&e o' 'ree so't6are li&ense, su&h as the ./0 .eneral "ubli&
3i&ense, to permit their use in 'ree so't6are.
262

Regina REXX v3.7 - User Manual

Загружено:

Сведения о документе

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Regina REXX v3.7 - User Manual

Загружено:

Авторское право:

Доступные форматы

The Regina Rexx Interpreter

Вам также может понравиться