[r9634]: docs / trunk / rexxref / en-US / instrc.xml Maximize Restore History

Download this file

instrc.xml    3891 lines (3726 with data), 174.2 kB

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191
3192
3193
3194
3195
3196
3197
3198
3199
3200
3201
3202
3203
3204
3205
3206
3207
3208
3209
3210
3211
3212
3213
3214
3215
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247
3248
3249
3250
3251
3252
3253
3254
3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
3276
3277
3278
3279
3280
3281
3282
3283
3284
3285
3286
3287
3288
3289
3290
3291
3292
3293
3294
3295
3296
3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
3311
3312
3313
3314
3315
3316
3317
3318
3319
3320
3321
3322
3323
3324
3325
3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
3340
3341
3342
3343
3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
3383
3384
3385
3386
3387
3388
3389
3390
3391
3392
3393
3394
3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
3413
3414
3415
3416
3417
3418
3419
3420
3421
3422
3423
3424
3425
3426
3427
3428
3429
3430
3431
3432
3433
3434
3435
3436
3437
3438
3439
3440
3441
3442
3443
3444
3445
3446
3447
3448
3449
3450
3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
3601
3602
3603
3604
3605
3606
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
3632
3633
3634
3635
3636
3637
3638
3639
3640
3641
3642
3643
3644
3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
3667
3668
3669
3670
3671
3672
3673
3674
3675
3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
3697
3698
3699
3700
3701
3702
3703
3704
3705
3706
3707
3708
3709
3710
3711
3712
3713
3714
3715
3716
3717
3718
3719
3720
3721
3722
3723
3724
3725
3726
3727
3728
3729
3730
3731
3732
3733
3734
3735
3736
3737
3738
3739
3740
3741
3742
3743
3744
3745
3746
3747
3748
3749
3750
3751
3752
3753
3754
3755
3756
3757
3758
3759
3760
3761
3762
3763
3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
3803
3804
3805
3806
3807
3808
3809
3810
3811
3812
3813
3814
3815
3816
3817
3818
3819
3820
3821
3822
3823
3824
3825
3826
3827
3828
3829
3830
3831
3832
3833
3834
3835
3836
3837
3838
3839
3840
3841
3842
3843
3844
3845
3846
3847
3848
3849
3850
3851
3852
3853
3854
3855
3856
3857
3858
3859
3860
3861
3862
3863
3864
3865
3866
3867
3868
3869
3870
3871
3872
3873
3874
3875
3876
3877
3878
3879
3880
3881
3882
3883
3884
3885
3886
3887
3888
3889
3890
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "rexxref.ent">
%BOOK_ENTITIES;
]>
<!--#########################################################################
#
# Description: Open Object Rexx: Reference XML File
#
# Copyright (c) 2005-2012, Rexx Language Association. All rights reserved.
# Portions Copyright (c) 2004, IBM Corporation. All rights reserved.
#
# This program and the accompanying materials are made available under
# the terms of the Common Public License v1.0 which accompanies this
# distribution. A copy is also available at the following address:
# http://www.oorexx.org/license.html
#
# Redistribution and use in source and binary forms, with or
# without modification, are permitted provided that the following
# conditions are met:
#
# Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
# Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in
# the documentation and/or other materials provided with the distribution.
#
# Neither the name of Rexx Language Association nor the names
# of its contributors may be used to endorse or promote products
# derived from this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
# TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
# OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
# OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
#########################################################################
-->
<chapter id="instrc"><title>Keyword Instructions</title>
<indexterm><primary>keyword</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>general concepts</primary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>keyword</secondary>
<tertiary>description</tertiary></indexterm>
<para>A <emphasis>keyword instruction</emphasis> is one or more clauses, the
first of which starts with a keyword that identifies the instruction. Some
keyword instructions affect the flow of control, while others provide services
to the programmer. Some keyword instructions, like DO, can include nested
instructions.</para>
<para>In the syntax diagrams on the following pages, symbols (words) in capitals
denote keywords or subkeywords. Other words, such as
<emphasis role="italic">expression</emphasis>,
denote a collection of tokens as defined previously. Note, however, that the
<indexterm><primary>keyword</primary>
<secondary>mixed case</secondary></indexterm>
keywords and subkeywords are not case-dependent. The symbols
<computeroutput>if</computeroutput>, <computeroutput>If</computeroutput>,
and <computeroutput>iF</computeroutput> all have the same effect.
Note also that you can usually omit most of the clause delimiters
<indexterm><primary>semicolons</primary>
<secondary>omission of</secondary></indexterm>
(<computeroutput>;</computeroutput>) shown because the
end of a line implies them.</para>
<indexterm><primary>ELSE</primary>
<secondary>as free standing clause</secondary></indexterm>
<indexterm><primary>END</primary>
<secondary>as free standing clause</secondary></indexterm>
<indexterm><primary>OTHERWISE</primary>
<secondary>as free standing clause</secondary></indexterm>
<indexterm><primary>THEN</primary>
<secondary>as free standing clause</secondary></indexterm>
<indexterm><primary>WHEN</primary>
<secondary>as free standing clause</secondary></indexterm>
<para>A keyword instruction is recognized <emphasis>only</emphasis> if its
keyword is the first token in a clause and if the second token does not start
with an equal (=) character (implying an assignment) or a colon (implying
a label). The keywords ELSE, END, OTHERWISE, THEN, and WHEN are treated in
the same way. Note that any clause that starts with a keyword defined by Rexx
cannot be a command. Therefore, </para>
<programlisting>
arg(fred) rest
</programlisting>
<para>is an ARG keyword
instruction, not a command that starts with a call to the ARG built-in function.
A syntax error results if the keywords are not in their correct positions
in a DO, IF, or SELECT instruction. The keyword THEN is also recognized in
the body of an IF or WHEN clause. In other contexts, keywords are not reserved
and can be used as labels or as the names of variables (though this is generally
not recommended).</para>
<para><emphasis>Subkeywords</emphasis> are reserved within the clauses of
individual instructions. For example, the symbols VALUE and WITH are subkeywords
in the ADDRESS and PARSE instructions, respectively. For details, see the
description of each instruction.</para>
<para>Whitespace characters (blanks or horizontal tabs) adjacent to keywords
separate the keyword from the subsequent token. One or more whitespace
characters following VALUE are required to separate the
<emphasis role="italic">expression
</emphasis> from the subkeyword in the example following: </para>
<programlisting> ADDRESS VALUE expression
</programlisting>
<para>However, no whitespace character is required after the VALUE subkeyword in
the following example, although it would improve readability:
</para>
<programlisting>
ADDRESS VALUE"ENVIR"||number
</programlisting>
<section id="keyAddress"><title>ADDRESS</title>
<indexterm><primary>ADDRESS instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>command</primary>
<secondary>destination of</secondary></indexterm>
<indexterm><primary>ADDRESS instruction</primary>
<secondary>issuing commands to</secondary></indexterm>
<indexterm><primary>changing destination of commands</primary></indexterm>
<indexterm><primary>name, definition</primary></indexterm>
<indexterm><primary>environment</primary></indexterm>
<indexterm><primary>temporary change of</primary></indexterm>
<indexterm><primary>permanent command destination change</primary></indexterm>
<indexterm><primary>presumed command destinations</primary></indexterm>
<indexterm><primary>temporary command destination change</primary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>ADDRESS</secondary></indexterm>
<indexterm><primary>VALUE subkeyword</primary>
<secondary>in an ADDRESS instruction</secondary></indexterm>
<programlisting>
<![CDATA[
>>-ADDRESS--+-----------------------------+--;-----------------><
+-environment--+------------+-+
| +-expression-+ |
+-+-------+--expression1------+
+-VALUE-+
]]>
</programlisting>
<para>ADDRESS temporarily or permanently changes the destination of commands.
Commands are strings sent to an external environment. You can send commands
by specifying clauses consisting of only an expression or by using the ADDRESS
instruction. (See
<xref linkend="cmdhost" />.)</para>
<para>To send a single command to a specified environment, code an
<emphasis role="italic">environment</emphasis>,
<indexterm><primary>environment</primary>
<secondary>addressing of</secondary></indexterm>
a literal string or a single symbol, which is taken to be a constant,
followed by an <emphasis role="italic">expression</emphasis>.
The environment name is the name of an external procedure
or process that can process commands. The
<emphasis role="italic">expression</emphasis> is evaluated
to produce a character string value, and this string is routed to the
<emphasis role="italic">environment</emphasis>
to be processed as a command.
After execution
of the command, <emphasis role="italic">environment</emphasis>
is set back to its original state, thus
temporarily changing the destination for a single command. The special variable
RC and the environment symbol .RS are set and errors and failures in commands
processed in this way are trapped or traced.</para>
<indexterm><primary>ADDRESS instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>ADDRESS instruction</secondary></indexterm>
<indexterm><primary>CMD command environment</primary></indexterm>
<example>
<title>Instructions - ADDRESS (Windows)</title>
<programlisting>
ADDRESS CMD "DIR C:\CONFIG.SYS"
</programlisting>
</example>
<example>
<title>Instructions - ADDRESS (Linux)</title>
<indexterm><primary>bash command environment</primary></indexterm>
<programlisting>
ADDRESS "bash" "ls /usr/lib"
</programlisting>
</example>
<para>If you specify only <emphasis role="italic">environment</emphasis>, a
lasting change of destination occurs: all commands (see
<xref linkend="commnds" />) that follow are routed to
the specified command environment, until the next ADDRESS instruction is
processed. The previously selected environment is saved.</para>
<para>Assume that the environment for a Windows text editor is
registered by the name <computeroutput>EDIT</computeroutput>:</para>
<example>
<title>Instructions - ADDRESS environments</title>
<programlisting>
address CMD
"DIR C:\AUTOEXEC.BAT"
if rc=0 then "COPY C:\AUTOEXEC.BAT C:\*.TMP"
address EDIT
</programlisting>
</example>
<para>Subsequent commands are passed to the editor until the next ADDRESS
instruction.</para>
<para>Similarly, you can use the VALUE form to make a lasting change to the
environment. Here <emphasis role="italic">expression1</emphasis>, which can be a
variable name, is evaluated, and
the resulting character string value forms the name of the environment. You
can omit the subkeyword VALUE if <emphasis role="italic">expression1</emphasis>
does not begin with
a literal string or symbol, that is, if it starts with a special character
such as an operator character or parenthesis.</para>
<example>
<title>Instructions - ADDRESS environments</title>
<programlisting>
ADDRESS ("ENVIR"||number) /* Same as ADDRESS VALUE "ENVIR"||number */
</programlisting>
</example>
<para>With no arguments, commands are routed back to the environment that was
selected before the previous change of the environment, and the current environment
name is saved. After changing the environment, repeated execution of ADDRESS
alone, therefore, switches the command destination between two environments.
Using a null string for the environment name (&quot;&quot;) is the same as using
the default environment.</para>
<para>The two environment names are automatically saved across internal and external
subroutine and function calls. See the CALL instruction
(<xref linkend="keyCall" />) for more details.</para>
<para>The address setting is the currently
<indexterm><primary>address setting</primary></indexterm>
<indexterm><primary>environment</primary>
<secondary>default</secondary></indexterm>
selected environment name. You can retrieve the current address setting by
using the ADDRESS built-in function. (See
<xref linkend="bifAddress" />.) The
<citetitle pubwork="book">Open Object Rexx: Programming Guide</citetitle>
describes the creation of alternative subcommand environments.</para>
</section>
<section id="keyArg"><title>ARG</title>
<indexterm><primary>ARG instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>arguments</primary>
<secondary>retrieving with ARG instruction</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>ARG</secondary></indexterm>
<indexterm><primary>parsing</primary>
<secondary>templates</secondary>
<tertiary>in ARG instruction</tertiary></indexterm>
<indexterm><primary>programs</primary>
<secondary>arguments to</secondary></indexterm>
<indexterm><primary>retrieving</primary>
<secondary>argument strings with ARG</secondary></indexterm>
<indexterm><primary>template</primary>
<secondary>list</secondary>
<tertiary>ARG instruction</tertiary></indexterm>
<indexterm><primary>UPPER subkeyword</primary>
<secondary>in a PARSE instruction</secondary></indexterm>
<indexterm><primary>ARG subkeyword</primary>
<secondary>in a PARSE instruction</secondary></indexterm>
<programlisting>
<![CDATA[
>>-ARG--+---------------+--;-----------------------------------><
+-template_list-+
]]>
</programlisting>
<indexterm><primary>arguments</primary>
<secondary>of functions</secondary></indexterm>
<indexterm><primary>arguments</primary>
<secondary>of programs</secondary></indexterm>
<indexterm><primary>arguments</primary>
<secondary>of subroutines</secondary></indexterm>
<indexterm><primary>uppercase translation</primary>
<secondary>during ARG instruction</secondary></indexterm>
<para>ARG retrieves the argument strings provided to a program, internal
routine, or method and assigns them to variables. It is a short form of the
instruction:</para>
<para></para>
<programlisting>
<![CDATA[
>>-PARSE UPPER ARG--+---------------+--;-----------------------><
+-template_list-+
]]>
</programlisting>
<para>The <emphasis role="italic">template_list</emphasis> can be a single
template or list of templates separated by commas.
Each template consists of one or more symbols separated by whitespace
characters, patterns, or both.
</para>
<para>The objects passed to the program, routine, or method
are converted to string values
and parsed into variables according to the rules described in
<xref linkend="parsingch" />.</para>
<para>The language processor converts the objects to strings and translates the
strings to uppercase (that is, lowercase
<computeroutput>a</computeroutput>-<computeroutput>z</computeroutput> to
uppercase <computeroutput>A</computeroutput>-<computeroutput>Z</computeroutput>)
before processing them. Use the
PARSE ARG instruction if you do not want uppercase translation.</para>
<para>You can use the ARG and PARSE ARG instructions repeatedly on the same source
objects (typically with different templates). The source objects do not change.
</para>
<indexterm><primary>ARG instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>ARG instruction</secondary></indexterm>
<example>
<title>Instructions - ARG</title>
<programlisting>
/* String passed is "Easy Rider" */
Arg adjective noun .
/* Now: ADJECTIVE contains "EASY" */
/* NOUN contains "RIDER" */
</programlisting>
</example>
<para>If you expect more than one object to be available to the program or
routine, you can use a comma
<indexterm><primary>, (comma)</primary>
<secondary>in parsing template list</secondary></indexterm>
<indexterm><primary>comma</primary>
<secondary>in parsing template list</secondary></indexterm>
in the parsing <emphasis role="italic">template_list</emphasis> so each template
is selected in turn.</para>
<example>
<title>Instructions - ARG</title>
<programlisting>
/* Function is called by FRED("data X",1,5) */
Fred: Arg string, num1, num2
/* Now: STRING contains "DATA X" */
/* NUM1 contains "1" */
/* NUM2 contains "5" */
</programlisting>
</example>
<para><emphasis role="bold">Notes:</emphasis></para>
<orderedlist>
<listitem><para>The ARG built-in function can also retrieve or check the
arguments. See <xref linkend="bifArg" />.</para></listitem>
<listitem><para>The USE ARG instruction (see
<xref linkend="keyUse" />) is an alternative way
of retrieving arguments. USE ARG performs a direct, one-to-one assignment
of argument objects to Rexx variables. You should use this when your program
needs a direct reference to the argument object, without string conversion
or parsing.
ARG and PARSE ARG produce string values from the argument objects, and the
language processor then parses the string values.</para></listitem>
</orderedlist>
</section>
<section id="keyCall"><title>CALL</title>
<indexterm><primary>CALL instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>flow of control</primary>
<secondary>with CALL and RETURN construct</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>CALL</secondary></indexterm>
<indexterm><primary>internal</primary>
<secondary>routine</secondary></indexterm>
<indexterm><primary>label</primary>
<secondary>as target of CALL</secondary></indexterm>
<indexterm><primary>invoking</primary>
<secondary>built-in functions</secondary></indexterm>
<indexterm><primary>invoking</primary>
<secondary>routines</secondary></indexterm>
<indexterm><primary>names</primary>
<secondary>of subroutines</secondary></indexterm>
<indexterm><primary>string</primary>
<secondary>as name of subroutine</secondary></indexterm>
<indexterm><primary>subroutines</primary>
<secondary>calling of</secondary></indexterm>
<indexterm><primary>subroutines</primary>
<secondary>naming of</secondary></indexterm>
<indexterm><primary>subroutines</primary>
<secondary>use of labels</secondary></indexterm>
<indexterm><primary>OFF subkeyword</primary>
<secondary>in a CALL instruction</secondary></indexterm>
<indexterm><primary>ANY subkeyword</primary>
<secondary>in a CALL instruction</secondary></indexterm>
<indexterm><primary>ERROR subkeyword</primary>
<secondary>in a CALL instruction</secondary></indexterm>
<indexterm><primary>FAILURE subkeyword</primary>
<secondary>in a CALL instruction</secondary></indexterm>
<indexterm><primary>HALT subkeyword</primary>
<secondary>in a CALL instruction</secondary></indexterm>
<indexterm><primary>NOTREADY subkeyword</primary>
<secondary>in a CALL instruction</secondary></indexterm>
<indexterm><primary>USER subkeyword</primary>
<secondary>in a CALL instruction</secondary></indexterm>
<indexterm><primary>ON subkeyword</primary>
<secondary>in a CALL instruction</secondary></indexterm>
<indexterm><primary>NAME subkeyword</primary>
<secondary>in a CALL instruction</secondary></indexterm>
<programlisting>
<![CDATA[
+-,--------------+
V |
>>-CALL--+-+-name---+----+------------+-+------------------+--;--><
| +-(expr)-+ +-expression-+ |
+-OFF--+-ANY-----------------+--------------------+
| +-ERROR---------------+ |
| +-FAILURE-------------+ |
| +-HALT----------------+ |
| +-NOTREADY------------+ |
| +-USER--usercondition-+ |
+-ON--+-ANY-----------------+--+----------------+-+
+-ERROR---------------+ +-NAME--trapname-+
+-FAILURE-------------+
+-HALT----------------+
+-NOTREADY------------+
+-USER--usercondition-+
]]>
</programlisting>
<para>CALL calls a routine (if you specify
<emphasis role="italic">name</emphasis>) or controls the trapping
of certain conditions (if you specify ON or OFF).</para>
<para>To control trapping, you specify OFF or ON and the condition you want to
trap. OFF turns off the specified condition trap. ON turns on the specified
condition trap. All information on condition traps is contained in
<xref linkend="condtra" />.</para>
<para>To call a routine, specify <emphasis role="italic">name</emphasis>,
which must be a literal string or symbol that is taken as a constant. The
<emphasis role="italic">usercondition</emphasis> is a single
symbol that is taken as a constant. The
<emphasis role="italic">trapname</emphasis> is a symbol or string
taken as a constant. The routine called can be: </para>
<variablelist>
<varlistentry><term><emphasis role="bold">An internal routine</emphasis></term>
<listitem><para>A subroutine that is in the same program as the CALL
instruction or function call that calls it. Internal routines are located
using label instructions.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="bold">A built-in routine</emphasis>
<indexterm><primary>built-in functions</primary>
<secondary>calling</secondary></indexterm>
<indexterm><primary>built-in functions</primary>
<secondary>definition</secondary></indexterm>
</term>
<listitem><para>A function that is defined as part of the
Rexx language.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="bold">An external routine</emphasis>
<indexterm><primary>external routine</primary></indexterm>
</term>
<listitem><para>A subroutine that is neither built-in nor a label
within the same same program as the CALL instruction call that invokes it.
See <xref linkend="xsearcho" /> for details on the different
types of external routines.
</para></listitem></varlistentry>
</variablelist>
<indexterm><primary>subroutines</primary>
<secondary>forcing built-in or external reference</secondary></indexterm>
<para>If <emphasis role="italic">name</emphasis> is a literal string
(that is, specified in in quotation marks), the search for internal routines is bypassed,
and only a built-in function or an external routine is called. Note that
built-in function names are in uppercase. Therefore, a literal string call
to a built-in function must also use uppercase characters.</para>
<para>You can also specify (<emphasis role="italic">expr</emphasis>),
any valid expression enclosed in
parentheses. The expression is evaluated before any of the argument expressions,
and the value is the target of the CALL instruction. The language processor
does not translate the expression value into uppercase, so the evaluated name
must exactly match any label name or built-in function name. (See
<xref linkend="labels" /> for a description of label names.)</para>
<para>The called routine can optionally return a result. In this case, the CALL
instruction is functionally identical with the clause:</para>
<para></para>
<programlisting>
<![CDATA[
+-,--------------+
V |
>>-result=name(----+------------+-+--)--;----------------------><
+-expression-+
]]>
</programlisting>
<para>You can use any number of <emphasis role="italic">expression</emphasis>s,
separated by
<indexterm><primary>, (comma)</primary>
<secondary>in CALL instruction</secondary></indexterm>
<indexterm><primary>, (comma)</primary>
<secondary>separator of arguments</secondary></indexterm>
<indexterm><primary>comma</primary>
<secondary>separator of arguments</secondary></indexterm>
<indexterm><primary>comma</primary>
<secondary>in CALL instruction</secondary></indexterm>
commas. The expressions are evaluated from left to right and form the arguments
during execution of the routine. Any ARG, PARSE ARG, or USE ARG instruction
or ARG built-in function in the called routine accesses these objects while
the called routine is running. You can omit expressions, if appropriate, by
including extra commas.</para>
<para>The CALL then branches to the routine called
<emphasis role="italic">name</emphasis>, using exactly
the same mechanism as function calls. See
<xref linkend="funct" />. The search
order is as follows: </para>
<indexterm><primary>search order</primary>
<secondary>for subroutines</secondary></indexterm>
<variablelist>
<varlistentry><term><emphasis role="bold">Internal routines</emphasis></term>
<listitem><para>These are sequences of instructions inside the same program,
starting at the label that matches
<emphasis role="italic">name</emphasis> in the CALL instruction. If you specify
the routine name in quotation marks, then an internal routine is not considered
for that search order. The RETURN instruction completes the execution of an
internal routine.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Built-in routines</emphasis></term>
<listitem><para>These are routines built into the language processor for
providing various functions. They always return an object that is the result
of the routine. (See <xref linkend="bifArg" />.)</para>
<note><title>Note</title>
<para>You can call any built-in function
as a subroutine. Any result is stored in RESULT. Simply specify
<computeroutput>CALL</computeroutput>, the function name (with
<emphasis>no parenthesis</emphasis>)
and any arguments:</para></note>
<example>
<title>Instructions - CALL</title>
<programlisting>
call length "string" /* Same as length("string") */
say result /* Produces: 6 */
</programlisting>
</example>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">External routines</emphasis></term>
<listitem><para>Users can write or use routines that are external to the
language processor and the calling program. You can code an external routine
in Rexx or in any language that supports the system-dependent interfaces.
If the CALL instruction calls an external routine written in Rexx as a
subroutine, you can retrieve any argument strings with the ARG, PARSE ARG, or
USE ARG instructions or the ARG built-in function.
</para></listitem></varlistentry>
</variablelist>
<para>For more information on the search order, see
<xref linkend="xsearcho" />.</para>
<para>During execution of an internal routine, all variables previously known
are generally accessible. However, the PROCEDURE instruction can set up a
local variables environment to protect the subroutine and caller from each
other. The EXPOSE option on the PROCEDURE instruction can expose selected
variables to a routine.</para>
<para>Calling an external program or routine defined with a ::ROUTINE directive
is similar to calling an internal
routine. The external routine, however, is an implicit PROCEDURE in that all
the caller's variables are always hidden. The status of internal values, for
<indexterm><primary>NUMERIC instruction</primary>
<secondary>settings saved during subroutine calls</secondary></indexterm>
example NUMERIC settings, start with their defaults (rather than inheriting
those of the caller). In addition, you can use EXIT to return from the routine.</para>
<para>When
control reaches an internal routine,
the line number of the CALL instruction is available in the variable
SIGL (in the caller's variable environment). This can be used as a debug aid
because it is possible to find out how control reached a routine. Note that
if the internal routine uses the PROCEDURE instruction, it needs to EXPOSE
<indexterm><primary>special</primary>
<secondary>variable</secondary>
<tertiary>SIGL</tertiary></indexterm>
<indexterm><primary>SIGL</primary>
<secondary>in CALL instruction</secondary></indexterm>
<indexterm><primary>variable</primary>
<secondary>special</secondary>
<tertiary>SIGL</tertiary></indexterm>
SIGL to get access to the line number of the CALL.</para>
<para>After the subroutine processed
the RETURN instruction, control returns to the clause following the original
CALL. If the RETURN instruction specified an expression, the variable RESULT
<indexterm><primary>special</primary>
<secondary>variable</secondary>
<tertiary>RESULT</tertiary></indexterm>
<indexterm><primary>RESULT special variable</primary>
<secondary>set by RETURN instruction</secondary></indexterm>
is set to the value of that expression. Otherwise, the variable RESULT is
dropped (becomes uninitialized).</para>
<para>An internal routine can include calls to other internal routines,
as well as recursive calls to itself.
<indexterm><primary>recursive call</primary></indexterm>
<indexterm><primary>call, recursive</primary></indexterm>
</para>
<indexterm><primary>CALL instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>CALL instruction</secondary></indexterm>
<example>
<title>Instructions - CALL</title>
<programlisting>
/* Recursive subroutine execution... */
arg z
call factorial z
say z"! =" result
exit
factorial: procedure /* Calculate factorial by */
arg n /* recursive invocation. */
if n=0 then return 1
call factorial n-1
return result * n
</programlisting>
</example>
<indexterm><primary>tracing</primary>
<secondary>action saved during subroutine calls</secondary></indexterm>
<para>During
internal subroutine (and function) execution, all important pieces of
information are automatically saved and then restored upon return from the
routine. These are: </para>
<indexterm><primary>exception conditions saved during subroutine calls
</primary></indexterm>
<itemizedlist>
<listitem><para><emphasis role="bold">The status of loops and other
structures:</emphasis> Executing
a SIGNAL within a subroutine is safe because loops and other structures
that were active when the subroutine was called are not ended. However, those
currently active within the subroutine are ended.</para></listitem>
<listitem><para><emphasis role="bold">Trace action:</emphasis> After a
subroutine is debugged, you
can insert a TRACE Off at the beginning of it without affecting the tracing
of the caller. If you want to debug a subroutine, you can insert a TRACE Results
at the start and tracing is automatically restored to the conditions at entry
(for example, Off) upon return. Similarly, <computeroutput>?</computeroutput>
(interactive debug) is saved across routines.</para></listitem>
<listitem><para><emphasis role="bold">NUMERIC settings:</emphasis> The DIGITS,
FUZZ, and FORM of arithmetic operations (in
<xref linkend="keyNumeric" />) are saved and then restored
on return. A subroutine can, therefore, set the precision, for example, that
it needs to use without affecting the caller.</para></listitem>
<listitem><para><emphasis role="bold">ADDRESS settings:
<indexterm><primary>ADDRESS instruction</primary>
<secondary>settings saved during subroutine calls</secondary></indexterm>
<indexterm><primary>address setting</primary></indexterm>
</emphasis>The current and previous destinations for commands (see
<xref linkend="keyAddress" />)
are saved and then restored on return.</para></listitem>
<listitem><para>
<indexterm><primary>SIGNAL instruction</primary>
<secondary>execution of in subroutines</secondary></indexterm>
<emphasis role="bold">Condition traps:</emphasis> CALL ON and SIGNAL ON are
saved and then restored on return. This means that CALL ON, CALL OFF, SIGNAL ON,
and SIGNAL OFF can be used in a subroutine without affecting the conditions
the caller set up.</para></listitem>
<listitem><para><emphasis role="bold">Condition information:</emphasis> This
information describes
<indexterm><primary>condition</primary>
<secondary>saved during subroutine calls</secondary></indexterm>
<indexterm><primary>condition</primary>
<secondary>information</secondary></indexterm>
<indexterm><primary>condition</primary>
<secondary>saved</secondary></indexterm>
the state and origin of the current trapped condition. The CONDITION built-in
function returns this information. See
<xref linkend="bifCondition" />.</para></listitem>
<listitem><para><emphasis role="bold">.RS value:</emphasis> The value of
the .RS environment symbol. (See <xref linkend="rs" />.)
</para></listitem>
<listitem><para><emphasis role="bold">Elapsed-time clocks:</emphasis>
<indexterm><primary>elapsed-time clock</primary>
<secondary>saved during subroutine calls</secondary></indexterm>
A subroutine inherits the elapsed-time
clock from its caller (see <xref linkend="bifTime" />), but because the
time clock is saved across routine calls, a subroutine or internal function
can independently restart and use the clock without affecting its caller.
For the same reason, a clock started within an internal routine is not
available to the caller.</para></listitem>
</itemizedlist>
</section>
<section id="keyDo"><title>DO</title>
<indexterm><primary>DO instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>flow of control</primary>
<secondary>with DO construct</secondary></indexterm>
<indexterm><primary>grouping instructions to run repetitively</primary></indexterm>
<indexterm><primary>infinite loops</primary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>DO</secondary></indexterm>
<indexterm><primary>END subkeyword</primary>
<secondary>in a DO instruction</secondary></indexterm>
<indexterm><primary>TO subkeyword</primary>
<secondary>in a DO instruction</secondary></indexterm>
<indexterm><primary>BY subkeyword</primary>
<secondary>in a DO instruction</secondary></indexterm>
<indexterm><primary>FOR subkeyword</primary>
<secondary>in a DO instruction</secondary></indexterm>
<indexterm><primary>OVER subkeyword</primary>
<secondary>in a DO instruction</secondary></indexterm>
<indexterm><primary>FOREVER subkeyword</primary>
<secondary>in a DO instruction</secondary></indexterm>
<indexterm><primary>WHILE subkeyword</primary>
<secondary>in a DO instruction</secondary></indexterm>
<indexterm><primary>UNTIL subkeyword</primary>
<secondary>in a DO instruction</secondary></indexterm>
<programlisting>
<![CDATA[
>>-DO---+-------------+--+---------------+--+-----------------+--;-->
+-LABEL--name-+ +-| repetitor |-+ +-| conditional |-+
>--+---------------------+--END--+--------+--;---------------------><
| +-----------------+ | +--name--+
| V | |
+---instruction--;--+-+
]]>
</programlisting>
<para><emphasis role="bold">repetitor:</emphasis>
<indexterm><primary>= (equal sign)</primary>
<secondary>in DO instruction)</secondary></indexterm>
</para>
<indexterm><primary>conditional</primary>
<secondary>loops</secondary></indexterm>
<indexterm><primary>FOREVER phrase of DO instruction</primary></indexterm>
<programlisting>
<![CDATA[
|--+-control1=expri--+-----------+--+-----------+--+------------+-+--|
| +-TO--exprt-+ +-BY--exprb-+ +-FOR--exprf-+ |
+-control2--OVER--collection-----------------------------------+
+-FOREVER------------------------------------------------------+
+-exprr--------------------------------------------------------+
]]>
</programlisting>
<para><emphasis role="bold">conditional:</emphasis></para>
<indexterm><primary>UNTIL phrase of DO instruction</primary></indexterm>
<indexterm><primary>WHILE phrase of DO instruction</primary></indexterm>
<programlisting>
<![CDATA[
|--+-WHILE--exprw-+---------------------------------------------|
+-UNTIL--expru-+
]]>
</programlisting>
<para>DO groups instructions and optionally processes them repetitively. During
repetitive execution, a control variable
(<emphasis role="italic">control1</emphasis>
or <emphasis role="italic">control2</emphasis>) can be stepped through some
range of values.</para>
<para><emphasis role="bold">Notes:</emphasis></para>
<orderedlist>
<listitem><para>The LABEL phrase, if used, must precede any
<emphasis role="italic">repetitor</emphasis> or <emphasis role="italic">conditional</emphasis>.
</para></listitem>
<listitem><para>The <emphasis role="italic">exprr</emphasis>,
<emphasis role="italic">expri</emphasis>,
<emphasis role="italic">exprb</emphasis>,
<emphasis role="italic">exprt</emphasis>, and
<emphasis role="italic">exprf</emphasis> options, if present,
are any expressions that evaluate to a number.
<indexterm><primary>numbers</primary>
<secondary>in DO instruction</secondary></indexterm>
The <emphasis role="italic">exprr</emphasis> and
<emphasis role="italic">exprf</emphasis> options are further restricted
to result in a positive whole number or zero. If necessary, the numbers are
rounded according to the setting of NUMERIC DIGITS.</para></listitem>
<listitem><para>The <emphasis role="italic">exprw</emphasis> or
<emphasis role="italic">expru</emphasis> options, if present, can be any
expression that evaluates to <computeroutput>1</computeroutput> or
<computeroutput>0</computeroutput>. This includes the list form of conditional
expression supported by IF and WHEN, which is
a list of expressions separated by ",". Each subexpression must evaluate to
either <computeroutput>0</computeroutput> or <computeroutput>1</computeroutput>.
The list of expressions is evaluated left-to-right. Evaluation will stop with
the first <computeroutput>0</computeroutput> result and <computeroutput>0</computeroutput>
will be returned as the condition result. If all of the subexpressions evaluate
to <computeroutput>1</computeroutput>, then the condition result is also
<computeroutput>1</computeroutput>.
</para></listitem>
<listitem><para>The TO, BY, and FOR phrases can be in any order, if used, and
are evaluated in the order in which they are written.
<indexterm><primary>BY phrase of DO instruction</primary></indexterm>
<indexterm><primary>TO phrase of DO instruction</primary></indexterm>
<indexterm><primary>FOR phrase of DO instruction</primary></indexterm>
</para></listitem>
<listitem><para>The <emphasis role="italic">instruction</emphasis>
can be any instruction, including assignments,
commands, message instructions, and keyword instructions (including any of
the more complex constructs such as IF, SELECT, and the DO instruction itself).
</para></listitem>
<listitem><para>The subkeywords WHILE, UNTIL, and OVER are reserved within a DO
instruction in that they act as expression terminators for other keywords. Thus they
cannot be used as symbols in any of the expressions.
Similarly, TO, BY, and FOR cannot be used in
<emphasis role="italic">expri</emphasis>,
<emphasis role="italic">exprt</emphasis>,
<emphasis role="italic">exprb</emphasis>, or
<emphasis role="italic">exprf</emphasis>.
<indexterm><primary>FOREVER repetitor on DO instruction</primary></indexterm>
FOREVER is also reserved, but only if it immediately
follows the keyword DO and is not followed by an equal sign.
However, parentheses
around or within an expression can prevent these keywords from terminating an expression.
For example, </para>
<example>
<programlisting>
do i = 1 while i &lt; until
say i
end
</programlisting>
</example>
<para>is considered a syntax error because of the variable named UNTIL. Using parentheses
around the expression allows the variable UNTIL to be used:</para>
<example>
<programlisting>
do i = 1 while (i &lt; until)
say i
end
</programlisting>
</example>
</listitem>
<listitem><para>The <emphasis role="italic">exprb</emphasis>
option defaults to <computeroutput>1</computeroutput>,
if relevant.</para></listitem>
<listitem><para>The <emphasis role="italic">collection</emphasis>
can be any expression that evaluates to an object
that supports a MAKEARRAY method.
Array and List items return an array with the items in the appropriate order,
as do Streams. Tables, Stems, Directories, etc. are not ordered so the items
get placed in the array in no particular order.
</para></listitem>
</orderedlist>
<para>For more information, refer to
<xref linkend="dokey" />.</para>
</section>
<section id="keyDrop"><title>DROP</title>
<indexterm><primary>DROP instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>DROP</secondary></indexterm>
<indexterm><primary>variable</primary>
<secondary>dropping of</secondary></indexterm>
<indexterm><primary>unassing variables</primary></indexterm>
<indexterm><primary>variable</primary>
<secondary>resetting of</secondary></indexterm>
<programlisting>
<![CDATA[
+------------+
V |
>>-DROP----+-name---+-+--;-------------------------------------><
+-(name)-+
]]>
</programlisting>
<para>DROP &quot;unassigns&quot; variables, that is, restores them to their
original uninitialized state. If <emphasis role="italic">name</emphasis>
is not enclosed in parentheses, it identifies
a variable you want to drop and must be a symbol that is a valid variable
name, separated from any other <emphasis role="italic">name</emphasis>
by one or more whitespace characters or comments.</para>
<para>If parentheses enclose a single
<emphasis role="italic">name</emphasis>, then its value is used as a
<indexterm><primary>subsidiary list</primary></indexterm>
subsidiary list of variables to drop. Whitespace characters are not necessary
inside or outside the parentheses, but you can add them if desired. This
subsidiary list must follow the same rules as the original list, that is, be
valid character strings separated by whitespace, except that no parentheses are
allowed. The list need not contain any names&mdash;that is, it can be empty.
</para>
<para>Variables are dropped from left to right. It is not an error to specify
a name more than once or to drop a variable that is not known. If an exposed
variable is named (see <xref linkend="keyExpose" />
and <xref linkend="keyProcedure" />), then
the original variable is dropped.</para>
<indexterm><primary>DROP instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>DROP instruction</secondary></indexterm>
<example>
<title>Instructions - DROP</title>
<programlisting>
j=4
Drop a z.3 z.j
/* Drops the variables: A, Z.3, and Z.4 */
/* so that reference to them returns their names. */
</programlisting>
</example>
<para>Here, a variable name in parentheses is used as a subsidiary list.</para>
<example>
<title>Instructions - DROP</title>
<programlisting>
mylist="c d e"
drop (mylist) f
/* Drops the variables C, D, E, and F */
/* Does not drop MYLIST */
</programlisting>
</example>
<indexterm><primary>stem of a variable</primary>
<secondary>used in DROP instruction</secondary></indexterm>
<para> Specifying a stem
(that is, a symbol that contains only one period as the last character) assigns
the stem variable to a new, empty stem object.</para>
<para><emphasis role="bold">Example:</emphasis></para>
<programlisting>
Drop z.
/* Assigns stem variable z. to a new empty stem object */
</programlisting>
</section>
<section id="keyExit"><title>EXIT</title>
<indexterm><primary>EXIT instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>EXIT</secondary></indexterm>
<indexterm><primary>leaving your program</primary></indexterm>
<indexterm><primary>return</primary>
<secondary>code</secondary>
<tertiary>setting on exit</tertiary></indexterm>
<indexterm><primary>return</primary>
<secondary>string</secondary>
<tertiary>setting on exit</tertiary></indexterm>
<indexterm><primary>unconditionally leaving your program</primary></indexterm>
<programlisting>
<![CDATA[
>>-EXIT--+------------+--;-------------------------------------><
+-expression-+
]]>
</programlisting>
<indexterm><primary>leaving your program</primary></indexterm>
<para>EXIT leaves a program unconditionally. Optionally, EXIT returns a
result object to the caller. The program is stopped immediately, even
if an internal routine is being run. If no internal routine is active, RETURN
(see <xref linkend="keyReturn" />) and EXIT are identical in their
effect on the program running.</para>
<para>If you specify <emphasis role="italic">expression</emphasis>,
it is evaluated and the object resulting from the evaluation is passed back
to the caller when the program stops.</para>
<indexterm><primary>EXIT instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>EXIT instruction</secondary></indexterm>
<example>
<title>Instructions - EXIT</title>
<programlisting>
j=3
Exit j*4
/* Would exit with the string "12" */
</programlisting>
</example>
<para>If you do not specify <emphasis role="italic">expression</emphasis>,
no data is passed back to the
caller. If the program was called as a function, this is detected
as an error.
</para>
<para>You can also use EXIT within a method. The method is stopped immediately,
and the result object, if specified, is returned to the sender. If the method
has previously issued a REPLY instruction
(see <xref linkend="keyReply" />),
the EXIT instruction must not include a result expression.</para>
<para><emphasis role="bold">Notes:</emphasis></para>
<orderedlist>
<listitem><para>If the program was called through a command interface,
an attempt is made
to convert the returned value to a return code acceptable by the underlying
operating system. The returned string must be a whole number whose
value fits in a 16-bit signed integer (within the range -(2**15) to (2**15-1).
If the conversion fails, no error is raised, and a return code of 0 is returned.
</para></listitem>
<listitem><para>If you do not specify EXIT, EXIT is implied at the end of the program,
but no result
value is returned.
<indexterm><primary>bottom of program reached during execution
</primary></indexterm>
</para></listitem>
<listitem><para>On Unix/Linux systems the returned value is limited to a
numerical value between 0 and 255 (an unsigned byte).
</para></listitem>
</orderedlist>
</section>
<section id="keyExpose"><title>EXPOSE</title>
<indexterm><primary>EXPOSE instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>EXPOSE</secondary></indexterm>
<programlisting>
<![CDATA[
+------------+
V |
>>-EXPOSE----+-name---+-+--;-----------------------------------><
+-(name)-+
]]>
</programlisting>
<para>EXPOSE causes the object
variables identified in <emphasis role="italic">name</emphasis>
to be exposed to a method. References to exposed variables, including assigning
and dropping, access variables in the current object's variable pool.
<indexterm><primary>object variable pool</primary></indexterm>
(An object variable pool is a collection
of variables that is associated with an object rather than with any individual
method.) Therefore, the values of existing variables are accessible, and any
changes are persistent even after RETURN or EXIT from the method.</para>
<para>Any changes a method makes to an object variable pool are immediately
visible to any other methods that share the same object variable scope. All
other variables that a method uses are local to the method and are dropped on
RETURN or EXIT. If an EXPOSE instruction is included, it must be the first
instruction of the method.</para>
<para>If parentheses enclose a single <emphasis role="italic">name</emphasis>,
then, after the variable <emphasis role="italic">name</emphasis> is exposed,
the character string value of <emphasis role="italic">name</emphasis> is
immediately used as a subsidiary list of variables. Whitespace characters are
not necessary inside or outside the parentheses, but you can add them if
desired.
<indexterm><primary>subsidiary list</primary></indexterm> This subsidiary list
must follow the same rules as the original list, that is, valid variable names
separated by whitespace characters, except that no parentheses are
allowed.</para>
<para>Variables are exposed in sequence from left to right. It is not an error
to specify a name more than once, or to specify a name that has not been used
as a variable.</para>
<indexterm><primary>EXPOSE instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>EXPOSE instruction</secondary></indexterm>
<example>
<title>Instructions - EXPOSE</title>
<programlisting>
/* Example of exposing object variables */
myobj = .myclass~new
myobj~c
myobj~d /* Would display "Z is: 120" */
::class myclass /* The ::CLASS directive */
/* (see <xref linkend="clasdi" />) */
::method c /* The ::METHOD directive */
/* (see <xref linkend="methd" />) */
expose z
z = 100 /* Would assign 100 to the object variable z */
return
::method d
expose z
z=z+20 /* Would add 20 to the same object variable z */
say "Z is:" z
return
</programlisting>
</example>
<para>You can expose an entire collection of compound variables
(see <xref linkend="compsym" />)
by specifying their stem in the variable list or a subsidiary list.
The variables are exposed for all operations.</para>
<example>
<title>Instructions - EXPOSE</title>
<programlisting>
expose j k c. d.
/* This exposes "J", "K", and all variables whose */
/* name starts with "C." or "D." */
c.1="7." /* This sets "C.1" in the object */
/* variable pool, even if it did not */
/* previously exist. */
</programlisting>
</example>
</section>
<section id="keyForward"><title>FORWARD</title>
<indexterm><primary>FORWARD instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>FORWARD</secondary></indexterm>
<indexterm><primary>CONTINUE subkeyword</primary>
<secondary>in a FORWARD instruction</secondary></indexterm>
<indexterm><primary>ARGUMENTS subkeyword</primary>
<secondary>in a FORWARD instruction</secondary></indexterm>
<indexterm><primary>ARRAY subkeyword</primary>
<secondary>in a FORWARD instruction</secondary></indexterm>
<indexterm><primary>MESSAGE subkeyword</primary>
<secondary>in a FORWARD instruction</secondary></indexterm>
<indexterm><primary>CLASS subkeyword</primary>
<secondary>in a FORWARD instruction</secondary></indexterm>
<indexterm><primary>YO subkeyword</primary>
<secondary>in a FORWARD instruction</secondary></indexterm>
<programlisting>
<![CDATA[
>>-FORWARD--+----------+--+------------------------+------------>
+-CONTINUE-+ +-ARGUMENTS--expra-------+
| +-,-----+ |
| V | |
+-ARRAY--(----expri-+--)-+
>--+----------------+--+--------------+--+-----------+---------><
+-MESSAGE--exprm-+ +-CLASS--exprs-+ +-TO--exprt-+
]]>
</programlisting>
<note><title>Note</title>
<para>You can specify the options in any order.</para></note>
<para>FORWARD forwards the message that caused the currently active method to
begin running. The FORWARD instruction can change parts of the forwarded
message, such as the target object, the message name, the arguments, and the
superclass override.</para>
<para>If you specify the TO option, the language processor evaluates
<emphasis role="italic">exprt</emphasis> to produce a new target object
for the forwarded message. The <emphasis role="italic">exprt</emphasis>
is a literal string, constant symbol, or expression enclosed in parentheses.
If you do not specify the TO option, the initial value of the Rexx special
variable SELF is used.</para>
<para>If you specify the ARGUMENTS option, the language processor
evaluates <emphasis role="italic">expra</emphasis> to produce an
array object that supplies the set of arguments for
the forwarded message. The <emphasis role="italic">expra</emphasis> can be a
literal string, constant symbol, or expression enclosed in parentheses. The
ARGUMENTS value must evaluate to a Rexx array object.</para>
<para>If you specify the ARRAY option, each
<emphasis role="italic">expri</emphasis> is an expression (use
commas to separate the expressions). The language processor evaluates the
expression list to produce a set of arguments for the forwarded message. It
is an error to use both the ARRAY and the ARGUMENTS options on the same FORWARD
instruction.</para>
<para>If you specify neither ARGUMENTS nor ARRAY, the language processor uses
the same arguments specified on the original method call.</para>
<para>If you specify the MESSAGE option, the
<emphasis role="italic">exprm</emphasis> is a literal string,
a constant symbol, or an expression enclosed in parentheses. If you specify
an expression enclosed in parentheses, the language processor evaluates the
expression to obtain its value. The uppercase character string value of the
MESSAGE option is the name of the message that the FORWARD instruction issues.
</para>
<para>If you do not specify MESSAGE, FORWARD uses the message name used to call
the currently active method.</para>
<para>If you specify the CLASS option, the
<emphasis role="italic">exprs</emphasis> is a literal string,
a constant symbol, or an expression enclosed in parentheses. This is the class
object used as a superclass specifier on the forwarded message.</para>
<para>If you do not specify CLASS, the message is forwarded without a superclass
override.</para>
<para>If you do not specify the CONTINUE option,
the language processor immediately
exits the current method before forwarding the message. Results returned from
the forwarded message are the return value from the original message that
called the active method (the caller of the method that issued the FORWARD
instruction). Any conditions the forwarded message raises are raised in the
calling program (without raising a condition in the method issuing the FORWARD
instruction).</para>
<para>If you specify the CONTINUE option, the current method does not exit and
continues with the next instruction when the forwarded message completes.
If the forwarded message returns a result, the language processor assigns
it to the special variable RESULT. If the message does not return a result,
the language processor drops (uninitializes) the variable RESULT.</para>
<para>The FORWARD instruction passes all or part
of an existing message invocation
to another method. For example, the FORWARD instruction can forward a message
to a different target object, using the same message name and arguments.</para>
<indexterm><primary>FORWARD instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>FORWARD instruction</secondary></indexterm>
<example>
<title>Instructions - FORWARD</title>
<programlisting>
::method substr
forward to (self~string) /* Forward to the string value */
</programlisting>
</example>
<para>You can use FORWARD in an UNKNOWN method to reissue to another object the
message that the UNKNOWN method traps.</para>
<example>
<title>Instructions - FORWARD</title>
<programlisting>
::method unknown
use arg msg, args
/* Forward to the string value */
/* passing along the arguments */
forward to (self~string) message (msg) arguments (args)
</programlisting>
</example>
<para>You can use FORWARD in a method to forward a message to a superclass's
methods, passing the same arguments. This is very common usage in object INIT
methods.</para>
<example>
<title>Instructions - FORWARD</title>
<programlisting>
::class savings subclass account
::method init
expose type penalty
forward class (super) continue /* Send to the superclass */
type = "Savings" /* Now complete initialization */
penalty = "1% for balance under 500"
</programlisting>
</example>
<para>In the preceding example, the CONTINUE option causes the FORWARD message
to continue with the next instruction, rather than exiting the Savings class
INIT method.</para>
</section>
<section id="keyGuard"><title>GUARD</title>
<indexterm><primary>GUARD instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>concurrency</primary>
<secondary>GUARD instruction</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>GUARD</secondary></indexterm>
<indexterm><primary>ON subkeyword</primary>
<secondary>in an GUARD instruction</secondary></indexterm>
<indexterm><primary>OFF subkeyword</primary>
<secondary>in an GUARD instruction</secondary></indexterm>
<indexterm><primary>WHEN subkeyword</primary>
<secondary>in an GUARD instruction</secondary></indexterm>
<programlisting>
<![CDATA[
>>-GUARD--+-ON--+------------------+--+--;---------------------><
| +-WHEN--expression-+ |
+-OFF--+------------------+-+
+-WHEN--expression-+
]]>
</programlisting>
<para>GUARD controls a method's exclusive access to an object.</para>
<para>GUARD ON acquires for an active method exclusive use of
its object variable
pool. This prevents other methods that also require exclusive use of the same
variable pool from running on the same object. If another method has already
acquired exclusive access, the GUARD instruction causes the issuing method
to wait until the variable pool is available.</para>
<para>GUARD OFF releases exclusive use of the object variable pool.
Other methods
that require exclusive use of the same variable pool can begin running.</para>
<para>If you specify WHEN, the method delays running until the
<emphasis role="italic">expression</emphasis> evaluates to
<computeroutput>1</computeroutput> (true). If the
<emphasis role="italic">expression</emphasis> evaluates
to <computeroutput>0</computeroutput> (false),
GUARD waits until another method assigns or drops
an object variable (that is, a variable named on an EXPOSE instruction) used
in the WHEN <emphasis role="italic">expression</emphasis>.
When an object variable changes, GUARD reevaluates
the WHEN <emphasis role="italic">expression</emphasis>. If the
<emphasis role="italic">expression</emphasis> evaluates to true,
the method resumes running. If the
<emphasis role="italic">expression</emphasis> evaluates to false,
GUARD resumes waiting.</para>
<indexterm><primary>GUARD instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>GUARD instruction</secondary></indexterm>
<example>
<title>Instructions - GUARD</title>
<programlisting>
<![CDATA[
::method c
expose y
if y>0 then
return 1
else
return 0
::method d
expose z
guard on when z>0
self~c /* Reevaluated when Z changes */
say "Method D"
]]>
</programlisting>
</example>
<para>If you specify WHEN and the method has exclusive access to the object's
variable pool, then the exclusive access is released while GUARD is waiting
for an object variable to change. Exclusive access is reacquired before the
WHEN <emphasis role="italic">expression</emphasis> is evaluated. Once the
WHEN <emphasis role="italic">expression</emphasis> evaluates
to <computeroutput>1</computeroutput> (true), exclusive access is either
retained (for GUARD ON
WHEN) or released (for GUARD OFF WHEN), and the method resumes running.</para>
<note><title>Note</title>
<para>If the condition expression cannot be met, GUARD ON WHEN puts the
program in a continuous wait condition. This can occur in particular when
several activities run concurrently. See
<xref linkend="guamet" /> for more information.
</para></note>
</section>
<section id="keyIf"><title>IF</title>
<indexterm><primary>IF instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>flow of control</primary>
<secondary>with IF construct</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>IF</secondary></indexterm>
<indexterm><primary>THEN</primary>
<secondary>following IF clause</secondary></indexterm>
<indexterm><primary>THEN subkeyword</primary>
<secondary>in an IF instruction</secondary></indexterm>
<indexterm><primary>ELSE subkeyword</primary>
<secondary>in an IF instruction</secondary></indexterm>
<programlisting>
<![CDATA[
>>-IF--expression--+---+--THEN--+---+--instruction-------------->
+-;-+ +-;-+
>--+--------------------------+--------------------------------><
+-ELSE--+---+--instruction-+
+-;-+
]]>
</programlisting>
<para>IF conditionally processes an instruction or group of instructions
depending on the evaluation of the <emphasis role="italic">expression</emphasis>.
The <emphasis role="italic">expression</emphasis> is evaluated
and must result in <computeroutput>0</computeroutput> or
<computeroutput>1</computeroutput>.</para>
<para>The instruction after the THEN is processed only if the result is
<computeroutput>1</computeroutput> (true). If you specify an ELSE, the
instruction after ELSE is processed only if the result of the evaluation is
<computeroutput>0</computeroutput> (false).</para>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>IF instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>IF instruction</secondary></indexterm>
<programlisting>
if answer="YES" then say "OK!"
else say "Why not?"
</programlisting>
<para>Remember that if the ELSE clause is on the same line as the last clause
of the THEN part, you need a semicolon before ELSE.</para>
<para><emphasis role="bold">Example:</emphasis></para>
<programlisting>
if answer="YES" then say "OK!"; else say "Why not?"
</programlisting>
<para>ELSE binds to the nearest IF at the same level. You can use the NOP
instruction to eliminate errors and possible confusion when IF constructs
are nested, as in the following example.</para>
<example>
<title>Instructions - IF</title>
<programlisting>
If answer = "YES" Then
If name = "FRED" Then
say "OK, Fred."
Else
nop
Else
say "Why not?"
</programlisting>
</example>
<para>The <emphasis role="italic">expression</emphasis> may also be
a list of expressions separated by ",". Each subexpression must evaluate to
either <computeroutput>0</computeroutput> or <computeroutput>1</computeroutput>.
The list of expressions is evaluated left-to-right. Evaluation will stop with
the first <computeroutput>0</computeroutput> result and <computeroutput>0</computeroutput>
will be returned as the condition result. If all of the subexpressions evaluate
to <computeroutput>1</computeroutput>, then the condition result is also
<computeroutput>1</computeroutput>.</para>
<example>
<title>Instructions - IF</title>
<programlisting>
If answer~datatype('w'), answer//2 = 0 Then
say answer "is even"
Else
say answer "is odd"
</programlisting>
</example>
<para>The example above is not the same as using the following</para>
<example>
<title>Instructions - IF</title>
<programlisting>
If answer~datatype('w') &amp; answer//2 = 0 Then
say answer "is even"
Else
say answer "is odd"
</programlisting>
</example>
<para>The logical &amp; operator will evaluate both terms of the operation, so the
term "answer//2" will result in a syntax error if answer is a non-numeric value. With the
list conditional form, evaluation will stop with the first false result, so the
"answer//2" term will not be evaluated if the datatype test returns <computeroutput>0</computeroutput>.
</para>
<para><emphasis role="bold">Notes:</emphasis></para>
<orderedlist>
<listitem><para>The <emphasis role="italic">instruction</emphasis>
can be any assignment, message instruction, command, or keyword instruction,
including any of the more complex constructs
such as DO, LOOP, SELECT, or the IF instruction itself. A null clause is not an
instruction, so putting an extra semicolon (or label) after THEN or ELSE is
not equivalent to putting a dummy instruction (as it would be in C). The
NOP instruction is provided for this purpose.</para></listitem>
<listitem><para>The symbol THEN cannot be used within
<emphasis role="italic">expression</emphasis>, because the
keyword THEN is treated differently in that it need not start a clause. This
allows the expression on the IF clause to be ended by THEN, without a semicolon
(;) being required.</para></listitem>
</orderedlist>
</section>
<section id="keyInterpret"><title>INTERPRET</title>
<indexterm><primary>INTERPRET instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>execution</primary>
<secondary>of data</secondary></indexterm>
<indexterm><primary>interpretive execution of data</primary></indexterm>
<indexterm><primary>indirect evaluation of data</primary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>INTERPRET</secondary></indexterm>
<indexterm><primary>label</primary>
<secondary>in INTERPRET instruction</secondary></indexterm>
<indexterm><primary>string</primary>
<secondary>interpretation of</secondary></indexterm>
<programlisting>
<![CDATA[
>>-INTERPRET--expression--;------------------------------------><
]]>
</programlisting>
<para>INTERPRET processes instructions that have been built dynamically by
evaluating <emphasis role="italic">expression</emphasis>.</para>
<para>The <emphasis role="italic">expression</emphasis>
is evaluated to produce a character string, and
is then processed (interpreted) just as though the resulting string were a
line inserted into the program and bracketed by a DO; and an END;.</para>
<para>Any instructions (including INTERPRET instructions) are allowed, but note
that constructions such as DO...END and SELECT...END must be complete.
For example, a string of instructions being interpreted cannot contain a LEAVE
or ITERATE instruction (valid only within a repetitive loop) unless it
also contains the whole repetitive DO...END or LOOP...END construct.</para>
<para>A semicolon is implied at the end of the expression during execution, if
one was not supplied.</para>
<indexterm><primary>INTERPRET instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>INTERPRET instruction</secondary></indexterm>
<example>
<title>Instructions - INTERPRET</title>
<programlisting>
/* INTERPRET example */
data="FRED"
interpret data "= 4"
/* Builds the string "FRED = 4" and */
/* Processes: FRED = 4; */
/* Thus the variable FRED is set to "4" */
</programlisting>
<programlisting>
/* Another INTERPRET example */
data="do 3; say "Hello there!"; end"
interpret data /* Displays: */
/* Hello there! */
/* Hello there! */
/* Hello there! */
</programlisting>
</example>
<para><emphasis role="bold">Notes:</emphasis></para>
<orderedlist>
<listitem><para>
Labels within the interpreted string are not permanent and
are, therefore, an error.</para></listitem>
<listitem><para>Executing the INTERPRET instruction with
<computeroutput>TRACE R</computeroutput> or
<computeroutput>TRACE I</computeroutput>
can be helpful in interpreting the results you get.</para>
<indexterm><primary>INTERPRET instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>INTERPRET instruction</secondary></indexterm>
<example>
<title>Instructions - INTERPRET</title>
<programlisting>
/* Here is a small Rexx program. */
Trace Int
name="Kitty"
indirect="name"
interpret &apos;say "Hello"&apos; indirect&apos;"!"&apos;
</programlisting>
<para>When this is
run, you get the following trace: </para>
<programlisting>
3 *-* name="Kitty"
>L> "Kitty"
>>> "Kitty"
4 *-* indirect="name"
>L> "name"
>>> "name"
5 *-* interpret 'say "Hello"' indirect'"!"'
>L> "say "Hello""
>V> INDIRECT => "name"
>O> " " => "say "Hello" name"
>L> ""!""
>O> "" => "say "Hello" name"!""
>>> "say "Hello" name"!""
5 *-* say "Hello" name"!"
>L> "Hello"
>V> NAME => "Kitty"
>O> " " => "Hello Kitty"
>L> "!"
>O> "" => "Hello Kitty!"
>>> "Hello Kitty!"
Hello Kitty!
</programlisting>
</example>
<para>Lines 3 and 4 set the variables used in line 5. Execution
of line 5 then proceeds in two stages. First the string to be interpreted
is built up, using a literal string, a variable
(<computeroutput>INDIRECT</computeroutput>), and
another literal string. The resulting pure character string is then interpreted,
just as though it were actually part of the original program. Because it is
a new clause, it is traced as such (the second
<computeroutput>*-*</computeroutput> trace flag under
line 5) and is then processed. Again a literal string is concatenated to the
value of a variable (<computeroutput>NAME</computeroutput>) and another literal,
and the final result (<computeroutput>Hello Kitty!</computeroutput>) is then
displayed.</para></listitem>
<listitem><para>For many purposes, you can use the VALUE function
(see <xref linkend="bifValue" />)
instead of the INTERPRET instruction. The following line could, therefore,
have replaced line 5 in the previous example: </para>
<example>
<title>Instructions - INTERPRET</title>
<programlisting>
say "Hello" value(indirect)"!"
</programlisting>
</example>
<para>INTERPRET is usually required only in special cases, such as when
two or more statements are to be interpreted together, or when an expression
is to be evaluated dynamically.</para></listitem>
<listitem><para>You cannot use a directive (see
<xref linkend="dire" />) within an INTERPRET
instruction.</para></listitem>
</orderedlist>
</section>
<section id="keyIterate"><title>ITERATE</title>
<indexterm><primary>ITERATE instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>ITERATE</secondary></indexterm>
<indexterm><primary>loops</primary>
<secondary>modification of</secondary></indexterm>
<programlisting>
<![CDATA[
>>-ITERATE--+------+--;----------------------------------------><
+-name-+
]]>
</programlisting>
<indexterm><primary>altering</primary>
<secondary>flow within a repetitive loop</secondary></indexterm>
<para>ITERATE alters the flow within a repetitive loop (that is, any DO
construct other than that with a simple DO or a LOOP instruction).</para>
<para>Execution of the group of instructions stops, and control is passed to
the DO or LOOP instruction just as though the END clause had been encountered. The
control variable, if any, is incremented and tested, as usual, and the group
of instructions is processed again, unless the DO or LOOP instruction ends the loop.
</para>
<para>The <emphasis role="italic">name</emphasis> is a symbol, taken as a
constant. If <emphasis role="italic">name</emphasis> is
not specified, ITERATE continues with the current repetitive loop.
If <emphasis role="italic">name</emphasis> is specified, it must be the
name of the control variable or the LABEL name of a currently
active loop, which can be the innermost, and this is the loop that is stepped.
Any active loops inside the one selected for iteration are ended (as though
by a LEAVE instruction).</para>
<indexterm><primary>ITERATE instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>ITERATE instruction</secondary></indexterm>
<example>
<title>Instructions - ITERATE</title>
<programlisting>
loop label MyLabelName i=1 to 4 /* label set to 'MYLABELNAME' */
if i=2 then iterate
say i
end myLabelName
/* Displays the numbers:
1
3
4
*/
</programlisting>
</example>
<para><emphasis role="bold">Notes:</emphasis></para>
<orderedlist>
<listitem><para>If specified, <emphasis role="italic">name</emphasis>
must match the symbol naming the control variable or LABEL name
in the DO or LOOP clause in all respects except the case. No substitution for compound
variables is carried out when the comparison is made.</para></listitem>
<listitem><para>A loop is active if it is currently being processed.
If a subroutine is called, or an INTERPRET instruction is processed, during
the execution of a loop, the loop becomes inactive until the subroutine has
returned or the INTERPRET instruction has completed. ITERATE cannot be used
to continue with an inactive loop.</para></listitem>
<listitem><para>
<indexterm><primary>loops</primary>
<secondary>active</secondary></indexterm>
If more than one active loop uses the same name, ITERATE selects
the innermost loop.</para></listitem>
</orderedlist>
</section>
<section id="keyLeave"><title>LEAVE</title>
<indexterm><primary>LEAVE instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>LEAVE</secondary></indexterm>
<indexterm><primary>loops</primary>
<secondary>termination of</secondary></indexterm>
<indexterm><primary>repetitive loops</primary>
<secondary>altering flow</secondary></indexterm>
<indexterm><primary>repetitive loops</primary>
<secondary>exiting</secondary></indexterm>
<programlisting>
<![CDATA[
>>-LEAVE--+------+--;------------------------------------------><
+-name-+
]]>
</programlisting>
<para>LEAVE causes an immediate exit from one or more repetitive loops or block instruction
(simple DO or SELECT).
</para>
<para>Processing of the group of instructions is ended, and control is passed
to the instruction following the END clause, just as though the END clause
had been encountered and the termination condition had been met. However,
on exit, the control variable, if any, contains the value it had when the
LEAVE instruction was processed.</para>
<para>The <emphasis role="italic">name</emphasis> is
a symbol, taken as a constant. If
<emphasis role="italic">name</emphasis> is not specified, LEAVE ends
the innermost active repetitive loop. If
<emphasis role="italic">name</emphasis> is specified, it must
be the name of the control variable or LABEL name of a currently active LOOP, DO, or SELECT, which can
be the innermost, and that block, and any active block
<indexterm><primary>active blocks</primary></indexterm>
inside it, are then
ended. Control then passes to the clause following the END that matches the
instruction of the selected block.</para>
<indexterm><primary>LEAVE instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>LEAVE instruction</secondary></indexterm>
<example>
<title>Instructions - LEAVE</title>
<programlisting>
max=5
do label myDoBlock /* define a label 'MYDOBLOCK' */
loop i=1 to max /* label defaults to control variable 'I' */
if i = 2 then iterate i
if i = 4 the leave myDoBlock
say i
end i
say 'after looping' max 'times'
end myDoBlock
/* Displays the following
1
3
after looping 4 times
*/
</programlisting>
</example>
<para><emphasis role="bold">Notes:</emphasis></para>
<orderedlist>
<listitem><para>If specified, <emphasis role="italic">name</emphasis>
must match the symbol naming the control variable or LABEL name
in the DO, LOOP, or SELECT clause in all respects except the case. No substitution for compound
variables is carried out when the comparison is made.</para></listitem>
<listitem><para>A loop is active if it is currently being processed. If a
subroutine is called, or an INTERPRET instruction is processed, during
execution of a loop, the loop becomes inactive until the subroutine has
returned or the INTERPRET instruction has completed. LEAVE cannot be used to
end an inactive block.</para></listitem>
<listitem><para>If more than one active block uses the same control variable,
LEAVE selects the innermost block.</para></listitem>
</orderedlist>
</section>
<section id="keyLoop"><title>LOOP</title>
<indexterm><primary>LOOP instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>flow of control</primary>
<secondary>with LOOP construct</secondary></indexterm>
<indexterm><primary>grouping instructions to run repetitively</primary></indexterm>
<indexterm><primary>infinite loops</primary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>LOOP</secondary></indexterm>
<indexterm><primary>END subkeyword</primary>
<secondary>in a LOOP instruction</secondary></indexterm>
<indexterm><primary>TO subkeyword</primary>
<secondary>in a LOOP instruction</secondary></indexterm>
<indexterm><primary>BY subkeyword</primary>
<secondary>in a LOOP instruction</secondary></indexterm>
<indexterm><primary>FOR subkeyword</primary>
<secondary>in a LOOP instruction</secondary></indexterm>
<indexterm><primary>OVER subkeyword</primary>
<secondary>in a LOOP instruction</secondary></indexterm>
<indexterm><primary>FOREVER subkeyword</primary>
<secondary>in a LOOP instruction</secondary></indexterm>
<indexterm><primary>WHILE subkeyword</primary>
<secondary>in a LOOP instruction</secondary></indexterm>
<indexterm><primary>UNTIL subkeyword</primary>
<secondary>in a LOOP instruction</secondary></indexterm>
<programlisting>
<![CDATA[
>>-LOOP--+-------------+--+---------------+--+-----------------+--;-->
+-LABEL--name-+ +-| repetitor |-+ +-| conditional |-+
>--+--------------------+--END--+--------+--;-----------------------><
| +----------------+ | +--name--+
| V | |
+---instruction--;-+-+
]]>
</programlisting>
<para><emphasis role="bold">repetitor:</emphasis>
<indexterm><primary>= (equal sign)</primary>
<secondary>in LOOP instruction)</secondary></indexterm>
</para>
<indexterm><primary>conditional</primary>
<secondary>loops</secondary></indexterm>
<indexterm><primary>FOREVER phrase of LOOP instruction</primary></indexterm>
<programlisting>
<![CDATA[
|--+-control1=expri--+-----------+--+-----------+--+------------+-+--|
| +-TO--exprt-+ +-BY--exprb-+ +-FOR--exprf-+ |
+-control2--OVER--collection-----------------------------------+
+-FOREVER------------------------------------------------------+
+-exprr--------------------------------------------------------+
]]>
</programlisting>
<para><emphasis role="bold">conditional:</emphasis></para>
<indexterm><primary>UNTIL phrase of LOOP instruction</primary></indexterm>
<indexterm><primary>WHILE phrase of LOOP instruction</primary></indexterm>
<programlisting>
<![CDATA[
|--+-WHILE--exprw-+---------------------------------------------|
+-UNTIL--expru-+
]]>
</programlisting>
<para>LOOP groups instructions and processes them repetitively. During
repetitive execution, a control variable
(<emphasis role="italic">control1</emphasis>
or <emphasis role="italic">control2</emphasis>) can be stepped through some
range of values.</para>
<para><emphasis role="bold">Notes:</emphasis></para>
<orderedlist>
<listitem><para>The LABEL phrase, if used, must precede any
<emphasis role="italic">repetitor</emphasis> or <emphasis role="italic">conditional</emphasis>.
</para></listitem>
<listitem><para>The <emphasis role="italic">exprr</emphasis>,
<emphasis role="italic">expri</emphasis>,
<emphasis role="italic">exprb</emphasis>,
<emphasis role="italic">exprt</emphasis>, and
<emphasis role="italic">exprf</emphasis> options, if present,
are any expressions that evaluate to a number.
<indexterm><primary>numbers</primary>
<secondary>in LOOP instruction</secondary></indexterm>
The <emphasis role="italic">exprr</emphasis> and
<emphasis role="italic">exprf</emphasis> options are further restricted
to result in a positive whole number or zero. If necessary, the numbers are
rounded according to the setting of NUMERIC DIGITS.</para></listitem>
<listitem><para>The <emphasis role="italic">exprw</emphasis> or
<emphasis role="italic">expru</emphasis> options, if present, can be any
expression that evaluates to <computeroutput>1</computeroutput> or
<computeroutput>0</computeroutput>. This includes the list form of conditional
expression supported by IF and WHEN, which is
a list of expressions separated by ",". Each subexpression must evaluate to
either <computeroutput>0</computeroutput> or <computeroutput>1</computeroutput>.
The list of expressions is evaluated left-to-right. Evaluation will stop with
the first <computeroutput>0</computeroutput> result and <computeroutput>0</computeroutput>
will be returned as the condition result. If all of the subexpressions evaluate
to <computeroutput>1</computeroutput>, then the condition result is also
<computeroutput>1</computeroutput>.
</para></listitem>
<listitem><para>The TO, BY, and FOR phrases can be in any order, if used, and
are evaluated in the order in which they are written.
<indexterm><primary>BY phrase of LOOP instruction</primary></indexterm>
<indexterm><primary>TO phrase of LOOP instruction</primary></indexterm>
<indexterm><primary>FOR phrase of LOOP instruction</primary></indexterm>
</para></listitem>
<listitem><para>The <emphasis role="italic">instruction</emphasis>
can be any instruction, including assignments,
commands, message instructions, and keyword instructions (including any of
the more complex constructs such as IF, SELECT, and the LOOP instruction itself).
</para></listitem>
<listitem><para>The subkeywords WHILE, UNTIL, and OVER are reserved within a DO
instruction in that they act as expression terminators for other keywords. Thus they
cannot be used as symbols in any of the expressions.
Similarly, TO, BY, and FOR cannot be used in
<emphasis role="italic">expri</emphasis>,
<emphasis role="italic">exprt</emphasis>,
<emphasis role="italic">exprb</emphasis>, or
<emphasis role="italic">exprf</emphasis>.
<indexterm><primary>FOREVER repetitor on DO instruction</primary></indexterm>
FOREVER is also reserved, but only if it immediately
follows the keyword DO and is not followed by an equal sign.
However, parentheses
around or within an expression can prevent these keywords from terminating an expression.
For example, </para>
<example>
<programlisting>
loop i = 1 while i &lt; until
say i
end
</programlisting>
</example>
<para>is considered a syntax error because of the variable named UNTIL. Using parentheses
around the expression allows the variable UNTIL to be used:</para>
<example>
<programlisting>
loop i = 1 while (i &lt; until)
say i
end
</programlisting>
</example>
</listitem>
<listitem><para>The <emphasis role="italic">exprb</emphasis>
option defaults to <computeroutput>1</computeroutput>,
if relevant.</para></listitem>
<listitem><para>The <emphasis role="italic">collection</emphasis>
can be any expression that evaluates to an object
that supports a MAKEARRAY method.
Array and List items return an array with the items in the appropriate order,
as do Streams. Tables, Stems, Directories, etc. are not ordered so the items
get placed in the array in no particular order.
</para></listitem>
</orderedlist>
<para>For more information, refer to
<xref linkend="dokey" />.</para>
</section>
<section id="keyNop"><title>NOP</title>
<indexterm><primary>NOP instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>NOP</secondary></indexterm>
<programlisting>
<![CDATA[
>>-NOP;--------------------------------------------------------><
]]>
</programlisting>
<para>NOP is a dummy instruction that has no effect. It can be useful as the
target of a THEN or ELSE clause.</para>
<indexterm><primary>NOP instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>NOP instruction</secondary></indexterm>
<example>
<title>Instructions - NOP</title>
<programlisting>
Select
when a=c then nop /* Do nothing */
when a>c then say "A > C"
otherwise say "A &lt; C"
end
</programlisting>
</example>
<note><title>Note</title>
<para>Putting an extra semicolon instead of the NOP would
merely insert a null clause, which would be ignored. The second WHEN clause
would be seen as the first instruction expected after the THEN, and would,
therefore, be treated as a syntax error. NOP is a true instruction, however,
and is, therefore, a valid target for the THEN clause.</para></note>
</section>
<section id="keyNumeric"><title>NUMERIC</title>
<indexterm><primary>NUMERIC instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>arithmetic</primary>
<secondary>NUMERIC setting</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>NUMERIC</secondary></indexterm>
<indexterm><primary>NUMERIC instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>DIGITS subkeyword</primary>
<secondary>in a NUMERIC instruction</secondary></indexterm>
<indexterm><primary>FORM subkeyword</primary>
<secondary>in a NUMERIC instruction</secondary></indexterm>
<indexterm><primary>FUZZ subkeyword</primary>
<secondary>in a NUMERIC instruction</secondary></indexterm>
<indexterm><primary>SCIENTIFIC subkeyword</primary>
<secondary>in a NUMERIC instruction</secondary></indexterm>
<indexterm><primary>ENGINEERING subkeyword</primary>
<secondary>in a NUMERIC instruction</secondary></indexterm>
<indexterm><primary>VALUE subkeyword</primary>
<secondary>in a NUMERIC instruction</secondary></indexterm>
<programlisting>
<![CDATA[
>>-NUMERIC--+-DIGITS--+-------------+----------+--;------------><
| +-expression1-+ |
| +-SCIENTIFIC-------------+ |
+-FORM--+------------------------+-+
| +-ENGINEERING------------+ |
| +-+-------+--expression2-+ |
| +-VALUE-+ |
+-FUZZ--+-------------+------------+
+-expression3-+
]]>
</programlisting>
<para>NUMERIC changes the way in which a program carries out arithmetic
operations. The options of this instruction are described in detail in
<xref linkend="numarit" />.</para>
<variablelist>
<varlistentry><term><emphasis role="bold">NUMERIC DIGITS</emphasis>
<indexterm><primary>NUMERIC instruction</primary>
<secondary>DIGITS option</secondary></indexterm>
</term>
<listitem><para>controls the precision to which arithmetic operations and
built-in functions are evaluated. If you omit
<emphasis role="italic">expression1</emphasis>, the precision defaults to
9 digits, but can be overridden on a source-file basis using the
::OPTIONS directive (<xref linkend="optionsd" />. Otherwise, the character
string value result of
<emphasis role="italic">expression1</emphasis> must evaluate to a positive whole
number and must be larger than the current NUMERIC FUZZ setting.</para>
<para>There is no limit to the value for DIGITS
(except the amount of storage available), but high precisions are likely to
require a great amount of processing time. It is recommended that you use
the default value whenever possible.</para>
<para>You can retrieve the current NUMERIC
DIGITS setting with the DIGITS built-in function. See
<xref linkend="bifDigits" />.</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">NUMERIC FORM</emphasis>
<indexterm><primary>NUMERIC instruction</primary>
<secondary>FORM option</secondary></indexterm>
<indexterm><primary>FORM option of NUMERIC instruction</primary></indexterm>
</term>
<listitem><para>controls the form of exponential notation
for the result of arithmetic
operations and built-in functions. This can be either SCIENTIFIC (in which
case only one, nonzero digit appears before the decimal point) or ENGINEERING
(in which case the power of 10 is always a multiple of 3). The default is
SCIENTIFIC. The subkeywords SCIENTIFIC or ENGINEERING set the FORM directly,
or it is taken from the character string result of evaluating the expression
(<emphasis role="italic">expression2</emphasis>) that follows VALUE. The result
in this case must be either <computeroutput>SCIENTIFIC</computeroutput> or
<computeroutput>ENGINEERING</computeroutput>. You can omit the subkeyword
VALUE if <emphasis role="italic">expression2</emphasis> does not begin with a
symbol or a literal string,
that is, if it starts with a special character, such as an operator character
or parenthesis.</para>
<para>You can retrieve the current NUMERIC FORM setting with
the FORM built-in function. See <xref linkend="bifForm" />.</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">NUMERIC FUZZ</emphasis></term>
<listitem><para>controls how many digits, at full precision, are ignored during
a numeric
comparison operation. (See <xref linkend="numcom" />.)
If you omit <emphasis role="italic">expression3</emphasis>,
the default is 0 digits. Otherwise, the character string value result
of <emphasis role="italic">expression3</emphasis> must evaluate
to 0 or a positive whole number rounded,
if necessary, according to the current NUMERIC DIGITS setting, and must be
smaller than the current NUMERIC DIGITS setting.</para>
<para>NUMERIC FUZZ temporarily
<indexterm><primary>NUMERIC instruction</primary>
<secondary>FUZZ option</secondary></indexterm>
<indexterm><primary>FUZZ</primary>
<secondary>instruction</secondary></indexterm>
reduces the value of NUMERIC DIGITS by the NUMERIC FUZZ value during every
numeric comparison. The numbers are subtracted under a precision of DIGITS
minus FUZZ digits during the comparison and are then compared with 0.</para>
<para>You can retrieve the current NUMERIC FUZZ setting with the FUZZ built-in
function. See <xref linkend="bifFuzz" />.</para>
</listitem></varlistentry>
</variablelist>
<note><title>Note</title>
<para>The three numeric settings are automatically saved across
internal subroutine and function calls. See the CALL instruction
(<xref linkend="keyCall" />) for more details.</para></note>
</section>
<section id="keyOptions"><title>OPTIONS</title>
<indexterm><primary>OPTIONS instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>OPTIONS</secondary></indexterm>
<programlisting>
<![CDATA[
>>-OPTIONS--+------------+--;-------------------------------------><
+-expression-+
]]>
</programlisting>
<para>The OPTIONS instruction is used to pass special requests to the
language processor.</para>
<para>The
<emphasis role="italic">expression</emphasis> is evaluated, and individual words
in the result that are meaningful to the language processor will be obeyed.
Optiions might control how the interpreter optimizes code, enforces standards,
enables implementation-dependent features, etc.). Unrecognized words in the
result are ignored, since they are assumed to be instructions for a different
language processor.</para>
<para>Open Object Rexx does not recognize any option keywords.</para>
</section>
<section id="keyParse"><title>PARSE</title>
<indexterm><primary>PARSE instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>PARSE</secondary></indexterm>
<indexterm><primary>template</primary>
<secondary>list</secondary>
<tertiary>PARSE instruction</tertiary></indexterm>
<indexterm><primary>UPPER subkeyword</primary>
<secondary>in a PARSE instruction</secondary></indexterm>
<indexterm><primary>LOWER subkeyword</primary>
<secondary>in a PARSE instruction</secondary></indexterm>
<indexterm><primary>CASELESS subkeyword</primary>
<secondary>in a PARSE instruction</secondary></indexterm>
<indexterm><primary>ARG subkeyword</primary>
<secondary>in a PARSE instruction</secondary></indexterm>
<indexterm><primary>LINEIN subkeyword</primary>
<secondary>in a PARSE instruction</secondary></indexterm>
<indexterm><primary>PULL subkeyword</primary>
<secondary>in a PARSE instruction</secondary></indexterm>
<indexterm><primary>SOURCE subkeyword</primary>
<secondary>in a PARSE instruction</secondary></indexterm>
<indexterm><primary>VALUE subkeyword</primary>
<secondary>in a PARSE instruction</secondary></indexterm>
<indexterm><primary>WITH subkeyword</primary>
<secondary>in a PARSE instruction</secondary></indexterm>
<indexterm><primary>VAR subkeyword</primary>
<secondary>in a PARSE instruction</secondary></indexterm>
<indexterm><primary>VERSION subkeyword</primary>
<secondary>in a PARSE instruction</secondary></indexterm>
<programlisting>
<![CDATA[
>>-PARSE--+-------+--+----------+------------------------------->
+-UPPER-+ +-CASELESS-+
+-LOWER-+
>--+-ARG-------------------------+--+---------------+--;-------><
+-LINEIN----------------------+ +-template_list-+
+-PULL------------------------+
+-SOURCE----------------------+
+-VALUE--+------------+--WITH-+
| +-expression-+ |
+-VAR--name-------------------+
+-VERSION---------------------+
]]>
</programlisting>
<note><title>Note</title>
<para>You can specify UPPER and CASELESS or LOWER and CASELESS in
either order.</para></note>
<indexterm><primary>assigning data to variables</primary></indexterm>
<para>PARSE assigns data from various sources to one or more variables according
to the rules of parsing. (See <xref linkend="parsingch" />.)</para>
<para>
<indexterm><primary>uppercase translation</primary>
<secondary>with PARSE UPPER</secondary></indexterm>
<indexterm><primary>lowercase translation</primary>
<secondary>with PARSE LOWER</secondary></indexterm>
If you specify UPPER, the strings to be parsed are translated to uppercase before
parsing. If you specify LOWER, the strings are translated to lowercase. Otherwise
no translation takes place.
</para>
<para>If you
specify CASELESS, character string matches during parsing are made independent
of the case. This means a letter in uppercase is equal to the same letter
in lowercase.</para>
<indexterm><primary>parsing</primary>
<secondary>templates</secondary>
<tertiary>in PARSE instruction</tertiary></indexterm>
<para>The <emphasis role="italic">template_list</emphasis> can be a
single template or list of templates separated by commas. Each
template consists of one or more symbols separated by whitespace, patterns, or
both.</para>
<para>Each template is applied to a single source string. Specifying several
templates is not a syntax error, but only the PARSE ARG variant can supply
more than one non-null source string. See
<xref linkend="parsmul" /> for information
on parsing several source strings.</para>
<para>If you do not specify a template, no variables are set but the data is
prepared for parsing, if necessary. Thus for PARSE PULL, a data string is
removed from the current data queue, for PARSE LINEIN (and PARSE PULL if the
queue is empty), a line is taken from the default input stream, and for PARSE
VALUE, <emphasis role="italic">expression</emphasis> is evaluated.
For PARSE VAR, the specified variable is accessed. If it does not have
a value, the NOVALUE condition is raised, if it is enabled.</para>
<para>The following list describes the data for each variant of the PARSE
instruction.</para>
<variablelist>
<varlistentry><term><emphasis role="bold">PARSE ARG</emphasis>
<indexterm><primary>ARG option of PARSE instruction</primary></indexterm>
<indexterm><primary>arguments</primary>
<secondary>retrieving with PARSE ARG instruction</secondary></indexterm>
</term>
<listitem><para>parses the strings passed to a program, routine, or method as
input arguments. (See the ARG instruction in
<xref linkend="keyArg" /> for details and examples.)
<note><title>Note</title>
<para>Parsing uses the string values of the argument objects. The
USE ARG instruction provides direct access to argument objects.
You can also retrieve or check the argument objects to a Rexx program, routine, or
method with the ARG built-in function (see
<xref linkend="bifArg" />).
</para></note>
</para></listitem></varlistentry>
<varlistentry><term id="parlini"><emphasis role="bold">PARSE LINEIN</emphasis>
<indexterm><primary>LINEIN option of PARSE instruction</primary></indexterm>
<indexterm><primary>lines</primary>
<secondary>from stream</secondary></indexterm>
</term>
<listitem><para>
parses the next line of the default input stream.
(See <xref linkend="iostrms" /> for a discussion
of Rexx input and output.) PARSE LINEIN
is a shorter form of the following instruction:
</para>
<programlisting>
<![CDATA[
>>-PARSE VALUE LINEIN() WITH--+---------------+--;--------------><
+-template_list-+
]]>
</programlisting>
<para>If no line is available, program execution usually pauses
until a line is complete. Use PARSE LINEIN only when direct access to the
character input stream is necessary. Use the PULL or PARSE PULL instructions
for the usual line-by-line dialog with the user to maintain generality.
PARSE LINEIN will not pull lines from the external data queue.
</para>
<para>To check if any lines are available in the default input stream, use the
built-in
function LINES. See <xref linkend="bifLines" />
and <xref linkend="bifLinein" />.</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">PARSE PULL</emphasis>
<indexterm><primary>PULL option of PARSE instruction</primary></indexterm>
</term>
<listitem><para>parses the next string of the external data queue. If the
external data
queue is empty, PARSE PULL reads a line of the default input stream (the user's
terminal), and the program pauses, if necessary, until a line is complete.
You can add data to the head or tail of the queue by using the PUSH and QUEUE
instructions, respectively. You can find the number of lines currently in
the queue with the QUEUED built-in function. (See
<xref linkend="bifQueued" />.)
The queue remains active as long as the language processor is active. Other
programs in the system can alter the queue and use it to communicate with
programs written in Rexx. See also the PULL instruction in
<xref linkend="keyPull" />.
</para>
<note><title>Note</title>
<para>PULL and PARSE PULL read the current data queue. If the queue is
empty, they read the default input stream, .INPUT (typically, the keyboard).
</para></note>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">PARSE SOURCE</emphasis>
<indexterm><primary>SOURCE option of PARSE instruction</primary></indexterm>
<indexterm><primary>file name, extension, path of program</primary></indexterm>
<indexterm><primary>names</primary>
<secondary>of programs</secondary></indexterm>
<indexterm><primary>programs</primary>
<secondary>retrieving name of</secondary></indexterm>
<indexterm><primary>source</primary>
<secondary>of program and retrieval of information</secondary></indexterm>
</term>
<listitem><para>parses data describing the source of the program running.
The language processor returns a string that does not change while the
program is running.</para>
<para>The source string contains operating system name,
followed by either <computeroutput>COMMAND</computeroutput>,
<computeroutput>FUNCTION</computeroutput>,
<computeroutput>SUBROUTINE</computeroutput>, or
<computeroutput>METHOD</computeroutput>, depending on
whether the program was called as a host command or from a function call in
an expression or using the CALL instruction or as a method of an object. These
two tokens are followed by the complete path specification of the program
file.</para>
<para>The string parsed might, therefore, look like this:</para>
<programlisting>
WindowsNT COMMAND C:\MYDIR\RexxTRY.CMD
</programlisting>
<para>or</para>
<programlisting>
LINUX COMMAND /opt/orexx/bin/rexxtry.cmd
</programlisting>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">PARSE VALUE</emphasis>
<indexterm><primary>VALUE option of PARSE instruction</primary></indexterm>
<indexterm><primary>expressions</primary>
<secondary>parsing of</secondary></indexterm>
</term>
<listitem><para>parses the data, a character string, that is the result of
evaluating <emphasis role="italic">expression</emphasis>.
If you specify no <emphasis role="italic">expression</emphasis>, the null string is
used. Note that WITH is a subkeyword in this context and cannot be used as
a symbol within <emphasis role="italic">expression</emphasis>.</para>
<para>Thus, for example: </para>
<indexterm><primary>PARSE instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>PARSE instruction</secondary></indexterm>
<programlisting>
PARSE VALUE time() WITH hours ":" mins ":" secs
</programlisting>
<para>gets the current time and splits it into its constituent parts.</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">PARSE VAR</emphasis>
<emphasis role="italic">name</emphasis>
<indexterm><primary>VAR option of PARSE instruction</primary></indexterm>
<indexterm><primary>variable</primary>
<secondary>parsing of</secondary></indexterm>
</term>
<listitem><para>parses the character string value of the variable
<emphasis role="italic">name</emphasis>. The
<emphasis role="italic">name</emphasis> must be a symbol
that is valid as a variable name, which means it
cannot start with a period or a digit. Note that the variable
<emphasis role="italic">name</emphasis> is
not changed unless it appears in the template, so that, for example:</para>
<programlisting>
PARSE VAR string word1 string
</programlisting>
<para>removes the first word from <emphasis role="italic">string</emphasis>,
puts it in the variable <emphasis role="italic">word1</emphasis>,
and assigns the remainder back to
<emphasis role="italic">string</emphasis>. </para>
<programlisting>
PARSE UPPER VAR string word1 string
</programlisting>
<para>also translates the data from <emphasis role="italic">string</emphasis>
to uppercase before it is parsed.</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">PARSE VERSION</emphasis>
<indexterm><primary>VERSION option of PARSE instruction</primary></indexterm>
<indexterm><primary>date and version of the language processor</primary>
</indexterm>
<indexterm><primary>language</primary>
<secondary>processor date and version</secondary></indexterm>
</term>
<listitem><para>parses information describing the language level and the date
of the language processor. This information consists of five blank-delimited
words:
<itemizedlist>
<listitem><para>The string <computeroutput>REXX-ooRexx_4.2.0(MT)_32-bit</computeroutput>,
if using the ooRexx interpreter at version 4, release 2, modification 0, and
compiled for 32-bit addressing mode.</para></listitem>
</listitem>
<listitem><para>The language level description, for example
<computeroutput>6.03</computeroutput>.</para></listitem>
<listitem><para>Three tokens that describe the language processor release
date in the same format as the default for the DATE built-in function
(see <xref linkend="bifDate" />),
for example, &quot;27 Sep 2007&quot;.</para></listitem></itemizedlist>
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="keyProcedure"><title>PROCEDURE</title>
<indexterm><primary>PROCEDURE instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>functions</primary>
<secondary>variables in</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>PROCEDURE</secondary></indexterm>
<indexterm><primary>internal</primary>
<secondary>functions</secondary>
<tertiary>variables in</tertiary></indexterm>
<indexterm><primary>protecting variables</primary></indexterm>
<indexterm><primary>subroutines</primary>
<secondary>variables in</secondary></indexterm>
<indexterm><primary>variable</primary>
<secondary>exposing to caller</secondary></indexterm>
<indexterm><primary>variable</primary>
<secondary>in internal functions</secondary></indexterm>
<indexterm><primary>variable</primary>
<secondary>in subroutines</secondary></indexterm>
<indexterm><primary>variable</primary>
<secondary>new level of</secondary></indexterm>
<indexterm><primary>EXPOSE subkeyword</primary>
<secondary>in a PROCEDURE instruction</secondary></indexterm>
<programlisting>
<![CDATA[
>>-PROCEDURE--+------------------------+--;--------------------><
| +------------+ |
| V | |
+-EXPOSE----+-name---+-+-+
+-(name)-+
]]>
</programlisting>
<para>PROCEDURE, within an internal
routine (subroutine or function), protects the caller's variables by making
them unknown to the instructions that follow it. After a RETURN instruction
is processed, the original variable environment is restored and any variables
used in the routine (that were not exposed) are dropped. (An exposed variable
is one belonging the caller of a routine that the PROCEDURE instruction has
exposed. When the routine refers to, or alters, the variable, the original
(caller's) copy of the variable is used.) An internal routine need not
include a PROCEDURE instruction. In this case the variables it is manipulating
are those the caller owns. If the PROCEDURE instruction is used, it must be
the first instruction processed after the CALL or function invocation; that
is, it must be the first instruction following the label.</para>
<indexterm><primary>EXPOSE option of PROCEDURE instruction</primary></indexterm>
<indexterm><primary>exposed variable</primary></indexterm>
<para>If you use the EXPOSE option, any variable specified by the
<emphasis role="italic">name</emphasis> is
exposed. Any reference to it (including setting and dropping) is made to
the variables environment the caller owns. Hence, the values of existing
variables are accessible, and any changes are persistent even on RETURN from
the routine. If the <emphasis role="italic">name</emphasis> is not enclosed
in parentheses, it identifies a variable
you want to expose and must be a symbol that is a valid variable name, separated
from any other <emphasis role="italic">name</emphasis> with one or more
whitespace characters.
</para>
<para>If parentheses enclose a single <emphasis role="italic">name</emphasis>,
then, after the variable <emphasis role="italic">name</emphasis> is exposed,
the character string value of <emphasis role="italic">name</emphasis> is
immediately used as a subsidiary list of variables. Whitespace characters are
not necessary inside or outside the parentheses, but you can add them if
desired.
<indexterm><primary>subsidiary list</primary></indexterm>
This subsidiary list must follow the same rules
as the original list, that is, valid variable names separated by whitespace
characters, except that no parentheses are allowed.
</para>
<para>Variables are exposed from left to right. It is not an error to specify
a name more than once, or to specify a name that the caller has not used as
a variable.</para>
<para>Any variables in the main program that are not exposed are still protected.
Therefore, some of the caller's variables can be made accessible and can
be changed, or new variables can be created. All these changes are visible
to the caller upon RETURN from the routine.</para>
<indexterm><primary>PROCEDURE instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>PROCEDURE instruction</secondary></indexterm>
<example>
<title>Instructions - PROCEDURE</title>
<programlisting>
/* This is the main Rexx program */
j=1; z.1="a"
call toft
say j k m /* Displays "1 7 M" */
exit
/* This is a subroutine */
toft: procedure expose j k z.j
say j k z.j /* Displays "1 K a" */
k=7; m=3 /* Note: M is not exposed */
return
</programlisting>
</example>
<para>Note that if <computeroutput>Z.J</computeroutput> in the
EXPOSE list is placed before <computeroutput>J</computeroutput>,
the caller's value of <computeroutput>J</computeroutput> is not visible,
so <computeroutput>Z.1</computeroutput> is not exposed.</para>
<para>The variables in a subsidiary list are also exposed from left to right.
</para>
<example>
<title>Instructions - PROCEDURE</title>
<programlisting>
/* This is the main Rexx program */
j=1;k=6;m=9
a ="j k m"
call test
exit
/* This is a subroutine */
test: procedure expose (a) /* Exposes A, J, K, and M */
say a j k m /* Displays "j k m 1 6 9" */
return
</programlisting>
</example>
<para>You can use subsidiary lists to more easily expose a number of variables
at a time or, with the VALUE built-in function, to manipulate dynamically
named variables.</para>
<example>
<title>Instructions - PROCEDURE</title>
<programlisting>
/* This is the main Rexx program */
c=11; d=12; e=13
Showlist="c d" /* but not E */
call Playvars
say c d e f /* Displays "11 New 13 9" */
exit
/* This is a subroutine */
Playvars: procedure expose (showlist) f
say word(showlist,2) /* Displays "d" */
say value(word(showlist,2),"New") /* Displays "12" and sets new value */
say value(word(showlist,2)) /* Displays "New" */
e=8 /* E is not exposed */
f=9 /* F was explicitly exposed */
return
</programlisting>
</example>
<indexterm><primary>stem of a variable</primary>
<secondary>used in PROCEDURE instruction</secondary></indexterm>
<para>Specifying a stem as <emphasis role="italic">name</emphasis>
exposes this stem and all possible compound
variables whose names begin with that stem. (See .)</para>
<example>
<title>Instructions - PROCEDURE</title>
<programlisting>
/* This is the main Rexx program */
a.=11; i=13; j=15
i = i + 1
C.5 = "FRED"
call lucky7
say a. a.1 i j c. c.5
say "You should see 11 7 14 15 C. FRED"
exit
lucky7:Procedure Expose i j a. c.
/* This exposes I, J, and all variables whose */
/* names start with A. or C. */
A.1="7" /* This sets A.1 in the caller-&apos;s */
/* environment, even if it did not */
/* previously exist. */
return
</programlisting>
</example>
<note><title>Note</title>
<para>Variables can be exposed through several generations
of routines if they are included in all intermediate PROCEDURE instructions.
</para></note>
<para>See the CALL instruction and function descriptions in
<xref linkend="keyCall" /> and <xref linkend="funct" />
for details and examples of how routines are called.</para>
</section>
<section id="keyPull"><title>PULL</title>
<indexterm><primary>PULL instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>console</primary>
<secondary>reading from with PULL</secondary></indexterm>
<indexterm><primary>external data queue</primary>
<secondary>reading from with PULL</secondary></indexterm>
<indexterm><primary>input to PULL from STDIN</primary></indexterm>
<indexterm><primary>input to PULL from the keyboard</primary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>PULL</secondary></indexterm>
<indexterm><primary>parsing</primary>
<secondary>templates</secondary>
<tertiary>in PULL instruction</tertiary></indexterm>
<indexterm><primary>template</primary>
<secondary>list</secondary>
<tertiary>PULL instruction</tertiary></indexterm>
<indexterm><primary>terminal</primary>
<secondary>reading from with PULL</secondary></indexterm>
<indexterm><primary>UPPER subkeyword</primary>
<secondary>in an PARSE instruction</secondary></indexterm>
<indexterm><primary>PULL subkeyword</primary>
<secondary>in an PARSE instruction</secondary></indexterm>
<programlisting>
<![CDATA[
>>-PULL--+---------------+--;----------------------------------><
+-template_list-+
]]>
</programlisting>
<para>PULL reads a string from the head of the external data queue or, if
the external data queue is empty, from the standard input stream (typically the keyboard).
(See <xref linkend="iostrms" /> for a
discussion of Rexx input and output.) It is a short
form of the following instruction:</para>
<indexterm><primary>uppercase translation</primary>
<secondary>during PULL instruction</secondary></indexterm>
<programlisting>
<![CDATA[
>>-PARSE UPPER PULL--+---------------+--;----------------------><
+-template_list-+
]]>
</programlisting>
<para>The current head
of the queue is read as one string. Without a
<emphasis role="italic">template_list</emphasis> specified,
no further action is taken and the string is thus effectively discarded.
The <emphasis role="italic">template_list</emphasis> can be a single
template or list of templates separated
by commas, but PULL parses only one source string. Each template consists
of one or more symbols separated by whitespace, patterns, or both.</para>
<para>If you specify several comma-separated templates, variables in templates
other than the first one are assigned the null string. The string is translated
to uppercase (that is, lowercase
<computeroutput>a</computeroutput>-<computeroutput>z</computeroutput>
to uppercase
<computeroutput>A</computeroutput>-<computeroutput>Z</computeroutput>)
and then parsed into variables according to the
rules described in <xref linkend="parsingch" />. Use the PARSE PULL
instruction if you do not desire uppercase translation. </para>
<note><title>Note</title>
<para>If the current
data queue is empty, PULL reads from the standard input (typically, the
keyboard). If there is a PULL from the standard input, the program waits for
keyboard input with no prompt.
</para></note>
<para><emphasis role="bold">Example:</emphasis></para>
<indexterm><primary>PULL instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>PULL instruction</secondary></indexterm>
<programlisting>
Say "Do you want to erase the file? Answer Yes or No:"
Pull answer .
if answer="NO" then say "The file will not be erased."
</programlisting>
<para>Here the dummy placeholder, a period
(<computeroutput>.</computeroutput>), is used in the template
to isolate the first word the user enters.</para>
<para>If the external data queue is empty, a line is read from the default input
stream and the program pauses, if necessary, until a line is complete. (This
is as though PARSE UPPER LINEIN had been processed.
See <xref linkend="parlini" />.)</para>
<para>The QUEUED built-in function (see
<xref linkend="bifQueued" />) returns the
number of lines currently in the external data queue.</para>
</section>
<section id="keyPush"><title>PUSH</title>
<indexterm><primary>PUSH instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>external data queue</primary>
<secondary>writing to with PUSH</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>PUSH</secondary></indexterm>
<indexterm><primary>LIFO (last-in, first-out) stacking</primary></indexterm>
<indexterm><primary>writing to external data queue</primary>
<secondary>with PUSH</secondary></indexterm>
<programlisting>
<![CDATA[
>>-PUSH--+------------+--;-------------------------------------><
+-expression-+
]]>
</programlisting>
<para>PUSH stacks the string resulting from the evaluation of
<emphasis role="italic">expression</emphasis> LIFO (Last In, First Out)
into the external data queue. (See
<xref linkend="iostrms" /> for
a discussion of Rexx input and output.)</para>
<para>If you do not specify <emphasis role="italic">expression</emphasis>,
a null string is stacked.</para>
<indexterm><primary>PUSH instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>PUSH instruction</secondary></indexterm>
<example>
<title>Instructions - PUSH</title>
<programlisting>
a="Fred"
push /* Puts a null line onto the queue */
push a 2 /* Puts "Fred 2" onto the queue */
</programlisting>
</example>
<para> The QUEUED built-in
function (described in <xref linkend="bifQueued" />) returns the number
of lines currently in the external data queue.</para>
</section>
<section id="keyQueue"><title>QUEUE</title>
<indexterm><primary>QUEUE instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>external data queue</primary>
<secondary>writing to with QUEUE</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>QUEUE</secondary></indexterm>
<indexterm><primary>writing to external data queue</primary>
<secondary>with QUEUE</secondary></indexterm>
<programlisting>
<![CDATA[
>>-QUEUE--+------------+--;------------------------------------><
+-expression-+
]]>
</programlisting>
<para>QUEUE appends the string resulting from
<emphasis role="italic">expression</emphasis> to the tail
of the external data queue. That is, it is added FIFO (First In, First Out).
<indexterm><primary>FIFO (first-in/first-out) stacking</primary></indexterm>
(See <xref linkend="iostrms" />
for a discussion of Rexx input and output.)</para>
<para>If you do not specify <emphasis role="italic">expression</emphasis>,
a null string is queued.</para>
<indexterm><primary>QUEUE instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>QUEUE instruction</secondary></indexterm>
<example>
<title>Instructions - QUEUE</title>
<programlisting>
a="Toft"
queue a 2 /* Enqueues "Toft 2" */
queue /* Enqueues a null line behind the last */
</programlisting>
</example>
<para> The QUEUED built-in
function (described in <xref linkend="bifQueued" />) returns the number
of lines currently in the external data queue.</para>
</section>
<section id="keyRaise"><title>RAISE</title>
<indexterm><primary>RAISE instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>conditions</primary>
<secondary>raising of</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>RAISE</secondary></indexterm>
<indexterm><primary>ERROR subkeyword</primary>
<secondary>in a RAISE instruction</secondary></indexterm>
<indexterm><primary>FAILURE subkeyword</primary>
<secondary>in a RAISE instruction</secondary></indexterm>
<indexterm><primary>SYNTAX subkeyword</primary>
<secondary>in a RAISE instruction</secondary></indexterm>
<indexterm><primary>USER subkeyword</primary>
<secondary>in a RAISE instruction</secondary></indexterm>
<indexterm><primary>PROPAGATE subkeyword</primary>
<secondary>in a RAISE instruction</secondary></indexterm>
<indexterm><primary>ADDITIONAL subkeyword</primary>
<secondary>in a RAISE instruction</secondary></indexterm>
<indexterm><primary>DESCRIPTION subkeyword</primary>
<secondary>in a RAISE instruction</secondary></indexterm>
<indexterm><primary>ARRAY subkeyword</primary>
<secondary>in a RAISE instruction</secondary></indexterm>
<indexterm><primary>EXIT subkeyword</primary>
<secondary>in a RAISE instruction</secondary></indexterm>
<indexterm><primary>RETURN subkeyword</primary>
<secondary>in a RAISE instruction</secondary></indexterm>
<programlisting>
<![CDATA[
>>-RAISE--+-condition------------+--+-------------+--;---------><
+-ERROR--errorcode-----+ +-| options |-+
+-FAILURE--failurecode-+
+-SYNTAX--number-------+
+-USER--usercondition--+
+-PROPAGATE------------+
]]>
</programlisting>
<para><emphasis role="bold">options:</emphasis></para>
<programlisting>
<![CDATA[
|--+------------------------+--+--------------------+----------->
+-ADDITIONAL--expra------+ +-DESCRIPTION--exprd-+
| +-,-----+ |
| V | |
+-ARRAY--(----expri-+--)-+
+-| EXIT |----------+
>--+-------------------+----------------------------------------|
+-RETURN--+-------+-+
+-exprr-+
]]>
</programlisting>
<para><emphasis role="bold">EXIT:</emphasis></para>
<programlisting>
<![CDATA[
|--EXIT--+-------+----------------------------------------------|
+-expre-+
]]>
</programlisting>
<note><title>Note</title>
<para>You can specify the options ADDITIONAL, ARRAY, DESCRIPTION,
RETURN, and EXIT in any order. However, if you specify EXIT without
<emphasis role="italic">expre</emphasis> or RETURN without
<emphasis role="italic">exprr</emphasis>, it must appear last.</para></note>
<para>RAISE returns or exits from the currently running routine or method and
raises a condition in the caller (for a routine) or sender (for a method).
See <xref linkend="condtra" />
for details of the actions taken when conditions
are raised. The RAISE instruction can raise all conditions that can be trapped.
</para>
<para>If you specify <emphasis role="italic">condition</emphasis>,
it is a single symbol that is taken as a constant.</para>
<para>If the ERROR or FAILURE condition is raised, you must supply the
associated return code as <emphasis role="italic">errorcode</emphasis> or
<emphasis role="italic">failurecode</emphasis>, respectively. These
can be literal strings, constant symbols, or expressions enclosed in parentheses.
If you specify an expression enclosed in parentheses, a subexpression, the
language processor evaluates the expression to obtain its character string
value.</para>
<para>If the SYNTAX condition is raised, you must supply the associated Rexx
error number as <emphasis role="italic">number</emphasis>. This error
<emphasis role="italic">number</emphasis> can be either
a Rexx major error code or a Rexx detailed error code in the form
<emphasis role="italic">nn.nnn</emphasis>. The
<emphasis role="italic">number</emphasis> can be a literal string, a constant
symbol, or an expression enclosed in parentheses. If you specify an
expression enclosed in parentheses, the language processor evaluates the
expression to obtain its character string value.</para>
<para>If a USER condition is raised, you must supply the associated user
condition name as <emphasis role="italic">usercondition</emphasis>.
This can be a literal string or a symbol that is taken as a constant.</para>
<para>If you specify the ADDITIONAL option, the language processor evaluates
<emphasis role="italic">expra</emphasis> to produce an object that supplies
additional object information associated with the condition. The
<emphasis role="italic">expra</emphasis> can be a literal string,
constant symbol, or expression enclosed in parentheses. The ADDITIONAL entry
of the condition object and the
<computeroutput>&quot;A&quot;</computeroutput> option of the CONDITION
built-in function return this additional object information. For SYNTAX conditions,
the ADDITIONAL value must evaluate to a single-dimension Rexx array object.</para>
<para>If you specify the ARRAY option, each
<emphasis role="italic">expri</emphasis> is an expression (use
commas to separate the expressions). The language processor evaluates the
expression list to produce an array object that supplies additional object
information associated with the condition. The ADDITIONAL entry of the condition
object and the <computeroutput>&quot;A&quot;</computeroutput> option of
the CONDITION built-in function
return this additional object information as an array of values. It is an
error to use both the ARRAY option and the ADDITIONAL option on the same RAISE
instruction.</para>
<para>The content of <emphasis role="italic">expra</emphasis> or
<emphasis role="italic">expri</emphasis> is used as the contents
of the secondary error message produced for a
<emphasis role="italic">condition</emphasis>.</para>
<para>If you specify neither ADDITIONAL nor ARRAY, there is no additional object
information associated with the condition.</para>
<para>If you specify the DESCRIPTION option, the
<emphasis role="italic">exprd</emphasis> can be a literal
string, a constant symbol, or an expression enclosed in parentheses. If you
specify an expression enclosed in parentheses, the language processor evaluates
the expression to obtain its character string value. This is the description
associated with the condition. The
<computeroutput>&quot;D&quot;</computeroutput> option of the CONDITION
built-in function and the DESCRIPTION entry of the condition object return
this string.</para>
<para>If you do not specify DESCRIPTION, the language processor uses a null
string as the descriptive string.</para>
<para>If you specify the RETURN or EXIT option, the language processor evaluates
the expression <emphasis role="italic">exprr</emphasis> or
<emphasis role="italic">expre</emphasis>, respectively, to produce
a result object that is passed back to the caller or sender as if it were
a RETURN or EXIT result. The <emphasis role="italic">expre</emphasis> or
<emphasis role="italic">exprr</emphasis> is a literal
string, constant symbol, or expression enclosed in parentheses. If you specify
an expression enclosed in parentheses, the language processor evaluates the
expression to obtain its character string value. If you do not specify
<emphasis role="italic">exprr</emphasis> or
<emphasis role="italic">expre</emphasis>, no result is passed back to the
caller or sender. In either case, the effect is the same as that of the
RETURN or EXIT instruction (see <xref linkend="keyReturn" />).
Following the return or exit, the appropriate action is taken in the caller
or sender (see
<xref linkend="atwcnt" />).
If specified, the result value can be obtained from the RESULT entry of the
condition object.</para>
<indexterm><primary>RAISE instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>RAISE instruction</secondary></indexterm>
<example>
<title>Instructions - RAISE</title>
<programlisting>
raise syntax 40 /* Raises syntax error 40 */
raise syntax 40.12 array (1, number) /* Raises syntax error 40, subcode 12 */
/* Passing two substitution values */
raise syntax (errnum) /* Uses the value of the variable ERRNUM */
/* as the syntax error number */
raise user badvalue /* Raises user condition BADVALUE */
</programlisting>
</example>
<para>If you specify PROPAGATE, and there is a currently trapped condition, this
condition is raised again in the caller (for a routine) or sender (for a method).
Any ADDITIONAL, DESCRIPTION, ARRAY, RETURN, or EXIT information specified
on the RAISE instruction replaces the corresponding values for the currently
trapped condition. A SYNTAX error occurs if no condition is currently trapped.
</para>
<example>
<title>Instructions - RAISE</title>
<programlisting>
signal on syntax
a = "xyz"
c = a+2 /* Raises the SYNTAX condition */
.
.
.
exit
syntax:
raise propagate /* Propagates SYNTAX information to caller */
</programlisting>
</example>
</section>
<section id="keyReply"><title>REPLY</title>
<indexterm><primary>REPLY instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>early reply</primary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>REPLY</secondary></indexterm>
<programlisting>
<![CDATA[
>>-REPLY--+------------+--;------------------------------------><
+-expression-+
]]>
</programlisting>
<para>REPLY sends an early
reply from a method to its caller. The method issuing REPLY returns control,
and possibly a result, to its caller to the point from which the message was
sent; meanwhile, the method issuing REPLY continues running on a newly created thread.</para>
<para>If you specify <emphasis role="italic">expression</emphasis>,
it is evaluated and the object resulting from the evaluation is passed back.
If you omit <emphasis role="italic">expression</emphasis>, no object
is passed back.</para>
<para>Unlike RETURN or EXIT, the method issuing REPLY continues to run after
the REPLY until it issues an EXIT or RETURN instruction. The EXIT or RETURN
must not specify a result expression.</para>
<indexterm><primary>REPLY instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>REPLY instruction</secondary></indexterm>
<example>
<title>Instructions - REPLY</title>
<programlisting>
reply 42 /* Returns control and a result */
call tidyup /* Can run in parallel with sender */
return
</programlisting>
</example>
<para><emphasis role="bold">Notes:</emphasis></para>
<orderedlist>
<listitem><para>You can use REPLY only in a method.</para></listitem>
<listitem><para>A method can execute only one REPLY instruction.</para>
</listitem>
<listitem><para>When the method issuing the REPLY instruction is the only
active method on the
current thread with exclusive access to the object's variable pool,
the method retains exclusive access on the new thread. When other methods
on the thread also have access, the method issuing the REPLY releases its access
and reacquires the access on the new thread. This might force the method
to wait until the original activity has released its access.</para></listitem>
</orderedlist>
<para>See <xref linkend="xconcur" /> for a complete
description of concurrency.</para>
</section>
<section id="keyReturn"><title>RETURN</title>
<indexterm><primary>RETURN instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>functions</primary>
<secondary>return from</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>RETURN</secondary></indexterm>
<indexterm><primary>internal</primary>
<secondary>functions</secondary>
<tertiary>return from</tertiary></indexterm>
<indexterm><primary>returning control from Rexx program</primary></indexterm>
<indexterm><primary>running off the end of a program</primary></indexterm>
<indexterm><primary>subroutines</primary>
<secondary>return from</secondary></indexterm>
<indexterm><primary>subroutines</primary>
<secondary>passing back values from</secondary></indexterm>
<programlisting>
<![CDATA[
>>-RETURN--+------------+--;-----------------------------------><
+-expression-+
]]>
</programlisting>
<para>RETURN returns control, and possibly a result, from a Rexx program,
method, or routine to the point of its invocation.</para>
<para>If no internal routine (subroutine or function) is active, RETURN and EXIT
are identical in their effect on the program that is run.
(See <xref linkend="keyExit" />.)</para>
<para>If called as a routine, <emphasis role="italic">expression</emphasis>
(if any) is evaluated, control is passed back to the caller, and the Rexx
special variable
<indexterm><primary>RESULT special variable</primary>
<secondary>set by RETURN instruction</secondary></indexterm>
RESULT is set to the value of <emphasis role="italic">expression</emphasis>.
If you omit <emphasis role="italic">expression</emphasis>,
the special variable RESULT is dropped (becomes uninitialized). The
various settings saved at the time of the CALL (for example, tracing and
addresses) are also restored. (See <xref linkend="keyCall" />.)</para>
<para>If a function call is active, the action taken is identical, except that
<emphasis role="italic">expression</emphasis> must be specified on the
RETURN instruction. The result of <emphasis role="italic">expression</emphasis>
is then used in the original expression at the point where the function
was called. See the description of functions in
<xref linkend="funct" /> for more details.</para>
<para>If a method is processed, the language processor evaluates
<emphasis role="italic">expression</emphasis> (if any) and returns control to
the point from which the method's activating message was sent.
If called as a term of an expression,
<emphasis role="italic">expression</emphasis> is required. If called as a
message instruction, <emphasis role="italic">expression</emphasis> is
optional and is assigned to the Rexx special variable
<indexterm><primary>special</primary>
<secondary>variable</secondary>
<tertiary>RESULT</tertiary></indexterm>
<indexterm><primary>special</primary>
<secondary>variables</secondary>
<tertiary>RESULT</tertiary></indexterm>
RESULT if a return <emphasis role="italic">expression</emphasis> is specified.
If the method has previously issued a REPLY instruction, the RETURN instruction
must not include a result <emphasis role="italic">expression</emphasis>.</para>
<para>If a PROCEDURE instruction was processed within an internal subroutine
or internal function, all variables of the current generation are dropped
(and those of the previous generation are exposed) after
<emphasis role="italic">expression</emphasis> is
evaluated and before the result is used or assigned to RESULT.</para>
<note><para>If the RETURN statement causes the program to return to the operating
system on a Unix/Linux system the value returned is limited to a numerical
value between 0 and 255 (an unsigned byte). If no
<emphasis role="italic">expression</emphasis> is supplied then the default value
returned to the operating system is zero.
</para></note>
</section>
<section id="keySay"><title>SAY</title>
<indexterm><primary>SAY instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>SAY instruction</primary>
<secondary>displaying data</secondary></indexterm>
<indexterm><primary>console</primary>
<secondary>writing to with SAY</secondary></indexterm>
<indexterm><primary>continuation</primary>
<secondary>of data for display</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>SAY</secondary></indexterm>
<indexterm><primary>terminal</primary>
<secondary>writing to with SAY</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SAY--+------------+--;--------------------------------------><
+-expression-+
]]>
</programlisting>
<para>SAY writes a line to the default output stream, which displays it to the
user. However, the output destination can depend on the implementation. See
<xref linkend="iostrms" /> for a discussion of
Rexx input and output. The string value of the
<emphasis role="italic">expression</emphasis> result is written to the default
character output stream. The resulting string can be of any length. If
you omit <emphasis role="italic">expression</emphasis>,
the null string is written.</para>
<para>The SAY instruction is a shorter form of the following instruction:</para>
<programlisting>
<![CDATA[
>>-CALL LINEOUT,--+------------+--;----------------------------><
+-expression-+
]]>
</programlisting>
<para>except that:</para>
<itemizedlist>
<listitem><para>SAY does not affect the special variable RESULT.</para>
</listitem>
<listitem><para>If you use SAY and omit
<emphasis role="italic">expression</emphasis>, a null string is used.</para>
</listitem>
<listitem><para>CALL LINEOUT can raise NOTREADY; SAY will not.</para></listitem>
</itemizedlist>
<para>See <xref linkend="bifLineout" />
for details of the LINEOUT function.</para>
<indexterm><primary>SAY instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SAY instruction</secondary></indexterm>
<example>
<title>Instructions - SAY</title>
<programlisting>
<![CDATA[
data=100
Say data "divided by 4 =>" data/4
/* Displays: "100 divided by 4 => 25" */
]]>
</programlisting>
</example>
<para><emphasis role="bold">Notes:</emphasis></para>
<orderedlist>
<listitem><para>Data from the SAY instruction is sent to the default output
stream (.OUTPUT). However, the standard rules for redirecting output apply
to the SAY output.
</para></listitem>
<listitem><para>The SAY instruction does not format data; the operating system
and the hardware handle line wrapping. However, formatting is accomplished,
the output data remains a single logical line.</para></listitem>
</orderedlist>
</section>
<section id="keySelect"><title>SELECT</title>
<indexterm><primary>SELECT instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>flow of control</primary>
<secondary>with SELECT construct</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>SELECT</secondary></indexterm>
<indexterm><primary>THEN</primary>
<secondary>following WHEN clause</secondary></indexterm>
<indexterm><primary>WHEN subkeyword</primary>
<secondary>in a SELECT instruction</secondary></indexterm>
<indexterm><primary>THEN subkeyword</primary>
<secondary>in a SELECT instruction</secondary></indexterm>
<indexterm><primary>OTHERWISE subkeyword</primary>
<secondary>in a SELECT instruction</secondary></indexterm>
<indexterm><primary>END subkeyword</primary>
<secondary>in a SELECT instruction</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SELECT--+-------------+-;------------------------------------->
+-LABEL--name-+
+------------------------------------------------------+
V |
>----WHEN--expression--+---+--THEN--+---+--instruction--;-+------>
+-;-+ +-;-+
>-+------------------------------------------+-END-+--------+-;-><
+-OTHERWISE--+---+--+--------------------+-+ +--name--+
+-;-+ | +----------------+ |
| V | |
+---instruction--;-+-+
]]>
</programlisting>
<para>SELECT conditionally calls one of several alternative instructions.</para>
<para>Each <emphasis role="italic">expression</emphasis>
after a WHEN is evaluated in turn and must result
in <computeroutput>0</computeroutput> or <computeroutput>1</computeroutput>.
If the result is <computeroutput>1</computeroutput>, the instruction
following the associated THEN (which can be a complex instruction such as
IF, DO, LOOP, or SELECT) is processed and control is then passed to the END. If
the result is <computeroutput>0</computeroutput>, control is passed to the
next WHEN clause.</para>
<para>If none of the WHEN expressions evaluates to
<computeroutput>1</computeroutput>, control is passed
to the instructions, if any, after OTHERWISE. In this situation, the absence
of an OTHERWISE produces an error, however, you can omit the instruction list
that follows OTHERWISE.</para>
<indexterm><primary>SELECT instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SELECT instruction</secondary></indexterm>
<example>
<title>Instructions - SELECT</title>
<programlisting>
<![CDATA[
balance=100
check=50
balance = balance - check
Select
when balance > 0 then
say "Congratulations! You still have" balance "dollars left."
when balance = 0 then do
say "Warning, Balance is now zero! STOP all spending."
say "You cut it close this month! Hope you do not have any"
say "checks left outstanding."
end
Otherwise do
say "You have just overdrawn your account."
say "Your balance now shows" balance "dollars."
say "Oops! Hope the bank does not close your account."
end
end /* Select */
]]>
/</programlisting>
</example>
<para>The <emphasis role="italic">expression</emphasis> may also be
a list of expressions separated by ",". Each subexpression must evaluate to
either <computeroutput>0</computeroutput> or <computeroutput>1</computeroutput>.
The list of expressions is evaluated left-to-right. Evaluation will stop with
the first <computeroutput>0</computeroutput> result and <computeroutput>0</computeroutput>
will be returned as the condition result. If all of the subexpressions evaluate
to <computeroutput>1</computeroutput>, then the condition result is also
<computeroutput>1</computeroutput>.</para>
<example>
<title>Instructions - SELECT</title>
<programlisting>
select
when answer~datatype('w'), answer//2 = 0 Then
say answer "is even"
when answer~datatype('w'), answer//2 = 1 Then
say answer "is odd"
otherwise
say answer "is not a number"
end
</programlisting>
<para>The example above is not the same as using the following</para>
<programlisting>
select
when answer~datatype('w') &amp; answer//2 = 0 Then
say answer "is even"
when answer~datatype('w') &amp; answer//2 = 1 Then
say answer "is odd"
otherwise
say answer "is not a number"
end
</programlisting>
</example>
<para>The logical &amp; operator will evaluate both terms of the operation, so the
term "answer//2" will result in a syntax error if answer is a non-numeric value. With the
list conditional form, evaluation will stop with the first false result, so the
"answer//2" term will not be evaluated if the datatype test returns
<computeroutput>0</computeroutput> (.false).
</para>
<para><emphasis role="bold">Notes:</emphasis></para>
<orderedlist>
<listitem><para>The <emphasis role="italic">instruction</emphasis>
can be any assignment, command, message instruction,
or keyword instruction, including any of the more complex constructs, such
as DO, LOOP, IF, or the SELECT instruction itself.</para></listitem>
<listitem><para>A null clause is not an instruction, so putting an extra
semicolon (or
label) after a THEN clause is not equivalent to putting a dummy instruction.
The NOP instruction is provided for this purpose.</para></listitem>
<listitem><para>The symbol THEN cannot be used within
<emphasis role="italic">expression</emphasis>, because the
keyword THEN is treated differently in that it need not start a clause. This
allows the expression on the WHEN clause to be ended by the THEN without a
semicolon (;).</para></listitem>
</orderedlist>
</section>
<section id="keySignal"><title>SIGNAL</title>
<indexterm><primary>SIGNAL instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>SIGNAL</secondary></indexterm>
<indexterm><primary>label</primary>
<secondary>as target of SIGNAL</secondary></indexterm>
<indexterm><primary>label</primary>
<secondary>search algorithm</secondary></indexterm>
<indexterm><primary>VALUE subkeyword</primary>
<secondary>in a SIGNAL instruction</secondary></indexterm>
<indexterm><primary>OFF subkeyword</primary>
<secondary>in a SIGNAL instruction</secondary></indexterm>
<indexterm><primary>ON subkeyword</primary>
<secondary>in a SIGNAL instruction</secondary></indexterm>
<indexterm><primary>ANY subkeyword</primary>
<secondary>in a SIGNAL instruction</secondary></indexterm>
<indexterm><primary>ERROR subkeyword</primary>
<secondary>in a SIGNAL instruction</secondary></indexterm>
<indexterm><primary>FAILURE subkeyword</primary>
<secondary>in a SIGNAL instruction</secondary></indexterm>
<indexterm><primary>HALT subkeyword</primary>
<secondary>in a SIGNAL instruction</secondary></indexterm>
<indexterm><primary>LOSTDIGITS subkeyword</primary>
<secondary>in a SIGNAL instruction</secondary></indexterm>
<indexterm><primary>NOMETHOD subkeyword</primary>
<secondary>in a SIGNAL instruction</secondary></indexterm>
<indexterm><primary>NOSTRING subkeyword</primary>
<secondary>in a SIGNAL instruction</secondary></indexterm>
<indexterm><primary>NOTREADY subkeyword</primary>
<secondary>in a SIGNAL instruction</secondary></indexterm>
<indexterm><primary>NOVALUE subkeyword</primary>
<secondary>in a SIGNAL instruction</secondary></indexterm>
<indexterm><primary>SYNTAX subkeyword</primary>
<secondary>in a SIGNAL instruction</secondary></indexterm>
<indexterm><primary>USER subkeyword</primary>
<secondary>in a SIGNAL instruction</secondary></indexterm>
<indexterm><primary>NAME subkeyword</primary>
<secondary>in a SIGNAL instruction</secondary></indexterm>
<programlisting>
<![CDATA[
>>-SIGNAL------------------------------------------------------->
>--+-labelname---------------------------------------+--;------><
+-+-------+--expression---------------------------+
| +-VALUE-+ |
+-OFF--+-ANY-----------------+--------------------+
| +-ERROR---------------+ |
| +-FAILURE-------------+ |
| +-HALT----------------+ |
| +-LOSTDIGITS----------+ |
| +-NOMETHOD------------+ |
| +-NOSTRING------------+ |
| +-NOTREADY------------+ |
| +-NOVALUE-------------+ |
| +-SYNTAX--------------+ |
| +-USER--usercondition-+ |
+-ON--+-ANY-----------------+--+----------------+-+
+-ERROR---------------+ +-NAME--trapname-+
+-FAILURE-------------+
+-HALT----------------+
+-LOSTDIGITS----------+
+-NOMETHOD------------+
+-NOSTRING------------+
+-NOTREADY------------+
+-NOVALUE-------------+
+-SYNTAX--------------+
+-USER--usercondition-+
]]>
</programlisting>
<para>SIGNAL causes an unusual change in the flow of control (if you specify
<emphasis role="italic">labelname</emphasis> or VALUE
<emphasis role="italic">expression</emphasis>), or controls the trapping of
certain conditions (if you specify ON or OFF).</para>
<para>To control trapping, you specify OFF or ON and the condition you want to
trap. OFF turns off the specified condition trap. ON turns on the specified
condition trap. All information on condition traps is contained in
<xref linkend="condtra" />.</para>
<para>To change the flow of control, a label
name is derived from <emphasis role="italic">labelname</emphasis> or taken
from the character string result of evaluating the
<emphasis role="italic">expression</emphasis> after VALUE. The
<emphasis role="italic">labelname</emphasis> you specify must be a literal
string or symbol that is taken as a constant. If you specify a symbol for
<emphasis role="italic">labelname</emphasis>, the search looks for a label
with uppercase characters. If you specify a literal string, the search uses
the literal string directly. You can locate label names with lowercase letters
only if you specify the label as a literal string with the same case. Similarly,
for SIGNAL VALUE, the lettercase of
<emphasis role="italic">labelname</emphasis> must match exactly.
You can omit the subkeyword VALUE if
<emphasis role="italic">expression</emphasis> does not begin with
a symbol or literal string, that is, if it starts with a special character,
such as an operator character or parenthesis. All active pending DO, IF, SELECT,
and INTERPRET instructions in the current routine are then ended and cannot
be resumed. Control is then passed to the first label in the program that
matches the given name, as though the search had started at the beginning
of the program.</para>
<para>The <emphasis role="italic">labelname</emphasis>
<indexterm><primary>label</primary>
<secondary>duplicate</secondary></indexterm>
and <emphasis role="italic">usercondition</emphasis> are single symbols, which
are taken as constants. The <emphasis role="italic">trapname</emphasis> is a
string or symbol taken as a constant.</para>
<indexterm><primary>SIGNAL instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>SIGNAL instruction</secondary></indexterm>
<example>
<title>Instructions - SIGNAL</title>
<programlisting>
Signal fred; /* Transfer control to label FRED below */
....
....
Fred: say "Hi!"
</programlisting>
</example>
<para>If there are duplicates,
control is always passed to the first occurrence of the label in the program.
</para>
<para>When control
reaches the specified label, the line number of the SIGNAL instruction is
assigned to the special variable
<indexterm><primary>SIGL</primary>
<secondary>in SIGNAL instruction</secondary></indexterm>
SIGL. This can aid debugging because you
can use SIGL to determine the source of a transfer of control to a label.</para>
</section>
<section id="keyTrace"><title>TRACE</title>
<indexterm><primary>TRACE instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>debug interactive</primary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>TRACE</secondary></indexterm>
<indexterm><primary>interactive debug</primary></indexterm>
<indexterm><primary>operations</primary>
<secondary>tracing results</secondary></indexterm>
<indexterm><primary>TRACE setting</primary>
<secondary>altering with TRACE instruction</secondary></indexterm>
<indexterm><primary>tracing</primary>
<secondary>execution of programs</secondary></indexterm>
<indexterm><primary>VALUE subkeyword</primary>
<secondary>in a TRACE instruction</secondary></indexterm>
<programlisting>
<![CDATA[
>>-TRACE--+-+--------+-----------------------+--;--------------><
| +-number-+ |
| +-Normal--------+ |
+-+-----------+--+---------------+-+
| +-------+ | +-All-----------+
| V | | +-Commands------+
+-----?---+-+ +-Error---------+
+-Failure-------+
+-Intermediates-+
+-Labels--------+
+-Off-----------+
+-Results-------+
]]>
</programlisting>
<para>Or, alternatively:</para>
<programlisting>
<![CDATA[
>>-TRACE--+-----------------------+--;-------------------------><
+-string----------------+
+-symbol----------------+
+-+-------+--expression-+
+-VALUE-+
]]>
</programlisting>
<para>TRACE controls the tracing action (that is, how much is displayed to the
user) during the processing of a Rexx program. Tracing describes some or all
of the clauses in a program, producing descriptions of clauses as they are
processed. TRACE is mainly used for debugging. Its syntax is more concise
than that of other Rexx instructions because TRACE is usually entered manually
during interactive debugging. (This is a form of tracing in which the user
can interact with the language processor while the program is running.)</para>
<note><title>Note</title>
<para>TRACE cannot be used in the Rexx macrospace. See
<xref linkend="traceinmacrospace" />.</para></note>
<para>If specified, the <emphasis role="italic">number</emphasis>
must be a whole number.</para>
<para>The <emphasis role="italic">string</emphasis> or
<emphasis role="italic">expression</emphasis> evaluates to: </para>
<itemizedlist>
<listitem><para>A numeric option</para></listitem>
<listitem><para>One of the valid prefix or alphabetic character (word) options
described in
<xref linkend="alphaco" /></para>
</listitem>
<listitem><para>Null</para></listitem></itemizedlist>
<para>The <emphasis role="italic">symbol</emphasis> is taken as a constant
and is therefore:</para>
<itemizedlist>
<listitem><para>A numeric option</para></listitem>
<listitem><para>One of the valid prefix or alphabetic character (word) options
described in <xref linkend="alphaco" />
</para></listitem></itemizedlist>
<para>The option that follows TRACE or the character string that is the result
of evaluating <emphasis role="italic">expression</emphasis> determines the
tracing action. You can omit
the subkeyword VALUE if <emphasis role="italic">expression</emphasis>
does not begin with a symbol or
a literal string, that is, if it starts with a special character, such as
an operator or parenthesis.</para>
<section id="alphaco"><title>Trace Alphabetic Character (Word) Options</title>
<indexterm><primary>TRACE instruction</primary>
<secondary>alphabetical character word options</secondary></indexterm>
<indexterm><primary>word</primary>
<secondary>alphabetical character options in TRACE</secondary></indexterm>
<indexterm><primary>alphabetical character word options in TRACE</primary>
</indexterm>
<indexterm><primary>options</primary>
<secondary>alphabetical character word options</secondary></indexterm>
<para>Although you can enter the word in full, only the first capitalized letter
is needed; all following characters are ignored. That is why these are referred
to as alphabetic character options.</para>
<para>TRACE actions correspond to the alphabetic character options as follows:
</para>
<variablelist>
<varlistentry><term><emphasis role="bold">All</emphasis></term>
<listitem><para>Traces (that is, displays) all clauses before execution.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Commands</emphasis></term>
<listitem><para>Traces all commands before execution. If the command results
in an error or failure (see <xref linkend="commnds" />),
tracing also displays the return code from the command.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Error</emphasis>
<indexterm><primary>error</primary>
<secondary>traceback after</secondary></indexterm>
</term>
<listitem><para>Traces any command resulting in an error or failure after
execution (see <xref linkend="commnds" />), together with the
return code from the command.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Failure</emphasis></term>
<listitem><para>Traces any command resulting in a failure after execution
(see <xref linkend="commnds" />), together with the return
code from the command. This is
the same as the <computeroutput>Normal</computeroutput> option.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Intermediates</emphasis></term>
<listitem><para>Traces all clauses before execution. Also traces intermediate
results during the evaluation of expressions and substituted names.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Labels</emphasis></term>
<listitem><para>Traces only labels passed during execution. This is especially
useful with debug mode, when the language processor pauses after each label. It
also helps the user to note all internal subroutine calls and transfers of
control because of the SIGNAL instruction.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Normal</emphasis></term>
<listitem><para>Traces any failing command after execution, together with the
return code from the command. This is the default setting. </para>
<para>For the default Windows command processor, an attempt
to enter an unknown command raises a FAILURE condition. The CMD return code
for an unknown command is 1. An attempt to enter a command in an unknown command
environment also raises a FAILURE condition; in such a case, the variable
RC is set to 30.</para>
</listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Off</emphasis></term>
<listitem><para>Traces nothing and resets the special prefix option
(described later) to OFF.
</para></listitem></varlistentry>
<varlistentry><term><emphasis role="bold">Results</emphasis>
<indexterm><primary>expressions</primary>
<secondary>tracing results of</secondary></indexterm>
</term>
<listitem><para>Traces all clauses before execution. Displays the final results
(in contrast with <computeroutput>Intermediates</computeroutput> option) of the
expression evaluation.
Also displays values assigned during PULL, ARG, PARSE, and USE instructions.
This setting is recommended for general debugging.
</para></listitem></varlistentry>
</variablelist>
</section>
<section id="xpreop"><title>Prefix Option</title>
<indexterm><primary>? prefix on TRACE option</primary></indexterm>
<para>The prefix <computeroutput>?</computeroutput> is valid alone or with
one of the alphabetic character options. You can specify the prefix more
than once, if desired. Each occurrence
of a prefix on an instruction reverses the action of the previous prefix.
The prefix must immediately precede the option (no intervening
whitespace).</para>
<para>The prefix <computeroutput>?</computeroutput>
controls interactive debugging. During normal execution, a TRACE option
with a prefix of <computeroutput>?</computeroutput>
causes interactive debugging to be switched
on. (See <xref linkend="xintdeb" />
for full details of this facility.) When interactive
debugging is on, interpretation pauses after most clauses that are traced.
For example, the instruction <computeroutput>TRACE ?E</computeroutput>
makes the language processor
pause for input after executing any command that returns an error, that is,
a nonzero return code or explicit setting of the error condition by the command
handler.</para>
<para>Any TRACE instructions in the program being traced are ignored to ensure
that you are not taken out of interactive debugging unexpectedly.</para>
<para>You can switch off interactive debugging in several ways: </para>
<itemizedlist>
<listitem><para>Entering <computeroutput>TRACE O</computeroutput>
turns off all tracing.</para></listitem>
<listitem><para>Entering <computeroutput>TRACE</computeroutput>
with no options restores the defaults&mdash;it
turns off interactive debugging but continues tracing with TRACE Normal (which
traces any failing command after execution).</para></listitem>
<listitem><para>Entering <computeroutput>TRACE ?</computeroutput> turns off
interactive debugging and continues tracing with the current option.</para>
</listitem>
<listitem><para>Entering a TRACE instruction with a
<computeroutput>?</computeroutput> prefix before the option
turns off interactive debugging and continues tracing with the new option.
</para></listitem></itemizedlist>
<para> Using the <computeroutput>?</computeroutput> prefix, therefore, switches
you in or out of
interactive debugging. Because the language processor ignores any further
TRACE statements in your program after you are in interactive debug mode,
use <computeroutput>CALL TRACE "?"</computeroutput> to turn off interactive
debugging.</para>
</section>
<section id="numopt"><title>Numeric Options</title>
<indexterm><primary>numeric</primary>
<secondary>options in TRACE</secondary></indexterm>
<indexterm><primary>options</primary>
<secondary>numeric in TRACE</secondary></indexterm>
<para>If interactive debugging is active and the option specified is a positive
whole number (or an expression that evaluates to a positive whole number),
that number indicates the number of debug pauses to be skipped.
(See <xref linkend="xintdeb" /> for further information.)
However, if the option is a negative
whole number (or an expression that evaluates to a negative whole number),
all tracing, including debug pauses, is temporarily inhibited for the specified
number of clauses. For example, <computeroutput>TRACE -100</computeroutput>
means that the next 100 clauses that would usually be traced are not displayed.
After that, tracing resumes as before.</para>
</section>
<section id="trnotes"><title>Tracing Tips</title>
<indexterm><primary>tracing</primary>
<secondary>tips</secondary></indexterm>
<indexterm><primary>tips, tracing</primary></indexterm>
<itemizedlist>
<listitem><para>When a loop is traced, the DO clause itself is traced on
every iteration of the loop.</para></listitem>
<listitem><para>You can retrieve the trace actions currently in effect by
using the TRACE
built-in function (see <xref linkend="bifTrace" />).</para></listitem>
<listitem><para>The trace output of commands traced before execution always
contains the final value of the command, that is, the
string passed to the environment, and the clause generating it.</para>
</listitem>
<listitem><para>Trace actions are automatically saved across subroutine,
function, and method calls. See
<xref linkend="keyCall" /> for more details.
</para></listitem></itemizedlist>
<indexterm><primary>TRACE instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>TRACE instruction</secondary></indexterm>
<para>One of the most common traces you will use is: </para>
<example>
<title>Instructions - TRACE</title>
<programlisting>
TRACE ?R
/* Interactive debugging is switched on if it was off, */
/* and tracing results of expressions begins. */
</programlisting>
</example>
</section>
<section id="tracfor"><title>The Format of Trace Output</title>
<indexterm><primary>formatting</primary>
<secondary>of output during tracing</secondary></indexterm>
<para>Every clause traced appears with automatic
<indexterm><primary>indentation during tracing</primary></indexterm>
formatting (indentation) according to its logical depth of nesting, for example.
Results, if requested, are indented by two extra spaces and are enclosed in
double quotation marks so that leading and trailing whitespace characters are
apparent. Any control codes in the data encoding (ASCII values less than "20"x)
are replaced by a question mark (?) to avoid screen interference. Results other
than strings appear in the string representation obtained by sending them a
<computeroutput>STRING</computeroutput> message. The resulting string is
enclosed in parentheses. The line number in the program precedes the first
clause traced on any line. All lines displayed during tracing have a
three-character prefix to identify the type of data being traced. These can be:
</para>
<indexterm><primary>tracing</primary>
<secondary>data identifiers</secondary></indexterm>
<variablelist>
<varlistentry><term><computeroutput>*-*</computeroutput>
<indexterm><primary>*-* tracing flag</primary></indexterm>
<indexterm><primary>flag, tracing</primary>
<secondary>*-*</secondary></indexterm>
<indexterm><primary>tracing flag</primary>
<secondary>*-*</secondary></indexterm>
</term>
<listitem><para>Identifies the source of a single clause, that is, the data
actually in the program.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>+++</computeroutput>
<indexterm><primary>flag, tracing</primary>
<secondary>+++</secondary></indexterm>
<indexterm><primary>tracing flag</primary>
<secondary>+++</secondary></indexterm>
<indexterm><primary>+++ tracing flag</primary></indexterm>
</term>
<listitem><para>Identifies a trace message. This can be the nonzero return
code from a command, the prompt message when interactive debugging is entered,
an indication of a syntax error when in interactive debugging.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>>I></computeroutput>
<indexterm><primary>flag, tracing</primary>
<secondary>>I></secondary></indexterm>
<indexterm><primary>tracing flag</primary>
<secondary>>I></secondary></indexterm>
<indexterm><primary>>I> tracing flag</primary></indexterm>
</term>
<listitem><para>Identifies an entry to a routine or method. This
trace entry will only appear if tracing is enabled using the ::OPTIONS
directive using TRACE A, TRACE R, or TRACE I.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>>>></computeroutput>
<indexterm><primary>flag, tracing</primary>
<secondary>>>></secondary></indexterm>
<indexterm><primary>tracing flag</primary>
<secondary>>>></secondary></indexterm>
<indexterm><primary>>>> tracing flag</primary></indexterm>
</term>
<listitem><para>Identifies the result of an expression
(for <computeroutput>TRACE R</computeroutput>) or the
the value returned from a
subroutine call, or a value evaluated by execution of a DO loop.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>>=></computeroutput>
<indexterm><primary>flag, tracing</primary>
<secondary>>=></secondary></indexterm>
<indexterm><primary>tracing flag</primary>
<secondary>=>></secondary></indexterm>
<indexterm><primary>>=> tracing flag</primary></indexterm>
</term>
<listitem><para>Identifies a variable assignment or a message assignment result.
The trace message includes both the name of the assignment target and the
assigned value. Assignment trace lines are displayed by assignment instructions,
variable assigned via PARSE, ARG, PULL, or USE ARG, as well as control variable
updates for DO and LOOP instructions.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>>.></computeroutput>
<indexterm><primary>flag, tracing</primary>
<secondary>>.></secondary></indexterm>
<indexterm><primary>tracing flag</primary>
<secondary>>.></secondary></indexterm>
<indexterm><primary>>.> tracing flag</primary></indexterm>
</term>
<listitem><para>Identifies the value assigned to a placeholder during parsing
(see <xref linkend="placeh" />).
</para></listitem></varlistentry>
</variablelist><para> The following prefixes are used only if
<computeroutput>TRACE Intermediates</computeroutput> is in effect:</para>
<variablelist>
<varlistentry><term><computeroutput>>A></computeroutput>
<indexterm><primary>flag, tracing</primary>
<secondary>>A></secondary></indexterm>
<indexterm><primary>tracing flag</primary>
<secondary>>A></secondary></indexterm>
<indexterm><primary>>A> tracing flag</primary></indexterm>
</term>
<listitem><para>Identifies a value used as a function, subroutine, or message argument.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>>C></computeroutput>
</term>
<listitem><para>The data traced is the orignal name of the compound variable and
the name of a compound variable,
after the name has
been replaced by the value of the variable but before the variable is used.
If no value was assigned to the variable, the trace shows the variable in
uppercase characters.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>>E></computeroutput>
<indexterm><primary>flag, tracing</primary>
<secondary>>E></secondary></indexterm>
<indexterm><primary>tracing flag</primary>
<secondary>>E></secondary></indexterm>
<indexterm><primary>>E> tracing flag</primary></indexterm>
</term>
<listitem><para>The data traced is the name and value of an environment symbol.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>>F></computeroutput>
<indexterm><primary>flag, tracing</primary>
<secondary>>F></secondary></indexterm>
<indexterm><primary>tracing flag</primary>
<secondary>>F></secondary></indexterm>
<indexterm><primary>>F> tracing flag</primary></indexterm>
</term>
<listitem><para>The data traced is the name and result of a function call.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>>L></computeroutput>
<indexterm><primary>flag, tracing</primary>
<secondary>>L></secondary></indexterm>
<indexterm><primary>tracing flag</primary>
<secondary>>L></secondary></indexterm>
<indexterm><primary>>L> tracing flag</primary></indexterm>
</term>
<listitem><para>The data traced is a literal (string, uninitialized variable,
or constant symbol).
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>>M></computeroutput>
<indexterm><primary>flag, tracing</primary>
<secondary>>M></secondary></indexterm>
<indexterm><primary>tracing flag</primary>
<secondary>>M></secondary></indexterm>
<indexterm><primary>>M> tracing flag</primary></indexterm>
</term>
<listitem><para>The data traced is the name and result of an object message.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>>O></computeroutput>
<indexterm><primary>flag, tracing</primary>
<secondary>>O></secondary></indexterm>
<indexterm><primary>tracing flag</primary>
<secondary>>O></secondary></indexterm>
<indexterm><primary>>O> tracing flag</primary></indexterm>
</term>
<listitem><para>The data traced is the name and result of an operation on two terms.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>>P></computeroutput>
<indexterm><primary>flag, tracing</primary>
<secondary>>P></secondary></indexterm>
<indexterm><primary>tracing flag</primary>
<secondary>>P></secondary></indexterm>
<indexterm><primary>>P> tracing flag</primary></indexterm>
</term>
<listitem><para>The data traced is the name and result of a prefix operation.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>>V></computeroutput>
<indexterm><primary>flag, tracing</primary>
<secondary>>V></secondary></indexterm>
<indexterm><primary>tracing flag</primary>
<secondary>>V></secondary></indexterm>
<indexterm><primary>>V> tracing flag</primary></indexterm>
</term>
<listitem><para>The data traced is the name and contents of a variable.
</para></listitem></varlistentry>
</variablelist>
<note><para>The characters <computeroutput>=></computeroutput> indicate the
value of a variable or the result of an operation.</para>
<para>The characters <computeroutput>&lt;=</computeroutput> indicate a value assignment.
The name to the left of the marker is the assignment topic. The data to the right
of the marker is the assigned value.</para>
<para>The character <computeroutput>?</computeroutput> could indicate a
non-printable character in the output.</para>
</note>
<para>If no option is specified on a TRACE instruction, or if the result of
evaluating the expression is null, the default tracing actions are restored.
The defaults are TRACE N and interactive debugging
(<computeroutput>?</computeroutput>) off.</para>
<indexterm><primary>syntax</primary>
<secondary>error</secondary>
<tertiary>traceback after</tertiary></indexterm>
<indexterm><primary>traceback, on syntax error</primary></indexterm>
<para>Following a syntax error that SIGNAL ON SYNTAX does not trap, the clause
in error is always traced.</para>
</section>
</section>
<section id="keyUse"><title>USE</title>
<indexterm><primary>USE instruction</primary>
<secondary>description</secondary></indexterm>
<indexterm><primary>instructions</primary>
<secondary>USE</secondary></indexterm>
<indexterm><primary>ARG subkeyword</primary>
<secondary>in a USE instruction</secondary></indexterm>
<indexterm><primary>STRICT subkeyword</primary>
<secondary>in a USE instruction</secondary></indexterm>
<programlisting>
<![CDATA[
+-,----------------------+
V |
>>-USE--+-----------+--ARG----+--------------------+-+-----------------------><
+-- STRICT--+ +-name-+----------+--+
+-=--expr--+
]]>
</programlisting>
<para>USE ARG retrieves the argument objects provided in a program, routine,
function, or method and assigns them to variables or message term assignments.</para>
<para>Each <emphasis role="italic">name</emphasis> must be a valid variable
name. The <emphasis role="italic">name</emphasis>s are
assigned from left to right. For each <emphasis role="italic">name</emphasis>
you specify, the language processor assigns it a corresponding argument from
the program, routine, function, or method call. If there is no corresponding
argument, <emphasis role="italic">name</emphasis> is assigned the value
of <emphasis role="italic">expr</emphasis>. If <emphasis role="italic">expr</emphasis>
is not specified for the given argument, the variable <emphasis role="italic">name</emphasis>
is dropped. If the assignment target is a messaging term, no action is taken for omitted arguments.
</para>
<para>A USE ARG instruction can be processed repeatedly and it always accesses
the same current argument data.</para>
<para>If <emphasis role="italic">expr</emphasis> is specified for an argument, the
expression is evaluated to provide a default value for an argument when the corresponding
argument does not exist. The default <emphasis role="italic">expr</emphasis>
must be a literal string, a constant expression, or an expression enclosed in
parentheses.</para>
<para>The <emphasis role="italic">name</emphasis>s may be any valid symbol or
message term which
can appear on the left side of an assignment statement (See
<xref linkend="assinmt" />).
</para>
<para>The STRICT options imposes additional constraints on argument processing.
The number of arguments must match the number of
<emphasis role="italic">name</emphasis>s, otherwise an error is raised. An argument
may be considered optional if <emphasis role="italic">expr</emphasis> has been
specified for the argument.</para>
<para>The ellipsis ("...") can be given in place of the last variable in the USE
STRICT ARG statement and indicates that more arguments may follow. It allows
defining a minimum amount of arguments that must be supplied or for which
there are default values defined and that may be followed optionally by any
additional arguments.</para>
<indexterm><primary>USE instruction</primary>
<secondary>example</secondary></indexterm>
<indexterm><primary>examples</primary>
<secondary>USE instruction</secondary></indexterm>
<example>
<title>Instructions - USE</title>
<programlisting>
/* USE Example */
/* FRED("Ogof X",1,5) calls function */
Fred: use arg string, num1, num2
/* Now: STRING contains "Ogof X" */
/* NUM1 contains "1" */
/* NUM2 contains "5" */
</programlisting>
<programlisting>
/* Another example, shows how to pass non-string arguments with USE ARG */
/* Pass a stem and an array to a routine to modify one element of each */
stem.1 = "Value"
array = .array~of("Item")
say "Before subroutine:" stem.1 array[1] /* Shows "Value Item" */
Call Change_First stem. , array
say "After subroutine:" stem.1 array[1] /* Shows "NewValue NewItem" */
Exit
Change_First: Procedure
Use Arg substem., subarray
substem.1 = "NewValue"
subarray[1] = "NewItem"
Return
</programlisting>
<programlisting>
/* USE STRICT Example */
/* FRED("Ogof X",1) calls function */
Fred: use strict arg string, num1, num2=4
/* Now: STRING contains "Ogof X" */
/* NUM1 contains "1" */
/* NUM2 contains "4" */
</programlisting>
</example>
<para>In the above example, a call to the function FRED may have either 2 or 3 arguments. The
STRICT keyword on the USE instruction will raise a syntax error for any other combination of
arguments.</para>
<example>
<title>Instructions - USE</title>
<programlisting>
call test "one"
call test "one", "two"
call test "one", "two", "three"
call test "one", , "three", "four", "five"
exit
test: procedure /* a minimum of one argument must be supplied */
use strict arg v1, v2="zwei", ...
say "There are ["arg()"] argument(s); v1,v2=["v1","v2"]"
do i=3 to arg()
say " arg #" i"=["arg(i)"]"
end
say "--"
return
</programlisting>
<para><emphasis role="bold">Output:</emphasis></para>
<programlisting>
There are [1] argument(s); v1,v2=[one,zwei]
--
There are [2] argument(s); v1,v2=[one,two]
--
There are [3] argument(s); v1,v2=[one,two]
arg # 3=[three]
--
There are [5] argument(s); v1,v2=[one,zwei]
arg # 3=[three]
arg # 4=[four]
arg # 5=[five]
--
</programlisting>
</example>
<para>The assignment targets may be any term that can be on the left side of
an assignment statement.</para>
<example>
<title>Instructions - USE</title>
<programlisting>
expose myArray myDirectory
use arg myArray[1], myDirectory~name
</programlisting>
<para>would be equivalent to</para>
<programlisting>
myArray[1] = arg(1)
myDirectory~name = arg(2)
</programlisting>
</example>
<para>You can retrieve or check the arguments by using the ARG built-in function
(see <xref linkend="bifArg" />).
The ARG and PARSE ARG instructions are alternative
ways of retrieving arguments. ARG and PARSE ARG access the string values of
arguments. USE ARG performs a direct, one-to-one assignment of arguments.
This is preferable when you need direct access to an argument,
without translation or parsing. USE ARG also allows access to both string
and non-string argument objects; ARG and PARSE ARG convert the arguments to values
before parsing.</para>
</section>
</chapter>