PLI 5.1 Language Reference
PLI 5.1 Language Reference
PLI 5.1 Language Reference
Language Reference
Version 5 Release 1
SC27-8940-00
Enterprise PL/I for z/OS
PL/I for AIX
Rational Developer for System z PL/I for Windows IBM
Language Reference
Version 5 Release 1
SC27-8940-00
Note
Before using this information and the product it supports, be sure to read the general information under Notices on page
875.
Contents v
PRINT attribute . . . . . . . . . . . 305 PRINT attribute . . . . . . . . . . . . 341
Opening and closing files . . . . . . . . . 305 DBCS data in stream I/O . . . . . . . . . 342
OPEN statement . . . . . . . . . . . 305
Implicit opening . . . . . . . . . . . 307 Chapter 13. Edit-directed format items 343
CLOSE statement . . . . . . . . . . . 309 A-format item . . . . . . . . . . . . . 343
FLUSH statement . . . . . . . . . . . 310 B-format item . . . . . . . . . . . . . 344
SYSPRINT and SYSIN . . . . . . . . . . 310 C-format item . . . . . . . . . . . . . 344
COLUMN format item . . . . . . . . . . 345
Chapter 11. Record-oriented data E-format item . . . . . . . . . . . . . 346
transmission. . . . . . . . . . . . 311 F-format item . . . . . . . . . . . . . 348
Data transmitted . . . . . . . . . . . . 311 G-format item . . . . . . . . . . . . . 350
Unaligned bit strings . . . . . . . . . . 311 L-format item . . . . . . . . . . . . . 350
Varying length strings . . . . . . . . . 311 LINE format item . . . . . . . . . . . . 351
Area variables . . . . . . . . . . . . 312 P-format item . . . . . . . . . . . . . 351
Data transmission statements . . . . . . . . 312 PAGE format item . . . . . . . . . . . . 352
READ statement . . . . . . . . . . . 312 R-format item . . . . . . . . . . . . . 352
WRITE statement . . . . . . . . . . . 313 SKIP format item . . . . . . . . . . . . 353
REWRITE statement . . . . . . . . . . 313 V-format item . . . . . . . . . . . . . 353
LOCATE statement . . . . . . . . . . 314 X-format item . . . . . . . . . . . . . 354
DELETE statement . . . . . . . . . . 314
Options of data transmission statements . . . . 314 Chapter 14. Picture specification
FILE option . . . . . . . . . . . . . 314 characters. . . . . . . . . . . . . 355
FROM option . . . . . . . . . . . . 315 Picture repetition factor . . . . . . . . . . 355
IGNORE option . . . . . . . . . . . 315 Picture characters for character data . . . . . . 356
INTO option . . . . . . . . . . . . 315 Picture characters for numeric character data . . . 357
KEY option . . . . . . . . . . . . . 316 Digits and decimal points . . . . . . . . 358
KEYFROM option . . . . . . . . . . . 316 Zero suppression . . . . . . . . . . . 359
KEYTO option . . . . . . . . . . . . 317 Insertion characters . . . . . . . . . . 360
SET option . . . . . . . . . . . . . 317 Defining currency symbols . . . . . . . . 362
Processing modes . . . . . . . . . . . . 318 Using signs and currency symbols . . . . . 364
Move mode . . . . . . . . . . . . . 318 Credit, debit, overpunched, and zero
Locate mode . . . . . . . . . . . . 318 replacement characters . . . . . . . . . 366
Exponent characters . . . . . . . . . . 368
Chapter 12. Stream-oriented data Scaling factor . . . . . . . . . . . . 369
transmission. . . . . . . . . . . . 321
Data transmission statements . . . . . . . . 321 Chapter 15. Condition handling. . . . 371
GET statement . . . . . . . . . . . . 322 Condition prefixes . . . . . . . . . . . . 371
PUT statement . . . . . . . . . . . . 322 Scope of the condition prefix . . . . . . . 373
Options of data transmission statements . . . . 323 Raising conditions with OPTIMIZATION . . . 373
COPY option . . . . . . . . . . . . 323 On-units . . . . . . . . . . . . . . . 373
Data specification options . . . . . . . . 324 ON statement . . . . . . . . . . . . 374
FILE option . . . . . . . . . . . . . 325 Null ON-unit . . . . . . . . . . . . 375
LINE option . . . . . . . . . . . . . 326 Scope of the ON-unit . . . . . . . . . . 375
PAGE option . . . . . . . . . . . . 326 Dynamically descendent ON-units . . . . . 375
SKIP option . . . . . . . . . . . . . 326 ON-units for file variables . . . . . . . . 376
STRING option . . . . . . . . . . . . 327 REVERT statement . . . . . . . . . . . 377
Transmission of data-list items. . . . . . . . 328 SIGNAL statement . . . . . . . . . . . 377
Data-directed data specification . . . . . . . 329 RESIGNAL statement. . . . . . . . . . . 378
Restrictions on data-directed data . . . . . 329 Multiple conditions . . . . . . . . . . . 378
Syntax of data-directed data . . . . . . . 330 CONDITION attribute . . . . . . . . . . 378
GET data-directed . . . . . . . . . . . 331
PUT data-directed . . . . . . . . . . . 332 Chapter 16. Conditions . . . . . . . 381
Edit-directed data specification . . . . . . . 333 ANYCONDITION condition . . . . . . . . 381
GET edit-directed . . . . . . . . . . . 335 AREA condition . . . . . . . . . . . . 382
PUT edit-directed . . . . . . . . . . . 336 ATTENTION condition . . . . . . . . . . 383
FORMAT statement . . . . . . . . . . 337 CONDITION condition . . . . . . . . . . 384
List-directed data specification . . . . . . . 338 CONVERSION condition . . . . . . . . . 385
Syntax of list-directed data . . . . . . . . 338 ENDFILE condition . . . . . . . . . . . 386
GET list-directed . . . . . . . . . . . 339 ENDPAGE condition . . . . . . . . . . . 387
PUT list-directed . . . . . . . . . . . 340 ERROR condition . . . . . . . . . . . . 388
Contents vii
DAYS . . . . . . . . . . . . . . . 490 ISNORMAL . . . . . . . . . . . . . 553
DAYSTODATE . . . . . . . . . . . . 491 ISRL . . . . . . . . . . . . . . . 554
DAYSTOSECS . . . . . . . . . . . . 492 ISZERO . . . . . . . . . . . . . . 555
DECIMAL . . . . . . . . . . . . . 493 IUNSIGNED . . . . . . . . . . . . 556
DIMENSION . . . . . . . . . . . . 494 JSONGETARRAYEND . . . . . . . . . 557
DIVIDE . . . . . . . . . . . . . . 495 JSONGETARRAYSTART . . . . . . . . . 558
EDIT . . . . . . . . . . . . . . . 496 JSONGETCOLON . . . . . . . . . . . 559
EMPTY . . . . . . . . . . . . . . 497 JSONGETCOMMA . . . . . . . . . . 560
ENDFILE. . . . . . . . . . . . . . 498 JSONGETMEMBER . . . . . . . . . . 561
ENTRYADDR . . . . . . . . . . . . 499 JSONGETOBJECTEND . . . . . . . . . 563
ENTRYADDR pseudovariable . . . . . . . 500 JSONGETOBJECTSTART . . . . . . . . 564
EPSILON . . . . . . . . . . . . . . 501 JSONGETVALUE . . . . . . . . . . . 565
ERF . . . . . . . . . . . . . . . 502 JSONPUTARRAYEND . . . . . . . . . 567
ERFC . . . . . . . . . . . . . . . 503 JSONPUTARRAYSTART . . . . . . . . . 568
EXP . . . . . . . . . . . . . . . 504 JSONPUTCOLON . . . . . . . . . . . 569
EXPONENT . . . . . . . . . . . . . 505 JSONPUTCOMMA . . . . . . . . . . 570
FILEDDINT . . . . . . . . . . . . . 506 JSONPUTMEMBER . . . . . . . . . . 571
FILEDDTEST . . . . . . . . . . . . 507 JSONPUTOBJECTEND . . . . . . . . . 573
FILEDDWORD . . . . . . . . . . . . 508 JSONPUTOBJECTSTART . . . . . . . . 574
FILEID . . . . . . . . . . . . . . 509 JSONPUTVALUE . . . . . . . . . . . 575
FILEOPEN . . . . . . . . . . . . . 510 JSONVALID . . . . . . . . . . . . . 576
FILEREAD . . . . . . . . . . . . . 511 JULIANTOSMF. . . . . . . . . . . . 577
FILESEEK . . . . . . . . . . . . . 512 LBOUND. . . . . . . . . . . . . . 578
FILETELL . . . . . . . . . . . . . 513 LBOUNDACROSS. . . . . . . . . . . 579
FILEWRITE . . . . . . . . . . . . . 514 LEFT . . . . . . . . . . . . . . . 580
FIXED . . . . . . . . . . . . . . . 515 LENGTH . . . . . . . . . . . . . . 581
FIXEDBIN . . . . . . . . . . . . . 516 LINENO . . . . . . . . . . . . . . 582
FIXEDDEC . . . . . . . . . . . . . 517 LOCATION . . . . . . . . . . . . . 583
FLOAT . . . . . . . . . . . . . . 518 LOCNEWSPACE . . . . . . . . . . . 584
FLOATBIN . . . . . . . . . . . . . 519 LOCNEWVALUE . . . . . . . . . . . 585
FLOATDEC . . . . . . . . . . . . . 520 LOCSTG . . . . . . . . . . . . . . 586
FLOOR . . . . . . . . . . . . . . 521 LOCVAL . . . . . . . . . . . . . . 587
GAMMA . . . . . . . . . . . . . . 522 LOG . . . . . . . . . . . . . . . 588
GETENV . . . . . . . . . . . . . . 523 LOGGAMMA . . . . . . . . . . . . 589
GRAPHIC . . . . . . . . . . . . . 524 LOG2 . . . . . . . . . . . . . . . 590
HANDLE . . . . . . . . . . . . . 526 LOG10 . . . . . . . . . . . . . . 591
HBOUND . . . . . . . . . . . . . 527 LOW . . . . . . . . . . . . . . . 592
HBOUNDACROSS . . . . . . . . . . 528 LOWERCASE . . . . . . . . . . . . 593
HEX . . . . . . . . . . . . . . . 529 LOWER2 . . . . . . . . . . . . . . 594
HEXDECODE . . . . . . . . . . . . 531 MAINNAME . . . . . . . . . . . . 595
HEXDECODE8 . . . . . . . . . . . . 532 MAX . . . . . . . . . . . . . . . 596
HEXIMAGE . . . . . . . . . . . . . 533 MAXEXP . . . . . . . . . . . . . . 597
HIGH . . . . . . . . . . . . . . . 534 MAXLENGTH . . . . . . . . . . . . 598
HUGE . . . . . . . . . . . . . . . 535 MEMCONVERT . . . . . . . . . . . 599
IAND . . . . . . . . . . . . . . . 536 MEMCU12 . . . . . . . . . . . . . 600
ICLZ . . . . . . . . . . . . . . . 537 MEMCU14 . . . . . . . . . . . . . 601
IEOR . . . . . . . . . . . . . . . 538 MEMCU21 . . . . . . . . . . . . . 602
IMAG . . . . . . . . . . . . . . . 539 MEMCU24 . . . . . . . . . . . . . 603
IMAG pseudovariable . . . . . . . . . 540 MEMCU41 . . . . . . . . . . . . . 604
INDEX . . . . . . . . . . . . . . 541 MEMCU42 . . . . . . . . . . . . . 605
INDEXR . . . . . . . . . . . . . . 542 MEMINDEX. . . . . . . . . . . . . 606
INDICATORS . . . . . . . . . . . . 543 MEMSEARCH . . . . . . . . . . . . 607
INLIST . . . . . . . . . . . . . . 544 MEMSEARCHR . . . . . . . . . . . 608
INOT . . . . . . . . . . . . . . . 545 MEMVERIFY . . . . . . . . . . . . 609
IOR . . . . . . . . . . . . . . . 546 MEMVERIFYR . . . . . . . . . . . . 610
ISFINITE . . . . . . . . . . . . . . 547 MIN . . . . . . . . . . . . . . . 611
ISIGNED . . . . . . . . . . . . . . 548 MINEXP . . . . . . . . . . . . . . 612
ISINF . . . . . . . . . . . . . . . 549 MOD . . . . . . . . . . . . . . . 613
ISLL . . . . . . . . . . . . . . . 550 MPSTR . . . . . . . . . . . . . . 615
ISMAIN . . . . . . . . . . . . . . 551 MULTIPLY . . . . . . . . . . . . . 616
ISNAN . . . . . . . . . . . . . . 552 NULL . . . . . . . . . . . . . . . 617
Contents ix
TALLY . . . . . . . . . . . . . . 744 RESPEC . . . . . . . . . . . . . . . 806
TAN . . . . . . . . . . . . . . . 745 SIZE . . . . . . . . . . . . . . . . 807
TAND . . . . . . . . . . . . . . . 746 VALUE . . . . . . . . . . . . . . . 808
TANH . . . . . . . . . . . . . . . 747
THREADID . . . . . . . . . . . . . 748 Chapter 20. Preprocessor facilities 809
TIME . . . . . . . . . . . . . . . 749 Preprocessor options . . . . . . . . . . . 810
TIMESTAMP . . . . . . . . . . . . 750 Preprocessor scan . . . . . . . . . . . . 811
TINY . . . . . . . . . . . . . . . 751 Execution of preprocessor statements . . . . 811
TRANSLATE . . . . . . . . . . . . 752 Execution of listing control statements . . . . 811
TRIM . . . . . . . . . . . . . . . 753 Execution of input text . . . . . . . . . 811
TRUNC . . . . . . . . . . . . . . 754 Preprocessor variables and data elements . . . . 813
TYPE . . . . . . . . . . . . . . . 755 Preprocessor references and expressions . . . . 813
TYPE pseudovariable. . . . . . . . . . 756 Scope of preprocessor names . . . . . . . . 814
ULENGTH . . . . . . . . . . . . . 757 Preprocessor procedures . . . . . . . . . . 814
ULENGTH8 . . . . . . . . . . . . . 758 Arguments and parameters for preprocessor
ULENGTH16 . . . . . . . . . . . . 759 procedures . . . . . . . . . . . . . 815
UNALLOCATED . . . . . . . . . . . 760 %PROCEDURE statement . . . . . . . . 816
UNSIGNED . . . . . . . . . . . . . 761 Preprocessor RETURN statement . . . . . . 817
UNSPEC . . . . . . . . . . . . . . 762 Preprocessor ANSWER statement. . . . . . 818
UNSPEC pseudovariable . . . . . . . . 764 Preprocessor CALL statement . . . . . . . 820
UPOS . . . . . . . . . . . . . . . 765 Preprocessor built-in functions . . . . . . . 820
UPPERCASE . . . . . . . . . . . . 766 COLLATE . . . . . . . . . . . . . 822
USUBSTR . . . . . . . . . . . . . 767 COMMENT . . . . . . . . . . . . . 823
USUPPLEMENTARY . . . . . . . . . . 768 COMPILEDATE . . . . . . . . . . . 824
UTCDATETIME . . . . . . . . . . . 769 COMPILETIME . . . . . . . . . . . 825
UTCSECS . . . . . . . . . . . . . 770 COPY . . . . . . . . . . . . . . . 826
UTF8 . . . . . . . . . . . . . . . 771 COUNTER . . . . . . . . . . . . . 827
UTF8STG. . . . . . . . . . . . . . 772 DIMENSION . . . . . . . . . . . . 828
UTF8TOCHAR . . . . . . . . . . . . 773 HBOUND . . . . . . . . . . . . . 829
UTF8TOWCHAR . . . . . . . . . . . 774 INDEX . . . . . . . . . . . . . . 830
UUID . . . . . . . . . . . . . . . 775 LBOUND. . . . . . . . . . . . . . 831
UVALID . . . . . . . . . . . . . . 776 LENGTH . . . . . . . . . . . . . . 832
UWIDTH. . . . . . . . . . . . . . 778 LOWERCASE . . . . . . . . . . . . 833
VALID . . . . . . . . . . . . . . 779 MACCOL . . . . . . . . . . . . . 834
VALIDDATE . . . . . . . . . . . . 780 MACLMAR . . . . . . . . . . . . . 835
VARGLIST . . . . . . . . . . . . . 781 MACNAME . . . . . . . . . . . . . 836
VARGSIZE . . . . . . . . . . . . . 782 MACRMAR . . . . . . . . . . . . . 837
VERIFY . . . . . . . . . . . . . . 783 MAX . . . . . . . . . . . . . . . 838
VERIFYR . . . . . . . . . . . . . . 784 MIN . . . . . . . . . . . . . . . 839
WCHARVAL . . . . . . . . . . . . 785 PARMSET . . . . . . . . . . . . . 840
WEEKDAY . . . . . . . . . . . . . 786 QUOTE . . . . . . . . . . . . . . 841
WHIGH . . . . . . . . . . . . . . 787 REPEAT . . . . . . . . . . . . . . 842
WHITESPACECOLLAPSE . . . . . . . . 788 SUBSTR . . . . . . . . . . . . . . 843
WHITESPACEREPLACE . . . . . . . . 789 SYSDIMSIZE . . . . . . . . . . . . 844
WIDECHAR. . . . . . . . . . . . . 790 SYSOFFSETSIZE . . . . . . . . . . . 845
WLOW . . . . . . . . . . . . . . 791 SYSPARM . . . . . . . . . . . . . 846
XMLCHAR . . . . . . . . . . . . . 792 SYSPOINTERSIZE . . . . . . . . . . . 847
XMLCLEAN . . . . . . . . . . . . 794 SYSTEM . . . . . . . . . . . . . . 848
Y4DATE . . . . . . . . . . . . . . 795 SYSVERSION . . . . . . . . . . . . 849
Y4JULIAN . . . . . . . . . . . . . 796 TRANSLATE . . . . . . . . . . . . 850
Y4YEAR . . . . . . . . . . . . . . 797 TRIM . . . . . . . . . . . . . . . 851
UPPERCASE . . . . . . . . . . . . 852
Chapter 19. Type functions . . . . . 799 VERIFY . . . . . . . . . . . . . . 853
Invoking type functions . . . . . . . . . . 799 Preprocessor statements . . . . . . . . . . 853
Specifying arguments for type functions . . . . 799 %ACTIVATE statement . . . . . . . . . 853
Brief descriptions of type functions . . . . . . 799 %assignment statement . . . . . . . . . 854
BIND . . . . . . . . . . . . . . . . 801 %DEACTIVATE statement . . . . . . . . 854
CAST . . . . . . . . . . . . . . . . 802 %DECLARE statement . . . . . . . . . 855
FIRST . . . . . . . . . . . . . . . . 803 %DO statement. . . . . . . . . . . . 857
LAST . . . . . . . . . . . . . . . . 804 %END statement . . . . . . . . . . . 858
NEW . . . . . . . . . . . . . . . . 805 %GO TO statement . . . . . . . . . . 858
Notices . . . . . . . . . . . . . . 875
Trademarks . . . . . . . . . . . . . . 876
Contents xi
xii Enterprise PL/I for z/OS Language Reference
Tables
1. Alphabetic equivalents . . . . . . . . . 1 41. Compound assignment operators . . . . . 215
2. Decimal digit equivalents . . . . . . . . 3 42. Alternative file attributes. . . . . . . . 300
3. Special character equivalents . . . . . . . 3 43. Attributes by data transmission type 300
4. Composite symbol description . . . . . . 4 44. Attributes of PL/I file declarations . . . . 301
5. Delimiters . . . . . . . . . . . . . 6 45. Attributes implied by implicit open . . . . 307
6. Operators . . . . . . . . . . . . . 7 46. Merged and implied attributes . . . . . . 308
7. Classification of attributes by constant types 19 47. Options and format items for PRINT files 341
8. Classification of attributes by variable types 21 48. Character picture specification examples 356
9. Abbreviations for coded arithmetic data 49. Examples of digit and decimal point
attributes . . . . . . . . . . . . . 23 characters . . . . . . . . . . . . . 359
10. FIXED BINARY SIGNED data storage 50. Examples of zero suppression characters 360
requirements . . . . . . . . . . . . 26 51. Examples of insertion characters . . . . . 362
11. FIXED BINARY UNSIGNED data storage 52. Examples of signs and currency characters 365
requirements . . . . . . . . . . . . 26 53. Interpretation of the T, I, and R picture
12. Examples . . . . . . . . . . . . . 29 characters . . . . . . . . . . . . . 366
13. Examples . . . . . . . . . . . . . 29 54. Examples of credit, debit, overpunched, and
14. Abbreviations for string data attributes 31 zero replacement characters . . . . . . . 368
15. Examples of character constants. . . . . . 34 55. Examples of exponent characters . . . . . 368
16. Examples of X constants . . . . . . . . 36 56. Examples of scaling factor characters 369
17. Examples of bit constants . . . . . . . . 36 57. Classes and status of conditions . . . . . 372
18. Examples of B4 constants . . . . . . . . 37 58. Built-in functions and pseudovariables that
19. Examples of B3 constants . . . . . . . . 37 accept structure or union arguments . . . . 411
20. Examples . . . . . . . . . . . . . 38 59. Arithmetic built-in functions . . . . . . 412
21. Examples of mixed character constants 39 60. Array-handling built-in functions . . . . . 412
22. Examples . . . . . . . . . . . . . 40 61. Buffer-management built-in functions 413
23. Arithmetic operator . . . . . . . . . . 57 62. Condition-handling built-in functions 415
24. Results of arithmetic operations for one or 63. Date/time built-in functions . . . . . . 416
more FLOAT operands . . . . . . . . . 61 64. Date/time patterns. . . . . . . . . . 417
25. Results of arithmetic operations between two 65. Floating-point inquiry built-in functions 418
unscaled FIXED operands under RULES(ANS) . 61 66. Floating-point manipulation built-in functions 419
26. Results of arithmetic operations between two 67. Input/output built-in functions . . . . . 419
scaled FIXED operands under RULES(ANS) . 62 68. Integer manipulation built-in functions 420
27. Results of arithmetic operations between two 69. JSON built-in functions . . . . . . . . 420
FIXED operands under RULES(IBM) . . . . 63 70. Mathematical built-in functions . . . . . 421
28. Comparison of FIXED division and constant 71. Miscellaneous built-in functions . . . . . 422
expressions . . . . . . . . . . . . 64 72. Ordinal-handling built-in functions . . . . 423
29. Special cases for exponentiation . . . . . . 65 73. Precision-handling built-in functions . . . . 423
30. Logical operators for bit operations . . . . 65 74. Built-in pseudovariables . . . . . . . . 424
31. Bit operations . . . . . . . . . . . . 66 75. Storage control built-in functions . . . . . 424
32. Bit operation examples . . . . . . . . . 66 76. String-handling built-in functions . . . . . 426
33. Priority of operations and guide to conversions 71 77. Built-in subroutines . . . . . . . . . 427
34. CEIL (n*3.32) and CEIL (n/3.32) values 80 78. Example of encoding a source buffer into
35. Ordinal-handling built-in functions . . . . 154 base 64 as UTF-8 . . . . . . . . . . 450
36. Type functions . . . . . . . . . . . 157 79. Example of encoding a source buffer into
37. Alignment on integral boundaries of base 64 as UTF-16 . . . . . . . . . . 451
halfwords, words, and doublewords . . . . 172 80. Length of bit string returned by UNSPEC 762
38. Alignment requirements . . . . . . . . 173 81. Type functions . . . . . . . . . . . 799
39. Default arithmetic precisions . . . . . . 179 82. Language element limits . . . . . . . . 869
40. Attributes in attribute-expression in DEFAULT 183 83. Macro facility limits . . . . . . . . . 872
It is not a tutorial, but is designed for the reader who already has a knowledge of
the PL/I language and who requires reference information needed to write a
program for an IBM PL/I compiler. It contains guidance information and
general-use programming interfaces.
Because this book is a reference manual, it is not intended to be read from front to
back, and terms can be used before they are defined. Terms are highlighted where
they are defined in the book, and definitions are found in the glossary.
Text set apart by the workstation opening and closing icons designates features
which are supported only on PL/I workstation products (AIX and Windows).
REQUIRED_ITEM
Optional Items
Optional items appear below the main path.
REQUIRED_ITEM
optional_item
If an optional item appears above the main path, that item has no effect on
the execution of the statement and is used only for readability.
optional_item
REQUIRED_ITEM
REQUIRED_ITEM required_choice1
required_choice2
If choosing one of the items is optional, the entire stack appears below the
main path.
REQUIRED_ITEM
optional_choice1
optional_choice2
Repeatable items
An arrow returning to the left above the main line indicates that an item
can be repeated.
REQUIRED_ITEM repeatable_item
If the repeat arrow contains a comma, you must separate repeated items
with a comma.
REQUIRED_ITEM repeatable_item
A repeat arrow above a stack indicates that you can specify more than one
of the choices in the stack.
Default keywords
IBM-supplied default keywords appear above the main path, and the
remaining choices are shown below the main path. In the parameter list
following the syntax diagram, the default choices are underlined.
default_choice
REQUIRED_ITEM
optional_choice
optional_choice
Fragments
Sometimes a diagram must be split into fragments. The fragments are
represented by a letter or fragment name, set off like this: | A |. The
fragment follows the end of the main diagram. The following example
shows the use of a fragment.
A:
item 3 KEYWORD
item 4 item 5
item 6
Substitution-block
Sometimes a set of several parameters is represented by a
substitution-block such as <A>. For example, in the imaginary /VERB
command you could enter /VERB LINE 1, /VERB EITHER LINE 1, or /VERB
OR LINE 1.
EITHER
OR
Parameter endings
Parameters with number values end with the symbol '#', parameters that
are names end with 'name', and parameters that can be generic end with
'*'.
The MSNAME keyword in the example supports a name value and the
SYSID keyword supports a number value.
Semantics
To describe the PL/I language, the following conventions are used:
Summary of changes
Enhancements in usability
v The compiler now supports 64-bit applications under the LP(64) option. This
means that under this option, POINTER and HANLDE can be eight bytes in
size, structures and arrays can be larger than 2G in size, and many built-in
functions (such as PLIMOVE) can take 8-byte integer arguments and return
8-byte integer results.
v The INITIAL attribute is now allowed on macro declare statements.
v The JSONNAME attribute provides the ability to specify the name that is used
or expected for a variable in jsonPut or jsonGet functions. In particular, with this
attribute you can specify a name that does not conform to PL/I name rules.
v The JSONOMIT attribute indicates that fields of certain data items must be
omitted from output that is generated by JSON functions. In particular, if a
variable has the JSONOMIT attribute, the jsonPut functions will omit this
variable from the generated text if the variable is equal to a null string .
v The SUPPRESS attribute now accepts NOPADDING as a subattribute, which can
be applied on a variable. If specified on a level-1 structure name,
SUPPRESS(NOPADDING) causes the RULES(NOPADDING) compiler option to
be ignored for that structure.
v The compiler now issues a W-level message rather than an I-level message if
attributes other than FIXED BIN(p,0) are used with REFER objects.
v Some assignments to UNIONs and, more generally, to structures that contain
UNIONs are now supported.
v The XMLCONTENT attribute specifies that when a variable is included in the
text that is generated by the XMLCHAR built-in function, it is presented as
tagless text.
Performance improvements
v Some fixed decimal divides with large precision are now done using the
Decimal Floating-Point (DFP) facility. This might cause some ZERODIVIDE
exceptions to be reported as INVALIDOP.
SQL enhancements
v The INDFOR attribute makes it easy to declare a structure of indicator variables
to match another PL/I structure.
v The new HEX suboption of the USAGE compiler option will allow the user to
specify how much data is displayed when applying the HEX built-in function to
VARYING and VARYINGZ strings.
v The PICSPEC built-in function is now supported so that CHARACTER data may
be quickly cast to PICTURE.
v The THREADID built-in function may now be used under z/OS. It has also
been changed so that it returns a pointer to the thread identifier and so that it
always requires a parameter.
v Support, in the same manner as provided by the old host compiler, for PROCs
with ENTRY statements that have differing RETURNS attributes.
v OPTIONS(RETCODE) is assumed for PROCs and ENTRYs with
OPTIONS(COBOL).
v The SIZE condition is no longer promoted to ERROR if unhandled.
v The new USAGE compiler option gives you full control over the IBM or ANS
behavior of the ROUND and UNSPEC built-in function without the other effects
of the RULES(IBM|ANS) option.
v POINTERs are now allowed in PUT LIST and PUT EDIT statements: the 8-byte
hex value will be output.
v If specified on a STATIC variable, the ABNORMAL attribute will cause that
variable to be retained even if unused.
This release also provides all of the functional enhancements that are offered in
Enterprise PL/I V3R1, including the following:
v Support for Multithreading on z/OS
v Support for IEEE floating-point on z/OS
v Support for the ANSWER statement in the macro prepreprocessor
v SAX-style XML parsing via the PLISAXA and PLISAXB built-in subroutines
v Additional built-in functions:
CS
CDS
ISMAIN
LOWERCASE
UPPERCASE
This release also provides all of the functional enhancements that are offered in
VisualAge PL/I V2R2, including the following:
v Initial UTF-16 support via the WIDECHAR attribute
There is currently no support yet for
WIDECHAR characters in source files
W string constants
use of WIDECHAR expressions in stream I/O
implicit conversion to/from WIDECHAR in record I/O
implicit endianness flags in record I/O
If you create a WIDECHAR file, you should write the endianness flag
('fe_ff'wx) as the first two bytes of the file.
v DESCRIPTORS and VALUE options that are supported in DEFAULT statements
v PUT DATA enhancements
POINTER, OFFSET, and other non-computational variables supported
Type-3 DO specifications allowed
Subscripts allowed
v DEFINE statement enhancements
Unspecified structure definitions
CAST and RESPEC type functions
v Additional built-in functions:
CHARVAL
ISIGNED
IUNSIGNED
ONWCHAR
ONWSOURCE
WCHAR
WCHARVAL
WHIGH
WIDECHAR
WLOW
v Preprocessor enhancements
Support for arrays in preprocessor procedures
WHILE, UNTIL and LOOP keywords supported in %DO statements
%ITERATE statement supported
%LEAVE statement supported
%REPLACE statement supported
%SELECT statement supported
Additional built-in functions:
- COLLATE
- COMMENT
- COMPILEDATE
- COMPILETIME
- COPY
- COUNTER
- DIMENSION
- HBOUND
- INDEX
- LBOUND
- LENGTH
- MACCOL
- MACLMAR
- MACRMAR
- MAX
- MIN
- PARMSET
- QUOTE
- REPEAT
- SUBSTR
- SYSPARM
- SYSTEM
- SYSVERSION
- TRANSLATE
- VERIFY
or send an email to
comments@us.ibm.com
Be sure to include the name of the document, the publication number of the
document, the version of PL/I, and, if applicable, the specific location (for
example, page number) of the text that you are commenting on.
v Fill out the Readers' Comment Form at the back of this document, and return it
by mail or give it to an IBM representative. If the form has been removed,
address your comments to:
When you send information to IBM, you grant IBM a nonexclusive right to use or
distribute the information in any way it believes appropriate without incurring any
obligation to you.
Accessibility
Accessibility features assist users who have a disability, such as restricted mobility
or limited vision, to use information technology content successfully. The
accessibility features in z/OS provide accessibility for Enterprise PL/I for z/OS.
Accessibility features
The Enterprise PL/I for z/OS online product documentation in IBM Knowledge
Center is enabled for accessibility. The accessibility features of IBM Knowledge
Center are described at http://www.ibm.com/support/knowledgecenter/doc/
kc_help.html#accessibility.
Keyboard navigation
Users can access z/OS user interfaces by using TSO/E or ISPF.
Users can also access z/OS services by using IBM Rational Developer for System
z .
For information about accessing these interfaces, see the following publications:
v z/OS TSO/E Primer (http://publib.boulder.ibm.com/cgi-bin/bookmgr/BOOKS/
ikj4p120)
v z/OS TSO/E User's Guide (http://publib.boulder.ibm.com/cgi-bin/bookmgr/
BOOKS/ikj4c240/APPENDIX1.3)
v z/OS ISPF User's Guide Volume I (http://publib.boulder.ibm.com/cgi-bin/
bookmgr/BOOKS/ispzug70)
v IBM Rational Developer for System z Knowledge Center (http://www.ibm.com/
support/knowledgecenter/SSQ2R2/rdz_welcome.html?lang=en)
These guides describe how to use TSO/E and ISPF, including the use of keyboard
shortcuts or function keys (PF keys). Each guide includes the default settings for
the PF keys and explains how to modify their functions.
Interface information
The Enterprise PL/I for z/OS online product documentation is available in IBM
Knowledge Center, which is viewable from a standard web browser.
PDF files have limited accessibility support. With PDF documentation, you can use
optional font enlargement, high-contrast display settings, and can navigate by
keyboard alone.
To enable your screen reader to accurately read syntax diagrams, source code
examples, and text that contains the period or comma PICTURE symbols, you
must set the screen reader to speak all punctuation.
Assistive technology products work with the user interfaces that are found in
z/OS. For specific guidance information, see the documentation for the assistive
technology product that you use to access z/OS interfaces.
In addition to standard IBM help desk and support websites, IBM has established
a TTY telephone service for use by deaf or hard of hearing customers to access
sales and support services:
TTY service
800-IBM-3383 (800-426-3383)
(within North America)
For more information about the commitment that IBM has to accessibility, see IBM
Accessibility (www.ibm.com/able).
PL/I supports a single-byte character set (SBCS) and a double-byte character set
(DBCS).
The implementation limits for PL/I language elements are listed in Limits, on
page 869.
Character set 0640 is called the invariant character set because a character from this
set has the same code point in all code pages. A code point is a one-byte code
representing one of 256 potential characters; a code page is an assignment of graphic
characters and control function meanings to all of the code points.
PL/I supports all code pages that conform to character set 0640; however, PL/I
assumes code page 0850 for all code points, except for those characters that are
specified by the programmer using the CURRENCY, NAMES, OR, or NOT
compiler options. For more information about these options, refer to the
Programming Guide.
Code page 0850 contains the English alphabet, ten decimal digits, special
characters, and other national language and control characters. Constants and
comments can contain any SBCS character value. PL/I elements (for example,
statements, keywords and delimiters) are limited to the characters described in the
following sections.
Alphabetic characters
There are 26 base alphabetic characters that comprise the English alphabet. They
are shown in Table 1 with the equivalent ASCII and EBCDIC values in hexadecimal
notation.
Table 1. Alphabetic equivalents
EBCDIC EBCDIC ASCII ASCII
Uppercase Hex Lowercase Hex Uppercase Hex Lowercase Hex
Character Value Value Value Value
A C1 81 41 61
B C2 82 42 62
Extralingual characters
The default extralingual characters are the number sign (#), the at sign (@), and the
currency sign ($). The hexadecimal values for these characters vary across code
pages. You can use the NAMES compiler option to define your own extralingual
characters. For more information about defining extralingual characters, refer to the
Programming Guide.
Alphanumeric characters
An alphanumeric character is either an alphabetic or extralingual character, or a
digit.
Decimal digits
PL/I recognizes the ten decimal digits, 0 through 9. They are also known simply as
digits and are used to write decimal constants and other representations and
values.
The following table shows the digits and their hexadecimal values.
Table 2. Decimal digit equivalents
Character EBCDIC Hex Value ASCII Hex Value
0 F0 30
1 F1 31
2 F2 32
3 F3 33
4 F4 34
5 F5 35
6 F6 36
7 F7 37
8 F8 38
9 F9 39
Binary digits
PL/I recognizes the two binary digits, 0 and 1. They are also known as bits and
are used to write binary and bit constants.
Hexadecimal digits
PL/I recognizes the 16 hexadecimal digits, 0 through 9 and A through F. A through
F represent the decimal values 10 through 15, respectively. They are also known as
hex digits or just hex and are used to write constants in hexadecimal notation.
Special characters
This topic shows the special characters, their PL/I meanings, and their ASCII and
EBCDIC values in hexadecimal notation.
Table 3. Special character equivalents
Default EBCDIC Default ASCII
Character Meaning Hex value Hex value
b Blank 40 20
= Equal sign or assignment symbol 7E 3D
+ Plus sign 4E 2B
- Minus sign 60 2D
* Asterisk or multiply symbol 5C 2A
/ Slash or divide symbol 61 2F
( Left parenthesis 4D 28
) Right parenthesis 5D 29
, Comma 6B 2C
. Point or period 4B 2E
' Single quotation mark 7D 27
" Double quotation mark1 7F 22
% Percent 6C 25
; Semicolon 5E 3B
Composite symbols
You can combine special characters to create composite symbols.
The following table describes these symbols and their meanings. Composite
symbols cannot contain blanks.
Table 4. Composite symbol description
Composite symbol Meaning
{ Concatenation
** Exponentiation
< Not less than
> Not greater than
1
= or <> Not equal to; Evaluate, exclusive-or and assign
<= Less than or equal to
>= Greater than or equal to
/* Start of a comment
*/ End of a comment
> Locator (pointers and offsets)
=> Locator (handles)
+= Evaluate expression, add and assign
-= Evaluate expression, subtract and assign
*= Evaluate expression, multiply and assign
/= Evaluate expression, divide and assign
|= Evaluate expression, or and assign
&= Evaluate expression, and, and assign
{= Evaluate expression, concatenate and assign
**= Evaluate expression, exponentiate and assign
(: Start of type function parameter list
:) End of type function parameter list
Case sensitivity
You can use a combination of lowercase and uppercase characters in a PL/I
program.
When used in keywords or identifiers, the lowercase characters are treated as the
corresponding uppercase characters. This is true even if you entered a lowercase
character as a DBCS character.
Identifiers
An identifier is a series of characters that are not contained in a comment or a
constant.
Except for P, PIC, and PICTURE, identifiers must be preceded and followed by a
delimiter. (P, PIC, and PICTURE identifiers can be followed by a character string.)
The first character of an identifier must be an alphabetic or extralingual character.
If the identifier names an INTERNAL symbol, it can also use the break (_)
character as its first character. Other characters, if any, can be alphabetic,
extralingual, digit, or the break (_) character. External user names must not start
with IBM, PLI, CEE, _IBM, _PLI, and _CEE.
PL/I keywords:
Keywords can specify such things as the action to be taken or the attributes of
data. For example, READ, DECIMAL, and ENDFILE are keywords. Some
keywords can be abbreviated. The keywords and their abbreviations are shown in
uppercase letters.
Programmer-defined names:
In a PL/I program, names are given to variables and program-control data. There
are also built-in names, condition names, and generic names.
Any identifier can be used as a name. A name can have only one meaning in a
program block; the same name cannot be used for both a file and a floating-point
variable in the same block.
To improve readability, the break character (_) can be used in a name, such as
Gross_Pay.
Record Loop_3
Table 6. Operators
Operator type Character(s) Description
Arithmetic + Addition or prefix plus
- Subtraction or prefix minus
* Multiplication
/ Division
** Exponentiation
Comparison = Equal to
= or <> Not equal to
< Less than
< Not less than
> Greater than
> Not greater than
<= Less than or equal to
>= Greater than or equal to
Logical Not, Exclusive-or
& And
| Or
String { Concatenation
The characters used for delimiters can be used in other contexts. For example, the
period is a delimiter when used in name qualification (for example,
Weather.Temperature), but is a decimal point in an arithmetic constant (for
example, 3.14).
Blanks
One or more blanks must separate identifiers and constants that are not separated
by some other delimiter. The only exception to this rule is that the identifiers P,
PIC and PICTURE can be followed by a character string without any intervening
blanks. Any number of blanks can appear wherever one blank is allowed.
ab+bc is equivalent to Ab + Bc
Table(10) is equivalent to TABLEb(b10bbb)
First,Second is equivalent to first,bsecond
AtoB is not equivalent to AbtobB
Other cases that require or allow blanks are noted where those language features
are discussed.
Comments
/* */
text
Comments cannot be nested. However, the %DO SKIP: statement can be used as a
way of "commenting out" code that contains comments.
Statements
You use identifiers, delimiters, operators, and constants to construct PL/I
statements.
Although your source program consists of a series of records or lines, PL/I views
the program as a continuous stream of characters. There are few restrictions in the
format of PL/I statements, and programs can be written without considering
special coding rules or checking to see that each statement begins in a specific
column. A statement can begin in the next position after the previous statement, or
it can be separated by any number of blanks.
Some statements begin with a % symbol. These statements are either %directives
that direct preprocessor and compiler operations (controlling listings, including
program source text from a library, and so on) or are PL/I macro facility
%statements. A %directive must be on a line by itself.
The PL/I statements, macro facility %statements, and the %directives are
alphabetically listed in Chapter 8, Statements and directives, on page 211.
Syntax for a PL/I statement
condition-prefix label-prefix statement
%
statement
%
label-prefix statement
label-prefix statement
Every statement must be contained within some enclosing group or block. Macro
statements must be contained within some enclosing macro group or procedure.
condition-prefix
A condition prefix specifies the enabling or disabling of a PL/I condition (see
Chapter 15, Condition handling, on page 371).
label-prefix
A label prefix is one or more statement labels. It identifies a statement so that it
can be referred to at some other point in the program. Statement labels are
either label constants (see Label data and LABEL attribute on page 47), entry
constants (see Entry data on page 119), or format constants (see Format data
and FORMAT attribute on page 48).
Any statement, except DECLARE, DEFAULT, WHEN, OTHERWISE, and ON
statements, can have a label prefix. Use the following syntax for a label prefix.
identifier :
The syntax for individual statements throughout this book generally does not
show the condition prefix or the label prefix.
statement
A simple or a compound statement.
Simple statements
The types of simple statements are keyword, assignment, and null.
Keyword statement
A keyword statement is a statement that begins with a keyword. This
keyword indicates the function of the statement.
In the following example, READ and DECLARE are keywords.
read file(In) into(Input); /* keyword statement */
%declare Text char; /* keyword %statement */
Assignment statement
An assignment statement contains one or more identifiers on the left side of
the assignment symbol (=) and an expression on the right. It does not
begin with a keyword. See the following examples:
A = B + C; /* assignment statement */
%Size = 15; /* % assignment statement */
Null statement
A null statement consists of only a semicolon and is a nonoperational
statement. See the following examples:
; /* null statement */
Label:; /* labeled null statement */
% ; /* % null statement */
Compound statements
Compound statements are all keyword statements. Each begins with a keyword
that indicates the purpose of the statement. A compound statement contains one or
more simple or compound statements.
There are four compound statements: IF, ON, WHEN, and OTHERWISE. A
compound statement is terminated by the semicolon that also terminates the final
statement of the compound statement.
call Print;
end;
end;
Groups
Statements can be contained within larger program units called groups.
When a group is used in a compound statement, control either flows into the
group or bypasses it, effectively treating the group as if it were a single statement.
Every group must be contained within some enclosing group or block. Groups can
contain none, one, or more statements, groups, or blocks.
In particular, you can use DBCS characters in the source program in following
places:
v inside comments
v as part of statement labels and identifiers
v in G or M literals
However, INCLUDE file names and the TITLE option of FETCH statements must
be in SBCS.
DBCS identifiers
DBCS identifiers can be composed of single-byte characters in DBCS form,
double-byte characters, or a combination of both.
Notes:
1. This book uses the symbol . (bold period) to represent the first byte of a
double-byte character that can also be represented as SBCS.
2. This book uses kk to represent a double-byte character.
3. This book uses < to represent a shift-out character ('0E'X).
4. This book uses > to represent a shift-in character ('0F'X).
Example
<.I.B.M> = 3; /* is the same as IBM=3; */
SBCS characters expressed in DBCS form within a DBCS identifier are considered
to be SBCS. See the following example:
A<kk>B
A<kk.B>
<.Akk>B /* are all A<kk>B (SBCS-DBCS-SBCS) */
When DBCS identifiers are used for EXTERNAL names and %INCLUDE file
names, you must ensure that the identifiers are acceptable to the operating system,
or are made acceptable by using the EXTERNAL attribute with an
environment-name or by using the TITLE option of the OPEN statement.
Related information:
EXTERNAL attribute
The INTERNAL and EXTERNAL attributes define the scope of a name.
OPEN statement on page 305
The OPEN statement associates a file with a data set. It merges attributes specified
on the OPEN statement with those specified on the DECLARE statement. It also
completes the specification of attributes for the file, if a complete set of attributes
has not been declared for the file being opened.
Definitions of the language elements in this section and general usage rules appear
in corresponding sections in Statement elements for SBCS on page 5.
The following list shows the language elements that can be coded in DBCS. It
includes an explanation of the rules and examples of usage.
Identifiers
Use SBCS, DBCS, or both.
dcl Eof /* in SBCS, is the same as */
dcl <.E.o.f> /* this in DBCS. */
G literals can start and end with DBCS quotes, and in that case, the G itself
can also be specified in DBCS. So, the following are all equivalent.
<.a.b.c>G
<..a.b.c.>G
<..a.b.c..G>
Data items
A data item is either the value of a variable or a constant. (These terms are not
exactly the same as in general mathematical usage. They are discussed further in
the next section.)
Data items can be single items, called scalars, or they can be a collection of items,
called data aggregates.
Data aggregates are groups of data items that can be referred to either collectively
or individually. The kinds of data aggregates are arrays, structures, and unions. You
can use any type of computational or program-control data to form a data
aggregate.
Related information:
Arrays on page 184
An array is an n-dimensional collection of elements that have identical attributes.
Structures on page 188
A structure is a collection of member elements that can be structures, unions,
elementary variables, and arrays.
Unions on page 189
A union is a collection of member elements that overlay each other, occupying the
same storage. The members can be structures, unions, elementary variables, and
arrays. They need not have identical attributes.
Combinations of arrays, structures, and unions on page 198
Specifying the dimension attribute on a structure or union results in an array of
structures or an array of unions, respectively. The elements of such an array are
structures or unions having identical names, levels, and members.
Variables
A variable has a value or values that might change during execution of a program.
Constants
A constant has a value that cannot change. Constants for computational data are
referred to by stating the value of the constant or by naming the constant in a
DECLARE statement.
For more information about declaring named constants, see Named constants on
page 45.
Examples
Shakespeares "Hamlet" is identical to
"Shakespeares ""Hamlet"""
Note: The syntax diagrams in this book show single quotation marks. Double
quotation marks can be substituted unless otherwise noted.
Punctuating constants
To improve readability, arithmetic, bit, and hexadecimal constants can use the
break character ( _ ).
Example
Area = (Radius**2) * 3.1416;
Area and Radius are coded arithmetic variables of computational data. The
numbers 2 and 3.1416 are coded arithmetic constants of computational data.
If the number 3.1416 is used in more than one place in the program, or if it
requires specific data or precision attributes, you must declare it as a named
constant. Thus, the above statement can be coded as follows:
dcl Pi FIXED DECIMAL (5,4) VALUE(3.1416);
area = (radius**2) * Pi;
Attributes
To work with a data item, PL/I needs to know the type of data and how to
process it. Attributes provide this information. The kinds of attributes are data
attributes and nondata attributes.
Data attributes
Data attributes describe computational data, program-control data, and program
characteristics.
Nondata attributes
Nondata attributes describe nondata elements (for example, built-in functions) or
provide additional description for elements that have other data attributes.
For example, the keyword CHARACTER is a data attribute for the string type of
computational data. The keyword FILE is a data attribute for the file type of
program-control data. The INTERNAL scope attribute specifies that the data item
is known only within its declaring block.
For the details on using keywords and expressions to specify the attributes, see
Chapter 7, Data declarations, on page 159. Briefly, you specify attributes in one
of the following ways:
v Explicitly, using a DECLARE statement
v Contextually, letting PL/I determine them
v By using programmer-defined or language-specified defaults
Table 7 on page 19 and Table 8 on page 21 help you correlate PL/I's variety of
attributes with its variety of computational and program-control data types. The
tables show that the constants and the named constants can only have the
indicated data and scope attributes (Table 7 on page 19). Variables can specify
additional attributes (Table 8 on page 21).
(See the Coded arithmetic row, and Data Attributes and Scope Attributes
columns of Table 7.)
The constant 1.0 (a decimal fixed-point constant) is different from the constants 1
(another decimal fixed-point constant), '1'B (a bit constant), '1' (a character
constant), 1B (binary fixed-point constant), or 1E0 (a decimal floating-point
constant).
Because this DECLARE statement contains no other attributes for Pi, PL/I applies
the defaults for the remaining attributes:
v REAL from the Data Attributes column
v ALIGNED from the Alignment Attributes column
v INTERNAL from the Scope Attributes column
v AUTOMATIC from the Storage Attributes column
v SIGNED from the Data Attributes column
FLOAT | FIXED
BINARY | DECIMAL
PRECISION
SIGNED
Named coded arithmetic REAL | COMPLEX internal
FLOAT | FIXED
BINARY | DECIMAL
PRECISION
VALUE
SIGNED | UNSIGNED
GRAPHIC | WIDECHAR
(length)
Named string BIT | CHARACTER | internal
GRAPHIC | WIDECHAR
[(length)]
NONVARYING
VALUE
Named locator POINTER | OFFSET | HANDLE internal
VALUE
LOCATES
Named picture PICTURE | WIDEPIC internal
REAL | COMPLEX
VALUE
Note 3
File FILE ENVIRONMENT INTERNAL | EXTERNAL
STREAM | RECORD
SEQUENTIAL | DIRECT
BUFFERED | UNBUFFEREDNote 4
KEYED
PRINT
EntryNote 5 ENTRY [RETURNS] INTERNAL | EXTERNAL
FormatNote 5 FORMAT internal
LabelNote 5 LABEL internal
Notes:
1. Attributes in this table that appear in uppercase can be explicitly declared. Attributes that are in lowercase are
implicitly given to the data type.
2. Defaults for data attributes are underlined. Because the data attributes for literals are contextual, defaults are not
applicable. Named constants and file constants have selectable attributes, so defaults are shown.
3. File Attributes are described in Chapter 10, Input and output, on page 297.
4. BUFFERED is the default for SEQUENTIAL files. UNBUFFERED is the default for DIRECT files.
5. Format and label constants, and INTERNAL entry constants cannot be declared in a DECLARE statement.
Defined
File FILE variable:
DEFINED
Format FORMAT [POSITION]
Parameter:
Label LABEL PARAMETER
[CONNECTED |
Locator POINTER | HANDLE | NONCONNECTED]
{OFFSET [CONTROLLED]
[(area-variable)]
LOCATES} [INITIAL
[CALL]]
ASSIGNABLE |
String BIT | CHARACTER | NONASSIGNABLE
GRAPHIC | WIDECHAR
[(length)]
[ VARYING |
VARYING4 |
VARYINGZ |
NONVARYING]
See Data types and attributes on page 17 for general information about coded
arithmetic data.
float sequence:
fixed sequence:
UNSIGNED
precision specification:
float precision
PRECISION fixed precision
float precision:
(number-of-digits)
fixed precision:
(number-of-digits )
,scaling-factor
A fixed-point data item is a rational number in which the position of the decimal
or binary point is specified, either by its appearance in a constant or by a scaling
factor declared for a variable.
Floating-point data items are rational numbers in the form of a fractional part and
an exponent part.
PRECISION attribute
The precision of a coded arithmetic data item includes the number of digits and the
scaling factor. (The scaling factor is used only for fixed-point items).
number of digits
An integer that specifies how many digits the value can have. For
fixed-point items, the integer is the number of significant digits. For
floating-point items, the integer is the number of significant digits to be
maintained excluding the decimal point (independent of its position).
scaling factor
An optionally-signed integer that specifies the assumed position of the
decimal or binary point, relative to the rightmost digit of the number. If no
scaling factor is specified, the default is 0.
A negative scaling factor (-q) specifies an integer, with the point assumed to be
located q places to the right of the rightmost actual digit. A positive scaling factor
(q) that is larger than the number of digits specifies a fraction, with the point
assumed to be located q places to the left of the rightmost actual digit. In either
case, intervening zeros are assumed, but they are not stored; only the specified
number of digits is actually stored.
A complex data item consists of two partsa real part and an imaginary part. For
a variable representing complex data items, the base, scale, and precision of the
two parts are identical.
Each of these has a real part of zero. A complex value with a nonzero real part is
represented by an expression with the following syntax:
real_constant + imaginary_constant
+ -
-
SIGNED indicates that the variable can assume negative values. UNSIGNED
indicates that the variable can assume only nonnegative values.
If you are using the RULES(ANS) compiler option, UNSIGNED has the following
effect on the semantics of fixed- point operations:
v The result of an add, multiply, or divide operation is UNSIGNED if both
operands are UNSIGNED.
v The result of MAX or MIN is UNSIGNED if all operands are UNSIGNED.
v The result of REM or MOD is UNSIGNED if all operands are UNSIGNED.
In the following example, Factor is declared as a variable that can represent binary
fixed-point data of 20 data bits, two of which are to the right of the binary point.
declare Factor binary fixed (20,2);
See SIGNED and UNSIGNED attributes on page 25 for information about how
much storage signed and unsigned fixed-binary data occupy.
The declared number of data bits is in the low-order positions, but the extra
high-order bits participate in any operation performed upon the data item. Any
arithmetic overflow into such extra high-order bit positions can be detected only if
the SIZE condition is enabled.
Binary fixed-point constants have a precision (p,q), where p is the total number of
data bits in the constant, and q is the number of bits to the right of the binary
point.
Example
Constant Precision
1011_0B (5,0)
1111_1B (5,0)
101B (3,0)
1011.111B (7,3)
If the constant has 8 or fewer digits, it has a precision of 31; otherwise, it has a
precision of 63.
The hexadecimal value for the XN constant is the value specified padded on the
left with hex zeros if necessary.
If the constant has 8 or fewer digits, it has a precision of 32; otherwise, it has a
precision of 64.
The hexadecimal value for the XU constant is the value specified padded on the
left with hex zeros if necessary.
For example, the following DECLARE statement specifies that A represents decimal
fixed-point data of 5 digits, 4 of which are to the right of the decimal point.
declare A fixed decimal (5,4);
The following example specifies that C has a scaling factor of -2. This means that C
holds 7 digits in the range -9999999*100 - 9999999*100, in increments of 100.
declare C fixed (7,-2) decimal;
Decimal fixed-point data is stored two digits per byte, with a sign indication in the
rightmost 4 bits of the rightmost byte. Consequently, a decimal fixed-point data
item is always stored as an odd number of digits, even though the declaration of
the variable can specify the number of digits, p, as an even number.
When the declaration specifies an even number of digits, the extra digit place is in
the high-order position, and it participates in any operation performed upon the
data item, such as in a comparison operation. If the extra high-order digit place is
nonzero, the use of the data in arithmetic operation or assignment may produce an
exception. Any arithmetic overflow or assignment into an extra high-order digit
place can be detected only if the SIZE condition is enabled.
Decimal fixed-point constants have a precision (p,q), where p is the total number of
digits in the constant and q is the number of digits specified to the right of the
decimal point.
Examples
Constant Precision
3.1416 (5,4)
455.3 (4,1)
732 (3,0)
1_200_300 (7,0)
003 (3,0)
5280 (4,0)
.0012 (4,4)
The exponent cannot exceed five decimal digits. If the declared precision is less
than or equal to (21), short floating-point form is used. If the declared precision is
greater than (21) and less than or equal to (53), long floating-point form is used. If
the declared precision is greater than (53), extended floating-point form is used.
The last five examples represent the same value (although with different
precisions).
For IEEE Decimal Floating Point (DFP), decimal floating-point literals, when
converted to "right-units-view", that is, when the exponent has been adjusted, if
needed, so that no nonzero digits follow the decimal point (for example, as would
be done when viewing 3.1415E0 as 31415E-4), must have an exponent within the
range of the normal numbers for the precision given by the literal. These bounds
are given by the value of MINEXP-1 and MAXEXP-PLACES. In particular, the
following must hold:
v For short float, -95 <= exponent <= 90
v For long float, -383 <= exponent <= 369
v For extended float, -6143 <= exponent <= 6111
So, for IEEE Decimal Floating Point (DFP), the largest positive short decimal
floating-point literal is 9999999E90 (or .9999999E97), and the smallest positive
nonzero short decimal floating-point literal is 1E-95.
Rather than trying to specify the largest positive floating point value as a literal,
you should use the HUGE built-in function for this purpose. Similarly, to specify
the smallest nonzero positive value, you should use the TINY built-in function.
See Data types and attributes on page 17 for general information about strings.
The WIDECHAR attribute specifies a widechar variable which will hold UTF-16
data.
NONVARYING
BIT (length )
CHARACTER REFER(variable) VARYING
GRAPHIC (*)
WIDECHAR VARYING4
VARYINGZ
length
Specifies the length of a NONVARYING string or the maximum length of a
VARYING, VARYING4, or VARYINGZ string. The length is in bits, characters,
widechars or graphics (DBCS characters), as appropriate.
You can specify the length as an expression or as an asterisk. If the length is
not specified, the default is 1. For named constants, length is determined from
the length of the value expression.
For a parameter, an expression is valid only if it is CONTROLLED. An asterisk
specification for a parameter indicates that the length is taken from the
argument that is passed.
If the length specification is an expression, it is evaluated and converted to a
FIXED BINARY(31,0) value, which must be nonnegative, when storage is
allocated for the variable.
For STATIC data, length must be a restricted expression.
For information about specifying the length of the BASED data, see Extent
specifications in BASED declarations on page 261.
REFER
See REFER option (self-defining data) on page 269 for the description of the
REFER option.
Examples
The following statement declares User as a variable that can represent character
data with a length of 15:
declare User character (15);
The storage allocated for VARYING strings is 2 bytes longer than the declared
length. The leftmost 2 bytes hold the string's current length.
The storage allocated for VARYING4 strings is 4 bytes longer than the declared
length. The leftmost 4 bytes hold the string's current length.
The storage allocated for a VARYINGZ character string is 1 byte longer than the
declared length. The current length of the string is equal to the number of bytes
before the first 00x in the storage allocated to it.
The storage allocated for a VARYINGZ GRAPHIC string is 2 bytes longer than the
declared length. The current length of the string is equal to half the number of
bytes before the first 0000gx in the storage allocated to it.
The storage allocated for a VARYINGZ WIDECHAR string is 2 bytes longer than
the declared length. The current length of the string is equal to half the number of
bytes before the first 0000wx in the storage allocated to it.
The length for User and Zuser at any time is the length of the data item assigned
to it at that time. You can determine the declared and the current length by using
the MAXLENGTH and LENGTH built-in functions, respectively.
The VARYING, VARYING4, and VARYINGZ strings can be passed and received as
parameters with * length. They can be passed without a descriptor if they have the
NONASSIGNABLE attribute.
A picture character specifies a category of characters that can occupy that position.
Syntax
Abbreviation PIC
picture-specification
Describes either a character data item or a numeric character data item. The
picture specification must be followed by a picture specification. See Picture
characters for character data on page 356 or Picture characters for numeric
character data on page 357 for the valid characters.
You can use WIDEPIC in the same way as you use PICTURE except that the
following additional rules apply to WIDEPIC:
v The picture specification must specify an arithmetic picture, so the specification
must not contain the A or X symbol.
v The picture specification must not contain any currency symbols or overpunch
symbols.
Character data
Data with the CHARACTER attribute can contain any of the 256 characters
supported by the character set. Data with the PICTURE attribute must have
characters that match the picture-specification characters.
Character constant
A character constant is a contiguous sequence of characters enclosed in single or
double quotation marks.
Quotation marks included in the constant follow the rules listed in Using
quotation marks on page 16. The length of a character constant is the number of
characters between the enclosing quotation marks counting any doubled quotation
marks as a single character.
Syntax
' '
character
In the last example, the number in parentheses is a string repetition factor, which
indicates repetition of the characters that follow. This example is equivalent to the
constant "Walla Walla ". The string repetition factor must be a constant and
enclosed in parentheses.
Syntax
' 'A
character
character
All characters in an A character constant must be code page invariant and
occupy only one byte if converted to UTF-8.
Example
Syntax
' 'E
character
character
All characters in an E character constant must be code page invariant and
occupy only one byte if converted to UTF-8.
Example
Syntax
' 'X
hex-digit hex-digit
Bit data
Data with the BIT attribute allows manipulation of storage in terms of bits. Each
byte of storage is composed of 8 bits.
Bit constant
A bit constant is a contiguous sequence of binary digits enclosed in single or
double quotation marks and followed immediately by the letter B.
Syntax
' 'B
binary-digit
The number in parentheses in the third example is a string repetition factor which
specifies that the following series of bits is repeated the specified number of times.
The example shown would result in a string of 64 zero bits.
Syntax
' ' B4
hex-digit BX
Graphic data
GRAPHIC data can contain any DBCS character. Each DBCS character occupies 2
bytes of storage.
Graphic constant
A graphic constant is a contiguous sequence of DBCS characters enclosed in single
or double quotation marks. Graphic constants take up 2 bytes of storage for each
DBCS character in the constant.
G literals can start and end with DBCS quotes; in this case, the G itself can also be
specified in DBCS.
Syntax
'< >'G
kk
Syntax
' 'GX
hex-digit hex-digit hex-digit hex-digit
The CHARGRAPHIC option of the OPTIONS attribute and the MPSTR built-in
function can be used to assist in mixed data handling. For more information about
CHARGRAPHIC, see OPTIONS option and attribute on page 135; for
information about MPSTR, see MPSTR on page 615.
Quotations marks included in the constant follow the rules listed in Using
quotation marks on page 16. The length of an M constant is the number of SBCS
characters between the enclosing quotation marks counting any doubled quotation
marks as a single character, plus twice the number of DBCS characters in the
string.
Syntax
' 'M
character
<kk>
Note: Because shift-codes are used only on z/OS, the use of mixed data and M
constants can limit program portability.
Widechar data
WIDECHAR data can contain any UTF-16 character. Each widechar occupies 2
bytes of storage.
Syntax
' 'WX
hex-digit hex-digit hex-digit hex-digit
Notes:
v WX constants should be specified in bigendian format (even if the program will
run in littleendian format). So, for example, the widechar value for the character
'1' should always be specified as '0031'wx (and not as '3100'wx).
v The use of WX can limit the portability of a program.
Numeric picture specification describes a character string that can be assigned only
data that can be converted to an arithmetic value.
This declare specifies that any value assigned to Price is maintained as a character
string of five decimal digits, with an assumed decimal point preceding the
rightmost two digits. Data assigned to Price is aligned on the assumed point in
the same way that point alignment is maintained for fixed-point decimal data.
Numeric character data has arithmetic attributes, but it is not stored in coded
arithmetic form. Numeric character data is stored as a character string. Before it
can be used in arithmetic computations, it must be converted either to decimal
fixed-point or to decimal floating-point format. Such conversions are done
automatically, but they require extra processing time.
Although numeric character data is in character form, like character strings, and
although it is aligned on the decimal point like coded arithmetic data, it is
processed differently from the way either coded arithmetic items or character
strings are processed. Editing characters can be specified for insertion into a
numeric character data item, and such characters are actually stored within the
data item. Consequently, when the item is printed or treated as a character string,
the editing characters are included in the assignment operation. However, if a
numeric character item is assigned to another numeric character or arithmetic
variable, the editing characters are not included in the assignment operationonly
the actual digits, signs, and the location of the assumed decimal point are assigned.
Consider the following example:
In the picture specification for PRICE, the currency symbol ($) and the decimal
point (.) are editing characters. They are stored as characters in the data item.
However, they are not a part of its arithmetic value. After both assignment
statements are executed, the actual internal character representation of Price and
Cost can be considered identical. If they were printed, they would print exactly the
same; but they do not always function in the same way. Consider the following
example:
Amount = Price;
Cost = Price;
Amount = Cost;
Price = Cost;
After the first two assignment statements are executed, the value of Amount is
0012.28 and the value of Cost is '$12.28'. In the assignment of Price to Amount, the
currency symbol and the decimal point are editing characters, and they are not
part of the assignment. The numeric value of Price is converted to internal coded
arithmetic form. In the assignment of Price to Cost, however, the assignment is to
a character string, and the editing characters of a numeric picture specification
always participate in such an assignment. No conversion is necessary because
Price is stored in character form.
The third and fourth assignment statements would raise the CONVERSION
condition. The value of Cost cannot be assigned to Amount because the currency
symbol in the string makes it invalid as an arithmetic constant. The value of Cost
cannot be assigned to Price for the same reason. Only values that are of arithmetic
type, or that can be converted to arithmetic type, can be assigned to a variable
declared with a numeric picture specification.
Date attribute
Implicit date comparisons and conversions are made by the compiler if the two
operands have the DATE attribute. The DATE attribute specifies that a variable (or
argument or returned value) holds a date with a specified pattern.
Syntax
DATE
('pattern')
pattern
One of the supported date patterns. If you do not specify a pattern, YYMMDD
is the default.
The DATE attribute is valid only with variables having one of the following sets of
attributes:
v CHAR(n) NONVARYING
v PIC'(n)9' REAL
v FIXED DEC(n,0) REAL
When you specify the RESPECT compile-time option (see the Programming Guide
for details), the following occurs:
v The compiler knows to honor the DATE attribute.
v The DATE built-in function returns a value that has the attribute
DATE('YYMMDD').
The DATE attribute causes implicit commoning when two variables declared with
the DATE attribute are compared. Comparisons where only one variable has the
DATE attribute are flagged, and the other comparand is generally treated as if it
had the same DATE attribute, although some exceptions apply which are discussed
later.
Implicit commoning means that the compiler generates code to convert the dates to
a common, comparable representation. This process converts 2-digit years using
the window you specify in the WINDOW compile-time option.
In the following code fragment, if the DATE attribute is honored, the comparison
in the second display statement is 'windowed'. This means that if the window
started at 1900, the comparison would return false. However, if the window started
at 1950, the comparison would return true.
dcl a pic(6)9 date;
dcl b pic(6)9 def(a);
dcl c pic(6)9 date;
dcl d pic(6)9 def(c);
b = 670101;
d = 010101;
display( b || < || d || ? );
display( a < c );
Under some conditions, the compiler does not generate any special code to
compare dates with identical patterns.
For comparisons involving dates with unlike patterns, the compiler generates code
to convert the dates to a common comparable representation.
When the conversion has taken place, the compiler compares the two values.
If you are making comparisons in which one comparand has the DATE attribute
and the other is a literal, the compiler issues a W-level message.
In comparisons where one comparand has the DATE attribute and the other is not
a date and not a literal, the compiler issues an E-level message. The non-date value
is treated as if it had the same date pattern as the other comparand and as if it had
the same window.
dcl start_date char(6) date;
dcl non_date char (6);
The DATE attribute can also cause implicit conversions to occur in assignments of
two variables declared with date patterns.
v If the source and target have the same DATE and data attributes, then the
assignment proceeds as if neither had the DATE attribute.
v If the source and target have differing DATE attributes, then the compiler
generates code to convert the source date before making the assignment.
v In assignments where the source has the DATE attribute but the target does not,
the compiler issues an E-level message and ignores the DATE attribute.
v In assignments where the target has the DATE attribute but the source does not
(and the source IS NOT a literal), the compiler issues an E-level message and
ignores the DATE attribute.
v In assignments where the target has the DATE attribute but the source does not
(and the source IS a literal), the compiler issues a W-level message and ignores
the DATE attribute.
dcl start_date char(6) date;
start_date = ;
...
v If the source holds a four-digit year and the target holds a two-digit year, the
source can hold a year that is not in the target window. In this case, the ERROR
condition is raised.
dcl x char(6) date;
dcl y char(8) date(YYYYMMDD);
y = 20600101;
Even if you do not choose a windowing solution, you might have some code that
needs to manipulate both two- and four-digit years. You can use multiple date
patterns to help you in these situations:
dcl old_date char(6) date(YYMMDD);
dcl new_date char(8) date(YYYYMMDD);
new_date = old_date;
Date diagnostics:
In all of the cases listed previously, code is produced but no windowing occurs. In
effect, the DATE attribute is ignored.
Named constants
Named constants can be declared for scalars or structures.
As a scalar identifier, a named constant is declared with the VALUE attribute along
with other data attributes. All references to the name are logically treated as a
reference to the appropriate constant but with the complete set of attributes,
whether explicitly declared or defaulted.
A structure can define a namespace of named constants, when the VALUE attribute
is specified on the leaf elements, and the references to the members of all structure
elements are unambiguous. You can specify the elements of a structure with the
VALUE attribute, provided that the structure meets all of the following conditions:
v All leaf elements of the structure have the VALUE attribute.
v The structure contains no arrays or unions.
v The structure has no storage attributes such as AUTOMATIC.
Note: The effect of the use of a named constant might not be exactly the same as
the use of an unnamed constant. The attributes for a named constant are taken
from the declaration which includes explicit and default attributes. The attributes
for an unnamed constant are deduced from the shape, form, and size of the
constant. For string data, if the length is not specified, or is specified with an
asterisk, the length is determined from the length of the restricted expression.
Named constants can be more precise to use in an application program, and they
can offer more predictable results. For example, if the named constant Unit is
defined as FIXED BINARY VALUE(1), it has the attributes FIXED BINARY(15)
VALUE(1). If you simply use the digit 1, its attributes are FIXED DECIMAL(1,0).
See Figure 1 on page 46 for other differences that can occur.
Named constants can be declared for arithmetic data, string data, and for pointers
and offsets. A named constant must be declared before it is used.
Related information:
String data and attributes on page 30
This section describes string data types and attributes.
Coded arithmetic data and attributes on page 22
This topic provides the syntax for coded arithmetic data and lists coded arithmetic
data attributes and their abbreviations.
VALUE attribute:
This topic describes the VALUE attribute and shows its syntax.
VALUE(restricted-expression)
restricted expression
The expression must evaluate to a scalar value.
Related information:
Named constants can be used wherever a constant is required. They can also be
used in restricted expressions that appear later in the program allowing evaluation
of a dependent constant.
Figure 1 shows named constants and the differences in attributes and precisions
that can occur between named and unnamed constants.
/* Differences in attributes/results of
named and unnamed constants */
Syntax
LABEL
,
( label-constant )
If a list of label constants is given, the variable must always have as its value a
member of that list, and the label constants in the list must be known in the block
containing the label declaration. The parenthesized list of label constants can be
used in a LABEL attribute specification for a label array.
A label constant is a name written as the label prefix of a statement (other than
PROCEDURE, ENTRY, PACKAGE, or FORMAT) so that during execution,
program-control can be transferred to that statement through a reference to it.
(Statements on page 8 discusses the syntax of the label prefix.)
A label variable can have another label variable or a label constant assigned to it.
When such an assignment is made, the environment of the source label is assigned
to the target. If you declare a static array of labels to have initial values, the array
is treated as nonassignable.
A label variable used in a GO TO statement must have as its value a label constant
that is used in a block that is active at the time the GO TO is executed. Consider
the following example:
declare Lbl_x label;
Lbl_a: statement;
.
.
.
Lbl_b: statement;
.
.
.
Lbl_x = Lbl_a;
.
.
.
go to Lbl_x;
Lbl_a and Lbl_b are label constants, and Lbl_x is a label variable. By assigning
Lbl_a to Lbl_x, the statement GO TO Lbl_x transfers control to the Lbl_a statement.
Elsewhere, the program can contain a statement assigning Lbl_b to Lbl_x. Then,
any reference to Lbl_x would be the same as a reference to Lbl_b. This value of
Lbl_x is retained until another value is assigned to it.
If Z(2) is omitted, GO TO Z(I) when I=2 raises the ERROR condition. GO TO Z(I)
when I < LBOUND(Z) or I > HBOUND(Z) causes unpredictable results if the
SUBSCRIPTRANGE condition is disabled.
FORMAT
A name declared with the FORMAT attribute can have another format variable or
a format constant assigned to it. When such an assignment is made, the
environment of the source label is assigned to the target.
A second example indicates that 4 and 5 have the same effect as 2, and 6
and 7 have the same effect as 3.
1 dcl Print format;
2 put edit (X,Y,Z) (R(Prntexe) );
3 put edit (X,Y,Z) (R(Prntstf) );
4 Print = Prntexe;
5 put edit (X,Y,Z) (R(Print) );
6 Print = Prntstf;
7 put edit (X,Y,Z) (R(Print) );
VARIABLE attribute
The VARIABLE attribute establishes the name as a variable and should be
specified only along with one of the attributes: ENTRY, FILE or LABEL. It will be
ignored in all other declares.
VARIABLE
In the following declaration, Account1 and Account2 are file variables and File1
and File2 are file constants.
declare Account1 file variable,
Account2 file automatic,
File1 file,
File2 file;
The constants and variables of an operational expression are called operands. See
Operational expressions on page 55 for more information.
The following diagram shows the syntax for expressions and references.
unary-expression
(1)
infix-operator unary-expression
unary-expression:
elementary-expression
(1)
prefix-operator
elementary-expression:
(expression)
reference
constant
reference:
(2)
locator-qualifier basic-reference
(3)
( subscript-list )
(4)
( argument-list )
locator-qualifier:
(2)
reference ->
=>
.
basic-reference:
(5) (6)
qualified-reference identifier
subscript-list:
,
(3)
expression
*
argument-list:
,
(4)
expression
*
qualified-reference:
(5)
basic-reference .
( subscript-list )
Notes:
1 Operators are shown in Table 6 on page 7.
2 Locator-qualifier is described under Locator qualification on page 265 and
Typed structure qualification on page 152.
3 Subscripts are described under Arrays on page 184.
4 Arguments are described in Passing arguments to procedures on page 114.
5 Qualified-reference is described under Structure and union qualification on
page 191.
6 Identifiers are described under Identifiers on page 5.
An array expression
Represents an array of values. This definition includes a member of a
structure or union that has the dimension attribute.
A structure expression
Represents a structured set of values.
The syntax of many PL/I statements allows expressions, provided the result of the
expression conforms with the syntax rules. Unless specifically stated in the text
following the syntax specification, the unqualified term expression or reference refers
to a scalar expression. For expressions other than a scalar expression, the type of
expression is noted. For example, the term array expression indicates that a scalar
expression is not valid.
Order of evaluation
PL/I statements often contain more than one expression or reference. Except as
described for specific instances (for example, the assignment statement), evaluation
can be in any order, or (conceptually) at the same time.
The functions Y and Z can change the value of the arguments passed to them.
Hence, the value returned by X might be different depending on which function is
invoked first. You should not presume that the first parameter is evaluated first. In
some situations, it is more optimal to evaluate the last first.
Assuming that the INC function increments the value of the argument passed to it
and returns the updated value, the example that follows could put out B(1,2) or
B(2,1) depending on which subscript is evaluated first. You should not presume
which subscript is evaluated first.
dcl B(2,2);
I = 0;
put list ( B( INC(I), INC(I) ) );
Targets
The results of an expression evaluation or of a conversion are assigned to a target.
Targets can be variables, pseudovariables, or intermediate results.
Variables
Variables can be the target of expression evaluations or conversions.
In the case of an assignment, such as the statement A = B;, the target is the
variable on the left of the assignment symbol (in this case A). Assignment to
variables can also occur in stream I/O, DO, DISPLAY, and record I/O statements.
Pseudovariables
A pseudovariable represents a target field.
Intermediate results
When an expression is evaluated, the target attributes usually are partly derived
from the source, partly from the operation being performed, and partly from the
attributes of a second operand. Some defaults can be used, and some
implementation restrictions (for example, maximum precision) and conventions
exist. An intermediate result can undergo conversion if a further operation is
performed. After an expression is evaluated, the result can be further converted for
assignment to a variable or pseudovariable. These conversions follow the same
rules as the conversion of programmer-defined data.
declare A character(8),
B fixed decimal(3,2),
C fixed binary(10);
A = B + C;
During the evaluation of the expression B + C and during the assignment of that
result, there are four different results:
1. The intermediate result to which the converted binary equivalent of B is
assigned
2. The intermediate result to which the binary result of the addition is assigned
3. The intermediate result to which the converted decimal fixed-point equivalent
of the binary result is assigned
4. A, the final destination of the result, to which the converted character
equivalent of the decimal fixed-point representation of the value is assigned
The attributes of the first result are determined from the attributes of the source B,
from the operator, and from the attributes of the other operand. If one operand of
an arithmetic infix operator is binary, the other is converted to binary before
evaluation.
The attributes of the second result are determined from the attributes of the source
(C and the converted representation of B).
The attributes of the third result are determined in part from the source (the
second result) and in part from the attributes of the eventual target A. The only
attribute determined from the eventual target is DECIMAL (a binary arithmetic
representation must be converted to decimal representation before it can be
converted to a character value).
Operational expressions
An operational expression consists of one or more single operations. A single
operation is either a prefix operation (an operator preceding a single operand) or an
infix operation (an operator between two operands). The two operands of any infix
operation normally should be the same data type when the operation is performed.
There are few restrictions on the use of different data types in an expression.
However, these mixtures imply conversions. If conversions take place at run time,
the program takes longer to run. Also, conversion can result in loss of precision.
When using expressions that mix data types, you must understand the relevant
conversion rules.
The classes of operations include handle, pointer, arithmetic, bit, comparison, and
concatenation.
Handle operations
These handle operations can be used in PL/I programs.
v Compare two handles that have the same associated structure type.
Pointer operations
These pointer operations can be used in PL/I programs.
v Add an expression to or subtract an expression from a pointer expression.
The expression type must be computational. If necessary, the nonpointer
1
operand is converted to size_t . See the following example:
Ptr1 = Ptr1 - 16;
Ptr2 = Ptr1 + (I*J);
You can also use the built-in function POINTERADD to perform these
operations. You must use POINTERADD if the result is used as a locator
reference. For example, (Ptr1 + 16) -> Based_ptr is invalid;
pointeradd(Ptr1,16) -> Based_ptr is valid.
1
v Subtract two pointers to obtain the logical difference. The result is a size_t value.
Diff = Ptr2 - Ptr1;
v Compare pointer expressions using infix operators.
if Ptr2 > Ptr1 then
Diff = Ptr2 - Ptr1;
v Compare pointer expressions to null strings (' ' or ' 'b).
The NULLSTRPTR suboption of the DEFAULT compiler option determines how
the compiler handles assignments of null strings to pointers and comparisons of
null strings to pointers. In both cases, the option determines if the null string is
treated as if it were a reference to the NULL built-in function or to the
SYSNULL built-in function.
For example, if the NULLSTRPTR(SYSNULL) suboption is in effect, the
assignment in the following code assigns SYSNULL() to header, and the
comparison produces a true value if header equals to SYSNULL().
dcl header pointer;
header = ;
...
if header = then...
1. If the LP(32) compiler option is in effect, size_t is FIXED BIN(31); if the LP(64) compiler option is in effect, size_t is FIXED BIN(63).
A PL/I block can use pointer arithmetic to access any element within a structure or
an array variable. However, the block must be passed the containing structure or
array variable, or have the referenced aggregate within its name scope.
Arithmetic operations
An arithmetic operation is specified by combining operands with one arithmetic
operator. Arithmetic operations can also be specified by the ADD, SUBTRACT,
DIVIDE, and MULTIPLY built-in functions.
The plus sign and the minus sign can appear as prefix operators or as infix
operators. All other arithmetic operators can appear only as infix operators.
Prefix operators can precede and be associated with any of the operands of an infix
operation. For example, in the expression A*-B, the minus sign indicates that the
value of A is multiplied by -1 times the value of B.
More than one prefix operator can precede and be associated with a single
variable. More than one positive prefix operator has no cumulative effect, but two
negative prefix operators have the same effect as a single positive prefix operator.
For coded arithmetic operands, you can also determine conversions by using
Table 24 on page 60. Each operand is converted to the type, base, and mode of the
result. It is not necessarily converted to the result's precision and scale.
Note: Scaled FIXED BINARY operands are converted to scaled FIXED DECIMAL
before any operations on them are performed.
Type:
Graphic and widechar variables and strings are allowed in all computational
contexts. If conversion is necessary, the rules followed are the same as for
character.
Base:
If the bases of the two operands differ, the decimal operand is converted to its
binary equivalent.
Mode:
If the modes of the two operands differ, the real operand is converted to complex
mode by acquiring an imaginary part of zero with the same base, scale, and
precision as the real part. But there is an exception.
In the case of exponentiation when the second operand (the exponent of the
operation) is fixed-point real with a scaling factor of zero, conversion is not
necessary.
Precision:
If only precisions and/or scaling factors vary, type conversion is not necessary.
Scale:
If the scales of the two operands differ, the fixed-point operand is converted to
floating-point scale. But there is an exception.
In the case of exponentiation when the first operand is of floating-point scale and
the second operand (the exponent of the operation) is fixed-point with a scaling
factor of zero, that is, an integer or a variable that has been declared with precision
(p,0), conversion is not necessary, but the result is floating-point.
Table 24 on page 60 and Table 25 on page 61 show the attributes and precisions
that result from various arithmetic operations.
Table 29 on page 65 shows the attributes of the result for the special cases of
exponentiation noted in the right-hand columns of Table 24 on page 60 and
Table 25 on page 61.
On the z/OS platform, the choice of which set of instructions is used for a float
calculation is determined by two compiler options:
v Under FLOAT(DFP)
All computations that would yield a FLOAT DEC result are done using the
IEEE decimal floating-point instructions.
All computations that would yield a FLOAT BIN result are done using the
floating-point instructions for the format specified by the HEXADEC and
IEEE suboptions of the DEFAULT compiler option.
v Under FLOAT(NODFP)
All computations that would yield a FLOAT result are done using the
floating-point instructions for the format specified by the HEXADEC and
IEEE suboptions of the DEFAULT compiler option.
On all other platforms, float calculations are done using the IEEE binary
floating-point instructions native to that platform.
Table 24. Results of arithmetic operations for one or more FLOAT operands
Attributes of
the Result
for Addition, Addition Attributes
Subtraction, or of the
1st Operand 2nd Operand Multiplication, Subtraction Multiplication Division Result for
(p1,q1) (p2,q2) or Division Precision Precision Precision Exponentiation
FLOAT FLOAT
DECIMAL DECIMAL
(p1) (p2)
FLOAT
FLOAT FIXED FLOAT DECIMAL (p)
DECIMAL DECIMAL DECIMAL (unless special case
(p1) (p2,q2) (p) C applies)
p = MAX(p1,p2)
FIXED FLOAT
DECIMAL DECIMAL
(p1,q1) (p2)
p = MAX(p1,p2)
FLOAT FLOAT
BINARY BINARY
(p1) (p2)
FLOAT
FLOAT FIXED FLOAT BINARY (p)
BINARY BINARY BINARY (unless special case
(p1) (p2,q2) (p) C applies)
p = MAX(p1,p2)
FIXED FLOAT
BINARY BINARY
(p1,q1) (p2)
FIXED FLOAT
DECIMAL BINARY
(p1,q1) (p2)
FLOAT
BINARY (p)
FLOAT FIXED FLOAT
p = MAX( (unless special case
DECIMAL BIN BINARY
CEIL(p1*3.32),p2) A or C applies)
(p1) (p2,q2) (p)
p = MAX(
CEIL(p1*3.32),p2)
FLOAT FLOAT
DECIMAL BINARY
(p1) (p2)
FIXED FLOAT
BINARY DECIMAL
(p1,q1) (p2)
FLOAT
BINARY (p)
FLOAT FIXED FLOAT
(unless special case
BINARY DECIMAL BINARY p = MAX(p1,CEIL(p2*3.32))
B or C applies)
(p1) (p2,q2) (p)
p = MAX(
p1,CEIL(p2*3.32))
FLOAT FLOAT
BINARY DECIMAL
(p1) (p2)
Notes:
1. Special cases of exponentiation are described in Table 29 on page 65.
2. For a table of CEIL(N*3.32) values, see Table 34 on page 80.
Table 25. Results of arithmetic operations between two unscaled FIXED operands under RULES(ANS)
Attributes of
the Result for
Addition, Addition Attributes
Subtraction, or of the
1st Operand 2nd Operand Multiplication, Subtraction Multiplication Division Result for
(p1,q1) (p2,q2) or Division Precision Precision Precision Exponentiation
Notes:
Table 26. Results of arithmetic operations between two scaled FIXED operands under RULES(ANS)
Attributes of
the Result for
Addition, Addition Attributes
Subtraction, or of the
1st Operand 2nd Operand Multiplication, Subtraction Multiplication Division Result for
(p1,q1) (p2,q2) or Division Precision Precision Precision Exponentiation
p = 1 +
p = 1 FLOAT DECIMAL (p)
FIXED FIXED FIXED MAX(p1-q1, p = N
+p1+p2 (unless special case
DECIMAL DECIMAL DECIMAL p2-q2) +q q =
q = A applies)
(p1,q1) (p2,q2) (p,q) q = N-p1+q1-q2
q1+q2 p = MAX(p1,p2)
MAX(q1,q2)
Notes:
Table 27. Results of arithmetic operations between two FIXED operands under RULES(IBM)
Attributes of
the Result for
Addition, Addition Attributes
Subtraction, or of the
1st Operand 2nd Operand Multiplication, Subtraction Multiplication Division Result for
(p1,q1) (p2,q2) or Division Precision Precision Precision Exponentiation
p = 1
p = 1 FLOAT DECIMAL (p)
FIXED FIXED FIXED +MAX(p1-q1, p = N
+p1+p2 (unless special case
DECIMAL DECIMAL DECIMAL p2-q2) +q q =
q = A applies)
(p1,q1) (p2,q2) (p,q) q = N-p1+q1-q2
q1+q2 p = MAX(p1,p2)
MAX(q1,q2)
Table 27. Results of arithmetic operations between two FIXED operands under RULES(IBM) (continued)
Attributes of
the Result for
Addition, Addition Attributes
Subtraction, or of the
1st Operand 2nd Operand Multiplication, Subtraction Multiplication Division Result for
(p1,q1) (p2,q2) or Division Precision Precision Precision Exponentiation
p = 1
FLOAT BINARY (p)
FIXED FIXED FIXED +MAX(p1-q1, p = 1 p = M
(unless special case
BINARY BINARY BINARY p2-q2) +q +p1+p2 q = M-p1
B applies)
(p1,q1) (p2,q2) (p,q) q = q = q1+q2 +q1-q2
p = MAX(p1,p2)
MAX(q1,q2)
Notes:
PL/I gives the intermediate result attributes the same way it gives attributes to any
variable. The attributes of the result are derived from the attributes of the two
operands (or the single operand in the case of a prefix operation) and the operator
involved. The way the attributes of the result are derived is further explained
under Targets on page 54.
The ADD, SUBTRACT, MULTIPLY, and DIVIDE built-in functions allow you to
override the implementation precision rules for addition, subtraction,
multiplication, and division operations.
FIXED division:
The results of the two evaluations are reached as shown in Table 28.
Table 28. Comparison of FIXED division and constant expressions
1 (1,0) 1
3 (1,0) 3
1/3 (15,14) 0.33333333333333
25 (2,0) 25
25+1/3 (15,14) undefined
(truncation on left;
FIXEDOVERFLOW is raised
when the maximum
precision is 15)
01 (2,0) 01
3 (1,0) 3
01/3 (15,13) 00.3333333333333
25 (2,0) 25
25+01/3 (15,13) 25.3333333333333
The PRECISION built-in function can also be used. See the following example:
25+prec(1/3,15,13)
Note: Named constants are recommended for situations that require exact
precisions.
Using exponentiation
This topic describes how exponentiation is handled in PL/I.
Table 29. Special cases for exponentiation
Case First operand Second operand Attributes of result
A FIXED DECIMAL Integer with value n FIXED DECIMAL (p,q)
(p1,q1)
(provided p <= N)
where
p = (p1 + 1)*n-1
q = q1*n
B FIXED BINARY Integer with value n FIXED BINARY (p,q)
(p1,q1)
(provided p <= M)
where
p = (p1 + 1)*n-1
q = q1*n
C FLOAT (p1) FIXED (p2,0) FLOAT (p1) with base of first
operand
Special cases of x**y in real/complex modes:
Real mode:
Complex mode:
If x=0 and y>0,
result is 0. If x=0, and real part of y>0 and imaginary part of y=0, result is 0.
If x=0 and y<=0,
ERROR condition is raised. If x=0 and real part of y<=0 or imaginary part of y
=0, ERROR condition is raised.
If x<0 and y not FIXED (p,0),
ERROR condition is raised. If x=0 and real and imaginary parts of y=0, result is
1.
If you use exponentiation, simple calculations might become incorrect; for example,
10**-3 results in 0.0009 erroneously, instead of 0.0010. In such cases, round off the
result; or, do not use exponentiation but use division or multiplication.
Bit operations
A bit operation is specified by combining operands with a logical operator.
The following table lists logical operators that can be used for bit operations and
shows whether each operator can be used as a prefix or infix operator.
Table 30. Logical operators for bit operations
Operator Operator
symbol name As prefix operator As a infix operator
not/exclusive-or Yes Yes
& and No Yes
Operands of a bit operation are converted, if necessary, to bit strings before the
operation is performed. If the operands of an infix operation do not have the same
length, the shorter is padded on the right with '0'B.
The result of a bit operation is a bit string equal in length to the length of the
operands.
Bit operations are performed on a bit-by-bit basis. Table 31 illustrates the result for
each bit position for each of the operators.
Table 31. Bit operations
A B A B A&B A|B AB
1 1 0 0 1 1 0
1 0 0 1 0 1 1
0 1 1 0 0 1 1
0 0 1 1 0 0 0
Comparison operations
A comparison operation is specified by combining operands with one infix
operator.
The result of a comparison operation is always a bit string of length 1. The value is
'1'B if the relationship is true, or '0'B if the relationship is false.
If the operands of a computational data comparison have data types that are
appropriate to different types of comparison, the operand of the lower precedence
is converted to conform to the comparison type of the other. The precedence of
comparison types is (1) algebraic (highest), (2) widechar, (3) graphic, (4) character,
(5) bit. For example, if a bit string is compared with a fixed decimal value, the bit
string is converted to fixed binary for algebraic comparison with the decimal value.
The decimal value is also converted to fixed binary.
In the comparison of strings of unequal lengths, the shorter string is padded on the
right. This padding consists of the following:
v Blanks in a character comparison
v '0'B in a bit comparison
v A graphic (DBCS) blank in a graphic comparison
v A widechar blank ('0020'wx) in a widechar comparison
The evaluation of the expression A = B yields either 1B for true, or 0B for false.
The first equal symbol is the assignment symbol; the second equal symbol is the
comparison operator. The value 1B is assigned to X if A is equal to B; otherwise,
the value 0B is assigned.
Concatenation operations
Concatenation signifies that the operands are to be joined in such a way that the
last character, bit, graphic, or widechar of the operand to the left immediately
precedes the first character, bit, graphic, or widechar of the operand to the right,
with nothing intervening.
The result of a concatenation operation is a string whose length is equal to the sum
of the lengths of the two operands, and whose type (that is, character, bit, graphic,
or widechar) is the same as that of the two operands.
If an operand requires conversion for concatenation, the result depends upon the
length of the string to which the operand is converted.
For these operands and values This operation Yields this result
A = '010111'B A { B '010111_101'B
B = '101'B
A { A { B '010111_010111_101'B
C = 'xy,Z'
D = 'aa/BB' C { D 'xy,Zaa/BB'
D { C 'aa/BBxy,Z'
B { D '101aa/BB'
In the last example, the bit string '101'B is converted to the character string '101'
before the concatenation is performed. The result is a character string.
Combinations of operations
Different types of operations can be combined within the same operational
expression. Any combination can be used.
Each operation within the expression is evaluated according to the rules for that
kind of operation, with necessary data conversions taking place before the
operation is performed, as follows:
v The decimal value of A is converted to binary base.
v The binary addition is performed, adding A and B.
v The binary result is compared with the converted binary value of C.
v The bit result of the comparison is extended to the length of the bit variable D,
and the & operation is performed.
v The result of the & operation, a bit string of length 4, is assigned to Result
without conversion, but with truncation on the right.
Priority of operators
In the evaluation of expressions, operators have different priorities.
Note:
1. The operators are listed in order of priority, group 1 having the highest priority and group 7 the lowest. All
operators in the same priority group have the same priority. For example, the exponentiation operator ** has the
same priority as the prefix + and prefix - operators and the not operator .
2. For priority group 1, if two or more operators appear in an expression, the order of priority is right to left within
the expression; that is, the rightmost exponentiation or prefix operator has the highest priority, the next rightmost
the next highest, and so on. For all other priority groups, if two or more operators in the same priority group
appear in an expression, their order or priority is their order left to right within the expression.
The order of evaluation of the expression A + B < C & D is the same as if the
elements of the expression were parenthesized as (((A + B) < C) & D).
In this case, PL/I specifies only that the exponentiation occurs before the
concatenation. It does not specify the order of the evaluation of (D{E ** F) in
relation to the evaluation of the other operand (A + (B < C)).
In the next example, because of the use of parentheses, the operator of the final
infix operation is the comparison operator:
(A + B) < (C & D)
Array expressions
Array expressions can include operators (both prefix and infix), element variables,
and constants. The rules for combining operations and for data conversion of
operands are the same as for element operations.
Example
If A is the array 5 3 -9
1 2 7
6 3 -4
Array-and-element operations
The result of an expression with an element, an array, and an infix operator is an
array with bounds identical to the original array.
Each element of the resulting array is the result of the operation between each
corresponding element of the original array and the single element. See the
following example:
If A is the array 5 10 8
12 11 3
Again, using the above values for A, the newly assigned value of A will be as
follows:
50 100 800
1200 1100 300
Array-and-array operations
If the two operands of an infix operator are arrays, the arrays must have the same
number of dimensions, and corresponding dimensions must have identical lower
bounds and identical upper bounds.
The result is an array with bounds identical to those of the original arrays; the
operation is performed upon the corresponding elements of the two original
arrays.
Example
If A is the array 2 4 3
6 1 7
4 8 2
and if B is the array 1 5 7
8 3 4
6 3 1
then A+B is the array 3 9 10
14 4 11
10 11 3
and A*B is the array 2 20 21
48 3 28
24 24 2
Structure expressions
Structure expressions, unlike structure references, are allowed only in assignments
and as arguments to procedures or functions, as long as the associated parameter
has constant extents, namely, constant string lengths, area sizes, and array bounds.
Restricted expressions
Where PL/I requires a (possibly signed) constant, a restricted expression can be
used.
Examples
dcl Max_names fixed bin value (1000),
Name_size fixed bin value (30),
Addr_size fixed bin value (20),
Addr_lines fixed bin value (4);
dcl 1 Name_addr(Max_names),
2 Name char(Name_size),
2 * union,
3 Address char(Addr_lines*Addr_size), /* address */
3 addr(Addr_lines) char(Addr_size),
2 * char(0);
dcl One_Name_addr char(size(Name_addr(1))); /* 1 name/addr*/
dcl Two_Name_addr char(length(One_Name_addr)
*2); /* 2 name/addrs */
dcl Name_or_addr char(max(Name_size,Addr_size)) based;
If you change the value of any of the named constants in the example, all of the
dependent declarations are automatically reevaluated.
Conversion of the value of a computational data item can change its internal
representation, precision or mode (for arithmetic values), or length (for string
values). The following tables summarize the circumstances that can cause
conversion to other attributes.
Statement Option
DISPLAY
Record I/O KEYFROMKEY
OPEN TITLE
Statement Option/Attribute/Reference
DECLARE, ALLOCATE, DEFAULT length, size, dimension, bound, repetition
factor
DELAY milliseconds
FORMAT (and format items in GET and iteration factor w, d, s, p
PUT)
OPEN LINESIZE, PAGESIZE
I/O SKIP, LINE, IGNORE
Most statements subscript
All attributes for source and target data items (except string length) must be
specified at compile time. Conversion can raise one of the following conditions:
CONVERSION, OVERFLOW, SIZE, or STRINGSIZE. (See Chapter 16,
Conditions, on page 381.)
Constants can be converted at compile time as well as at run time. In all cases, the
conversions are as described in this topic collection.
More than one conversion might be required for a particular operation. The
implementation does not necessarily go through more than one. To understand the
conversion rules, it is convenient to consider them separately. Consider the
following example:
dcl A fixed dec(3,2) init(1.23);
dcl B fixed bin(15,5);
B = A;
Each function returns a value with the attribute specified by the function name,
performing any required conversions.
Note: If you use SUBSTR with variables as the parameters, and the variables
specify a string not contained in the target, unpredictable results can occur if the
STRINGRANGE condition is not enabled.
Character strings are padded with blanks, bit strings with '0'B, graphic strings with
DBCS blanks, and widechar strings with widechar blanks.
declare Subject char(10);
Subject = Transformations;
The first two of the following statements assign equivalent values to Subject and
the last two assign equivalent values to Code:
Subject = Physics;
Subject = Physics ;
declare Code bit(10);
Code = 110011B;
Code = 1100110000B;
When the first statement is executed, the bit constant on the right is first converted
to a character string and is then extended on the right with blank characters rather
than zero characters. This statement is equivalent to the following statement:
Subject = 110011bbbb;
The second statement requires only a conversion from bit to character type and is
equivalent to the following statement:
Subject = 1100110000;
A string value is not extended with blank characters or zero bits when it is
assigned to a string variable that has the VARYING or VARYING4 attribute.
Instead, the length of the target string variable is set to the length of the assigned
string. However, truncation will occur if the length of the assigned string exceeds
the maximum length declared for the varying-length string variable.
For fixed-point data items, decimal or binary point alignment is maintained during
precision conversion. Therefore, padding or truncation can occur on the left or
right. If nonzero bits or digits on the left are lost, the SIZE condition is raised.
For floating-point data items, truncation on the right, or padding on the right with
zeros, can occur.
Converting mode
If a complex value is converted to a real value, the imaginary part is ignored. If a
real value is converted to a complex value, the imaginary part is zero.
Source-to-target rules are given, following this section, for converting data items
with the following data attributes:
v Coded arithmetic:
FIXED BINARY
FIXED DECIMAL
FLOAT BINARY
FLOAT DECIMAL
v Arithmetic character PICTURE
v CHARACTER
v BIT
v GRAPHIC
v WIDECHAR
In converting between binary and decimal, the factor 3.32 is used as follows:
v n decimal digits convert to CEIL (n*3.32) binary digits.
v n binary digits convert to CEIL (n/3.32) decimal digits.
For fixed-point integer values, conversion does not change the value. For
fixed-point fractional values, the factor 3.32 provides only enough digits or bits so
that the converted value differs from the original value by less than 1 digit or bit
in the rightmost place.
For example, the decimal constant .1, with attributes FIXED DECIMAL (1,1),
converts to the binary value .0001B, converting 1/10 to 1/16. The decimal constant
.10, with attributes FIXED DECIMAL (2,2), converts to the binary value .0001100B,
converting 10/100 to 12/128.
Source-to-target rules
These source-to-target rules are given for converting data items with the following
data attributes.
v Coded arithmetic
FIXED BINARY
FIXED DECIMAL
FLOAT BINARY
FLOAT DECIMAL
v Arithmetic character PICTURE
v CHARACTER
v BIT
v GRAPHIC
v WIDECHAR
GRAPHIC
Graphic variables and strings are converted to CHARACTER, and then
follow the rules for character source described
WIDECHAR
Widechar variables and strings are converted to CHARACTER, and
then follow the rules for character source described in CHARACTER.
CHARACTER
See Target: Coded Arithmetic.
BIT
See Target: Coded Arithmetic.
GRAPHIC
See Target: Coded Arithmetic.
WIDECHAR
See Target: Coded Arithmetic.
GRAPHIC
See Target: Coded Arithmetic.
WIDECHAR
See Target: Coded Arithmetic.
where p>= p1 and the values of p and q take account of the range of
values that can be held by the exponent of the source.
Arithmetic character PICTURE
The implied attributes of the source will be either FIXED DECIMAL or
FLOAT DECIMAL. See the respective entries for this target.
CHARACTER
See Target: Coded Arithmetic.
BIT(n)
The target must imply:
fixed decimal (1+x+q,q) or
float decimal (x)
WIDECHAR
See Target: Coded Arithmetic.
Target: CHARACTER
Source:
FIXED BINARY, FIXED DECIMAL,
FLOAT BINARY, and FLOAT DECIMAL
The coded arithmetic value is converted to a decimal constant
(preceded by a minus sign if it is negative) as described below. The
constant is inserted into an intermediate character string whose length
is derived from the attributes of the source. The intermediate string is
assigned to the target according to the rules for string assignment.
The rules for coded-arithmetic-to-character-string conversion are also
used for list-directed and data-directed output, and for evaluating keys
(even for REGIONAL files).
FIXED BINARY (p1,q1)
The binary precision (p1,q1) is first converted to the equivalent decimal
precision (p,q), where p=1+CEIL(p1/3.32) and q=CEIL(ABS(q1/
3.32))*SIGN(q1). Thereafter, the rules are the same as for FIXED
DECIMAL to CHARACTER.
FIXED DECIMAL (p1,q1)
If p1>=q1>=0 then:
v The constant is right adjusted in a field of width p1+3. (The 3 is
necessary to allow for the possibility of a minus sign, a decimal or
binary point, and a leading zero before the point.)
v Leading zeros are replaced by blanks, except for a single zero that
immediately precedes the decimal point of a fractional number. A
single zero also remains when the value of the source is zero.
v A minus sign precedes the first digit of a negative number. A
positive value is unsigned.
v If q1=0, no decimal point appears; if q1>0, a decimal point appears
and the constant has q fractional digits.
If p1<q1 or q1<0, a scaling factor appends to the right of the constant;
the constant is an optionally-signed integer. The scaling factor appears
even if the value of the item is zero and has the following syntax:
F{+|-}nn
Target: BIT
Source:
FIXED BINARY, FIXED DECIMAL,
FLOAT BINARY, and FLOAT DECIMAL
If necessary, the arithmetic value converts to binary and both the sign
and any fractional part are ignored. (If the arithmetic value is complex,
the imaginary part is also ignored.) The resulting binary value is
treated as a bit string. It is assigned to the target according to the rules
for string assignments.
FIXED BINARY (p1,q1)
The length of the intermediate bit string is given by:
min(M,(p1-q1))
(1) 1 1B
(3) -3 011B
(4,2) 1.25 01B
FIXED DECIMAL (p1,q1)
The length of the intermediate bit string is given by:
min(M,CEIL((p1-q1)*3.32))
(1) 1 0001B
(2,1) 1.1 0001B
FLOAT BINARY (p1)
The length of the intermediate bit string is given by:
min(M,p1)
FLOAT DECIMAL (p1)
The length of the intermediate bit string is given by:
min(M,ceil(p1*3.32))
Arithmetic character PICTURE
Data is first interpreted as decimal with scale and precision determined
by the corresponding PICTURE specification. The item then converts
according to the rules given for FIXED DECIMAL or FLOAT
DECIMAL to BIT.
CHARACTER
Character 0 becomes bit 0 and character 1 becomes bit 1. Any character
other than 0 or 1 raises the CONVERSION condition. A null string
becomes a null bit string. The generated bit string, which has the same
length as the source character string, is assigned to the target according
to the rules for string assignment.
GRAPHIC
Graphic 0 becomes bit 0 and graphic 1 becomes bit 1. Any graphic
Target: GRAPHIC
Target: WIDECHAR
Source other than widechar is first converted to character according to the rules in
Target: Character. The resultant character string is then converted to a widechar
string.
Examples
This section provides additional data conversion examples.
3. The bit string is assigned to A. Since A has a declared length of 1, and the
value to be assigned has acquired a length of 4, truncation occurs at the right,
and A has a final value of '0'B.
For the comparison operation in the IF statement, '0'B and 1 convert to FIXED
BINARY and compare arithmetically. They are unequal, giving a result of false for
the relationship A=1.
For this example, FIXED DECIMAL precision 15 was used for the implementation
maximum. The example raises the CONVERSION condition because of the
following sequence of actions:
1. The initial value of CTLNO, that is, '0bbbbbbb' converts to FIXED
DECIMAL(15,0).
2. The decimal constant, 1, with attributes FIXED DECIMAL(1,0), is added; in
accordance with the rules for addition, the precision of the result is (16,0).
3. This value now converts to a character string of length 18 in preparation for the
assignment back to CTLNO.
4. Because CTLNO has a length of 8, the assignment causes truncation at the
right; thus, CTLNO has a final value that consists entirely of blanks. This value
cannot be successfully converted to arithmetic type for the second iteration of
the loop.
Proper division of a program into blocks simplifies the writing and testing of the
program, particularly when many programmers are writing it. Proper division can
also result in more efficient use of storage, because automatic storage is allocated
on entry to the block in which it is declared and released when the block is
terminated.
Programs
PL/I is a block-structured language, consisting of packages, procedures,
begin-blocks, statements, expressions, and built-in functions. A PL/I application
consists of one or more separately loadable entities, known as a load module. Each
load module can consist of one or more separately compiled entities, known as a
compilation unit (CU). Unless otherwise stated, a program refers to a PL/I
application or a compilation unit.
Program structure
Programs refer to PL/I applications or compilation units, which are separately
compiled entities that compose load modules. A PL/I application consists of one or
more load modules.
Related information:
Packages on page 94
A package is a block that can contain only declarations, default statements, and
procedure blocks. The package forms a name scope that is shared by all
declarations and procedures contained in the package, unless the names are
declared again.
Procedures on page 97
A procedure is a sequence of statements delimited by a PROCEDURE statement
and a corresponding END statement. A procedure can be a main procedure, a
subroutine, or a function.
Begin-blocks on page 118
A begin-block is a sequence of statements delimited by a BEGIN statement and a
corresponding END statement.
Program activation
A PL/I program becomes active when a calling program invokes the main
procedure.
This calling program usually is the operating system, although it could be another
program. The main procedure is the external procedure for which the statement
has the OPTIONS(MAIN) specification.
In this example, Contrl is the main procedure and it invokes other external
procedures in the program. The main procedure remains active for the duration of
the program.
Contrl: procedure options(main);
call A;
call B;
call C;
end Contrl;
Program termination
A program is terminated when the main procedure is terminated. Whether
termination is normal or abnormal, control returns to the calling program.
Blocks
A block is a delimited sequence of statements, processed as a unit, that specifies the
scope of names and the allocation of storage for names declared within it. A block
can be a package, a procedure, or a begin-block.
v A block establishes the scope of names declared within it.
v A block limits the allocation of automatic variables.
v A block determines the scope of DEFAULT statements (as described in Defaults
for attributes on page 178).
These blocks can contain declarations that are treated as local definitions of names.
This is done to establish the scope of the names and to limit the allocation of
automatic variables. These declarations are not known outside their own block,
and the names cannot be referred to in the containing block. For more information,
see Scope of declarations on page 162.
Storage is allocated to automatic variables upon entry to the block where the
storage is declared, and is freed upon exit from the block. For more information,
see Scope of declarations on page 162.
Block activation
Each block plays the same role in the allocation and freeing of storage and in
delimiting the scope of names. Packages are neither activated nor terminated.
For information about how activation occurs, see Procedures on page 97 and
Begin-blocks on page 118.
Initial values and extents for automatic variables must not depend on the values or
extents of other automatic variables declared in the same block. For example, the
following initialization can produce incorrect results for J and K:
dcl I init(10),J init(K),K init(I);
Similarly, the following code causes b to have an undefined value (and most likely,
not the value 10) after this structure is initialized:
dcl
1 a,
2 b fixed bin init(c),
2 c fixed bin init(10);
Declarations of data items must not be mutually interdependent. For example, the
following declarations are invalid:
dcl A(B(1)), B(A(1));
Errors can occur during block activation, and the ERROR condition (or other
conditions) can be raised. If so, the environment of the block might be incomplete.
In particular, some automatic variables might not have been allocated. Statements
referencing automatic variables executed after the ERROR condition has been
raised might reference unallocated storage. The results of referring to unallocated
storage are undefined.
Block termination
There are a number of ways a block can be terminated. Packages are neither
activated nor terminated.
For information about how termination occurs, see Procedures on page 97 and
Begin-blocks on page 118.
Packages
A package is a block that can contain only declarations, default statements, and
procedure blocks. The package forms a name scope that is shared by all
declarations and procedures contained in the package, unless the names are
declared again.
Some or all of the level-1 procedures can be exported and made known outside of
the package as external procedures. A package can be used for implementing
multiple entry point applications.
A package that contains a MAIN procedure must not contain any FETCHABLE
procedures. A package that contains a MAIN procedure must not be linked into a
DLL. It should form part of a base executable that can, if desired, invoke routines
in a DLL. Such a package can, of course, also define external routines that can be
called from other routines statically linked with it, and the package can also define
EXTERNAL STATIC data that can be referenced from other routines statically
linked with it.
If a package that does not contain a MAIN routine is linked into a DLL, the only
EXTERNAL STATIC variables that will be exported from that package out of the
DLL are those variables that have the RESERVED attribute.
If the source contains a PACKAGE statement, there must be at most only one set of
*PROCESS statements and those must be the first statements in the source. If the
source contains no PACKAGE statement, the compiler effectively inserts one after
the first set of *PROCESS statements and the source might contain multiple
external procedures separated by groups of *PROCESS statements.
EXPORTS ( procedure )
*
;
, OPTIONS(options)
declare-statement END ;
default-statement package-name
procedure-statement
procedure:
procedure-name
EXTERNAL(environment-name)
condition-prefix
Condition prefixes specified on a PACKAGE statement apply to all procedures
contained in the package unless overridden on the PROCEDURE statement.
For more information, see Condition prefixes on page 371.
package-name
The name of the package. All PACKAGE names must be unique within a
linked module.
EXPORTS
Specifies that all (EXPORTS(*)) or the named procedures are to be exported
and thus made externally known outside of the package. If no EXPORTS
option is specified, EXPORTS(*) is assumed.
procedure name
Is the name of a level-1 procedure within the package.
/***********************************************/
/* Common Data */
/***********************************************/
/***********************************************/
/* Main Program */
/***********************************************/
/***********************************************/
/* Subroutine */
/***********************************************/
end Package_Demo;
Procedures
A procedure is a sequence of statements delimited by a PROCEDURE statement
and a corresponding END statement. A procedure can be a main procedure, a
subroutine, or a function.
The ENTRY statement can define a secondary entry point to a procedure. Consider
the following example:
Name: procedure;
B: entry;
end Name;
B defines a secondary entry point to the Name procedure. The ENTRY statement is
described in ENTRY attribute on page 121.
A procedure can be recursive, which means that it can be reactivated from within
itself or from within another active procedure while it is already active. You can
pass arguments when invoking a procedure.
Related information:
Scope of declarations on page 162
The part of the program to which a name applies is called the scope of the
declaration of that name. In most cases, the scope of the declaration of a name is
determined entirely by the position where the name is declared within the
program.
Subroutines on page 110
A subroutine is an internal or external procedure that is invoked by a CALL
statement.
Functions on page 112
A function is a procedure that has zero or more arguments and is invoked by a
function reference in an expression.
Passing arguments to procedures on page 114
When a function or a subroutine is invoked, parameters are associated, from left to
right, with the passed arguments.
The primary entry point to a procedure is established by the leftmost label of the
procedure statement. Secondary entry points to a procedure are established by
additional labels on the PROCEDURE statement and by the ENTRY statement.
Each entry point has an entry name. See INTERNAL and EXTERNAL attributes
on page 165 for a discussion of the rules for the creation of an external name.
entry-label: PROCEDURE
,
( )
parameter
returns-option OPTIONS(options) RECURSIVE
; statement
scope-attribute group
internal-procedure
begin-block
END ;
entry-label
ENTRY statement
The ENTRY statement specifies a secondary entry point of a procedure. The
ENTRY statement must be internal to the procedure for which it defines a
secondary entry point. It cannot be within a do-group that specifies repetitive
execution, or internal to a ON-unit.
entry-label: ENTRY
,
( parameter )
;
OPTIONS(options)
RETURNS( attribute )
entry-label
The secondary entry point to the procedure.
parameter
See Parameter attribute and Passing arguments to procedures on page 114.
RETURNS option
See RETURNS option and attribute on page 144.
OPTIONS option
See OPTIONS option and attribute on page 135.
If a procedure that contains ENTRY statements has the RETURNS option, or if any
of its contained ENTRY statements have the RETURNS option, the following
conditions apply:
v The BYADDR attribute must be specified (or implied by the compile-time option
DEFAULT(RETURNS(BYADDR)) in all of the RETURNS options for that
procedure and its ENTRY statements.
v All routines that call one of these entry points must also either declare the entry
with RETURNS(BYADDR) or be compiled with the
DEFAULT(RETURNS(BYADDR)) compiler option.
When a procedure contains ENTRY statements and some, but not all of its entry
points have the RETURNS attribute, the ERROR condition is detected under the
following circumstances:
v If the code executes a RETURN statement with an expression when the
procedure was entered at an entry point which did not have the RETURNS
attribute.
v If the code executes a RETURN statement without an expression when the
procedure was entered at an entry point that has the RETURNS attribute.
Parameter attribute
A parameter is contextually declared with the parameter attribute by its
specification in a PROCEDURE or ENTRY statement.
PARAMETER
Table 8 on page 21, and the following discussion, describe the attributes that can be
declared for a parameter.
When the actual length, bounds, or size can be different for different invocations,
each can be specified in a DECLARE statement by an asterisk. When an asterisk is
used, the length, bounds, or size are taken from the current generation of the
associated argument.
Asterisk notation:
When asterisks are used, length, bounds, or size of the controlled parameter are
taken from the current generation of the associated argument. Any subsequent
allocation of the controlled parameter uses these same bounds, length, or size,
unless they are overridden by a different length, bounds, or size specification in
the ALLOCATE statement.
If no current generation of the argument exists, the asterisks determine only the
dimensionality of the parameter, and an ALLOCATE statement in the invoked
procedure must specify bounds, length, or size for the controlled parameter before
other references to the parameter can be made.
Expression notation:
Each time the parameter is allocated, the expressions are evaluated to give current
bounds, lengths, or sizes for the new allocation. However, such expressions in a
DECLARE statement can be overridden by a bounds, length, or size specification
in the ALLOCATE statement itself.
In Figure 4 on page 103, when Sub1 is invoked, A and B, which have been allocated,
are passed.
end Package;
On returning to Main, the first FREE statement frees the second generation of A and
B (allocated in Sub1). The second FREE statement frees the first generation of A and
B (allocated in Main).
In Sub2, X and Y are declared with bounds that depend on the value of N. When X
and Y are allocated, their values determine the bounds of the allocated arrays.
On returning to Main from Sub2, the FREE statement frees the only generation of C
and D (allocated in Sub2).
Procedure activation
Sequential program flow passes around a procedure, from the statement before the
PROCEDURE statement to the statement after the END statement for that
procedure. The only way that a procedure can be activated is by a procedure
reference.
For information about how to activate the main procedure, see Program
activation on page 92.
The execution of the invoking procedure is suspended until the invoked procedure
returns control to it.
The information in this section is relevant to each of these contexts. However, the
examples in this chapter use CALL statements.
When a procedure reference occurs, the procedure containing the specified entry
point is said to be invoked. The point at which the procedure reference appears is
called the point of invocation and the block in which the reference is made is called
the invoking block. An invoking block remains active even though control is
transferred from it to the procedure it invokes.
call Readin;
call Errt;
The statement call Readin invokes Readin at its primary entry point and execution
begins with statement-1; the statement call Errt invokes the Readin procedure at
the secondary entry point Errt and execution begins with statement-3. The entry
constant (Readin) can also be assigned to an entry variable that is used in a
procedure reference, as in the following example:
declare Readin entry,
Ent1 entry variable;
Ent1 = Readin;
call Ent1;
call Readin;
Procedure termination
A procedure is terminated when, by some means other than a procedure reference,
control passes back to the invoking program, block, or to some other active block.
statement-3
statement-4
C: procedure;
statement-c1
statement-c2
statement-c3
D: begin;
statement-d1
statement-d2
go to Lab;
statement-d3
end D;
statement-c4
end C;
statement-5
Lab: statement-6
statement-7
end A;
Recursive procedures
An active procedure that is invoked from within itself or from within another
active procedure is a recursive procedure. Such an invocation is called recursion.
RECURSIVE
The environment (that is, values of automatic variables and the like) of every
invocation of a recursive procedure is preserved in a manner analogous to the
stacking of allocations of a controlled variable (see Controlled storage and
attribute on page 256). Think of an environment as being pushed down at a
recursive invocation, and popped up at the termination of that invocation. A label
constant in the current block is always a reference to the current invocation of the
block that contains the label.
A: proc recursive;
It is not an error if the procedure has already been loaded into main storage. The
fetched procedure can remain in main storage until execution of the whole
program is completed. Alternatively, the storage it occupies can be freed for other
purposes at any time by means of the RELEASE statement.
FETCH statement
The FETCH statement checks main storage for the named procedures.
Procedures not already in main storage are loaded from the disk.
FETCH entry-constant
SET ( ptr-ref ) TITLE ( char-expr )
entry-constant
Specifies the name by which the procedure to be fetched is known to the
operating system. Details of the linking considerations for fetchable procedures
are given in the Programming Guide.
The entry-constant must be the same as the one used in the corresponding
CALL statement, CALL option, or function reference.
SET
Specifies a pointer reference (ptr-ref) that will be set to the address of the entry
point of the loaded module. This option can be used to load tables
(non-executable load modules). It can also be used for entries that are fetched
and whose addresses need to be passed to non-PL/I procedures.
If the load module is later released by the RELEASE statement, and the load
module is accessed (through the pointer), unpredictable results can occur.
TITLE
For TITLE, char-expr is any character expression or an expression that can be
converted to a character expression. If TITLE is specified, the load module
name specified is searched for and loaded. If it is not specified, the load
module name used is the environment name specified in the EXTERNAL
attribute for the variable (if present) or the entry constant name itself.
See the following example:
dcl A entry;
dcl B entry ext(C);
dcl T char(20) varying;
T = Y;
RELEASE statement
The RELEASE statement frees the main storage occupied by procedures identified
by its specified entry constants.
RELEASE entry-constant ;
*
entry constant
Must be the same as the one used in the corresponding CALL statement,
CALL option, function reference, and FETCH statements. RELEASE * releases
all previously fetched PL/I modules. It must not be executed from within a
fetched module.
If the module has never been fetched in the same external procedure before or
has already been released, the entry constant is the null pointer. No release is
performed, no message is issued and execution continues with the statement
that follows the RELEASE statement.
Consider the following example, in which ProgA and ProgB are entry names of
procedures resident on disk:
Prog: procedure;
1 fetch ProgA;
2 call ProgA;
3 release ProgA;
4 call ProgB;
go to Fin;
fetch ProgB;
Fin: end Prog;
1 ProgA is loaded into main storage by the first FETCH statement.
2 ProgA executes when the first CALL statement is reached.
3 Storage for ProgA is released when the RELEASE statement is executed.
4 ProgB is loaded and executed when the second CALL statement is reached,
even though the FETCH statement referring to this procedure is never
executed.
The same results would be achieved if the statement FETCH ProgA were omitted.
The appearance of ProgA in a RELEASE statement causes the statement CALL
ProgA to load the procedure, as well as invoke it.
The fetched procedure is compiled and linked separately from the calling
procedure. You must ensure that the entry constant specified in FETCH, RELEASE,
and CALL statements; CALL options; and in function references is the name
known on the disk. This is discussed in the Programming Guide.
Note: Before a module is released, the module must release all system resources it
has acquired. This includes but is not limited to the following actions:
v Release any modules it has fetched.
v Close any files it has opened.
v Free any controlled storage it has allocated.
Subroutines
A subroutine is an internal or external procedure that is invoked by a CALL
statement.
The arguments of the CALL statement are associated with the parameters of the
invoked procedure. The subroutine is activated, and execution begins. The
arguments (zero or more) can be input only, output only, or both.
The following examples illustrate the invocation of subroutines that are external to
and internal to the invoking block.
Example 1
This example illustrates the invocation of subroutines that are external to the
invoking block.
Prmain: procedure;
declare Name character (20),
Item bit(5),
4 Outsub entry;
1 call Outsub (Name, Item);
end Prmain;
Example 2
This example illustrates the invocation of subroutines that are internal to the
invoking block.
A: procedure;
declare Rate float (10),
Time float(5),
Distance float(15),
Master file;
1 call Readcm (Rate, Time, Distance, Master);
3 Readcm:
2 procedure (W,X,Y,Z);
declare W float (10),
X float(5),
Y float(15), Z file;
get File (Z) list (W,X,Y);
Y = W * X;
if Y > 0 then
return;
else
end A;
1 The arguments Rate, Time, Distance, and Master are passed to the
procedure Readcm in 3 and associated with the parameters W, X, Y, and Z.
2 A reference to W is the same as a reference to Rate, X the same as Time, Y
the same as Distance, and Z the same as Master.
3 Note that Readcm is not explicitly declared in A. It is implicitly declared
with the ENTRY attribute by its specification on the PROCEDURE
statement.
Built-in subroutines
You can use built-in subroutines, which provide ready-made programming tasks.
Their built-in names can be explicitly declared with the BUILTIN attribute.
For more information about the BUILTIN attribute or for the description of any
built-in function, see Chapter 18, Built-in functions, pseudovariables, and
subroutines, on page 409.
Functions
A function is a procedure that has zero or more arguments and is invoked by a
function reference in an expression.
The RETURN statement terminates a function and returns the value specified in its
expression to the invoking expression.
Examples
These examples illustrate the invocation of functions that are internal to and
external to the invoking block.
Example 1
In the following example, the assignment statement contains a reference to the
Sprod function:
Mainp: procedure;
get list (A, B, C, Y);
1 X = Y**3+Sprod(A,B,C);
Example 2
Mainp: procedure;
dcl Tprod entry (bin float(53),
bin float(53),
bin float(53),
label) external
returns (bin float(21));
get list (A,B,C,Y);
1 X = Y**3+Tprod(A,B,C,Lab1);
Lab1: call Errt;
end Mainp;
1 Tprod: procedure (U,V,W,Z)
returns (bin float(21));
dcl (U,V,W) bin float(53);
declare Z label;
2 if U > V + W then
go to Z;
3 else
return (U*V*W);
end Tprod;
1 When Tprod is invoked, Lab1 is associated with parameter Z.
2 If U is greater than V + W, control returns to Mainp at the statement labeled
Lab1. Evaluation of the assignment in 1 is discontinued.
3 If U is not greater than V + W, U*V*W is calculated and returned to Mainp in
the normal fashion. Evaluation of the assignment in 1 continues.
Built-in functions
Besides allowing programmer-written function procedures, PL/I provides a set of
built-in functions.
Arguments that require aggregate temporaries derived from structures are not
allowed, unless the structure argument is declared with constant extents.
Expressions in the argument list are evaluated in the invoking block before the
subroutine or function is invoked. A parameter has no storage associated with it. It
is merely a means of allowing the invoked procedure to access storage allocated in
the invoking procedure.
When you specify BYADDR, the compiler puts the address of the corresponding
argument in the parameter list. When you specify BYVALUE, puts the value of the
argument in the parameter list.
BYVALUE can be specified only for scalar arguments and parameters that have
lengths and sizes known at compile time.
When you declare an argument as OUTONLY, then the argument is presumed not
to have a value before it is passed but to be set by the called code.
The BYVALUE attribute implies the INONLY attribute. Hence the attributes
OUTONLY and BYVALUE conflict and may not both be specified for the same
argument. However, the ASSIGNABLE attribute is allowed with the BYVALUE
attribute.
The attributes INONLY and OPTIONAL also conflict and may not both be
specified for the same argument.
The explicit use of these attributes makes your code more self-documenting.
Furthermore, it allows the compiler to produce better code and to be more accurate
in reporting possibly uninitialized variables.
Dummy arguments
A dummy argument is a piece of temporary storage that is created automatically to
hold the value of an argument.
When the invoking program is the operating system and the invoked program was
compiled with the SYSTEM(MVS) compiler option, the following rules apply:
v A single argument is passed to the MAIN procedure, and that parameter must
be declared as CHARACTER VARYING.
v The current length of this parameter is set equal to the argument length at run
time. So, in the following example, storage is allocated only for the current
length of the argument:
Tom: proc (Param) options (main);
dcl Param char(100) varying;
v The contents of this parameter depend on a second option that may be specified
along with OPTIONS(MAIN):
Begin-blocks
A begin-block is a sequence of statements delimited by a BEGIN statement and a
corresponding END statement.
Example
B: begin;
statement-1
statement-2
.
.
.
statement-n
end B;
BEGIN statement
The BEGIN statement and a corresponding END statement delimit a begin-block.
BEGIN ;
OPTIONS ( options )
OPTIONS option
For begin-block options, see OPTIONS option and attribute on page 135.
Begin-block activation
Begin-blocks are activated through sequential flow or as a unit in an IF, ON,
WHEN, or OTHERWISE statement.
Begin-block termination
A begin-block is terminated when control passes to another active block by some
means other than a procedure reference.
Entry data
The entry data can be an entry constant or the value of an entry variable.
Ev = E1;
call Ev;
Ev = E2;
call Ev;
The first CALL statement invokes the entry point E1. The second CALL invokes the
entry point E2.
The five entries A, B, C, D, and E are each invoked with the parameters X, Y, and Z.
declare (A,B,C,D,E) entry,
declare F(5) entry variable initial (A,B,C,D,E);
do I = 1 to 5;
call F(I) (X,Y,Z);
end;
Entry constants
The appearance of a label prefix to a PROCEDURE or ENTRY statement explicitly
declares an entry constant.
ENTRY
(parameter-descriptor-list) RETURNS attribute
OPTIONS(characteristic-list) EXTERNAL
(environment-name)
Entry variables
An entry variable can contain both internal and external entry values. It can be
part of an aggregate.
For information about structuring and array dimension attributes, see Arrays on
page 184 and Structures on page 188.
ENTRY
(parameter-descriptor-list) OPTIONS(characteristic-list)
VARIABLE LIMITED RETURNS attribute
EXTERNAL
(environment-name)
VARIABLE attribute
The VARIABLE attribute establishes the name as an entry variable. This
variable can contain entry constants and variables. See VARIABLE attribute
on page 49 for syntax information.
LIMITED attribute
See LIMITED attribute on page 129.
RETURNS attribute
See RETURNS option and attribute on page 144.
EXTERNAL attribute
See Scope of declarations on page 162.
Under 64-bit, all ENTRY variables, whether they have the LIMITED attribute or
not, are 8 bytes in size and are by default doubleword-aligned.
ENTRY attribute
The ENTRY attribute specifies that the name being declared is either an external
entry constant or an entry variable. It also describes the attributes of the
parameters of the entry point.
ENTRY
,
( parameter-descr )
structure-union-descr
parameter-descr:
attribute
*
ALIGNED OPTIONAL
UNALIGNED
ASSIGNABLE
NONASSIGNABLE
INOUT
INONLY
OUTONLY
CONNECTED
NONCONNECTED
BYADDR
BYVALUE
structure-union-descr:
1 , level
attribute OPTIONAL attribute
ENTRY
The ENTRY attribute, without a parameter descriptor list, is implied by the
RETURNS attribute.
parameter-descr (parameter-descriptor)
A parameter descriptor list can be given to describe the attributes of the
parameters of the associated external entry constant or entry variable. It is
used for argument and parameter attribute matching and the creation of
dummy arguments.
If no parameter descriptor list is given, the default is for the argument
attributes to match the parameter attributes. Thus, the parameter descriptor list
must be supplied if argument attributes do not match the parameter attributes.
Each parameter descriptor corresponds to one parameter of the entry point
invoked and, if given, specifies the attributes of that parameter.
The parameter descriptors must appear in the same order as the parameters
they describe. If a descriptor is absent, the default is for the argument to match
the parameter.
attribute
The allowed attributes are any of the data attributes listed under Data
attributes on page 18. The attributes can appear in any order in a parameter
descriptor. For an array parameter-descriptor, the dimension attribute must be
the first one specified.
* An asterisk specifies that, for that parameter, any data type is allowed. Only
the following attributes are valid attributes following the asterisk:
v ALIGNED or UNALIGNED
v ASSIGNABLE or NONASSIGNABLE
v BYADDR or BYVALUE
v CONNECTED or NONCONNECTED
v INONLY, INOUT, or OUTONLY
v OPTIONAL
No conversions are done.
OPTIONAL
See OPTIONAL attribute on page 124.
structure-union-descr (structure-union-descriptor)
For a structure-union descriptor, the descriptor level-numbers need not be the
same as those of the parameter, but the structuring must be identical. The
attributes for a particular level can appear in any order.
Defaults are not applied if an asterisk is specified. For example, in the following
declaration, defaults are applied only for the second parameter.
dcl X entry(* optional, aligned); /* defaults applied for 2nd parm */
RETURNS attribute implies the ENTRY attribute. See the following example:
In the preceding example, the parameter C and the structure parameter E do not
have descriptors.
OPTIONAL attribute
You can specify OPTIONAL as part of the parameter-descriptor list or as an
attribute in the parameter declaration.
OPTIONAL
Using OPTIONAL and BYVALUE for the same item is not valid, unless the item is
a LIMITED ENTRY.
The receiving procedure can use the OMITTED or PRESENT built-in function to
determine whether an OPTIONAL parameter/argument was omitted in the
invocation of the entry.
You can omit such trailing OPTIONAL parameters both when the ENTRY invoked
is explicitly declared and when the ENTRY invoked is a nested subprocedure. Note
also that unless the ENTRY has the OPTIONS(ASSEMBLER) attribute, the
generated code will supply null pointers for the omitted parameters.
Figure 5 shows both valid and invalid CALL statements for the procedure Vrtn.
Caller: proc;
dcl Vrtn entry (
fixed bin,
ptr optional,
float,
* optional);
Vrtn determines whether OPTIONAL parameters are omitted and takes the
appropriate action.
Related information:
OMITTED on page 624
LIST attribute
You can specify LIST on the last parameter in a parameter-descriptor list or as an
attribute on the last parameter to a procedure.
LIST
When the LIST attribute is specified in an entry declaration, it indicates that zero
or more additional arguments can be passed to that entry. For example, the
following declare specifies that vararg must be invoked with one character
varyingz parameter and can be invoked with any number of other parameters.
dcl vararg external
entry( list byaddr char(*) varz nonasgn )
options( nodescriptor byvalue );
When the LIST attribute is specified in the declaration of the last parameter in a
procedure, it indicates that zero or more additional arguments might have been
passed to that procedure.
The address of the first of these additional parameters can be obtained by the
VARGLIST built-in function. This address can be used to obtain the addresses of
any additional parameters as follows:
v If the additional parameters to this procedure were passed by value (BYVALUE),
successively incrementing this initial address by the value returned by the
VARGSIZE built-in function will return the addresses of any additional
parameters.
v If the additional parameters to this procedure were passed by reverence
(BYADDR), successively incrementing this initial address by the size of a pointer
will return the addresses of any additional parameters.
Example
The following sample program, which implements a simple version of printf,
illustrates how to use the LIST attribute. The routine varg1 illustrates how to walk
a variable argument list with BYVALUE parameters, and varg2 illustrates how to
walk such a list with BYADDR parameters.
*process ;
varg1:
proc( text )
options( nodescriptor byvalue );
ptext = addr(text);
ltext = length(text);
iz = index( substr(ptext->chars,1,ltext), % );
p = varglist();
do while( iz > 0 );
if iz = 1 then;
else
put edit( substr(ptext->chars,1,iz-1) )(a);
ptext += iz;
ltext -= iz;
select( ptext->ch );
when( i )
do;
put edit( trim(p->i) )(a);
p += vargsize( p->i );
end;
when( d )
do;
put edit( trim(p->d) )(a);
p += vargsize( p->d );
end;
end;
ptext += 1;
ltext -= 1;
if ltext <= 0 then leave;
iz = index( substr(ptext->chars,1,ltext), % );
end;
if ltext = 0 then;
else
put edit( substr(ptext->chars,1,ltext) )(a);
put skip;
end;
*process ;
varg2:
proc( text )
options( nodescriptor byaddr );
ptext = addr(text);
ltext = length(text);
iz = index( substr(ptext->chars,1,ltext), % );
p = varglist();
do while( iz > 0 );
if iz = 1 then;
else
put edit( substr(ptext->chars,1,iz-1) )(a);
ptext += iz;
ltext -= iz;
select( ptext->ch );
when( i )
do;
put edit( trim(p->p2->i) )(a);
p += size( p );
end;
when( d )
do;
put edit( trim(p->p2->d) )(a);
p += size( p );
end;
end;
ptext += 1;
ltext -= 1;
if ltext <= 0 then leave;
iz = index( substr(ptext->chars,1,ltext), % );
end;
if ltext = 0 then;
else
put edit( substr(ptext->chars,1,ltext) )(a);
put skip;
end;
LIMITED attribute
The LIMITED attribute indicates that the entry variable has only non-nested entry
constants as values. A entry variable that is not LIMITED can have any entry
constants as values.
LIMITED
Example
A LIMITED static entry variable can be initialized with the value of a non-nested
entry constant, thus allowing generation of more efficient code. It also uses less
storage than a non-LIMITED entry variable.
Example: proc options(reorder reentrant);
dcl (Read, Write) entry;
dcl FuncRtn(2) entry limited
static init (Read, Write);
Generic entries
A generic entry declaration specifies a generic name for a set of entry references
and their descriptors.
GENERIC attribute
The generic name must be explicitly declared with the GENERIC attribute.
) ;
references
,
,
entry-ref WHEN ( )
generic-descriptor
*
generic-descriptor:
data-attributes
ALIGNED ASSIGNABLE INOUT
UNALIGNED (1) INONLY
NONASSIGNABLE OUTONLY
CONNECTED HEXADEC BIGENDIAN OPTIONAL
(1) IEEE LITTLEENDIAN
NONCONNECTED
Notes:
1 If specified, this keyword is ignored.
For the general declaration syntax, see DECLARE statement on page 160.
entry-ref
Must not be subscripted or defined. The same entry reference can appear more
than once within a single GENERIC declaration with different lists of
descriptors.
generic-descriptor
Corresponds to a single argument. It specifies an attribute that the
corresponding argument must have so that the associated entry reference can
be selected for replacement.
Structures or unions cannot be specified.
Where a descriptor is not required, its absence must be indicated by an
asterisk.
The descriptor that represents the absence of all arguments in the invoking
statement is expressed by omitting the generic descriptor in the WHEN clause
of the entry. It has the form:
generic (... entry1 when( ) ...)
data-attributes
Listed in Data types and attributes on page 17.
In the following example, an entry reference that has exactly two descriptors with
the attributes DECIMAL or FLOAT, and BINARY or FIXED is searched for.
declare Calc generic (
Fxdcal when (fixed,fixed),
Flocal when (float,float),
Mixed when (float,fixed),
Error otherwise);
Dcl X decimal float (6),
Y binary fixed (15,0);
Z = X+Calc(X,Y);
If an entry with the exact number of descriptors with the exact attributes is not
found, the entry with the OTHERWISE clause is selected if present. In the previous
example, Mixed is selected as the replacement.
If all of the descriptors are omitted or consist of an asterisk, the first entry
reference with the correct number of descriptors is selected.
The following table explains the conditions under which an entry reference is
invoked or not invoked.
Example 1
In this example, A is invoked, B(C) passes C as an entry value, and D( C() )
invokes C.
dcl ( A, B, C returns (fixed bin), D) entry;
call A; /* A is invoked */
call B(C); /* C is passed as an entry value */
call D( C() ); /* C is invoked */
Example 2
In this example, the first assignment is not valid because it represents an attempt
to assign an entry constant to an integer. The second assignment is valid.
dcl A fixed bin,
B entry returns ( fixed bin );
A = B;
A = B();
CALL statement
The CALL statement invokes a subroutine.
CALL entry-reference ( ) ;
generic-name ,
built-in-name
argument
*
entry-reference
Specifies that the name of the subroutine to be invoked is declared with the
ENTRY attribute. See Entry data on page 119.
generic-name
Specifies that the name of the subroutine to be invoked is declared with the
GENERIC attribute. See Generic entries on page 130.
built-in name
Specifies the name of the subroutine to be invoked is declared with the
BUILTIN attribute. See BUILTIN attribute on page 409.
argument
Is an element, an element expression, or an aggregate to be passed to the
invoked subroutine. See Passing arguments to procedures on page 114.
References and expressions in the CALL statement are evaluated in the block in
which the call is executed. This includes execution of any ON-units entered as the
result of the evaluations.
RETURN statement
The RETURN statement terminates execution of the subroutine or function
procedure that contains the RETURN statement and returns control to the invoking
procedure. Control is returned to the point immediately following the invocation
reference.
The RETURN statement with an expression should not be used within a procedure
with OPTIONS(MAIN).
A procedure with the RETURNS option must contains at least one RETURN
statement (with an expression, of course).
RETURN ;
If the RETURN statement terminates the main procedure, the FINISH condition is
raised before program termination.
RETURN (expression) ;
The value returned to the function reference is the value of the expression
specified, converted to conform to the attributes specified in the RETURNS option
of the ENTRY or PROCEDURE statement at which the function was entered.
Consider the following example:
BEGIN statement
ORDER
OPTIONS ( )
REORDER
NOCHARGRAPHIC
CHARGRAPHIC
NOINLINE
INLINE
ENTRY declaration
OPTIONS ( )
ASSEMBLER
RETCODE
COBOL
FORTRAN
FETCHABLE
BYADDR
BYVALUE
DESCRIPTOR
NODESCRIPTOR
LINKAGE ( linkage )
IRREDUCIBLE
REDUCIBLE
NOMAP
parameter-list
NOMAPIN
parameter-list
NOMAPOUT
parameter-list
ENTRY statement
OPTIONS ( REENTRANT )
ASSEMBLER
RETCODE
COBOL
FORTRAN
BYADDR
BYVALUE
DESCRIPTOR
NODESCRIPTOR
DLLINTERNAL
LINKAGE(linkage)
NOMAP
parameter-list
NOMAPIN
parameter-list
NOMAPOUT
parameter-list
IRREDUCIBLE
REDUCIBLE
PACKAGE statement
NOCHARGRAPHIC
OPTIONS ( )
CHARGRAPHIC
ORDER
REORDER
REENTRANT
PROCEDURE statement
OPTIONS ( )
ASSEMBLER
COBOL
FORTRAN
FETCHABLE
MAIN
NOEXECOPS
BYADDR
BYVALUE
NOCHARGRAPHIC
CHARGRAPHIC
DESCRIPTOR
NODESCRIPTOR
DLLINTERNAL
FROMALIEN
LINKAGE ( linkage )
NOMAP
parameter-list
NOMAPIN
parameter-list
NOMAPOUT
parameter-list
NOINLINE
INLINE
ORDER
REORDER
IRREDUCIBLE
REDUCIBLE
REENTRANT
RETCODE
WINMAIN
The options are separated by blanks or commas. They can appear in any order.
ASSEMBLER
Abbreviation: ASM
The ASSEMBLER option has the same effect as NODESCRIPTOR.
If a procedure has the ASSEMBLER option, then upon exit from that
procedure, the PLIRETV() value will be used as the return value for the
procedure.
A PROCEDURE or ENTRY statement that specifies OPTIONS(ASSEMBLER)
will have LINKAGE(SYSTEM) unless a different linkage is explicitly specified.
For more information, refer to the Programming Guide.
BYADDR or BYVALUE
These specify how arguments and parameters are passed and received.
BYADDR is the default.
BYVALUE can be specified only for scalar arguments and parameters that have
known lengths and sizes.
The BYVALUE and BYADDR attributes can also be specified in the description
list of an entry declaration and in the attribute list of a parameter declaration.
Specifying BYVALUE or BYADDR in an entry or a parameter declaration
overrides the option specified in an OPTIONS statement.
The following examples show BYVALUE and BYADDR in both entry
declarations and in the OPTIONS statement. The examples assume that the
compiler option DEFAULT(BYADDR) is in effect.
Example 1:
MAINPR: proc options(main);
D: proc(I, Q, C)
options(byvalue);
dcl I fixed bin byaddr,
Q ptr,
C char(4) byvalue;
E2: proc(Q);
dcl Q ptr;
Example 2:
dcl F entry (fixed bin byaddr, /* byaddr not needed */
ptr,
char(4) byvalue)
options(byaddr);
dcl E3 entry;
dcl E4 entry (fixed bin byvalue);
F: proc(I,P,C) options(byaddr);
dcl I fixed bin byaddr; /* byaddr not needed */
dcl P ptr byaddr; /* byaddr not needed */
dcl C char(4) byvalue; /* byvalue needed */
E3: proc(L);
dcl L char(4);
E4: proc(N);
dcl N fixed bin byvalue;
CHARGRAPHIC or NOCHARGRAPHIC
Abbreviations: CHARG, NOCHARG
The default for an external procedure is NOCHARG. Internal procedures and
begin-blocks inherit their defaults from the containing procedure.
When CHARG is in effect, the following semantic changes occur:
v All character string assignments are considered to be mixed character
assignments.
v STRINGSIZE condition causes the MPSTR built-in function to be used.
STRINGSIZE must be enabled for character assignment that can cause
truncation and intelligent DBCS truncation is required. See the following
example:
Name: procedure options(chargraphic);
dcl A char(5);
dcl B char(8);
(stringsize): A=B;
A=mpstr(B,vs,length(A));
When NOCHARG is in effect, no semantic changes occur.
COBOL
This option has the same effects as NODESCRIPTOR, but additionally
OPTIONS(COBOL) has the following effects:
v Implies LINKAGE(SYSTEM) unless a different linkage is specified on the
entry declaration or procedure statement.
v Permits the use of the NOMAP, NOMAPIN, and NOMAPOUT options.
v Implies, if specified on a procedure statement, that upon exit from that
procedure, the PLIRETV() value will be used as the return value for the
procedure.
COBOL and MAIN must not be specified together.
DESCRIPTOR or NODESCRIPTOR
These indicate whether the procedure specified in the entry declaration or
procedure statement will be passed a descriptor list when it is invoked.
If DESCRIPTOR appears, the compiler passes descriptors, if necessary.
If NODESCRIPTOR appears, the compiler does not pass descriptors.
Each option argument-list can specify the parameters to which the option
applies. Parameters can appear in any order and are separated by commas or
blanks. If there is no argument-list for an option, the default list is all the
parameters of the entry name.
NOMAP, NOMAPIN, and NOMAPOUT can all appear in the same OPTIONS
specification. This specification should not include the same parameter in more
than one specified or default argument list.
These options are accepted but ignored unless the COBOL option applies.
ORDER or REORDER
ORDER and REORDER are optimization options that are specified for a
procedure or begin-block.
ORDER indicates that only the most recently assigned values of variables
modified in the block are available for ON-units that are entered because of
computational conditions raised during statement execution and expressions in
the block.
The REORDER option allows the compiler to generate optimized code to
produce the result specified by the source program when error-free execution
takes place.
For more information about using the ORDER and REORDER options, refer to
the Programming Guide.
If neither option is specified for the external procedure, the default is set by the
DEFAULT compiler option. Internal blocks inherit ORDER or REORDER from
the containing block.
REDUCIBLE or IRREDUCIBLE
Abbreviations: RED, IRRED
REDUCIBLE indicates that a procedure or entry need not be invoked multiple
times if the argument(s) stays unchanged, and that the invocation of the
procedure has no side effects.
For example, a user-written function that computes a result based on
unchanging data should be declared REDUCIBLE. A function that computes a
result based on changing data, such as a random number or time of day,
should be declared IRREDUCIBLE.
REENTRANT
This option is ignored. On the Intel and AIX platforms, all PL/I programs are
reentrant. On the z/OS platform, all programs compiled with the RENT
compiler option are reentrant, and other programs are reentrant if they do not
alter any static variables (which might require use of the NOWRITABLE
compiler option).
RETCODE
This option specifies that if the ENTRY point also has the ASM or COBOL
option, the ENTRY will return a value that will be saved, after the ENTRY is
invoked, as the PL/I return code. Essentially, after such an ENTRY is invoked,
its return value will be passed to the PLIRETC subroutine.
WINMAIN (Windows only)
The RETURNS option and the RETURNS attribute are used to specify the
attributes of the value that is being returned. The attributes in the RETURNS
option must match the attributes in the RETURNS attribute.
Procedures that are subroutines (and are therefore invoked by the CALL statement)
must not have the RETURNS option on the procedure statement and their entry
declaration must not have the RETURNS attribute.
RETURNS ( attribute )
If more than one attribute is specified, they must be separated by blanks (except
attributes such as precision that are enclosed in parentheses).
The attributes are specified in the same way as they are in a declare statement.
Defaults are applied in the normal way.
The attributes that can be specified are any of the data attributes and alignment
attributes for scalar variables (as shown in Table 8 on page 21). ENTRY variables
must have the LIMITED attribute. In addition, you can specify the TYPE attribute
to name user-defined types, ordinals, and typed structures and unions.
String lengths and area sizes must be specified by constants. The returned value
has the specified length or size.
BYADDR and BYVALUE can also be specified in the list of attributes for
RETURNS. The BYADDR attribute must be in effect if a procedure contains any
ENTRY statements and the procedure or any of its secondary entry points returns
no value or an aggregate value.
For information about these built-in data types, see Chapter 2, Data elements, on
page 15.
All types that are created by DEFINE statements follow the same scoping rules
that apply to names in DECLARE statements. For example, an ORDINAL defined
in a procedure is known in all child procedures of that procedure, but not in any
of its sister or parent procedures. Therefore, if a procedure returns a type, that type
must be defined in a parent procedure or at the package level.
A DEFINE statement for a type must precede any use of that type.
In this way, you can assign meaningful names to data types and improve the
understandability of a program. By defining an alias, you can also provide a
shorter notation for a set of data attributes, which can decrease typographical
errors.
alias-name
Specifies the name that can be used wherever the explicit data type defined by
the specified attributes is allowed.
attributes
The attributes that can be specified are any of the attributes for variables that
can be returned by a function (for example, those attributes valid in the
RETURNS option and attribute). These valid attributes are listed in Table 8 on
page 21. Therefore, you cannot specify an alias for an array or a structured
attribute list. However, you can specify an alias for a type that is defined in a
Example
Defining ordinals
An ordinal is a named set of ordered values. Using the DEFINE ORDINAL
statement, you can define an ordinal and assign meaningful names to be used to
refer to that set.
For example, you can define an ordinal called color. The color ordinal could
include the members red, yellow, blue, and so on. The members of the color set
can then be referred to by these names instead of by their associated fixed binary
value, making code much more self-documenting. Furthermore, a variable declared
with the ordinal type can be assigned and compared only with an ordinal of the
same type, or with a member of that ordinal type. This automatic checking
provides for better program reliability.
;
PRECISION (integer) SIGNED
UNSIGNED
ordinal-value-list:
member
VALUE(integer)
ordinal-type-name
Specifies the name of the set of ordinal values. This name can be used only in
DECLARE statements with the ORDINAL attribute. Use of this name
elsewhere results in it being treated as any other nonordinal name.
member
Specifies the name of a member within the set.
VALUE
Specifies the value of a particular member within the set. If the VALUE
attribute is omitted for the first member, a value of zero is used. If the VALUE
attribute is omitted for any other member, the next greater integer value is
used.
The value in the given (or assumed) VALUE attribute must be an integer, can
be signed, and must be strictly increasing. The value in the given (or assumed)
VALUE attributed can also be specified as an XN constant.
PRECISION
Abbreviation: PREC
Specifies the precision of a particular ordinal value. If omitted, the precision is
determined by the range of ordinal values.
The maximum precision is the same as that for data items declared FIXED
BINARY.
SIGNED or UNSIGNED
Indicates whether ordinal values can assume negative values. If omitted, they
are determined by the range of ordinal values. For example, if any value is
negative, the SIGNED attribute is applied.
Example
In the following example, Red has the value 0, Orange has the value 1, and so on.
But Low has the value 2 and Medium has the value 3.
define ordinal Color ( Red, /* is 0, since VALUE is omitted */
Orange,
Yellow,
Green,
Blue,
Indigo,
Violet );
level minor-structure-name ;
attribute
Abbreviation: STRUCT
structure-type-name
Specifies the name given to this structure type. This name cannot have
dimensions, although substructures can.
UNION
See UNION attribute on page 190.
minor-structure-name
Specifies the name given to a deeper level.
attributes
Specifies attributes for the minor-structure name. Only the following attributes
are allowed:
v The data attributes
v The INITIAL nondata attribute
v The VALUE nondata attribute
For more information about the VALUE attribute, see Named constants on
page 45.
Any string lengths, area sizes, or array dimensions specified in a DEFINE STRUCT
statement must be restricted expressions.
Missing data attributes are supplied with PL/I defaults. If a variable is declared as
a typed structure, none of the following attributes are propagated to the members
of the typed structure. These attributes are propagated if the variable is declared as
an untyped structure.
v ALIGNED|UNALIGNED
v ASSIGNABLE|NONASSIGNABLE
v DIMACROSS
v NATIVE|NONNATIVE
v NORMAL|ABNORMAL
v SUPPRESS
Restrictions:
v Defined structures must occupy a number of bytes that is a multiple of the
structures alignment.
v In a defined structure, the number of bytes before the element with the most
stringent alignment must be a multiple of that element's alignment.
For example, if a structure contains an aligned fixed bin(31) field as its most
stringently aligned item, the following applies:
v The structure must occupy a multiple of 4 bytes.
v There must be a multiple of 4 bytes before the first aligned fixed bin(31) field.
define structure
1 parent,
2 first_child handle child,
2 parent_data fixed bin(31);
define structure
1 child,
2 parent handle parent,
2 next_child handle child,
2 child_data fixed bin(31);
Related information:
Structures on page 188
A structure is a collection of member elements that can be structures, unions,
elementary variables, and arrays.
INITIAL attribute on page 288
The INITIAL attribute specifies an initial value or values assigned to a variable at
the time storage is allocated for it.
HANDLE attribute
You can use the HANDLE attribute to declare a variable as a pointer to a structure
type. Such a variable is called a handle.
HANDLE structure_type_name
( 32 ) (structure-type-name)
64
If the LP(32) compiler option is in effect, the default is HANDLE(32); if the LP(64)
compiler option is in effect, the default is HANDLE(64). HANDLE(64) is valid only
under LP(64).
Like defined structures, handles are strongly typed: they can only be assigned to or
compared with handles for the same structure type. No arithmetic operations are
permitted on handles.
You cannot use the ADDR built-in function to assign the address of a typed
structure to a handle because the ADDR built-in function returns a pointer, and
pointers cannot be assigned to handles. However, the HANDLE built-in function
takes a typed structure as its argument and returns a handle to that type. Consider
the following example:
P_Daterec = handle(Daterec);
TYPE attribute
This topic shows the syntax for the TYPE attribute.
TYPE defined-type-name
(defined-type-name)
defined-type-name
Specifies the name of a previously defined alias, defined structure, or ordinal
type.
Example 1
The TYPE attribute can be used in a DEFINE ALIAS statement to specify an alias
for a type defined in a previous DEFINE ALIAS statement. See the following
example:
define alias Word fixed bin(31);
define alias Short type word;
Example 2
The following example defines several named types, a structure type (tm), and
declares the C function that gets a handle to this typed structure:
define alias int fixed bin(31);
define alias time_t fixed bin(31);
define structure
1 tm
,2 tm_sec type int /* seconds after the minute (0-61) */
,2 tm_min type int /* minutes after the hour (0-59) */
,2 tm_hour type int /* hours since midnight (0-23) */
,2 tm_mday type int /* day of the month (1-31) */
,2 tm_mon type int /* months since January (0-11) */
,2 tm_year type int /* years since 1900 */
,2 tm_wday type int /* days since Sunday (0-6) */
,2 tm_yday type int /* days since January 1 (0-365) */
,2 tm_isdst type int /* Daylight Saving Time flag */
;
ORDINAL attribute
You can use the TYPE or ORDINAL attribute to declare variables with an ordinal
type.
See TYPE attribute on page 150 for the syntax for the TYPE attribute.
ORDINAL ordinal-type-name
ordinal-type-name
Specifies the name of a previously defined set of ordinal values.
The ORDINAL attribute conflicts with other data attributes such as FIXED or
SIGNED, but it is allowed with attributes such as BASED or DIMENSION.
Example
dcl Wall_color ordinal Color;
For example, given the following declares and definitions, B is a valid reference,
but Y is not.
dcl 1 A,
2 B fixed bin,
2 C fixed bin;
define structure
1 X,
2 Y fixed bin,
2 Z fixed bin;
dcl S type X;
Type names are also in a separate name space from declared names. Therefore, you
can use the name of a type as a variable name as well.
define alias Hps pointer;
declare Hps type Hps;
typed-structure-name . typed-structure-member
typed-structure-reference
Name of the declared typed structure
typed-structure-member
Name of the referenced major or minor structure member of the structure type
For example, given the structure type tm and function localtime defined in the
examples in TYPE attribute on page 150, the following code obtains the system
date and displays the time:
dcl Daterec type tm;
display ( edit(Daterec.Hours,99) { : {
edit(Daterec.Minutes,99) { : {
edit(Daterec.Seconds,99));
For details, see Combinations of arrays, structures, and unions on page 198.
Example 1
Given this untyped structure, a(1).b(2), a.b(1,2), and a(1,2).b have the same
meaning.
Example 2
However, given the following typed structure, only x(1).b(2) is valid.
define structure
1 t,
2 b(4) fixed bin,
2 c(5) fixed bin;
Example 3
This example is based on the structure type t defined in Example 2 on page 153.
Using handles
Handles access members of a typed structure with the => operator.
In the following example, given the tm type defined in Example 2 on page 151,
the time is displayed by using a handle to that type:
dcl P_Daterec handle tm;
P_Daterec = handle(Daterec);
display ( edit(P_Daterec=>tm_hours,99) { : {
edit(P_Daterec=>tm_min,99) { : {
edit(P_Daterec=>tm_sec,99) );
Handles can locate any member in a typed structure, including the level-1 name
(the type name itself). A reference by a handle to its type name constitutes a
reference to the typed structure which is pointed to by that handle. This allows
reference to this aggregate data by its handle. For example, given that H1 and H2
point to two allocated structures, you can swap two structures as follows:
define structure 1 T, 2 U, 2 V, 2 W;
dcl (H1, H2) handle T;
dcl Temp type T;
Temp = H1=>T;
H1=>T = H2=>T;
H2=>T = Temp;
Using ordinals
When using ordinals, keep in mind these usage rules.
v Ordinals are strongly-typed; that is, an ordinal can only be compared with or
assigned to another ordinal of the same type. The ordinal must have been
explicitly declared in a DECLARE statement.
v The ordinal-type-name in a DEFINE ORDINAL statement cannot be used in
comparisons or assignments.
v Ordinals can be passed/received as arguments/parameters like any other data
type.
v Ordinals are invalid as arguments for all built-in functions requiring arguments
with computational types. However, in support of ordinals, built-in functions
have been defined and BINARYVALUE has been extended. These built-in
functions are listed in Table 35. For descriptions of these functions, see
Chapter 18, Built-in functions, pseudovariables, and subroutines, on page 409.
Each of the built-in functions listed takes exactly one argument, which must be a
reference having type ORDINAL.
Table 35. Ordinal-handling built-in functions
Function Description
BINARYVALUE Converts an ordinal to a binary value
In the following sample code, the first DO loop lists, in ascending order, the
members of the Color set; the second DO loop lists them in descending order. The
example uses the ordinal definition from Example on page 147.
dcl Next_color ordinal Color;
An ordinal cannot be used as an index into an array and cannot define an extent
for a variable, including the lower or upper bound of an array. However, an
ordinal can be converted to binary by the BINARYVALUE built-in function. The
value that is returned by this function can then be used to index into an array or
define an extent.
For example, the following package defines an array usage_count to hold the
number of times each color is used, a procedure Record_usage to update this array,
and a procedure Show_usage to display the values in this array.
Usage: package exports(*);
: binvalue( last(:Color:)) )
static fixed bin(31) init( (*) 0 );
/* first(:Color:) = Red */
/* last(:Color:) = Violet */
Usage_count( binvalue(Wall_color) )
= 1 + Usage_count( binvalue(Wall_color) );
end Record_usage;
Show_usage: proc;
dcl Next_color type Color;
end Usage;
Ordinals can be used to create functions that are easy to maintain and enhance and
are as efficient as table look-ups.
In the following example, the function Is_mellow returns a bit indicating whether a
color is or is not mellow. If more colors are defined, the mellow ones can be
added to the list of colors in the select-group. In a select-group, unlike a hand-built
table, the colors do not have to be in the same order as in the DEFINE statement,
or in any particular order at all.
However, because all of the statements inside the select-group consist of RETURN
statements that return constant values, the compiler will convert the entire
select-group into a simple table look-up.
Is_mellow: proc( Test_color ) returns( bit(1) aligned );
select (Test_color);
when( Yellow, Indigo)
return( 1b );
otherwise
return( 0b );
end;
end;
This feature can also be used to define your own version of the ORDINALNAME
built-in function. Your own version can return the name you want to be displayed
for each ordinal value. For example, the following function Color_name returns the
color name associated with each name with the first letter capitalized:
Color_name: proc( Test_color ) returns( char(8) varying );
select (Test_color);
when ( Blue ) return( Blue);
when ( Green ) return( Green);
when ( Orange ) return( Orange);
end;
Type functions
Because type names are in a separate name space from declared names, they
cannot be used where variable references are required, in particular as arguments
to built-in functions. However, type names can be used as arguments to type
functions. (In ANSI terminology, these type functions are known as enquiry
functions.)
Related information:
Chapter 19, Type functions, on page 799
Using type functions, you can manipulate defined types. This chapter describes the
type functions.
Most attributes of data items are known at the time the program is compiled. For
nonstatic items, attribute values (the bounds of the dimensions of arrays, the
lengths of strings, area sizes, initial values) and some file attributes can be
determined during execution of the program. See Block activation on page 93 for
more information.
Data items, types, and attributes are introduced in Chapter 2, Data elements, on
page 15.
Explicit declaration
An explicit declaration is the appearance of an identifier (a name) in a DECLARE
statement, as a label prefix, or in a parameter list.
Notes:
1. Naming an internal entry constant, a label constant, or a format constant in a
DECLARE statement is invalid.
2. The bounds, if any, for a label or format constant are determined by the
smallest and largest values that are specified in any use of it as a label in the
source code.
B and B indicate the two distinct uses of the name B; C and C indicate the two
uses of the name C.
Related information:
DECLARE statement
The DECLARE statement specifies some or all of the attributes of a name. If the
attributes are not explicitly declared and cannot be determined by context, default
attributes are applied.
DECLARE name ;
level * attributes
attributes:
data-attributes
alignment-attributes
scope-attributes
storage-attributes
complementary-attributes
Abbreviation: DCL
For more information about declaring arrays, structures, and unions, see Arrays
on page 184, Structures on page 188, and Unions on page 189.
* Cannot be used as the name of an INTERNAL or an EXTERNAL scalar or as
the name of a level-1 EXTERNAL structure or union unless the EXTERNAL
attribute specifies an environment name (see INTERNAL and EXTERNAL
attributes on page 165).
attributes
The attributes can appear in any order.
All attributes given explicitly for the name must be declared together in a
DECLARE statement, except that:
Names having the FILE attribute can also be given attributes in an OPEN
statement (or have attributes implied by an implicit opening).
Factoring attributes
Attributes common to several names can be factored to eliminate repeated
specification of the same attributes. To achieve factoring, enclose the names in
parentheses followed by the set of attributes that apply to all of the names.
Factoring can be nested. The dimension attribute can be factored. Factoring can
also be used on elementary names within structures and unions. A factored
level-number must precede the parenthesized list.
Examples
The following examples show factoring. The last declaration shows nested
factoring.
declare (A,B,C,D) binary fixed (31);
Implicit declaration
If a name appears in a program and is not explicitly declared, it is implicitly
declared. The scope of an implicit declaration is determined as if the name were
declared in a DECLARE statement immediately following the PROCEDURE
statement of the external procedure in which the name is used.
With the exception of files, entries, and built-in functions, implicit declaration has
the same effect as if the name were declared in the outermost procedure. For files
and built-in functions, implicit declaration has the same effect as if the names were
declared in the logical package outside any procedures.
Note: Using implicit declarations for anything other than built-in functions and the
files SYSIN and SYSPRINT is in violation of the 1987 ANSI standard and should be
avoided.
Some attributes for a name declared implicitly can be determined from the context
in which the name appears. These cases, called contextual declarations, are listed as
follows:
v A name of a built-in function.
v A name that appears in a CALL statement or the CALL option of INITIAL, or
that is followed by an argument list, is given the ENTRY and EXTERNAL
attributes.
v A name that appears in the parameter list of a PROCEDURE or ENTRY
statement is given the PARAMETER attribute.
v A name that appears in a FILE or COPY option, or a name that appears in an
ON, SIGNAL, or REVERT statement for a condition that requires a file name, is
given the FILE attribute.
v A name that appears in an ON CONDITION, SIGNAL CONDITION, or
REVERT CONDITION statement is given the CONDITION attribute.
v A name that appears in the BASED attribute, in a SET option, or on the
left-hand side of a locator qualification symbol is given the POINTER attribute.
v A name that appears in an IN option, or in the OFFSET attribute, is given the
AREA attribute.
Implicit declarations that are not contextual declarations acquire all attributes by
default, as described in Defaults for attributes on page 178. Because a contextual
declaration cannot exist within the scope of an explicit declaration, it is impossible
for the context of a name to add to the attributes established for that name in an
explicit declaration.
In the following statements, PREQ is given the FILE attribute, and S is given the
AREA attribute.
read file (PREQ) into (Q);
allocate X in (S);
Scope of declarations
The part of the program to which a name applies is called the scope of the
declaration of that name. In most cases, the scope of the declaration of a name is
determined entirely by the position where the name is declared within the
program.
It is not necessary for a name to have the same meaning throughout a program. A
name explicitly declared within a block has a meaning only within that block.
Outside the block, the name is unknown unless the same name has also been
declared in the outer block. Each declaration of the name establishes a scope and
in this case, the name in the outer block refers to a different data item. This enables
you to specify local definitions and, hence, to write procedures or begin-blocks
without knowing all the names used in other parts of the program.
In the following example, the output for A is actually C.A, which is 2. The output
for B is 1, as declared in procedure X.
X: proc options(main);
dcl (A,B) char(1) init(1);
call Y;
return;
Y: proc;
dcl 1 C,
3 A char(1) init(2);
put data(A,B);
return;
end Y;
end X;
Thus, for nested procedures, PL/I uses the variable declared within the current
block before using any variables that are declared in containing blocks.
All of the text of a block, from the PACKAGE, PROCEDURE, or BEGIN statement
through the corresponding END statement (including condition prefixes of BEGIN,
PACKAGE, and PROCEDURE statements), is said to be contained in that block.
However, the labels of the BEGIN or PROCEDURE statement heading the block, as
well as the labels of any ENTRY statements that apply to the block, are not
contained in that block. Nested blocks are contained in the block in which they
appear.
Text that is contained in a block, but not contained in any other block nested
within it, is said to be internal to that block. Entry names of a procedure (and
labels of a BEGIN statement) are not contained in that block. Consequently, they
are internal to the containing block. Entry names of an external procedure are
treated as if they were external to the external procedure.
The brackets to the left indicate the block structure; the brackets to the right show
the scope of each declaration of a name. The scopes of the two declarations of Q
and R are shown as Q and Q and R and R.
Note that X and Y are visible to all of the procedures contained in the package.
1 P is declared in the block A and known throughout A because it is not
redeclared.
2 Q is declared in block A, and redeclared in block B. The scope of the first
declaration of Q is all of A except B; the scope of the second declaration of Q
is block B only.
3 R is declared in block C, but a reference to R is also made in block B. The
reference to R in block B results in an implicit declaration of R in A, the
external procedure. Therefore, two separate names (R and R in Figure 7)
with different scopes exist. The scope of the explicitly declared R is block C;
the scope of the implicitly declared R in block B is all of A except block C.
4 I is referred to in block C. This results in an implicit declaration in the
external procedure A. As a result, this declaration applies to all of A,
including the contained procedures B, C, and D.
5 S is explicitly declared in procedure D and is known only within D.
Figure 8 on page 165 illustrates the scopes of entry constant and statement label
declarations.
INTERNAL
EXTERNAL
( environment-name )
The name for xyz is decorated. For more information about the decoration of
environment names, see the Understanding linkage considerations topic in
the Calling conventions chapter in the PL/I for Windows Programming Guide.
INTERNAL is the default for entry names of internal procedures and for all other
variables except for entry constants, file constants and programmer defined
conditions. INTERNAL specifies that the name can be known only in the declaring
block. Any other explicit declaration of that name refers to a new object with a
different scope that does not overlap.
EXTERNAL is the default for file constants, entry constants (other than internal
procedures) and programmer-defined conditions. A name with the EXTERNAL
attribute can be declared more than once, either in different external procedures or
within blocks contained in external procedures. All declarations of the same name
with the EXTERNAL attribute refer to the same data. The scope of each declaration
of the name (with the EXTERNAL attribute) includes the scopes of all the
declarations of that name (with EXTERNAL) within the application.
When a major structure or union name is declared EXTERNAL in more than one
block, the attributes of the members must be the same in each case, although the
corresponding member names need not be identical.
%process;
ProcB: procedure;
declare 1 A external,
2 B,
2 D;
.
.
.
end ProcB;
If A.B is changed in ProcA, it is also changed for ProcB, and vice versa; if A.C is
changed in ProcA, A.D is changed for ProcB, and vice versa.
Because external declarations for the same name all refer to the same data, they
must all result in the same set of attributes. When EXTERNAL names are declared
in different external procedures, the user has the responsibility to ensure that the
attributes are matching. Figure 9 on page 168 illustrates a variety of declarations
and their scopes.
1 A is an external procedure name. Its scope is all of block A, plus any other
blocks where A is declared as external.
2 S is explicitly declared in block A and block C. The character variable
declaration applies to all of block A except block C. The fixed binary
declaration applies only within block C. Notice that although D is called
from within block C, the reference to S in the PUT statement in D is to the
character variable S, and not to the S declared in block C.
3 N appears as a parameter in block D, but is also used outside the block. Its
appearance as a parameter establishes an explicit declaration of N within D.
The references outside D cause an implicit declaration of N in block A. These
two declarations of the name N refer to different objects, although in this
case, the objects have the same data attributes, which are, by default,
FIXED BINARY(15,0) and INTERNAL. Under DEFAULT(ANS), the
precision is (31,0).
4 X and Y are known throughout B and can be referred to in block C or D
within B, but not in that part of A outside B.
5 P and Q are parameters, and therefore if there were no other declaration of
these names within the block, their appearance in the parameter list would
be sufficient to constitute a contextual declaration. However, a separate,
explicit declaration statement is required in order to specify that P and Q
are arrays. Although the arguments X and Y are declared as arrays and are
known in block C, it is still necessary to declare P and Q in a DECLARE
statement to establish that they, too, are arrays. (The asterisk notation
indicates that the bounds of the parameters are the same as the bounds of
the arguments.)
6 I and M are not explicitly declared in the external procedure A. Therefore,
they are implicitly declared and are known throughout A, even though I
appears only within block C.
7 The Out and Set external procedures in the example have an external
declaration of L that is common to both. They also must be declared
explicitly with the ENTRY attribute in procedure A. Because ENTRY
implies EXTERNAL, the two entry constants Set and Out are known
throughout the two external procedures.
8 The label B appears twice in the programfirst in A, as the label of a
begin-block, which is an explicit declaration, and then redeclared as a label
within block C by its appearance as a prefix to an END statement. The go
to B statement within block C, therefore, refers to the label of the END
statement within block C. Outside block C, any reference to B is to the label
of the begin-block.
9 Blocks C and D can be called from any point within B but not from that part
of A outside B, nor from another external procedure. Similarly, because
label E is known throughout the external procedure A, a transfer to E can
be made from any point within A. The label B within block C, however, can
be referred to only from within C. Transfers out of a block by a GO TO
statement can be made; but such transfers into a nested block generally
cannot. An exception is shown in the external procedure Out, where the
label E from block C is passed as an argument to the label parameter R.
Note that, with no files specified in the GET and PUT statements, SYSIN
and SYSPRINT are implicitly declared.
10 The statement else go to R; transfers control to the label E, even though E
is declared within A, and not known within Out.
11 The variables K (INTERNAL) and L (EXTERNAL) are declared as STATIC
within the Out procedure block; their values are preserved between calls to
Out.
12 In order to identify the S in the procedure Out as the same S in the
procedure C, both are declared with the attribute EXTERNAL.
RESERVED attribute
The RESERVED attribute implies STATIC EXTERNAL.
Moreover, if a variable has the RESERVED attribute, the application must comply
with the following conditions:
v All declarations of the variable must specify RESERVED.
v The variable name must appear in the RESERVES option of exactly one package.
If a variable has the RESERVED attribute, any INITIAL values are ignored except
in the package reserving it.
RESERVED
(IMPORTED)
If a compilation unit has a variable with the RESERVED attribute and is not the
reserving package for that variable, that compilation unit must either be part of the
load module that contains the reserving package or import the variable from
another load module that contains the reserving package. In the latter case, the
following conditions apply:
v The declaration for the variable must specify the RESERVED(IMPORTED)
attribute.
v The variable must be exported from a DLL.
v The sidefile that is associated with the DLL must be included during the linking
of the importing module.
Example
In the following example, the package owns_x reserves and initializes the storage
for the variable x. It must be linked into the same load module as the package
owns_y. This load module must import the variable z from the load module into
which package owns_z is linked.
owns_x:
package
exports(*)
reserves(x);
end;
owns_y:
package
exports(*)
reserves(y);
end;
owns_z:
package
exports(*)
reserves(z);
end;
FORCE attribute
You can use the FORCE attribute to instruct the compiler to issue various
messages.
FORCE ( )
NOLAXQUAL
NOLAXQUAL
Specifying FORCE(NOLAXQUAL) on a variable causes the compiler to flag
any reference to the variable that is not properly qualified.
If the FORCE attribute is specified on a structure or union, it also applies to all the
elements of that structure (or union).
SUPPRESS attribute
You can use the SUPPRESS attribute to instruct the compiler not to issue various
messages.
When you use the SUPPRESS attribute on a variable, the compiler does not issue a
message when the variable is uninitialized, unreferenced, or both. The following
syntax diagram applies to the SUPPRESS attribute on a variable:
SUPPRESS ( )
UNINIT
UNREF
NOPADDING
SUPPRESS ( )
UNREF
LAXNESTED
UNINIT
Specifying SUPPRESS(UNINIT) as an attribute in the declaration of a variable
causes the compiler not to flag any use of the variable where it might be
uninitialized.
UNREF
Specifying SUPPRESS(UNREF) as an attribute in the declaration of a variable
causes the compiler not to flag the variable as unused when the compilation
unit contains no references to that variable.
Specifying SUPPRESS(UNREF) on the PROCEDURE statement causes the
compiler not to flag the procedure as unused when the compilation unit
contains no references to that procedure.
NOPADDING
Specifying SUPPRESS(NOPADDING) on a level-1 structure name causes the
RULES(NOPADDING) compiler option to be ignored for that structure.
SUPPRESS(NOPADDING) has no effect if it is specified on a member within a
structure.
LAXNESTED
Specifying SUPPRESS(LAXNESTED) on a procedure causes the compiler not to
flag the procedure if executable statements follow it.
Data alignment
The computer holds information in multiples of units of 8 bits. Each 8-bit unit of
information is called a byte. The computer accesses bytes singly or as halfwords,
words, or doublewords. Byte locations in storage are consecutively numbered
starting with 0; each number is the address of the corresponding byte.
Your programs can execute faster if halfwords, words, and doublewords are
located in main storage on an integral boundary for that unit of information. That
is, the unit of information's address is a multiple of the number of bytes in the
unit, as can be seen in Table 37.
Table 37. Alignment on integral boundaries of halfwords, words, and doublewords
ADDRESSES IN A SECTION OF STORAGE
5000 5001 5002 5003 5004 5005 5006 5007
byte byte byte byte byte byte byte byte
halfword halfword halfword halfword
fullword fullword
doubleword
ALIGNED
UNALIGNED
Defaults are applied at element level. UNALIGNED is the default for bit data,
character data, graphic data, widechar data and numeric character data. ALIGNED
is the default for all other types of data.
Notes:
v Alignment and storage requirements for program control data can vary across
supported systems.
v Complex data requires twice as much storage as its real counterpart, but the
alignment requirements are the same.
Table 38. Alignment requirements
SIGNED
1 <= p <= 7
UNSIGNED
1 <= p <= 8
One byte 1
ORDINAL
SIGNED
1 <= p <= 7
UNSIGNED
1 <= p <= 8
SIGNED
8 <= p <= 15
UNSIGNED
9 <= p <= 16
Halfword 2
ORDINAL
SIGNED
8 <= p <= 15
UNSIGNED
9 <= p <= 16
BINARY FIXED(p,q)
SIGNED
16 <= p <= 31
UNSIGNED
17 <= p <= 32
Fullword
ORDINAL
BINARY FLOAT(p)
54 <= p Extended
16
floating-point
DECIMAL FLOAT(p)
17<=p
You can use language-specified defaults or the defaults that you define using the
DEFAULT statement for the following attributes:
v Attributes of explicitly declared names
v Attributes of implicitly (including contextually) declared names
v Attributes to be included in parameter descriptors
v Attributes of values returned from function procedures
You can use the DEFAULT statement to specify attribute defaults either to modify
the language-specified defaults or to develop a completely new set of defaults.
Language-specified defaults
When a variable has not been declared with any data attributes, it is given
arithmetic attributes by default.
If mode, scale, and base are not specified by a DECLARE or DEFAULT statement,
the DEFAULT compiler option determines the variable attributes as follows:
v If DEFAULT(IBM) is in effect, variables with names beginning with the letters I
through N are given the attributes REAL FIXED BINARY(15,0); all other
variables are given the attributes REAL FLOAT DECIMAL(6).
v If DEFAULT(ANS) is in effect, all variables are given the attributes REAL FIXED
BINARY(31,0).
dcl X entry;
call X( 1 );
The argument has the attributes REAL FIXED DECIMAL(1,0). This would be an
error if the procedure x declared its parameter with other attributes, as shown in
the following example:
X: proc( Y );
dcl Y fixed bin(15);
This potential problem can be easily avoided if the entry declaration specifies the
attributes for all of its parameters.
Table 39. Default arithmetic precisions
Attributes DEFAULT(IBM) DEFAULT(ANS)
DECIMAL FIXED (5,0) (10,0)
BINARY FIXED (15,0) (31,0)
DECIMAL FLOAT (6) (6)
BINARY FLOAT (21) (21)
DEFAULT statement
The DEFAULT statement specifies data-attribute defaults (when attribute sets are
not complete). Any attributes not applied by the DEFAULT statement for any
partially-complete explicit or contextual declarations, and for implicit declarations,
are supplied by language-specified defaults.
You can use a logical expression with the RANGE attribute and other attribute
keywords in the DEFAULT statement. These attributes are listed in Table 40 on
page 183.
The DEFAULT statement overrides all other attribute specifications, except that a
name declared with the ENTRY or FILE attribute, but none of the attributes that
would imply the VARIABLE attribute, will be given the implicit CONSTANT
attribute by PL/I before any DEFAULT statements are applied. Consequently, in
the following example, PL/I gives Xtrn the CONSTANT attribute and not the
STATIC attribute.
Sample: proc;
end;
Structure and union elements are given default attributes according to the name of
the element, not the qualified element name. The DEFAULT statement cannot be
used to create a structure or a union.
expression attribute-specification
DEFAULT
expression:
RANGE ( identifiers )
( attribute-expression ) ;
identifiers:
identifier
:identifier
*
Abbreviation: DFT
RANGE(identifier)
Specifies that the defaults apply to names that begin with the same letters as in
the identifier specified. For example, RANGE (ABC) applies to these names:
ABC
ABCD
ABCDE
This statement specifies default attributes REAL PICTURE '99999' for all
names.
DESCRIPTORS
Specifies that the attributes are included in any parameter descriptors in a
parameter descriptor list of an explicit entry declaration, if the following
conditions are true:
v The inclusion of any such attributes is not prohibited by the presence of
alternative attributes of the same class.
v At least one attribute is already present. (The DESCRIPTORS default
attributes are not applied to null descriptors).
Consider the following example:
DEFAULT DESCRIPTORS BINARY;
DCL X ENTRY (FIXED, FLOAT);
length and precision. So, for example, given DCL I; and DEFAULT RANGE(*)
VALUE( FIXED BIN(31) );, the variable I will receive the system default
attributes of FIXED BIN, but the precision 31 from the VALUE option (rather
than the system default of 15).
The size of AREA data, or length of BIT, CHARACTER, or GRAPHIC data can
be an expression or an integer, and can include the REFER option or can be
specified as an asterisk.
Consider the following example:
DEFAULT RANGE(A:C)
VALUE (FIXED DEC(10),
FLOAT DEC(14),
AREA(2000));
DECLARE B FIXED DECIMAL,
C FLOAT DECIMAL,
A AREA;
These statements are equivalent to the following declaration:
DECLARE B FIXED DECIMAL(10),
C FLOAT DECIMAL(14),
A AREA(2000);
However, the following statement specifies both the FIXED BINARY attribute
as a default and the precision:
DFT RANGE(*) FIXED BINARY VALUE(FIXED BINARY(31));
attribute-expression
Is an expression that uses the and, or, and not operators with operands that are
attributes. If the expression is true, the specified attributes are applied. For
example, if a precision is not specified, DEFAULT(FIXED & BIN) PREC(31) sets
the precision of all FIXED BIN variables as 31.
All the attributes are individual keywords, except the RANGE attribute. The
RANGE attribute must be specified with *, identifier, or identifier : identifier, as
in a simple DEFAULT statement.
You can use the attributes that are listed in the following table in
attribute-expression in DEFAULT.
There can be more than one DEFAULT statement within a block. The scope of a
DEFAULT statement is the block in which it occurs, and all blocks within that
block which neither include another DEFAULT statement with the same range, nor
are contained in a block having a DEFAULT statement with the same range.
Arrays
An array is an n-dimensional collection of elements that have identical attributes.
Only the array itself is given a name. An individual item of an array is referred to
by giving its position within the array. You indicate that a name is an array variable
by providing the dimension attribute.
Unless specified with REFER, every dimension of every array must have at least
one element. When the bounds of an array are specified with REFER, the array can
be defined to have zero elements if the following conditions are true:
v The array is never accessed or assigned.
v The array has only one dimension (excluding any inherited dimensions).
v The lower bound of that dimension must be 1.
v All of the elements in the containing structure must be either UNALIGNED or
NONVARYING BIT.
So, for example, given the following code, it is valid to allocate the array a when
n1 is zero if ab3, abc1, and abc2 are neither accessed nor assigned.
dcl n1 fixed bin(31);
dcl p pointer;
dcl
1 a based(p),
2 ab1 fixed bin(31),
2 ab2 fixed bin(31),
2 ab3( n1 refer(ab2) ),
3 abc1 char(40) var,
3 abc2 char(40) var,
2 ab4 char(40) var;
DIMENSION attribute
The DIMENSION attribute specifies the number of dimensions of an array and
upper and lower bounds of each.
Bounds that are nonrestricted expressions are evaluated and converted to FIXED
BINARY (with a precision corresponding to the CMPAT compiler option) when
storage is allocated for the array.
The extent of a dimension is the number of integers between, and including, the
lower and upper bounds for a dimension.
( bound )
DIMENSION
bound:
upper-bound
lower-bound : *
*:
lower-bound:
expression
REFER(variable)
upper-bound:
expression
REFER(variable)
Abbreviation: DIM
DIMACROSS attribute
The DIMACROSS attribute specifies a DIMENSION attribute on a structure, but
one which will be removed from the structure and propagated to its members.
The DIMACROSS attribute has the same syntax as the DIMENSION attribute
except that the DIMACROSS keyword is, of course, not optional.
Declaration 1 Declaration 2
Dcl Dcl
1 a(10) dimacross, 1 a,
2 b, 2 b(10),
2 c, 2 c(10),
3 d, 3 d,
3 e; 3 e;
Examples of arrays
These examples help you understand declarations of arrays and array dimensions.
In the first example, the bounds are 4 and 11; in the second they are -4 and 3. The
extents are the same for each, 8 integers from the lower bound through the upper
bound.
Subscripts
A subscript is an element expression that specifies a position within a dimension of
an array. If the subscript is an asterisk, it specifies all of the elements of the
dimension.
The bounds of an array determine the way elements of the array can be referred
to. For example, when the following data items:
20 5 10 30 630 150 310 70
are assigned to the array List, as declared above, the different elements are
referred to as follows:
Reference Element
LIST (1) 20
LIST (2) 5
LIST (3) 10
LIST (4) 30
LIST (5) 630
LIST (6) 150
LIST (7) 310
LIST (8) 70
The same data can be assigned to List_A and List_B declared previously. In this
case it is referenced as follows:
Any expression that yields a valid arithmetic value can be used for a subscript. If
necessary, the value is converted to FIXED BINARY (with a precision
corresponding to the CMPAT compiler option). Thus, TABLE(I,J*K) can be used to
refer to the different elements of TABLE by varying the values of I, J, and K.
The asterisk specifies that the entire extent is used. For example, TABLE(*,1) refers
to all of the elements in the first column of TABLE. It specifies the cross section
consisting of TABLE(1,1), TABLE(2,1), TABLE(3,1), and TABLE(4,1). The subscripted
name TABLE(2,*) refers to all of the data items in the second row of TABLE.
TABLE(*,*) refers to the entire array, as does TABLE.
A reference to a cross section of an array can refer to two or more elements that
are not adjacent in storage. The storage represented by such a cross section is
known as nonconnected storage. The rule is as follows: if a nonasterisk bound
appears to the right of the leftmost asterisk bound, the array cross section is in
nonconnected storage. Thus, A(4,*,*) is in connected storage; A(*,2,*) is not.
Related information:
CONNECTED and NONCONNECTED attributes on page 282
The CONNECTED attribute specifies that a parameter is a reference to connected
storage only. The NONCONNECTED attribute allows a parameter to occupy
noncontiguous as well as contiguous storage.
Structures
A structure is a collection of member elements that can be structures, unions,
elementary variables, and arrays.
The structure variable is a name that can be used to refer to the entire aggregate of
data. Unlike an array, however, each member of a structure also has a name, and
the attributes of each member can differ. An asterisk can be used as the name of a
structure or a member when it will not be referred to. For example, reserved or
filler items can be named with an asterisk.
A structure has different levels. The name at level-1 is called a major structure.
Names at deeper levels can be minor structures or unions. Names at the deepest
level are called elementary names, which can represent an elementary variable or an
array variable.
delimiter must separate the level-number and its associated name. For example,
the items of a payroll record could be declared as follows:
declare 1 Payroll, /* major structure name */
2 Name, /* minor structure name */
3 Last char(20), /* elementary name */
3 First char(15),
2 Hours,
3 Regular fixed dec(5,2),
3 Overtime fixed dec(5,2),
2 Rate,
3 Regular fixed dec(3,2),
3 Overtime fixed dec(3,2);
In the example, Payroll is the major structure and all other names are members of
this structure. Name, Hours, and Rate are minor structures, and all other members
are elementary variables. You can refer to the entire structure by the name Payroll,
or to portions of the structure by the minor structure names. You can refer to a
member by referring to the member name.
The level-numbers you choose for successively deeper levels need not be
consecutive. A minor structure at level n contains all the names with level-numbers
greater than n that lie between that minor structure name and the next name with
a level-number less than or equal to n.
For example, the following declaration results in exactly the same structure as the
declaration in the previous example.
Declare 1 Payroll,
4 Name,
5 Last char(20),
5 First char(15),
3 Hours,
6 Regular fixed dec(5,2),
5 Overtime fixed dec(5,2),
2 Rate,
9 Regular fixed dec(3,2),
9 Overtime fixed dec(3,2);
Unions
A union is a collection of member elements that overlay each other, occupying the
same storage. The members can be structures, unions, elementary variables, and
arrays. They need not have identical attributes.
The entire union is given a name that can be used to refer to the entire aggregate
of data. Like a structure, each element of a union also has a name. An asterisk can
be used as the name of a union or a member, when it will not be referred to. For
example, reserved or filler items can be named asterisk.
Like a structure, a union can be at any level including level 1. All elements of a
union at the next deeper level are members of the union and occupy the same
storage. The storage occupied by the union is equal to the storage required by the
largest member. Normally, only one member is used at any time and the
programmer determines which member is used.
Unions can be used to declare variant records that would typically contain a
common part, a selector part, and variant parts. For example, records in a client
file can be declared as follows:
Declare 1 Client,
2 Number pic 999999,
2 Type bit(1),
2 * bit(7),
2 Name union,
3 Individual,
5 Last_Name char(20),
5 First_Name union,
7 First char(15),
7 Initial char(1),
3 Company char(35),
2 * char(0);
In this example, Client is a major structure. The structure Individual, and the
element Company are members of the union Name. One of these members is active
depending on Type. The structure Individual contains the union First_name and
the element Last_name. First_name union has First and Initial as its members,
both of which are active. The example also shows the use of asterisk as a name.
The description of a union is terminated by the semicolon that terminates a
DECLARE statement or by a comma, followed by the declaration of another item.
UNION attribute
The UNION attribute allows you to specify that a variable is a union and that its
members are those that follow it and are at the next logically higher level. CELL is
accepted as a synonym for UNION.
UNION
Related information:
Assignments to UNIONs on page 192
Assignments to UNIONs or to structures that contain UNIONS are possible.
A qualified reference is a member name that is qualified with one or more names of
parent members connected by periods. (See the qualified reference syntax in
Chapter 3, Expressions and references, on page 51.) Blanks can appear
surrounding the period.
The qualification must follow the order of levels. That is, the name at the highest
level must appear first, with the name at the deepest level appearing last.
While the level-1 structure or union name must be unique within the block scope,
member names need not be unique as long as they do not appear at same logical
level within their most immediate parent. A qualified name must be used only so
far as necessary to make a reference of the same structure unique within the block
in which it appears. In the following example, the value of x.y (19) is displayed,
not the value (17).
dcl Y fixed init(17);
begin;
dcl
1 X,
2 Y fixed init(19);
display( Y );
end;
A reference is always taken to apply to the declared name in the innermost block
containing the reference.
In the following example, D has been declared twice. A reference to A.D refers to
the second D, because A.D is a complete qualification of only the second D. The first
D is referred to as A.C.D.
declare 1 A,
2 B,
2 C,
3 D,
2 D;
In the following example, a reference to A refers to the first A, A.A to the second A,
and A.A.A to the third A.
declare 1 A,
2 A,
3 A;
Assignments to UNIONs
Assignments to UNIONs or to structures that contain UNIONS are possible.
Structures that contain UNIONs are not supported in the following assignments:
v Multiple assignments
v Compound assignments
v BY NAME assignments
v BY DIMACROSS assignments
In the generated code for the assignments of the UNIONs, the assignment is
performed by a simple byte copy of the whole UNION.
LIKE attribute
The LIKE attribute specifies that the name that is declared has an organization that
is logically the same as the referenced structure or union, the object of the LIKE
attribute.
The object variable's member names and their attributes, including the dimension
attribute, are effectively copied and become members of the name being declared.
If necessary, the level-numbers of the copied members are automatically adjusted.
The object variable name and its attributes, including the dimension attribute, are
ignored.
LIKE object-variable
object-variable
Can be a major structure, a minor structure, or a union. It must be known in
the block containing the LIKE attribute specification. It can be qualified but
must not be subscripted. The object or its members can also have the LIKE
attribute if they were declared previously.
The objects in all LIKE attributes are associated with declared names before
any LIKE attributes are expanded.
dcl
1 X,
2 B bit(4),
2 C bit(4);
Notice that the dimension (DIM(10)), ALIGNED, and STATIC attributes are not
copied as part of the LIKE expansion.
The LIKE attribute is expanded before the defaults are applied and before the
ALIGNED and UNALIGNED attributes are applied to the contained elements of
the LIKE object variable. However, the LIKE attribute is expanded only after all
LIKE attributes have been resolved.
Examples
5 E1,
5 E2,
3 F;
declare 1 B(10) union,
2 C, 3 G, 3 H,
2 D;
begin;
declare 1 C like B;
declare 1 D(2),
5 BB like A.C;
end;
dcl 1 D(2),
5 BB,
6 E(3) union, /* DIM(3) and UNION copied. */
7 E1, /* Note adjusted level-numbers. */
7 E2,
6 F;
The following declarations are valid, but only because B is declared before C and E
is declared before F:
dcl 1 a, 2 a1 fixed bin;
dcl 1 b, 2 b1 like a;
dcl 1 c, 2 c1 like b;
The following example is valid, but only because the LIKE references are expanded
after they are all resolved, otherwise the reference aa3_array would be ambiguous:
dcl 1 aa(30)
,5 aa1 char( 5)
,5 aa2 fixed bin(31)
,5 aa3_array(30)
,7 aa3_1 fixed dec(15,2)
,7 aa3_2 fixed dec(15,2)
,7 aa3_3 fixed dec(11,4)
,7 aa3_4 fixed dec(7,3)
;
The following example is invalid because C.E has the LIKE attribute and because B
is declared after A. If the order of the declarations for A and B is reversed, the code
is valid.
declare 1 A like C,
1 B,
2 C,
3 D,
3 E like X,
2 F,
1 X,
2 Y,
2 Z;
The following example is invalid because G.C cannot be resolved. G.C is not
resolved because the expansion of the LIKE for G occurs after the attempt to
resolve the LIKE attribute for A:
declare 1 B,
2 C,
3 D,
3 E,
2 F,
1 G like B;
1 A like G.C,
INDFOR attribute
The INDFOR attribute specifies that the name that is declared has an organization
that is logically the same as the referenced structure or union, the object of the
INDFOR attribute. The INDFOR attribute is similar to the LIKE attribute.
The member names and their attributes, excluding the dimension attribute, of the
object variable are effectively converted to FIXED BIN(15) and become members of
the name that is declared. This differs from the LIKE attribute, which copies the
attributes.
INDFOR object-variable
object-variable
Can be a major structure, a minor structure, or a union. It must be known in
the block that has the INDFOR attribute. It can be qualified but must not be
subscripted. The object or its members can also have the INDFOR attribute if
they were declared previously.
The objects in all INDFOR attributes are associated with declared names before
any INDFOR attributes are expanded.
The INDFOR attribute is expanded before the defaults are applied and before the
ALIGNED and UNALIGNED attributes are applied to the contained elements of
the INDFOR object variable. However, the INDFOR attribute is expanded only
after all INDFOR attributes have been resolved.
Example
This example illustrates the difference between the INDFOR attribute and the LIKE
attribute.
Related information:
LIKE attribute on page 193
The LIKE attribute specifies that the name that is declared has an organization that
is logically the same as the referenced structure or union, the object of the LIKE
attribute.
NOINIT attribute
The NOINIT attribute specifies that any INITIAL attributes are to be ignored.
While the NOINIT attribute might be most useful on level-1 structures, it can be
specified on any substructure as well.
The NOINIT attribute is particularly useful with the LIKE attribute because when a
new variable is declared LIKE an old variable but with the NOINIT attribute, the
new variable will inherit all the substructuring from the old variable, but none of
its INITIAL values.
NULLINIT attribute
The NULLINIT attribute specifies that any variable that does not have an INITIAL
attribute is given an INITIAL attribute according to its data attributes.
v INIT( (*) 0 ) if it is FIXED or FLOAT
v INIT( (*) '') if it is PICTURE, CHAR, BIT, GRAPHIC or WIDECHAR
v INIT( (*) SYSNULL() ) if it is POINTER or OFFSET
v INIT( (*) NULLENTRY() ) if it is ENTRY
Variables with attributes other than those in the previous list are unchanged by the
NULLINIT attribute.
The NULLINIT attribute can be specified only on level-1 names, and it conflicts
with the NOINIT and INITIAL attributes.
XML-related attributes
XML-related attributes specify the use of XML attributes and control output that is
generated by the XMLCHAR built-in function.
XMLCONTENT attribute
The XMLCONTENT attribute specifies that when a variable is included in the text
that is generated by the XMLCHAR built-in function, it is presented as tagless text.
Related information:
XMLCHAR on page 792
The XMLCHAR built-in function dumps data from a structure as XML into a
buffer. It returns a size_t 1 value that indicates the number of bytes written to the
buffer. If the buffer is too small, the structure data is truncated and the number of
bytes needed for the buffer to contain the structure is returned.
XMLATTR attribute
The XMLATTR attribute indicates that the field is presented as an attribute of its
containing structure in the XML output that is generated by XMLCHAR.
Note: The compiler ignores XMLATTR unless a structure that contains fields using
XMLATTR is passed to XMLCHAR.
v Arrays
v Structures or unions
v Unnamed structure elements
v A structure element that is used previously with the same parent but without
the XMLATTR attribute
XMLOMIT attribute
The XMLOMIT attribute indicates that fields of certain data items must be omitted
from the XML output that is generated by XMLCHAR if the field is a string equal
to the null string (' ') or a number equal to 0.
Note: The compiler ignores XMLOMIT unless a structure that contains fields using
XMLOMIT is passed to XMLCHAR.
Output:
<order>
<orderNr>1729</orderNr>
<customer id=2917 name=jakob firstname=michael>
<partno>1367</partno>
</customer>
</order>
JSON-related attributes
JSON-related attributes specify the use of variable attributes in JSON functions and
control output that is generated by JSON functions.
JSONNAME attribute
The JSONNAME attribute specifies the name that is used or expected for a
variable in jsonPut or jsonGet functions. In particular, using the JSONNAME
attribute, you can specify a name that does not conform to PL/I name rules.
For example, if you want to specify a name with a hyphen, you can use the
following attribute for the variable:
JSONNAME('comment-text')
JSONOMIT attribute
The JSONOMIT attribute indicates that fields of certain data items must be omitted
from output that is generated by JSON functions if the field is a string equal to the
null string (' ') or a number equal to 0.
For example, if a structure is used to hold meteorological data for each month of
the year for the twentieth and the twenty-first centuries, it might be declared as
follows:
Declare 1 Year(1901:2100),
3 Month(12),
5 Temperature,
7 High decimal fixed(4,1),
7 Low decimal fixed(4,1),
5 Wind_velocity,
7 High decimal fixed(3),
7 Low decimal fixed(3),
5 Precipitation,
7 Total decimal fixed(3,1),
7 Average decimal fixed(3,1),
3 * char(0);
You can refer to the weather data for July 1991 by specifying Year(1991,7). You
can refer to portions of this data by Temperature(1991,7) and
Wind_Velocity(1991,7). Precipitation.Total(1991,7) and Total(1991,7) both
refer to the total precipitation during July 1991.
The need for subscripted qualified references becomes apparent when an array of
structures or unions contains members that are arrays. In the following example,
both A and B are structures:
declare 1 A (2,2),
(2 B (2),
3 C,
3 D,
2 E) fixed bin;
To refer to a data item, it might be necessary to use as many as three names and
three subscripts. See the following example:
For example, you can have structure references in assignments, I/O statements,
and so on.
But references to unions or structures that contain unions are limited to the
following contexts:
v Parameters and arguments
v Storage control and those built-in functions and subroutines that allow
structures.
2 E,
3 F char(2),
3 G fixed bin(31),
2 H char(8);
Three bytes of padding are added between A and B. Two bytes are added between
A and E. No padding bytes are between A and H. It means that C starts with the
fourth byte of H and that F starts with the third byte of H.
You must not use the ADDR, BITLOCATION, or LOCATION built-in functions
against any UNION like the one in the previous example. You should use these
functions only when the first storage locations of the members of a union are the
same.
To ensure that the first storage location of each of the members of a union is the
same, make sure that the first member of each has the same alignment requirement
and it is the same as the highest alignment of any of its members (or members of
its member).
For any major or minor structure, the length, alignment requirement, and position
relative to an 8-byte boundary depend on the lengths, alignment requirements, and
relative positions of its members. The process of determining these requirements
for each level and for the complete structure is known as structure mapping.
You can use structure mapping for determining the record length required for a
structure when record-oriented input/output is used, and determining the amount
of padding or rearrangement required for correct alignment of a structure for
locate-mode input/output.
The structure mapping process minimizes the amount of unused storage (padding)
between members of the structure. It completes the entire process before the
structure is allocated, according (in effect) to the rules discussed in the following
paragraphs.
Structure mapping is not a physical process. Terms such as shifted and offset are
used purely for ease of discussion, and do not imply actual movement in storage.
When the structure is allocated, the relative locations are already known as a result
of the mapping process.
These rules are described below, and an example shows an application of the rules
in detail. It is necessary to understand the difference between the logical level and
the level-number of structure elements. The logical levels are immediately apparent
if the structure declaration is written with consistent level-numbers or suitable
indentation (as in the detailed example given after the rules). In any case, you can
determine the logical level of each item in the structure by applying the following
rule to each item in turn, starting at the beginning of the structure declaration:
200 Enterprise PL/I for z/OS Language Reference
Structure and union mapping
Note: The logical level of a given item is always one unit deeper than that of its
immediate containing structure.
In the following example, the lower line shows the logical level for each item in
the declaration.
dcl 1 A, 4 B, 5 C, 5 D, 3 E, 8 F, 7 G;
1 2 3 3 2 3 3
After this process has been completed, any padding between the two elements has
been minimized and does not change throughout the rest of the operation. The
pair is now a unit of fixed length and alignment requirement; its length is the sum
of the two lengths plus padding, and its alignment requirement is the higher of the
two alignment requirements (if they differ).
If a structure has the UNALIGNED attribute and it contains an element that cannot
be unaligned, UNALIGNED is ignored for that element. The element is aligned
and an error message is produced. For example, in a program with the following
declaration, C is given the attribute ALIGNED because the inherited attribute
UNALIGNED conflicts with AREA.
declare 1 A unaligned,
2 B,
2 C area(100);
The minor structure at the deepest logical level is G, so this is mapped first. Then E
is mapped, followed by N, S, C, and M, in that order.
For each minor structure, a table in Figure 10 on page 204 shows the steps in the
process, and a diagram in Figure 11 on page 205 shows a visual interpretation of
the process. Finally, the major structure A is mapped as shown in Figure 17 on page
208
202 Enterprise PL/I for z/OS Language Reference
Structure mapping example
207. At the end of the example, the structure map for A is set out in the form of a
table (Figure 18 on page 209) showing the offset of each member from the start of
A.
ALLOCATE statement
The ALLOCATE statement allocates storage for variables.
For details about the ALLOCATE statement, see ALLOCATE statement for
controlled variables on page 257 and ALLOCATE statement for based variables
on page 267 in Chapter 9, Storage control, on page 253.
ASSERT statement
The ASSERT statement asserts whether a condition is true or false or whether a
statement should not be executed.
TEXT ( display-expression )
TRUE(test-expression)
Asserts that test-expression is true when one or more bits in test-expression have
the value 1B.
FALSE(test-expression)
Asserts that test-expression is false when all the bits in test-expression have the
value 0B.
TEXT(display-expression)
Passes the display-expression to the assertion routine if the assert fails.
UNREACHABLE
Asserts that the statement cannot be reached, because it is bypassed by a
proceeding statement, such as a GOTO, RETURN, or SIGNAL statement.
display-expression
A scalar CHARACTER expression.
test-expression
A computational scalar expression that is to be, if necessary, converted to BIT.
If the assertion fails, the compiled code calls routine IBMPASU for ASSERT
UNREACHABLE and IBMPAST for all the other ASSERT statements. These
routines must use the OPTLINK linkage, and the compiled code calls these
routines with the following BYVALUE parameters:
v A POINTER holding the address of a buffer that contains the PACKAGENAME
value as a varying character string
v A POINTER holding the address of a buffer that contains the PROCNAME value
as a varying character string
v A FIXED BIN(31) holding the SOURCELINE value
v A POINTER holding the ADDRDATA of the TEXT value. If the TEXT clause is
omitted, the value passed is SYSNULL.
v A FIXED BIN(31) holding the LENGTH of the TEXT value. If the TEXT clause is
omitted, the value passed is 0.
Example
The following example shows the usage of the ASSERT statement. You must code
the routines that are used in this example.
asserts: package;
n = 1;
assert true( n> 0 );
assert true( n= 2 ) text(n not equal to 2);
assert unreachable;
end;
ibmpasu:
proc( packagename_ptr, procname_ptr, assert_sourceline,
text_addr, text_length )
ext( _IBMPASU)
options( byvalue linkage(optlink) );
ibmpast:
proc( packagename_ptr, procname_ptr, assert_sourceline,
text_addr, text_length )
ext( _IBMPAST)
options( byvalue linkage(optlink) );
The GET and PUT statements with the STRING option can also be used for
internal data movement. Additionally, the PUT statement can specify computations
to be done. See Chapter 12, Stream-oriented data transmission, on page 321.
Because the attributes of the target variable or pseudovariable can differ from the
attributes of the source (a variable, a constant, or the result of an expression), the
assignment statement might require conversions.
Related information:
Chapter 4, Data conversion, on page 77
This chapter discusses data conversions for computational data. PL/I converts data
when a data item with a set of attributes is assigned to another data item with a
different set of attributes.
Assignment statements
This topic describes the syntax and parameters for assignment statements.
Syntax
reference = expression ;
,BY NAME
Parameters
reference
Specifies the target to be given the assignment.
expression
Specifies an expression that is evaluated and possibly converted.
BY NAME
For structure assignments, the BY NAME option specifies that the assignment
follows the steps outlined under Structure assignments using the BY NAME
option on page 218.
Syntax
Parameters
reference
Specifies the target to be given the assignment.
exp1
Specifies an expression that is evaluated and possibly converted.
BY DIMACROSS
For structure assignments, the BY DIMACROSS option specifies that the
assignment follows the steps outlined under Structure assignments using the
BY DIMACROSS option on page 218.
exp2
Specifies an expression that is used as the index appended to the associated
DIMACROSS structure elements.
Syntax
Parameters
reference
Specifies the target to be given the assignment
compound assignment operator
Specifies the operator that is applied to the reference and the evaluated
For information about area assignment, see Area data and attribute on page 271.
Table 41. Compound assignment operators
Compound Meaning
assignment operator
+= Evaluate expression, add and assign
-= Evaluate expression, subtract and assign
*= Evaluate expression, multiply and assign
/= Evaluate expression, divide and assign
|= Evaluate expression, or and assign
&= Evaluate expression, and and assign
{= Evaluate expression, concatenate and assign
**= Evaluate expression, exponentiate and assign
= or <> Evaluate expression, exclusive-or and assign
The operator is applied to the target and source first, and then what results is
assigned to the target.
Target variables
The target variables can be element, array, structure variables; or pseudovariables.
Array targets
For array assignments, each target variable must be an array of scalars or
structures.
The source must be a scalar or an expression with the same number of dimensions
and the same bounds for all dimensions as for the target.
Union targets
Union assignments are not allowed.
Structure targets
In BY NAME structure assignments, each target variable must be a structure, and
the right-hand side must be a structure reference. In structure assignments not
using BY NAME or BY DIMACROSS, each target variable must be a structure, and
the right-hand side must be a scalar or a structure expression with the same
structuring as the target structure.
v The structures must have the same minor structuring and the same number of
contained elements and arrays.
v The positioning of the elements and arrays within the structure (and within the
minor structures, if any) must be the same.
v Arrays in corresponding positions must have identical bounds.
Element assignments
Element assignments are performed as follows:
1. These are evaluated first:
v Subscripts
v POSITION attribute expressions
v Locator qualifications of the target variables
v The second and third arguments of SUBSTR pseudovariable references
2. Then, the expression on the right-hand side is evaluated.
3. For each target variable (in left to right order), the expression is converted to
the characteristics of the target variable according to the rules for data
conversion. The converted value is then assigned to the target variable.
Aggregate assignments
Aggregate assignments (array and structure assignments) are expanded into a
series of element assignments as follows:
1. The label prefix of the original statement is applied to a null statement
preceding the other generated statements.
2. Array and structure assignments, when there are more than one, are done
iteratively.
3. Any assignment statement can be generated by a previous array or structure
assignment. The first target variable in an aggregate assignment is known as
the master variable. (It can also be the first argument of a pseudovariable). If
the master variable is an array, an array expansion is performed; otherwise, a
structure expansion is performed.
4. If an aggregate assignment meets either of the following conditions, it can be
done as a whole instead of being expanded into a series of element
assignments.
v The arrays are not interleaved.
v The structures are contiguous and have the same format.
Array assignments:
In array assignments, all array operands must have the same number of
dimensions and identical bounds. The array assignment is expanded into a loop as
follows:
do J1 = lbound(Master-variable,1) to
hbound(Master-variable,1);
do J2 = lbound(Master-variable,2) to
hbound(Master-variable,2);
.
.
.
do Jn = lbound(Master-variable,N) to
hbound(Master-variable,N);
end;
In this expansion, n is the number of dimensions of the master variable that are to
participate in the assignment. In the generated assignment statement, all array
operands are fully subscripted, using (from left to right) the dummy variables j1 to
jn. If an array operand appears with no subscripts, it has only the subscripts j1 to
jn. If a cross-section notation is used, the asterisks are replaced by j1 to jn. If the
original assignment statement has a condition prefix, the generated assignment
statement is given this condition prefix.
v None of the operands can be arrays, although they can be structures that contain
arrays.
v All of the structure operands must have the same number, k, of immediately
contained items.
Multiple assignments
Assignments can be made to multiple variables in a single assignment statement
The value of B + C is assigned to both A and X. In general, it has the same effect as
the following statements:
Temporary = B + C;
A = Temporary;
X = Temporary;
The source in the assignment statement must be a scalar or an array of scalars, and
if the source is an array, all the targets must also be arrays. If the source is a
constant, it is assigned to each of the targets from left to right. If the source is not a
constant, it is assigned to a temporary variable, which is then assigned to each of
the targets from left to right.
Examples
This section provides examples of assignment statements that are used for internal
data movement, assignments of expression values, and assignments of structures.
Example 1
x = 0;
do jx = lboundacross( xa ) to hboundacross( xa );
x = x + xa, by dimacross( jx );
end;
Example 2
This code exchanges the entries in the first and seventeenth columns of xa:
dcl
1 x,
2 a fixed bin(31),
2 b fixed bin(31),
2 c fixed bin(31),
2 d fixed bin(31);
dcl y like x;
x = xa, by dimacross( 1 );
y = xa, by dimacross( 17 );
xa = y, by dimacross( 1 );
xa = x, by dimacross( 17 );
ATTACH statement
The ATTACH statement attaches or creates a thread.
For details about the ATTACH statement, see ATTACH statement on page 404 in
the section Chapter 17, Multithreading facility, on page 403.
BEGIN statement
The BEGIN statement and a corresponding END statement delimit a begin-block.
For details about the BEGIN statement, see BEGIN statement on page 118 in
Chapter 5, Program organization, on page 91.
CALL statement
The CALL statement invokes a subroutine.
For details about the CALL statement, see CALL statement on page 133.
For details about the CANCEL THREAD statement, see Canceling a thread on
page 406.
CLOSE statement
The CLOSE statement dissociates an opened file from its data set.
For details about the CLOSE statement, see CLOSE statement on page 309 in
Chapter 10, Input and output, on page 297.
DECLARE statement
The DECLARE statement specifies some or all of the attributes of a name.
For details about the DECLARE statement, see DECLARE statement on page
160.
For details about the DEFINE ALIAS statement, see DEFINE ALIAS statement
on page 145 in Chapter 6, Type definitions, on page 145.
For details about the DEFINE ORDINAL statement, see DEFINE ORDINAL
statement on page 146 in Chapter 6, Type definitions, on page 145.
For details about the DEFINE STRUCTURE statement, see Defining typed
structures and unions on page 148 in Chapter 6, Type definitions, on page 145.
DEFAULT statement
The DEFAULT statement specifies data-attribute defaults (when attribute sets are
not complete).
For details about the DEFAULT statement, see DEFAULT statement on page 179.
DELAY statement
The DELAY statement suspends the execution of the next statement in the
application program for the specified period of time.
DELAY (expression) ;
expression
Specifies an expression that is evaluated and converted to FIXED
BINARY(31,0). Execution is suspended for the number of milliseconds
specified.
The maximum wait time is 23 hours and 59 minutes.
DELETE statement
The DELETE statement deletes a record from an UPDATE file.
For details about the DELETE statement, see DELETE statement on page 314 in
Chapter 11, Record-oriented data transmission, on page 311.
DETACH statement
The DETACH statement frees the system resources associated with a thread that
was attached with the THREAD option.
For details about the DETACH statement, see Detaching a thread on page 406 in
Chapter 17, Multithreading facility, on page 403.
DISPLAY statement
The DISPLAY statement displays a message on the user's screen and optionally
requests the user to enter a response to the message.
DISPLAY (expression) ;
REPLY (char-ref)
expression
Is converted, where necessary, to a character string. This character string is
displayed. It can contain mixed character data. If the expression has the
GRAPHIC attribute, it is not converted.
REPLY (char-ref)
Specifies a character reference that receives the user-entered response. The
response can contain CHARACTER, GRAPHIC, or mixed data.
The REPLY option suspends program execution until the user enters a response.
Example
DO statement
The DO statement and its corresponding END statement, delimit a group of
statements collectively called a do-group.
Type 1
The type 1 do-group specifies that the statements in the group are executed. It
does not provide for the repetitive execution of the statements within the group.
Type 1
DO ;
expn
An abbreviation for expression n.
Types 2 and 3
Types 2 and 3 provide for the repetitive execution of the statements within the
do-group.
Type 2
DO WHILE ( exp4 ) ;
UNTIL ( exp5 )
UNTIL ( exp5 )
WHILE ( exp4 )
Type 3
DO reference = specification
exp1
TO exp2 WHILE ( exp4 )
BY exp3 UNTIL ( exp5 )
BY exp3 UNTIL ( exp5 )
TO exp2 WHILE ( exp4 )
UPTHRU exp2
DOWNTHRU exp2
REPEAT exp6
expn
An abbreviation for expression n.
WHILE (exp4)
Specifies that before each repetition of the do-group, exp4 is evaluated and, if
necessary, converted to a bit string. If any bit in the resulting string is 1, the
do-group is executed. If all bits are 0, or if the string is null, execution of the
Type 2 do-group is terminated. For Type 3, only the execution associated with
the specification containing the WHILE option is terminated. Execution for the
next specification, if one exists, then begins.
UNTIL (exp5)
Specifies that after each repetition of do-group, exp5 is evaluated, and, if
necessary, converted to a bit string. If all the bits in the resulting string are 0,
or if the string is null, the next iteration of the do-group is executed. If any bit
is 1, execution of the Type 2 do-group is terminated. For Type 3, only the
execution associated with the specification containing the UNTIL option is
terminated. Execution for the next specification, if one exists, then begins.
reference
The only pseudovariables that can be used as references are SUBSTR, REAL,
IMAG and UNSPEC. All data types are allowed.
The generation g of a reference is established once at the beginning of the
do-group, immediately before the initial value expression exp1 is evaluated. If
In Type 3 do-groups, you should not rely on the order in which exp1, exp2, and
exp3 are evaluated. Consequently, it is best if none of these expressions invoke
functions that set values used in the other expressions.
Control can transfer into a do-group from outside the do-group only if the
do-group is delimited by the DO statement in Type 1. Consequently, Type 2 and 3
do-groups cannot contain ENTRY statements. Control can also return to a
do-group from a procedure or ON-unit invoked from within that do-group.
The following sections give more information about using Type 2 and Type 3 DO
groups. Examples of DO groups begin in Examples of basic repetitions on page
231.
If the UNTIL option is omitted, the IF statement at label Label2 in the expansion is
replaced by the statement GO TO Label.
f. If the TO, BY, UPTHRU, DOWNTHRU, and REPEAT options are all absent,
leave the do-group.
9. Go to 2 on page 227.
When execution of the last specification terminates, control passes to the statement
following the do-group.
If the Type 3 DO specification includes the TO and BY options, the action of the
do-group is defined by the following:
Label: do Variable=
Exp1
to Exp2
by Exp3
while (Exp4)
until(Exp5);
statement-1
.
.
.
statement-m
Label1: end;
Next: statement
If the specification includes the REPEAT option, the action of the do-group is
defined by the following:
Label: do Variable=
Exp1
repeat Exp6
while (Exp4)
until(Exp5);
statement-1
.
.
.
statement-m
Label1: end;
Next: statement
Type 4
Type 4 specifies loops. A loop specifies a sequence of instructions that is executed
iteratively.
LOOP
Specifies infinite iteration. FOREVER is a synonym of LOOP.
Example
dcl Payroll file;
dcl 1 Payrec,
2 Type char,
2 Subtype char,
2 * char(100);
Readfile:
do loop;
If Payrec.type = E
then leave; /* like goto After_ReadFile */
If Payrec.type = 1 then
do;
/* process first part of record */
If Payrec.subtype = S
then iterate Readfile; /* like goto End_ReadFile */
End_ReadFile:
end;
After_ReadFile:;
In the following example, the do-group is executed ten times, while the value of
the reference I progresses from 1 through 10.
do I = 1 to 10;
.
.
.
end;
The following DO statement executes the do-group three timesonce for each
assignment of Tom, Dick, and Harry to Name.
do Name = Tom, Dick, Harry;
The following statement specifies that the do-group executes thirteen timesten
times with the value of I equal to 1 through 10, and three times with the value of
I equal to 13 through 15:
do I = 1 to 10, 13 to 15;
In the following example, the first ten elements of A are set to 1 through 10 in
sequence:
do I = 1 to 10;
A(I) = I;
end;
Example 1
The following example specifies that the do-group is executed five times, with the
value of I equal to 2, 4, 6, 8, and 10:
do I = 2 to 10 by 2;
Example 2
If negative increments of the reference are required, the BY option must be used.
For example, the following statement is executed with I equal to 10, 8, 6, 4, 2, 0,
and -2:
do I = 10 to -2 by -2;
Example 3
In the following example, if A=B, when the DO statement is first encountered, the
do-group is not executed at all.
do while(A=B) until(X=10);
In the following example, the do-group is executed at least once, with I equal to 1:
do I=1 to 10 until(Y=1);
The following statement specifies that the do-group executes ten times while C(I)
is less than zero, and then (provided that A is equal to B) once more:
do I = 1 to 10 while (C(I)<0),
11 while (A = B);
In the following example, the do-group executes 5 times and at the end of the loop
i has the value 5:
do i = 1 upthru 5;
.
.
.
end;
When the UPTHRU option is used, the reference is compared to the terminating
value before being updated; this can be very useful when there is no value after
the terminating value. For instance, the FIXEDOVERFLOW condition would not be
raised by the following loop:
do i = 2147483641 upthru 2147483647;
.
.
.
end;
UPTHRU and DOWNTHRU are particularly useful with ordinals. Consider the
following example:
define ordinal Color ( Red value (1),
Orange,
Yellow,
Green,
Blue,
Indigo,
Violet);
dcl C ordinal Color;
In the first loop, c assumes each successive color in ascending order from red to
violet. In the second loop, c assumes each successive color in descending order
from violet to red.
Example of REPEAT
This example shows the use of the REPEAT option in do-groups.
In the following example, the first execution of the do-group is performed with
I=1.
do I=1 repeat 2*I until(I=256);
After this and each subsequent execution of the do-group, the UNTIL expression is
tested. If I=256, no further executions are performed. Otherwise, the REPEAT
expression is evaluated and assigned to I, and a new execution starts.
The value Phead is assigned to P for the first execution of the do-group. Before each
subsequent execution, the value P -> Fwd is assigned to P. The value of P is tested
before the first and each subsequent execution of the do-group. If it is null, no
further executions are performed.
The following statement specifies that the do-group is to be executed nine times,
with the value of I equal to 1 through 9; then successively with the value of I
equal to 10, 20, 40, and so on. Execution ceases when the do-group has been
executed with a value of I greater than 10000.
do I = 1 to 9, 10 repeat 2*I
until (I>10000);
.
.
.
end;
END statement
The END statement ends one or more blocks or groups. Every block or group must
have an END statement.
END ;
statement-label
statement-label
Cannot be subscripted. If a statement-label follows END, the END statement
closes the unclosed group or block headed by the nearest preceding DO,
SELECT, PACKAGE, BEGIN, or PROCEDURE statement having that
statement-label. Every block with a DO, SELECT, PACKAGE, BEGIN or
PROCEDURE statement must have a corresponding END statement.
If a statement-label does not follow END, the END statement closes the one
group or block headed by the nearest preceding DO, SELECT, PACKAGE,
BEGIN, or PROCEDURE statement for which there is no other corresponding
END statement.
Execution of a block terminates when control reaches the END statement for the
block. However, it is not the only means of terminating a block's execution, even
though each block must have an END statement. (See Procedures on page 97
and Begin-blocks on page 118 for more details.)
Normal termination of a program occurs when control reaches the END statement
of the main procedure.
ENTRY statement
The ENTRY statement specifies a secondary entry point of a procedure.
For details about the ENTRY statement, see ENTRY attribute on page 121.
EXIT statement
The EXIT statement stops the current thread.
EXIT ;
FETCH statement
The FETCH statement checks main storage for the named procedures.
For details about the FETCH statement, see FETCH statement on page 108.
FLUSH statement
The FLUSH statement flushes the buffers associated with an open output file or
with all open output files.
For details about the FLUSH statement, see FLUSH statement on page 310 in
Chapter 10, Input and output, on page 297.
FORMAT statement
The FORMAT statement specifies a format list that can be used by edit-directed
data transmission statements to control the format of the data being transmitted.
For details about the FORMAT statement, see FORMAT statement on page 337 in
Chapter 12, Stream-oriented data transmission, on page 321.
FREE statement
The FREE statement frees the storage allocated for based and controlled variables.
For details about the FREE statement, see FREE statement for controlled
variables on page 259 and FREE statement for based variables on page 268 in
Chapter 9, Storage control, on page 253.
GET statement
The GET statement is a STREAM input data transmission statement that can assign
data values from either a data set or a string to one or more variables.
For details about the GET statement, see GET statement on page 322 in
Chapter 12, Stream-oriented data transmission, on page 321.
GO TO statement
The GO TO statement transfers control to the statement identified by the specified
label reference. The GO TO statement is an unconditional branch.
GO TO label ;
Abbreviation: GOTO
label
Specifies a label constant, a label variable, or a function reference that returns a
label value. Because a label variable can have different values at each execution
of the GO TO statement, control might not always transfer to the same
statement.
IF statement
The IF statement evaluates an expression and controls the flow of execution
according to the result of that evaluation. The IF statement thus provides a
conditional branch.
expression
The expression must have the attributes BIT(1) NONVARYING unless
RULES(LAXIF) is used.
When expressions involve the use of the & or | operators, they are evaluated
as described in Combinations of operations on page 70.
unit
Either a valid single statement, a group, or a begin-block. All single statements
are considered valid and executable except DECLARE, DEFAULT, END,
ENTRY FORMAT, PROCEDURE, or a %statement. If a nonexecutable statement
is used, the result can be unpredictable. Each unit can contain statements that
specify a transfer of control (for example, GO TO). Hence, the normal sequence
of the IF statement can be overridden.
Each unit can be labeled and can have condition prefixes.
If any bit in the string expression has the value '1'B, unit1 is executed and unit2, if
present, is ignored. If all bits are '0'B, or the string is null, unit1 is ignored and
unit2, if present, is executed.
IF statements can be nested. That is, either unit can itself be an IF statement, or
both can be. Because each ELSE is always associated with the innermost
unmatched IF in the same block or do-group, an ELSE with a null statement might
be required to specify a desired sequence of control. Consider the following
example:
if A = B then
.
.
.
else
if A = C then
.
.
.
else
.
.
.
If B and C are constants, this example is equivalent to the following statement and
would be better coded as follows:
select( A );
when ( B )
.
.
.
when ( C )
.
.
.
end;
Examples
In the following example, if the comparison is true (if A is equal to B), the value of
D is assigned to C, and the ELSE unit is not executed.
if A = B then
C = D;
else
C = E;
If the comparison is false (A is not equal to B), the THEN unit is not executed, and
the value of E is assigned to C.
Either the THEN unit or the ELSE unit can contain a statement that transfers
control, either conditionally or unconditionally. If the THEN unit ends with a GO
TO statement, there is no need to specify an ELSE unit. Consider the following
example:
if all(Array1 = Array2) then
go to LABEL_1;
next-statement
If the expression is true, the GO TO statement of the THEN unit transfers control
to LABEL_1. If the expression is not true, the THEN unit is not executed and control
passes to the next statement.
Short-circuit evaluation
The test of the IF expression is short-circuited under the following circumstances:
v If the IF expression consists of a logical OR of 2 expressions and the first of
these expressions is true, the second expression will not be evaluated and the
code will execute the THEN clause.
v If the IF expression consists of a logical AND of 2 expressions and the first of
these expressions is false, the second expression will not be evaluated and the
code will execute the ELSE clause.
Naturally, an expression formed (possibly recursively) from the above and the
NOT prefix operator and the AND or OR infix operators will also be
short-circuited.
Example
%INCLUDE directive
The %INCLUDE directive is used to incorporate external text into the source
program.
%INCLUDE member ;
ddname (member)
The included member can specify an absolute file name. Enclose the absolute file
name in single or double quotes. For example, the following statement is valid:
INTEL
%include "\ibmpli\include\sqlcodes.inc"
ITERATE statement
The ITERATE statement transfers control to the END statement that delimits its
containing iterative do-group. The current iteration completes and the next
iteration, if needed, is started.
ITERATE ;
label-constant
label-constant
Must be the label of a containing do-group. If label-constant is omitted, control
transfers to the END statement of the most recent iterative do-group containing
the ITERATE statement.
LEAVE statement
When contained in or specifying a simple do-group, the LEAVE statement
terminates the group. When contained in or specifying an iterative do-group, the
LEAVE statement terminates all iterations of the group, including the current
iteration.
The flow of control goes to the same point it would normally go to if the do-group
had terminated by reaching its END statement. This point is not necessarily the
statement following the END statement of the do-group (see Example).
LEAVE ;
label-constant
label-constant
Must be a label of a containing do-group. The do-group that is left is the
do-group that has the specified label. If label-constant is omitted, the do-group
that is left is the group that contains the LEAVE statement.
The LEAVE statement and the referenced or implied DO statement must not be in
different blocks.
Example
A: do I = lbound(X,1) to hbound(X,1);
do J = lbound(X,2) to hbound(X,2);
If X(I,J)=0 then
leave A; /* control goes to C, not B */
else
do;
.
.
.
end;
end;
end;
Else
B: do;
.
.
.
end;
%LINE directive
The %LINE directive specifies that the next line should be treated in messages and
in information generated for debugging as if it came from the specified line and
file.
The characters '%LINE' must be in columns 1 through 5 of the input line for the
directive to be recognized (and conversely, any line starting with these five
characters is treated as a %LINE directive). The line-number must be an integral
value of seven digits or less and the file-specification must not be enclosed in
quotation marks. Any characters specified after the semicolon are ignored.
The %LINE directive is invalid unless the LINEDIR compiler option is in effect.
LOCATE statement
The LOCATE statement allocates storage within an output buffer for a based
variable and sets a pointer to the location of the next record. The LOCATE
statement can be used only with an OUTPUT SEQUENTIAL BUFFERED file for
locate mode processing.
For details about the LOCATE statement, see LOCATE statement on page 314 in
Chapter 11, Record-oriented data transmission, on page 311.
%NOPRINT directive
The %NOPRINT directive causes printing of the source listings to be suspended
until a %PRINT directive is encountered or until a %POP directive that restores the
previous %PRINT directive is encountered.
%NOPRINT ;
For an example of the %NOPRINT directive, see %PUSH directive on page 247.
%NOTE directive
The %NOTE directive generates a diagnostic message of specified text and severity.
%NOTE ( message ) ;
,code
message
A character expression whose value is the required diagnostic message.
code
A fixed expression whose value indicates the severity of the message, as
follows:
Code Severity
0 I
4 W
8 E
12 S
16 U
Generated messages are filed together with other messages. Whether or not a
particular message is subsequently printed depends upon its severity level and the
setting of the compiler FLAG option (as described in the Programming Guide).
null statement
The null statement causes no operation to be performed and does not modify
sequential statement execution. It is often used to denote null action for THEN and
ELSE clauses and for WHEN and OTHERWISE statements.
ON statement
The ON statement establishes the action to be executed for any subsequent raising
of an enabled condition in the scope of the established condition.
OPEN statement
The OPEN statement associates a file with a data set.
For details about the OPEN statement, see OPEN statement on page 305 in
Chapter 10, Input and output, on page 297.
OTHERWISE statement
In a select-group, the OTHERWISE statement specifies the unit to be executed
when every test of the preceding WHEN statements fails.
For details about the OTHERWISE statement, see SELECT statement on page
249.
PACKAGE statement
The PACKAGE statement defines a package. A package forms a name scope that is
shared by all declarations and procedures contained in the package, unless the
names are declared again.
%PAGE directive
The %PAGE directive allows you to start a new page in the compiler source
listings.
%PAGE ;
%POP directive
The %POP directive allows you to restore the status of the %PRINT and
%NOPRINT directives saved by the most recent %PUSH directive.
The most common use of the %PUSH and %POP directives is in included files and
macros.
%POP ;
%PRINT directive
The %PRINT directive causes printing of the source listings to be resumed.
%PRINT ;
%PRINT is in effect, provided that the relevant compiler options are specified. For
an example of the %PRINT directive, see %PUSH directive on page 247.
PROCEDURE statement
A PROCEDURE statement identifies the procedure as a main procedure, a
subroutine, or a function. Parameters expected by the procedure and other
characteristics are also specified on the PROCEDURE statement.
For details about the PROCEDURE statement, see PROCEDURE and ENTRY
statements on page 98 in Chapter 5, Program organization, on page 91.
%PROCESS directive
The %PROCESS directive is used to override compiler options.
%PROCESS ;
compiler-option
The % or * must be the first data byte of a source record. Any number of
%PROCESS and *PROCESS directives can be specified, but they must all appear
before the first language element appears. Refer to the Programming Guide for
more information.
*PROCESS directive
The *PROCESS directive is a synonym for the %PROCESS directive.
Related information:
%PROCESS directive
The %PROCESS directive is used to override compiler options.
%PUSH directive
The %PUSH directive allows you to save the current status of the %PRINT and
%NOPRINT directives in a push down stack on a last-in, first-out basis. You can
restore this saved status later, also on a last-in, first-out basis, by using the %POP
directive.
A common use of %PUSH and %POP directives is in included files and macros.
%PUSH ;
In the following example, statements 1, 2, 3, S3, S4, and 4 are printed in the
listings. All others are not printed.
Source Program
statement 1;
statement 2;
%include First; /* statement 3 */
First
%push; /* F1 */
%noprint; /* F2 */
dcl A entry (ptr, fixed bin); /* F3 */
statement F4;
%include Second; /* stmt F5 */
Second
%push; /* S1 */
%print; /* S2 */
dcl B entry (ptr,fixed bin)
options(byvalue); /* S3 */
statement S4;
%pop;
statement F6;
%pop;
statement 4;
PUT statement
The PUT statement is a STREAM output data transmission statement that can
transmit values to a stream output file or assign values to a character variable.
For details about the PUT statement, see PUT statement on page 322 in
Chapter 12, Stream-oriented data transmission, on page 321.
READ statement
The READ statement either transmits a record from the data set to the program
variable or sets a pointer to the record in storage.
For details about the READ statement, see READ statement on page 312 in
Chapter 11, Record-oriented data transmission, on page 311.
REINIT statement
The REINIT statement allows variables to be reset with their INITIAL values.
REINIT reference ;
reference
The reference must be unsubscripted (although if BASED, it can be
locator-qualified), and the reference must be AUTOMATIC, CONTROLLED,
BASED, or STATIC.
RELEASE statement
The RELEASE statement frees the main storage occupied by procedures identified
by its specified entry constants.
For details about the RELEASE statement, see RELEASE statement on page 109
in Dynamic loading of an external procedure on page 107.
RESIGNAL statement
The RESIGNAL statement terminates the current ON-unit and allows another
ON-unit for the same condition to get control.
For details about the RESIGNAL statement, see RESIGNAL statement on page
378 in Chapter 15, Condition handling, on page 371.
RETURN statement
The RETURN statement terminates execution of the subroutine or function
procedure that contains the RETURN statement and returns control to the invoking
procedure.
REVERT statement
The REVERT statement cancels the ON-unit for the condition that was executed in
a given block.
For details about the REVERT statement, see REVERT statement on page 377 in
Chapter 15, Condition handling, on page 371.
REWRITE statement
The REWRITE statement replaces a record in an UPDATE file.
For details about the REWRITE statement, see REWRITE statement on page 313
in Chapter 11, Record-oriented data transmission, on page 311.
SELECT statement
A select-group provides a multiple path conditional branch. A select-group
contains a SELECT statement, optionally one or more WHEN statements,
optionally an OTHERWISE statement, and an END statement.
SELECT ;
(exp1) ,
OTHERWISE unit ;
If exp1 is omitted, each exp2 is evaluated and converted, if necessary, to a bit string.
If any bit in the resulting string is '1'B, the unit of the associated WHEN statement
is executed. If all bits are 0 or the string is null, the unit of the OTHERWISE
statement is executed.
If exp1 is specified, each exp2 must be such that the following comparison
expression has a scalar bit value:
(exp1) = (exp2)
Both exp1 and exp2 must be scalar expressions. Hence, while arrays, structures, and
unions can be used in either exp1 or exp2, the evaluated expression must be a
scalar value.
Examples
In the following example, E, E1, and so on, are expressions. When control reaches
the SELECT statement, the expression E is evaluated and its value is saved. The
expressions in the WHEN statements are then evaluated in turn (in the order in
which they appear), and each value is compared with the value of E.
If a value is found that is equal to the value of E, the action following the
corresponding THEN statement is performed; no further WHEN statement
expressions are evaluated.
SIGNAL statement
The SIGNAL statement is used in program testing to verify the action of an
ON-unit and to determine whether the correct action is associated with the
condition.
For details about the SIGNAL statement, see SIGNAL statement on page 377 in
Chapter 15, Condition handling, on page 371.
%SKIP directive
The %SKIP directive causes the specified number of lines to be left blank in the
compiler source listings.
%SKIP ;
(n)
STOP statement
The STOP statement stops the current application.
STOP ;
WAIT statement
The WAIT statement specifies that a process is suspended until the specified thread
terminates.
For details about the WAIT statement, see Waiting for a thread to complete on
page 406 in Chapter 17, Multithreading facility, on page 403.
WHEN statement
The WHEN statement specifies one or more expressions that are evaluated and
compared with the saved value from the SELECT statement.
For details about the WHEN statement, see SELECT statement on page 249.
WRITE statement
The WRITE statement transmits a record from the program and adds it to the data
set.
For details about the WRITE statement, see WRITE statement on page 313 in
Chapter 11, Record-oriented data transmission, on page 311.
%XINCLUDE statement
The %XINCLUDE directive is used to incorporate external text into the source
program if it has not previously been included.
%XINCLUDE member ;
ddname( member )
XPROCEDURE statement
The macro XPROCEDURE statement is identical to the macro PROCEDURE
statement except that the preprocessor will ignore rather than flag any subsequent
occurrence of an XPROCEDURE statement if the leftmost name on the statement is
the name of an already defined preprocessor procedure.
Abbreviation: XPROC
For information about the PROCEDURE statement, see PROCEDURE and ENTRY
statements on page 98 in Chapter 5, Program organization, on page 91.
Because X is automatic, the storage for it is allocated when its declaring block is
activated, and the storage remains allocated until the block is deactivated.
Allocation for a given variable can take place statically (before the execution of the
program) or dynamically (during execution). A variable that is allocated statically
remains allocated for the duration of the application program. A variable that is
allocated dynamically relinquishes its storage either upon the termination of the
block containing that variable, or at an explicit request from the application.
The storage class assigned to a variable determines the degree of storage control
applied to the variable's storage and the manner in which the variable's storage is
allocated and freed. You assign the storage class by using its corresponding
attribute in an explicit, implicit, or contextual declaration. There are four storage
classes:
AUTOMATIC
Specifies that storage is allocated upon each entry to the block that
contains the storage declaration. The storage is released when the block is
exited.
If the block is a procedure that is invoked recursively, the previously
allocated storage is pushed down upon entry; the latest allocation of
storage is popped up in a recursive procedure when each generation
terminates. For information about push-down and pop-up stacking, see
Recursive procedures on page 106.
STATIC
Specifies that storage is allocated when the program is loaded. The storage
is not freed until program execution is completed. The storage for a
fetched procedure is not freed until the procedure is released.
CONTROLLED
Specifies that you use the ALLOCATE and FREE statements to control the
allocation and freeing of storage. Multiple allocations of the same
controlled variable in the same program, without intervening freeing,
stacks generations of the variable. You can access earlier generations only
by freeing the later ones.
BASED
Like CONTROLLED, specifies that you control storage allocation and
freeing. One difference is that multiple allocations are not stacked but are
available at any time. Each allocation can be identified by the value of a
pointer variable. Another difference is that based variables can be
associated with an area of storage and identified by the value of an offset
variable.
Based variables outside of areas can be allocated by the ALLOCATE
built-in function and freed by the PLIFREE built-in subroutine. They can
also be allocated by the AUTOMATIC built-in function; such allocated
variables are freed automatically when the block in which they are
allocated terminates.
Storage class attributes can be declared explicitly for element, array, and major
structure and union variables. For array and major structure and union variables,
the storage class declared for the variable applies to all of the elements in the array
or structure or union.
Allocation of storage for variables is managed by PL/I. You do not specify where
in storage the allocation is to be made. You can, however, specify that a variable be
allocated in an existing AREA.
Related information:
Area data and attribute on page 271
Area variables describe areas of storage that are reserved for the allocation of
based variables. This reserved storage can be allocated to, and freed from, based
variables by the ALLOCATE and FREE statements.
STATIC
STATIC is the default for external variables, but internal variables can also be
static. It is also the default for variables declared in a package, outside of any
procedure. Static variables follow the normal scope rules for the validity of
references to them. In the following example, the variable X is allocated for the life
of the program, but it can be referenced only within procedure B or any block
contained in B. The variable Y gets the STATIC attribute and is also allocated for
the life of the program.
A: proc options(main);
B: proc;
declare X static internal;
end B;
end A;
C: proc;
Y = hello;
end C;
end Package;
If static variables are initialized by the INITIAL attribute, the initial values must be
restricted expressions. Extent specifications must also be restricted expressions.
If a variable has more than 100 INITIAL items, the compiler and the user code
usually perform better when the variable is declared with the STATIC attribute.
AUTOMATIC
Abbreviation: AUTO
In the following example, each time procedure B is invoked, the variables X and Y
are allocated storage. When B terminates, the storage is released, and the values
that X and Y contain are lost.
A: proc;
.
.
.
call B;
B: proc;
declare X,Y auto;
.
.
.
end B;
.
.
.
call B;
The storage that is freed is available for allocation to other variables. Thus,
whenever a block (procedure or begin) is active, storage is allocated for all
variables declared automatic within that block. Whenever a block is inactive, no
storage is allocated for the automatic variables in that block. Only one allocation of
a particular automatic variable can exist, except for those procedures that are called
recursively or by more than one program.
Extents for automatic variables can be specified as expressions. This means that
you can allocate a specific amount of storage when you need it. In the following
example, the character string STR has a length defined by the value of the variable
N when procedure B is invoked.
A: proc;
declare N fixed bin;
.
.
.
B: proc;
declare STR char(N);
If the declare statements are located in the same block, PL/I requires that the
variable N be initialized either to a restricted expression or to an initialized static
variable. In the following example, the length allocated is correct for Str1, but not
for Str2. PL/I does not resolve this type of declaration dependency.
dcl N fixed bin (15) init(10),
M fixed bin (15) init(N),
Str1 char(N),
Str2 char(M);
Controlled variables are partially independent of the program block structure, but
not completely. The scope of a controlled variable can be internal or external.
When it is declared as internal, the scope of the variable is the block in which the
variable is declared and any contained blocks. Any reference to a controlled
variable that is not allocated is in error.
You cannot pass variables that are not declared as CONTROLLED to a procedure
that declares them as CONTROLLED. However, you can pass a variable that is
declared as CONTROLLED to a procedure that does not declare it as
CONTROLLED.
CONTROLLED
Abbreviation: CTL
.
B: proc;
allocate X;
.
.
end B;
end A;
Generally, controlled variables are useful when a program requires large data
aggregates with adjustable extents. Statements in the following example allocate
the exact storage required depending on the input data and free the storage when
it is no longer required.
dcl A(M,N) ctl;
get list(M,N);
allocate A;
get list(A);
.
.
.
free A;
The bounds of controlled arrays, the lengths of controlled strings, and the size of
controlled areas, as well as their initial values, can be specified in the ALLOCATE
statement.
attribute:
dimension
CHARACTER(length)
BIT(length)
GRAPHIC(length)
WIDECHAR(length)
AREA(size)
,
INITIAL( item )
INITIAL CALL entry-reference
,
( argument )
Abbreviation: ALLOC
level
Indicates a level number. If no level number is specified, the
controlled-variable named must be a level-1 variable.
controlled-variable
Specifies a controlled variable or an element of a controlled major structure. A
structure element, other than the major structure, can appear only if the
relative structuring of the entire major structure containing the element appears
as it is in the DECLARE statement for that structure. In this case, dimension
attributes must be specified for all names that are declared with the dimension
attribute.
Both controlled and based variables can be allocated in the same statement. For the
syntax of the ALLOCATE statement for based variables, see ALLOCATE
statement for based variables on page 267.
Bounds for arrays, lengths of strings, and sizes of areas (extents) are evaluated at
the execution of an ALLOCATE statement:
v Either the ALLOCATE statement or a DECLARE or DEFAULT statement must
specify any necessary dimension, size, or length attributes (extents) for a
variable. Any expression taken from a DECLARE statement is evaluated at the
point of allocation by using the conditions enabled at the ALLOCATE statement.
However, names in the expression refer to those variables whose scope includes
the DECLARE or DEFAULT statement.
v If a bound, length, or size is explicitly specified in an ALLOCATE statement, it
overrides that given in the DECLARE statement for that variable.
v If a bound, length, or size is specified by an asterisk in an ALLOCATE
statement, that extent is taken from the current generation. If no generation of
the variable exists, the extent is undefined and the program is in error.
v If, in either an ALLOCATE or a DECLARE statement, bounds, lengths, or sizes
are specified by expressions that contain references to the variable being
allocated, the expressions are evaluated by using the value of the most recent
generation of the variable. Consider the following example:
declare X(N) fixed bin ctl;
N = 20;
allocate X;
allocate X(X(1));
In the first allocation of X, the upper bound is specified by the declare statement
and N = 20;. In the second allocation, the upper bound is specified by the value
of the first element of the first generation of X.
The dimension attribute must specify the same number of dimensions as declared.
The dimension attribute can appear with any of the other attributes and must be
the first attribute specified. See the following example:
declare X(M) char(N) controlled;
M = 20;
N = 5;
allocate X(25) char(6);
The BIT, CHARACTER, GRAPHIC, WIDECHAR and AREA attributes can appear
only for variables having the same attributes, respectively.
Initial values are assigned to a variable upon allocation, if the variable has an
INITIAL attribute in either the DECLARE or ALLOCATE statement. Expressions or
the CALL option in the INITIAL attribute are evaluated at the point of allocation,
by using the conditions enabled at the ALLOCATE statement. However, the names
Any evaluations performed at the time the ALLOCATE statement is executed (for
example, evaluation of expressions in an INITIAL attribute) must not be
interdependent.
If storage for the controlled variable is not available, the STORAGE condition is
raised.
FREE controlled-variable ;
controlled-variable
A level-1, unsubscripted variable
Both based and controlled variables can be freed in the same statement. For the
syntax of the FREE statement for based variables, see FREE statement for based
variables on page 268.
Implicit freeing
The previous generation cannot be directly accessed until the current generation
has been freed. When storage for this variable is freed by the FREE statement or at
termination of the program in which the storage was allocated, storage is popped
up or removed from the stack.
Asterisk notation
In an ALLOCATE statement, values are inherited from the most recent previous
generation when dimensions, lengths, or sizes are indicated by asterisks. For
arrays, the asterisk must be used for every dimension of the array, not just one of
them.
allocate X;
allocate X(10,10);
allocate X(*,*);
The first generation of X has bounds (10,20); the second and third generations have
bounds (10,10). The elements of each generation of X are all character strings of
length 5.
The asterisk notation can also be used in a DECLARE statement, but has a
different meaning there. Consider the following example:
dcl Y char(*) ctl,
N fixed bin;
N=20;
allocate Y char(N);
allocate Y;
The length of the character string Y is taken from the previous generation unless it
is specified in an ALLOCATE statement. In that case, Y is given the specified
length. This allows you to defer the specification of the string length until the
actual allocation of storage.
Adjustable extents
Controlled scalars, arrays, and members of structures and unions can have
adjustable array extents, string lengths, and area sizes.
In the following example, when the structure is allocated, A.B has the extent 1 to
10 and A.C is a varying character string with maximum length 5.
dcl 1 A ctl,
2 B(N:M),
2 C char(*) varying;
N = -10;
M = 10;
alloc 1 A,
2 B(1:10),
2 C char(5);
free A;
If the variable is not allocated, the function returns the value zero.
A based variable does not identify the location of a generation in main storage. A
locator value identifies the location of the generation. Any reference to a based
variable that is not allocated is in error.
BASED
(locator-reference)
locator-reference
Identifies the location of the data.
When reference is made to a based variable, the data and alignment attributes used
are those of the based variable, while the qualifying locator variable identifies the
location of data.
A based variable cannot have the EXTERNAL attribute, but a locator reference for
a based variable can have any storage class, including based.
If you do not specify the REFER option, the extent specifications in the BASED
declarations must be restricted expressions with the following exceptions:
v A non-constant array extent in a BASED variable is invalid unless the array
meets all of the following conditions:
It is one dimensional.
The lower bound of the array is a constant.
When it is a part of a structure, the extents of all other fields in the structure
are constant, and no fields follow the array and the parent structures, if any,
of the array.
v A non-constant CHAR extent in a BASED variable is invalid unless the string is
a scalar or it meets all of the following conditions:
It is the last element in a structure.
It has no parents that are arrays.
It has one of these attributes: UNALIGNED, NONVARYING, or VARZ.
v Any of the following non-constant extents in a BASED variable are valid only if
the variable is a scalar:
The non-constant AREA extent
Examples
A based variable can also be used to access existing data by using the READ
statement (with SET option), or the FETCH statement (with SET option), or the
ADDR built-in function.
Based AREA variables can be allocated by using the ALLOCATE statement; PL/I
automatically initializes the area to EMPTY upon allocation. However, if you
obtain storage for the area variable by the ALLOCATE or the AUTOMATIC built-in
function, you must assign EMPTY to the variable after obtaining the storage.
Locator variables
Because a locator variable identifies the location of any generation, you can refer at
any point in a program to any generation of a based variable by using an
appropriate locator value.
The following example declares that references to X, except when the reference is
explicitly qualified, use the locator variable P to locate the storage for X.
dcl X fixed bin based(P);
The association of a locator reference in this way is not permanent. The locator
reference can be used to identify locations of other based variables and other
locator references can be used to identify other generations of the variable X. When
a based variable is declared without a locator reference, any reference to the based
variable must always be explicitly locator-qualified.
In the following example, the arrays A and C refer to the same storage. The
elements B and C(2,1) also refer to the same storage.
dcl A(3,2) character(5) based(P),
B char(5) based(Q),
C(3,2) character(5);
P = addr(C);
Q = addr(A(2,1));
Note: When a based variable is overlaid in this way, no new storage is allocated.
The based variable uses the same storage as the variable on which it is overlaid
(C(3,2) in the example).
INITIAL attribute
The INITIAL attribute can be specified for a based variable. The initial values are
assigned only upon explicit allocation of the based variable with an ALLOCATE or
LOCATE statement.
Locator data
There are two types of locator data: pointer and offset.
The value of an offset variable specifies a location within an area variable and
remains valid when the area is assigned to a different part of storage.
A locator value can be assigned only to a locator variable. When an offset value is
assigned to an offset variable, the area variables named in the OFFSET attributes
are ignored.
Locator conversion
Except in a few cases, locator data cannot be converted to other data types.
Because the area variable is different from that associated with the offset variable,
you must ensure that the offset value is valid for the different area. It is valid, for
example, if area A is assigned to area B before the invocation of the function.
The OFFSET built-in function, in contrast to the POINTER built-in function, returns
an offset value derived from a given pointer and area. The given pointer value
must identify the location of a based variable in the given area.
A pointer value is converted to an offset by using the pointer value and the
address of the area. This conversion is limited to pointer values that relate to
addresses within the area named in the OFFSET attribute.
Except when assigning the NULL or the SYSNULL built-in function value, it is an
error to attempt to convert from or to an offset variable that is not associated with
an area.
Locator reference
A locator reference is either a locator variable that can be qualified or subscripted,
or a function reference that returns a locator value.
Because PL/I implicitly converts an offset to a pointer value, offset references can
be used interchangeably with pointer references.
Locator qualification
Locator qualification is the association of one or more locator references with a
based reference to identify a particular generation of a based variable. This is
called a locator-qualified reference.
The composite symbol -> represents qualified by or points to. The following
syntax diagram is for an explicit qualified reference.
locator-reference ->
based-locator-reference ->
based-variable
locator-reference
based-locator-reference
Identify the location of the data.
The reference means that it is that generation of X that is identified by the based
locator Q that is also identified by the value of the locator P. X and Q are explicitly
locator-qualified.
When more than one locator qualifier is used, they are evaluated from left to right.
Reference to a based variable can also be implicitly qualified. The locator reference
used to determine the generation of a based variable that is implicitly qualified is
the one declared with the based variable. In the following example, the
ALLOCATE statement sets the pointer variable P so that the reference X applies to
allocated storage.
dcl X fixed bin based(P) init(0);
allocate X;
X = X + 1;
The following assignment statements have the same effect as the previous example:
Q = P;
Q->X = Q->X + 1;
Because the locator declared with a based variable can also be based, a chain of
locator qualifiers can be implied. For example, the following pointer and based
variables can be used:
declare (P(10),Q) pointer,
R pointer based (Q),
V based (P(3)),
W based (R),
Y based;
allocate R,V,W;
Given the previous declaration and allocation, the following references are valid:
P(3) -> V
V
Q -> R -> W
R -> W
W
The first two references are equivalent, and the last three are equivalent. Any
reference to Y must include a qualifying locator variable.
In the following example, the references X, P -> X, and Q -> P -> X represent three
levels of locator qualification.
declare X based (P),
P pointer based (Q),
Q offset (A);
POINTER
( 32 )
64
Abbreviation: PTR
32 A POINTER(32) is four bytes in size and by default fullword-aligned.
64 A POINTER(64) is eight bytes in size and by default doubleword-aligned.
If the LP(32) compiler option is in effect, the default is POINTER(32); if the LP(64)
compiler option is in effect, the default is POINTER(64). POINTER(64) is valid only
under LP(64).
The ALLOCATE built-in function can be used to obtain storage for a based
variable, and the PLIFREE built-in subroutine can be used to free such storage. The
AUTOMATIC built-in function can also be used to obtain storage for a based
variable, but such storage must not be explicitly freed. Storage allocated with the
AUTOMATIC built-in function is automatically freed when the block in which it is
allocated terminates.
The ADDR built-in function returns a pointer value that identifies the first byte of
a variable. The ENTRYADDR built-in function returns a pointer value that is the
address of the first executed instruction if the entry were to be invoked. The NULL
and SYSNULL built-in functions return the PL/I null pointer and the system null
pointer respectively.
Note: The NULL and SYSNULL built-in functions can, but do not necessarily,
compare equally. Your application program must not depend on the functions'
equality.
location-reference:
IN(area-variable) SET(locator-variable)
Abbreviation: ALLOC
based variable
Is a level-1 unsubscripted variable.
IN Specifies the area variable in which the storage is allocated. For more
information about areas, see Area data and attribute on page 271.
SET
Specifies a locator variable that is set to the location of the storage allocated. If
the SET option is not specified, the locator used is the one specified in the
declaration of the based variable. For syntax information about declaring based
variables, see Based storage and attribute on page 261 and Locator data on
page 264.
Both based and controlled variables can be allocated in the same statement. For the
syntax of the ALLOCATE statement for controlled variables, see ALLOCATE
statement for controlled variables on page 257.
Storage is allocated in an area when the IN option is specified or when the SET
option specifies an offset variable. These options can appear in any order.
For allocations in areas, if the area does not have sufficient storage for the based
variable, the AREA condition is raised. If you use an offset variable without the IN
option, you must specify an area reference in the declaration of the offset variable.
When an area is not used, the locator variable must be a pointer variable. If
storage for the based variable is not available, the STORAGE condition is raised.
Note that if a based variable uses REFER, its size will be calculated at run time. If
2
this calculation yields a value that is too large to fit in a size_t variable, your
program is in error and should be corrected. In this situation, the STORAGE
condition will not be raised; instead, the ERROR condition with ONCODE=3809
will be raised if either of the following conditions applies:
v The SIZE condition is enabled.
v The BASED structure is mapped through a library call.
The amount of storage allocated for a based variable depends on its attributes, and
on its dimensions, length, or size specifications if these are applicable at the time of
allocation. These attributes are determined from the declaration of the based
variable.
A based structure or union can contain adjustable array bounds or string lengths
or area sizes (see REFER option (self-defining data) on page 269). The asterisk
notation for extents is not allowed for based variables.
2. If the LP(32) compiler option is in effect, size_t is FIXED BIN(31); if the LP(64) compiler option is in effect, size_t is FIXED BIN(63).
FREE option ;
option:
based-variable
locator-reference -> IN(area-variable)
locator-reference ->
Frees a particular generation of a based variable. The composite symbol ->
means qualified by or points to. If the based variable is not explicitly
locator-qualified, the locator variable declared in the BASED attribute is used
to identify the generation of data to be freed. If no locator has been declared,
the statement is in error.
based variable
Must be a level-1, unsubscripted based variable.
IN Must be specified or the based variable must be qualified by an offset declared
with an associated area, if the storage to be freed was allocated in an area. The
IN option cannot appear if the based variable was not allocated in an area.
Area assignment allocates based storage in the target area. These allocations
can be freed by the IN option naming the target area.
Both based and controlled variables can be freed in the same statement. For the
syntax of the FREE statement for controlled variables, see FREE statement for
controlled variables on page 259.
A based variable can be used to free storage only if that storage has been allocated
for a based variable having identical data attributes.
The amount of storage freed depends upon the attributes of the based variable,
including bounds or lengths at the time the storage is freed. The user is responsible
for determining that this amount coincides with the amount allocated. If the
variable has not been allocated, the results are unpredictable.
Implicit freeing
A based variable need not be explicitly freed by a FREE statement, but it is a good
practice to do so.
The syntax for a length, bound, or size with a REFER option is shown in the
following diagram.
expression
The value of this expression defines the length, bound, or size of the member
when the structure or union is allocated (by ALLOCATE or LOCATE). The
3
expression is evaluated and converted to size_t . Any variables that are used as
operands in the expression must not belong to the structure or union that
contains the REFER option.
Subsequent references to the structure or union obtain the REFER option
member's length, bound, or size from the current value of member-variable (the
refer object).
member-variable
The refer object must conform to the following rules:
v It must be a member of the same level-1 structure or union, and it must
appear before any member that names it in a REFER option.
v It must be computational. It must be FIXED BIN with a scale factor of zero.
If it has a type other than FIXED BIN(p,0), the compiler issues a W-level
message.
v It cannot be locator-qualified (see Locator qualification on page 265) or
subscripted.
v It cannot be part of an array.
In the following example, the declaration specifies that the based structure STR
consists of an array Y and an element X.
declare 1 STR based(P),
2 X fixed binary(31,0),
2 Y (L refer (X)),
L fixed binary(31,0) init(1000);
When STR is allocated, the upper bound is set to the current value of L, which is
assigned to X. For any other reference to Y, such as a READ statement that sets P,
the bound value is taken from X.
If the INITIAL attribute is specified for the member with the REFER option,
initialization of the member occurs after the refer object has been assigned its
value.
3. If the LP(32) compiler option is in effect, size_t is FIXED BIN(31); if the LP(64) compiler option is in effect, size_t is FIXED BIN(63).
The value of the refer object should not be changed during program execution. It is
an error to free such an aggregate if the value of the refer object has changed.
Note also that any variables used in the expression defining the REFER extent
should be declared in the block (or one of its parent blocks) containing the
DECLARE using that REFER. If one of the variables is not declared, it will be
implicitly declared following the usual rules for implicit declaration, that is, a
DECLARE for it will be added to the outermost block containing the DECLARE.
This means that in the following code, the declaration of and assignment to the
variable m in the subroutine inner_proc will have no effect on the ALLOCATE
statement: the ALLOCATE statement will use the implicitly declared and
uninitialized m from the main block.
refertst: proc options(main);
dcl
1 a based,
2 n fixed bin(31),
2 c char(m refer(n));
call inner_proc;
inner_proc: proc;
m = 15;
allocate a set(p);
end;
end;
Area variables can have any storage class and can be aligned or unaligned. When
you declare the AREA variables as UNALIGNED, they are aligned by byte rather
than by doubleword.
You might want to identify the locations of based variables within an area variable
relative to the start of the area variable. Offset variables are provided for this
purpose.
The size of an area is adjustable in the same way as a string length or an array
bound and therefore it can be specified by an expression or an asterisk (for a
controlled area parameter) or by a REFER option (for a based area).
AREA
(*)
(expression )
REFER(variable)
expression
Specifies the size of the area. If expression or an asterisk is not specified, the
default is 1000.
* An asterisk can be used to specify the size if the area variable is declared is a
parameter.
REFER
For a description of the REFER option, see REFER option (self-defining data)
on page 269.
The area size for areas that have the storage classes AUTOMATIC or
CONTROLLED is given by an expression whose value specifies the number of
reserved bytes.
If an area has the BASED attribute, the area size must be a constant unless the area
is a member of a based structure or union and the REFER option is used.
The size for areas of static storage class must be specified as a restricted
expression.
The amount of reserved storage that is actually in use is known as the extent of the
area. When an area variable is allocated, it is empty, that is, the area extent is zero.
The maximum extent is represented by the area size. Based variables can be
allocated and freed within an area at any time during execution, thus varying the
extent of an area.
When a based variable is freed, the storage it occupied is available for other
allocations. A chain of available storage within an area is maintained; the head of
the chain is held within the control information. Inevitably, as based variables with
different storage requirements are allocated and freed, gaps occur in the area when
allocations do not fit available spaces. These gaps are included in the extent of the
area.
Because the based variables are located relatively, if the area variable is assigned to
a different part of main storage, the offset values remain valid.
Offset variables do not preclude the use of pointer variables within an area.
OFFSET
(area-variable)
If no area variable is specified, the offset can be used only as a locator qualifier
through use of the POINTER built-in function.
allocate X;
allocate Y in(A);
The storage class of area A and offset O is AUTOMATIC by default. The first
ALLOCATE statement is equivalent to the following statement:
allocate x in(A) set(O);
The following example shows how a list can be built in an area variable using
offset variables:
dcl A area,
(T,H) offset(A),
1 STR based(H),
2 P offset(A),
2 data;
do loop;
allocate STR set(T->P);
T=T->P;
.
.
.
end;
LOCATES attribute
Specifying the LOCATES attribute reduces storage when the compiler creates and
passes sparse arrays of strings. The LOCATES attribute is valid only with the
OFFSET attribute. And the LOCATES attribute allows the located type to be any
computational type, an ORDINAL type, or a STRUCT type.
LOCATES ( description )
description
Must specify a set of attributes, which are separated by blanks or parentheses.
You can specify the attributes in the same way as you declare them in the
DECLARE statement. The compiler applies defaults in the normal way.
The attributes in description can be any of the data and alignment attributes for
scalar BIT, CHARACTER, and WIDECHAR strings. The string lengths must be
specified by constants. The compiler ignores any alignment attributes that are
specified when it allocates the associated storage. The following example, Example
1, shows how to specify the LOCATES attribute:
Example 1
declare
1 data based(data_ptr) unaligned,
2 actual_count fixed bin(31),
2 orderinfo(order_count refer(actual_count)),
3 name offset(pool) locates(char(30) varying),
3 address offset(pool) locates(char(62) varying),
2 pool area(10_000);
The LOCATES attributes turn the associated offset into a typed offset. Then you
can use the LOCVAL built-in function and pseudovariable to dereference the typed
offset. The process of dereferencing is the same as the process of the * operator
dereferencing a typed pointer in the C language.
You can use the following built-in subroutines and built-in functions to allocate the
offsets that have the LOCATES attribute, assign values into the associated area,
and retrieve the values that are associated with these offsets:
v LOCNEWSPACE
You can use the LOCNEWSPACE on page 584 built-in subroutine to allocate
an OFFSET variable with enough space for the maximum length that is required
by the LOCATES attribute.
v LOCNEWVALUE
You can use the LOCNEWVALUE on page 585 built-in subroutine to allocate
an OFFSET variable with enough space to hold a specified value with its
LOCATES attribute. It also assigns that specified value into the associated
address.
v LOCVAL
You can use the LOCVAL on page 587 built-in function and pseudovariable to
dereference an OFFSET variable that has the LOCATES attribute.
v LOCSTG
You can use the LOCSTG on page 586 built-in function to determine the
maximum size that is needed for an AREA variable to hold all the values that
can be held indirectly in a variable that has the LOCATES attribute or contains
elements that have the LOCATES attribute.
For example, given the declaration in Example 1, both of the following statements
allocate space in the pool area to hold the string, assign that offset to name(1), and
then assign the value Sherlock Holmes as a character varying string to that location
in the area. The call locnewvalue statement allocates 17 bytes to hold the specified
value. The call locnewvalue statement allocates the full size, 32 bytes that are
required for the string attributes (CHAR(30) VARYING) in the LOCATES attribute.
However, a new offset area can be allocated by using the following statement:
address(1) = '221B Baker Street';
v You can determine whether a LOCVAL reference is valid by first testing that the
offset is not equal to sysnull().
If the type in the LOCATES attribute is a STRUCT type, after the space for it is
allocated, the LOCATES attribute might be referenced as if it had the type directly.
Consider the following example:
dcl
1 xmit based(p) unal,
2 asize fixed bin(31),
2 bcount fixed bin(31),
2 b(bx refer(bcount))
offset(a) locates( type ted ),
2 a area(ax refer(asize));
b(1).t1 = 17;
b(1).t2 = 314159265358;
However, the values for b(1) can also be assigned by using the LOCVAL
pseudovariable.
Area assignment
The value of an area reference can be assigned to one or more area variables by an
assignment statement. Area-to-area assignment has the effect of freeing all
allocations in the target area and then assigning the extent of the source area to the
target area so that all offsets for the source area are valid for the target area.
alloc X in (A);
X = 1;
alloc X in (A) set (O(2));
O(2) -> X = 2;
B = A;
Using the POINTER built-in function, the references POINTER (O(2),B)->X and
O(2)->X represent the same value allocated in areas B and A, respectively.
Area assignment can be used to expand a list of based variables beyond the
bounds of the original area. Attempting to allocate a based variable within an area
that contains insufficient free storage to accommodate it or attempting to assign an
area to another area that is not large enough raises the AREA condition. The
ON-unit for this condition can be used to change the value of a pointer qualifying
the reference to the inadequate area, so that it points to a different area; on return
from the ON-unit, the allocation is attempted again, within the new area.
Alternatively, you can use the AVAILABLEAREA built-in function to determine
whether the allocation you are about to make can be done in the area without
raising the AREA condition. Also, the ON-unit can write out the area and reset it
to EMPTY.
Input/output of areas
Areas allow input and output of complete lists of based variables as one unit, to
and from RECORD files.
On output, the area extent, together with the 16 bytes of control information, is
transmitted, except when the area is in a structure or union and is not the last item
in it. Then, the declared size is transmitted. Thus the unused part of an area does
not take up space on the data set.
Because the extents of areas can vary, varying length records should be used. The
maximum record length required is governed by the area length (area size + 16).
List processing
List processing is the name for a number of techniques to help manipulate
collections of data. Although arrays, structures, and unions are also used for
manipulating collections of data, list processing techniques are more flexible
because they allow collections of data to be indefinitely reordered and extended
during program execution.
The purpose here is not to illustrate these techniques but is to show how based
variables and locator variables serve as a basis for this type of processing.
allocate STR;
T=H;
do loop;
allocate STR set(T->P);
T=T->P;
T->P=null;
.
.
.
end;
The structures are generations of STR and are linked by the pointer variable P in
each generation. The pointer variable T identifies the previous generation during
the creation of the list. The first ALLOCATE statement sets the pointer H to identify
it. The pointer H identifies the start, or head, of the list. The second ALLOCATE
statement sets the pointer P in the previous generation to identify the location of
this new generation. The assignment statement T=T->P; updates pointer T to
identify the location of the new generation. The assignment statement T->P=NULL;
sets the pointer in the last generation to NULL, giving a positive indication of the
end of the list.
The foregoing examples show a simple list processing technique, the creation of a
unidirectional list. More complex lists can be formed by adding other pointer
variables into the structure or union. If a second pointer is added, it can be made
to point to the previous generation. The list is then bidirectional; from any item in
the list, the previous and next items can be accessed by using the appropriate
pointer value. Instead of setting the last pointer value to the value of NULL, it can
be set to point to the first item in the list, creating a ring or circular list.
A list need not consist only of generations of a single based variable. Generations
of different based structure or unions can be included in a list by setting the
appropriate pointer values. Items can be added and deleted from a list by
manipulating the values of pointers. A list can be restructured by manipulating the
pointers so that the processing of data in the list can be simplified.
ASSIGNABLE
NONASSIGNABLE
Default: ASSIGNABLE
The ABNORMAL attribute specifies that the value of the variable can change
between statements or within a statement. An abnormal variable is fetched from or
stored in storage each time it is needed or each time it is changed. All optimization
is inhibited for an abnormal variable.
NORMAL
ABNORMAL
Default: NORMAL
BIGENDIAN
LITTLEENDIAN
X = 258;
Y = 258;
The HEXIMAGE built-in function shows how X and Y are actually stored.
display( heximage( addr(X), stg(X) ) ); /* displays 0102 */
display( heximage( addr(Y), stg(Y) ) ); /* displays 0201 */
In contrast, the HEX built-in function shows the storage representation for X and Y.
display (hex(X)); /* displays 0102 */
display (hex(Y)); /* displays 0102 */
For more information about using BIGENDIAN and LITTLEENDIAN, refer to the
Programming Guide.
The NATIVE and NONNATIVE attributes are synonyms for BIGENDIAN and
LITTLEENDIAN, but their meanings can vary across different systems:
v On z/OS and RS/600, NATIVE means BIGENDIAN.
v On Windows, NATIVE means LITTLEENDIAN.
IEEE
HEXADEC
The HEXADEC and IEEE suboptions of the DEFAULT compiler option can be used
to change the default for this attribute.
On the Windows and AIX platforms, all computations are done using IEEE
floating-point; variables declared HEXADEC will be converted to IEEE as
necessary.
On the z/OS platform, floating-point computations can be done using one of 3 sets
of floating-point instructions:
v IBM hexadecimal floating-point
v IEEE binary floating-point
v IEEE decimal floating-point
On the z/OS platform, the choice of which set of instructions is used for a float
calculation is determined by two compiler options:
v Under FLOAT(DFP)
All computations that would yield a FLOAT DEC result are done using the
IEEE decimal floating-point instructions.
All computations that would yield a FLOAT BIN result are done using the
floating-point instructions for the format specified by the HEXADEC and
IEEE suboptions of the DEFAULT compiler option.
v Under FLOAT(NODFP)
All computations that would yield a FLOAT result are done using the
floating-point instructions for the format specified by the HEXADEC and
IEEE suboptions of the DEFAULT compiler option.
Under the FLOAT(DFP) compiler option, the IEEE and HEXADEC attributes are
valid only for FLOAT BIN, and the DEFAULT(IEEE/HEXADEC) option will be
applied only to FLOAT BIN.
Elements, arrays, and major structure or unions are always allocated in connected
storage. References to unconnected storage arise only when you refer to an
aggregate that is made up of noncontiguous items from a larger aggregate. (See
Cross sections of arrays on page 188.) For example, in the following structure,
the interleaved arrays A.B and A.C are both in unconnected storage.
1 A(10),
2 B,
2 C;
NONCONNECTED
CONNECTED
Default: NONCONNECTED
The UNION attribute allows you to achieve the same end in a much cleaner
manner and also allows variables with different attributes and precisions to be
overlaid. Also, while the DEFINED attribute guarantees that access through
defined or base variables is reflected in all defined variables, in a union only one
member of the union is valid at any given time. For syntax information for the
UNION attribute, see UNION attribute on page 190.
DEFINED reference
(reference) POSITION(expression)
If the base variable is a data aggregate, a defined variable can comprise all the data
or only a specified part of it.
The defined variable does not inherit any attributes from the base variable. The
defined variable must be INTERNAL and a level-1 identifier. It can have the
dimension attribute. It cannot be INITIAL, AUTOMATIC, BASED, CONTROLLED,
STATIC, or a parameter.
There are three types of defining: simple, iSUB, and string overlay.
If the POSITION attribute is specified, the base variable must not contain iSUB
references.
A base variable and a defined variable match if the base variable when passed as
an argument matches a parameter that has the attributes of the defined variable
(except for the DEFINED attribute). For this purpose, the parameter is assumed to
have all array bounds, string lengths, and area sizes specified by asterisks.
For simple defining and iSUB defining, a PICTURE attribute can only be matched
by a PICTURE attribute that is identical except for repetition factors. For a
reference to specify a valid base variable in string overlay defining, the reference
must be in connected storage. You can override the matching rule completely, but
this can cause unwanted side effects within your program.
The values specified or derived for any array bounds, string lengths, or area sizes
in a defined variable do not always have to match those of the base variable.
However, the defined variable must be able to fit into the corresponding base
array, string, or area.
If the defined variable is a structure or union containing any elements that are
unaligned nonvarying BIT, all array bounds and string lengths in the defined
variable must be specified as constants.
If the defined variable has the BIT attribute, unpredictable results can occur under
the following conditions:
v The base variable is not on a byte boundary.
v The defined variable is not defined on the first position of the base variable, and
the defined variable is used as follows:
A parameter in a subroutine call (that is, referenced as internally stored data)
An argument in a PUT statement
An argument in a built-in function (library call)
If the base variable is controlled, and the defined variable is dimensioned and
is declared with variable array bounds.
v If the defined variable consists entirely of unaligned nonvarying bit strings, the
array bounds, string lengths, and area sizes of the defined variable must be
known at compile time.
Unconnected storage
The DEFINED attribute can overlay arrays. This allows array expressions to refer
to array elements in unconnected storage (array elements that are not adjacent in
storage).
Simple defining
Simple defining allows you to refer to an element, array, or structure variable by
another name.
Simple defining is supported only for scalars, for structures with constant extents
matching those in the base variable, and for arrays of such scalars and structures if
they are not based on controlled variables.
The defined and base variables can comprise any data type, but they must match.
The ALIGNED and UNALIGNED attributes must match for each element in the
defined variable and the corresponding element in the base variable.
In simple defining of a string, the length of the defined string must be less than or
equal to the length of the base string.
In simple defining of an area, the size of the defined area must be equal to the size
of the base area.
A base variable can be, or can contain, a varying string, provided that the
corresponding part of the defined variable is a varying string of the same
maximum length.
Examples
DCL A(10,10,10),
X1(2,2,2) DEF A,
X2(10,10) DEF A(*,*,5),
X3 DEF A(L,M,N);
X1 is a three-dimensional array that consists of the first two elements of each row,
column and plane of A. X2 is a two-dimensional array that consists of the fifth
plane of A. X3 is an element that consists of the element identified by the subscript
expressions L, M, and N.
DCL B CHAR(10),
Y CHAR(5) DEF B;
Z is an area defined on C.
DCL 1 D UNALIGNED,
2 E,
2 F,
3 G CHAR(10) VAR,
3 H,
1 S UNALIGNED DEF D,
2 T,
2 U,
3 V CHAR(10) VAR,
3 W;
iSUB Defining
With iSUB defining, you can create a defined array that consists of designated
elements from a base array.
The defined and base arrays must be arrays of scalars, can comprise any data
types, and must have identical attributes (apart from the dimension attribute).
The defined variable must have the dimension attribute. In the declaration of the
defined array, the base array must be subscripted, and the subscript positions
cannot be specified as asterisks.
An iSUB variable is a reference, in the subscript list for the base array, to the
dimension of the defined array. At least one subscript in the base array's
subscript-list must be an iSUB expression that, on evaluation, gives the required
subscript in the base array. The value of i ranges from 1 to n, where n is the
number of dimensions in the defined array. The number of subscripts for the base
array must be equal to the number of dimensions for the base array.
An iSUB-defined variable must not appear in the data-list of a GET DATA or PUT
DATA statement.
Examples
DCL A(10,10) FIXED BIN
X(10) FIXED BIN DEF( A(1SUB,1SUB) );
Neither the defined nor the base variable can have the ALIGNED, VARYING, or
VARYING4 attributes.
Both the defined and the base variables must belong to any of the following class:
v The bit class, which consists of the following variables:
Fixed-length bit variables
Aggregates of fixed-length bit variables
v The character class, which consists of the following variables:
Fixed-length character variables
Character pictured and numeric pictured variables
Aggregates of the two above
v The graphic class, which consists of the following variables:
Fixed-length graphic variables
Aggregates of fixed-length graphic variables
v The widechar class, which consists of the following variables:
Fixed-length widechar variables
Aggregates of fixed-length widechar variables
Examples
DCL A CHAR(100),
V(10,10) CHAR(1) DEF A;
POSITION attribute
The POSITION attribute can be used only with string-overlay defining and
specifies the bit, character, graphic or widechar within the base variable at which
the defined variable is to begin.
The expression in the POSITION attribute specifies the position relative to the start
of the base variable. The value specified in the expression can range from 1 to n,
where n is defined as follows:
n = N(b) - N(d) + 1
where N(b) is the number of bits, characters, graphics or widechars in the base
variable, and N(d) is the number of bits, characters, graphics or widechars in the
defined variable.
When the defined variable is a bit class aggregate, the POSITION attribute can
contain only an integer, and the base variable must not be subscripted.
Examples
DCL C(10,10) BIT(1),
X BIT(40) DEF C POS(20);
Z1 is a character string array that consists of all the elements of the decimal
numeric picture E. Z2 is a character string that consists of the elements '999' of the
picture E. Z3 is a character-string array that consists of the elements '9.99' of the
picture E.
DCL A(20) CHAR(10),
B(10) CHAR(5) DEF (A) POSITION(1);
INITIAL attribute
The INITIAL attribute specifies an initial value or values assigned to a variable at
the time storage is allocated for it.
Only one initial value can be specified for an element variable. More than one can
be specified for an array variable. A union variable can be initialized only by
separate initialization of its elementary names, whether they are element or array
variables. A variable that has a defined structure type can be initialized by using
the VALUE type function together with the INITIAL attribute. The INITIAL
attribute cannot be given to constants, defined data, noncontrolled parameters, and
non-LIMITED static entry variables.
INITIAL ( item )
item:
*
initial-constant
reference
(expression)
iteration-specification
iteration-specification:
( iteration-factor ) iteration-item
*
iteration-item:
*
initial-constant
reference
,
( item )
initial-constant:
arithmetic-constant
+
-
bit-constant
character-constant
graphic-constant
entry-constant
file-constant
label-constant
real-constant + imaginary-constant
+ -
-
item:
The following example initializes all of the elements of A to '00'X without the need
for the INITIAL attribute on each element:
dcl 1 A automatic,
2 ...,
2 ...,
2 * char(0) initial call plifill( addr(A), 00X, stg(A) );
If the procedure invoked by the INITIAL CALL statement has been specified in a
FETCH or RELEASE statement and it is not present in main storage, the INITIAL
CALL statement initiates dynamic loading of the procedure. (For more information
about dynamic loading, see Dynamic loading of an external procedure on page
107.)
INITIAL TO
Use only with static native pointers. Specifies that the pointer (or array of
pointers) is initialized with the address of the character string specified in the
INITIAL LIST. Also specifies that the string has the attributes indicated by the
TO keyword.
You should not change a value identified by a pointer initialized with INITIAL TO.
The value can be placed in read-only storage and an attempt to change it could
result in a protection exception. Given the array pdays in the preceding example,
the following assignment is illegal:
dcl x char(30) varz based;
pdays(1)->x = Sonntag;
The initialization of an array of strings can include both string repetition and
iteration factors. Where only one of these is given, it is taken to be a string
repetition factor unless the string constant is placed in parentheses.
The iteration factor can be specified as *, which means that all of the remaining
elements will be initialized with the given value.
The following examples illustrate the use of (and the difference between) string
repetition and iteration factors:
((2)A) is equivalent to (AA)
((2)(A)) is equivalent to (A,A)
((2)(1)A) is equivalent to (A,A)
((*)(1)A) is equivalent to (A,A...A)
An area variable is initialized with the value of the EMPTY built-in function, on
allocation. Any INITIAL clause for an area variable will be ignored.
If the attributes of an item in the INITIAL attribute differ from those of the data
item itself, conversion is performed, provided that the attributes are compatible.
Initializing unions
The members of a union can have initial values. However, if the union is static,
only one member of the union can have the initial attribute. For nonstatic unions,
initial attributes are applied in order of appearance. Subsequent initial values
overwrite previous ones.
In the following example, the declaration for NT1 would be invalid if it had the
static storage attribute.
dcl
1 NT1 union automatic,
2 Numeric_translate_table1 char(256)
init( (256)00X),
2 *,
3 * char(240),
3 * char(10) init(0123456789),
2 * char(0);
dcl
1 NT2 union static,
2 Numeric_translate_table2 char(256),
2 *,
3 * char( rank(0) )
init((1)(low(rank(0))) ),
3 * char(10) init(0123456789),
3 * char( (256-(rank(0))-10) )
init((1)(low( (256-(rank(0))-10) )) ),
The declaration for NT2 is valid even though it has static storage class.
Furthermore, the NT2 declaration is portable between EBCDIC and ASCII modes of
execution.
If static variables are initialized by using the INITIAL attribute, the initial values
must be specified as restricted expressions. Extent specifications must be restricted
expressions.
All initial values must be in the same block as the label declaration.
If the label is an array, it must be completely initialized.
v INITIAL is not valid for AREA variables.
v Only one member of a static union can specify INITIAL.
v If a STATIC EXTERNAL item without the RESERVED attribute is given the
INITIAL attribute in more than one declaration, the value specified must be the
same in every case.
When storage for based variables is allocated through the ALLOCATE or the
AUTOMATIC built-in functions, the initial values are not assigned; for area
variables, the area is not implicitly initialized to EMPTY.
Examples
These examples illustrate how variables are initialized upon allocation.
In the following example, when storage is allocated for Name, the character constant
John Doe (padded on the right to 10 characters) is assigned to it.
dcl Name char(10) init(John Doe);
The following example specifies that A is to be initialized with the value of the
expression B*C:
declare A init((B*C));
The following example results in each of the first 920 elements of A being set to 0.
The next 80 elements consist of 20 repetitions of the sequence 5,5,5,9.
declare A (100,10) initial
((920)0, (20) ((3)5,9));
In the following example, only the first, third, and fourth elements of A are
initialized; the rest of the array is not initialized. The array B is fully initialized,
with the first 25 elements initialized to 0, the next 25 to 1, and the remaining
elements to 0. In the structure C, where the dimension (8) has been inherited by D
and E, only the first element of D is initialized. All the elements of E are initialized.
declare A(15) character(13) initial
(John Doe,
*,
Richard Row,
Mary Smith),
1 C(8),
2 D initial (0),
2 E initial((*)0);
When an array of structures or unions is declared with the LIKE attribute to obtain
the same structuring as a structure or union whose elements have been initialized,
only the first structure or union is initialized.
In the following example only J(1).H and J(1).I are initialized in the array of
structures.
declare 1 G,
2 H initial(0),
2 I initial(0),
1 J(8) like G;
PL/I input and output statements are concerned with the logical organization of a
data set and not with its physical characteristics. A program can be designed
without specific knowledge of the input/output devices that is used when the
program is executed. To allow a source program to deal primarily with the logical
aspects of data rather than with its physical organization in a data set, PL/I
employs models of data sets, called files. A file can be associated with different
data sets at different times during the execution of a program.
It is possible for the same data set to be processed at different times by either
stream or record data transmission. However, all items in the data set must be in
character form.
The following topics discuss the kinds of data sets, the attributes for describing
files, and how you open and close files in order to transmit data. For more
information about the types of data set organizations that PL/I recognizes, refer to
the Programming Guide.
Related information:
Chapter 12, Stream-oriented data transmission, on page 321
This chapter describes the input and output statements used in stream-oriented
data transmission.
Chapter 11, Record-oriented data transmission, on page 311
This chapter describes features of the input and output statements used in
record-oriented data transmission.
Data sets
In addition to being used as input from and output to your terminal, data sets are
stored on a variety of auxiliary storage media, including magnetic tape and
direct-access storage devices (DASDs). Despite their variety, these media have
characteristics that allow common methods of collecting, storing, and transmitting
data. The organization of a data set determines how data is recorded in a data set
and how the data is subsequently retrieved so that it can be transmitted to the
program.
Records are stored in and retrieved from a data set either sequentially on the basis
of successive physical or logical positions, or directly by the use of keys specified
in data transmission statements.
The data set organizations differ in the way they store data and in the means they
use to access data.
Consecutive
In the consecutive data set organization, records are organized solely on the basis
of their successive physical positions.
When the data set is created, records are written consecutively in the order in
which they are presented. The records can be retrieved only in the order in which
they were written.
Indexed
In the indexed data set organization, records are placed in a logical sequence based
on the key of each record.
An indexed data set must reside on a direct-access device. A character string key
identifies the record and allows direct retrieval, replacement, addition, and deletion
of records. Sequential processing is also allowed.
Relative
In the relative data set organization, numbered records are placed in a position
relative to each other.
The records are numbered in succession, beginning with one. A relative data set
must reside on a direct-access device. A key that specifies the record number
identifies the record and allows direct retrieval, replacement, addition, and deletion
of records. Sequential processing is also allowed.
Regional
The regional data set organization is divided into numbered regions, each of which
can contain one record.
The regions are numbered in succession, beginning with zero. A region can be
accessed by specifying its region number, and perhaps a key, in a data
transmission statement. The key specifies the region number and identifies the
region to allow optimized direct retrieval, replacement, addition, and deletion of
records.
Files
To allow a source program to deal primarily with the logical aspects of data rather
than with its physical organization in a data set, PL/I employs models of data sets,
called files.
These models determine how input and output statements access and process the
associated data set. Unlike a data set, a file data item has significance only within
the source program and does not exist as a physical entity external to the program.
FILE attribute
The FILE attribute specifies that the associated name is a file constant or file
variable.
FILE
The FILE attribute can be implied for a file constant by any of the file description
attributes. A name can be contextually declared as a file constant through its
appearance in the FILE option of any input or output statement, or in an ON
statement for any input/output condition.
File constant
Each data set processed by a PL/I program must be associated with a file constant.
The individual characteristics of each file constant are described with file
description attributes. These attributes fall into two categories: alternative attributes
and additive attributes.
Table 43 shows the attributes that apply to each type of data transmission.
Table 43. Attributes by data transmission type
Type of transmission Attribute
Stream-oriented ENVIRONMENT
INPUT and OUTPUT
PRINT
STREAM
Record-oriented BUFFERED and UNBUFFERED
DIRECT and SEQUENTIAL
ENVIRONMENT
INPUT, OUTPUT, and UPDATE
KEYED
RECORD
The FILE attribute can be implied for a file constant by any of the file description
attributes discussed in this chapter. A name can be contextually declared as a file
constant through its appearance in the FILE option of any input or output
statement, or in an ON statement for any input/output condition.
File variable
A file variable has the attributes FILE and VARIABLE. It cannot have any of the
file constant description attributes. File constants can be assigned to file variables.
After assignment, a reference to the file variable has the same significance as a
reference to the assigned file constant.
In the following declaration, Account is declared as a file variable, and Acct1 and
Acct2 are declared as file constants. The file constants can subsequently be
assigned to the file variable.
declare Account file variable,
Acct1 file,
Acc2 file;
On-units can be established for a file constant through a file variable that
represents its value (see ON-units for file variables on page 376). In the
following example, the statements labelled L1 and L2 both specify null ON-units
for the same file.
dcl F file,
G file variable;
G=F;
L1: on endfile(G);
L2: on endfile(F);
STREAM
RECORD
Default: STREAM
RECORD
Indicates that the file consists of a collection of physically separate records,
each of which consists of one or more data items in any form. Each record
is transmitted as an entity to or from a variable.
A file with the RECORD attribute can be specified only in the FILE option
of the OPEN, CLOSE, READ, WRITE, REWRITE, LOCATE, and DELETE
input/output statements.
STREAM
Indicates that the data of the file is a continuous stream of data items, in
character form, assigned from the stream to variables, or from expressions
into the stream.
A file with the STREAM attribute can be specified only in the FILE option
of the OPEN, CLOSE, GET, and PUT input/output statements.
INPUT
OUTPUT
UPDATE
Default: INPUT
INPUT
Specifies that data is transmitted from a data set to the program.
OUTPUT
Specifies that data is transmitted from the program to a data set, either to
create a new data set or to extend an existing one.
UPDATE
Specifies that the data can be transmitted in either direction. The UPDATE
attribute applies to RECORD files only. A declaration of UPDATE for a
SEQUENTIAL file indicates the update-in-place mode.
SEQUENTIAL
DIRECT
Default: SEQUENTIAL
DIRECT
Specifies that records in a data set are directly accessed. The location of the
record in the data set is determined by a character-string key. Therefore,
the DIRECT attribute implies the KEYED attribute. The associated data set
must be on a direct-access storage device.
SEQUENTIAL
Specifies that records in a consecutive or relative data set are accessed in
physical sequence, and that records in an indexed data set are accessed in
key sequence order. For certain data set organizations, a file with the
SEQUENTIAL attribute can also be used for direct access or for a mixture
of random and sequential access. In this case, the file must have the
additive attribute KEYED. Existing records of a data set in a SEQUENTIAL
UPDATE file can be modified, ignored, or, if the data set is indexed,
deleted.
BUFFERED
UNBUFFERED
ENVIRONMENT attribute
The characteristic list of the ENVIRONMENT attribute specifies various data set
characteristics that are not part of PL/I.
For a full list and description of the characteristics and their uses, refer to the
Programming Guide.
Note: Because the characteristics are not part of the PL/I language, using them in
a file declaration can limit the portability of your application program.
KEYED attribute
The KEYED attribute applies only to RECORD files, and must be associated with
indexed and relative data sets. It specifies that records in the file can be accessed
using one of the key options (KEY, KEYTO, or KEYFROM) of record I/O
statements.
KEYED
The KEYED attribute need not be specified unless one of the key options is used.
PRINT attribute
The PRINT attribute applies to files with the STREAM and OUTPUT attributes. It
indicates that the file is intended to be printed; that is, the data associated with the
file is to appear on printed pages, although it can first be written on some other
medium.
PL/I provides two statements, OPEN and CLOSE, to perform these functions.
However, use of these statements is optional. If an OPEN statement is not executed
for a file, the file is opened implicitly during the execution of first data
transmission statement for that file. In this case, the file opening uses information
about the file as specified in a DECLARE statement (and defaults derived from the
transmission statement). Similarly, if a file has not been closed before PL/I
termination, PL/I will close it during the termination process.
When a file for stream input, sequential input, or sequential update is opened, the
associated data set is positioned at the first record.
OPEN statement
The OPEN statement associates a file with a data set. It merges attributes specified
on the OPEN statement with those specified on the DECLARE statement. It also
completes the specification of attributes for the file, if a complete set of attributes
has not been declared for the file being opened.
OPEN options-group ;
options-group:
STREAM INPUT
FILE(file-reference)
RECORD OUTPUT
UPDATE
BUFFERED
SEQUENTIAL
UNBUFFERED
UNBUFFERED KEYED PRINT
DIRECT
BUFFERED
TITLE(expression) LINESIZE(expression) PAGESIZE(expression)
TITLE
The content of expression determines what is being designated. For more
information about the TITLE attribute, refer to the Programming Guide.
LINESIZE
Converted to an integer value, specifies the length in bytes of a line during
subsequent operations on the file. New lines can be started by use of the
printing and control format items or by options in a GET or PUT statement. If
an attempt is made to position a file past the end of a line before explicit
action to start a new line is taken, a new line is started, and the file is
positioned to the start of this new line. The default line size for PRINT file is
120.
The LINESIZE option can be specified only for a STREAM OUTPUT file.
PAGESIZE
Is evaluated and converted to an integer value, and specifies the number of
lines per page. The first attempt to exceed this limit raises the ENDPAGE
condition. During subsequent transmission to the PRINT file, a new page can
be started by use of the PAGE format item or by the PAGE option in the PUT
statement. The default page size is 60.
The PAGESIZE option can be specified only for a file having the PRINT
attribute.
Implicit opening
An implicit opening of a file occurs when a GET, PUT, READ, WRITE, LOCATE,
REWRITE, or DELETE statement is executed for a file for which an OPEN
statement has not already been executed.
If a GET statement contains a COPY option, execution of the GET statement can
cause implicit opening of either the file specified in the COPY option, or, if no file
was specified, the output file SYSPRINT. Implicit opening of the file specified in
the COPY option implies the STREAM and OUTPUT attributes.
Table 45 shows the attributes that are implied when a given statement causes the
file to be implicitly opened.
Table 45. Attributes implied by implicit open
Statement Implied attributes
GET STREAM, INPUT
PUT STREAM, OUTPUT
READ RECORD, INPUTNote
WRITE RECORD, OUTPUTNote
LOCATE RECORD, OUTPUT, SEQUENTIAL
REWRITE RECORD, UPDATE
DELETE RECORD, UPDATE
Note: INPUT and OUTPUT are default attributes for READ and WRITE statements only if
UPDATE has not been explicitly declared.
There must be no conflict between the attributes specified in a file declaration and
the attributes implied as the result of opening the file. For example, the attributes
INPUT and UPDATE are in conflict, as are the attributes UPDATE and STREAM.
The implied attributes are applied before the default attributes that are listed in
Table 42 on page 300 are applied. Implied attributes can also cause a conflict. If a
conflict in attributes exists after the application of default attributes, the
UNDEFINEDFILE condition is raised.
Table 46. Merged and implied attributes
Merged attributes Implied attributes
UPDATE RECORD
SEQUENTIAL RECORD
DIRECT RECORD, KEYED
PRINT OUTPUT, STREAM
KEYED RECORD
Attributes after merge caused by execution of the OPEN statement are STREAM
and PRINT. Attributes after implication are STREAM, PRINT, and OUTPUT.
Attributes after default application are STREAM, PRINT, OUTPUT, and
EXTERNAL.
Account = Acct1;
open file(Account) print;
Account = Acct2;
open file(Account) record unbuf;
The file Acct1 is opened with attributes (explicit and implied) STREAM,
EXTERNAL, PRINT, and OUTPUT. The file Acct2 is opened with attributes
RECORD, EXTERNAL, and OUTPUT.
Attributes after merge (from the implicit opening caused by execution of the READ
statement) are KEYED, INTERNAL, RECORD, and INPUT. (No additional
attributes are implied.) Attributes after default application are KEYED, INTERNAL,
RECORD, INPUT, and SEQUENTIAL.
For the previous declaration, all necessary attributes are either stated or implied in
the DECLARE statement. None of the stated attributes can be changed (or
overridden) in an OPEN statement.
In the following example, the file attributes are the same as those specified (or
implied) in the DECLARE statement in the previous example.
open file (Invntry)
update sequential;
The file might be opened in this way, then closed, and then later opened with a
different set of attributes. For example, the following OPEN statement allows
records to be read with either the KEYTO or the KEY option.
open file (Invntry)
input sequential keyed;
Because the file is SEQUENTIAL, the data set can be accessed in a purely
sequential manner. It can also be accessed directly by means of a READ statement
with a KEY option. A READ statement with a KEY option for a file of this
description obtains a specified record. Subsequent READ statements without a KEY
option access records sequentially, beginning with the next record in KEY
sequence.
CLOSE statement
The CLOSE statement dissociates an opened file from its data set.
FILE
Specifies the name of the file that is dissociated from the data set. CLOSE
FILE(*) closes all open files.
The CLOSE statement also dissociates from the file all attributes established for it
by the implicit or explicit opening process. If desired, new attributes can be
specified for the file in a subsequent OPEN statement. However, all attributes
explicitly given to the file constant in a DECLARE statement remain in effect.
Closing a file that was previously closed has no effect. A closed file can be
reopened. If a file is not closed by a CLOSE statement, it is closed at the
termination of the program.
FLUSH statement
The FLUSH statement can be used to flush one or all files.
FLUSH FILE(file-reference) ;
FILE(*)
FILE
Specifies the name of the output file.
The FLUSH statement flushes the buffers associated with an open output file (or
with all open output files if * is specified). This normally happens when the file is
closed or when the program ends, but the FLUSH statement ensures that the
buffers are flushed before any other processing occurs.
For SYSIN, the default attributes are STREAM INPUT, and for SYSPRINT they are
STREAM OUTPUT PRINT. Both file names, SYSIN and SYSPRINT, have the
default attribute EXTERNAL, even though SYSPRINT contains more than 7
characters.
The compiler does not reserve the names SYSIN and SYSPRINT for the specific
purposes described above. They can be used for other purposes besides identifying
SYSIN and SYSPRINT files. Other attributes can be applied to them, but the PRINT
attribute is applied by default to SYSPRINT when it is declared or opened as a
STREAM OUTPUT file unless the INTERNAL attribute is declared for it.
Data transmitted
Most variables, including parameters and DEFINED variables, can be transmitted
by record-oriented data transmission statements. In general, the information given
in this chapter can be applied equally to all variables.
A locate mode output statement (see LOCATE statement on page 314) specifying
a varying length string transmits a field having a length equal to the maximum
length of the string. For VARYINGZ strings, the null terminator is also transmitted.
For VARYING strings, a 2-byte prefix denoting the current length of the string is
also transmitted; for this, the SCALARVARYING option of the ENVIRONMENT
attribute must be specified for the file.
A move mode output statement (see WRITE statement on page 313 and
REWRITE statement on page 313) specifying a varying length string variable
transmits only the current length of the string. For VARYINGZ strings, the null
terminator is also transmitted. For VARYING strings, a 2-byte prefix is included
only if the SCALARVARYING option of the ENVIRONMENT attribute is specified
for the file.
Area variables
A locate mode output statement specifying an area variable transmits a field whose
length is the declared size of the area, plus a 16-byte prefix containing control
information.
The DELETE statement deletes records from an UPDATE file. The attributes of the
file determine which data transmission statements can be used. Statement options
are described in Options of data transmission statements on page 314. For
information about variables in data transmission statements, see the Programming
Guide.
READ statement
The READ statement can be used with any INPUT or UPDATE file. It either
transmits a record from the data set to the program variable or sets a pointer to the
record in storage.
IGNORE (expression)
READ FILE (file-reference)
INTO(ref)
KEY(expression)
KEYTO(reference)
SET(pointer-ref)
KEY(expression)
KEYTO(reference)
The keywords can appear in any order. A READ statement without an INTO, SET,
or IGNORE option is equivalent to a READ with an IGNORE(1).
WRITE statement
The WRITE statement can be used with SEQUENTIAL UPDATE files (if VSAM),
with DIRECT UPDATE files, and with any OUTPUT file. It transmits a record from
the program and adds it to the data set.
;
KEYFROM(expression)
KEYTO(reference)
Also, if you want to add records to the end of an existing sequential file, the file
must be opened as OUTPUT, and you must specify either DISP=MOD in its DD
statement (if your program is running under z/OS batch) or APPEND(Y) in its
environment variable (if your program is running under Windows, AIX, or z/OS
UNIX).
REWRITE statement
The REWRITE statement replaces a record in an UPDATE file.
For SEQUENTIAL UPDATE files, the REWRITE statement specifies that the last
record read from the file is rewritten; consequently a record must be read before it
can be rewritten. For DIRECT UPDATE files, any record can be rewritten whether
or not it has first been read.
;
KEY (expression)
The keywords can appear in any order. The FROM option must be specified for
UPDATE files with the DIRECT attribute, or with both the SEQUENTIAL and
UNBUFFERED attributes.
A REWRITE statement that does not specify the FROM option has the following
effect:
v If the last record was read by a READ statement with the INTO option,
REWRITE without FROM has no effect on the record in the data set.
v If the last record was read by a READ statement with the SET option, the record
is updated by whatever assignments were made in the variable identified by the
pointer variable in the SET option.
LOCATE statement
The LOCATE statement can be used only with an OUTPUT SEQUENTIAL
BUFFERED file for locate mode processing. It allocates storage within an output
buffer for a based variable and sets a pointer to the location of the next record.
For further description of locate mode processing, see Locate mode on page 318.
;
SET (pointer-reference) KEYFROM (expression)
DELETE statement
The DELETE statement deletes a record from an UPDATE file.
The keywords can appear in any order. If the KEY option is omitted, the record to
be deleted is the last record that is read. No subsequent DELETE or REWRITE
statement without a KEY is allowed until another READ statement is processed. If
the KEY option is included, that record addressed by the key is deleted if found.
FILE option
The FILE option must appear in every record-oriented data transmission statement.
It specifies the file upon which the operation takes place.
An example of the FILE option is shown in each of the statements in this section. If
the file specified is not open in the current process, it is opened implicitly.
FROM option
The FROM option specifies the element or aggregate variable from which the
record is written. The FROM option must be used in the WRITE statement for any
OUTPUT or DIRECT UPDATE file. It can also be used in the REWRITE statement
for any UPDATE file.
The FROM variable can be an element string variable of varying length. When a
WRITE statement is specified with the FROM option, only the current length of a
varying length string is transmitted to a data set. For a VARYINGZ string, the null
terminator is attached and also transmitted. For a VARYING string, a 2-byte prefix
specifying the length is attached only if the SCALARVARYING option of the
ENVIRONMENT attribute is specified for the file.
The FROM option can be omitted from a REWRITE statement for SEQUENTIAL
UPDATE files. If the last record was read by a READ statement with the INTO
option, REWRITE without FROM has no effect on the record in the data set. If the
last record was read by a READ statement with the SET option, the record
(updated by whatever assignments were made) is copied back onto the data set.
In the following examples, the statements specify that the value of the variable
Mas_Rec is written into the output file Master.
write file (Master) from (Mas_Rec);
The REWRITE statement specifies that Mas_Rec replaces the last record read from
an UPDATE file.
rewrite file (Master) from (Mas_Rec);
IGNORE option
The IGNORE option can be used in a READ statement for any SEQUENTIAL
INPUT or SEQUENTIAL UPDATE file.
The following example specifies that the next three records in the file are to be
ignored:
read file (In) ignore (3);
INTO option
The INTO option specifies an element or aggregate variable into which the logical
record is read.
The INTO option can be used in the READ statement for any INPUT or UPDATE
file.
The INTO variable can be an element string variable of varying length. For
VARYINGZ strings, each record contains a null terminator. For VARYING strings,
if the SCALARVARYING option of the ENVIRONMENT attribute was specified for
the file, each record contains a 2-byte prefix that specifies the length of the string
data.
The following example specifies that the next sequential record is read into the
variable RECORD_1:
read file (Detail) into (Record_1);
KEY option
The KEY option specifies a character, graphic, or widechar key that identifies a
record. It can be used in a READ statement for an INPUT or UPDATE file, or in a
REWRITE statement for a DIRECT UPDATE file.
The KEY option applies only to KEYED files. The KEY option is required if the file
has the DIRECT attribute, and is optional if the file has the SEQUENTIAL and
KEYED attributes.
The expression in the KEY option is evaluated, and if it is not character, graphic, or
widechar, the expression is converted to a character value that represents a key. It
is this character, graphic, or widechar value that determines which record is read.
The following example specifies that the record identified by the character value of
the variable Stkey is read into the variable Item:
read file (Stpck) into (Item) key (Stkey);
KEYFROM option
The KEYFROM option specifies a character, graphic, or widechar key that
identifies the record on the data set to which the record is transmitted. It can be
used in a WRITE statement for any KEYED OUTPUT or DIRECT UPDATE file, or
in a LOCATE statement.
The KEYFROM option applies only to KEYED files. The expression is evaluated,
and if it is not character, graphic, or widechar, the expression is converted to a
character string and is used as the key of the record when it is written.
Relative data sets can be created by using the KEYFROM option. The record
number is specified as the key.
REGIONAL(1) data sets can be created by using the KEYFROM option. The region
number is specified as the key.
For indexed data sets, KEYFROM specifies a recorded key whose length must be
equal to the key length specified for the data set.
The following example specifies that the value of Loanrec is written as a record in
the file Loans, and that the character string value of Loanno is used as the key with
which it can be retrieved:
write file (Loans) from (Loanrec) keyfrom (Loanno);
KEYTO option
The KEYTO option specifies the character, graphic, or widechar variable to which
the key of a record is assigned.
The KEYTO option can specify any string pseudovariable other than STRING. It
cannot specify a variable declared with a numeric picture specification. The
KEYTO option can be used in a READ statement for a SEQUENTIAL INPUT or
SEQUENTIAL UPDATE file.
The KEY condition is not raised for this type of padding or truncation.
The following example specifies that the next record in the file Detail is read into
the variable Invntry, and that the key of the record is assigned to the variable
Keyfld:
read file (Detail) into (Invntry) keyto (Keyfld);
SET option
The SET option can be used with a READ statement or a LOCATE statement. For
the READ statement, it specifies a pointer variable that is set to point to the record
read. For the LOCATE statement, it specifies a pointer variable that is set to point
to the next record for output.
If the SET option is omitted for the LOCATE statement, the pointer declared with
the record variable is set. If a VARYING string is transmitted, the
SCALARVARYING option must be specified for the file.
The following example specifies that the value of the pointer variable P is set to the
location in the buffer of the next sequential record:
read file (X) set (P);
Processing modes
Record-oriented data transmission has two modes of handling data.
Move mode
Processes data by moving it into or out of the variable.
Locate mode
Processes data while it remains in a buffer. The execution of a data
transmission statement assigns a pointer variable for the location of the
storage allocated to a record in the buffer. Locate mode is applicable only
to BUFFERED files.
The data transmission statements and options that you specify determine the
processing mode used.
Move mode
In move mode, a READ statement transfers a record from the data set to the
variable named in the INTO option.
A WRITE or REWRITE statement transfers a record from the variable named in the
FROM option to the data set. The variables named in the INTO and FROM options
can be of any storage class.
Locate mode
Locate mode assigns to a pointer variable the location of the buffer.
A based variable described the record. The same data can be interpreted in
different ways by using different based variables. Locate mode can also be used to
read self-defining records, in which information in one part of the record is used to
indicate the structure of the rest of the record. For example, this information could
be an array bound or a code identifying which based structure should be used for
the attributes of the data.
A READ statement with a SET option sets the pointer variable in the SET option to
a buffer containing the record. The data in the record can then be referenced by a
based variable qualified with the pointer variable.
The pointer value is valid only until the execution of the next READ or CLOSE
statement that refers to the same file.
The pointer variable specified in the SET option or, if SET was omitted, the pointer
variable specified in the declaration of the based variable, is used. The pointer
value is valid only until the execution of the next LOCATE, WRITE, or CLOSE
statement that refers to the same file. It also initializes components of the based
variable that have been specified in REFER options.
The LOCATE statement sets a pointer variable to a large enough area where the
next record can be built.
After execution of the LOCATE statement, values can be assigned directly into the
based variables qualified by the pointer variable set by the LOCATE statement.
Example 1
on endfile(In);
read file(In) set(P);
do while (endfile(In));
.
.
.
/* process record */
read file(In) set(P);
end;
Example 2
do while (More_records_to_write);
locate Data file(Out);
.
.
. /* build record */
end;
The stream-oriented data transmission statements can also be used for internal
data movement, by specifying the STRING option instead of specifying the FILE
option. Although the STRING option is not an input/output operation, its use is
described in this chapter.
The following sections provide details about the data transmission statements and
their options, and give instructions on how to specify the list-, data-, and
edit-directed data. For information about how to accommodate double-byte
characters, see DBCS data in stream I/O on page 342.
The variables or pseudovariables to which data values are assigned, and the
expressions from which they are transmitted, are generally specified in a
data-specification with each GET or PUT statement. The statements can also
Copyright IBM Corp. 1999, 2016 321
Data transmission statements
include options that specify the origin or destination of the data values or indicate
where they appear in the stream relative to the preceding data values. Options for
the stream-data transmission statements are described in Options of data
transmission statements on page 323.
GET statement
The GET statement is a STREAM input data transmission statement that can assign
data values either from a data set to one or more variables or from a string to one
or more variables.
For a stream input file, use the following syntax for the GET statement.
GET
FILE (expression) data-specification
;
COPY SKIP
(file-reference) (expression)
The keywords can appear in any order. The data specification must appear unless
the SKIP option is specified.
For transmission from a string, use this syntax for the GET statement.
PUT statement
The PUT statement is a STREAM output data transmission statement that can
transmit values to a stream output file or assign values to a character variable.
Use the following syntax of the PUT statement when dealing with stream output
files.
PUT
FILE (file-reference) data-specification
;
PAGE
LINE (expression)
SKIP
(expression)
LINE (expression)
The keywords can appear in any order. The data specification can be omitted only
if one of the control options (PAGE, SKIP, or LINE) appears.
For transmission to a character string, however, use this syntax of the PUT
statement.
COPY option
The COPY option specifies that the source data stream is written on the specified
STREAM OUTPUT file without alteration.
If no file reference is given, the default is the output file SYSPRINT. Each new
record in the input stream starts a new record on the COPY file. Consider the
following example:
get file(sysin) data(A,B,C) copy(DPL);
The statement not only transmits the values assigned to A, B, and C in the input
stream to the variables with these names, but also writes them exactly as they
appear in the input stream on the file DPL. Data values that are skipped on input,
and not transmitted to internal variables, copy intact into the output stream.
If the COPY option file is not open in the current program, the file is implicitly
opened in the program for stream output transmission.
( data-list )
LIST
DATA
,
( data-list-item )
data-list:
data-list item
( data-list type-3-DO )
format-list:
format-item
n format-item
n (format-list)
If a GET or PUT statement includes a data list that is not preceded by one of the
keywords LIST, DATA, or EDIT, LIST is the default.
Important: In a statement without LIST, DATA, or EDIT preceding the data list,
the data list must immediately follow the GET or PUT keyword. Any options
required must be specified after the data list.
DATA
See Data-directed data specification on page 329.
EDIT
See Edit-directed data specification on page 333.
LIST
See List-directed data specification on page 338.
data-list item
On input, a data-list item for edit-directed and list-directed transmission can be
an element, an array, or a structure variable. For a data-directed data
specification, a data-list item can be an element, an array, or a structure
variable. None of the names in a data-directed data list can be subscripted or
locator-qualified. However, qualified (that is, structure-member) or
string-overlay-defined names are allowed.
On output, a data list item for edit-directed and list-directed data specifications
can be an element expression, an array expression, or a structure expression.
For a data-directed data specification, a data-list item can be an element, an
array, or a structure variable. It must not be locator-qualified. It can be
qualified (that is, a member of a structure) or string-overlay-defined.
The data types of a data-list item can be any computational data (as long it
does not have the CONSTANT or VALUE attribute), and in PUT statements,
the data type may also be POINTER. If the data type is non-computational, the
contents of the item will be transmitted as if the item had been specified by
applying the HEX built-in function applied to the item (and for PUT DATA,
the hex value will be enclosed in quotation marks followed by a suffix of BX).
An array or structure variable in a data-list is equivalent to n items in the data
list, where n is the number of element items in the array or structure. For
edit-directed transmission, each element item is associated with a separate use
of a data-format item.
data-list type-3-DO
The syntax for the Type 3 DO specification is described under DO statement
on page 223. Data list items with Type 3 DO specifications are not allowed in
data-directed data lists for GET statements.
When the last repetitive specification is completed, processing continues with
the next data-list item.
Each repetitive specification must be enclosed in parentheses, as shown in the
syntax diagram. If a data specification contains only a repetitive specification,
two sets of outer parentheses are required, because the data list is enclosed in
parentheses and the repetitive specification must have a separate set.
When repetitive specifications are nested, the rightmost DO is at the outer level
of nesting. Consider the following example:
get list (((A(I,J)
do I = 1 to 2)
do J = 3 to 4));
There are three sets of parentheses, in addition to the set used to delimit the
subscripts. The outermost set is the set required by the data specification. The
next set is that required by the outer repetitive specification. The third set of
parentheses is required by the inner repetitive specification.
This statement is equivalent in function to the following nested do-groups:
do J = 3 to 4;
do I = 1 to 2;
get list (A (I,J));
end;
end;
It assigns values to the elements of the array A in the following order:
A(1,3), A(2,3), A(1,4), A(2,4)
format list
For a description of the format list, see Edit-directed data specification on
page 333.
FILE option
The FILE option specifies the file upon which the operation takes place. It must be
a STREAM file.
For information about how to declare a file type data item, see Files on page 299.
If neither the FILE option nor the STRING option appears in a GET statement, the
input file SYSIN is the default; if neither option appears in a PUT statement, the
output file SYSPRINT is the default.
LINE option
The LINE option can be specified only for PRINT files. The LINE option defines a
new current line for the data set.
The expression is evaluated and converted to an integer value, n. The new current
line is the nth line of the current page. If at least n lines have already been written
on the current page or if n exceeds the limits set by the PAGESIZE option of the
OPEN statement, the ENDPAGE condition is raised. If n is less than or equal to
zero, a value of 1 is used. If n specifies the current line, ENDPAGE is raised except
when the file is positioned on column 1, in which case the effect is the same as if a
SKIP(0) option were specified.
The LINE option takes effect before the transmission of any values defined by the
data specification (if any). If both the PAGE option and the LINE option appear in
the same statement, the PAGE option is applied first. Consider the following
example:
put file(List) data(P,Q,R) line(34) page;
For the effect of the LINE option when specified in the first GET statement
following the opening of the file, see OPEN statement on page 305.
For output to a terminal in interactive mode, the LINE option skips three lines.
PAGE option
The PAGE option can be specified only for PRINT files. It defines a new current
page within the data set.
If PAGE and LINE appear in the same PUT statement, the PAGE option is applied
first. The PAGE option takes effect before the transmission of any values defined
by the data specification (if any).
The page remains current until the execution of a PUT statement with the PAGE
option, until a PAGE format item is encountered, or until the ENDPAGE condition
is raised, resulting in the definition of a new page. A new current page implies line
one.
For output to a terminal in interactive mode, the PAGE option skips three lines.
SKIP option
The SKIP option specifies a new current line (or record) within the data set.
The expression is evaluated and converted to an integer value, n. The data set is
positioned to the start of the nth line (record) relative to the current line (record). If
expression is not specified, the default is SKIP(1).
The SKIP option takes effect before the transmission of values defined by the data
specification (if any). Consider the following example:
This statement prints the values of the variables X, Y, and Z on the output file
SYSPRINT commencing on the third line after the current line.
For non-PRINT files and input files, if the expression in the SKIP option is less
than or equal to zero, a value of 1 is used. For PRINT files, if n is less than or
equal to zero, the positioning is to the start of the current line.
For the effect of the SKIP option when specified in the first GET statement
following the opening of the file, see OPEN statement on page 305.
If fewer than n lines remain on the current page when a SKIP(n) is issued,
ENDPAGE is raised.
STRING option
The STRING option in GET and PUT statements transmits data between main
storage locations rather than between the main and a data set. DBCS data items
cannot be used with the STRING option.
The GET statement with the STRING option specifies that data values assigned to
the data list items are obtained from the expression, after conversion to character
string. Each GET operation using this option always begins at the leftmost
character position of the string. If the number of characters in this string is less
than the total number of characters specified by the data specification, the ERROR
condition is raised.
The PUT statement with the STRING option specifies that values of the data-list
items are to be assigned to the specified character variable or pseudovariable. The
PUT operation begins assigning values at the leftmost character position of the
string, after appropriate conversions are performed. Blanks and delimiters are
inserted as in normal I/O operations. If the string is not long enough to
accommodate the data, the ERROR condition is raised.
The NAME condition is not raised for a GET DATA statement with the STRING
option. Instead, the ERROR condition is raised for situations that raise the NAME
condition for a GET DATA statement with the FILE option.
The STRING option is most useful with edit-directed transmission. It allows data
gathering or scattering operations performed with a single statement, and it allows
stream-oriented processing of character strings that are transmitted by
record-oriented statements.
The READ statement reads a record from the input file Inputr. The first GET
statement uses the STRING option to extract the code from the first byte of the
record and assigns it to Code. If the code is 1, the second GET statement uses the
STRING option to assign the values in the record to X, Y, and Z. The second GET
statement specifies that the first character in the string Temp is ignored (the X(1)
format item in the format list). This ignored character is the same one assigned to
Code by the first GET statement.
The PUT statement specifies, by the X(1) spacing format item, that the first
character assigned to the character variable is a single blank, which is the ANS
vertical carriage positioning character that specifies a single space before printing.
Following that, the values of the variables Name and Pay# and of the expression
Hours*Rate are assigned. The WRITE statement specifies that record transmission is
used to write the record into the file Outprt.
The variable referenced in the STRING option should not be referenced by name or
by alias in the data list. Consider the following example:
declare S char(8) init(YYMMDD);
put string (S) edit
(substr (S, 3, 2), /,
substr (S, 5, 2), /,
substr (S, 1, 2))
(A);
The value of S after the PUT statement is 'MM/bb/MM' and not 'MM/DD/YY'
because S is blanked after the first data item is transmitted. The same effect is
obtained if the data list contains a variable based or defined on the variable
specified in the STRING option.
If a data-list item is of complex mode, the real part is transmitted before the
imaginary part.
If a data-list item is an array expression, the elements of the array are transmitted
in row-major order; that is, with the rightmost subscript of the array varying most
frequently.
Example 1
declare 1 A (10),
2 B,
2 C;
put file(X) list(A);
Example 2
When this statement is executed, values are transmitted and assigned in the
following order:
1. A new value is assigned to N.
2. Elements are assigned to the array X as specified in the repetitive specification
in the order X(1),X(2),...X(N), with the new value of N specifying the
number of assigned items.
3. A new value is assigned to J.
4. A new value is assigned to K.
For a description of the syntax of the DATA data specification, see Data
specification options on page 324.
,
b
element-variable = data-value ;
Each data-value in the stream has one of the syntaxes described for list-directed
transmission. For a description of list-directed transmission syntax, see Syntax of
list-directed data on page 338.
The length of the data value in the stream is a function of the attributes declared
for the variable and, because the name is also included, the length of the fully
qualified subscripted name. The length for output items converted from coded
arithmetic data, numeric character data, and bit-string data is the same as that for
list-directed output data, and is governed by the rules for data conversion to
character type as described in Chapter 4, Data conversion, on page 77.
GET data-directed
This topic provides information about using the GET statement for data-directed
data transmission.
If a data list is used, each data-list item must be an element, array, or structure
variable. Names cannot be subscripted, but qualified names are allowed in the data
list. All names in the stream should appear in the data list; however, the order of
the names need not be the same, and the data list can include names that do not
appear in the stream.
If the data list contains a name that is not included in the stream, the value of the
named variable remains unchanged.
For example, consider the following data list, where A, B, C, and D are names of
element variables:
Data (B, A, C, D)
This data list can be associated with the following input data stream:
A= 2.5, B= .0047, D= 125, Z= ABC;
Because C appears in the data list but not in the stream, its value remains
unaltered. Z, which is not in the data list, raises the NAME condition.
If the data list includes the name of an array, subscripted references to that array
can appear in the stream although subscripted names cannot appear in the data
list. The entire array need not appear in the stream; only those elements that
actually appear in the stream are assigned. If a subscript is out of range, or is
missing, the NAME condition is raised.
Although the data list has only the name of the array, the input stream can contain
values for individual elements of the array. In this case, only three elements are
assigned; the remainder of the array is unchanged.
If the data list includes the names of structures, minor structures, or structure
elements, fully qualified names must appear in the stream, although full
qualification is not required in the data list. Consider the following example:
dcl 1 In,
2 Partno,
2 Descrp,
2 Price,
3 Retail,
3 Whsl;
If it is desired to read a value for In.Price.Retail, the input data stream must
have the following form:
In.Price.Retail=1.23;
PUT data-directed
This topic provides information about using the PUT statement for data-directed
data transmission.
A semicolon is written into the stream after the last data item transmitted by each
PUT statement.
Names are transmitted as a mixed string, which can contain SBCS characters,
DBCS characters, or both. Any SBCS characters expressed in DBCS form are first
translated to SBCS. For example, put data (<.A>B<.Ckk>); will be transmitted as
follows:
ABC<kk>=value-of-variable
Data-directed output is not valid for subsequent data-directed input when the
character-string value of a numeric character variable does not represent a valid
optionally signed arithmetic constant or a complex expression.
For character data, the contents of the character string are written out enclosed in
quotation marks. Each quotation mark contained within the character string is
represented by two successive quotation marks.
Example 1
The following example shows data-directed transmission (both input and output).
declare (A(6), B(7)) fixed;
get file (X) data (B);
do I = 1 to 6;
A (I) = B (I+1) + B (I);
end;
put file (Y) data (A);
Input stream:
B(1)=1, B(2)=2, B(3)=3,
B(4)=1, B(5)=2, B(6)=3, B(7)=4;
Output stream:
A(1)= 3 A(2)= 5 A(3)= 4 A(4)= 3
A(5)= 5 A(6)= 7;
Example 2
dcl 1 A,
2 B FIXED,
2 C,
3 D FIXED;
A.B = 2;
A.D = 17;
put data (A);
For information about the syntax of the EDIT data specification, see Data
specification options on page 324.
format-item
n format-item
n (format-list)
The first data-format item is associated with the first data-list item, the second
data-format item with the second data-list item, and so on. If a format list contains
fewer data-format items than there are items in the associated data list, the format
list is reused. If there are excessive format items, they are ignored.
Suppose a format list contains five data-format items and its associated data list
specifies ten items to be transmitted. The sixth item in the data list is associated
with the first data-format item, and so forth. Suppose a format list contains ten
data-format items and its associated data list specifies only five items. The sixth
through the tenth format items are ignored.
The PAGE and LINE control-format items can be used only with PRINT files and,
consequently, can appear only in PUT statements. The SKIP, COLUMN, and
X-format items apply to both input and output.
The PAGE, SKIP, and LINE format items have the same effect as the corresponding
options of the PUT statement (and of the GET statement, in the case of SKIP),
except that the format items take effect when they are encountered in the format
list, while the options take effect before any data is transmitted.
The COLUMN format item cannot be used in a GET STRING or PUT STRING
statement.
For the effects of control-format items when they are specified in the first GET or
PUT statement following the opening of a file, see OPEN statement on page 305.
A value read into a variable can be used in a format item that is associated with
another variable later in the data list.
get edit (M,String_A,I,String_B)(F(2),A(M),X(M),F(2),A(I));
In this example, the first two characters are assigned to M. The value of M specifies
the number of characters assigned to String_A and the number of characters being
ignored before two characters are assigned to I, whose value is used to specify the
number of characters assigned to String_B.
The transmission is complete when the last data-list item has been processed.
Subsequent format items, including control-format items, are ignored.
GET edit-directed
This topic provides information about using the GET statement for edit-directed
data transmission.
All blanks and quotation marks are treated as characters in the stream. Strings
should not be enclosed in quotation marks. Quotation marks should not be
doubled. The letter B should not be used to identify bit strings or G to identify
graphic strings. If characters in the stream cannot be interpreted in the manner
specified, the CONVERSION condition is raised.
Example
get edit (Name, Data, Salary)(A(N), X(2), A(6), F(6,2));
v The first N characters in the stream are treated as a character string and assigned
to Name.
v The next two characters are skipped.
v The next six characters are assigned to Data in character format.
v The next six characters are considered an optionally signed decimal fixed-point
constant and are assigned to Salary.
Related information:
GET statement on page 322
The GET statement is a STREAM input data transmission statement that can assign
data values either from a data set to one or more variables or from a string to one
or more variables.
PUT edit-directed
In edit-directed data transmission, the value of each data-list item is converted to
the character or graphic representation specified by the associated data-format item
and placed in the stream in a field whose width also is specified by the format
item. When the data list has been processed, execution of the PUT statement stops
and any remaining format items are not processed.
On output, binary items are converted to decimal values and the associated F- or
E-format items must state the field width and point placement in terms of the
converted decimal number. For the P-format these are specified by the picture
specification.
On output, blanks are not inserted to separate data values in the output stream.
String data is left-adjusted in the field to the width specified. Arithmetic data is
right-adjusted. Because of the rules for conversion of arithmetic data to character
type, which can cause up to 3 leading blanks to be inserted (in addition to any
blanks that replace leading zeros), generally there is at least 1 blank preceding an
arithmetic item in the converted field. Leading blanks do not appear in the stream,
however, unless the specified field width allows for them. Truncation, due to
inadequate field-width specification, is on the left for arithmetic items, and on the
right for string items. SIZE or STRINGSIZE is raised if truncation occurs.
Example 1
put edit(Inventory={Inum,Invcode)(A,F(5));
This example specifies that the character string Inventory= is concatenated with
the value of Inum and placed in the stream in a field whose width is the length of
the resultant string. Then, the value of Invcode is converted to character, as
described by the F-format item, and placed in the stream right-adjusted in a field
with a width of five characters (leading characters can be blanks).
Example 2
The following example shows the use of the COLUMN, LINE, PAGE, and SKIP
format items in combination with one another:
put edit (Quarterly Statement)
(page, line(2), A(19))(Acct#, Bought, Sold, Payment, Balance)
(skip(3), A(6), column(14), F(7,2), column(30), F(7,2),
column(45), F(7,2), column(60), F(7,2));
1. The heading Quarterly Statement is written on line two of a new page in the
output file SYSPRINT.
2. Two lines are skipped. The next line in the output is the third line following the
heading, or the fifth line of the report.
3. The following values are written:
Acct#, beginning at character position 1
Bought, beginning at character position 14
Sold, beginning at character position 30
Payment, beginning at character position 45
Balance at character position 60.
Example 3
In the following example, the value of Name is inserted in the stream as a character
string left-adjusted in a field of N characters.
put edit (Name,Number,City) (A(N),A(N-4),A(10));
FORMAT statement
The FORMAT statement specifies a format list that can be used by edit-directed
data transmission statements to control the format of the data being transmitted.
label
Same as the label-reference of the remote-format item R. See R-format item
on page 352.
format list
Specified as described in Edit-directed data specification on page 333.
A GET or PUT EDIT statement can include an R-format item in its format-list
option. That portion of the format list represented by the R-format item is supplied
by the identified FORMAT statement.
For information about the syntax of the LIST data specification, see Data
specification options on page 324.
list ((Thickness(Distance)
do Distance = 1 to 1000))
list (P, Z, M, R)
The specification in the last example can be used only for output, because it
contains expressions. These expressions are evaluated when the statement is
executed, and the result is placed in the stream.
arithmetic-constant
+
-
real-constant + imaginary-constant
+ -
-
character-constant
bit-constant
graphic-constant
String repetition factors are not allowed. A blank must not follow a sign preceding
a real constant, and must not precede or follow the central positive (+) or negative
(-) symbol in complex expressions.
The length of the data value in the stream is a function of the attributes of the data
value, including precision and length. Detailed discussions of the conversion rules
and their effect upon precision are listed in the descriptions of conversion to
character type in Chapter 4, Data conversion, on page 77.
GET list-directed
This topic provides information about using the GET statement for list-directed
data transmission.
If the items are separated by a comma, the first character scanned when the next
GET statement is executed is the one immediately following the comma:
Xbb,bbbXX
If the items are separated by blanks only, the first item scanned is the next
nonblank character:
XbbbbXXX
If the end-of-record is encountered, the file is positioned at the end of the record:
XbbbbXXX
If the record does terminate with a comma, the next record is not read until the
next GET statement requires it.
If the data is a character constant, the surrounding quotation marks are removed,
and the enclosed characters are interpreted as a character string. A double
quotation mark is treated as a single quotation mark.
If the data is a bit constant, the enclosing quotation marks and the trailing
character B are removed, and the enclosed characters are interpreted as a bit string.
If the data is a hexadecimal constant (X, BX, B4, GX), the enclosing quotation
marks and the suffix are removed, and the enclosed characters are interpreted as a
hexadecimal representation of a character, bit, or graphic string.
If the data is a mixed constant, the enclosing quotation marks and the suffix M are
removed, and the enclosed constant is interpreted as a character string.
If the data is a graphic constant, the enclosing quotation marks and the trailing
character G are removed, and the enclosed graphics are interpreted as a graphic
string.
PUT list-directed
In list-directed data transmission, how data values are converted and written out
depends on the value type and file attributes.
The values of the data-list items are converted to character representations (except
for graphics) and transmitted to the data stream. A blank separates successive data
values transmitted. For PRINT files, items are separated according to program tab
settings (see PRINT attribute on page 341).
Binary data values are converted to decimal notation before being placed in the
stream.
Bit strings are converted to character strings. The character string is enclosed in
quotation marks and followed by the letter B.
v If the file has the attribute PRINT, the enclosing quotation marks and letter G
are not supplied, and graphic quotation marks are represented by a single
graphic quotation mark (unmodified).
Related information:
PUT statement on page 322
The PUT statement is a STREAM output data transmission statement that can
transmit values to a stream output file or assign values to a character variable.
PRINT attribute
The PRINT attribute applies to files with the STREAM and OUTPUT attributes. It
indicates that the file is intended to be printed; that is, the data associated with the
file is to appear on printed pages, although it can first be written on some other
medium.
When PRINT is specified, the first data byte of each record of a PRINT file is
reserved for an American National Standard (ANS) printer control character. The
control characters are inserted by PL/I.
The layout of a PRINT file can be controlled by the use of the options and format
items listed in Table 47.
Table 47. Options and format items for PRINT files
Edit directed
Statement Statement option format item Effect
OPEN LINESIZE(n) Establishes line width
OPEN PAGESIZE(n) Establishes page length
PUT PAGE PAGE Skip to new page
PUT LINE(n) LINE(n) Skip to specified line
PUT SKIP[(n)] SKIP[(n)] Skip specified number of lines
PUT COLUMN(n) Skip to specified character position
in line
PUT X(n) Places blank characters in line to
establish position
LINESIZE and PAGESIZE establish the dimensions of the printed area of the page,
excluding footings. The LINESIZE option specifies the maximum number of
characters included in each printed line. If it is not specified for a PRINT file, a
default value of 120 characters is used. There is no default for a non-PRINT file.
The PAGESIZE option specifies the maximum number of lines in each printed
page; if it is not specified, a default value of 60 lines is used. Consider the
following example:
The OPEN statement opens the file Report as a PRINT file. The specification
PAGESIZE(55) indicates that each page contains a maximum of 55 lines. An
attempt to write on a page after 55 lines have already been written (or skipped)
raises the ENDPAGE condition. The implicit action for the ENDPAGE condition is
to skip to a new page, but you can establish your own action through use of the
ON statement, as shown in the example.
LINESIZE(110) indicates that each line on the page can contain a maximum of 110
characters. An attempt to write a line greater than 110 characters places the excess
characters on the next line.
When an attempt is made to write on line 56 (or to skip beyond line 55), the
ENDPAGE condition is raised, and the begin-block shown here is executed. The
ENDPAGE condition is raised only once per page. Consequently, printing can be
continued beyond the specified PAGESIZE after the ENDPAGE condition has been
raised. This can be useful, for example, if you want to write a footing at the
bottom of each page.
The first PUT statement specifies that a line is skipped, and the value of Footing,
presumably a character string, is printed on line 57 (when ENDPAGE is raised, the
current line is always PAGESIZE+1). The page number, Pageno, is incremented, the
file Report is set to the next page, and the character constant Page is
concatenated with the new page number and printed. The final PUT statement
skips three lines, so that the next printing is on line 4. Control returns from the
begin-block to the PUT statement that raised the ENDPAGE condition. However,
any SKIP or LINE option specified in that statement has no further effect.
DBCS continuation rules are applied and are the same rules as those described in
DBCS continuation rules on page 13. For information about how graphics are
handled for edit-directed transmission, see Edit-directed data specification on
page 333.
A-format item
The character (or A) format item describes the representation of a character value.
A
(field-width)
field-width
Specifies the number of character positions in the data stream that contain (or
will contain) the string. It is an expression that is evaluated and converted to
an integer value, which must be nonnegative, each time the format item is
used.
On input, the specified number of characters is obtained from the data stream and
assigned, with any necessary conversion, truncation, or padding, to the data-list
item. The field width is always required on input, and if it is zero, a null string is
obtained. If quotation marks appear in the stream, they are treated as characters in
the string.
The GET statement assigns the next 20 characters in Infile to Item. The value is
converted from its character representation specified by the format item A(20) to
the representation specified by the attributes declared for Item.
B-format item
The bit (or B) format item describes the character representation of a bit value.
Each bit is represented by the character zero or one.
B
(field-width)
field-width
Specifies the number of data-stream character positions that contain (or will
contain) the bit string. It is an expression that is evaluated and converted to an
integer value, which must be nonnegative, each time the format item is used.
On input, the character representation of the bit string can occur anywhere within
the specified field. Blanks, which can appear before and after the bit string in the
field, are ignored. Any necessary conversion occurs when the bit string is assigned
to the data-list item. The field width is always required on input, and if it is zero, a
null string is obtained. Any character other than 0 or 1 in the string, including
embedded blanks, quotation marks, or the letter B, raises the CONVERSION
condition.
The PUT statement writes the value of Mask in Maskfle as a string of 25 characters
consisting of zeros and ones.
C-format item
The complex (or C) format item describes the character representation of a complex
data value. You use one real-format-item to describe both the real and imaginary
parts of the complex data value in the data stream.
C (real-format-item)
real-format-item
Specified by one of the F-, E-, or P-format items. The P-format item must
describe numeric character data.
On output, the letter I is never appended to the imaginary part. If the second real
format item (or the first, if only one appears) is an F or E item, the sign is
transmitted only if the value of the imaginary part is less than zero. If the real
format item is a P item, the sign is transmitted only if the S or - or + picture
character is specified.
COLUMN (character-position)
character-position
Specifies an expression that is evaluated and converted to an integer value,
which must be nonnegative, each time the format item is used.
The file is positioned to the specified character position in the current line,
provided that it has not already passed this position. If the file is already
positioned after the specified character position, the current line is completed and a
new line is started; the format item is then applied to the following line.
Then, if the specified character position lies beyond the rightmost character
position of the current line, or if the value of the expression for the character
position is less than one, the default character position is one.
COLUMN cannot be used with input or output lines that contain graphics or
widechars.
E-format item
The floating-point (or E) format item describes the character representation of a
real floating-point decimal arithmetic data value.
E ( field-width,fractional-digits )
,significant-digits
field-width
Specifies the total number of characters in the field. It is evaluated and
converted to an integer value w each time the format item is used. w must be
nonnegative.
fractional-digits
Specifies the number of digits in the mantissa that follow the decimal point. It
is evaluated and converted to an integer value d each time the format item is
used. d must be nonnegative.
significant-digits
Specifies the number of digits that must appear in the mantissa. It is evaluated
and converted to an integer value s each time the format item is used. s must
be nonnegative.
On input, either the data value in the data stream is an optionally signed real
decimal floating-point or fixed-point constant located anywhere within the
specified field or the CONVERSION condition is raised. (For convenience, the E
preceding a signed exponent can be omitted.)
The field width includes leading and trailing blanks, the exponent position, the
positions for the optional plus or minus signs, the position for the optional letter E,
and the position for the optional decimal point in the mantissa.
The data value can appear anywhere within the specified field; blanks can appear
before and after the data value in the field and are ignored. If the entire field is
blank, the CONVERSION condition is raised. When no decimal point appears,
fractional-digits specifies the number of character positions in the mantissa to the
right of the assumed decimal point. If a decimal point does appear in the number,
it overrides the specification of fractional-digits.
The following statement obtains the next 10 characters from A and interprets them
as a floating-point decimal number. A decimal point is assumed before the
rightmost 6 digits of the mantissa. The value of the number is converted to the
attributes of COST and assigned to this variable.
get file(A) edit (Cost) (E(10,6));
The character string written in the stream for output has one of the following
syntaxes:
Note:
1. Blanks are not allowed between the elements of the character strings.
2. The length of the exponent is either 2 or 4 digits depending on the float
datatype and the setting of the E suboption of the DEFAULT compiler option.
In the discussion below, this length is represented by e.
v For d=0
s-digits E + exponent
- -
v For d=s
0. d-digits E + exponent
- -
If the field width is such that significant digits or the sign are lost, the SIZE
condition is raised. If the character string does not fill the specified field on output,
the character string is right-adjusted and extended on the left with blanks.
F-format item
The fixed-point (or F) format item describes the character representation of a real
fixed-point decimal arithmetic value.
F ( field-width )
,fractional-digits
,scaling-factor
field-width
Specifies the total number of characters in the field. It is evaluated and
converted to an integer value w each time the format item is used. The
converted value must be nonnegative.
fractional-digits
Specifies the number of digits in the mantissa that follow the decimal point. It
is evaluated and converted to an integer value d each time the format item is
used. The converted value must be nonnegative. If fractional-digits is not
specified, the default value is 0.
scaling-factor
Specifies the number of digits that must appear in the mantissa. It is evaluated
and converted to an integer value p each time the format item is used.
On input, either the data value in the data stream is an optionally signed real
decimal fixed-point constant located anywhere within the specified field or the
CONVERSION condition is raised. Blanks can appear before and after the data
value in the field and are ignored. If the entire field is blank, it is interpreted as
zero.
If only the field-width is specified, only the integer portion of the number is written;
no decimal point appears.
If both the field-width and fractional-digits are specified, both the integer and
fractional portions of the number are written. If the value (d) of fractional-digits is
greater than 0, a decimal point is inserted before the rightmost d digits. Trailing
zeros are supplied when fractional-digits is less than d (the value d must be less
than field-width). If the absolute value of the item is less than 1, a 0 precedes the
decimal point. Suppression of leading zeros is applied to all digit positions (except
the first) to the left of the decimal point.
The rounding of the data value is as follows: if truncation causes a digit to be lost
from the right, and this digit is greater than or equal to 5, 1 is added to the digit to
the left of the truncated digit.
On output, if the data-list item is less than 0, a minus sign is prefixed to the
character representation; if it is greater than or equal to 0, no sign appears.
Therefore, for negative values, the field-width might need to include provision for
the sign, a decimal point, and a 0 before the point.
If the field-width is such that any character is lost, the SIZE condition is raised.
The PUT statement specifies that the value of Total is converted to the character
representation of a fixed-point number and written into the output file SYSPRINT.
A decimal point is inserted before the last two numeric characters, and the number
is right-adjusted in a field of six characters. Leading zeros are changed to blanks
(except for a zero immediately to the left of the point), and, if necessary, a minus
sign is placed to the left of the first numeric character.
G-format item
For the compiler, the graphic (or G) format item describes the representation of a
graphic string.
G
(field-width)
field-width
Specifies the number of 2-byte positions in the data stream that contain (or will
contain) the graphic string. It is an expression that is evaluated and converted
to an integer value, which must be nonnegative, each time the format item is
used. End-of-line must not occur between the 2 bytes of a graphic.
On input, the specified number of graphics is obtained from the data stream and is
assigned, with any necessary truncation or padding, to the data-list item. The
field-width is always required on input, and if it is zero, a null string is obtained.
On output, the data-list item is truncated or extended (with the padding graphic)
on the right to the specified field-width before being placed into the data stream. No
enclosing quotation marks are inserted; nor is the identifying suffix, G, inserted. If
the field-width is zero, no graphics are placed into the data stream. If the field-width
is not specified, a default value is used, which is equal to the graphic-string length
of the data-list item.
In the following example, if file OUT has the GRAPHIC option, six bytes are
transmitted.
declare A graphic(3);
put file(Out) edit (A) (G(3));
L-format item
On input, L indicates that all data up to the end of the line is assigned to the data
item.
On output, L indicates that the data item, padded on the right with blanks, if
necessary, is to fill the remainder of the output line.
LINE (line-number)
line-number
Can be represented by an expression, which is evaluated and converted to an
integer value, which must be nonnegative, each time the format item is used.
If the specified line-number is less than or equal to the current line number, or if the
specified line is beyond the limits set by the PAGESIZE option of the OPEN
statement (or by default), the ENDPAGE condition is raised. An exception is that if
the specified line-number is equal to the current line number, and the column 1
character has not yet been transmitted, the effect is as for a SKIP(0) item, that is, a
carriage return with no line spacing.
P-format item
The picture (or P) format item describes the character representation of real
numeric character values and of character values.
The picture specification of the P-format item, on input, describes the form of the
data item expected in the data stream and, in the case of a numeric character
specification, how the item's arithmetic value is interpreted. If the indicated
character does not appear in the stream, the CONVERSION condition is raised.
On output, the value of the associated element in the data list is converted to the
form specified by the picture specification before it is written into the data stream.
P 'picture-specification'
picture-specification
See Chapter 14, Picture specification characters, on page 355.
When this statement is executed, the input file SYSIN is the default. The next five
characters input from SYSIN must be alphabetic or blank and they are assigned to
Name. The next four characters must be digits and they are assigned to Total.
PAGE
Starting a new page positions the file to the first line of the next page.
R-format item
The remote (or R) format item specifies that the format list in a FORMAT
statement is to be used.
R (label-reference)
label-reference
The label constant of a FORMAT statement
The R-format item and the specified FORMAT statement must be internal to the
same block, and they must be in the same invocation of that block.
A remote FORMAT statement cannot contain an R-format item that references itself
as a label reference; nor can it reference another remote FORMAT statement that
leads to the referencing of the original FORMAT statement.
Conditions enabled for the GET or PUT statement must also be enabled for the
remote FORMAT statement(s) that are referred to.
If the GET or PUT statement is the single statement of an ON-unit, that statement
is a block, and it cannot contain a remote format item.
Example
declare Switch label;
get file(In) list(Code);
if Code = 1 then
Switch = L1;
else
Switch = L2;
get file(In) edit (W,X,Y,Z)
(R(Switch));
L1: format (4 F(8,3));
L2: format (4 E(12,6));
Switch has been declared a label variable. The second GET statement can be made
to operate with either of the two FORMAT statements.
Related information:
SKIP
(relative-line)
relative-line
Specifies an expression, which is evaluated and converted to an integer value,
n, each time the format item is used. The converted value must be nonnegative
and less than 32768. It must be greater than zero for non-PRINT files. If it is
zero, or if it is omitted, the default is 1.
The new line is the nth line after the present line.
If n is greater than one, one or more lines are ignored on input; on output, one or
more blank lines are inserted.
The value n can be zero for PRINT files only, in which case the positioning is at
the start of the current line. Characters previously written can be overprinted.
For PRINT files, if the specified relative-line is beyond the limit set by the
PAGESIZE option of the OPEN statement (or the default), the ENDPAGE condition
is raised.
If the SKIP format item is the first item to be executed after a file has been opened,
output commences on the nth line of the first page. If n is zero or 1, it commences
on the first line of the first page.
Example
get file(In) edit(Man,Overtime)
(skip(1), A(6), COL(60), F(4,2));
This statement positions the data set associated with file to a new line. The first 6
characters on the line are assigned to Man, and the 4 characters beginning at
character position 60 are assigned to Overtime.
V-format item
On input, V indicates that all data up to the end of the line is assigned to the data
item. However, the characters read with a V-format item are not flushed; they are
only viewed. They will be flushed only when read by some other format item.
X-format item
The spacing (or X) format item specifies the relative spacing of data values in the
data stream.
X (field-width)
field-width
Specifies an expression that is evaluated and converted to an integer value,
which must be nonnegative, each time the format item is used. The integer
value specifies the number of characters before the next field of the data
stream, relative to the current position in the stream.
On input, the specified number of characters are spaced over in the data stream
and not transmitted to the program.
The next 15 characters from the input file, SYSIN, are treated as follows: the first
five characters are assigned to Number, the next five characters are ignored, and the
remaining five characters are assigned to Rebate.
On output, the specified number of blank characters are inserted into the stream.
Four characters that represent the value of Part, then two blank characters, and
finally five characters that represent the fixed-point value of Count, are placed in
the file named Out.
A character pictured item can consist of alphabetic characters, decimal digits, blanks,
currency and punctuation characters.
A numeric character pictured item can consist only of decimal digits, an optional
decimal point, an optional letter E, and, optionally, one or two plus or minus signs.
Other characters generally associated with arithmetic data, such as currency
symbols, can also be specified, but they are not part of the arithmetic value of the
numeric character variable, although the characters are stored with the digits and
are part of the character value of the variable.
Figures in this section illustrate how different picture specifications affect the
representation of values when assigned to a pictured variable or when printed
using the P-format item. Each figure shows the original value of the data, the
attributes of the variable from which it is assigned (or written), the picture
specification, and the character value of the numeric character or pictured character
variable.
(n)
For example, the following picture specifications result in the same description:
999V99
(3)9V(2)9
The only valid characters in a character picture specification are X, A, and 9. Each
of these specifies the presence of one character position in the character value.
X Any character of the 256 possible bit combinations represented by the 8-bit
byte.
A Any alphabetic or extralingual (#, @, $) character, or blank.
9 Any digit, or blank. (Note that the 9 picture specification character allows
blanks only for character data.)
The following values are not valid for Part# (the invalid characters are
underscored):
AB123M
ABC1/2
Mb#A5;
A numeric character variable can have two values, depending upon how the
variable is used. The types of values are as follows:
Arithmetic
The arithmetic value is the value expressed by the decimal digits of the
data item, the assumed location of a decimal point, possibly a sign, and an
optionally-signed exponent or scaling factor. The arithmetic value of a
numeric character variable is used in the following situations:
v Whenever the variable appears in an expression that results in a coded
arithmetic value or bit value (this includes expressions with the , &, |,
and comparison operators; even comparison with a character string uses
the arithmetic value of a numeric character variable)
v Whenever the variable is assigned to a coded arithmetic, numeric
character, or bit variable
v When used with the C, E, F, B, and P (numeric) format items in
edit-directed I/O.
The arithmetic value of the numeric character variable is converted to
internal coded arithmetic representation.
Character value
The character value is the value expressed by the decimal digits of the data
item, as well as all of the editing and insertion characters appearing in the
picture specification. The character value does not, however, include the
assumed location of a decimal point, as specified by the picture characters
V, K, or F. The character value of a numeric character variable is used:
v Whenever the variable appears in a character expression
v In an assignment to a character variable
v Whenever the data is printed using list-directed or data-directed output
v Whenever a reference is made to a character variable that is defined or
based on the numeric character variable
v Whenever the variable is printed using edit-directed output with the A
or P (character) format items.
No data conversion is necessary.
Numeric character data can contain only decimal digits, an optional decimal point,
an optional letter E, and one or two plus or minus signs. Other characters
generally associated with arithmetic data, such as currency symbols, can also be
specified, but they are not a part of the arithmetic value of the numeric character
variable, although the characters are stored with the digits and are part of the
character value of the variable.
A requirement of the picture specification for numeric character data is that each
field must contain at least one picture character that specifies a digit position. This
picture character, however, need not be the digit character 9. Other picture
characters, such as the zero suppression characters (Z or *), also specify digit
positions.
Note: All characters except K, V, and F specify the occurrence of a character in the
character representation.
Related information:
Insertion and decimal point characters on page 361
The point, comma, slash, or apostrophe can be used with the V to cause insertion
of the point, comma, slash, or apostrophe in the position that delimits the end of
the integer portion and the beginning of the fractional portion of a fixed-point (or
floating-point) number, as might be wanted in printing. The V itself does not cause
the printing of period or any other delimiters.
Picture repetition factor on page 355
A picture repetition factor specifies the number of repetitions of the next picture
character in the specification.
Zero suppression
The picture characters Z and asterisk (*) specify conditional digit positions in the
character value and can cause leading zeros to be replaced by asterisks or blanks.
Leading zeros are those that occur in the leftmost digit positions of fixed-point
numbers or in the leftmost digit positions of the two parts of floating-point
numbers, that are to the left of the assumed position of a decimal point, and that
are not preceded by any of the digits 1 through 9. The leftmost nonzero digit in a
number and all digits, zeros or not, to the right of it represent significant digits.
Z Specifies a conditional digit position and causes a leading zero in the
associated data position to be replaced by a blank. Otherwise, the digit in the
position is unchanged. The picture character Z cannot appear in the same field
as the picture character * or a drifting character; nor can it appear to the right
of any of the picture characters in a field.
* Specifies a conditional digit position. It is used in the way the picture character
Z is used, except that leading zeros are replaced by asterisks. The picture
character asterisk cannot appear in the same field as the picture character Z or
a drifting character, nor can it appear to the right of any of the picture
characters in a field.
If one of the picture characters Z or asterisk appears to the right of the picture
character V, all fractional digit positions in the specification, as well as all integer
digit positions, must use the Z or asterisk picture character, respectively. When all
digit positions to the right of the picture character V contain zero suppression
picture characters, fractional zeros of the value are suppressed only if all positions
in the fractional part contain zeros and all integer positions have been suppressed.
The character value of the data item will then consist of blanks or asterisks. No
digits in the fractional part are replaced by blanks or asterisks if the fractional part
contains any significant digit.
Insertion characters
The picture characters comma (,), point (.), slash (/), apostrophe ('), and blank (B)
cause the specified character to be inserted into the associated position of the
numeric character data. They do not indicate digit or character positions, but are
inserted between digits or characters. Each does, however, actually represent a
character position in the character value, whether or not the character is
suppressed.
The comma, point, slash, and apostrophe are conditional insertion characters and
can be suppressed within a sequence of zero suppression characters. The blank is
an unconditional insertion character, and always specifies that a blank appears in
the associated position.
Insertion characters are applicable only to the character value. They specify
nothing about the arithmetic value of the data item. They never cause decimal
point or decimal comma alignment in the picture specifications of a fixed-point
decimal number and are not a part of the arithmetic value of the data item.
Decimal alignment is controlled by the picture characters V and F.
The point must immediately precede or immediately follow the V. If the point
precedes the V, it is inserted only if an unsuppressed digit appears to the left of the
V, even if all fractional digits are significant. If the point immediately follows the V,
it is suppressed if all digits to the right of the V are suppressed, but it appears if
there are any unsuppressed fractional digits (along with any intervening zeros).
The following example shows decimal conventions that are used in different
countries.
declare A picture Z,ZZZ,ZZZV.99,
B picture Z.ZZZ.ZZZV,99,
C picture ZBZZZBZZZV,99,
D picture ZZZZZZZV.99;
A,B,C,D = 1234;
A,B,C,D = 1234.00;
< Indicates the start of the currency symbol. It acts as an escape character. If you
want to use the character <, you must specify <<.
char
Is any character that will be part of your currency symbol(s).
> Indicates the end of the currency symbol. If you want to use the character >,
you must specify <>.
More than one > indicates a drifting string (see Drifting use on page 364).
If the character < or > must be included in the sequence, it must be preceded by
another <. Therefore, < acts as an escape character also.
The entire sequence enclosed in < > represents one "symbol" and, therefore,
represents the character value for one numeric character. If the symbol needs to be
represented as a drifting picture character, you specify > following the "< >" to
represent each occurrence.
dcl P pic<DM>9.999,V99;
P = 34.40; /* Yields DM 34,40 */
dcl P pic<DM>>.>>9,V99;
P = 1234.40; /* Yields DM1.234,40 */
dcl P pic<DM>>.>>9,V99;
P = 34.40; /* Yields DM34,40 */
dcl P pic9.999,V99<K$>;
P = 1234.40; /* Yields 1.234,40K$ */
In this section, the term currency symbol and the $ symbol refer to the dollar sign or
any user-defined currency symbol.
Signs and currency symbols can be used in either a static or a drifting manner.
Static use
Static use specifies that a sign, a currency symbol, or a blank appears in the
associated position.
An S, +, or - used as a static character can appear to the right or left of all digits in
the mantissa and exponent fields of a floating-point specification, and to the right
or left of all digit positions of a fixed-point specification.
Drifting use
Drifting use specifies that leading zeros are to be suppressed. In this case, the
rightmost suppressed position associated with the picture character will contain a
sign, a blank, or a currency symbol (except that where all digit positions are
occupied by drifting characters and the value of the data item is zero, the drifting
character is not inserted).
The position in the data associated with the characters slash, comma, and point
appearing in a string of drifting characters contains one of the following:
v Slash, comma, or point if a significant digit appears to the left
v The drifting symbol, if the next position to the right contains the leftmost
significant digit of the field
v Blank, if the leftmost significant digit of the field is more than one position to
the right.
If a drifting string contains the drifting character n times, the string is associated
with n-1 conditional digit positions. The position associated with the leftmost
drifting character can contain only the drifting character or blank, never a digit.
Two different picture characters cannot be used in a drifting manner in the same
field.
If a drifting string contains a V within it, the V delimits the preceding portion as a
subfield, and all digit positions of the subfield following the V must also be part of
the drifting string that commences the second subfield.
In the case in which all digit positions after the V contain drifting characters,
suppression in the subfield occurs only if all of the integer and fractional digits are
zero. The resulting edited data item is then all blanks (except for any insertion
characters at the start of the field). If there are any nonzero fractional digits, the
entire fractional portion appears unsuppressed.
Overpunch
Any of the picture characters T, I, or R (known as overpunch characters) specifies
that a character represents the corresponding digit and the sign of the data item. A
floating-point specification can contain twoone in the mantissa field and one in
the exponent field. The overpunch character can be specified for any digit position
within a field.
The T, I, and R picture characters specify how the input characters are interpreted,
as shown in Table 53.
Table 53. Interpretation of the T, I, and R picture characters
T or I T or R
Digit with + Digit with -
Digit
Character Character
This example sets X to 132 on finding '132' in the next three positions of the
input stream, but sets X to -132 on finding 'J32'.
Zero replacement
The picture character Y specifies that a zero in the specified digit position is
replaced unconditionally by the blank character.
Table 54 on page 368 shows examples of credit, debit, overpunched, and zero
replacement characters.
Table 54. Examples of credit, debit, overpunched, and zero replacement characters
Source data (in
Source attributes constant form) Picture specification Character value
Exponent characters
The picture characters K and E delimit the exponent field of a numeric character
specification that describes floating-point decimal numbers. The exponent field is
the last field of a numeric character floating-point picture specification. The picture
characters K and E cannot appear in the same specification.
K Specifies that the exponent field appears to the right of the associated position.
It does not specify a character in the numeric character data item.
E Specifies that the associated position contains the letter E, which indicates the
start of the exponent field.
The value of the exponent is adjusted in the character value so that the first
significant digit of the first field (the mantissa) appears in the position associated
with the first digit specifier of the specification (even if it is a zero suppression
character).
Scaling factor
The picture character F specifies a picture scaling factor for fixed-point decimal
numbers. It can appear only once at the right end of the picture specification.
F ( integer)
+
-
F Specifies the picture scaling factor. The picture scaling factor specifies that the
decimal point in the arithmetic value of the variable is that number of places to
the right (if the picture scaling factor is positive) or to the left (if negative) of
its assumed position in the character value.
The number of digits following the V picture character minus the integer
specified with F must be in the range -128 to 127.
The implicit action for many conditions is to raise the ERROR condition. This
provides a common condition that can be used to check for a number of different
conditions, rather than checking each condition separately. The ONCODE built-in
function is particularly useful here, as it can be used to identify the specific
circumstances that raised the conditions. Codes corresponding to the conditions
and errors detected are listed in Messages and Codes.
Related information:
Chapter 18, Built-in functions, pseudovariables, and subroutines, on page 409
A large number of common tasks are available in the form of built-in functions,
subroutines, and pseudovariables. When you use them, you can write less code
more quickly with greater reliability. This chapter describes the built-in functions,
subroutines, and pseudovariables that you can use in your PL/I program.
Condition prefixes
You can use a condition prefix to specify whether some conditions are enabled or
disabled. If a condition is enabled, the compiler generates any extra code needed in
order to detect the condition. If a condition is disabled, the compiler generates no
extra code to detect it.
( condition ) : statement
;
condition
Some conditions are always enabled, and cannot be disabled. Some are enabled
unless you disable them, and some are disabled unless you enable them. The
conditions are listed in Chapter 16, Conditions, on page 381.
statement
Condition prefixes are not valid for DECLARE, DEFAULT, FORMAT,
OTHERWISE, END, ELSE, ENTRY, and %statements. For information about the
scope of condition prefixes, see Scope of the condition prefix on page 373.
In the following example, (size): is the condition prefix. The conditional prefix
indicates that the corresponding condition is enabled within the scope of the
prefix.
(size): L1: X=(I**N) / (M+L);
To enable conditions, specify the condition prefix with the condition name. To
disable conditions, specify the condition prefix with the condition name, preceded
by NO without intervening blanks.
On-units
An implicit action exists for every condition. When an enabled condition is raised,
the implicit action is executed unless an ON-unit for the enabled condition is
established. If the implicit action is to raise ERROR and no ON-unit has been
established for the condition, a message will be written before the ERROR
condition is raised.
ON statement
The ON statement establishes the action to be executed for any subsequent raising
of an enabled condition in the scope of the established condition.
ON condition SYSTEM;
SNAP ON-unit
condition
Is any one of those described in Chapter 16, Conditions, on page 381 or
defined with the CONDITION attribute.
SNAP
Specifies that when the enabled condition is raised, diagnostic information
relating to the condition is printed. The action of the SNAP option precedes the
action of the ON-unit.
If SNAP and SYSTEM are specified, the implicit action is followed immediately
by SNAP information.
SYSTEM
Specifies that the implicit action is taken. The implicit action is not the same
for every condition, although for most conditions a message is printed and the
ERROR condition is raised. The implicit action for each condition is given in
Chapter 16, Conditions, on page 381.
ON-unit
Specifies the action to be executed when the condition is raised and is enabled.
The action is defined by the statement or statements in the ON-unit itself.
When the ON statement is executed, the ON-unit is said to be established for
the specified condition. The ON-unit is not executed at the time the ON
statement is executed; it is executed only when the specified enabled condition
is raised.
The ON-unit can be either a single unlabeled simple statement or an unlabeled
begin-block. If it is a simple statement, it can be any statement except BEGIN,
DECLARE, DEFAULT, DO, END, ENTRY, FORMAT, ITERATE, LEAVE,
OTHERWISE, PROCEDURE, RETURN, SELECT, WHEN, or %statements. If the
ON-unit is a begin-block, a RETURN statement can appear only within a
procedure nested within the begin-block; a LEAVE statement can appear only
within a do-group nested within the begin-block.
Except for ON-units consisting only of either a semicolon (;) or the RESIGNAL
statement, an ON-unit is treated as a procedure (without parameters) that is
internal to the block in which it appears. Any names referenced in an ON-unit
are those known in the environment in which the ON statement for that
ON-unit was executed, rather than the environment in which the condition
was raised.
When execution of the ON-unit is complete, control generally returns to the
block from which the ON-unit was entered. Just as with a procedure, control
can be transferred out of an ON-unit by a GO TO statement. In this case,
control is transferred to the point specified in the GO TO, and a normal return
does not occur.
The specific point to which control returns from an ON-unit varies for different
conditions. Normal return for each condition is described in Chapter 16,
Conditions, on page 381.
Null ON-unit
The effect of a null statement ON-unit is to execute normal return from the
condition.
Use of the null ON-unit is different from disabling a condition for two reasons:
v A null ON-unit can be specified for any condition, but not all conditions can be
disabled.
v Disabling a condition, if possible, can save time by avoiding any checking for
this condition. (If a null ON-unit is specified, the PL/I must still check for the
raising of the condition.)
When another ON statement specifies the same conditions, the following applies:
v If a later ON statement specifies the same condition as a prior ON statement and
this later ON statement is executed in a block which is a dynamic descendant of
the block containing the prior ON statement, the action specification of the prior
ON statement is temporarily suspended, or stacked. It can be restored either by
the execution of a REVERT statement, or by the termination of the block
containing the later ON statement.
When control returns from a block, all established actions that existed at the
time of its activation are reestablished. This makes it impossible for a subroutine
to alter the action established for the block that invoked the subroutine.
v If the later ON statement and the prior ON statement are internal to the same
invocation of the same block, the effect of the prior ON statement is logically
nullified. No reestablishment is possible, except through execution of another
ON statement (or re-execution of an overridden ON statement).
Related information:
Dynamically descendent ON-units
It is possible to raise a condition during execution of an ON-unit that specifies
another ON-unit. An ON-unit entered because a condition is either raised or
signalled in another ON-unit is a dynamically descendent ON-unit. A normal
return from a dynamically descendent ON-unit reestablishes the environment of
the ON-unit in which the condition was raised.
A loop can occur if an ERROR condition raised in an ERROR ON-unit executes the
same ERROR ON-unit, raising the ERROR condition again. In any situation where
a loop can cause the maximum nesting level to be exceeded, a message is printed
and the application is terminated. To avoid a loop caused by this situation, use the
following technique:
on error begin;
on error system;
.
.
.
end;
Example 1
dcl F file,
G file variable;
G = F;
L1: on endfile(G);
L2: on endfile(F);
Example 2
declare FV file variable,
FC1 file,
FC2 file;
FV = FC1;
on endfile(FV) go to Fin;
.
.
.
FV = FC2;
read file(FC1) into (X1);
read file(FV) into (X2);
An ENDFILE condition raised during the first READ statement causes the ON-unit
to be entered, because the ON-unit refers to file FC1. If the condition is raised in
the second READ statement, however, the ON-unit is not entered, because this
READ refers to file FC2.
Example 3
E: procedure;
declare F1 file;
on endfile (F1) goto L1;
call E1 (F1);
.
.
.
E1: procedure (F2);
declare F2 file;
on endfile (F2) go to L2;
read file (F1);
read file (F2);
end E1;
Example 4
declare FV file variable,
FC1 file,
FC2 file;
do FV=FC1,FC2;
on endfile(FV) go to Fin;
end;
If an ON statement specifying a file variable is executed more than once, and the
variable has a different value each time, a different ON-unit is established at each
execution.
REVERT statement
Execution of the REVERT statement in a given block cancels the ON-unit for the
condition that executed in that block. The ON-unit that was established at the time
the block was activated is then reestablished.
REVERT affects only ON statements that are internal to the block in which the
REVERT statement occurs and that have been executed in the same invocation of
that block.
REVERT condition ;
condition
Is any one of those described in Chapter 16, Conditions, on page 381 or
defined with the CONDITION attribute.
The REVERT statement cancels an ON-unit only if both of the following conditions
are true:
1. An ON statement that is eligible for reversion and that specifies a condition
listed in the REVERT statement was executed after the block was activated.
2. A REVERT statement with the specified condition was not previously executed
in the same block.
If either of these two conditions is not met, the REVERT statement is treated as a
null statement.
SIGNAL statement
You can raise a condition by means of the SIGNAL statement. This statement can
be used in program testing to verify the action of an ON-unit and to determine
whether the correct action is associated with the condition. The established action
is taken unless the condition is disabled.
SIGNAL condition ;
condition
Is any condition described in Chapter 16, Conditions, on page 381 or defined
with the CONDITION attribute.
RESIGNAL statement
The RESIGNAL statement terminates the current ON-unit and allows another
ON-unit for the same condition to get control.
The processing continues as if the ON-unit executing the RESIGNAL did not exist
and was never given control. It allows multiple ON-units to get control for the
same condition.
RESIGNAL ;
Multiple conditions
A multiple condition is the simultaneous raising of two or more conditions.
The conditions for which a multiple condition can occur are the RECORD
condition on page 393 and the TRANSMIT condition on page 397. The
TRANSMIT condition is always processed first. The RECORD condition is ignored
unless there is a normal return from the TRANSMIT ON-unit.
Multiple conditions are processed successively. When one of the following events
occurs, no subsequent conditions are processed:
v Condition processing terminates the program, through implicit action for the
condition, normal return from an ON-unit, or abnormal termination in the
ON-unit.
v A GO TO statement transfers control from an ON-unit, so that a normal return is
prevented.
CONDITION attribute
The CONDITION attribute specifies that the declared name identifies a
programmer-defined condition.
CONDITION
ANYCONDITION condition
Status
ANYCONDITION is always enabled.
Result
The result is the same as for the underlying condition.
Cause and syntax
SIGNAL ANYCONDITION is not allowed. ANYCONDITION can be used only
in ON (and REVERT) statements to establish (and cancel) an ON-unit that will
trap any condition, including the CONDITION condition, that occurs in a
block, and that is not trapped by some other eligible ON-unit in that block.
In the following example, all ERROR conditions would be handled in the
begin-block, the FINISH condition would be handled by the system, and all
other conditions would be handled by the call to the routine named
handle_All_Others.
on error
begin;
.
.
.
end;
on finish system;
on anycondition call Handle_all_others;
Note: To avoid infinite loops, the use of ON FINISH (as in the preceding
example) might be necessary when ON ANYCONDITION is used.
Note that when a condition is raised, the call stack will be walked (backwards)
to search for a block that has an ON-unit for that condition. The search will
stop when the first block with such an ON-unit or with an ON
ANYCONDITION ON-unit is found. If no such ON-units are found and the
implicit action for the condition is to promote it to ERROR, the stack will then
(and only then) be walked again to search for an ON ERROR ON-unit.
You can use the ONCONDID built-in function in an ANYCONDITION
ON-unit to determine what condition is being handled, and the
ONCONDCOND built-in function to determine the name of the CONDITION
condition. Other ON built-in functions, such as ONFILE, can be used to
determine the exact cause and other related information. These built-in
functions are listed in Chapter 18, Built-in functions, pseudovariables, and
subroutines, on page 409.
ANYCONDITION
Abbreviation
ANYCOND
Implicit action
The implicit action is that of the underlying condition.
Normal return
Normal return is the same as for the underlying condition.
Condition codes
There are no condition codes unique to the ANYCONDITION.
AREA condition
Status
AREA is always enabled.
Result
An attempted allocation or assignment that raises the AREA condition has no
effect.
Cause and syntax
The AREA condition is raised in either of the following circumstances:
v When an attempt is made to allocate a based variable within an area that
contains insufficient free storage for the allocation to be made.
v When an attempt is made to perform an area assignment and the target area
contains insufficient storage to accommodate the allocations in the source
area
You can retrieve the name of the AREA reference that raised an AREA
condition by using the ONAREA built-in function in the ON-unit. For more
information about the ONAREA built-in function, see ONAREA on page 625
in Chapter 18, Built-in functions, pseudovariables, and subroutines, on page
409.
AREA
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
On normal return from the ON-unit, the action is as follows:
v If the condition was raised by an allocation and the ON-unit is a null
ON-unit, the allocation is not attempted again.
v If the condition was raised by an allocation, the allocation is attempted
again. Before the attempt is made, the area reference is reevaluated. Thus, if
the ON-unit has changed the value of a pointer qualifying the reference to
the inadequate area so that it points to another area, the allocation is
attempted again within the new area.
v If the condition was raised by an area assignment or by a SIGNAL
statement, execution continues from the point at which the condition was
raised.
Condition codes
360, 361, 362
ATTENTION condition
Status
ATTENTION is always enabled.
Result
Raising the condition causes an ATTENTION ON-unit to be entered. If there is
no ATTENTION ON-unit, the application is terminated.
Cause and syntax
The ATTENTION condition is raised when the user hits a specific key
combination to interrupt an application. The specific key is determined by the
operating system as follows:
v On Windows, CTRL-BRK and CTRL-C. No ATTENTION ON-units will be
driven on Windows as a result of the user entering CTRL-BRK or CTRL-C
key combinations. The implicit action will be taken.
v On the host, the ATTN key, if available.
The condition can also be raised by a SIGNAL ATTENTION statement.
ATTENTION
Abbreviation
ATTN
Implicit action
The application is terminated.
Normal return
On return from an ATTENTION ON-unit, processing is resumed at a point in
the program immediately following the point at which the condition was
raised.
Condition code
400
CONDITION condition
Status
CONDITION is always enabled.
Result
The CONDITION condition allows you to establish an ON-unit that will be
executed whenever a SIGNAL statement for the appropriate CONDITION
condition is executed.
As a debugging aid, the CONDITION condition can be used to establish an
ON-unit that prints information about the current status of the program.
Cause and syntax
The CONDITION condition is raised by a SIGNAL statement. The name
specified in the SIGNAL statement determines which CONDITION condition is
raised. The ON-unit can be executed from any point in the program through
placement of a SIGNAL statement. Normal rules of name scope apply. A
condition name is external by default, but can be declared INTERNAL.
The following example shows the use of the CONDITION condition.
dcl Test condition;
on condition (Test)
begin;
.
.
.
end;
The begin-block is executed whenever the following statement is executed:
signal condition (Test);
CONDITION (name)
Abbreviation
COND
Implicit action
A message is printed and execution continues with the statement following
SIGNAL.
Normal return
Execution continues with the statement following the SIGNAL statement.
Condition code
500
CONVERSION condition
Status
CONVERSION is enabled throughout the program, except within the scope of
the NOCONVERSION condition prefix. You can use the ONSOURCE,
ONCHAR, ONGSORCE, and ONWSOURCE pseudovariables in
CONVERSION ON-units to correct conversion errors.
Result
When CONVERSION is raised, the contents of the entire result field are
undefined.
Cause and syntax
The CONVERSION computational condition is raised whenever an invalid
conversion is attempted on character, widechar, or graphic data. This attempt
can be made internally or during an input/output operation. For example, the
condition is raised when any of the following conversions happens:
v A character other than 0 or 1 exists in character data being converted to bit
data.
v A character value that is being converted to a numeric character field or to a
coded arithmetic value contains characters that are not the representation of
an optionally signed arithmetic constant or an expression to represent a
complex constant.
v A graphic (DBCS) string being converted to character contains a graphic that
cannot be converted to SBCS.
v A value being converted to a character pictured item contains characters not
allowed by the picture specification.
All conversions of character data are carried out character-by-character in a
left-to-right sequence. The condition is raised for each invalid character. The
condition is also raised if all the characters are blank, with the following
exceptions:
v For input with the F-format item, a value of zero is assumed.
v For input with the E-format item, be aware that sometimes the ON-unit will
be repeatedly entered.
Note that if a null string or a string of one or more blanks is assigned to a
numeric variable, the CONVERSION condition will not be raised.
When the CONVERSION condition is raised, the ONSUBCODE built-in
function will return the index of the offending character or graphic.
When an invalid character is encountered, the current action specification for
the condition is executed (provided that CONVERSION is not disabled). If the
action specification is an ON-unit, the invalid character can be replaced within
the unit.
v For character source data, use the ONSOURCE or ONCHAR
pseudovariables.
CONVERSION
Abbreviation
CONV
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
If CONVERSION was raised on a character string source (not graphic source)
and either ONSOURCE or ONCHAR pseudovariables are used in the ON-unit,
the program retries the conversion on return from the ON-unit.
If CONVERSION was raised on a graphic source and the ONGSOURCE
pseudovariable is used in the ON-unit, the program retries the conversion on
return from the ON-unit.
If CONVERSION was raised on a widechar source and the ONWSOURCE
pseudovariable is used in the ON-unit, the program retries the conversion on
return from the ON-unit.
If the conversion error is not corrected by using these pseudovariables, the
program loops.
Condition codes
600-672
ENDFILE condition
Status
The ENDFILE condition is always enabled.
Result
If the specified file is not closed after the condition is raised, subsequent GET
or READ statements to the file are unsuccessful and cause additional ENDFILE
conditions to be raised.
But the file must not be closed in its ENDFILE ON-unit: it should be closed
only after that ON-unit has been exited.
Cause and syntax
The ENDFILE input/output condition can be raised during an operation by an
attempt to read past the end of the file specified in the GET or READ
statement. It applies only to SEQUENTIAL INPUT, SEQUENTIAL UPDATE,
and STREAM INPUT files.
In record-oriented data transmission, ENDFILE is raised whenever an end of
file is encountered during the execution of a READ statement.
In stream-oriented data transmission, ENDFILE is raised during the execution
of a GET statement if an end of file is encountered either before any items in
the GET statement data list have been transmitted or between transmission of
two of the data items. If an end of file is encountered while a data item is
being processed, or if it is encountered while an X-format item is being
processed, the ERROR condition is raised.
ENDFILE
(file-reference)
file-reference
The file reference must be a scalar reference. If a file reference is
omitted, SYSIN is assumed.
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
Execution continues with the statement immediately following the GET or
READ statement that raised the ENDFILE.
If a file is closed in an ON-unit for this condition, the results of normal return
are undefined. Exit from the ON-unit with the closed file must be achieved
with a GO TO statement.
Condition code
70
ENDPAGE condition
Status
ENDPAGE is always enabled.
Result
When ENDPAGE is raised, the current line number is one greater than that
specified by the PAGESIZE option (default is 60) so that it is possible to
continue writing on the same page. The ON-unit can start a new page by
execution of a PAGE option or a PAGE format item, which sets the current line
to one.
If the ON-unit does not start a new page, the current line number can increase
indefinitely. If a subsequent LINE option or LINE format item specifies a line
number that is less than or equal to the current line number, ENDPAGE is not
raised, but a new page is started with the current line set to one. An exception
is that if the current line number is equal to the specified line number, and the
file is positioned on column one of the line, ENDPAGE is not raised.
If ENDPAGE is raised during data transmission, on return from the ON-unit,
the data is written on the current line, which might have been changed by the
ON-unit. If ENDPAGE results from a LINE or SKIP option, on return from the
ON-unit, the action specified by LINE or SKIP is ignored.
Cause and syntax
The ENDPAGE input/output condition is raised when a PUT statement results
in an attempt to start a new line beyond the limit specified for the current
page. This limit can be specified by the PAGESIZE option in an OPEN
statement; if PAGESIZE has not been specified, a default limit of 60 is applied.
The attempt to exceed the limit can be made during data transmission
(including associated format items, if the PUT statement is edit-directed), by
the LINE option, or by the SKIP option. ENDPAGE can also be raised by a
LINE option or LINE format item that specified a line number less than the
current line number. ENDPAGE is raised only once per page, except when it is
raised by the SIGNAL statement.
ENDPAGE
(file-reference)
file-reference
The file reference must be a scalar reference. If a file reference is
omitted, SYSPRINT is assumed.
Implicit action
A new page is started. If the condition is signalled, execution is unaffected and
continues with the statement following the SIGNAL statement.
Normal return
Execution of the PUT statement continues in the manner described above.
Condition code
90
ERROR condition
Status
ERROR is always enabled.
Result
An error message is issued if no ON-unit is active when the ERROR condition
arises, or if the ON-unit does not use a GOTO (to exit the block) to recover
from the condition.
Cause and syntax
The ERROR condition is the implicit action for many conditions. This provides
a common condition that can be used to check for a number of different
conditions, rather than checking each condition separately.
The ERROR condition is raised under the following circumstances:
v As a result of the implicit action for a condition, which is to raise the
ERROR condition
v As a result of the normal return action for some conditions, such as
SUBSCRIPTRANGE CONVERSION or when no retry is attempted
v As a result of an error (for which there is no other PL/I-defined condition)
during program execution
v As a result of a SIGNAL ERROR statement
ERROR
Implicit action
The message is printed and the FINISH condition is raised.
Normal return
The implicit action is taken.
Condition codes
All codes 1000 and above are ERROR conditions.
FINISH condition
Status
FINISH is always enabled.
Result
Control passes to the FINISH ON-unit and processing continues.
Cause and syntax
The FINISH condition is raised during execution of a statement that would
terminate the procedures. The following actions take place:
v If the termination is normalthe FINISH ON-unit, if established, is given
control only if the main procedure is PL/I.
v If the termination is abnormalthe FINISH ON-unit, if established in an
active block, is given control.
FINISH
Implicit action
v If the condition is raised in the major task, no action is taken and processing
continues from the point where the condition was raised.
v If the condition is raised as part of the implicit action for another condition,
the program is terminated.
Normal return
Processing resumes at the point where the condition was raised. This point is
the statement following the SIGNAL statement if the conditions was signalled.
Condition code
4
FIXEDOVERFLOW condition
Status
FIXEDOVERFLOW is enabled throughout the program, except within the
scope of the NOFIXEDOVERFLOW condition prefix.
Result
The result of the invalid FIXED DECIMAL operation is undefined.
Cause and syntax
The FIXEDOVERFLOW computational condition is raised when the length of
the result of a FIXED DECIMAL arithmetic operation exceeds the maximum
length allowed by the implementation.
The FIXEDOVERFLOW condition is not raised for FIXED BINARY operations.
The FIXEDOVERFLOW condition differs from the SIZE condition in that SIZE
is raised when a result exceeds the declared size of a variable, while
FIXEDOVERFLOW is raised when a result exceeds the maximum allowed by
the computer.
If the FIXEDOVERFLOW condition is raised and it is disabled, the program is
in error.
FIXEDOVERFLOW
Abbreviation
FOFL
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
Control returns to the point immediately following the point at which the
condition was raised.
Condition code
310
INVALIDOP condition
Status
INVALIDOP is enabled throughout the program, except within the scope of the
NOINVALIDOP condition prefix.
Result
The result of the invalid operation is undefined.
Cause and syntax
The INVALIDOP computational condition is raised when any of the following
are detected during the evaluation of IEEE floating-point expressions.
v Subtraction of two infinities
v Multiplication of infinity by 0
v Division of two infinities
v Division of zero by zero
v Invalid floating-point data
Some fixed decimal divides with large precision are done using the Decimal
Floating-Point (DFP) facility. This might cause some ZERODIVIDE exceptions
to be reported as INVALIDOP.
INVALIDOP
Implicit action
The ERROR condition is raised.
Normal return
A message is printed and the ERROR condition is raised.
Condition code
290
Related information:
ZERODIVIDE condition on page 400
KEY condition
Status
KEY is always enabled.
Result
The keyed record is undefined, and the statement in which it appears is
ignored.
Cause and syntax
The KEY input/output condition is raised when a record with a specified key
cannot be found. The condition can be raised only during operations on keyed
records. It is raised for the condition codes listed below.
When a LOCATE statement is used for the data set, the KEY condition for this
LOCATE statement is not raised until the next WRITE or LOCATE statement
for the file, or when the file is closed.
KEY (file-reference)
NAME condition
Status
NAME is always enabled.
Result
The named data is undefined.
Cause and syntax
The NAME input/output condition can be raised only during execution of a
data-directed GET statement with the FILE option. It is raised in any of the
following situations:
v The syntax is not correct, as described under Syntax of data-directed data
on page 330.
v The name is missing or invalid. These are some examples:
No counterpart is found in the data list.
If there is no data list, the name is not known in the block.
A qualified name is not fully qualified.
DBCS contains a byte outside the valid range '41'X to 'FE'X.
v A subscript list is missing or invalid. These are some examples:
A subscript is missing.
The number of subscripts is incorrect.
More than 10 digits are in a subscript (leading zeros ignored).
A subscript is outside the allowed range of the current allocation of the
variable.
You can retrieve the incorrect data field by using the built-in function
DATAFIELD in the ON-unit.
NAME (file-reference)
OVERFLOW condition
Status
OVERFLOW is enabled throughout the program, except within the scope of
the NOOVERFLOW condition prefix.
Result
The value of such an invalid floating-point number is undefined.
OVERFLOW
Abbreviation
OFL
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
The ERROR condition is raised.
Condition code
300
RECORD condition
Status
RECORD is always enabled.
Result
The length prefix for the specified file can be inaccurately transmitted.
Cause and syntax
The RECORD input/output condition is raised if the specified record is
truncated. The condition can be raised only during a READ, WRITE, LOCATE,
or REWRITE operation.
If the SCALARVARYING option is applied to the file (it must be applied to a
file using locate mode to transmit varying-length strings), a 2-byte length
prefix is transmitted with an element varying-length string. The length prefix is
not reset if the RECORD condition is raised. If the SCALARVARYING option is
not applied to the file, the length prefix is not transmitted. On input, the
current length of a varying-length string is set to the shorter of the record
length and the maximum length of the string.
RECORD (file-reference)
Normal return
Execution continues with the statement immediately following the one for
which RECORD was raised.
If a file is closed in an ON-unit for this condition, the results of normal return
are undefined. Exit from the ON-unit with the closed file must be achieved
with a GO TO statement.
Condition codes
20-24
SIZE condition
Status
SIZE is disabled throughout the program, except within the scope of the SIZE
condition prefix.
Result
The result of the assignment is undefined.
Cause and syntax
The SIZE computational condition is raised only when high-order (that is,
leftmost) significant binary or decimal digits are lost in an attempted
assignment to a variable or an intermediate result or in an input/output
operation. This loss can result from a conversion involving different data types,
different bases, different scales, or different precisions. Even if the SIZE
condition is disabled, any conversion that is not done inline might cause the
condition to be raised.
SIZE is raised when the size of the value being assigned to a data item exceeds
the declared (or default) size of the data item, even if this is not the actual size
of the storage that the item occupies. For example, a fixed binary item of
precision (20) occupies a fullword in storage, but SIZE is raised if a value
whose size exceeds FIXED BINARY(20) is assigned to it.
In optimized code, FOFL might be raised instead of SIZE.
Because checking sizes requires substantial overhead in both storage space and
run time, the SIZE condition is primarily used for program testing. It can be
removed from production programs. For more information about test and
production application programs, see the Programming Guide.
The SIZE condition differs from the FIXEDOVERFLOW condition in that
FIXEDOVERFLOW is raised when the size of a calculated fixed-point value
exceeds the maximum allowed by the implementation. SIZE can be raised on
assignment of a value regardless of whether or not FIXEDOVERFLOW was
raised in the calculation of that value.
If the SIZE condition is raised and it is disabled, the program is in error.
SIZE
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
Control returns to the point immediately following the point at which the
condition was raised.
Condition codes
340, 341
STORAGE condition
Status
STORAGE is always enabled.
Result
The result depends on the type of variable for which attempted storage
allocation raised the condition.
v After an ALLOCATE statement for a controlled variable, that variable's
generation is not allocated. A reference to that controlled variable results in
accessing the generation (if any) before the ALLOCATE statement.
v After an ALLOCATE statement for a based variable, the variable is not
allocated and its associated pointer is undefined.
v After an ALLOCATE built-in function for a based variable, the variable is
not allocated and the use of the associated pointer is undefined.
Cause and syntax
The STORAGE condition allows the program to gain control for the failure of
an ALLOCATE built-in function or ALLOCATE statement that attempted to
allocate BASED or CONTROLLED storage outside of an AREA. Failure of an
ALLOCATE statement in an AREA raises the AREA condition.
Failure of the AUTOMATIC built-in function does not raise the STORAGE
condition.
The ON-unit for the STORAGE condition can attempt to free allocated storage.
If the ON-unit is unable to free sufficient storage, it can provide the necessary
steps to terminate the program without losing diagnostic information.
STORAGE
Implicit action
The ERROR condition is raised.
Normal return
The ERROR condition is raised.
Condition codes
450, 451
STRINGRANGE condition
Status
STRINGRANGE is disabled throughout the program, except within the scope
of the STRINGRANGE condition prefix.
Result
The value of the specified SUBSTR is altered.
STRINGRANGE
Abbreviation
STRG
Implicit action
A message is printed and processing continues as described for normal return.
Normal return
Execution continues with a revised SUBSTR reference for which the value is
defined as follows:
Assume that the length of the source string (after execution of the ON-unit, if
specified) is k, the starting point is i, and the length of the substring is j:
v If i is greater than k, the value is the null string.
v If i is less than or equal to k, the value is that substring beginning at the mth
character, bit, widechar, or graphic of the source string and extending n
characters, bits, widechars, or graphics, where m and n are defined as
follows:
M = max( I,1 )
N = max( 0,min( J + min(I,1) - 1,K - M + 1 ))
if J is specified.
N = K - M + 1
if J is not specified.
This means that the new arguments are forced within the limits.
The values of i and j are established before entry to the ON-unit. They are not
reevaluated on return from the ON-unit.
The value of k might change in the ON-unit if the first argument of SUBSTR is
a varying-length string. The value n is computed on return from the ON-unit
using any new value of k.
Condition code
350
STRINGSIZE condition
Status
STRINGSIZE is disabled throughout the program, except within the scope of
the STRINGSIZE condition prefix.
Result
After the condition action, the truncated string is assigned to its target string.
The right-hand characters, bits, widechars, or graphics of the source string are
truncated so that the target string can accommodate the source string.
STRINGSIZE
Abbreviation
STRZ
Implicit action
A message is printed and processing continues.
Normal return
Execution continues from the point at which the condition was raised.
Condition codes
150, 151
SUBSCRIPTRANGE condition
Status
SUBSCRIPTRANGE is disabled throughout the program, except within the
scope of the SUBSCRIPTRANGE condition prefix.
Result
When SUBSCRIPTRANGE has been raised, the value of the invalid subscript is
undefined, and, hence, the reference is also undefined.
Cause and syntax
The SUBSCRIPTRANGE program-checkout condition is raised whenever a
subscript is evaluated and found to lie outside its specified bounds. The order
of raising SUBSCRIPTRANGE relative to evaluation of other subscripts is
undefined.
SUBSCRIPTRANGE
Abbreviation
SUBRG
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
Normal return from a SUBSCRIPTRANGE ON-unit raises the ERROR
condition.
Condition codes
520
TRANSMIT condition
Status
TRANSMIT is always enabled.
Result
Raising the TRANSMIT condition indicates that any data transmitted is
potentially incorrect.
Cause and syntax
The TRANSMIT input/output condition can be raised during any
input/output operation. It is raised by an uncorrectable transmission error of a
record (or of a block, if records are blocked), which is an input/output error
that could not be corrected during execution. It can be caused by a damaged
recording medium, or by incorrect specification or setup.
During input, TRANSMIT is raised after transmission of the potentially
incorrect record. If records are blocked, TRANSMIT is raised for each
subsequent record in the block.
During output, TRANSMIT is raised after transmission. If records are blocked,
transmission occurs when the block is complete rather than after each output
statement.
When a spanned record is being updated, the TRANSMIT condition is raised
on the last segment of a record only. It is not raised for any subsequent records
in the same block, although the integrity of these records cannot be assumed.
TRANSMIT (file-reference)
UNDEFINEDFILE condition
Status
UNDEFINEDFILE is always enabled.
Result
Specified files are undefined to the application program.
Cause and syntax
The UNDEFINEDFILE input/output condition is raised whenever an
unsuccessful attempt to open a file is made. If the attempt is made by means
of an OPEN statement that specifies more than one file, the condition is raised
after attempts to open all specified files.
If UNDEFINEDFILE is raised for more than one file in the same OPEN
statement, ON-units are executed according to the order of appearance (taken
from left to right) of the file names in that OPEN statement.
If UNDEFINEDFILE is raised by an implicit file opening in a data transmission
statement, upon normal return from the ON-unit, processing continues with
the remainder of the data transmission statement. If the file was not opened in
the ON-unit, the statement cannot continue and the ERROR condition is raised.
The UNDEFINEDFILE condition is raised not only by conflicting attributes
(such as DIRECT with PRINT), but also by the following:
v Block size smaller than record size (except when records are spanned)
v LINESIZE exceeding the maximum allowed
v KEYLENGTH zero or not specified for creation of INDEXED data sets
v Specifying a KEYLOC option, for an INDEXED data set, with a value
resulting in KEYLENGTH + KEYLOC exceeding the record length
v Specifying a V-format logical record length of less than 18 bytes for
STREAM data sets
v Specifying a block size that is not an integral multiple of the record size for
FB-format records
v Specifying a logical record length that is not at least 4 bytes smaller than the
specified block size for VB-format records.
UNDEFINEDFILE (file-reference)
UNDERFLOW condition
Status
UNDERFLOW is enabled throughout the program, except within the scope of
the NOUNDERFLOW condition prefix.
Result
The invalid floating-point value is set to 0 except for IEEE floating-point on
z/OS when the result is undefined.
Cause and syntax
The UNDERFLOW computational condition is raised when the magnitude of a
UNDERFLOW
Abbreviation
UFL
Implicit action
Unless the exception is raised during the evaluation of an IEEE floating-point
expression (in either binary or decimal) on z/OS, a message is printed, and
execution continues from the point at which the condition was raised; if the
exception is raised during the evaluation of an IEEE floating-point exception
on z/OS, a message is printed and the ERROR condition is raised.
Normal return
Unless the exception is raised during the evaluation of an IEEE floating-point
expression (in either binary or decimal) on z/OS, control returns to the point
immediately following the point at which the condition was raised; if the
exception is raised during the evaluation of an IEEE floating-point exception
on z/OS, the ERROR condition is raised.
Condition code
330
ZERODIVIDE condition
Status
ZERODIVIDE is enabled throughout the program, except within the scope of
the NOZERODIVIDE condition prefix.
Result
The result of a division by zero is undefined.
Cause and syntax
The ZERODIVIDE computational condition is raised when an attempt is made
to divide by zero. This condition is raised for fixed-point and floating-point
division. If the numerator of a floating-point divide is also zero, INVALIDOP is
raised.
If the ZERODIVIDE condition is raised and it is disabled, the program is in
error.
Some fixed decimal divides with large precision are done using the Decimal
Floating-Point (DFP) facility. This might cause some ZERODIVIDE exceptions
to be reported as INVALIDOP.
ZERODIVIDE
Abbreviation
ZDIV
Implicit action
A message is printed and the ERROR condition is raised.
Normal return
The ERROR condition is raised.
Condition code
320
Related information:
INVALIDOP condition on page 390
When using the PL/I multithreading facility, the invoking procedure does not
relinquish control to the invoked procedure. Instead, an additional flow of control
is established so that both procedures are executed concurrently. The execution of
such concurrent procedures is called asynchronous flow.
With the PL/I multithreading facility, parts of a PL/I program can be executed
asynchronously in multiple threads. A thread is a unit of work that competes for
the resources of the computing system. A thread is not the equivalent of a task in
OS PL/I. Except for the main thread in a program, a thread is always independent
of and unrelated to other threads in the program. When a procedure invokes
another procedure as a thread, this action is known as attaching or creating the
thread.
There is normally one application thread per process. Multiple threads can be
attached (created) for these purposes:
v Perform a piece of work in a shorter elapsed time. Such applications can be
batch applications that are not interacting with the user. For example, one
procedure could attach a thread which would compile a PL/I program.
v Perform high response parts of a program in one thread and I/O parts in
another thread, and typical response parts in a third.
v Use computing system resources that might be idle. These resources can include
I/O devices as well as the CPUs.
v Implement realtime multiuser applications where the response time is critical.
v Isolate independent pieces of work for reliability. That is, the failure of a part of
a job can be isolated while other independent parts are processed.
Note: Operating system services must not be directly used when PL/I provides
the appropriate function.
Creating a thread
A thread is a unit of work that competes for the resources of the computing
system. When a procedure invokes another procedure as a thread, this action is
known as attaching, or creating the thread.
v A thread is an independent unit of work.
Copyright IBM Corp. 1999, 2016 403
Creating a thread
ATTACH statement
A thread is attached (or created) by the execution of the ATTACH statement. You
can specify explicit characteristics for the thread if the defaults are not what you
want.
ATTACH entry-reference
THREAD (task-reference)
;
ENVIRONMENT ( )
TSTACK(expression)
entry
Specifies the name of a limited entry variable or the name of an external entry
or level-1 procedure. It cannot be the name of an internal procedure or a
fetchable procedure. The ATTACHed entry must be declared as having no
parameters or as having exactly one BYVALUE POINTER parameter. However,
you can fetch a procedure, assign it to a limited entry variable, and then attach
the entry variable as a thread.
Arguments can be passed to the new thread just as you would pass arguments
to a synchronous entry in a CALL statement.
THREAD (task reference)
Specifies the name of a task variable that becomes associated with the thread.
The task variable can then be used to refer to the thread.
Unless explicitly declared, the named variable is given a contextual declaration.
If the THREAD option is not specified, the attached thread cannot be stopped
or waited upon by another thread.
If a thread is attached with the THREAD option, you must use the DETACH
statement to detach the thread to free all the system resources associated with
the thread.
Operating system services must not be used directly to create a thread.
ENVIRONMENT (abbrev: ENV)
Specifies environmental characteristics and is usually operating system
dependent.
TSTACK (expression)
On Intel, specifies the size of the stack to be used for the attached thread. The
expression should be FIXED BINARY(31,0). If the stack size is not specified,
the runtime default will be used.
On z/OS, TSTACK is ignored, and the size of the stack is determined by LE.
Examples
attach input (File1);
Terminating a thread
Execution of the END, EXIT, and STOP statements might terminate a thread. The
ERROR condition, when raised, might also terminate a thread.
The FINISH condition is raised only in the thread initiating program termination.
Any ON-units established within the thread are given control before the thread
actually terminates.
Except as noted above, when a thread terminates, no other threads are terminated,
unless the thread being terminated is the main thread. In that case, all other
threads are stopped and terminated before the main thread is terminated.
When a thread terminates, only its stack space is released. All other resources such
as allocated storage, open files, and so on remain intact. The user must ensure that
any resources that a thread has acquired are released and open files are closed,
unless they are needed by other threads that are still active.
When the main thread terminates, all resources are released and files are closed.
Canceling a thread
You can cancel a thread by using the CANCEL THREAD statement.
THREAD task-reference
The THREAD option specifies the task-reference task variable of the thread,
upon which the process is canceling. The task variable is generated during the
ATTACH of the thread.
THREAD (task-reference)
The THREAD option specifies the thread upon which the process is waiting.
The current thread is suspended until the specified thread terminates. As soon
as the specified thread has terminated, the current thread resumes.
Detaching a thread
The DETACH statement should be used to free the system resources associated
with a thread that was attached with the THREAD option.
THREAD (task-reference)
The THREAD option specifies the thread to be detached.
Normally, this statement would be executed immediately after the WAIT statement
for the terminating thread.
Condition handling
When a new thread is created, no ON-units are assumed to be established. The
ON-units that are in effect at the time a thread is created are not inherited by the
new attached thread. Conditions that occur within a thread are handled within the
thread and are not handled across thread boundaries.
For example, assume that thread A opens file F; then A creates thread T; T then
causes the ENDFILE condition to be raised. If an ON ENDFILE condition is not
established in thread T itself, the ERROR condition is raised in T, and the usual
condition handling takes place all within thread T. Whether or not A has
established ON-units for ENDFILE or ERROR does not affect the execution of
thread T.
TASK
A task variable is associated with a thread by the task reference in the THREAD
option of the ATTACH statement creating the thread. A task variable is active if it
is associated with a thread that is active. A task variable must be allocated before it
is associated with a thread and must not be freed while it is active. An active task
variable cannot be associated with another thread.
THREADID ( x )
The value used by this built-in function can be used as a parameter to system
functions such as DosSetPriority, but it should not be used as a parameter to
DosKillThread.
x Task reference. The value of x should have been set previously in the THREAD
option of the ATTACH statement.
For example, if automatic variables in the attaching thread are shared with the
attached thread, the attaching block must not terminate until the attached thread
has finished using the shared variables.
All allocated storage, unless freed explicitly, is not freed until program termination.
If a thread (other than MAIN) opens a file, it must be closed before that thread
terminates.
A file opened in a MAIN thread is not closed until it is explicitly closed or the
program ends. Except for the Language Environment message file on z/OS, if you
do not serialize your file usage, you might get unpredictable results, possibly
including abends.
Serialization is the responsibility of the user. See Sharing data between threads.
The message file and the display statement are automatically serialized by PL/I.
With PL/I, you can develop both 31-bit and 64-bit applications. When you develop
64-bit applications, you must be aware that the argument and return types of some
built-in functions are different from those under 31-bit. These arguments and
return values are of type size_t. Such size_t arguments represent the size of a piece
of storage.
If the LP(32) compiler option is in effect, size_t is FIXED BIN(31); if the LP(64)
compiler option is in effect, size_t is FIXED BIN(63).
BUILTIN attribute
The BUILTIN attribute specifies that the name is a built-in function,
pseudovariable, or a subroutine.
BUILTIN
Example
3 B: Begin;
Declare Sqrt builtin;
Z = Sqrt(P);
end B;
end A;
1 Sqrt is a programmer-defined name.
name
,
( )
argument
CALL name ;
( )
,
argument
Aggregate arguments
All built-in functions and pseudovariables that can have arguments can have array
arguments (if more than one is an array, the bounds must be identical).
v ADDR, ALLOCATION, CURRENTSIZE, SIZE, STRING, and the array-handling
functions return an element value.
v Under the compiler option USAGE(UNSPEC(ANS)), UNSPEC returns an
element value; Under USAGE(UNSPEC(IBM)), it returns an array of values.
v All other functions return an array of values.
This example results in A(1) having the value A and A(2) having the value CD.
The built-in functions and pseudovariables that can accept structure or union
arguments are listed in Table 58.
Table 58. Built-in functions and pseudovariables that accept structure or union arguments
Built-in functions and pseudovariables
ADDR CURRENTSIZE PRESENT XMLCHAR
ADDRDATA INDICATORS SIZE
ALLOCATION LOCATION STRING
BITLOCATION OMITTED UNSPEC1
1. UNSPEC may be applied to a structure or union only if the compiler option
USAGE(UNSPEC(ANS)) is in effect.
Most arguments contain errors. An error in a given argument can accumulate over
several steps before the evaluation of a function. Even data fresh from input
conversion can contain errors. The effect of argument error on the accuracy of a
result depends entirely on the nature of the mathematical function, and not on the
algorithm that computes the result. This book does not discuss argument errors of
this type.
The mathematical built-in functions that are implemented using inline machine
instructions produce results of different accuracy.
Only full function names are listed in these tables. Existing abbreviations are
provided in the sections that describe each built-in function, subroutine, and
pseudovariable.
v N is the maximum precision for FIXED DECIMAL. This is the value N2 from the
compiler option LIMITS(FIXEDDEC(N1,N2)).
Table 59 lists the arithmetic built-in functions and a short description of each.
Some of the arithmetic functions derive the data type of their results from one or
more arguments. When the data types of the arguments differ, they are converted
as described in Chapter 4, Data conversion, on page 77.
Table 59. Arithmetic built-in functions
Function Description
ABS Calculates the absolute value of a value
CEIL Calculates the smallest integer value greater than or equal to a value
COMPLEX Returns the complex number with given real and imaginary parts
CONJG Returns the complex conjugate of a value
FLOOR Calculates the largest integer value less than or equal to a value
IMAG Returns the imaginary part of a complex number
MAX Calculates the maximum of 2 or more values
MIN Calculates the minimum of 2 or more values
MOD Returns the modular equivalent of the remainder of one value divided
by another
RANDOM Returns a pseudo-random value
REAL Returns the real part of a complex number
REM Calculates the remainder of one value divided by another
ROUND Rounds a value at a specified digit
ROUNDDEC Rounds a decimal value at a specified digit
SIGN Returns a -1, 0 or 1 if a value is negative, zero, or positive, respectively
TRUNC Calculates the nearest integer for value rounded towards zero
Any conversion of arguments required for these functions is noted in the function
description. Table 60 lists the array-handling built-in functions.
Table 60. Array-handling built-in functions
Function Description
ALL Calculates the bitwise and of all the elements of an array
ANY Calculates the bitwise or of all the elements of an array
DIMENSION Returns the number of elements in a dimension of an array
The PLIFILL, PLIMOVE, and PLIOVER built-in subroutines are also useful in
managing buffers. Table 61 lists the buffer-management built-in functions.
Table 61. Buffer-management built-in functions
Function Description
BASE64DECODE8 Decodes the source buffer from base 64 that is encoded as
UTF-8. Returns a size_t value that indicates the number of
bytes that are written into the target buffer.
BASE64DECODE16 Decodes the source buffer from base 64 that is encoded as
UTF-16. Returns a size_t value that indicates the number of
bytes that are written into the target buffer.
BASE64ENCODE8 Encodes the source buffer into base 64 that is encoded as
UTF-8. Returns a size_t value that indicates the number of
bytes that are written into the target buffer.
BASE64ENCODE16 Encodes the source buffer into base 64 that is encoded as
UTF-16. Returns a size_t value that indicates the number of
bytes that are written into the target buffer.
CHECKSUM Returns the checksum value for a specified buffer.
COMPARE Compares two buffers.
HEXDECODE Decodes a source buffer from base 16 that is encoded in
the character set specified by the ASCII/EBCDIC
suboption of the DEFAULT compiler option. Returns a
size_t value that indicates the number of bytes that are
written into the target buffer.
HEXDECODE8 Decodes a source buffer from base 16 that is encoded in
UTF-8. Returns a size_t value that indicates the number of
bytes that are written into the target buffer.
HEXIMAGE Returns a character string that is the hexadecimal
representation of a buffer.
MEMCONVERT Converts the data in a source buffer from the specified
source codepage to a specified target codepage. Stores the
result in a target buffer. Returns a size_t value that
indicates the number of bytes that are written to the target
buffer.
Use of these functions is valid only within the scope of an ON-unit or dynamic
descendant for:
v the condition specific to the built-in function
v the ERROR or FINISH condition when raised as an implicit action
All other uses are out of context.
Table 62. Condition-handling built-in functions
Function Description
DATAFIELD Returns the value of a string that raised the NAME condition.
ONAREA Returns the name of the AREA reference for which an AREA condition
is raised.
ONCHAR Returns the value of a character that caused a conversion condition.
ONCODE Returns the condition code value.
ONCONDCOND Returns the name of CONDITION condition being processed.
ONCONDID Returns a number which identifies a particular condition.
ONCOUNT Returns the number of outstanding conditions.
ONFILE Returns the name of a file for which a condition is raised.
ONGSOURCE Returns the value of a graphic string that caused a conversion condition.
ONKEY Returns the key of a record that raised a condition.
ONLINE Returns the line number from the source in which a condition occurred.
ONLOC Returns the name of the procedure in which a condition occurred.
ONOFFSET Returns the offset within a block in which a condition occurred.
ONSOURCE Returns the value of a string that caused a conversion condition.
ONWCHAR Returns the value of a widechar that caused a conversion condition.
ONWSOURCE Returns the value of a widechar string that caused a conversion
condition.
Some of these built-in functions allow you to specify the date/time patterns to be
used. Table 63 lists the supported date/time built-in functions. Table 64 on page
417 lists the supported date/time patterns.
The time zone and accuracy for these functions are system dependent.
Lilian format: The Lilian format, named in honor of Luigi Lilio, the creator of the
Gregorian calendar, represents a date as the number of days or seconds from the
beginning of the Gregorian calendar. This format is useful for performing
calculations involving elapsed time.
The Lilian format counts days that have elapsed since October 14, 1582; day one is
Friday, October 15, 1582. For example, 16 May 1988 is 148138 Lilian days. The valid
range of Lilian days is 1 to 3,074,324 (15 October 1582 to 31 December 9999).
For the number of elapsed seconds, the Lilian format counts elapsed seconds
starting at 00:00:00 14 October 1582. For example, 00:00:01 on 15 October 1582 is
86,401 (24*60*60+1) Lilian seconds, and 19:01:01 16 May 1988 is 12,799,191,661
Lilian seconds. The valid range of Lilian seconds is 86,400 to 265,621,679,999.999
(23:59:59:999 31 December 9999) seconds.
Table 63. Date/time built-in functions
Function Description
DATE Returns the current date in the pattern YYMMDD.
DATETIME Returns the current date and time in the user-specified pattern or in the
default pattern YYYYMMDDHHMISS999.
DAYS Returns the number of days corresponding to a date/time pattern string,
or the number of days for today's date.
DAYSTODATE Converts a number of days to a date/time pattern string.
DAYSTOSECS Converts a number of days to a number of seconds.
JULIANTOSMF Converts a date from Julian format to SMF format.
REPATTERN Takes a value holding a date in one pattern and returns that value
converted to a date in a second pattern.
SECS Returns the number of seconds corresponding to a date/time pattern
string, or the number of seconds for today's date.
SECSTODATE Converts a number of seconds to a date/time pattern string.
SECSTODAYS Converts a number of seconds to a number of days.
SMFTOJULIAN Converts a date from SMF format to Julian format.
TIME Returns the current time in the pattern HHMISS999.
TIMESTAMP Returns the current time in the pattern YYYY-MM-DD-HH.MI.SS.999999.
UTCDATETIME Returns the current Coordinated Universal Time (UTC) in the pattern
YYYYMMDDHHMISS999.
UTCSECS Returns the current Coordinated Universal Time (UTC) in the Lilian
format in seconds.
VALIDDATE Indicates if a string holds a valid date.
WEEKDAY Returns the day of the week corresponding to the current day or
specified DAYS value.
Y4DATE Takes a date value with the pattern 'YYMMDD' and returns the date
value with the two-digit year widened to a four-digit year.
Note: For the three-letter month patterns, the uppercase/lowercase characters must
correspond exactly.
The only supported patterns that use any of HH, MI, SS, 999, or 999999 are
YYYYMMDDHHMISS999 and YYYY-MM-DD-HH.MI.SS.999999.
Table 64. Date/time patterns
Four-digit years Two-digit years
When the day is omitted from a pattern, it is assumed to have the value 1. If the
month and day are both omitted, they are also assumed to have the value 1.
When using MMM, the date must be written in three uppercase letters; when
using Mmm, the date must be written with the first letter in uppercase, and the
letters following in lowercase.
On input, the date value for the patterns "without zeros" may be less than 8
characters, for example, the date 20 Jan 2008 may be specified as 8-1-20 to match
the pattern "ZY-ZM-ZD". On output, the string produced for one of these patterns
will always be 8 characters with any suppressed zeros compensated by trailing
blanks.
Pseudovariables
Pseudovariables represent receiving fields. They cannot be nested. This topic lists
the built-in pseudovariables.
Subroutines
Built-in subroutines perform miscellaneous operations that do not necessarily
return a result as built-in functions do.
Table 77. Built-in subroutines
Function Description
LOCNEWSPACE Allocates space for the variable type described by the LOCATES
attribute.
LOCNEWVALUE Allocates space for the variable type described by the LOCATES
attribute that is associated with the offset and assigns value to that area.
The following example is valid even though Bin is an abbreviation of the Binary
built-in function.
dcl Binary file;
X = Bin (var, 6,3);
Note 1: Some arguments or return values are of type size_t. If the LP(32) compiler
option is in effect, size_t is FIXED BIN(31); if the LP(64) compiler option is in effect,
size_t is FIXED BIN(63).
ABS
ABS returns the absolute value of x. It is the positive value of x.
ABS(x)
x Expression.
The mode of the result is REAL. The result has the base, scale, and precision of x,
except when x is COMPLEX FIXED(p,q). In the latter case, the result is REAL
FIXED(min(n,p+1),q) where n is N for DECIMAL and M for BINARY.
ACOS
ACOS returns a real floating-point value that is an approximation of the inverse
(arc) cosine in radians of x.
ACOS(x)
ADD
ADD returns the sum of x and y with a precision specified by p and q. The base,
scale, and mode of the result are determined by the rules for expression evaluation
unless overruled by the PRECTYPE compiler option.
ADD(x,y,p )
,q
x and y
Expressions.
p Restricted expression. It specifies the number of digits to be maintained
throughout the operation.
q Restricted expression specifying the scaling factor of the result. For a
fixed-point result, if q is omitted, a scaling factor of zero is the default. For a
floating-point result, q must be omitted.
ADD can be used for subtraction by prefixing a minus sign to the operand to be
subtracted.
ADDR
ADDR returns the pointer value that identifies the generation of x.
ADDR(x)
ADDRDATA
ADDRDATA returns the pointer value that identifies the generation of x.
ADDRDATA(x)
x Reference.
ADDRDATA behaves the same as the ADDR built-in function except in the
following instance:
v When applied to a varying string, ADDRDATA returns the address of the first
data byte of the string (rather than of the length field).
v When applied to an OFFSET reference with the LOCATES attribute and implicit
AREA qualification:
If the OFFSET reference is not null, ADDRDATA returns the address of the
located data.
If the OFFSET reference is null, ADDRDATA returns SYSNULL.
ALL
ALL returns a bit string in which each bit is 1 if the corresponding bit in each
element of x exists and is 1. The length of the result is equal to that of the longest
element.
ALL(x)
ALLCOMPARE
ALLCOMPARE(x, y, z) returns a BIT(1) value that indicates the result of comparing
two structures.
ALLCOMPARE (x,y )
,z
x Structure reference.
y Structure reference.
z A CHAR(2) constant. When uppercased, the constant must have one of these
values: EQ, LE, LT, GT, GE, or NE. If you do not specify z, EQ is the default
value.
EQ Equal to
LE Less than or equal to
LT Less than
GT Greater than
GE Greater than or equal to
NE Not equal to
ALLOC31
ALLOC31 allocates storage of size n in heap storage below the bar and returns the
pointer to the allocated storage.
ALLOC31 (n)
n
Expression. Nonnegative value that represents the storage size to be allocated.
If necessary, n is converted to type size_t 1.
If the requested amount of storage is not available, the STORAGE condition is
raised.
ALLOCATE
ALLOCATE allocates storage of size n in heap storage and returns the pointer to
the allocated storage. You can also use ALLOCATE to allocate the specified size in
the specified area.
ALLOCATE (n, )
x
Abbreviation: ALLOC
n Expression. Nonnegative value that represents the storage size to be allocated.
If necessary, n is converted to type size_t 1.
If the requested amount of storage is not available, the STORAGE condition is
raised.
x AREA reference. When you specify ALLOCATE(n, x), the specified number of
bytes n is allocated within that area. The number is rounded up to a multiple
of 8.
If there is insufficient space within the specified area, the AREA condition is
raised.
ALLOCATION
ALLOCATION returns a FIXED BINARY(31,0) specifying the number of
generations that can be accessed in the current program for x.
ALLOCATION(x)
Abbreviation: ALLOCN
x Level-1 unsubscripted controlled variable.
ALLOCSIZE
ALLOCSIZE returns a FIXED BIN(31,0) value giving the amount of storage
allocated with a specified pointer. To use this built-in function, you must also
specify the CHECK(STORAGE) compile-time option.
ALLOCSIZE(p)
p Pointer expression.
ALLOCSIZE returns 0 if the pointer does not point to the start of a piece of
allocated storage.
Note that the pointer passed to ALLOCSIZE is "rounded down" to the nearest
doubleword and that rounded value is compared against all allocated addresses
when similarly rounded down.
ANY
ANY returns a bit string in which each bit is 1 if the corresponding bit in any
element of x exists and is 1. The length of the result is equal to that of the longest
element.
ANY(x)
ASIN
ASIN returns a real floating-point value that is an approximation of the inverse
(arc) sine in radians of x.
ASIN(x)
ATAN
ATAN returns a floating-point value that is an approximation of the inverse (arc)
tangent in radians of x or of a ratio x/y.
ATAN(x )
,y
x and y
Expressions.
If x alone is specified, the result has the base and precision of x, and is in the
range:
-/2 < ATAN(x) < /2
If x and y are specified, each must be real. An error exists if x and y are both
zero. The result for all other values of x and y has the precision of the longer
argument, a base determined by the rules for expressions, and a value given
by:
ATAND
ATAND returns a real floating-point value that is an approximation of the inverse
(arc) tangent in degrees of x or of a ratio x/y.
ATAND(x )
,y
x and y
Expressions.
If x alone is specified it must be real. The result has the base and precision of
x, and is in the range:
-90 < ATAND(x) < 90
If x and y are specified, each must be real. The value of the result is given by:
(180/) * ATAN(x,y)
For argument requirements and attributes of the result, see ATAN on page 443.
ATANH
ATANH returns a floating-point value that has the base, mode, and precision of x,
and is an approximation of the inverse (arc) hyperbolic tangent of x.
ATANH(x)
x Expression. ABS(x)<1.
AUTOMATIC
AUTOMATIC allocates storage of size n automatic storage and returns the pointer
to the allocated storage.
AUTOMATIC(n)
Abbreviation: AUTO
n Expression. n must be nonnegative. If necessary, n is converted to type size_t 1.
The storage acquired cannot be explicitly freed; the storage is automatically freed
when the block terminates.
AVAILABLEAREA
AVAILABLEAREA returns a size_t 1 value that indicates the size of the largest
single allocation that can be obtained from the area x.
AVAILABLEAREA(x)
Example
dcl Uarea area(1000);
dcl Pz ptr;
dcl C99z char(99) varyingz based(Pz);
dcl (SizeBefore, SizeAfter) fixed bin(31);
SizeBefore = availablearea(Uarea); /* returns 1000 */
Alloc C99z in(Uarea);
SizeAfter = availablearea(Uarea); /* returns 896 */
dcl C9 char(896) based(Pz);
Alloc C9 in(Uarea);
BASE64DECODE8
BASE64DECODE8 decodes the source buffer from base 64 that is encoded as
UTF-8. It returns a size_t 1 value that indicates the number of bytes that are written
into the target buffer.
BASE64DECODE8(p,m,q,n)
If the address of the target buffer is zero, the number of bytes that would be
written is returned. If the target buffer is not large enough, a value of -1 is
returned. If the target buffer is large enough, the number of bytes that is written to
the buffer is returned.
This function is the reverse of the function BASE64ENCODE8 and expects that the
base 64 source was encoded by using the same convention that the
BASE64ENCODE8 function uses. See Convention for encoding a source buffer
into base 64 as UTF-8 on page 450 for details. If other conventions were used, the
results are unpredictable.
BASE64DECODE16
BASE64DECODE16 decodes the source buffer from base 64 that is encoded as
UTF-16. It returns a size_t 1 value that indicates the number of bytes that are
written into the target buffer.
BASE64DECODE16(p,m,q,n)
If the address of the target buffer is zero, the number of bytes that would be
written is returned. If the target buffer is not large enough, a value of -1 is
returned. If the target buffer is large enough, the number of bytes that is written to
the buffer is returned.
This function is the reverse of the function BASE64ENCODE16 and expects that
the base 64 source was encoded by using the same convention that the
BASE64ENCODE16 function uses. See Convention for encoding a source buffer
into base 64 as UTF-16 on page 451 for details. If other conventions were used,
the results are unpredictable.
BASE64ENCODE8
BASE64ENCODE8 encodes the source buffer into base 64 that is encoded as UTF-8.
It returns a size_t 1 value that indicates the number of bytes that are written into
the target buffer.
BASE64ENCODE8(p,m,q,n)
If the address of the target buffer is zero, the number of bytes that would be
written is returned. If the target buffer is not large enough, a value of -1 is
returned. If the target buffer is large enough, the number of bytes that is written to
the buffer is returned.
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
Each 6 bits of the source is converted to the corresponding UTF-8 "digit" in this
base 64 string. If the source length in bits is not a multiple of 6, the result
concludes with one or two = symbols as needed, and the = symbol is UTF-8.
The source buffer is treated as a bit string, so the result in the target buffer varies
with the code page of the source. In particular, when the source is in EBCDIC, the
result differs when the source is in ASCII.
The following table shows the example of the sources and the corresponding
results when converting source buffer into base 64 that is encoded as UTF-8 by
using BASE64ENCODE8:
Table 78. Example of encoding a source buffer into base 64 as UTF-8
Source length Source value Result length Result value
6 please A 8 UTF8(cGxlYXNl)
5 pleasA 8 UTF8(cGxlYXM=)
4 pleaA 8 UTF8(cGxlYQ==)
6 pleaseE 8 UTF8(l5OFgaKF)
5 pleasE 8 UTF8(l5OFgaI=)
4 pleaE 8 UTF8(l5OFgQ==)
BASE64ENCODE16
BASE64ENCODE16 encodes the source buffer into base 64 that is encoded as
UTF-16. It returns a size_t 1 value that indicates the number of bytes that are
written into the target buffer.
BASE64ENCODE16(p,m,q,n)
If the address of the target buffer is zero, the number of bytes that would be
written is returned. If the target buffer is not large enough, a value of -1 is
returned. If the target buffer is large enough, the number of bytes that is written to
the buffer is returned.
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/
Each 6 bits of the source is converted to the corresponding UTF-16 "digit" in the
base 64 string. If the source length in bits is not a multiple of 6, the result
concludes with one or two = symbols as needed, and the = symbol is UTF-16.
The source buffer is treated as a bit string, so the result in the target buffer varies
with the code page of the source. In particular, when the source is in EBCDIC, the
result differs when the source is in ASCII.
The following table shows examples of the sources and the corresponding results
when converting the source buffer into base 64 that is encoded as UTF-16 by using
BASE64ENCODE16.
Table 79. Example of encoding a source buffer into base 64 as UTF-16
Source
length Source value Result length Result value
6 pleaseA 16 WCHAR(cGxlYXNl)
5 pleasA 16 WCHAR(cGxlYXM=)
4 pleaA 16 WCHAR(cGxlYQ==)
6 pleaseE 16 WCHAR(l5OFgaKF)
5 pleasE 16 WCHAR(l5OFgaI=)
4 pleaE 16 WCHAR(l5OFgQ==)
BETWEEN
BETWEEN returns a bit(1) value that indicates whether x is in the closed interval
as defined by a and b.
BETWEEN(x,a,b)
x, a, and b
Expressions. They must be either all ORDINAL with the same type or all
computational.
BETWEEN(x,a,b) is equivalent to the test (a <= x) & (x <= b). Thus, if any of the
arguments are numeric, they must all be REAL.
BETWEENEXCLUSIVE
The BETWEENEXCLUSIVE built-in function returns a bit(1) value that indicates
whether the first argument x is in the open interval as defined by the second
argument a and the third argument b.
BETWEENEXCLUSIVE(x,a,b)
x, a, b
Expressions. They must be either all ORDINAL with the same type or all
computational.
BETWEENLEFTEXCLUSIVE
The BETWEENLEFTEXCLUSIVE built-in function returns a bit(1) value that
indicates whether the first argument x is in the left-open interval as defined by the
second argument a and the third argument b.
BETWEENLEFTEXCLUSIVE(x,a,b)
x, a, b
Expressions. They must be either all ORDINAL with the same type or all
computational.
BETWEENRIGHTEXCLUSIVE
The BETWEENRIGHTEXCLUSIVE built-in function returns a bit(1) value that
indicates whether the first argument x is in the right-open interval as defined by
the second argument a and the third argument b.
BETWEENRIGHTEXCLUSIVE(x,a,b)
x, a, b
Expressions. They must be either all ORDINAL with the same type or all
computational.
BINARY
BINARY returns the binary value of x, with a precision specified by p and q. The
result has the mode and scale of x.
BINARY(x )
,p
,q
Abbreviation: BIN
x Expression.
p Restricted expression. Specifies the number of digits to be maintained
throughout the operation; it must not exceed the implementation limit.
q Restricted expression. It specifies the scaling factor of the result. For a
fixed-point result, if p is given and q is omitted, a scaling factor of zero is the
default. For a floating-point result, q must be omitted.
If both p and q are omitted, the precision of the result is determined from the rules
for base conversion.
BINARYVALUE
BINARYVALUE converts x, which can be a pointer, offset, or ordinal, to an integer.
The function returns a FIXED BIN value that is the converted value.
If x is a pointer, the return value has type size_t 1. If x is an ordinal, the return
value has type FIXED BIN(31). If x is an offset, the return value has type FIXED
BIN(31) under OFFSETSIZE(4) and FIXED BIN(63) under OFFSETSIZE(8).
BINARYVALUE(x)
Abbreviation: BINVALUE
x Expression
BIT
BIT returns a result that is the bit value of x, and has a length specified by y.
BIT(x )
,y
x Expression.
y Expression. If necessary, y is converted to a real fixed-point binary value. If y is
omitted, the length is determined by the rules for type conversion. If y = 0, the
result is the null bit string. y must not be negative.
BITLOCATION
BITLOCATION returns a FIXED BINARY(31,0) result that is the location of bit x
within the byte that contains x. The value returned is always between 0 and 7 (0
value 7).
BITLOCATION(x)
Abbreviation: BITLOC
x Reference of type unaligned bit. If x does not have type unaligned bit, a value
of 0 is returned.
x must not be subscripted.
BOOL
BOOL returns a bit string that is the result of the Boolean operation z, on x and y.
The length of the result is equal to that of the longer operand, x or y.
BOOL(x,y,z)
x and y
Expressions. x and y are converted to bit strings, if necessary. If x and y are of
different lengths, the shorter is padded on the right with zeros to match the
longer.
z Expression. z is converted to a bit string of length 4, if necessary. When a bit
from x is matched with a bit from y, the corresponding bit of the result is
specified by a selected bit of z, as follows:
x y Result
0 0 bit 1 of z
0 1 bit 2 of z
1 0 bit 3 of z
1 1 bit 4 of z
BYTE
BYTE is a synonym for CHARVAL.
Related information:
CHARVAL on page 471
CDS
CDS returns a FIXED BINARY(31) value that indicates if the old and current
values in a compare double and swap were equal.
CDS(p,q,x)
CDS compares the "current" and "old" values. If they are equal, the "new" value is
copied over the "current", and a value of 0 is returned. If they are unequal, the
"current" value is copied over the "old", and a value of 1 is returned.
On z/OS, the CDS built-in function implements the CDS instruction. For a detailed
description of this function, read the appendices in the Principles of Operations
manual.
On Intel, the CDS built-in function uses the Intel cmpxchg8 instruction in the same
manner that the CS built-in function uses the cmpxchg4 instruction.
CEIL
CEIL determines the smallest integer value greater than or equal to x, and assigns
this value to the result.
CEIL(x)
x Real expression.
The result has the mode, base, scale, and precision of x, except when x is
fixed-point with precision (p,q). The precision of the result is then given by:
(min(N,max(p-q+1,1)),0)
CENTERLEFT
CENTERLEFT returns a string that is the result of inserting string x in the center
(or one position to the left of center) of a string with length y and padded on the
left and on the right with the character z as needed.
CENTERLEFT (x,y )
CENTRELEFT ,z
Abbreviation: CENTER
x Expression that is converted to character.
y Expression that is converted to FIXED BINARY(31,0).
z Optional expression. If specified, z must be CHARACTER(1) NONVARYING
type.
Example
dcl Source char value(Feel the Power);
dcl Target20 char(20);
dcl Target21 char(21);
CENTRELEFT
CENTRELEFT is a synonym for CENTERLEFT.
Abbreviation: CENTRE
Related information:
CENTERLEFT on page 464
CENTERLEFT returns a string that is the result of inserting string x in the center
(or one position to the left of center) of a string with length y and padded on the
left and on the right with the character z as needed.
CENTERRIGHT
CENTERRIGHT returns a string that is the result of inserting string x in the center
(or one position to the right of center) of a string with length y and padded on the
left and on the right with the character z as needed.
CENTERRIGHT (x,y )
CENTRERIGHT ,z
Example
dcl Source char value(Feel the Power);
dcl Target20 char(20);
dcl Target21 char(21);
CENTRERIGHT
CENTRERIGHT is a synonym for CENTERRIGHT.
Related information:
CENTERRIGHT on page 466
CENTERRIGHT returns a string that is the result of inserting string x in the center
(or one position to the right of center) of a string with length y and padded on the
left and on the right with the character z as needed.
CHARACTER
CHARACTER returns the character value of x, with a length specified by y.
CHARACTER also supports conversion from graphic to character type.
CHARACTER(x )
,y
Abbreviation: CHAR
x Expression.
x must have a computational type.
When x is nongraphic, CHARACTER returns x converted to character.
When x is GRAPHIC, CHARACTER returns x converted to SBCS characters. If
a DBCS character cannot be translated to an SBCS equivalent, the
CONVERSION condition is raised.
The values of x are not checked.
y Expression. If necessary, y is converted to a real fixed-point binary value.
If y is omitted, the length is determined by the rules for type conversion.
y cannot be negative.
If y = 0, the result is the null character string.
CHARGRAPHIC
CHARGRAPHIC converts a GRAPHIC (DBCS) string x to a mixed character string
with a length specified by y.
CHARGRAPHIC(x )
,y
Abbreviation: CHARG
x Expression.
x must be a GRAPHIC string.
y Expression. If necessary, y is converted to a real fixed-point binary value.
If y is omitted, the length is determined by the rules for type conversion.
y cannot be negative.
Example 1
Example 2
CHARVAL
CHARVAL returns the CHARACTER(1) value corresponding to an integer.
CHARVAL ( n )
CHARVAL(n) has the same bit value as n (that is, UNSPEC(CHARVAL(n)) is equal
to UNSPEC(n)), but it has the attributes CHARACTER(1).
CHECKSTG
CHECKSTG returns a bit(1) value which indicates whether a specified pointer
value is the start of a piece of uncorrupted allocated storage. If no pointer value is
supplied, CHECKSTG determines whether all allocated storage is uncorrupted. To
use this built-in function, you must also specify the CHECK(STORAGE)
compile-time option.
CHECKSTG( )
p
p Pointer expression.
When an allocation is made, it is followed by eight extra bytes which are set to
'ff'x. The allocation is considered uncorrupted if those bytes have not been altered.
The pointer expression must point to storage allocated for a BASED variable.
CHECKSUM
CHECKSUM returns an UNSIGNED FIXED BIN(32) value that is the checksum
value for a specified buffer.
CHECKSUM(q,n)
COLLATE
COLLATE returns a CHARACTER(256) string comprising the 256 possible
CHARACTER(1) values one time each in the collating order.
COLLATE
()
COMPARE
COMPARE compares the z bytes of two buffers at the addresses x and y.
COMPARE(x,y,z)
x and y
Expressions. Both must have the POINTER or OFFSET type. If OFFSET, the
expression must be declared with the AREA qualification.
z Expression. It is converted to size_t 1.
Example
dcl Result fixed bin;
dcl 1 Str1,
2 B fixed bin(31),
2 C pointer,
2 * union,
3 D char(4),
3 E fixed bin(31),
3 *,
4 * char(3),
4 F fixed bin(8) unsigned,
2 * char(0);
dcl 1 Template nonasgn static,
2 * fixed bin(31) init(16), /* X */
2 * pointer init(null()),
2 * char(4) init(),
2 * char(0);
COMPLEX
COMPLEX returns the complex value x + yI.
COMPLEX(x,y)
Abbreviation: CPLX
x and y
Real expressions.
If x and y differ in base, the decimal argument is converted to binary. If they
differ in scale, the fixed-point argument is converted to floating-point. The
result has the common base and scale.
In this example, (p1,q1) and (p2,q2) are the precisions of x and y, respectively, and
N is the maximum number of digits allowed.
After any necessary conversions have been performed, if the arguments are
floating-point, the result has the precision of the longer argument.
CONJG
CONJG returns the conjugate of x, that is, the value of the expression with the sign
of the imaginary part reversed.
CONJG(x)
x Expression.
If x is real, it is converted to complex. The result has the base, scale, mode, and
precision of x.
COPY
COPY returns a string consisting of y concatenated copies of the string x.
COPY(x,y)
x Expression.
x must have a computational type and should have a string type. If not, it is
converted to character.
y An integer expression with a nonnegative value. It specifies the number of
repetitions. It must have a computational type and is converted to FIXED
BINARY(31,0).
If y is zero, the result is a null string.
Example
COS
COS returns a floating-point value that has the base, precision, and mode of x, and
is an approximation of the cosine of x.
COS(x)
COSD
COSD returns a real floating-point value that has the base and precision of x, and
is an approximation of the cosine of x.
COSD(x)
COSH
COSH returns a floating-point value that has the base, precision, and mode of x,
and is an approximation of the hyperbolic cosine of x.
COSH(x)
x Expression.
COUNT
COUNT returns an unscaled REAL FIXED BINARY value specifying the number of
data items transmitted during the last GET or PUT operation on x.
COUNT(x)
x File-reference. The file must be open and have the STREAM attribute.
The BIFPREC compiler option determines the precision of the result returned.
CS
CS returns a FIXED BINARY(31) value that indicates if the old and current values
in a compare and swap were equal.
CS(p,q,x)
CS compares the "current" and "old" values. If they are equal, the "new" value is
copied over the "current", and a value of 0 is returned. If they are unequal, the
"current" value is copied over the "old", and a value of 1 is returned.
So, CS could be implemented as the following PL/I function, but then it would not
be atomic at all. :
cs: proc( old_Addr, current_Addr, new )
returns( fixed bin(31) byvalue )
options( byvalue );
On Intel, the CDS built-in function uses the Intel cmpxchg4 instruction. The
cmpxchg4 instruction takes the address of a "current" value, a "new" value and an
"old" value. It returns the original "current" value and updates it with the "new"
value only if it equaled the "old" value.
So, on Intel, the CS built-in function is implemented via the following inline
function:
cs: proc( old_Addr, current_Addr, new )
returns( fixed bin(31) byvalue )
options( byvalue );
CURRENTSIZE
CURRENTSIZE returns a FIXED BIN value that gives the implementation-defined
storage, in bytes, required by x.
CURRENTSIZE(x)
x A variable of any data type, data organization, and storage class except those
in the following list:
v A BASED, DEFINED, parameter, subscripted, or structure or union
base-element variable that is an unaligned fixed-length bit string
v A minor structure or union whose first or last base element is an unaligned
fixed-length bit string (except where it is also the first or last element of the
containing major structure or union)
v A major structure or union that has the BASED, DEFINED, or parameter
attribute, and that has an unaligned fixed-length bit string as its first or last
element
v A variable not in connected storage
If x is a scalar area, the returned value includes the area control bytes and the
current extent of the area. It does not include any unused bytes at the end of the
area.
The CURRENTSIZE built-in function must not be used on a BASED variable with
adjustable extents if that variable has not been allocated.
For examples of the CURRENTSIZE built-in function, see SIZE on page 725.
CURRENTSTORAGE
CURRENTSTORAGE is a synonym for CURRENTSIZE.
Abbreviation: CSTG
Related information:
CURRENTSIZE on page 485
CURRENTSIZE returns a FIXED BIN value that gives the implementation-defined
storage, in bytes, required by x.
DATAFIELD
DATAFIELD is in context in a NAME condition ON-unit (or any of its dynamic
descendants). It returns a character string whose value is the contents of the field
that raised the condition. It is also in context in an ON-unit (or any of its dynamic
descendants) for an ERROR or FINISH condition raised as part of the implicit
action for the NAME condition.
DATAFIELD
()
If the string that raised the condition contains DBCS identifiers, GRAPHIC data, or
mixed character data, DATAFIELD returns a mixed character string.
DATE
DATE returns a nonvarying character(6) string containing the date in the format,
YYMMDD.
DATE
()
DATETIME
DATETIME returns a character string timestamp of today's date in either the
default format or a user-specified format.
DATETIME
( )
y
y Expression
If present, it specifies the date/time pattern in which the date is returned. If y
is missing, it is assumed to be the default date/time pattern
'YYYYMMDDHHMISS999'.
See Table 64 on page 417 for the allowed patterns.
y must have computational type and should have character type. If not, it is
converted to character.
DAYS
DAYS returns a FIXED BINARY(31,0) value that is the number of days (in Lilian
format) corresponding to the date d.
DAYS
( )
d
,p
,w
Example
dcl Date_format value (MMDDYYYY) char;
dcl Todays_date char(length(Date_format));
dcl Sep2_1993 char(length(Date_format));
dcl Days_of_July4_1993 fixed bin(31);
dcl Msg char(100) varying;
dcl Date_due char(length(Date_format));
Days_of_July4_1993 = days(07041993,MMDDYYYY);
Sep2_1993 = daystodate(days_of_July4_1993 + 60, Date_format);
/* 09021993 */
The allowed patterns are listed in Table 64 on page 417. For an explanation of the
Lilian format, see Date/time built-in functions on page 415.
DAYSTODATE
DAYSTODATE returns a nonvarying character string containing the date in the
form p that corresponds to d days (in Lilian format).
DAYSTODATE ( d )
,p
,w
d The number of days (in Lilian format). d must have a computational type and
is converted to FIXED BINARY(31,0) if necessary.
p One of the supported date/time patterns.
If omitted, p is assumed to be the default date/time pattern
'YYYYMMDDHHMISS999' (same as the default format returned by
DATETIME).
w An integer expression that defines a century window to be used to handle any
two-digit year formats.
v If the value is positive, such as 1950, it is treated as a year.
v If negative or zero, the value specifies an offset to be subtracted from the
current, system-supplied year.
v If omitted, w defaults to the value specified in the WINDOW compile-time
option.
The allowed patterns are listed in Table 64 on page 417. For an explanation of the
Lilian format, see Date/time built-in functions on page 415.
DAYSTOSECS
DAYSTOSECS returns a FLOAT BINARY(53) value that is the number of seconds
corresponding to the number of days x.
DAYSTOSECS(x)
x Expression.
x must have a computational type and is converted to FIXED BINARY(31,0) if
necessary.
DECIMAL
DECIMAL returns the decimal value of x, with a precision specified by p and q.
The result has the mode and scale of x.
DECIMAL(x )
,p
,q
Abbreviation: DEC
x Reference.
p Restricted expression specifying the number of digits to be maintained
throughout the operation.
q Restricted expression specifying the scaling factor of the result. For a
fixed-point result, if p is given and q is omitted, a scaling factor of zero is
assumed. For a floating-point result, q must be omitted.
If both p and q are omitted, the precision of the result is determined from the rules
for base conversion.
DIMENSION
DIMENSION returns a FIXED BINARY value that specifies the current extent of
dimension y of x.
DIMENSION(x )
,y
Abbreviation: DIM
x Array reference. x must not have less than y dimensions.
y Expression specifying a particular dimension of x. If necessary, y is converted
to a FIXED BINARY(31,0). y must be greater than or equal to 1. If y is not
supplied, it defaults to 1.
y can be omitted only if the array is one-dimensional.
DIVIDE
DIVIDE returns the quotient of x/y with a precision specified by p and q. The base,
scale, and mode of the result follow the rules for expression evaluation unless
overruled by the PRECTYPE compiler option.
DIVIDE(x,y,p )
,q
x Expression.
y Expression. If y = 0, the ZERODIVIDE condition is raised.
p Restricted expression specifying the number of digits to be maintained
throughout the operation.
q Restricted expression specifying the scaling factor of the result. For a
fixed-point result, if q is omitted, a scaling factor of zero is the default. For a
floating-point result, q must be omitted.
EDIT
EDIT returns a character string of length LENGTH(y). Its value is equivalent to
what would result if x were assigned to a variable declared with the picture
specification given by y.
For the valid picture characters, see Chapter 14, Picture specification characters,
on page 355.
EDIT(x,y)
x Expression
x must have computational type.
y String expression.
y must have character type and must contain picture characters that are valid
for a PICTURE data item. If y does not contain a valid picture specification, the
ERROR condition is raised.
Example
dcl pic1 char(9) init (ZZZZZZZZ9);
dcl pic2 char(7) init (ZZ9V.99);
dcl num fixed dec (9) init (123456789);
z = edit (num, pic1); /* 123456789 */
z = edit (num, pic2); /* 789.00 */
z = edit (num, substr(pic1,8)); /* 89 */
z = edit (num, substr(pic2,1,5)); /* 789. */
z = edit (num, substr(pic1,7,3)); /* 789 */
z = edit (num, substr(pic2,3,5)); /* 9.00 */
z = edit (1, substr(pic1,7,3)); /* 1 */
z = edit (PL/I, AAXA); /* PL/I */
z = edit (PL/I, AAAA); /* raises conversion */
If x cannot be edited into the picture specification given by y, the conditions raised
are those that would be raised if x were assigned to a PICTURE data item which
has the same picture specification contained in y.
EMPTY
EMPTY returns an area of zero extent. It can be used to free all allocations in an
area.
EMPTY
()
The value of this function is assigned to an area variable when the variable is
allocated. Consider this example:
declare A area,
I based (P),
J based (Q);
ENDFILE
ENDFILE returns a '1'B when the end of the file is reached; '0'B if the end is not
reached. If the file is not open, the ERROR condition is raised.
ENDFILE(x)
x File reference.
ENDFILE can be used to detect the end-of-file condition for bytestream files; for
example, files that require the use of the FILEREAD built-in function.
ENTRYADDR
ENTRYADDR returns a pointer value that is the address of the first executed
instruction if the entry x is invoked. The entry x must represent a non-nested
procedure.
ENTRYADDR(x)
x Entry reference.
ENTRYADDR pseudovariable
The ENTRYADDR pseudovariable initializes an entry variable, x, with the address
of the entry to be invoked.
ENTRYADDR(x)
x Entry reference.
EPSILON
EPSILON returns a floating-point value that is the spacing between x and the next
positive number when x is 1. It has the base, mode, and precision of x.
EPSILON(x)
ERF
ERF returns a real floating-point value that is an approximation of the error
function of x.
ERF(x)
x Real expression.
The result has the base and precision of x, and a value given by:
(2/ '() ) x0 EXP(-(t2 ))dt
ERFC
ERFC returns a real floating-point value that is an approximation of the
complement of the error function of x.
ERFC(x)
x Real expression.
The result has the base and precision of x, and a value given by:
1 - ERF(x)
EXP
EXP returns a floating-point value that is an approximation of the base, e, of the
natural logarithm system raised to the power x.
EXP(x)
x Expression.
EXPONENT
EXPONENT returns a FIXED BINARY(31,0) value that is the exponent part of x.
EXPONENT(x)
FILEDDINT
FILEDDINT returns a FIXED BIN(31) value that is the value of attribute c for file x.
FILEDDINT(x,c)
x File reference.
c Character string that holds the attribute to be queried.
blksize keylen
bufsize keyloc
delay recsize
filesize retry
The ERROR condition with oncode 1010 is raised when the file is not open or the
attribute is invalid for the file being queried.
FILEDDTEST
FILEDDTEST returns a FIXED BIN(31) value that holds the value 1 if the attribute
c applies to file x. Otherwise, a value of 0 is returned.
FILEDDTEST(x,c)
x File reference.
c Character string that holds the attribute to be queried.
append graphic
bkwd lrmskip
ctlasa print
delimit prompt
descendkey scalarvarying
genkey skip0
The ERROR condition with oncode 1010 is raised when the file is not open or the
attribute is invalid for the file being queried.
FILEDDWORD
FILEDDWORD returns a character string that is the value of the attribute c for file
x.
FILEDDWORD(x,c)
x File reference.
c Character string that holds the attribute to be queried.
access putpage
amthd recfm
action share
charset type
filename typef
organization
The ERROR condition with oncode 1010 is raised when the file is not open or the
attribute is invalid for the file being queried.
FILEID
FILEID returns a size_t 1 value that is the system token for a PL/I file constant or
variable.
FILEID(x)
x File reference
This token should not be used for any purpose that could be accomplished by a
PL/I statement.
On z/OS, the token holds the address of the DCB associated with a RECORD or
STREAM file or of the ACB associated with a VSAM RECORD file. The token is
not valid for other files.
Note: The DCB or ACB address is provided so that applications can read the DCB
or ACB. The DCB and ACB must not be altered.
The ERROR condition with oncode 1010 is raised when the file is not open.
FILEOPEN
FILEOPEN returns '1'B if the file x is open and '0'B if the file is not open.
FILEOPEN(x)
x File reference.
FILEREAD
FILEREAD attempts to read z storage units (bytes) from file x into location y. It
returns the number of storage units actually read.
FILEREAD(x,y,z)
x File reference
y Expression with type POINTER or OFFSET. If the type is OFFSET, the
expression must be an OFFSET variable declared with the AREA attribute.
z Expression. It must have a computational type and is converted to type size_t.1
FILESEEK
FILESEEK changes the current file position associated with file x to a new location
within the file. The next operation on the file takes place at the new location.
FILESEEK is equivalent to the fseek function in C.
FILESEEK returns a size_t 1 value. The value is 0 if the change in file position is
successful; it is nonzero otherwise.
FILESEEK(x,y,z)
x File reference.
y A size_t value that indicates the number of positions the file pointer is to be
moved relative to z.
z A FIXED BINARY(31) value that indicates the origin from which the file
pointer is to be moved. The following values are valid:
-1 Beginning of the file
0 Current position of the file pointer
1 End of the file
FILETELL
FILETELL returns a size_t 1 value that indicates the current position of the file x.
The return value is an offset relative to the beginning of the file. FILETELL is
equivalent to the ftell function in C.
FILETELL(x)
x File reference
FILEWRITE
FILEWRITE attempts to write z storage units (bytes) to file x from location y It
returns the number of storage units actually written.
FILEWRITE(x,y,z)
x File reference.
y Expression with type POINTER or OFFSET. If the type is OFFSET, the
expression must be an OFFSET variable declared with the AREA attribute.
z Expression. It must have a computational type and is converted to type size_t.1
FIXED
FIXED returns the fixed-point value of x, with a precision specified by p and q. The
result has the base and mode of x.
FIXED(x )
,p
,q
x Expression.
p Restricted expression that specifies the total number of digits in the result. It
must not exceed the implementation limit.
q Restricted expression that specifies the scaling factor of the result. If q is
omitted, a scaling factor of zero is assumed.
If both p and q are omitted, the default values, (15,0) for a binary result or (5,0) for
a decimal result, are used.
FIXEDBIN
FIXEDBIN returns a FIXED BIN value with precision and scale derived from the
source unless explicitly specified as parameters to the function.
FIXEDBIN(x )
,p
,q
x Expression.
p Restricted expression that specifies the total number of digits in the result. It
must not exceed the implementation limit.
q Restricted expression that specifies the scaling factor of the result. If q is
omitted, a scaling factor of zero is assumed.
If both p and q are omitted, the precision of the result is determined from the
source according to this table:
source result
FIXED BIN(p,q) FIXED BIN(p,q)
FIXED DEC(p,q) FIXED BIN(r,s)
where r = min(M,1+CEIL(p*3.32))
and s = CEIL(ABS(q*3.32))*SIGN(q)
FLOAT BIN(p) FIXED BIN(p,0)
FLOAT DEC(p) FIXED BIN(r,0)
where r = min(M,CEIL(p*3.32))
BIT FIXED BIN(M,0)
CHAR, GRAPHIC or FIXED BIN(r,0)
WIDECHAR where r = min(M,1+CEIL(N*3.32))
FIXEDDEC
FIXEDDEC returns a FIXED DEC value with precision and scale derived from the
source unless explicitly specified as parameters to the function.
FIXEDDEC(x )
,p
,q
x Expression.
p Restricted expression that specifies the total number of digits in the result. It
must not exceed the implementation limit.
q Restricted expression that specifies the scaling factor of the result. If q is
omitted, a scaling factor of zero is assumed.
If both p and q are omitted, the precision of the result is determined from the
source according to this table:
source result
FIXED BIN(p,q) FIXED DEC(r,s)
where r = min(N,1+CEIL(p/3.32))
and s=CEIL(ABS(q/3.32))*SIGN(q)
FIXED DEC(p,q) FIXED DEC(p,q)
FLOAT BIN(p) FIXED DEC(r,0)
where r = min(N,CEIL(p/3.32)
FLOAT DEC(p) FIXED DEC(p,0)
BIT FIXED DEC(r,0)
where where r = min(N,1+CEIL(M/3.32))
CHAR, GRAPHIC or FIXED DEC(N,0)
WIDECHAR
FLOAT
FLOAT returns the approximate floating-point value of x, with a precision
specified by p. The result has the base and mode of x.
FLOAT(x )
,p
x Expression.
p Restricted expression that specifies the minimum number of digits in the
result.
If p is omitted, the precision of the result is determined from the rules for base
conversion.
If p is omitted, the default value, 15 for a binary result or 5 for a decimal
result, is used.
FLOATBIN
FLOATBIN returns a FLOAT BIN value with precision derived from the source
unless explicitly specified as a parameter to the function.
FLOATBIN(x )
,p
x Expression.
p Restricted expression that specifies the total number of digits in the result. It
must not exceed the implementation limit.
If p is omitted, the precision of the result is determined from the source according
to this table:
source result
FIXED BIN(p,q) FLOAT BIN(p)
FIXED DEC(p,q) FLOAT BIN(r)
where r = CEIL(p*3.32)
FLOAT BIN(p) FLOAT BIN(p)
FLOAT DEC(p) FLOAT BIN(r)
where r = CEIL(p*3.32)
BIT FLOAT BIN(M)
CHAR, GRAPHIC or FLOAT BIN(r)
WIDECHAR where r = CEIL(N*3.32)
FLOATDEC
FLOATDEC returns a FLOAT DEC value with precision derived from the source
unless explicitly specified as a parameter to the function.
FLOATDEC(x )
,p
x Expression.
p Restricted expression that specifies the total number of digits in the result. It
must not exceed the implementation limit.
If p is omitted, the precision of the result is determined from the source according
to this table:
source result
FIXED BIN(p,q) FLOAT DEC(r)
where r = CEIL(p/3.32)
FIXED DEC(p,q) FLOAT DEC(p)
FLOAT BIN(p) FLOAT DEC(r)
where r = CEIL(p/3.32)
FLOAT DEC(p) FLOAT DEC(p)
BIT FLOAT DEC(r)
where r = CEIL(M/3.32)
CHAR, GRAPHIC or FLOAT DEC(N)
WIDECHAR
FLOOR
FLOOR returns the largest integer value less than or equal to x.
FLOOR(x)
x Real expression.
The mode, base, scale, and precision of the result match the argument. Except
when x is fixed-point with precision (p,q), the precision of the result is given by:
(min(n,max(p-q+1,1)),0)
where n is the maximum number of digits allowed and is N for FIXED DECIMAL
or M for FIXED BINARY.
GAMMA
GAMMA is an approximation of the gamma of x, as given by the following
equation:
gamma(x) = 0 (ux-1)(e-x)du
GAMMA returns a floating-point value that has the base, mode, and precision of x.
GAMMA(x)
GETENV
GETENV returns a character value representing a specified environment variable.
GETENV(x)
GRAPHIC
GRAPHIC explicitly converts character (or mixed character) data to GRAPHIC
data. All other data first converts to character, and then to the GRAPHIC data
type.
The content of x is checked for validity during conversion, using the same rules as
for checking graphic and mixed character constants.
GRAPHIC(x )
,y
Example 1
Example 2
HANDLE
HANDLE returns a handle to the typed structure x.
HANDLE(x)
x Typed structure.
HBOUND
HBOUND returns a FIXED BINARY value that specifies the current upper bound
of dimension y of x.
HBOUND(x )
,y
Under the CMPAT(V3) compiler option, HBOUND returns a FIXED BIN(63) value.
Under the CMPAT(V2) and CMPAT(LE) compiler options, HBOUND returns a
FIXED BIN(31) value.
HBOUNDACROSS
HBOUNDACROSS returns a FIXED BINARY value that specifies the current upper
bound of a DIMACROSS reference x.
HBOUNDACROSS(x)
x DIMACROSS reference
Example
dcl
1 a,
2 b fixed bin,
2 c fixed bin;
dcl 1 xa( 100 ) like a dimacross;
...
do jx = 1 to hboundacross(xa);
a = xa, by dimacross(jx);
...
end;
HEX
HEX returns a character string that is the hexadecimal representation of the storage
that contains x.
HEX(x )
,z
HEX(x,z) returns a character string that contains x with the character z inserted
between every set of eight characters in the output string. Its length is 2 * size(x)
+ ((size(x) - 1)/4).
Under the compiler option USAGE(HEX(CSTG)), the length used in the above
calculations is based, for VARYING, VARYING4, and VARYINGZ strings, on
cstg(x) rather than on stg(x).
x Expression that represents any variable. The whole number of bytes that
contain x is converted to hexadecimal.
z Expression. If specified, z must have the type CHARACTER(1) NONVARYING.
If the number of bytes to be converted to hex is not known at compile time, then
no more than 32767 bytes will be converted.
Note: This function does not return an exact image of x in storage. If an exact
image is required, use the HEXIMAGE built-in function.
Example 1
dcl Sweet char(5) init(Sweet);
dcl Sixteen fixed bin(31) init(16) littleendian;
dcl XSweet char(size(Sweet)*2+(size(Sweet)-1)/4);
dcl XSixteen char(size(Sixteen)*2+(size(Sixteen)-1)/4);
XSweet = hex(Sweet,-);
/* 53776565-74 */
XSweet = heximage(addr(Sweet),length(Sweet),-);
/* 53776565-74 */
XSixteen = hex(Sixteen,-);
/* 00000010 - bytes reversed */
XSixteen = heximage(addr(Sixteen),stg(Sixteen),-);
/* 10000000 - bytes NOT reversed */
Example 2
dcl X fixed bin(15) littleendian;
dcl Y fixed bin(15) bigendian;
HEXDECODE
HEXDECODE decodes a source buffer from base 16 that is encoded in the
character set specified by the ASCII/EBCDIC suboption of the DEFAULT compiler
option. This function returns a size_t 1 value that indicates the number of bytes that
are written into the target buffer.
HEXDECODE(p,m,q,n)
If the address of the target buffer is zero, the number of bytes that would be
written is returned. If the target buffer is not large enough, a value of -1 is
returned. If the target buffer is large enough, the number of bytes that is written to
the buffer is returned.
If the source contains characters other than hexadecimal digits, the CONVERSION
condition is raised.
HEXDECODE8
HEXDECODE8 decodes a source buffer from base 16 that is encoded in UTF-8.
This function returns a size_t 1 value that indicates the number of bytes that are
written into the target buffer.
HEXDECODE8(p,m,q,n)
If the address of the target buffer is zero, the number of bytes that would be
written is returned. If the target buffer is not large enough, a value of -1 is
returned. If the target buffer is large enough, the number of bytes that is written to
the buffer is returned.
If the source contains characters other than hexadecimal digits, the CONVERSION
condition is raised.
HEXIMAGE
HEXIMAGE returns a character string that is the hexadecimal representation of the
storage at a specified location.
HEXIMAGE(p,n )
,z
If the number of bytes to be converted to hex is not known at compile time, then
no more than 32767 bytes will be converted.
For examples of the HEXIMAGE built-in function, see HEX on page 529.
HIGH
HIGH returns a character string of length x, where each character is the highest
character in the collating sequence (hexadecimal FF).
HIGH(x)
HUGE
HUGE returns a floating-point value that is the largest positive value x can
assume. It has the base, mode, and precision of x.
HUGE(x)
IAND
IAND returns the logical AND of its arguments
IAND( x, y )
x and y
Expressions that must have a computational type.
ICLZ
ICLZ returns a FIXED BIN(31) value that indicates the number of leading zeros in
a FIXED BIN value.
ICLZ(x)
If the argument x is of the type SIGNED FIXED BIN(p) with p <= 15, it is
converted to SIGNED FIXED BIN(31). If it is of the type UNSIGNED FIXED BIN(p)
with p <= 16, it is converted to UNSIGNED FIXED BIN(32).
IEOR
IEOR returns the logical exclusive-OR of x and y. The result is unsigned if all
arguments are unsigned.
IEOR(x,y)
x and y
Expressions that must have a computational type.
IMAG
IMAG returns the imaginary part of x. The mode of the result is real and has the
base, scale, and precision of x.
IMAG(x)
IMAG pseudovariable
The IMAG pseudovariable assigns a real value or the real part of a complex value
to the coefficient of the imaginary part of x.
IMAG(x)
x Complex reference.
INDEX
INDEX returns an unscaled REAL FIXED BINARY value that indicates the starting
position within x of a substring identical to y. You can also specify the location
within x where processing begins.
INDEX(x,y )
,n
x String-expression to be searched.
y Target string-expression of the search.
n n specifies the location within x at which to begin processing. It must have a
computational type and is converted to FIXED BINARY(31,0).
If y does not occur in x, or if either x or y have zero length, the value zero is
returned.
The BIFPREC compiler option determines the precision of the result returned.
INDEX will perform best when the second and third arguments are either literals,
named constants declared with the VALUE attribute, or restricted expressions.
Example
dcl tractatus char
value( Wovon man nicht sprechen kann, {
darueber muss man schweigen. );
INDEXR
INDEXR returns an unscaled REAL FIXED BINARY value indicating the starting
position within x of a substring identical to y when the search for y starts from the
right end of x. You can also specify the location within x where processing begins.
INDEXR(x,y )
,n
The INDEXR function performs the same operation as the INDEX built-in function
except for the following differences:
v The search is done from right to left.
v The default value of n is LENGTH(x).
v Unless 0 n LENGTH(x), the STRINGRANGE condition, if enabled, is raised.
Its implicit action and normal return give a result of zero.
The BIFPREC compiler option determines the precision of the result returned.
INDEXR will perform best when the second and third arguments are either literals,
named constants declared with the VALUE attribute, or restricted expressions.
Related information:
INDEX on page 541
INDEX returns an unscaled REAL FIXED BINARY value that indicates the starting
position within x of a substring identical to y. You can also specify the location
within x where processing begins.
INDICATORS
INDICATORS returns a FIXED BIN value giving the number of the elements at the
next logical level in a structure x.
INDICATORS(x)
x Expression.
x must be a structure reference.
The INDICATORS built-in function is useful in declaring an indicator array for use
in SQL statements.
INLIST
INLIST returns a bit(1) value that indicates whether x is equal to any of the
remaining arguments.
INLIST( x, y )
x and y
Expressions. They must be either all ORDINAL with the same type or all
computational.
After the evaluation of the first argument x, the evaluation of the remaining
arguments must not change the address or value of the first argument. This
condition is true when all but the first argument are constants. It is also true if the
second and subsequent arguments do not rely on the invocation of any user
functions that change storage associated with the first argument.
INOT
INOT returns the logical NOT of x.
INOT(x)
Although INOT(x) has the opposite sign of x, INOT(x) is not the same as -x.
Examples
inot(0) /* produces -1 */
inot(-1) /* produces 0 */
inot(+1) /* produces -2 */
IOR
IOR returns the logical OR of its arguments.
IOR( x, y )
x and y
Expressions that must have a computational type.
ISFINITE
ISFINITE returns a '1'B if if the argument with which it is invoked is not a NAN
and not positive or negative infinity. Otherwise it returns a '0'B.
ISFINITE(x)
ISIGNED
ISIGNED(x) returns the result of casting x to a signed integer value without
changing its bit pattern.
ISIGNED(x)
If x is not an integer, that is, if x is not REAL FIXED BIN with zero scale factor, it
is converted to REAL FIXED BIN(p,0).
ISIGNED( x ) returns, for integer x, a value with the same bit pattern as x but with
the attributes SIGNED FIXED BIN(p).
Example
ISIGNED(ff_ff_ff_ffxu) equals the SIGNED FIXED BIN(31) value -1.
ISINF
ISINF returns a '1'B if if the argument with which it is invoked is an infinity.
Otherwise it returns a '0'B.
ISINF(x)
ISLL
ISLL(x,n) returns the result of logically shifting x to the left by n places, and
padding on the right with zeroes.
ISLL(x,n)
If x is REAL FIXED BIN(p,0) and SIGNED, the result is SIGNED REAL FIXED
BIN(r,0) where if p <= M1, r = M1; if p > M1, r = M2.
Otherwise, x is converted to SIGNED REAL FIXED BIN(p,0) and the result has the
same attributes as above.
Note: Unlike RAISE2(x,n), ISLL(x,n) can have a different sign from that of x.
Examples
isll(+6,1) /* produces 12 */
isll(2147483645,1) /* produces -6 */
ISMAIN
ISMAIN() returns a '1'B if the procedure in which it is invoked has the
OPTIONS(MAIN) attribute. Otherwise it returns a '0'B.
ISMAIN ( )
ISNAN
ISNAN returns a '1'B if if the argument with which it is invoked is a NAN.
Otherwise it returns a '0'B.
ISNAN(x)
ISNORMAL
ISNORMAL returns a '1'B if if the argument with which it is invoked is not a zero,
subnormal, infinity or NaN. Otherwise it returns a '0'B.
ISNORMAL(x)
ISRL
ISRL(x,n) returns the result of logically shifting x to the right by n places, and
padding on the left with zeroes.
ISRL(x,n)
Examples
isrl(+6,1) /* produces 3 */
isrl(-6,1) /* produces 2147483645 */
ISZERO
ISZERO returns a '1'B if if the argument with which it is invoked is a zero.
Otherwise it returns a '0'B.
ISZERO(x)
IUNSIGNED
IUNSIGNED(x) returns the result of casting x to an unsigned integer value without
changing its bit pattern.
IUNSIGNED(x)
If x is not an integer, that is, if x is not REAL FIXED BIN with zero scale factor, it
is converted to REAL FIXED BIN(p,0).
IUNSIGNED(x) returns, for integer x, a value with the same bit pattern as x but
with the attributes UNSIGNED FIXED BIN(p).
Example
IUNSIGNED(ff_ff_ff_ffxn) equals the largest UNSIGNED FIXED BIN(32) value.
JSONGETARRAYEND
JSONGETARRAYEND(p,n) checks whether the next character, ignoring whitespace,
in a piece of JSON text is a closing bracket ]. This function returns a size_t 1 value
that is equal to the number of bytes read.
JSONGETARRAYEND(p,n)
JSONGETARRAYSTART
JSONGETARRAYSTART(p,n) checks whether the next character, ignoring
whitespace, in a piece of JSON text is an opening bracket [. This function returns a
size_t 1 value that is equal to the number of bytes read.
JSONGETARRAYSTART(p,n)
JSONGETCOLON
JSONGETCOLON(p,n) checks whether the next character, ignoring whitespace, in a
piece of JSON text is a colon. This function returns a size_t 1 value that is equal to
the number of bytes read.
JSONGETCOLON(p,n)
JSONGETCOMMA
JSONGETCOMMA(p,n) checks whether the next character, ignoring whitespace, in
a piece of JSON text is a comma. This function returns a size_t 1 value that is equal
to the number of bytes read.
JSONGETCOMMA(p,n)
JSONGETMEMBER
JSONGETMEMBER reads a member (or name-value pair) from a piece of JSON
text. This function returns a size_t 1 value that specifies the number of bytes read
from the buffer.
If the JSON text is invalid, the ERROR condition is raised and the ONSUBCODE
built-in function gives the index of the invalid character.
If the third argument is a structure, the names in the JSON text must match those
in the structure. If not, the ERROR condition is raised.
If any element in the target has the CHARACTER type, the conversion from the
UTF-8 source in the JSON text is based on the CODEPAGE compiler option.
JSONGETMEMBER(p,n )
,x
The name-value pair must consist of the variable's name as a JSON string followed
by a colon and the variable's value.
Examples
Suppose a buffer contains the following JSON text, and the buffer address is in P
and its length is in N.
{ "passes" : 3,
"data" :
[
{ "name" : "Mather", "elevation" : 12100 }
, { "name" : "Pinchot", "elevation" : 12130 }
, { "name" : "Glenn", "elevation" : 11940 }
]
}
When compiled with the option JSON(CASE(ASIS)), the following code allocates
an appropriately sized structure and then fills it in. The JSON compiler option is
needed so that the names are accepted in lower case.
dcl
1 info based(q),
2 count fixed bin(31),
2 data( passes refer(count) ),
3 name char(20) varying,
3 elevation fixed bin(31);
read = 0;
read += jsonGetObjectStart(p+read,n-read);
read += jsonGetMember(p+read,n-read,passes);
allocate info;
read += jsonGetComma(p+read,n-read);
read += jsonGetValue(p+read,n-read,data);
read += jsonGetColon(p+read,n-read);
read += jsonGetValue(p+read,n-read,data);
Note that this code works equally well if the buffer contains more data. See the
following example:
{ "passes" : 5,
"data" :
[
{ "name" : "Muir", "elevation" : 11980 }
, { "name" : "Mather", "elevation" : 12100 }
, { "name" : "Pinchot", "elevation" : 12130 }
, { "name" : "Glenn", "elevation" : 11940 }
, { "name" : "Forester", "elevation" : 13100 }
]
}
JSONGETOBJECTEND
JSONGETOBJECTEND(p,n) checks whether the next character, ignoring whitespace,
in a piece of JSON text is a closing brace }. This function returns a size_t 1 value
that is equal to the number of bytes read.
JSONGETOBJECTEND(p,n)
JSONGETOBJECTSTART
JSONGETOBJECTSTART(p,n) checks whether the next character, ignoring
whitespace, in a piece of JSON text is an opening brace {. This function returns a
size_t 1 value that is equal to the number of bytes read.
JSONGETOBJECTSTART(p,n)
JSONGETVALUE
JSONGETVALUE reads a value from a piece of JSON text. This function returns a
size_t 1 value that specifies the number of bytes read from the buffer.
If the JSON text is invalid, the ERROR condition is raised and the ONSUBCODE
built-in function gives the index of the invalid character.
If the third argument of JSONGETVALUE is omitted, the value is simply read over.
If the third argument is a structure, the names in the JSON text must match those
in the structure. If not, the ERROR condition is raised.
If the third argument is an array, array values can be omitted in which case the
corresponding elements of the target array are unchanged.
If any element in the target has the CHARACTER type, the conversion from the
UTF-8 source in the JSON text is based on the CODEPAGE compiler option.
JSONGETVALUE(p,n )
,x
Example 1
The following code assigns the values 2, 3, and 5 to the array B. The value
returned would be 7 plus the count of whitespace characters before the closing
bracket, ].
dcl b(3) fixed bin;
dcl buffer char(1000) var;
dcl p pointer;
dcl n fixed bin(31);
buffer = utf8( [ 2, 3, 5 ] );
p = addrdata(buffer);
n = length(buffer);
read = jsonGetValue( p, n, b );
Example 2
The following code assigns the values 2 to B(1), 3 to B(2), and leaves B(3)
unchanged. The value returned would be 5 plus the count of whitespace characters
before the closing bracket, ].
dcl b(3) fixed bin;
dcl buffer char(1000) var;
dcl p pointer;
dcl n fixed bin(31);
buffer = utf8( [ 2, 3 ] );
p = addrdata(buffer);
n = length(buffer);
read = jsonGetValue( p, n, b );
Example 3
The following code assigns 2 to C.D and 3 to C.E. It returns a value greater than or
equal to 13.
dcl 1 c, 2 d fixed bin, 2 e fixed bin;
dcl buffer char(1000) var;
dcl p pointer;
dcl n fixed bin(31);
Example 4
Suppose that a buffer contains the following JSON text, and that the buffer address
is P and its length is in N.
{ "PASSES" : 3,
"DATA" :
[
{ "NAME" : "Mather", "ELEVATION" : 12100 }
, { "NAME" : "Pinchot", "ELEVATION" : 12130 }
, { "NAME" : "Glenn", "ELEVATION" : 11940 }
]
}
Then the single invocation of JSONGETVALUE in the following code will fill in the
entire structure.
dcl
1 info,
2 passes fixed bin(31),
2 data(3),
3 name char(20) varying,
3 elevation fixed bin(31);
JSONPUTARRAYEND
JSONPUTARRAYEND(p,n) writes a closing bracket ] to the buffer if the number of
available bytes n is greater than zero. The function returns a size_t 1 value equal to
1.
JSONPUTARRAYEND(p,n)
JSONPUTARRAYSTART
JSONPUTARRAYSTART(p,n) writes an opening bracket [ to the buffer if the
1
number of available bytes n is greater than zero. The function returns a size_t
value equal to 1.
JSONPUTARRAYSTART(p,n)
JSONPUTCOLON
JSONPUTCOLON(p,n) writes a colon to the buffer if the number of available bytes
n is greater than zero. The function returns a size_t 1 value equal to 1.
JSONPUTCOLON(p,n)
JSONPUTCOMMA
JSONPUTCOMMA(p,n) writes a comma to the buffer if the number of available
bytes n is greater than zero. The function returns a size_t 1 value equal to 1.
JSONPUTCOMMA(p,n)
JSONPUTMEMBER
JSONPUTMEMBER appends a member (or name-value pair), as UTF-8, to the
JSON text. This function returns a size_t 1 value that specifies the number of bytes
that are written to the buffer.
JSONPUTMEMBER(p,n,x)
Example 1
dcl b(3) fixed bin init(2,3,5);
dcl buffer char(1000);
dcl p pointer;
dcl n fixed bin(31);
p = addr(buffer);
n = length(buffer);
written = jsonPutMember( p, n, b );
The above code writes the following UTF-8 string to the buffer, and assigns the
value 11 to the variable written.
"B":[2,3,5]
Example 2
dcl 1 c, 2 d fixed bin init(2), 2 e fixed bin init(3);
dcl buffer char(1000);
dcl p pointer;
dcl n fixed bin(31);
p = addr(buffer);
n = length(buffer);
written = jsonPutMember( p, n, c );
The above code writes the following UTF-8 string to the buffer, and assigns the
value 17 to the variable written.
"C":{"D":2,"E":3}
Example 3
dcl 1 c(2), 2 d fixed bin init(2,3), 2 d fixed bin init(5,7);
dcl buffer char(1000);
dcl p pointer;
dcl n fixed bin(31);
p = addr(buffer);
n = length(buffer);
written = jsonPutMember( p, n, c );
The above code writes the following UTF-8 string to the buffer, and assigns the
value 33 to the variable written.
"C":[{"D":2,"E":5},{"D":3,"E":7}]
Example 4
dcl x fixed bin(31) init(11);
dcl y fixed bin(31) init(13);
dcl buffer char(1000);
dcl p pointer;
dcl n fixed bin(31);
p = addr(buffer);
n = length(buffer);
written = 0;
written += jsonPutObjectStart( p+written, n-written );
written += jsonPutMember( p+written, n-written, x );
written += jsonPutComma( p+written, n-written );
written += jsonPutMember( p+written, n-written, y );
written += jsonPutObjectEnd( p+written, n-written );
The above code writes the following UTF-8 string to the buffer, and assigns the
value 15 to the variable written.
{"X":11,"Y":13}
Unlike the previous examples, this buffer contains complete, valid JSON text.
JSONPUTOBJECTEND
JSONPUTOBJECTEND(p,n) writes a closing brace } to the buffer if the number of
available bytes n is greater than zero. The function returns a size_t 1 value equal to
1.
JSONPUTOBJECTEND(p,n)
JSONPUTOBJECTSTART
JSONPUTOBJECTSTART(p,n) writes an opening brace to the buffer if the number
of available bytes n is greater than zero. The function returns a size_t 1 value equal
to 1.
JSONPUTOBJECTSTART(p,n)
JSONPUTVALUE
JSONPUTVALUE appends a value, as UTF-8, to the JSON text. This function
returns a size_t 1 value that specifies the number of bytes that are written to the
buffer.
JSONPUTVALUE(p,n,x)
Example 1
dcl b(3) fixed bin init(2,3,5);
dcl buffer char(1000);
dcl p pointer;
dcl n fixed bin(31);
p = addr(buffer);
n = length(buffer);
written = jsonPutValue( p, n, b );
The above code writes the following UTF-8 string to the buffer, and assigns the
value 7 to the variable written.
[2,3,5]
Example 2
dcl 1 c, 2 d fixed bin init(2), 2 e fixed bin init(3);
dcl buffer char(1000);
dcl p pointer;
dcl n fixed bin(31);
p = addr(buffer);
n = length(buffer);
written = jsonPutValue( p, n, c );
The above code writes the following UTF-8 string to the buffer, and assigns the
value 13 to the variable written.
{"D":2,"E":3}
JSONVALID
JSONVALID determines whether a buffer contains valid JSON text. This function
returns a size_t 1 value of zero if the JSON text is valid; otherwise, it returns the
index of the first invalid byte.
JSONVALID(p,n)
JULIANTOSMF
JULIANTOSMF returns a CHAR(4) value that holds a date in the SMF format.
JULIANTOSMF(d)
LBOUND
LBOUND returns a FIXED BINARY value that specifies the current lower bound of
dimension y of x.
LBOUND(x )
,y
Under the CMPAT(V3) compiler option, LBOUND returns a FIXED BIN(63) value.
Under the CMPAT(V2) and CMPAT(LE) compiler options, LBOUND returns a
FIXED BIN(31) value.
LBOUNDACROSS
LBOUNDACROSS returns a FIXED BINARY value that specifies the current lower
bound of a DIMACROSS reference x.
LBOUNDACROSS(x)
x DIMACROSS reference
LEFT
LEFT returns a string that is the result of inserting string x at the left end of a
string with length n and padded on the right with the character z as needed.
LEFT(x,n )
,z
Example
dcl Source char value(One Hundred SCIDS Marks);
dcl Target char(30);
LENGTH
LENGTH returns an unscaled REAL FIXED BINARY value specifying the current
length of x.
LENGTH(x)
The BIFPREC compiler option determines the precision of the result returned.
When applied to an OFFSET reference with the LOCATES attribute and implicit
AREA qualification:
v If the OFFSET reference is not null, LENGTH returns the address of the located
data.
v If the OFFSET reference is null, LENGTH returns SYSNULL.
LINENO
LINENO returns an unscaled REAL FIXED BINARY specifying the current line
number of x.
LINENO(x)
x File-reference.
The file must be open and have the PRINT attribute. If the file is not open or does
not have the PRINT attribute, 0 is returned.
The BIFPREC compiler option determines the precision of the result returned.
LOCATION
LOCATION returns a FIXED BIN value that specifies the byte location of x within
the level-1 structure or union that has member x.
LOCATION(x)
Abbreviation: LOC
x Structure or union member name. If x is not a member of a structure or union,
a value of 0 is returned. If x has the BIT attribute, the value returned by
LOCATION is the location of the byte that contains x.
The value for x must not be subscripted.
LOCATION can be used in restricted expressions, with a limitation. The value for x
must be declared before y if LOC(x) is used to set either of the following:
v The extent of a variable y that must have constant extents.
v The value of a variable y that must have a constant value.
Example
dcl 1 Table static,
2 Tab2loc fixed bin(15) nonasgn init(loc(Tab2)),
/* location is 0; gets initialized to 8 */
2 Tab3loc fixed bin(15) nonasgn init(loc(Tab3)),
/* location is 2; gets initialized to 808 */
2 Length fixed bin nonasgn init(loc(End)),
/* location is 4 */
2 * fixed bin,
2 Tab2(20,20) fixed bin,
/* location is 8 */
2 Tab3(20,20) fixed bin,
/* location is 808 */
LOCNEWSPACE
The LOCNEWSPACE(x, a) built-in subroutine allocates space in a for the variable
type described by the LOCATES attribute that is associated with x.
LOCNEWSPACE(x, )
a
In the following code snippet, the two executable statements are equivalent: Both
statements allocate 32 bytes from the pool area and assign that offset to name(1).
declare
1 data based(data_ptr) unaligned,
2 actual_count fixed bin(31),
2 orderinfo(order_count refer( actual_count)),
3 name offset(pool) locates(char(30) varying),
3 address offset(pool) locates(char(62) varying),
2 pool area(10_000);
call locnewspace(name(1));
call locnewspace(name(1), pool);
LOCNEWVALUE
The LOCNEWVALUE(v, x, a) built-in subroutine allocates space in a for the
variable type described by the LOCATES attribute that is associated with x and
assigns v to that area.
LOCNEWVALUE(v,x, )
a
If the OFFSET attribute for x specifies an AREA attribute, the following statements
are equivalent:
v call locnewvalue(v, x);
v call locnewspace(x);
v locval(x) = v;
In the following code snippet, the two executable statements are equivalent: Both
statements allocate 17 bytes in the pool area, assign that offset to name(1), and
assign the 'Sherlock Holmes' value as a character varying string to that location in
the area.
declare
1 data based(data_ptr) unaligned,
2 actual_count fixed bin(31),
2 orderinfo(order_count refer(actual_count)),
3 name offset(pool) locates(char(30) varying),
3 address offset(pool) locates(char(62) varying),
2 pool area(10_000);
LOCSTG
LOCSTG(x) returns a FIXED BIN value that specifies the number of bytes that are
needed for the storage to hold all the elements of x that have the LOCATES
attributes.
The return value has type FIXED BIN(63) under CMPAT(V3); otherwise, it has type
FIXED BIN(31).
LOCSTG(x)
Example
With the following declaration, the reference locstag(data) returns the value
96*actual_count:
declare
1 data based(data_ptr) unaligned,
2 actual_count fixed bin(31),
2 orderinfo(order_count refer( actual_count)),
3 name offset(pool) locates(char(30) varying),
3 address offset(pool) locates(char(62) varying),
2 pool area(10_000);
LOCVAL
LOCVAL(x, a) returns the value at the offset that is specified by x in the a area. The
type of the value is specified in the LOCATES attribute of x.
LOCVAL (x )
,a
Do not use a LOCVAL reference as the argument to the ADDR built-in function. To
obtain the address of such a reference, apply the POINTER built-in function to the
corresponding OFFSET.
Example
LOG
LOG returns a floating-point value that is an approximation of the natural
logarithm (the logarithm to the base e) of x. It has the base, mode, and precision of
x.
LOG(x)
LOGGAMMA
LOGGAMMA returns a floating-point value that is an approximation of the log of
gamma of x. The gamma of x is given by the following equation:
gamma(x) = 0 (ux-1)(e-x)du
LOGGAMMA(x)
LOG2
LOG2 returns a real floating-point value that is an approximation of the binary
logarithm (the logarithm to the base 2) of x. It has the base and precision of x.
LOG2(x)
LOG10
LOG10 returns a real floating-point value that is an approximation of the common
logarithm (the logarithm to the base 10) of x. It has the base and precision of x.
LOG10(x)
LOW
LOW returns a character string of length x, where each character is the lowest
character in the collating sequence (hexadecimal 00).
LOW(x)
LOWERCASE
LOWERCASE returns a character string with all the alphabetic characters from A
to Z converted to their lowercase equivalent.
LOWERCASE(x)
LOWERCASE(x) is equivalent to
TRANSLATE( x,
abcdefghijklmnopqrstuvwxyz,
ABCDEFGHIJKLMNOPQRSTUVWXYZ )
LOWER2
LOWER2(x,n) returns the value:
LOWER2(x,n)
If x is SIGNED REAL FIXED BIN(p,0), then the result has the same attributes.
Otherwise, x is converted to SIGNED REAL FIXED BIN(p,0) and the result has the
same attributes.
Examples
lower2 (+6,1) /* Produces 3 */
MAINNAME
MAINNAME returns a CHARACTER string that is the name of the MAIN
function on the current call stack.
MAINNAME
MAX
MAX returns the largest value from a set of two or more expressions.
MAX( x, y )
x and y
Expressions.
All the arguments must be real. The result is real, with the common base and scale
of the arguments.
MAXEXP
MAXEXP returns a FIXED BINARY(31,0) value that is the maximum value that
EXPONENT(x) can assume.
MAXEXP(x)
MAXLENGTH
MAXLENGTH returns the maximum length of a string.
MAXLENGTH(x)
x Expression. x must have a computational type and should have a string type.
If not, it is converted to character.
Example
dcl x char(20);
dcl y char(20) varying;
x, y = ;
Note that the first assignment to y leaves it unchanged because length(y) will return
zero when it is used in the code snippet above (since y is VARYING and was
previously set to '').
MEMCONVERT
MEMCONVERT converts the data in a source buffer from the specified source
codepage to a specified target codepage, stores the result in a target buffer, and
returns a size_t 1 value that indicates the number of bytes that are written to the
target buffer.
MEMCONVERT ( p , n , c , q , m , d )
The buffer lengths must be nonnegative and must have a computational type. The
buffer lengths are converted to type size_t.
The code page must have a computational type and is converted to type FIXED
BINARY (31,0). The code page must specify a valid, supported code page.
MEMCU12
MEMCU12 converts the data in a source buffer from UTF-8 to UTF-16, stores the
result in a target buffer, and returns a size_t 1 value that indicates the number of
bytes that are written to the target buffer.
MEMCU12 ( p , n , q , m )
The buffer lengths must be nonnegative and must have a computational type. The
buffer lengths are converted to type size_t.
If the target buffer is too small or if the source UTF-8 is invalid, a value of -1 is
returned.
MEMCU14
MEMCU14 converts the data in a source buffer from UTF-8 to UTF-32, stores the
result in a target buffer, and returns a size_t 1 value that indicates the number of
bytes that are written to the target buffer.
MEMCU14 ( p , n , q , m )
The buffer lengths must be nonnegative and must have a computational type. The
buffer lengths are converted to type size_t.
If the target buffer is too small or if the source UTF-8 is invalid, a value of -1 is
returned.
MEMCU21
MEMCU21 converts the data in a source buffer from UTF-16 to UTF-8, stores the
result in a target buffer, and returns a size_t 1 value that indicates the number of
bytes that are written to the target buffer.
MEMCU21 ( p , n , q , m )
The buffer lengths must be nonnegative and must have a computational type. The
buffer lengths are converted to type size_t.
If the target buffer is too small, a value of -1 is returned. The source must contain
valid UTF-16, and the behavior of this function when it does not is unspecified.
MEMCU24
MEMCU24 converts the data in a source buffer from UTF-16 to UTF-32, stores the
result in a target buffer, and returns a size_t 1 value that indicates the number of
bytes that are written to the target buffer.
MEMCU24 ( p , n , q , m )
The buffer lengths must be nonnegative and must have a computational type. The
buffer lengths are converted to type size_t.
If the target buffer is too small, a value of -1 is returned. The source must contain
valid UTF-16, and the behavior of this function when it does not is unspecified.
MEMCU41
MEMCU41 converts the data in a source buffer from UTF-32 to UTF-8, stores the
result in a target buffer, and returns a size_t 1 value that indicates the number of
bytes that are written to the target buffer.
MEMCU41 ( p , n , q , m )
The buffer lengths must be nonnegative and must have a computational type. The
buffer lengths are converted to type size_t.
If the target buffer is too small or if the source UTF-32 is invalid, a value of -1 is
returned.
MEMCU42
MEMCU42 converts the data in a source buffer from UTF-32 to UTF-16, stores the
result in a target buffer, and returns a size_t 1 value that indicates the number of
bytes that are written to the target buffer.
MEMCU42 ( p , n , q , m )
The buffer lengths must be nonnegative and must have a computational type. The
buffer lengths are converted to type size_t.
If the target buffer is too small or if the source UTF-32 is invalid, a value of -1 is
returned.
MEMINDEX
MEMINDEX returns a size_t 1 value that indicates the starting position within a
buffer of a specified substring.
MEMINDEX ( p , n , x )
MEMINDEX ( p , n , q , m )
The buffer lengths must be nonnegative and must have a computational type. The
buffer lengths are converted to type size_t.
With three arguments, the target string-expression must have type CHARACTER
(including PICTURE), GRAPHIC, or WIDECHAR. The buffer length is interpreted
as the number of units of that string type.
With four arguments, the buffer lengths specify a number of bytes and the search
performed is a character search.
Example
dcl cb(128*1024) char(1);
dcl wb(128*1024) widechar(1);
dcl pos fixed bin(31);
/* 128K bytes searched for the character string test */
pos = memindex( addr(cb), stg(cb), test );
/* 256K bytes searched for the string test as widechar */
pos = memindex( addr(wb), stg(wb), wchar(<) );
MEMSEARCH
MEMSEARCH returns a size_t 1 value that specifies the first position (from the left)
in a buffer at which any character, graphic, or widechar in a given string appears.
MEMSEARCH ( p , n , x )
The buffer length must be nonnegative and must have a computational type. The
buffer length is converted to type size_t.
The address p and the length n specify the "string" in which to search for any
character, graphic, or widechar that appears in x.
If either the buffer length n is zero or x is the null string, the result is zero.
Example
dcl cb(128*1024) char(1);
dcl wb(128*1024) widechar(1);
dcl pos fixed bin(31);
MEMSEARCHR
MEMSEARCHR returns a size_t 1 value that specifies the first position (from the
right) in a buffer at which any character, graphic, or widechar in a given string
appears.
MEMSEARCHR ( p , n , x )
The buffer length must be nonnegative and must have a computational type. The
buffer length is converted to type size_t.
The address p and the length n specify the "string" in which to search for any
character, graphic, or widechar that appears in x.
If either the buffer length n is zero or x is the null string, the result is zero.
Example
dcl cb(128*1024) char(1);
dcl wb(128*1024) widechar(1);
dcl pos fixed bin(31);
MEMVERIFY
MEMVERIFY returns a size_t 1 value that specifies the position in a buffer of the
first (from the left) character, graphic, or widechar that is not in a specified string.
MEMVERIFY ( p , n , x )
The buffer length must be nonnegative and must have a computational type. The
buffer length is converted to type size_t.
The address p and the length n specify the "string" in which to search for any
character, graphic, or widechar that does not appear in x.
If either the buffer length n is zero or x is the null string, the result is zero.
If all the characters, graphics, or widechars in the buffer do appear in x, the result
is zero.
Example
dcl cb(128*1024) char(1);
dcl wb(128*1024) widechar(1);
dcl pos fixed bin(31);
/* 256K bytes searched from the left for the a non-blank widechar */
pos = memverify( addr(wb), stg(wb), 0020wx );
MEMVERIFYR
MEMVERIFYR returns a size_t 1 value that specifies the position in a buffer of the
first (from the right) character, graphic, or widechar that is not in a specified string.
MEMVERIFYR ( p , n , x )
The buffer length must be nonnegative and must have a computational type. The
buffer length is converted to type size_t.
The address p and the length n specify the "string" in which to search for any
character, graphic, or widechar that does not appear in x.
If either the buffer length n is zero or x is the null string, the result is zero.
If all the characters, graphics or widechars in the buffer do appear in x, the result
is zero.
Example
dcl cb(128*1024) char(1);
dcl wb(128*1024) widechar(1);
dcl pos fixed bin(31);
/* 256K bytes searched from the right for the a non-blank widechar */
pos = memverify( addr(wb), stg(wb), 0020wx );
MIN
MIN returns the smallest value from a set of one or more expressions.
MIN( x, y )
x and y
Expressions.
All the arguments must be real. The result is real with the common base and scale
of the arguments.
The precision of the result is the same as that described in MAX on page 596.
MINEXP
MINEXP returns a FIXED BINARY(31,0) value that is the minimum value that
EXPONENT(x) can assume.
MINEXP(x)
MOD
MOD returns the modular equivalent of the remainder of one value divided by
another.
In this example, the value for n is an integer value. That is, R is the smallest
nonnegative value that must be subtracted from x to make it divisible by y.
MOD(x,y)
x Real expression.
y Real expression. If y = 0, the ZERODIVIDE condition is raised.
The result, R, is real with the common base and scale of the arguments. If the
result is floating-point, the precision is the greater of those of x and y. If the result
is fixed-point, the precision is given by the following:
(min(n,p2-q2+max(q1,q2)),max(q1,q2))
In this example, (p1,q1) and (p2,q2) are the precisions of x and y, respectively, and
n is N for FIXED DECIMAL or M for FIXED BINARY.
If x and y are fixed-point with different scaling factors, the argument with the
smaller scaling factor is converted to the larger scaling factor before R is calculated.
If the conversion fails, the result is unpredictable.
If the result has the attributes FIXED BIN and one or more of the operands has the
attributes UNSIGNED FIXED BIN, the result has the SIGNED attribute unless both
of the following conditions are true:
v All of the operands are UNSIGNED FIXED BIN.
v The RULES(ANS) compiler option is in effect.
If any of the conditions above is not true, each UNSIGNED operand is converted
to SIGNED. If the operand is too large, the conversion would:
v Raise the SIZE condition if SIZE is enabled.
v Produce a negative value if SIZE is not enabled.
Example
The following example contrasts the MOD and REM built-in functions.
rem( +10, +8 ) = 2
mod( +10, +8 ) = 2
rem( +10, -8 ) = 2
mod( +10, -8 ) = 2
rem( -10, +8 ) = -2
mod( -10, +8 ) = 6
rem( -10, -8 ) = -2
mod( -10, -8 ) = 6
Related information:
MPSTR
MPSTR truncates a string at a logical boundary and returns a mixed character
string. It does not truncate a double-byte character between bytes. The length of
the returned string is equal to the length of the expression x, or to the value
specified by y. The processing of the string is determined by the rules selected by
the expression r, as described below.
MPSTR(x,r )
,y
x Expression that yields the character string result. The value of x is converted to
character if necessary.
r Expression that yields a character result. The expression cannot be GRAPHIC
and is converted to character if necessary.
The expression r specifies the rules to be used for processing the string. The
characters that can be used in r and the rules for them are as follows:
V or v
Validates the mixed string x and returns a mixed string.
S or s
Removes any null DBCS strings, creates a new string, and returns a mixed
string.
MULTIPLY
MULTIPLY returns the product of x and y, with a precision specified by p and q.
The base, scale, and mode of the result are determined by the rules for expression
evaluation unless overruled by the PRECTYPE compiler option.
MULTIPLY(x,y,p )
,q
x and y
Expressions.
p Restricted expression that specifies the number of digits to be maintained
throughout the operation.
q Restricted expression that specifies the scaling factor of the result. For a
fixed-point result, if q is omitted, a scaling factor of zero is assumed. For a
floating-point result, q must be omitted.
Note that when applied to FIXED DECIMAL, then if the mathematical result is too
big for the specified precision p but less than the maximum implementation value,
v if SIZE is disabled, the FIXEDOVERFLOW condition will not be raised and the
result will be truncated
v if SIZE is enabled, the SIZE condition will be raised
Note that the above text is false when the non-default compiler option
DECIMAL(FOFLONMULT) is in effect. In that case, FIXEDOVERFLOW will be
raised if SIZE is disabled (and the result is too big).
NULL
NULL returns the null pointer value. The null pointer value does not identify any
generation of a variable. The null pointer value can be assigned to and compared
with handles. The null pointer value can be converted to OFFSET by assignment of
the built-in function value to an offset variable.
NULL
()
NULLENTRY
NULLENTRY returns a limited entry that has a null value.
NULLENTRY
()
You cannot use NULLENTRY as one of the arguments to the PLISRTA, PLISRTB,
PLISRTC or PLISRTD built-in functions.
OFFSET
OFFSET returns an offset value derived from a pointer reference x and relative to
an area y. If x is the null pointer value, the null offset value is returned.
OFFSET ( x , y )
OFFSETADD
OFFSETADD returns the sum of the arguments.
OFFSETADD(x,y)
OFFSETDIFF
OFFSETDIFF returns a FIXED BIN value that is the arithmetic difference between
the arguments.
The return value has type FIXED BIN(31) under OFFSETSIZE(4) or type FIXED
BIN(63) under OFFSETSIZE(8).
OFFSETDIFF(x,y)
x and y
Expressions. Both must be specified as OFFSET.
OFFSETSUBTRACT
OFFSETSUBTRACT is equivalent to OFFSETADD(x,-y).
OFFSETSUBTRACT(x,y)
OFFSETVALUE
OFFSETVALUE returns an offset value that is the converted value of x.
OFFSETVALUE(x)
OMITTED
OMITTED returns a BIT(1) value that is '1'B if the parameter named x was omitted
in the invocation to its containing procedure.
OMITTED(x)
ONAREA
ONAREA returns a character string whose value is the name of the AREA
reference for which an AREA condition is raised. If the reference includes DBCS
names, the string returned is a mixed character string. It is in context in an
ON-unit (or any of its dynamic descendants) for the AREA condition, or for the
ERROR or FINISH condition raised as the implicit action for an AREA condition.
ONAREA
()
If the ONAREA built-in function is used out of context, a null string is returned.
ONCHAR
ONCHAR returns a character(1) string containing the character that caused the
CONVERSION condition to be raised. It is in context in an ON-unit (or any of its
dynamic descendants) for the CONVERSION condition or for the ERROR or
FINISH condition raised as the implicit action for the CONVERSION condition.
ONCHAR
()
ONCHAR pseudovariable
The ONCHAR pseudovariable sets the current value of the ONCHAR built-in
function. The element value assigned to the pseudovariable is converted to a
character value of length 1. The new character is used when the conversion is
attempted again. (See conversions in Chapter 4, Data conversion, on page 77.)
ONCHAR
()
ONCODE
The ONCODE built-in function provides a fixed-point binary value that depends
on the cause of the last condition. ONCODE can be used to distinguish between
the various circumstances that raise a particular conditionfor instance, the
ERROR condition. For codes corresponding to the conditions and errors detected,
refer to the specific condition.
ONCODE returns a real fixed-point binary value that is the condition code. It is in
context in any ON-unit or its dynamic descendant. All condition codes are defined
in Messages and Codes.
ONCODE
()
ONCONDCOND
ONCONDCOND returns a nonvarying character string whose value is the name of
the condition for which a CONDITION condition is raised. If the name is a DBCS
name, it will be returned as a mixed character string. It is in context in the
following circumstances:
v In a CONDITION ON-unit, or any of its dynamic descendants
v In an ANYCONDITION ON-unit that traps a CONDITION condition, or any
dynamic descendants of such an ON-unit.
ONCONDCOND
()
ONCONDID
ONCONDID (short for ON-condition identifier) returns a FIXED BINARY(31,0)
value that identifies the condition being handled by an ON-unit. It is in context in
any ON-unit or one of its dynamic descendants.
ONCONDID
()
ONCOUNT
ONCOUNT returns an unscaled REAL FIXED BINARY value specifying the
number of conditions that remain to be handled when an ON-unit is entered. (See
Multiple conditions on page 378.) It is in context in any ON-unit, or any
dynamic descendant of an ON-unit.
ONCOUNT
()
The BIFPREC compiler option determines the precision of the result returned.
ONFILE
ONFILE returns a character string whose value is the name of the file for which an
input or output condition is raised. If the name is a DBCS name, it is returned as a
mixed character string. It is in context in an ON-unit (or any of its dynamic
descendants) for an input or output condition, or for the ERROR or FINISH
condition raised as the implicit action for an input or output condition.
ONFILE
()
ONGSOURCE
ONGSOURCE returns a graphic string containing the DBCS character that caused
the CONVERSION condition to be raised. It is in context in an ON-unit (or any of
its dynamic descendants) for the CONVERSION condition or for the ERROR or
FINISH condition raised as the implicit action for a CONVERSION condition.
ONGSOURCE
()
ONGSOURCE pseudovariable
The ONGSOURCE pseudovariable sets the current value of the ONGSOURCE
built-in function. The element value assigned to the pseudovariable is converted
graphic. The string is used when the conversion is attempted again.
ONGSOURCE
()
ONKEY
ONKEY returns a character string whose value is the key of the record that raised
an input/output condition. For indexed files, if the key is GRAPHIC, the string is
returned as a mixed character string. ONKEY is in context for the following:
v An ON-unit, or any of its dynamic descendants
v Any input/output condition, except ENDFILE
v The ERROR or FINISH condition raised as implicit action for an input/output
condition.
ONKEY is always set for operations on a KEYED file, even if the statement that
raised the condition does not specified the KEY, KEYTO, or KEYFROM options.
ONKEY
()
ONLINE
ONLINE returns a FIXED BIN(31) value which is the line number in the source in
which a condition was raised.
ONLINE
()
The source program must have been compiled with the GONUMBER option, and
on Windows it must also have been linked with the /debug option.
ONLOC
ONLOC returns a character string whose value is the name of the entry-point used
for the current invocation of the procedure in which a condition was raised.
ONLOC
()
ONOFFSET
ONOFFSET returns a FIXED BIN(31) value which is the offset from the start of the
user procedure (or BEGIN block) in which a condition was raised.
ONOFFSET
()
ONSOURCE
ONSOURCE returns a character string whose value is the contents of the field that
was being processed when the CONVERSION condition was raised. It is in context
in an ON-unit (or any of its dynamic descendants) for the CONVERSION
condition or for the ERROR or FINISH condition raised as the implicit action for a
CONVERSION condition.
ONSOURCE
()
ONSOURCE pseudovariable
The ONSOURCE pseudovariable sets the current value of the ONSOURCE built-in
function. The element value assigned to the pseudovariable is converted to a
character string and, if necessary, is padded on the right with blanks or truncated
to match the length of the field that raised the CONVERSION condition. The string
is used when the conversion is attempted again.
ONSOURCE
()
ONSUBCODE
ONSUBCODE returns a FIXED BINARY(31,0) value that gives more information
about an I/O, JSON, or conversion error that occurred.
ONSUBCODE()
For JSON built-in functions, when the ERROR condition is raised, ONSUBCODE
returns the index of the invalid character.
ONSUBCODE2
ONSUBCODE2 returns a FIXED BIN(31) value that gives more information about
an I/O error that has occurred.
ONSUBCODE2()
ONWCHAR
ONWCHAR returns a widechar(1) string containing the widechar that caused the
CONVERSION condition to be raised. It is in context in an ON-unit (or any of its
dynamic descendants) for the CONVERSION condition or for the ERROR or
FINISH condition raised as the implicit action for the CONVERSION condition.
ONWCHAR
()
ONWCHAR pseudovariable
The ONWCHAR pseudovariable sets the current value of the ONWCHAR built-in
function. The element value assigned to the pseudovariable is converted to a
widechar value of length 1. The new widechar is used when the conversion is
attempted again. (See conversions in Chapter 4, Data conversion, on page 77.)
ONWCHAR
()
ONWSOURCE
ONWSOURCE returns a widechar string whose value is the contents of the field
that was being processed when the CONVERSION condition was raised. It is in
context in an ON-unit (or any of its dynamic descendants) for the CONVERSION
condition or for the ERROR or FINISH condition raised as the implicit action for a
CONVERSION condition.
ONWSOURCE
()
ONWSOURCE pseudovariable
The ONWSOURCE pseudovariable sets the current value of the ONWSOURCE
built-in function. The element value assigned to the pseudovariable is converted to
a widechar string and, if necessary, is padded on the right with widechar blanks or
truncated to match the length of the field that raised the CONVERSION condition.
The string is used when the conversion is attempted again.
ONWSOURCE
()
ORDINALNAME
ORDINALNAME returns a nonvarying character string that is the member of the
set associated with the ordinal x.
ORDINALNAME(x)
ORDINALPRED
ORDINALPRED returns an ordinal that is the next lower value that the ordinal x
could assume.
ORDINALPRED(x)
ORDINALSUCC
ORDINALSUCC returns an ordinal that is the next higher value the ordinal x
could assume.
ORDINALSUCC(x)
PACKAGENAME
PACKAGENAME returns a nonvarying character string containing the name of the
package in which it is invoked. If there is no package in the current compilation
unit, PACKAGENAME returns the name of the outermost procedure.
PACKAGENAME
()
PAGENO
PAGENO returns an unscaled REAL FIXED BIN(31) value that is the current page
number associated with file x.
PAGENO(x)
x File reference. The file must be open and have the PRINT attribute.
The BIFPREC compiler option determines the precision of the result returned.
PICSPEC
The PICSPEC built-in function casts data from CHARACTER to PICTURE type.
PICSPEC ( x , y )
x Expression.
y Picture specification.
The result has the PICTURE type specified by the second argument.
Unlike the EDIT built-in function, no conversion is done and no checks are made
to see if the first argument holds data valid for the picture.
Like the UNSPEC built-in function, only the "type" of the data is changed.
So, for example given PICSPEC(x,'(5)9'), x must be CHAR(5) (since while the
picture specification '(5)9' was 4 characters in length, its external representation
requires 5 characters), but x will not be checked to see if it actually contains 5
numeric digits.
PLACES
PLACES returns a FIXED BINARY(31,0) value that is the model-precision used to
represent the floating-point expression x.
PLACES(x)
PLIASCII
The PLIASCII subroutine converts z bytes of an EBCDIC value at location y to an
ASCII value at location x.
The storage at location x and y must not overlap unless they specify the same
location.
PLIASCII(x,y,z)
x and y
Expressions with type POINTER or OFFSET. If the type is OFFSET, the
expression must be an OFFSET variable declared with the AREA attribute.
z Expression. It must have a computational type and is converted to type size_t.1
PLIATTN
The PLIATTN subroutine gives you explicit control over where the compiler inserts
attention breakpoints. Each invocation of this subroutine causes the ATTENTION
condition to be raised at that point in the code.
PLIATTN
()
The INTERRUPT option has no effect on the code that is generated for a call to
this subroutine.
PLICANC
The PLICANC subroutine allows you to cancel the automatic restart facility.
PLICANC
()
For more information about using PLICANC, see the Programming Guide.
PLICKPT
The PLICKPT subroutine allows you to take a checkpoint for later restart.
PLICKPT(argument )
,argument
For more information about using PLICKPT, see the Programming Guide.
PLIDELETE
This built-in subroutine frees the storage associated with the handle x.
PLIDELETE(x)
x Handle expression.
PLIDELETE(x) is the best way to free the storage associated with a handle; this
storage is usually acquired by the NEW type function.
PLIDUMP
The PLIDUMP subroutine allows you to obtain a formatted dump of selected parts
of storage that is used by your program.
PLIDUMP(argument )
,argument
For more information about using PLIDUMP, refer to the Programming Guide.
PLIEBCDIC
The PLIEBCDIC subroutine converts z bytes of an ASCII value at location y to an
EBCDIC value at location x.
The storage at location x and y must not overlap unless they specify the same
location.
PLIEBCDIC(x,y,z)
x and y
Expressions with type POINTER or OFFSET. If the type is OFFSET, the
expression must be an OFFSET variable declared with the AREA attribute.
z Expression. It must have a computational type and is converted to type size_t.1
PLIFILL
The PLIFILL subroutine moves z copies of the byte y to the location x without any
conversions, padding, or truncation.
PLIFILL(x,y,z)
Example
dcl 1 Str1,
2 B fixed bin(31),
2 C pointer,
2 * union,
3 D char(4),
3 E fixed bin(31),
3 *,
4 * char(3),
4 F fixed bin(8) unsigned,
2 * char(0)
initial call plifill( addr(Str1), 00x, stg(Str1) );
PLIFREE
This built-in subroutine frees the heap storage associated with the pointer p that
was allocated using the ALLOCATE built-in function.
PLIFREE(p)
p Locator expression.
PLIMOVE
The PLIMOVE subroutine moves z storage units (bytes) from location y to location
x, without any conversions, padding, or truncation.
PLIMOVE(x,y,z)
x and y
Expressions declared as POINTER or OFFSET. If the type is OFFSET, x or y
must be declared with the AREA attribute.
z Expression. It must have a computational type and is converted to type size_t.1
Example
dcl 1 Str1,
2 B fixed bin(31),
2 C pointer,
2 * union,
3 D char(4),
3 E fixed bin(31),
3 *,
4 * char(3),
4 F fixed bin(8) unsigned,
2 * char(0);
dcl 1 Template nonasgn static,
2 * fixed bin(31) init(200),
2 * pointer init(null()),
2 * char(4) init(),
2 * char(0);
PLIOVER
The PLIOVER subroutine moves z storage units (bytes) from location y to location
x, without any conversions, padding, or truncation. Unlike the PLIMOVE built-in
subroutine, the storage at locations x and y can overlap.
PLIOVER(x,y,z)
x and y
Expressions declared as POINTER or OFFSET. If the type is OFFSET, x or y
must be declared with the AREA attribute.
z Expression. It must have a computational type and is converted to type size_t.1
Related information:
PLIMOVE on page 663
The PLIMOVE subroutine moves z storage units (bytes) from location y to location
x, without any conversions, padding, or truncation.
PLIREST
This built-in subroutine allows you to restart program execution.
PLIREST
()
For more information about using PLIREST, see the Programming Guide.
PLIRETC
This built-in subroutine allows you to set a return code that can be examined by
the program that invoked this PL/I program or by another PL/I procedure via the
PLIRETV built-in function.
PLIRETC(x)
PLIRETV
PLIRETV returns a FIXED BINARY(31,0) value that is the PL/I return code.
PLIRETV
()
The value of the PL/I return code is the most recent value specified by a CALL
PLIRETC statement.
PLISAXA
The PLISAXA subroutine allows you to perform SAX-style parsing of an XML
document that is located in a buffer in your program.
PLISAXA(e,p,x,n )
,c
e An event structure.
p A pointer value or "token" that will be passed back to the parsing events.
x The address of the buffer containing the input XML.
n The number of bytes of data in that buffer. It must have a computational type
and is converted to type size_t.1
c A numeric expression specifying the purported codepage of that XML.
Also note that if the XML is contained in a WIDECHAR string, the value for the
number of bytes is twice the value returned by the LENGTH built-in function.
PLISAXB
The PLISAXB subroutine allows you to perform SAX-style parsing of an XML
document that is located in a file.
PLISAXB(e,p,x )
,c
e An event structure
p A pointer value or "token" that will be passed back to the parsing events
x A character string expression specifying the input file
c A numeric expression specifying the purported codepage of that XML
PLISAXC
The PLISAXC subroutine allows you to perform SAX-style parsing of an XML
document that is located in one or more buffers in your program.
PLISAXC(e,p,x,n )
,c
e An event structure.
p A pointer value or "token" that will be passed back to the parsing events.
x The address of the buffer containing the XML document.
n The number of bytes of data in that buffer. It must have a computational type
and is converted to type size_t.1
c A numeric expression specifying the codepage of that XML document.
PLISAXC uses the z/OS XML System Services parser and is supported only on
z/OS.
For more information, see the Enterprise PL/I for z/OS Programming Guide.
PLISAXD
The PLISAXD built-in subroutine provides SAX-style parsing with XML validation
of an XML document.
PLISAXD(e,p,x,n,o )
,c
e An event structure.
p A pointer value or "token" that will be passed back to the parsing events.
x The address of s buffer that contains the XML document.
n The number of bytes of data in that buffer. It must have a computational type
and is converted to type size_t.1
o The address of a buffer that contains an Optimized Schema Representation
(OSR).
c A numeric expression specifying the codepage of that XML document.
PLISAXD uses the z/OS XML System Services parser and is supported only on
z/OS.
For more information, see the chapter Using the PLISAXD XML parser in the
Enterprise PL/I for z/OS Programming Guide.
PLISRTA
This built-in subroutine allows you to sort an input file to produce a sorted output
file.
PLISRTA( argument )
PLISRTB
This built-in subroutine allows you to sort input records provided by an E15 PL/I
exit procedure to produce a sorted output file.
PLISRTB( argument )
PLISRTC
This built-in subroutine allows you to sort an input file to produce sorted records
that are processed by an E35 PL/I exit procedure.
PLISRTC( argument )
For more information, see the Enterprise PL/I for z/OS Programming Guide.
PLISRTD
This built-in subroutine allows you to sort input records provided by an E15 PL/I
exit procedure to produce sorted records that are processed by an E35 PL/I exit
procedure.
PLISRTD( argument )
PLISTCK
PLISTCK generates the corresponding store clock hardware instruction and returns
the condition code set by the instruction.
PLISTCK(x)
PLISTCKE
PLISTCKE generates the corresponding store clock hardware instruction and
returns the condition code set by the instruction.
PLISTCKE(x)
PLISTCKF
PLISTCKF generates the corresponding store clock hardware instruction and
returns the condition code set by the instruction.
PLISTCKF(x)
PLITRAN11
The PLITRAN11 built-in function translates one-byte data from a source buffer to
one-byte data in a target buffer.
PLITRAN11 ( p , q , n , t )
The buffer length must be nonnegative and must have a computational type. The
buffer length is converted to type size_t.1
PLITRAN12
The PLITRAN12 built-in function translates one-byte data from a source buffer to
two-byte data in a target buffer.
PLITRAN12 ( p , q , n , t )
The target buffer must be at least twice as large as the source buffer.
PLITRAN21
The PLITRAN21 built-in function translates two-byte data from a source buffer to
one-byte data in a target buffer.
PLITRAN21 ( p , q , n , t )
The target buffer must be at least half as large as the source buffer.
PLITRAN22
The PLITRAN22 built-in function translates two-byte data from a source buffer to
two-byte data in a target buffer.
PLITRAN22 ( p , q , n , t )
POINTER
POINTER returns a pointer value that identifies the generation specified by an
offset reference x, in an area specified by y. If x is the null offset value, the null
pointer value is returned.
POINTER(x,y)
Abbreviation: PTR
x Offset reference. It can be the null offset value. If it is not, x must identify a
generation of a based variable, but not necessarily in y. If it is not in y, the
generation must be equivalent to a generation in y.
y Area reference.
POINTERADD
POINTERADD returns a pointer value that is the sum of its arguments.
POINTERADD(x,y)
Abbreviation: PTRADD
x Pointer expression.
y Expression that must have a computational type and is converted to FIXED
BINARY(31,0).
Note, however, since a locator in PL/I must be a reference, you cannot write
x = (p + 2)->b;
POINTERDIFF
POINTERDIFF returns a size_t 1 result that is the difference between the two
pointers x and y.
POINTERDIFF(x,y)
Abbreviation: PTRDIFF
x and y
Expressions declared as POINTER.
POINTERSUBTRACT
POINTERSUBTRACT is equivalent to POINTERADD(x,-y).
POINTERSUBTRACT(x,y)
Abbreviation: PTRSUBTRACT
x Must be a pointer expression.
y Expression that must have a computational type and is converted to FIXED
BINARY(31,0).
POINTERVALUE
POINTERVALUE returns a pointer value that is the converted value of x.
POINTERVALUE(x)
Abbreviation: PTRVALUE
x Expression that must have either the HANDLE attribute, or have a
computational type. If x has a computational type, it is converted to FIXED
BINARY(31,0).
POLY
POLY returns a floating-point value that is an approximation of a polynomial
formed from an one-dimensional array expressions x. The returned value has the
same attributes as the first argument. The syntax for POLY is:
POLY ( x , y )
x An array expression.
y An element expression.
If x has lower bound 0 and upper bound n, the result is a classic polynomial of
degree n in y with coefficients given by x, i.e. the result is
x(0) + x(1)*y + x(2)*y**2 + ... + x(n)*y**n
In the general case, where x has lower bound m and upper bound n, the result is
the polynomial
x(m) + x(m+1)*y + x(m+2)*y**2 + ... + x(n)*y**(n-m)
POPCNT
POPCNT returns a FIXED BIN value holding in each byte the number of bits equal
to 1 in the corresponding byte of x.
POPCNT(x)
x Expression.
x must have the attributes REAL FIXED BIN with a scale factor of zero.
PRECISION
PRECISION returns the value of x, with a precision specified by p and q. The base,
mode, and scale of the returned value are the same as that of x.
PRECISION(x,p )
,q
Abbreviation: PREC
x Expression.
p Restricted expression. p specifies the number of digits that the value of the
expression x is to have after conversion.
q Restricted expression. It specifies the scaling factor of the result. For a
fixed-point result, if q is omitted, a scaling factor of zero is assumed. For a
floating-point result, q must be omitted.
PRED
PRED returns a floating-point value that is the biggest representable number
smaller than x. It has the base, mode, and precision of x. OVERFLOW will be
raised if there is no such number.
PRED(x)
PRESENT
PRESENT(x) returns a BIT(1) value that is '1'B if the parameter x was present in
the invocation of its containing procedure.
PRESENT(x)
PROCEDURENAME
PROCEDURENAME() returns a nonvarying character string containing the name
of the procedure in which this built-in function is invoked.
PROCEDURENAME ( )
Abbreviation: PROCNAME
PROD
PROD returns the product of all the elements in x.
PROD(x)
The result has the precision of x, except that the result for fixed-point integer
values and strings is fixed-point with precision (n,0), where n is the maximum
number of digits allowed. The base and mode match the converted argument x.
PUTENV
This function adds new environment variables or modifies the values of existing
environment variables.
PUTENV(string)
string
A character string of the form envvarname=value.
RADIX
RADIX returns a FIXED BINARY(31,0) value that is the model-base used to
represent the floating-point expression x.
RADIX(x)
RAISE2
RAISE2(x,n) returns the value x*(2**n).
RAISE2(x,n)
If x is REAL FIXED BIN(p,0) and SIGNED, the result is SIGNED REAL FIXED
BIN(r,0) where if p <= M1, r = M1; if p > M1, r = M2.
Otherwise, x is converted to SIGNED REAL FIXED BIN(p,0) and the result has the
same attributes as above.
Example
raise2(6,1) /* produces 12 */
RANDOM
RANDOM returns a FLOAT BINARY(53) random number generated using x as the
given seed. If x is omitted, the random number generated is based on the seed
provided by the last RANDOM invocation with a seed, or on a default initial seed
of 1 if RANDOM has not previously been invoked with a seed.
RANDOM
(x)
The seed is maintained at the program level and not within each thread in a
multithreading application.
RANK
RANK returns the integer value corresponding to a character or widechar.
RANK(x)
REAL
REAL returns the real part of x. The result has the base, scale, and precision of x.
REAL(x)
REAL pseudovariable
The REAL pseudovariable assigns a real value or the real part of a complex value
to the real part of x.
REAL(x)
x Complex reference.
REG12
REG12 returns a pointer that holds the current value of register 12.
REG12
()
If the REG12 built-in function is used to change storage, unpredictable results may
occur
REM
REM returns the remainder of x divided by y. This can be calculated by:
x - y * trunc(x/y)
REM(x,y)
x and y
Expressions. x and y must be computational and can be arithmetic.
For examples that contrast the REM and MOD built-in functions, refer to MOD
on page 613.
REPATTERN
Takes a value holding a date in one pattern and returns that value converted to a
date in a second pattern.
REPATTERN(d ,p ,q )
,w
The returned value has the attributes CHAR(m) NONVARYING where m is the
length of the target pattern p.
The allowed patterns are listed in Table 64 on page 417. For an explanation of
Lilian format, see Date/time built-in functions on page 415.
The REPATTERN built-in function will perform the specified conversion in-line
when both of the following are true:
v the source and target patterns do not use the DDD, MMM or Mmm elements
v the source pattern has as much date information as the target, i.e. if the target
has a year, month or day, then the source must have the corresponding
information and there must also be at least as many digits in the source year as
in the target.
The following are some examples of how to use REPATTERN to convert between
2-digit-year and 4-digit-year date patterns. But you can use this built-in function to
convert a date from any supported pattern to any other supported pattern even if
the patterns use the same number of digits to hold the year value.
REPEAT
REPEAT returns a bit, character, graphic or widechar string consisting of x
concatenated to itself the number of times specified by y. That is, there are (y + 1)
occurrences of x.
REPEAT(x,y)
REPLACEBY2
REPLACEBY2 returns a nonvarying string formed by replacing some of the
characters in x by a pair of characters.
REPLACEBY2 ( x , y , z )
REVERSE
REVERSE returns a nonvarying string that contains the elements of x in reverse
order.
REVERSE(x)
x Expression. x must have a computational type and should have a string type.
If x does not have a string type, it is converted to string (that is, from numeric
to bit, character, graphic or widechar), according to the rules for concatenation.
Example
dcl Source char value(HARPO);
dcl Target char(length(Source));
RIGHT
RIGHT returns a string that is the result of inserting string x at the right end of a
string with length n and padded on the left with the character z as needed.
RIGHT(x,n )
,z
x Expression. x must have a computational type and can have a character type. If
not, it is converted to character.
n Expression. n must have a computational type and is converted to FIXED
BINARY(31,0).
z Expression. If specified, z must have the type CHARACTER(1) NONVARYING
type.
Example
dcl Source char value(One Hundred SCIDS Marks);
dcl Target char(30);
ROUND
ROUND returns the value of x rounded at a digit specified by n. The result has the
mode, base, and scale of x.
ROUND(x,n)
x Real expression. If x is negative, the absolute value is rounded and the sign is
restored.
n Optionally-signed integer. It specifies the digit at which rounding is to occur.
ROUND of FIXED
Where (p,q) is the precision of x, and N is the maximum number of digits allowed.
Hence, n specifies the scaling factor of the result.
n must conform to the limits of scaling-factors for FIXED data. If n is greater than
0, rounding occurs at the (n)th digit to the right of the point. If n is zero or
negative, rounding occurs at the (1-n)th digit to the left of the point.
The precision of an IEEE DECIMAL FLOAT result is the same as that of the source
argument.
The value of the result is given by the following formula, where where b = 10
(=radix(x)) and e = exponent(x):
round(x,n) = sign(x)*(b(e-n))* floor(abs(x)* (b(n-e)) + 1/2)
The precision of an IEEE binary floating point result is the same as that of the
source argument.
Under the compiler option USAGE(ROUND(IBM)), the value of the result is the
same as the source except on z/OS where if the source is not zero, then the result
is obtained by turning on the rightmost bit in the source.
Under the compiler option USAGE(ROUND(ANS)), the value of the result is given
by the following formula, where where b = 2 (=radix(x)) and e = exponent(x):
round(x,n) = sign(x)*(b(e-n))* floor(abs(x)* (b(n-e)) + 1/2)
The precision of an IBM hexadecimal floating point result is the same as that of the
source argument.
Under the compiler option USAGE(ROUND(IBM)), the value of the result is the
same as the source except on z/OS where if the source is not zero, then the result
is obtained by turning on the rightmost bit in the source.
Under the compiler option USAGE(ROUND(ANS)), the value of the result is given
by the following formula, where where b = 16 (=radix(x)) and e = exponent(x):
round(x,n) = sign(x)*(b(e-n))* floor(abs(x)* (b(n-e)) + 1/2)
ROUNDDEC
ROUNDDEC returns the value of x rounded at a digit specified by n. The result
has the mode, base, and scale of x.
ROUNDDEC(x,n)
SAMEKEY
SAMEKEY returns a bit string of length 1 indicating whether a record that has
been accessed is followed by another with the same key.
SAMEKEY(x)
SCALE
SCALE multiplies a floating-point number by an integral power of the radix.
SCALE(x,n)
SEARCH
SEARCH returns an unscaled REAL FIXED BINARY value specifying the first
position in one string at which any character, bit, graphic or widechar of another
string appears. It also allows you to specify the location at which to start searching.
SEARCH(x,y )
,n
x and y
Expressions. x specifies the string in which to search for any character, bit,
graphic or widechar that appears in string y.
If either x or y are the null string, the result is zero.
If y does not occur in x, the result is zero.
n Expression. n specifies the location within x at which to begin searching. It
must have a computational type and is converted to FIXED BINARY(31,0).
Unless 1 n LENGTH(x)+1, STRINGRANGE condition, if enabled, is raised.
Its implicit action and normal return give a result of zero.
The BIFPREC compiler option determines the precision of the result returned.
SEARCH will perform best when the second and third arguments are either
literals, named constants declared with the VALUE attribute, or restricted
expressions.
Example 1
dcl Source char value( Our PL/I wields the Power );
dcl Pos fixed bin(31);
In the above example, SEARCH returns the position at which any of the three
characters ('P', 'o', or 'w') appear. INDEX returns the position at which the whole
string 'Pow' appears.
Example 2
dcl Source char value ( 368,475;121.,856,478)
dcl Delims char(3) init (,;.); /* string of delimiters */
dcl Number(5) char(3);
dcl Start fixed bin(31);
dcl End fixed bin(31);
SEARCHR
The SEARCHR built-in function searches for the first occurrence of any one of the
elements of a string within another string but the search starts from the right.
SEARCHR(x,y )
,n
The SEARCHR function performs the same operation as the SEARCH built-in
function except for the following differences:
v The search is done from right to left.
v The default value for n is LENGTH(x).
v Unless 0 n LENGTH(x), the STRINGRANGE condition, if enabled, is raised.
Its implicit action and normal return give a result of zero.
The BIFPREC compiler option determines the precision of the result returned.
SEARCHR will perform best when the second and third arguments are either
literals, named constants declared with the VALUE attribute, or restricted
expressions.
Example
dcl Source char value ( 555 Bailey Ave, San Jose, CA 95141, USA);
dcl Digits char value (0123456789);
dcl (Start, End) fixed bin(31);
dcl Num char(20) var;
SECS
SECS returns a FLOAT BINARY(53) value that is the number of seconds (based on
Lilian format) corresponding to the date d.
SECS
( )
d
,p
,w
The allowed patterns are listed in Table 64 on page 417. For an explanation of
Lilian format, see Date/time built-in functions on page 415.
Example
dcl Dayname (7) char(9) var
static nonasgn init( Sunday,
Monday,
Tuesday,
Wednesday,
Thursday,
Friday,
Saturday);
dcl Jul4_1776_Secs float bin(53);
dcl Age_Tot_Secs pic Z,ZZZ,ZZZ,ZZZ,ZZ9;
SECSTODATE
SECSTODATE returns a nonvarying character string containing the date in the
date/time pattern specified by p that corresponds to d seconds (based on Lilian
format).
SECSTODATE ( d )
,p
,w
d The number of seconds (in Lilian format). d must have a computational type
and is converted to FLOAT BIN(53) if necessary.
p One of the supported date/time patterns. If omitted, p is assumed to be the
default date/time pattern 'YYYYMMDDHHMISS999' (the default format
returned by DATETIME).
w Specifies an expression (such as 1950) that can be converted to an integer. If
negative, it specifies an offset to be subtracted from the value of the year when
the code runs. If omitted, w defaults to the value specified in the WINDOW
compile-time option.
The allowed patterns are listed in Table 64 on page 417. For an explanation of
Lilian format, see Date/time built-in functions on page 415.
SECSTODAYS
SECSTODAYS returns a FIXED BINARY(31,0) value that represents the number of
seconds x converted to days, ignoring incomplete days.
SECSTODAYS(x)
x Expression. The value for x must have computational type and should be
FLOAT BINARY(53). If not, it is converted to FLOAT BINARY(53).
SIGN
SIGN returns an unscaled REAL FIXED BINARY value that indicates whether x is
positive, zero, or negative.
SIGN(x)
x Real expression.
The BIFPREC compiler option determines the precision of the result returned.
SIGNED
SIGNED returns a signed FIXED BINARY value of x, with a precision specified by
p and q.
SIGNED(x )
,p
,q
x Expression.
p Restricted expression that specifies the number of digits to be maintained
throughout the operation.
q Restricted expression that specifies the scaling factor of the result. For a
fixed-point result, if p is given and q is omitted, a scaling factor of zero is the
default.
SIN
SIN returns a floating-point value that is an approximation of the sine of x. It has
the base, mode, and precision of x.
SIN(x)
SIND
SIND returns a real floating-point value that is an approximation of the sine of x. It
has the base and precision of x.
SIND(x)
SINH
SINH returns a floating-point value that represents an approximation of the
hyperbolic sine of x. It has the base, mode, and precision of x.
SINH(x)
SIZE
SIZE returns a FIXED BIN value that gives the implementation-defined storage, in
bytes, allocated to a variable x.
SIZE(x)
x A variable of any data type, data organization, alignment, and storage class,
except those in the following list:
v A BASED, DEFINED, parameter, subscripted, or structure or union
base-element variable that is an unaligned fixed-length bit string
v A minor structure or union whose first or last base element is an unaligned
fixed-length bit string (except where it is also the first or last element of the
containing major structure or union)
v A major structure or union that has the BASED, DEFINED, or parameter
attribute, and that has an unaligned fixed-length bit string as its first or last
element
v A variable not in connected storage
The value returned by SIZE(x) is the maximum number of bytes that could be
transmitted in the following circumstances:
declare F file record input
environment(scalarvarying);
read file(F) into(x);
v If x is a varying-length string, the returned value includes the length-prefix of
the string and the number of bytes in the maximum length of the string
v If x is an area, the returned value includes the area control bytes and the
maximum size of the area
v If x is an aggregate containing areas or varying-length strings, the returned
value includes the area control bytes, the maximum sizes of the areas, the length
prefixes of the strings, and the number of bytes in the maximum lengths of the
strings.
The SIZE built-in function must not be used on a BASED variable with adjustable
extents if that variable has not been allocated.
Under the CMPAT(V3) compiler option, SIZE returns a FIXED BIN(63) value.
Under all other CMPAT options, it returns a FIXED BIN(31) value.
Example
dcl Scids char(17) init(See you at SCIDS!) static;
dcl Vscids char(20) varying init(See you at SCIDS!) static;
dcl Stg fixed bin(31);
SMFTOJULIAN
SMFTOJULIAN returns a CHAR(7) value that holds the date in the Julian format
YYYYDDD.
SMFTOJULIAN(d)
SOURCEFILE
SOURCEFILE returns a nonvarying character string containing the name of the file
that contains the statement where this function is invoked.
SOURCEFILE
()
The string returned is system dependent and should be used for tracing and
debugging purposes only.
SOURCELINE
SOURCELINE() returns a FIXED BINARY(31,0) value that is the line number of the
statement where this function is invoked, within the file that contains that
statement. If the statement extends over several source lines, the number returned
is that of the line on which the statement starts.
SOURCELINE ( )
SQRT
SQRT returns a floating-point value that is an approximation of the positive square
root of x. It has the base, mode, and precision of x.
SQRT(x)
SQRTF
SQRTF is the same as SQRT except for these differences:
v SQRTF calculates its result inline if hardware architecture permits.
v The argument must be real.
v Invalid arguments will generate hardware exceptions.
v The accuracy of the result is set by the hardware.
STACKADDR
STACKADDR returns the address of the dynamic save area (DSA) for the
procedure (or BEGIN block) in which it is invoked.
STACKADDR
()
STORAGE
STORAGE is a synonym for SIZE.
Abbreviation: STG
Related information:
SIZE on page 725
SIZE returns a FIXED BIN value that gives the implementation-defined storage, in
bytes, allocated to a variable x.
STRING
STRING returns a string that is the concatenation of all the elements of x.
STRING(x)
The type of string returned has the same type as one of these base elements with
these exceptions:
v If any of the base elements are PICTUREs, then the type returned has
CHARACTER type.
v If any of the base elements have the GRAPHIC type, then the type returned is
GRAPHIC unless the STRINGOFGRAPHIC compiler options specifies that it
should be CHARACTER.
dcl
1 W,
2 X char(2),
2 Y picaa,
2 Z char(6);
dcl
1 W,
2 X char(2),
2 Y pic99,
2 Z char(6);
dcl
1 A,
2 B bit(8) aligned,
2 C bit(2),
2 D bit(8) aligned;
STRING pseudovariable
The STRING pseudovariable assigns a string to x as if x were a string scalar. Any
remaining strings in x are filled with blanks or zero bits, or, if varying-length, are
given zero length.
STRING(x)
SUBSTR
SUBSTR returns a substring, specified by y and z, of x.
SUBSTR(x,y )
,z
x String expression. It specifies the string from which the substring is extracted.
If x is not a string, it is converted to character.
y Expression that is converted to FIXED BINARY(31,0). y specifies the starting
position of the substring in x.
z Expression that is converted to FIXED BINARY(31,0). z specifies the length of
the substring in x. If z is zero, a null string is returned. If z is omitted, the
substring returned is position y in x to the end of x.
SUBSTR pseudovariable
The SUBSTR pseudovariable assigns a string value to a substring, specified by y
and z, of x. The remainder of x is unchanged. Assignments to a varying string do
not change the length of the string.
SUBSTR(x,y )
,z
SUBTRACT
SUBTRACT is equivalent to ADD(x,-y,p,q).
SUBTRACT(x,y,p )
,q
For details about arguments, see ADD on page 432 for argument descriptions.
SUCC
SUCC returns a floating-point value that is the smallest representable number
larger than x. It is the base, mode, and precision of x. The OVERFLOW condition is
raised if there is no such number.
SUCC(x)
SUM
SUM returns the sum of all the elements in x. The base, mode, and scale of the
result match those of x.
SUM(x)
SYSNULL
SYSNULL returns the system null pointer value. You can assign SYSNULL to
handles and compare it with handles. You can use SYSNULL to initialize static
pointer and offset variables.
SYSNULL
()
Note: NULL and SYSNULL may compare equal; however, you should not write
code that depends on their equality.
SYSTEM
SYSTEM(x) returns a FIXED BIN(31,0) value that is the return value from the
command processor when it is invoked with the command contained in x.
SYSTEM
(x)
x Must have a computational type and should have characater type. If not, x is
converted to character.
TALLY
TALLY returns a FIXED BINARY(31,0) result that indicates the number of times
that string y appears in string x.
TALLY(x,y)
x and y
String expressions.
Both x and y must have computational type and should be character, bit,
graphic or widechar type.
Example
TALLY (Weve got the Power!, power); /* returns 0 */
TALLY (Weve got the Power!, Power); /* returns 1 */
TALLY (Weve got the Power!, ); /* returns 3 */
TALLY (Weve got the Power!, e); /* returns 4 */
TALLY (1001B, 1B); /* returns 2 */
TAN
TAN returns a floating-point value that is an approximation of the tangent of x. It
has the base, mode, and precision of x.
TAN(x)
TAND
TAND returns a real floating-point value that is an approximation of the tangent of
x. It has the base and precision of x.
TAND(x)
TANH
TANH returns a floating-point value that is an approximation of the hyperbolic
tangent of x. It has the base, mode, and precision of x.
TANH(x)
THREADID
THREADID (short for thread identifier) returns a POINTER value that is the
address of the operating system thread identifier for an attached thread.
THREADID ( x )
x Task reference. The value of x should have been set previously in the THREAD
option of the ATTACH statement.
The value returned by this built-in function can be used to invoke system
functions, such as DosSetPriority, on Windows, or posix functions on z/OS.
To obtain the system thread identifier for the currently executing thread, you must
invoke the function appropriate for the platform on which that thread is running.
So, on Windows, you should invoke GetCurrentThreadId, and on z/OS, you
should invoke pthread_self.
TIME
TIME returns a character string timestamp in the format HHMISS999.
TIME
()
TIMESTAMP
TIMESTAMP returns a CHAR(26) character string that gives the current date and
time in the format YYYY-MM-DD-HH.MI.SS.999999.
TIMESTAMP
()
TINY
TINY returns a floating-point value that is the smallest positive value x can
assume. It has the base, mode, and precision, of x.
TINY(x)
TRANSLATE
TRANSLATE returns a character string of the same length as x.
TRANSLATE(x,y )
,z
TRANSLATE will perform best when the second and third arguments are either
literals, named constants declared with the VALUE attribute, or restricted
expressions.
Example
dcl source char value("Ein Raetsel gibt es nicht.");
dcl target char(length(source));
dcl (to value (ABCDEFGHIJKLMNOPQRSTUVWXYZ),
from value (abcdefghijklmnopqrstuvwxyz)) char;
Note that you could also use the UPPERCASE built-in for the same purpose as the
TRANSLATE built-in in the example above. However, while the UPPERCASE
built-in function will translate only the standard alphabetic characters,
TRANSLATE can be used to translate other characters. For example, if "Raetsel"
were spelled with an a-umlaut, TRANSLATE could translate the a-umlaut to
A-umlaut if those characters were added to the from and to strings, respectively.
TRIM
TRIM returns a nonvarying character string with characters trimmed from one or
both ends.
TRIM(x )
,y
,z
x, y, and z
Expressions.
Each must have a computational type and should have the attribute
CHARACTER. If not, they are converted.
x is the string from which the characters defined by y are trimmed from the
left, and the characters defined by z are trimmed from the right.
If z is omitted, it defaults to a CHARACTER(1) NONVARYING string
containing one blank.
If y and z are both omitted, they both default to a CHAR(1) NONVARYING string
containing one blank.
Example
Target = trim(Source, , * );
/* "*** PL/Is got the Power!" */
TRUNC
TRUNC returns an integer value that is the truncated value of x. If x is positive or
0, this is the largest integer value less than or equal to x. If x is negative, this is the
smallest integer value greater than or equal to x.
TRUNC(x)
x Real expression.
The base, mode, scale, and precision of the result match those of x. Except when x
is fixed-point with precision (p,q), the precision of the result is given by:
(min(N,max(p-q+1,1)),0)
TYPE
TYPE returns the typed structure or union located by the handle, x.
TYPE(x)
x Handle
TYPE(x) dereferences the typed structure (or union) x. For an example of the TYPE
built-in functions, see TYPE pseudovariable on page 756.
TYPE pseudovariable
The TYPE pseudovariable assigns a typed structure or union to the storage located
by the handle x.
TYPE(x)
x Handle
ULENGTH
ULENGTH returns a FIXED BIN(31) value which is the number of UTF characters
held in a string.
ULENGTH(x)
If x has CHARACTER type, then the string must contain valid UTF-8 data. If not,
the program is in error.
If x has WIDECHAR type, then the string must contain valid UTF-16 data. If not,
the program is in error.
ULENGTH will return the number of UTF-8 or UTF-16 characters held in the
CHAR or WIDECHAR argument, respectively. It does not return the number of
characters if the string were normalized. So, for example, in UTF-8, a lowercase a
umlaut may be represented in the normalized or canonical form via the string
'c3_a4'x or in the unnormalized or combining form as '61_cc_88'x, but ULENGTH
will return 1 for the string 'c3_a4'x and 2 for the string '61_cc_88'x.
ULENGTH8
ULENGTH8 returns a FIXED BIN(31) value which is the length of a CHAR string
needed if the UTF characters held in a string were converted to UTF-8.
ULENGTH8(x)
If x has CHARACTER type, then ULENGTH8 is the same as LENGTH, and the
string will not be checked for valid UTF-8 data.
If x has WIDECHAR type, then the string must contain valid UTF-16 data, and
ULENGTH8 will return the length of the CHAR string that would result if x were
converted from UTF-16 to UTF-8. If the string does not contain valid UTF-16 data,
the program is in error.
ULENGTH16
ULENGTH16 returns a FIXED BIN(31) value which is the length of a WIDECHAR
string needed if the UTF characters held in a string were converted to UTF-16.
ULENGTH16(x)
If x has CHAR type, then the string must contain valid UTF-8 data, and
ULENGTH16 will return the length of the WIDECHAR string that would result if
x were converted from UTF-8 to UTF-16. If the string does not contain valid UTF-8
data, the program is in error.
If x has WIDECHAR type, then ULENGTH16 is the same as LENGTH, and the
string will not be checked for valid UTF-16 data.
UNALLOCATED
UNALLOCATED returns a bit(1) value indicating whether or not a specified
pointer value is the start of a piece of allocated storage. To use this built-in
function, you must also specify the CHECK(STORAGE) compile-time option.
UNALLOCATED(P)
p Pointer expression.
UNALLOCATED returns the bit(1) value '1'b if the specified pointer value is not
the start of a piece of storage that is obtained with the ALLOCATE statement or
the ALLOCATE built-in function.
Note that the pointer passed to UNALLOCATED is "rounded down" to the nearest
doubleword and that rounded value is compared against all allocated addresses
when similarly rounded down.
UNSIGNED
UNSIGNED returns an unsigned FIXED BINARY value of x, with a precision
specified by p and q.
UNSIGNED(x )
,p
,q
x Expression.
p Integer. It specifies the number of digits to be maintained throughout the
operation.
q Optionally-signed integer. It specifies the scaling factor of the result. For a
fixed-point result, if p is given and q is omitted, a scaling factor of zero is the
default.
UNSPEC
UNSPEC returns a bit string that is the internal coded form of x.
UNSPEC(x)
The length of the returned bit string depends on the attributes of x, as shown in
Table 80.
Table 80. Length of bit string returned by UNSPEC
Bit string length Attribute of x
8
SIGNED FIXED BINARY(p,q), 1 <= p <= 7
UNSIGNED FIXED BINARY(p,q), 1 <= p <= 8
ORDINAL SIGNED PRECISION(p), 1 <= p <= 7
ORDINAL UNSIGNED PRECISION(p), 1 <= p <= 8
16
SIGNED FIXED BINARY(p,q), 8 <= p <= 15
UNSIGNED FIXED BINARY(p,q), 9 <= p <= 16
ORDINAL SIGNED PRECISION(p), 8 <= p <= 15
ORDINAL UNSIGNED PRECISION(p), 9 <= p <= 16
32
ENTRY LIMITED, under LP(32)
SIGNED FIXED BINARY(p,q), 16 <= p <= 31
UNSIGNED FIXED BINARY(p,q), 17 <= p <= 32
ORDINAL SIGNED PRECISION(p), 16 <= p <= 31
ORDINAL UNSIGNED PRECISION(p), 17 <= p<= 32
FLOAT BINARY(p), 1 <= p <= 21
FLOAT DECIMAL(p), 1 <= p <= 6 if not DFP
FLOAT DECIMAL(p), 1 <= p <= 7 if DFP
OFFSET, under OFFSETSIZE(4)
FILE constant or variable, under LP(32)
POINTER(32)
HANDLE(32)
Alignment and storage requirements for program-control data can vary across
supported systems.
UNSPEC pseudovariable
The UNSPEC pseudovariable assigns a bit value directly to x; that is, without
conversion.
The bit value is padded, if necessary, on the right with '0'B to match the length of
x, according to Table 80 on page 762.
UNSPEC(x)
x Reference.
The pseudovariable is subject to the rules for the UNSPEC built-in function
described in UNSPEC on page 762.
Example
dcl 1 Str1 nonasgn static,
2 * fixed bin(15) littleendian init(16), /* 1000X */
2 * char init(33x),
2 * bit init(1b),
2 Ba(4) bit init(1b, 0b, 1b, 0b),
2 B3 bit(3) init(111b),
2 * char(0);
dcl Bit_Str1 bit(size(Str1)*8);
dcl Bit_Ba bit(dim(Ba)*length(Ba(1)));
dcl Bit_B3 bit(length(B3));
UPOS
UPOS returns a FIXED BIN(31) value which is the index of the nth UTF character
in a string.
UPOS(x,n)
If x has CHARACTER type, then the string must contain valid UTF-8 data. If not,
the program is in error.
If x has WIDECHAR type, then the string must contain valid UTF-16 data. If not,
the program is in error.
UPPERCASE
UPPERCASE returns a character string with all the alphabetic characters from a to
z converted to their uppercase equivalent.
UPPERCASE(x)
USUBSTR
USUBSTR returns a substring of a UTF string.
USUBSTR(x,i,j)
If x has CHARACTER type, then the string must contain valid UTF-8 data. If not,
the program is in error.
If x has WIDECHAR type, then the string must contain valid UTF-16 data. If not,
the program is in error.
The ERROR condition (and not the STRINGRANGE condition) will also be raised
if
v i is less than 1, or
v j is less than zero, or
v i + j - 1 is larger than ULENGTH(x)
USUPPLEMENTARY
USUPPLEMENTARY returns a FIXED BIN(31) value that is either the index of the
first of the UTF surrogate pair in a string or zero if the string contains no UTF
surrogate pairs.
USUPPLEMENTARY(x)
If x has CHARACTER type, then the string must contain valid UTF-8 data.
However, the validity of the data will not be checked. If the data is invalid, the
ERROR condition will not be raised, the program is in error, and the result
returned by this function will be unpredictable.
If x has WIDECHAR type, then the string must contain valid UTF-16 data.
However, the validity of the data will not be checked. If the data is invalid, the
ERROR condition will not be raised, the program is in error, and the result
returned by this function will be unpredictable.
w = 0020_0020_D834_DD1Ewx
jx = usupplementary(w);
UTCDATETIME
UTCDATETIME returns a character string that gives the current Coordinated
Universal Time (UTC) in the pattern YYYYMMDDHHMISS999.
UTCDATETIME
()
UTCSECS
UTCSECS returns a FLOAT BIN(53) value that gives the current Coordinated
Universal Time (UTC) in seconds in the Lilian format.
UTCSECS
()
The expression ( secs() utcsecs() ) provides the UTC offset in seconds. Dividing
that value by 3600 gives the UTC offset in hours.
UTF8
UTF8(x) returns a CHAR value that is the UTF-8 equivalent of x.
UTF8(x)
x An expression that must have one of these types: FIXED, FLOAT, PICTURE,
BIT, CHAR, or WIDECHAR.
If x has the type other than WIDECHAR, the CODEPAGE option specifies the
value for the code page of x when it is converted to UTF-8.
If x has the WIDECHAR type, it is converted to UTF-8 under the assumption that
x holds UTF-16.
You can use UTF8(x) in restricted expressions. Therefore, you can use UTF8(x) to
create UTF-8 literals.
Notes:
v If x has the CHAR type, the length of UTF8(x) might be two times as large as
the length of x. If x has the WCHAR type, the length of UTF8(x) might be three
times as the length of x. If the length of UTF8 exceeds the maximum length of
CHAR, the generated code raises the ERROR condition.
v If x has the WCHAR type and holds invalid UTF-16 data, the generated code
raises the ERROR condition.
UTF8STG
UTF8STG returns a FIXED BIN value that specifies the number of bytes that must
be present if the input character is the start of a valid UTF-8 character.
UTF8STG(x)
The function returns zero if the character cannot be the start of a valid UTF-8
character. For example, if the character has the value 80x, UTF8STG returns zero.
UTF8TOCHAR
UTF8TOCHAR(x) returns a CHAR value holding x converted from UTF-8.
UTF8TOCHAR(x)
Note: If x holds invalid UTF-8 data, the generated code raises the ERROR
condition.
UTF8TOWCHAR
UTF8TOWCHAR(x) returns a WCHAR value holding x converted from UTF-8 to
UTF-16.
UTF8TOWCHAR(x)
x An expression that must have the CHAR type. x is converted from UTF-8 to
UTF-16.
Note: If x holds invalid UTF-8 data, the generated code raises the ERROR
condition.
UUID
UUID returns a CHARACTER(36) string that is a universally unique identifier.
UUID
UVALID
UVALID returns a FIXED BIN(31) value which is zero if a string contains valid
UTF data and which is the index of the first invalid element if the string does not
contain valid UTF data.
UVALID(x)
If x has CHARACTER type, then UVALID(x) will return 0 if the string contains
valid UTF-8 data, and otherwise it will return the index of the byte where the first
invalid UTF-8 data starts.
If x has WIDECHAR type, then UVALID(x) will return 0 if the string contains valid
UTF-16 data, and otherwise it will return the index of the widechar where the first
invalid UTF-16 data starts.
Note that UVALID will indicate if the string contains valid UTF data (according to
the rules below). It does not indicate if these bytes have actually been allocated to
represent any particular character.
For UTF-8 data, the validity of a byte varies as follows according to its range:
v '00'x - '7f'x, it is valid
v '80'x - 'c1'x, it is invalid
v 'c2'x - 'df'x, it is valid if followed by a second byte and if that byte is in the
range '80'x to 'bf'x
v 'e0'x - 'ef'x, it is valid if followed by 2 more bytes and if
when the first byte is 'e0'x, the second and third bytes must be in the ranges
'a0'x to 'bf'x and '80'x to 'bf'x, respectively.
when the first byte is in the range 'e1'x to 'ec'x, the second and third bytes
must be in the ranges '80'x to 'bf'x
when the first byte is 'ed'x, the second and third bytes must be in the ranges
'80'x to '9f'x and '80'x to 'bf'x, respectively.
when the first byte is in the range 'ee'x to 'ef'x, the second and third bytes
must be in the ranges '80'x to 'bf'x
v 'f0'x - 'f4'x, it is valid if followed by 3 more bytes and if
when the first byte is 'f0'x, the second, third and fourth bytes must be in the
ranges '90'x to 'bf', '80'x to 'bf'x and '80'x to 'bf'x, respectively.
when the first byte is in the range 'f1'x to 'f3'x, the second, third and fourth
bytes must be in the range '80'x to 'bf'x
when the first byte is 'f4'x, the second, third and fourth bytes must be in the
ranges '80'x to '8f'x, '80'x to 'bf'x and '80'x to 'bf'x, respectively.
v 'f5'x - 'ff'x, it is invalid
For UTF-16 data, the validity of a widechar varies as follows according to its
range:
v '0000'wx - '007f'wx, it is valid and would be 1 byte if UTF-8
v '0080'wx - '07ff'wx, it is valid and would be 2 bytes if UTF-8
UWIDTH
UWIDTH returns a FIXED BIN(31) value which is the width of the nth UTF
character in a string.
UWIDTH(x,n)
If x has CHARACTER type, then the string must contain valid UTF-8 data. If not,
the program is in error.
If x has WIDECHAR type, then the string must contain valid UTF-16 data. If not,
the program is in error.
VALID
VALID returns a BIT(1) value that is '1'B under the following conditions:
v If x is PICTURE and its contents are valid for x's picture specification
v If x is FIXED DECIMAL and the data in x is valid fixed decimal data
VALID(x)
VALIDDATE
VALIDDATE returns a '1'B if the string d holds a date/time value that matches the
pattern p.
VALIDDATE ( d )
,p
,w
Allowable patterns are listed in Table 64 on page 417. For an explanation of Lilian
format, see Date/time built-in functions on page 415.
If the pattern contains punctuation characters, VALIDDATE checks that the input
string contains matching characters. For example, for the pattern YYYY-MM-DD,
VALIDDATE accepts 2008-03-14 but not 2008.03.14.
Example
dcl duedate char(8);
dcl (b1,b2) bit(1);
duedate = 19950228;
b1 = validdate( duedate, YYYYMMDD ); /* b1 = 1b */
duedate = 02301995;
b2 = validdate( duedate, DDMMYYYY ); /* b2 = 0b */
VARGLIST
VARGLIST returns the address of the first optional parameter passed to a
procedure with a variable number of arguments
VARGLIST()
VARGLIST may be used only inside a procedure whose last parameter has the
LIST attribute.
VARGSIZE
VARGSIZE returns the number of bytes that a variable would occupy on the stack
if it were passed byvalue.
VARGSIZE(x)
x A variable of any data type, data organization, alignment, and storage class,
except as listed below.
x cannot be:
v A BASED, DEFINED, parameter, subscripted, or structure or union
base-element variable that is an unaligned fixed-length bit string
v A minor structure or union whose first or last base element is an unaligned
fixed-length bit string (except where it is also the first or last element of the
containing major structure or union)
v A major structure or union that has the BASED, DEFINED, or parameter
attribute, and which has an unaligned fixed-length bit string as its first or
last element
v A variable not in connected storage
VARGSIZE(x) returns the number of bytes that x would occupy on the stack if it
were passed byvalue. This value will be at least as large as SIZE(x); it will be
larger if the value returned by SIZE(x) needs to be rounded up to a 4-byte
multiple.
VARGSIZE is meant to be used only inside a procedure whose last parameter has
the LIST attribute.
VERIFY
VERIFY returns an unscaled REAL FIXED BINARY value that indicates the
position in x of the leftmost character, widechar, graphic, or bit that is not in y. It
also allows you to specify the location within x at which to begin processing.
VERIFY(x,y )
,n
x String-expression.
y String-expression.
n Expression n specifies the location within x where processing begins. It must
have a computational type and is converted to FIXED BINARY(31,0).
The BIFPREC compiler option determines the precision of the result returned.
VERIFY will perform best when the second and third arguments are either literals,
named constants declared with the VALUE attribute, or restricted expressions.
Example
X = a b; /* Two blanks in each space */
Y = ; /* One blank */
N = 1;
I = verify(X,Y,N); /* I = 3 */
After the first pass through the do-loop, N=4 and VERIFY(X,Y,N) returns 6. After
the second pass, N=7 (LENGTH(x)+1), VERIFY(X,Y,N) now returns 0, and the loop
ends.
For more examples of the VERIFY built-in function, see SEARCH on page 714.
VERIFYR
The VERIFYR function performs the same operation as the VERIFY built-in
function except that the verification is done from right to left.
VERIFYR(x,y )
,n
The BIFPREC compiler option determines the precision of the result returned.
VERIFYR will perform best when the second and third arguments are either
literals, named constants declared with the VALUE attribute, or restricted
expressions.
Example
X = a b ; /* Two blanks in each space */
Y = ; /* One blank */
N = length(X); /* N = 6 */
I = verifyr(X,Y,N); /* I = 4 */
After the first pass through the do-loop, N=3 and VERIFYR(X,Y,N) returns 1. After
the second pass, N=0, VERIFYR(X,Y,N) returns 0, and the loop ends. For another
example, see SEARCHR on page 716.
WCHARVAL
WCHARVAL returns the WIDECHAR(1) value corresponding to an integer.
WCHARVAL ( n )
If n is in bigendian format, WCHARVAL(n) has the same bit value as n (that is,
UNSPEC(WCHARVAL(n)) is equal to UNSPEC(n)), but it has the attributes
WIDECHAR(1).
WEEKDAY
WEEKDAY returns a FIXED BINARY(31,0) value that is the number of days x
converted to the day of the week, where 1=Sunday, 2=Monday, . . . 7=Saturday. If x
is missing, it is assumed to be DAYS for today.
WEEKDAY
( )
x
WHIGH
WHIGH returns a widechar string of length x, where each widechar has the
highest widechar value (hexadecimal FFFF).
WHIGH(x)
WHITESPACECOLLAPSE
WHITESPACECOLLAPSE returns a size_t 1 value that indicates the number of
bytes that are written into the target buffer when it collapses all the whitespace in
the UTF-16 source buffer.
WHITESPACECOLLAPSE(p,m,q,n)
If the address of the target buffer is zero, the number of bytes to be written is
returned. If the target buffer is not large enough, a value of -1 is returned. If the
target buffer is large enough, the number of bytes that is written to the buffer is
returned.
WHITESPACEREPLACE
WHITESPACEREPLACE replaces each character of the whitespace in the UTF-16
XML source buffer from \t, \f, \v, \n, and \r by a UTF-16 blank. This function
returns a size_t 1 value that indicates the number of bytes that are written into the
target buffer when WHITESPACEREPLACE replaces the whitespace.
WHITESPACEREPLACE(p,m,q,n)
If the address of the target buffer is zero, the number of bytes to be written is
returned. If the target buffer is not large enough, a value of -1 is returned. If the
target buffer is large enough, the number of bytes that is written to the buffer is
returned.
WIDECHAR
WIDECHAR returns the widechar value of x, with a length specified by y.
WIDECHAR(x )
,y
Abbreviation: WCHAR
x Expression.
x must have a computational type.
The values of x are not checked.
y Expression. If necessary, y is converted to a real fixed-point binary value.
If y is omitted, the length is determined by the rules for type conversion.
y cannot be negative.
If y = 0, the result is the null widechar string.
WLOW
WLOW returns a widechar string of length x, where each widechar has the lowest
widechar value (hexadecimal 0000).
WLOW(x)
XMLCHAR
The XMLCHAR built-in function dumps data from a structure as XML into a
buffer. It returns a size_t 1 value that indicates the number of bytes written to the
buffer. If the buffer is too small, the structure data is truncated and the number of
bytes needed for the buffer to contain the structure is returned.
XMLCHAR ( x , p , n )
x Structure-reference.
The structure-reference x must conform to the following rules:
v It must contain only computational data, that is, only string and numeric
data. However, it must not contain any GRAPHIC, WIDECHAR, or
WIDEPIC elements.
v It may contain arrays, but if it is an array itself, it must be completely
subscripted.
v It may contain substructures, but any contained substructure must not use
an asterisk (*) in place of a name. However, an asterisk may be used as the
name of a base element, but in that case, the unnamed element will not be
written to the target buffer.
p Address of the target buffer.
n Length of the target buffer.
The buffer length must be nonnegative and must have a computational type.
The buffer length is converted to type size_t.
Note: By default the names of the variables in the generated XML output are all in
upper case. The CASE(ASIS) suboption of the XML compiler option can be used to
specify that the names appear in the case in which they were declared.
dcl
1 a,
2 a1,
3 b1 char(8),
3 b2 char(8),
2 a2,
3 c1 fixed bin,
3 c2 fixed dec(5,1);
b1 = t1;
b2 = t2;
c1 = 17;
c2 = -29;
next = addr(buffer);
left = stg(buffer);
written = xmlchar( a, next, left );
next += written;
left -= written;
The following bytes would be written to the buffer, and written would be set
equal to 72.
<A><A1><B1>t1</B1><B2>t2</B2></A1><A2><C1>17</C1><C2>-29.0</C2></A2></A>
Related information:
XMLCONTENT attribute on page 196
The XMLCONTENT attribute specifies that when a variable is included in the text
that is generated by the XMLCHAR built-in function, it is presented as tagless text.
XMLCLEAN
The XMLCLEAN built-in function cleans the UTF-16 source buffer. It returns a
size_t 1 value that indicates the number of bytes that are written into the target
buffer.
XMLCLEAN cleans the UTF-16 source buffer by one of the following means:
v Replacing each invalid UTF-16 with a UTF-16 blank.
v Replacing carriage returns with 
.
v Replacing the following characters with corresponding strings as follows:
Characters Strings
" "
'
& &
< <
> >
XMLCLEAN(p,m,q,n)
If the address of the target buffer is zero, the number of bytes to be written is
returned. If the target buffer is not large enough, a value of -1 is returned. If the
target buffer is large enough, the number of bytes that is written to the buffer is
returned.
Y4DATE
Y4DATE takes a date value with the pattern 'YYMMDD' and returns the date value
with the two-digit year widened to a four-digit year.
Y4DATE(d )
,w
The returned value has the attributes CHAR(8) NONVARYING and is calculated as
follows:
dcl y2 pic99;
dcl y4 pic9999;
dcl cc pic99;
y2 = substr(d,1,2);
cc = w/100;
return( y4 || substr(d,3) );
Y4JULIAN
Y4JULIAN takes a date value with the pattern 'YYDDD' and returns the date value
with the two-digit year widened to a four-digit year.
Y4JULIAN(d )
,w
The returned value has the attributes CHAR(7) NONVARYING and is calculated as
follows:
dcl y2 pic99;
dcl y4 pic9999;
dcl c pic99;
y2 = substr(d,1,2);
cc = w/100;
return( y4 || substr(d,3) );
Y4YEAR
Y4YEAR takes a date value with the pattern 'YY' and returns the date value with
the two-digit year widened to a four-digit year.
Y4YEAR(d )
,w
The returned value has the attributes CHAR(4) NONVARYING and is calculated as
follows:
dcl y2 pic99;
dcl y4 pic9999;
dcl c pic99;
y2 = d;
cc = w/100;
return( y4 );
Type functions are distinguished from built-in functions in the following ways:
v At least one of the arguments is a defined type.
v They cannot be declared.
v Arguments are enclosed in the (: and :) composite symbols, rather than in ( and )
symbols.
name
,
(: :)
argument
The arguments for a type function are enclosed by the delimiters (: and :).
BIND
BIND converts the pointer p to a handle for the structure type t. The BIND
function can be used as a locator for a member of a typed structure.
BIND (: t , p :)
CAST
CAST converts the expression x to the type t using C conversion rules.
CAST (: t , x :)
Any conversions that are needed follow the ANSI C rules. This means, for
instance, that SIZE will not be raised by CAST and that if negative values are cast
to UNSIGNED, the result will be a large positive number.
FIRST
FIRST returns the first value in the ordinal set t.
FIRST (: t :)
Example
define ordinal Color ( Red,
Orange,
Yellow,
Green,
Blue,
Indigo,
Violet );
LAST
LAST returns the last value in the ordinal set t.
LAST (: t :)
Example
define ordinal Color ( Red,
Orange,
Yellow,
Green,
Blue,
Indigo,
Violet );
NEW
NEW acquires heap storage for structure type t and returns a handle to the
acquired storage.
NEW (: t :)
RESPEC
RESPEC changes the attributes of the expression x to the type t without changing
the bit value of the expression.
RESPEC (: t , x :)
x must have the same size as t, and if either x or t is UNALIGNED BIT, both must
be UNALIGNED BIT (in which case the function is somewhat uninteresting
because it would do nothing).
SIZE
SIZE returns the amount of storage needed for a variable declared with the type t.
SIZE (: t :)
VALUE
The VALUE type function initializes or assigns to a variable that has the
corresponding structure type.
VALUE(restricted-expression)
If the VALUE function is used with a structure type that is partially initialized,
uninitialized bytes and bits are set to zero.
The VALUE function cannot be used with a structure type containing no elements
with the INITIAL attribute.
You can use the VALUE function with the INIT form of the INITIAL attribute on
the elements of a DEFINE STRUCTURE statement. However, you cannot use INIT
CALL and INIT TO with the VALUE function on the elements of a DEFINE
STRUCTURE statement.
define struct
1 c,
2 c1 type b init( value(: b :) ),
2 c2 fixed bin init(23);
y = value(: c :);
This description of the preprocessor assumes that you know the PL/I language
described throughout this publication.
4. For clarity in this discussion, preprocessor statements are shown with the % symbol (even though, when used in a preprocessor
procedure, such a statement would not have a % symbol).
5. Preprocessor replacement output is shown in a formatted style, while actual execution-generated replacement output is
unformatted.
You can specify compile-time options that cause the preprocessor input, the
preprocessor output, or both to be printed or written to a data set.
Preprocessor options
The preprocessor is invoked when you specify the MACRO or PP(MACRO)
compile-time option. You can also specify compiler options that affect the
preprocessor only. Some of the options can significantly change the behavior of the
preprocessor.
For more information about how to specify these options, see the Programming
Guide.
Preprocessor scan
The preprocessor starts its scan at the beginning of the preprocessor input and
scans each character sequentially.
To determine replacements, the input text is scanned for the following occurrences:
v Characters that are not part of this PL/I character set
These characters are treated as delimiters and are otherwise copied to this
output unchanged.
v PL/I character constants or PL/I comments
These are passed through unchanged from input text to preprocessor output by
the preprocessor unless they appear in an argument list to an active
preprocessor procedure. However, this can cause mismatches between input and
output lines for strings or comments extending over several lines, when the
input and output margins are different. This is especially true when V format
input is used, because the output is always F format, with margins in columns 2
and 72. The output line numbering in these cases also shows this inevitable
mismatch.
v Active identifiers
For an identifier to be replaced by a new value, the identifier must be first
activated for replacement. Initially, an identifier can be activated by its
appearance in a %DECLARE statement. It can be deactivated by executing a
%DEACTIVATE statement, and it can be reactivated by executing a %ACTIVATE
or %DECLARE statement.
An identifier that matches the name of an active preprocessor variable is
replaced in the preprocessor output by the value of the variable.
When an identifier matches the name of an active preprocessor function (either
programmer-written or built-in), the procedure is invoked and the invocation is
replaced by the returned value.
Identifiers can be activated with either the RESCAN or the NORESCAN options.
If the NORESCAN option applies, the value is immediately inserted into the
preprocessor output. If the RESCAN option applies, a rescan is made during
which the value is tested to determine whether it, or any part of it, should be
replaced by another value. If it cannot be replaced, it is inserted into the
preprocessor output; if it can be replaced, replacement activity continues until no
further replacements can be made. Thus, insertion of a value into the
preprocessor output takes place only after all possible replacements have been
made.
Preprocessor statements should be on separate lines from normal text. The one
exception is the null statement when it is specified in the form %;. Such a null
statement can be used to concatenate replacement text and regular text. For
example, suppose that the input text is as follows:
%dcl A char;
%A = B;
The scan terminates when an attempt is made to scan beyond the last character in
the preprocessor input. The preprocessor output is then complete and compilation
can begin.
Although not required, it is always the best practice that you specify the FIXED or
CHARACTER attribute for each variable in a %DECLARE.
Preprocessor data types are coded arithmetic and string data, and are declared
with one of the following attributes:
FIXED
A preprocessor variable declared with the FIXED attribute is, by default, given
the attributes DECIMAL(5,0).
If the FIXED(BINARY) macro preprocessor option is in effect, it is given the
attributes BINARY(31,0).
In either case, it is given an initial value of 0.
Fractional values are not supported.
CHARACTER
A preprocessor variable declared with the CHARACTER attribute is given the
VARYING attribute.
It is given an initial value of ''.
INITIAL
A preprocessor variable declared with the INITIAL attribute is assigned with
the specified initial values.
There are no preprocessor bit variables. However, bit constants are allowed, and bit
values result from comparison operators, the concatenation operator (when used
with bit operands), the not operator, and the PARMSET built-in function. The
preprocessor-expression in the %IF statement converts to a bit value.
The only numeric constants supported by the preprocessor are optionally signed,
unscaled integers (such as 17 or -29).
The only string constants supported by the preprocessor are character and bit
strings, either of which can be specified by using the hexadecimal notation (i.e. as
X or BX strings).
String repetition factors are not allowed. However, the COPY built-in function can
be used to replicate a constant.
Preprocessor procedures
A preprocessor procedure is a collection of statements that specifies the actions to
be performed by the preprocessor. A preprocessor procedure is delimited by
%PROCEDURE and %END statements.
If the procedure is not defined with a RETURNS attribute, it can contain ANSWER
statements, but it must not contain any RETURN statements. Conversely, if the
814 Enterprise PL/I for z/OS Language Reference
Preprocessor procedures
The following statements and groups can be used within a preprocessor procedure:
v The preprocessor ANSWER statement
v The preprocessor assignment statement
v The preprocessor CALL statement
v The preprocessor DECLARE statement
v The preprocessor DO-group
v The preprocessor GO TO statement
A GO TO statement appearing in a preprocessor procedure cannot transfer
control to a point outside of that procedure.
v The preprocessor IF statement
v The preprocessor ITERATE statement
v The preprocessor LEAVE statement
v The preprocessor null statement
v The preprocessor NOTE statement
v The preprocessor RETURN statement
v The preprocessor SELECT-group
Provided that its entry name is active, a preprocessor procedure need not be
scanned before it is invoked. However, it must be present in the preprocessor
input, or a string is included before the point of invocation.
The value returned by a preprocessor function (that is, the value of the
preprocessor expression in the RETURN statement) replaces the function reference
and its associated argument list in the preprocessor output.
If there are more positional arguments than parameters, the excess arguments on
the right are ignored. (For an argument that is a function reference, the function is
invoked and executed, even if the argument is ignored later.) Parameters that are
not set by the function reference are given values of zero, for FIXED parameters, or
the null string, for CHARACTER parameters.
Parameters should not be set more than once by a function reference. However, if
the value of a parameter is specified more than once (for example, both by its
position and by keyword), the error is diagnosed and the leftmost setting is used
for the invocation.
If the function reference appears in input text, dummy arguments are always
created. The arguments are interpreted as character strings and are delimited by a
comma or right parenthesis. A comma or right parenthesis does not act as a
delimiter, however, if it appears between matching parentheses, single quotation
marks, or comment delimiters. For example, the positional argument list (A(B,C),D)
has two arguments, namely, the string A(B,C) and the string D. Blanks in
arguments (including leading and trailing blanks) are significant but, if such blanks
extend to the end of a line and are not enclosed in quotation marks or comment
delimiters, they are replaced by one blank.
%PROCEDURE statement
The %PROCEDURE statement is used in conjunction with a %END statement to
delimit a preprocessor procedure.
% entry-name: PROCEDURE
, STATEMENT
( parameter )
;
RETURNS ( CHARACTER )
FIXED
Abbreviation: %PROC
parameter
Specifies a parameter of the function procedure.
STATEMENT
If the reference occurs in input text and the STATEMENT option is present, the
following rules apply:
v The arguments can be specified either in the positional argument list or by
keyword reference.
v The end of the reference must be indicated by a semicolon. The semicolon is
not retained when the replacement takes place.
For example, a preprocessor procedure headed by %FIND:PROC(A,B,C)
STATEMENT...; must be invoked from a preprocessor expression by a reference
of the form:
FIND(arg1,arg2,arg3)
If the reference is in input text, the procedure can be invoked by any of the
following references (or similar ones), all of which have the same result:
FIND(X,Y,Z);
FIND(,Y,Z) A(X);
RETURNS
Specifies the attribute of the value returned by the function procedure. You
must specify one of the following attributes:
v CHARACTER
v FIXED
RETURN ( preprocessor-expression ) ;
label:
preprocessor-expression
The value is converted to the RETURNS attribute specified in the
%PROCEDURE statement before it is passed back to the point of invocation.
ANSWER
( exp1 ) PAGE
SKIP
( exp2 )
;
COLUMN ( exp3 ) MARGINS
( exp4 )
, exp5
Abbreviations: ANS for ANSWER, COL for COLUMN, MAR for MARGINS
exp1
Represents a character expression that represents the ANSWER text. The
ANSWER text can be either a single character string constant or a preprocessor
expression of any complexity.
If it is an expression, the expression evaluation occurs in the usual manner and
the result is converted to a single character string.
If SCAN or RESCAN is in effect, the character string is scanned for
replacements and preprocessor procedure invocations. This replacement is
done within the scope of the preprocessor procedure and not in the scope into
which the answered text is returned. The answered text is then inserted into
the source at the point of the preprocessor invocation. After the text is returned
into the source, it is not scanned for any replacement activity.
Replacement activity in the string follows the same rules as those for source
text scanning and replacement. See Example on page 819.
PAGE
Forces the answer text to be placed on a new page of the output source by
generating a %PAGE directive.
SKIP
Forces the answer text to be placed on a new line of the output source. The
value of exp2 represents the arithmetic expression specifying the number of
lines to be skipped. If exp2 is not specified, the default value is 1.
COLUMN
Specifies the starting column in the source program line in which the answer
text is placed. The value of exp3 represents the arithmetic expression for the
column number of the source program line where the answer text starts.
MARGINS
Specifies where the output text is placed within the output record. The value of
exp4 represents the arithmetic expression for the left margin for the output text.
The value of exp5 represents the arithmetic expression for the right margin for
the output text.
The values specified for exp5 must be within the range returned by the
MACLMAR (left margin) and MACRMAR (right margin) built-in functions.
If you do not specify the MARGINS option for an ANSWER statement, the
default value is MARGINS(MACLMAR,MACRMAR); if you specify the
MARGINS option with no operands, the default value is
MARGINS(MACCOL,MACRMAR).
You must not use both the RETURN statement with an expression and the
ANSWER statement within the same preprocessor procedure.
Note: If a macro is invoked in an expression and that macro does not return a
value, the macro preprocessor acts as if the macro returned a null string.
Example
%dcl (Expression, Single_string) entry;
%dcl (Deactivated_macro, Statement_function) entry;
%dcl Deactivated_variable character;
%deact Deactivated_variable, Deactivated_macro;
%Deactivated_variable = ** value of deactivated variable **;
%Expression: procedure;
ANS( Counter ) skip;
ANS( Deactivated_macro ) skip;
ANS( Deactivated_variable ) skip;
/* The following is invalid: */
/* ANS( Statement_function Key1(7);); */
%end;
%Single_string: procedure;
ANS( Counter ) skip;
ANS( Deactivated_macro ) skip;
ANS( Deactivated_variable ) skip;
ANS( Statement_function Key1( 7 ); ) skip;
%end;
Expression /* Generates: */
/* 00001 */
/* ** value of deactivated macro ** */
/* ** value of deactivated variable ** */
Single_string /* Generates: */
/* Counter */
/* Deactivated_macro */
/* Deactivated_variable */
/* 14 */
CALL procedure-name ( ) ;
,
argument
*
procedure-name
Specifies the name of the procedure to be called. The procedure must not have
the RETURNS attribute or the STATEMENT option.
argument
Specifies an element, an element expression, or an aggregate to be passed to
the invoked subroutine. See Passing arguments to procedures on page 114.
The following preprocessor built-in functions do not require arguments and must
not be given a null argument:
COLLATE
COLLATE returns a CHARACTER string of length 256 comprising the 256 possible
character values one time each in the collating order.
COLLATE
COMMENT
COMMENT converts a CHARACTER expression into a comment.
COMMENT(x)
COMPILEDATE
COMPILEDATE returns a CHARACTER string of length 17 containing the date
and the time of the compilation.
COMPILEDATE
Example
The following example shows how to print the string returned by COMPILEDATE
when your program is run:
%DECLARE COMP_DATE CHAR;
%COMP_DATE=QUOTE(COMPILEDATE);
PUT EDIT (COMP_DATE) (A);
COMPILETIME
COMPILETIME returns a CHARACTER string of length 18 containing the date and
the time of compilation.
COMPILETIME
A leading zero in the day of the month field is replaced by a blank; no other
leading zeros are suppressed.
If no timing facility is available, the last 8 characters of the returned string are set
to 00.00.00.
Example
The following example shows how to print the string returned by COMPILETIME
when your program is executed:
%DECLARE COMP_TIME CHAR;
%COMP_TIME=QUOTE(COMPILETIME);
PUT EDIT (COMP_TIME) (A);
COPY
COPY returns a CHARACTER string consisting of y concatenated copies of the
string x.
COPY(x,y)
x Expression.
x should have CHARACTER type, and if not, it is converted thereto.
y Expression that specifies the number of repetitions. y should have FIXED type,
and if not, it is converted thereto.
y must be nonnegative.
COUNTER
COUNTER returns a CHARACTER string of length 5 containing a decimal
number. The returned number is 00001 for the first invocation, and increments by
one on each successive invocation.
COUNTER
The COUNTER built-in function can be used to generate unique names, or for
counting purposes.
DIMENSION
DIMENSION returns a FIXED value specifying current extent of dimension y of x.
DIMENSION(x )
,y
Abbreviation: DIM
x Array reference. x must not have less than y dimensions.
y Expression specifying a particular dimension of x.
y should have FIXED type, and if not, it will be converted thereto.
y must be greater than or equal to 1. If y is not supplied, the default is 1.
y can be omitted only if the array is one-dimensional.
HBOUND
HBOUND returns a FIXED value specifying current upper bound of dimension y
of x.
HBOUND(x )
,y
INDEX
INDEX returns a FIXED value indicating the starting position within x of a
substring identical to y. You can also specify the location within x where
processing begins.
INDEX(x,y )
,n
x Expression to be searched.
x should have CHARACTER type, and if not, it will be converted thereto.
y Target expression of the search.
y should have CHARACTER type, and if not, it will be converted thereto.
n n specifies the location within x at which to begin processing.
n should have FIXED type, and if not, it will be converted thereto.
If y does not occur in x, or if either x or y have zero length, the value zero is
returned.
LBOUND
LBOUND returns a FIXED value specifying current lower bound of dimension y of
x.
LBOUND(x )
,y
LENGTH
LENGTH returns a FIXED value specifying the current length of a given character
expression.
LENGTH ( x )
x Expression.
x should have CHARACTER type, and if not, it is converted thereto.
LOWERCASE
LOWERCASE returns a CHAR string with all the alphabetic characters from A to Z
converted to their lowercase equivalent.
LOWERCASE ( x )
x Expression.
x should have CHARACTER type, and if not, it is converted thereto.
MACCOL
MACCOL returns a FIXED value that represents the column where the outermost
macro invocation starts in the source text that contains the macro invocation.
MACCOL
MACLMAR
MACLMAR returns a FIXED value that represents the column number of the left
source margin in MARGINS compiler option.
MACLMAR
See the information about the MARGINS option in the Programming Guide.
MACNAME
MACNAME returns the name of the preprocessor procedure within which it is
invoked.
MACNAME
MACRMAR
MACRMAR returns a FIXED value that represents the column number of the right
source margin in MARGINS compiler option.
MACRMAR
See the information about the MARGINS option in the Programming Guide.
MAX
MAX returns the largest value from a set of two or more expressions.
MAX( x, y )
x and y
Expressions.
All the arguments should be FIXED, and any that are not FIXED are converted
thereto.
MIN
MIN returns the smallest value from a set of two or more expressions.
MIN( x, y )
x and y
Expressions.
All the arguments should be FIXED, and any that are not FIXED are converted
thereto.
PARMSET
PARMSET returns a BIT value indicating if a specified parameter was set on
invocation of the procedure.
PARMSET ( x )
The PARMSET built-in function can be used only within a preprocessor procedure.
PARMSET returns a bit value of '1'B if the parameter x was explicitly set by the
function reference that invoked the procedure, and a bit value of '0'B if it was
notthat is, if the corresponding argument was omitted from the function
reference in a preprocessor expression, or was the null string in a function
reference from input text.
PARMSET can return '0'B, even if a matching argument does appear in the
reference, but the reference is in another preprocessor procedure, as follows:
v If the argument is not itself a parameter of the invoking procedure, PARMSET
returns the value '1'B.
v If the argument is a parameter of the invoking procedure, PARMSET returns the
value for the specified parameter when the invoking procedure was itself
invoked.
QUOTE
QUOTE returns a CHARACTER string that represents x as a valid quoted string.
QUOTE(x)
REPEAT
REPEAT returns a CHARACTER string consisting of (y + 1) concatenated copies of
the string x.
REPEAT(x,y)
x Expression.
x should have CHARACTER type, and if not, it is converted thereto.
y Expression that specifies the number of repetitions. y should have FIXED type,
and if not, it is converted thereto.
y must be nonnegative.
SUBSTR
SUBSTR returns a substring, specified by y and z, of x.
SUBSTR(x,y )
,z
z must be nonnegative, and the values of y and z must be such that the substring
lies entirely within the current length of x.
SYSDIMSIZE
SYSDIMSIZE returns a FIXED value that indicates the maximum number of bytes
that is needed to hold an index for an array permitted under the compiler CMPAT
option.
SYSDIMSIZE
SYSOFFSETSIZE
SYSOFFSETSIZE returns a FIXED value that indicates the number of bytes needed
to hold an OFFSET.
SYSOFFSETSIZE
SYSPARM
SYSPARM returns the CHARACTER string value of the SYSPARM compiler
option.
SYSPARM
The value returned is not translated to uppercase; the exact value as specified in
the compiler option is returned. See the information about the SYSPARM compiler
option in the Programming Guide.
SYSPOINTERSIZE
SYSPOINTERSIZE returns a FIXED value that indicates the number of bytes
needed to hold a POINTER.
SYSPOINTERSIZE
SYSTEM
SYSTEM returns a CHARACTER string that contains the value of the SYSTEM
compiler option that is in effect.
SYSTEM
Note: The value returned might contain leading and trailing blanks. You can apply
the TRIM built-in function to that value to make it easier to test.
See the information about the SYSTEM compiler option in the Programming Guide.
SYSVERSION
SYSVERSION returns a CHARACTER string containing the product name as well
as the version, release, and modification level.
SYSVERSION
The result that SYSVERSION returns is a string of length 22 in one of the following
formats. Each string is padded with blanks on the right to make it 22 in length.
Under z/OS
PL/I for z/OS Vx.Ry.Mz
Under AIX
PL/I for AIX x.y
Under Windows
PL/I for Win* x.y
TRANSLATE
TRANSLATE returns a CHARACTER string of the same length as x, but with
selected characters translated.
TRANSLATE(x,y )
,z
TRIM
TRIM returns a CHAR string with characters trimmed from one or both ends of an
input string.
TRIM ( x )
, y
, z
UPPERCASE
UPPERCASE returns a CHAR string with all the alphabetic characters from a to z
converted to their uppercase equivalent.
UPPERCASE ( x )
x Expression.
x should have CHARACTER type, and if not, it is converted thereto.
VERIFY
VERIFY returns a FIXED value indicating the position in x of the leftmost character
that is not in y. It also allows you to specify the location within x at which to begin
processing.
VERIFY(x,y )
,n
x Expression.
x should have CHARACTER type, and if not, it is converted thereto.
y Expression.
y should have CHARACTER type, and if not, it is converted thereto.
n Expression n specifies the location within x where processing begins.
n should have FIXED type, and if not, it is converted thereto.
Preprocessor statements
This section lists the preprocessor statements in alphabetical order and describes
each statement.
Comments can appear within preprocessor statements wherever blanks can appear.
Such comments are not inserted into preprocessor output text.
%ACTIVATE statement
A %ACTIVATE statement makes an identifier active and eligible for replacement.
Any subsequent encounter of that identifier in the input text while the identifier is
active initiates replacement activity.
,
RESCAN
% ACTIVATE identifier ;
SCAN
NORESCAN
Abbreviation: %ACT
identifier
Specifies the name of a preprocessor variable, a preprocessor procedure, or a
preprocessor built-in function.
The identifier should not refer to an array variable.
RESCAN
Specifies that the identifier is replaced as many times as necessary to replace
all active identifiers before being placed into the output.
SCAN
Specifies that the identifier is replaced only once before being placed into the
output.
NORESCAN
Synonym for SCAN.
Using the %ACTIVATE statement for an identifier that is already active has no
effect, except possibly to change the scanning status.
%assignment statement
A %assignment statement evaluates a preprocessor expression and assigns the
result to a preprocessor variable.
% preprocessor-variable = preprocessor-expression ;
label:
The target in an assignment must not be an array, but it can be an array element.
%DEACTIVATE statement
A %DEACTIVATE statement makes an identifier inactive.
% DEACTIVATE identifier ;
label:
Abbreviation: %DEACT
identifier
Specifies the name of either a preprocessor variable, a preprocessor procedure,
or a preprocessor built-in function.
The deactivation of an identifier causes loss of its replacement capability but not its
value. Hence, the reactivation of such an identifier need not be accompanied by the
assignment of a replacement value.
The deactivation of an identifier does not prevent it from receiving new values in
subsequent preprocessor statements.
%DECLARE statement
The %DECLARE statement establishes an identifier as a macro variable, macro
procedure, or built-in function. In addition, scanning status can be specified for
macro variables.
( identifier )
Or
identifier description:
identifier attributes
( dimension )
,
( identifier )
( dimension )
dimension:
hbound
lbound :
,
attributes:
CHARACTER
FIXED
Specifies that the identifier represents an integer.
Under the (default) FIXED(DECIMAL) option, it is also given the attributes
DECIMAL(5,0).
Under the FIXED(BINARY) option, it is also given the attributes BINARY(31,0).
RESCAN
Specifies that the identifier is active and is replaced as many times as
necessary.
SCAN
Specifies that the identifier is active and is replaced only once in output.
NOSCAN
Specifies that the identifier is inactive and is not to be replaced in output.
dimension
Dimension specification for array variables. No more than 15 dimensions can
be specified.
%DO statement
The %DO statement, and its corresponding %END statement, delimit a
preprocessor DO-group, and can also specify repetitive execution of the DO-group.
For the syntax for the %DO statement, see DO statement on page 223.
Note: All the formats of the DO statement are supported with the following
exceptions:
v UPTHRU and DOWNTHRU are not accepted.
v The specification in Type 3 DO statements cannot be specified multiple times.
However, the %DO statement also supports an additional format not supported by
the DO statement: the %DO SKIP; statement. This statement causes all code
through the matching %END statement to be ignored (and thus can be useful as a
way of "commenting out" code that contains comments).
Preprocessor statements, input text, and listing control statements can appear
within a preprocessor DO-group. The preprocessor statements are executed, and
any input text is scanned for possible replacement activity.
%END statement
The %END statement is used in conjunction with %DO, %SELECT or
%PROCEDURE statements to delimit preprocessor DO-groups, SELECT-groups, or
preprocessor procedures.
% END ;
label
label:
%GO TO statement
The %GO TO statement causes the preprocessor to continue its scan at the
specified label.
% GO TO label ;
label:
Abbreviation: %GOTO
The label following the GO TO specifies the point to which the scan is transferred.
It must be a label of a preprocessor statement, although it cannot be the label of a
preprocessor procedure.
A %GO TO statement in included text can transfer control only to a point within
the same include file. The target label in the %GOTO statement must not precede
the %GOTO.
Related information:
%INCLUDE statement on page 860
The external text specified by a %INCLUDE statement is included into the
preprocessor input at the point at which the %INCLUDE statement is executed.
Such text, once included, is called included text and can consist of preprocessor
statements, listing control statements, and PL/I source.
%IF statement
The %IF statement controls the flow of the scan according to the bit value of a
preprocessor expression.
% IF preprocessor-expression % THEN
label:
preprocessor-unit1
% ELSE preprocessor-unit2
preprocessor-expression
Is evaluated and converted to a bit string (if the conversion cannot be made, it
is an error). The evaluation of the preprocessor-expression in a %IF statement is
not short-circuited.
preprocessor-unit
Is any single preprocessor statement (other than %DECLARE, %PROCEDURE,
%END, or %DO), a preprocessor DO-group, or a preprocessor SELECT-group.
Otherwise, the description is the same as that given under IF statement on
page 238.
If any bit in the string has the value '1'B, unit1 is executed and unit2, if present, is
ignored; if all bits are '0'B, unit1 is ignored and unit2, if present, is executed.
%IF statements can be nested in the same manner used for nesting IF statements,
as described under IF statement on page 238.
%INCLUDE statement
The external text specified by a %INCLUDE statement is included into the
preprocessor input at the point at which the %INCLUDE statement is executed.
Such text, once included, is called included text and can consist of preprocessor
statements, listing control statements, and PL/I source.
For the syntax for the %INCLUDE statement, see %INCLUDE directive on page
241.
Each dataset and member name pair identifies the external text to be incorporated
into the source program.
The scan continues with the first character in the included text. The included text
is scanned in the same manner as the preprocessor input. Hence, included text can
contribute to the preprocessor output being formed.
%INCLUDE statements can be nested. In other words, included text can contain
%INCLUDE statements.
A %GO TO statement in included text can transfer control only to a point within
the same include file. The target label in the %GOTO statement must not precede
the %GOTO.
If the preprocessor input and the included text contain no preprocessor statements
other than %INCLUDE, execution of the preprocessor can be omitted. (This
necessitates the use of the INCLUDE compile-time option.)
For example, assume that PAYRL is a member of the data set SYSLIB and contains
the following text, which is a structure declaration:
DECLARE 1 PAYROLL,
2 NAME,
3 LAST CHARACTER (30) VARYING,
3 FIRST CHARACTER (15) VARYING,
3 MIDDLE CHARACTER (3) VARYING,
2 CURR,
3 (REGLAR, OVERTIME) FIXED DECIMAL (8,2),
2 YTD LIKE CURR;
Execution of the first %INCLUDE statement incorporates the text in PAYRL into
the preprocessor input. When the preprocessor scan encounters the identifier
PAYROLL in this included text, it replaces it with the current value of the active
preprocessor variable PAYROLL, namely, CUM_PAY. Further scanning of the
included text results in no additional replacements. The preprocessor scan then
encounters the %DEACTIVATE statement and deactivates the preprocessor variable
PAYROLL. When the second %INCLUDE statement is executed, the text in PAYRL
once again is incorporated into the preprocessor input. This time, however,
scanning of the included text results in no replacements whatsoever.
%INSCAN statement
Like the %INCLUDE statement, the %INSCAN statement also includes a file
except in the %INSCAN statement, the file to be included is specified by a
preprocessor variable.
%INSCAN filename ;
filename
Is a preprocessor expression that specifies the name of the file to be included.
Example
%dcl inname char;
%inname = 'oldform';
%inscan inname; /* includes the file "oldform" */
%ITERATE statement
The %ITERATE statement transfers control to the %END statement that delimits its
containing iterative DO-group. The current iteration completes and the next
iteration, if needed, is started.
% ITERATE ;
label
label:
label-constant
Must be the label of a containing DO-group. If label-constant is omitted, control
transfers to the END statement of the most recent iterative do-group containing
the ITERATE statement.
%LEAVE Statement
When contained in or specifying a simple DO-group, the %LEAVE statement
terminates the group. When contained in or specifying an iterative DO-group, the
%LEAVE statement terminates all iterations of the group, including the current
iteration.
The flow of control goes to the same point as it would normally go to if the
do-group had terminated by reaching its END statement.
% LEAVE ;
label
label:
label-constant
Must be a label of a containing DO-group. The DO-group that is left is the
DO-group that has the specified label. If label-constant is omitted, the DO-group
that is left is the group that contains the LEAVE statement.
%NOTE statement
The %NOTE statement generates a preprocessor diagnostic message of specified
text and severity.
% NOTE ( message ) ;
, code
label:
message
A character expression whose value is the required diagnostic message.
code
A fixed expression whose value indicates the severity of the message, as
follows:
Code Severity
0 I
4 W
8 E
12 S
16 U
Generated messages are filed together with other preprocessor messages. Whether
or not a particular message is subsequently printed depends upon its severity level
and the setting of the compiler FLAG option.
%null statement
The %null statement does nothing and does not modify sequential statement
execution.
% ;
Related information:
%PROCEDURE statement on page 816
The %PROCEDURE statement is used in conjunction with a %END statement to
delimit a preprocessor procedure.
Preprocessor RETURN statement on page 817
The preprocessor RETURN statement can be used only in a preprocessor procedure
and only when the procedure has the RETURNS attribute. This statement returns a
value as well as control back to the point from which the preprocessor procedure
was invoked.
%REPLACE statement
The %REPLACE statement allows for the immediate replacement of a name with a
string constant or a numeric constant. The name does not need to be a declared
variable to have a value assigned to it.
% REPLACE identifier BY
WITH
label:
string-constant ;
arithmetic-constant
identifier
Name to be replaced.
string-constant
The name, if undeclared, will be given the CHARACTER attribute.
arithmetic-constant
The name, if undeclared, will be given the FIXED attribute.
Under the FIXED(DEC) option, the value will be converted to FIXED DEC(5,0).
Under the FIXED(BIN) option, the value will be converted to FIXED BIN(31,0).
%SELECT statement
The %SELECT statement, and its corresponding %END statement, delimit a
preprocessor SELECT-group.
% SELECT ;
( exp1 )
label:
%END ;
%OTHERWISE unit
,
%XINCLUDE statement
The %XINCLUDE statement is the same as the %INCLUDE statement except that
the file is not included if it already has been.
%XINSCAN statement
The %XINSCAN statement is the same as the %INSCAN statement except that the
file is not included if it already has been.
%XINSCAN filename ;
Preprocessor examples
This topic provides a few preprocessor examples.
Example 1
The preprocessor statements activate A and B with the default RESCAN, assign the
character string 'B+C' to A, and assign the constant 2 to B.
The fourth line is input text. The current value of A, which is 'B+C', replaces A in
the preprocessor output. But this string contains the preprocessor variable B. Upon
rescanning B, the preprocessor finds that it has been activated. Hence, the value 2
replaces B in the preprocessor output. The preprocessor variable B has a default
precision of (5,0) and, therefore, actually contains 2 preceded by four zeros. When
this value replaces B in the string 'B+C' it is converted to a character string and
becomes 2 preceded by seven blanks.
Further rescanning shows that 2 cannot be replaced; scanning resumes with +C,
which, again, cannot be replaced.
If, in the preceding example, the preprocessor variable A was activated by the
statement %ACTIVATE A NORESCAN;, the preprocessor output would be as follows:
X = B+C;
Example 2
Assume that the preprocessor input contains the following statements:
%DECLARE I FIXED, T CHARACTER;
%DEACTIVATE I;
%I = 15;
%T = A(I);
S = I*T*3;
%I = I+5;
%ACTIVATE I;
%DEACTIVATE T;
R = I*T*2
The preprocessor output would be as follows. Replacement blanks are not shown.
S = I*A(I)*3;
R = 20*T*2;
Example 3
This example illustrates how preprocessor facilities can be used to speed up the
execution of a DO-group.
The following statements would accomplish the same thing, but without the
requirements of incrementing and testing during execution of the compiled
program:
%DECLARE I FIXED;
%DO I = 1 TO 10;
Z(I)=X(I)+Y(I);
%END;
%DEACTIVATE I;
The third line is input text and is scanned for replacement activity. The first time
that this line is scanned, I has the value 1 and has been activated. Therefore, the
following string is inserted into the preprocessor output:
Z( 1)=X( 1)+Y( 1);
For each increment of I, up to and including 10, the input text is scanned and each
occurrence of I is replaced by its current value. As a result, the following string is
inserted into the preprocessor output:
When the value of I reaches 11, control falls through to the %DEACTIVATE
statement.
Example 4
When the scan encounters the fourth line, A is active and is thus eligible for
replacement. Because VALUE is also active, the reference to it in the fourth line
invokes the preprocessor function procedure of that name.
However, before the arguments A and 3 are passed to VALUE, A is replaced by its
value Z (assigned to A in a previous assignment statement), and 3 is converted to
fixed-point to conform to the attribute of its corresponding parameter. VALUE then
performs a concatenation of these arguments and the parentheses and returns the
concatenated value, that is, the string Z (3), to the point of invocation. The
returned value replaces the function reference and the result is inserted into the
preprocessor output. Thus, the preprocessor output generated is as follows:
DECLARE (Z(10),Q) FIXED;
Q = 6+Z( 3);
Example 5
THEN STRING=STRING{,;
ELSE STRING=STRING{);
/* LIST SEPARATOR */
END;
IF I<HIGH THEN /* ENTRY NAME SEPARATOR*/
STRING=STRING{,;
ELSE STRING=STRING{);
/* END OF LIST /*
END;
RETURN (STRING)
% END;
Example 6
IF PARMSET(USING) THEN
USING=I;
IF PARMSET(AND) THEN
AND=J;
IF USING = AND THEN
GO TO SERR;
LABL=SL{COUNTER;
DO1=LABL{: DO {USING{=LBOUND({TABLE{,1)
TO HBOUND({TABLE{,1);;
DO2=DO {AND{=LBOUND({TABLE{,2)
TO HBOUND ({TABLE{,2);;
RETURN(DO1{DO2{SELECT({TABLE
{({USING{,{AND{));
WHEN({FOR{) LEAVE {LABL{;
OTHER;
END {LABL{;
IF {AND{ > H BOUND({TABLE{,2) THEN
{USING{,{AND{. = -22222;);
%END SEARCH;
The PARMSET built-in function is used to determine which parameters are set
when the procedure is invoked. If USING is not set, the default array subscript
variable I is used. If AND is not set, J is used. If TABLE or FOR is not set, or if the
invocation results in the same variable being used for both subscripts, a
preprocessor diagnostic message is issued and a comment is returned in the
preprocessor output.
The COUNTER built-in function is used to generate unique labels for the
preprocessor output returned by the procedure.
SEARCH(LIST.NAME) FOR(J.DOE);
SEARCH(LIST.NAME,J.DOE);
SEARCH(,J.DOE) TABLE(LIST.NAME);
The label SL00001 is returned only for the first invocation. A new unique label is
returned for each subsequent invocation.
Table 82 summarizes the implementation limits for the PL/I language elements.
Table 82. Language element limits
Language element Description Limit
Arrays Maximum number of dimensions for an 15
array
Minimum lower boundNote 1 Under CMPAT(V3),
-263; otherwise,
-2147483648
Maximum upper boundNote 1 Under CMPAT(V3),
+263 - 1; otherwise,
+2147483647
Note 1: These bounds must be used with caution. For instance, if A has the maximum upper
bound and JX has the attributes SIGNED FIXED BIN(31), the loop DO JX = LBOUND(A) TO
HBOUND(A) will "wrap" after it hits the last element in the array. It would not "wrap" if
UPTHRU were used instead of TO.
Structures Maximum number of levels in a structure 15
Maximum level-number in a structure 255
Arithmetic precisions Maximum precision for FIXED DECIMAL 31Note 2
Maximum precision for FIXED BINARY 63Note 3
Maximum precision for FLOAT DECIMAL 33Note 4
Maximum precision for FLOAT BINARY 109Note 5
Maximum scale factor for FIXED data 127
Minimum scale factor for FIXED data -128
Note 2: This is true only if you specify the compile-time option LIMITS(FIXEDDEC(31)); the
default is 15.
Note 3: This is true only if you specify the compile-time option LIMITS(FIXEDBIN(63)); the
default is 31.
Note 4: On Intel, the maximum FLOAT DECIMAL precision is 18. Under FLOAT(DFP), the
maximum FLOAT DECIMAL precision is 34.
Note 5: On Intel, the maximum FLOAT BINARY precision is 64.
String and AREA Maximum length of CHARACTER 32767
variables or constants
Maximum length of BIT 32767
Maximum length of GRAPHIC 16383
Maximum length of WIDECHAR 32767
Maximum size of AREA 2147483647
Note 6: These are the default limits. Under the STRING suboption of the LIMITS compiler
option, the maximum length of the string types can be up to 128M.
Table 83 summarizes the implementation limits for the macro facility language
elements.
Table 83. Macro facility limits
Language element Description Limit
Arrays Maximum number of dimensions 15
Minimum lower bound -32768
Maximum upper bound +32767
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to:
IBM Corporation
J74/G4
555 Bailey Avenue
San Jose, CA 95141-1099
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this publication to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
Intel is a registered trademark of Intel Corporation in the United States and other
countries.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Oracle and/or its affiliates.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Other company, product or service names may be the trademarks or service marks
of others.
If you are viewing this information in softcopy, the photographs and color
illustrations may not appear.
Related publications
DB2 for z/OS
Administration Guide, SC19-2968
Application Programming and SQL Guide, SC19-2969
Command Reference, SC19-2972
Messages, GC19-2979
Codes, GC19-2971
SQL Reference, SC19-2983
See also the Information Center: publib.boulder.ibm.com/infocenter/dzichelp/
v2r2/topic/com.ibm.db2z10.doc/src/alltoc/db2z_10_prodhome.htm
LOBs with DB2 for z/OS: Stronger and Faster, SG24-7270
DFSORT
Application Programming Guide, SC33-4035
Installation and Customization, SC33-4034
IMS/ESA
Application Programming: Database Manager, SC26-8015
Application Programming: Database Manager Summary, SC26-8037
Application Programming: Design Guide, SC26-8016
Application Programming: Transaction Manager, SC26-8017
Application Programming: Transaction Manager Summary, SC26-8038
Application Programming: EXEC DL/I Commands for CICS and IMS, SC26-8018
z/Architecture
Principles of Operation, SA22-7832
z/OS MVS
JCL Reference, SA22-7597
JCL User's Guide, SA22-7598
System Commands, SA22-7627
z/OS TSO/E
Command Reference, SA22-7782
User's Guide, SA22-7794
Glossary 881
character string constant <= (less than or equal to)
A sequence of characters enclosed in = or <> (not equal to)
single quotes; for example, 'Shakespeare''s
> (not greater than)
'Hamlet:''.
< (not less than)
character set
A defined collection of characters. See compile time
also ASCII and EBCDIC. In general, the time during which a
source program is translated into an
character string picture data object module. In PL/I, it is the time
Picture data that has only a character during which a source program can be
value. This type of picture data must have altered, if desired, and then translated
at least one A or X picture specification into an object program.
character. Contrast with numeric picture
data. compiler options
Keywords that are specified to control
closing (of a file) certain aspects of a compilation, such as:
The dissociation of a file from a data set the nature of the object module generated,
or device. the types of printed output produced, and
coded arithmetic data so forth.
Data items that represent numeric values complex data
and are characterized by their base Arithmetic data, each item of which
(decimal or binary), scale (fixed-point or consists of a real part and an imaginary
floating-point), and precision (the number part.
of digits each can have). This data is
stored in a form that is acceptable, composite operator
without conversion, for arithmetic An operator that consists of more than
calculations. one special character, such as <=, **, and
/*.
combined nesting depth
The deepest level of nesting, determined compound statement
by counting the levels of A statement that contains other
PROCEDURE/BEGIN/ON, DO, SELECT, statements. In PL/I, IF, ON, OTHERWISE,
and IF...THEN...ELSE nestings in the and WHEN are the only compound
program. statements. See statement body.
comment concatenation
A string of zero or more characters used The operation that joins two strings in the
for documentation that are delimited by order specified, forming one string whose
/* and */. length is equal to the sum of the lengths
of the two original strings. It is specified
commercial character by the operator ||.
v CR (credit) picture specification
condition
character
An exceptional situation, either an error
v DB (debit) picture specification (such as an overflow), or an expected
character situation (such as the end of an input
comparison operator file). When a condition is raised
An operator that can be used in an (detected), the action established for it is
arithmetic, string locator, or logical processed. See also established action and
relation to indicate the comparison to be implicit action.
done between the terms in the relation. condition name
The comparison operators are: Name of a PL/I-defined or
= (equal to) programmer-defined condition.
> (greater than) condition prefix
< (less than) A parenthesized list of one or more
>= (greater than or equal to) condition names prefixed to a statement.
Glossary 883
data attribute decimal digit picture character
A keyword that specifies the type of data The picture specification character 9.
that the data item represents, such as
decimal fixed-point constant
FIXED BINARY.
A constant consisting of one or more
data-directed transmission decimal digits with an optional decimal
The type of stream-oriented transmission point.
in which data is transmitted. It resembles
decimal fixed-point value
an assignment statement and is of the
A rational number consisting of a
form name = constant.
sequence of decimal digits with an
data item assumed position of the decimal point.
A single named unit of data. Contrast with binary fixed-point value.
data list decimal floating-point constant
In stream-oriented transmission, a A value made up of a significand that
parenthesized list of the data items used consists of a decimal fixed-point constant,
in GET and PUT statements. Contrast and an exponent that consists of the letter
with format list. E followed by an optionally signed
integer constant not exceeding three
data set
digits.
A collection of data external to the
program that can be accessed by reference decimal floating-point value
to a single file name. A device that can be An approximation of a real number, in
referenced. the form of a significand, which can be
considered as a decimal fraction, and an
data specification
exponent, which can be considered as an
The portion of a stream-oriented
integer exponent to the base 10. Contrast
transmission statement that specifies the
with binary floating-point value.
mode of transmission (DATA, LIST, or
EDIT) and includes the data list(s) and, decimal picture data
for edit-directed mode, the format list(s). See numeric picture data.
data stream declaration
Data being transferred from or to a data The establishment of an identifier as a
set by stream-oriented transmission, as a name and the specification of a set of
continuous stream of data elements in attributes (partial or complete) for it. A
character form. source of attributes of a particular name.
data transmission default
The transfer of data from a data set to the Describes a value, attribute, or option that
program or vice versa. is assumed when none has been specified.
data type defined variable
A set of data attributes. A variable that is associated with some or
all of the storage of the designated base
DBCS In the character set, each character is
variable.
represented by two consecutive bytes.
delimit
deactivated
To enclose one or more items or
The state in which an identifier is said to
statements with preceding and following
be when its value cannot replace a
characters or keywords.
preprocessor identifier in source program
text. Contrast with active. delimiter
All comments and the following
debugging
characters: percent, parentheses, comma,
Process of removing bugs from a
period, semicolon, colon, assignment
program.
symbol, blank, pointer, asterisk, and
decimal single quote. They define the limits of
The number system whose numerals are 0 identifiers, constants, picture
through 9. specifications, iSUBs, and keywords.
Glossary 885
the environment of the activation that is assumed position to the right (if the
associated with the entry constant. constant is positive) or to the left (if
the constant is negative).
environment (of an activation)
Information associated with and used in expression
the invoked block regarding data declared A notation, within a program, that
in containing blocks. represents a value, an array of values, or
a structured set of values. A constant or a
environment (of a label constant)
reference appearing alone, or a
Identity of the particular activation of a
combination of constants and/or
block to which a reference to a
references with operators.
statement-label constant applies. This
information is determined at the time a extended alphabet
statement-label constant is passed as an The uppercase and lowercase alphabetic
argument or is assigned to a characters A through Z, $, @ and #, or
statement-label variable, and it is passed those specified in the NAMES compiler
or assigned along with the constant. option.
established action extent The range indicated by the bounds of an
The action taken when a condition is array dimension, by the length of a string,
raised. See also implicit action and or by the size of an area. The size of the
ON-statement action. target area if this area were to be assigned
to a target area.
epilogue
Those processes that occur automatically external name
at the termination of a block or task. A name (with the EXTERNAL attribute)
whose scope is not necessarily confined
evaluation
only to one block and its contained
The reduction of an expression to a single
blocks.
value, an array of values, or a structured
set of values. external procedure
A procedure that is not contained in any
event An activity in a program whose status
other procedure. A level-2 procedure
and completion can be determined from
contained in a package that is also
an associated event variable.
exported.
event variable
external symbol
A variable with the EVENT attribute that
Name that can be referred to in a control
can be associated with an event. Its value
section other than the one in which it is
indicates whether the action has been
defined.
completed and the status of the
completion. External Symbol Dictionary (ESD)
Table containing all the external symbols
explicit declaration
that appear in the object module.
The appearance of an identifier (a name)
in a DECLARE statement, as a label extralingual character
prefix, or in a parameter list. Contrast Characters (such as $, @, and #) that are
with implicit declaration. not classified as alphanumeric or special.
This group includes characters that are
exponent characters
determined with the NAMES compiler
The following picture specification
option.
characters:
1. K and E, which are used in F
floating-point picture specifications to
indicate the beginning of the exponent factoring
field. The application of one or more attributes
to a parenthesized list of names in a
2. F, the scaling factor character, specified
DECLARE statement, eliminating the
with an integer constant that indicates
repetition of identical attributes for
the number of decimal positions the
multiple names.
decimal point is to be moved from its
Glossary 887
keys can be considered to be unique implicit declaration
members of the classes 'ABCD', 'ABCE', A name not explicitly declared in a
'ABDF', respectively. DECLARE statement or contextually
declared.
generic name
The name of a family of entry names. A implicit opening
reference to the generic name is replaced The opening of a file as the result of an
by the entry name whose parameter input or output statement other than the
descriptors match the attributes of the OPEN statement.
arguments in the argument list at the
infix operator
point of invocation.
An operator that appears between two
group A collection of statements contained operands.
within larger program units. A group is
inherited dimensions
either a do-group or a select-group and it
For a structure, union, or element, those
can be used wherever a single statement
dimensions that are derived from the
can appear, except as an on-unit.
containing structures. If the name is an
element that is not an array, the
H
dimensions consist entirely of its inherited
hex See hexadecimal digit. dimensions. If the name is an element
that is an array, its dimensions consist of
hexadecimal
its inherited dimensions plus its explicitly
Pertaining to a numbering system with a
declared dimensions. A structure with one
base of sixteen; valid numbers use the
or more inherited dimensions is called a
digits 0 through 9 and the characters A
nonconnected aggregate. Contrast with
through F, where A represents 10 and F
connected aggregate.
represents 15.
input/output
hexadecimal digit
The transfer of data between auxiliary
One of the digits 0 through 9 and A
medium and main storage.
through F. A through F represent the
decimal values 10 through 15, insertion point character
respectively. A picture specification character that is,
on assignment of the associated data to a
I character string, inserted in the indicated
position. When used in a P-format item
identifier
for input, the insertion character is used
A string of characters, not contained in a
for checking purposes.
comment or constant, and preceded and
followed by a delimiter. The first integer
character of the identifier must be one of An optionally signed sequence of digits or
the 26 alphabetic characters and a sequence of bits without a decimal or
extralingual characters, if any. The other binary point. An optionally signed whole
characters, if any, can additionally include number, commonly described as FIXED
extended alphabetic, digit, or the break BINARY (p,0) or FIXED DECIMAL (p,0).
character.
integral boundary
IEEE Institute of Electrical and Electronics A byte multiple address of any 8-bit unit
Engineers. on which data can be aligned. It usually
is a halfword, fullword, or doubleword
implicit
(2-, 4-, or 8-byte multiple respectively)
The action taken in the absence of an
boundary.
explicit specification.
interleaved array
implicit action
An array that refers to nonconnected
The action taken when an enabled
storage.
condition is raised and no ON-unit is
currently established for the condition.
Contrast with ON-statement action.
Glossary 889
MACLIB that can be used to store other main procedure
data sets called members. An external procedure whose
PROCEDURE statement has the
list-directed
OPTIONS (MAIN) attribute. This
The type of stream-oriented transmission
procedure is invoked automatically as the
in which data in the stream appears as
first step in the execution of a program.
constants separated by blanks or commas
and for which formatting is provided major structure
automatically. A structure whose name is declared with
level number 1.
locator
A control block that holds the address of member
a variable or its descriptor. A structure, union, or element name in a
structure or union. Data sets in a library.
locator/descriptor
A locator followed by a descriptor. The minor structure
locator holds the address of the variable, A structure that is contained within
not the address of the descriptor. another structure or union. The name of a
minor structure is declared with a level
locator qualification
number greater than one and greater than
In a reference to a based variable, either a
its parent structure or union.
locator variable or function reference
connected by an arrow to the left of a mode (of arithmetic data)
based variable to specify the generation of An attribute of arithmetic data. It is either
the based variable to which the reference real or complex.
refers. It might be an implicit reference.
multiple declaration
locator value Two or more declarations of the same
A value that identifies or can be used to identifier internal to the same block
identify the storage address. without different qualifications. Two or
more external declarations of the same
locator variable
identifier.
A variable whose value identifies the
location in main storage of a variable or a multiprocessing
buffer. It has the POINTER or OFFSET The use of a computing system with two
attribute. or more processing units to execute two
or more programs simultaneously.
locked record
A record in an EXCLUSIVE DIRECT multiprogramming
UPDATE file that has been made The use of a computing system to execute
available to one task only and cannot be more than one program concurrently,
accessed by other tasks until the task using a single processing unit.
using it relinquishes it.
N
logical level (of a structure or union member)
The depth indicated by a level number name Any identifier that the user gives to a
when all level numbers are in direct variable or to a constant. An identifier
sequence (when the increment between appearing in a context where it is not a
successive level numbers is one). keyword. Sometimes called a user-defined
name.
logical operators
The bit-string operators not and nesting
exclusive-or (), and (&), and or (|). The occurrence of:
loop A sequence of instructions that is v A block within another block
executed iteratively. v A group within another group
lower bound v An IF statement in a THEN clause or in
The lower limit of an array dimension. an ELSE clause
v A function reference as an argument of
M a function reference
Glossary 891
parameter descriptor pointer variable
The set of attributes specified for a A locator variable with the POINTER
parameter in an ENTRY attribute attribute that contains a pointer value.
specification.
precision
parameter descriptor list The number of digits or bits contained in
The list of all parameter descriptors in an a fixed-point data item, or the minimum
ENTRY attribute specification. number of significant digits (excluding
the exponent) maintained for a
parameter list
floating-point data item.
A parenthesized list of one or more
parameters, separated by commas and prefix A label or a parenthesized list of one or
following either the keyword more condition names included at the
PROCEDURE in a procedure statement or beginning of a statement.
the keyword ENTRY in an ENTRY
prefix operator
statement. The list corresponds to a list of
An operator that precedes an operand
arguments passed at invocation.
and applies only to that operand. The
partially qualified name prefix operators are plus (+), minus (-),
A qualified name that is incomplete. It and not ().
includes one or more, but not all, of the
preprocessor
names in the hierarchical sequence above
A program that examines the source
the structure or union member to which
program before the compilation takes
the name refers, as well as the name of
place.
the member itself.
preprocessor statement
picture data
A special statement appearing in the
Numeric data, character data, or a mix of
source program that specifies the actions
both types, represented in character form.
to be performed by the preprocessor. It is
picture specification executed as it is encountered by the
A data item that is described using the preprocessor.
picture characters in a declaration with
primary entry point
the PICTURE attribute or in a P-format
The entry point identified by any of the
item.
names in the label list of the
picture specification character PROCEDURE statement.
Any of the characters that can be used in
priority
a picture specification.
A value associated with a task, that
PL/I character set specifies the precedence of the task
A set of characters that has been defined relative to other tasks.
to represent program elements in PL/I.
problem data
PL/I prompter Coded arithmetic, bit, character, graphic,
Command processor program for the PLI and picture data.
command that checks the operands and
problem-state program
allocates the data sets required by the
A program that operates in the problem
compiler.
state of the operating system. It does not
point of invocation contain input/output instructions or other
The point in the invoking block at which privileged instructions.
the reference to the invoked procedure
procedure
appears.
A collection of statements, delimited by
pointer PROCEDURE and END statements. A
A type of variable that identifies a procedure is a program or a part of a
location in storage. program, delimits the scope of names,
and is activated by a reference to the
pointer value
A value that identifies the pointer type.
Glossary 893
repetitive specification self-defining data
An element of a data list that specifies An aggregate that contains data items
controlled iteration to transmit one or whose bounds, lengths, and sizes are
more data items, generally used in determined at program execution time
conjunction with arrays. and are stored in a member of the
aggregate.
restricted expression
An expression that can be evaluated by separator
the compiler during compilation, resulting See delimiter.
in a constant. Operands of such an
shift Change of data in storage to the left or to
expression are constants, named
the right of original position.
constants, and restricted expressions.
shift-in
returned value
Symbol used to signal the compiler at the
The value returned by a function
end of a double-byte string.
procedure.
shift-out
RETURNS descriptor
Symbol used to signal the compiler at the
A descriptor used in a RETURNS
beginning of a double-byte string.
attribute, and in the RETURNS option of
the PROCEDURE and ENTRY statements. sign and currency symbol characters
The picture specification characters. S, +,
S -, and $ (or other national currency
symbols enclosed in < and >).
scalar variable
A variable that is not a structure, union, simple parameter
or array. A parameter for which no storage class
attribute is specified. It can represent an
scale A system of mathematical notation whose
argument of any storage class, but only
representation of an arithmetic value is
the current generation of a controlled
either fixed-point or floating-point.
argument.
scale factor
simple statement
A specification of the number of fractional
A statement other than IF, ON, WHEN,
digits in a fixed-point number.
and OTHERWISE.
scaling factor
source Data item to be converted for problem
See scale factor.
data.
scope (of a condition prefix)
source key
The portion of a program throughout
A key referred to in a record-oriented
which a particular condition prefix
transmission statement that identifies a
applies.
particular record within a direct-access
scope (of a declaration or name) data set.
The portion of a program throughout
source program
which a particular name is known.
A program that serves as input to the
secondary entry point source program processors and the
An entry point identified by any of the compiler.
names in the label list of an entry
source variable
statement.
A variable whose value participates in
select-group some other operation, but is not modified
A sequence of statements delimited by by the operation. Contrast with target
SELECT and END statements. variable.
selection clause spill file
A WHEN or OTHERWISE clause of a Data set named SYSUT1 that is used as a
select-group. temporary workfile.
Glossary 895
target reference upper bound
A reference that designates a receiving The upper limit of an array dimension.
variable (or a portion of a receiving
variable). V
target variable value reference
A variable to which a value is assigned. A reference used to obtain the value of an
item of data.
task The execution of one or more procedures
by a single flow of control. variable
A named entity used to refer to data and
task name
to which values can be assigned. Its
An identifier used to refer to a task
attributes remain constant, but it can refer
variable.
to different values at different times.
task variable
variable reference
A variable with the TASK attribute whose
A reference that designates all or part of a
value gives the relative priority of a task.
variable.
termination (of a block)
virtual origin (VO)
Cessation of execution of a block, and the
The location where the element of the
return of control to the activating block
array whose subscripts are all zero are
by means of a RETURN or END
held. If such an element does not appear
statement, or the transfer of control to the
in the array, the virtual origin is where it
activating block or to some other active
would be held.
block by means of a GO TO statement.
termination (of a task) Z
Cessation of the flow of control for a task.
zero-suppression characters
truncation The picture specification characters Z and
The removal of one or more digits, *, which are used to suppress zeros in the
characters, graphics, or bits from one end corresponding digit positions and replace
of an item of data when a string length or them with blanks or asterisks respectively.
precision of a target variable has been
exceeded.
type The set of data attributes and storage
attributes that apply to a generation, a
value, or an item of data.
U
undefined
Indicates something that a user must not
do. Use of a undefined feature is likely to
produce different results on different
implementations of a PL/I product. In
that case, the application program is in
error.
union A collection of data elements that overlay
each other, occupying the same storage.
The members can be structures, unions,
elementary variables, or arrays. They
need not have identical attributes.
union of arrays
A union that has the DIMENSION
attribute.
Index 899
BINARY (BIN) attribute 24 buffer-management built-in functions built-in functions (continued)
BINARY (BIN) built-in function 456 (continued) BOOL 460
binary digit 3 MEMCU12 600 BYTE 461
binary fixed-point constant 27 MEMCU14 601 categories of 411
binary fixed-point data MEMCU21 602 CDS 462
conversion 83 MEMCU24 603 CEIL 463
description 26 MEMCU41 604 CENTERLEFT (CENTER) 464
binary floating-point constant 29 MEMCU42 605 CENTERRIGHT 466
binary floating-point data MEMINDEX 606 CHAR 78
conversion 84 MEMSEARCH 607 CHARACTER (CHAR) 468
description 28 MEMSEARCHR 608 CHARGRAPHIC (CHARG) 469
BINARYVALUE (BINVALUE) built-in MEMVERIFY 609 CHARVAL 471
function 457 MEMVERIFYR 610 CHECKSTG 472
BINARYVALUE built-in function PICSPEC 652 CHECKSUM 473
for ordinals 154 PLITRAN11 679 COLLATE 474
using with pointer expressions 57 PLITRAN12 680 COMPARE 475
BIND type function 801 PLITRAN21 681 COMPLEX (CPLX) 476
bit PLITRAN22 682 condition-handling, summary 415
constant 36 WHITESPACECOLLAPSE 788 CONJG 477
conversion WHITESPACEREPLACE 789 controlled variables 260
description 80 XMLCHAR 792 converting data 78
rules 88 XMLCLEAN 794 COPY 478
data 36 BUFFERED (BUF) attribute 304 COS 479
operators built-in functions COSD 480
description 7 ABS 430 COSH 481
using in bit operations 65 accuracy of mathematical functions COUNT 482
BIT attribute 30 in 411 CS 483
BIT built-in function 458 ACOS 431 CURRENTSIZE (CSTG) 485
bit data ADD 432 CURRENTSTORAGE 486
repetition factor 36 ADDR 433 DATAFIELD 487
bit format item 344 ADDRDATA 434 DATE 488
bit operations aggregate arguments 410 date/time, summary 416
examples 66 ALL 435 DATETIME 489
using 65 ALLCOMPARE 436 DAYS 490
bit strings, transmission of ALLOC31 437 DAYSTODATE 491
unaligned 311 ALLOCATE (ALLOC) 438 DAYSTOSECS 492
BITLOCATION (BITLOC) built-in ALLOCATION (ALLOCN) 439 DECIMAL
function 459 ALLOCSIZE 440 converting data 78
blanks ANY 441 DECIMAL (DEC) 493
description 7 area variables 276 declaring 409
using as a delimiter 6 arithmetic, summary 412 definition 114
blocks array-handling, summary 412 DIMENSION (DIM) 494
activation 93 ASIN 442 DIVIDE 495
begin 118 ATAN 443 EDIT 496
description 93 ATAND 444 EMPTY 497
packages 94 ATANH 445 ENDFILE 498
procedures 97 AUTOMATIC (AUTO) 446 ENTRYADDR 499
termination 94 AVAILABLEAREA 447 EPSILON 501
types 93 BASE64DECODE16 449 ERF 502
BOOL built-in function 460 BASE64DECODE8 448 ERFC 503
Boolean operators 65 BASE64ENCODE16 451 EXP 504
bounds 184 BASE64ENCODE8 450 EXPONENT 505
controlled parameter 101 based variables 267 FILEDDINT 506
simple parameter 101 BETWEEN 452 FILEDDTEST 507
break (_) character 16 BETWEENEXCLUSIVE 453 FILEDDWORD 508
BUF (BUFFERED) attribute 304 BETWEENLEFTEXCLUSIVE 454 FILEID 509
buffer-management built-in functions BETWEENRIGHTEXCLUSIVE 455 FILEOPEN 510
BASE64DECODE16 449 BINARY FILEREAD 511
BASE64DECODE8 448 converting data 78 FILESEEK 512
BASE64ENCODE16 451 BINARY (BIN) 456 FILETELL 513
BASE64ENCODE8 450 BINARYVALUE FILEWRITE 514
CHECKSUM 473 using with ordinals 154 FIXED 515
COMPARE 475 using with pointer expressions 57 converting data 78
HEXDECODE 531 BINARYVALUE (BINVALUE) 457 FIXEDBIN 516
HEXDECODE8 532 BIT 458 FIXEDDEC 517
HEXIMAGE 533 converting data 78 FLOAT 518
MEMCONVERT 599 BITLOCATION (BITLOC) 459 converting data 78
Index 901
built-in functions (continued) built-in functions, miscellaneous canceling
SOURCEFILE 728 summary 422 thread 406
SOURCELINE 729 built-in names case sensitivity 5
SQRT 730 using with built-in functions 114 CAST type function 802
SQRTF 731 using with subroutines 112 CDS built-in function 462
STACKADDR 732 built-in pseudovariables, summary 424 CEIL built-in function 463
STORAGE (STG) 733 built-in subroutines CELL, synonym for 190
storage control, summary 424 declaring 409 CENTERLEFT (CENTER) built-in
STRING 734 definition 112 function 464
string-handling, summary 426 invoking 410 CENTERRIGHT built-in function 466
SUBSTR 737 LOCNEWSPACE 584 CHARACTER (CHAR) attribute
SUBTRACT 739 LOCNEWVALUE 585 description 30
SUCC 740 PLIASCII 654 CHARACTER (CHAR) built-in
SUM 741 PLIATTN 655 function 468
SYSNULL 742 PLICANC 656 character sets
SYSTEM 743 PLICKPT 657 discussion 1
TALLY 744 PLIDELETE 658 double-byte
TAN 745 PLIDUMP 659 identifier 11
TAND 746 PLIEBCDIC 660 statement element 12
TANH 747 PLIFILL 661 single-byte
THREADID 748 PLIFREE 662 delimiters and operators 6
TIME 749 PLIMOVE 663 identifier in DBCS form 12
TIMESTAMP 750 PLIOVER 664 identifiers 5
TINY 751 PLIREST 665 statement elements for 5
TRANSLATE 752 PLIRETC 666 character string constant 35
TRIM 753 PLISAXA 668 characters
TRUNC 754 PLISAXB 669 alphabetic 1
TYPE 755 PLISAXC 670 alphanumeric 2
ULENGTH 757 PLISAXD 671 character data
ULENGTH16 759 PLISRTA 672 conversion 80, 86
ULENGTH8 758 PLISRTB 673 description 34
UNALLOCATED 760 PLISRTC 674 picture specifiers 356
UNSIGNED 761 PLISRTD 675 constant 34
converting data 78 summary 427 extralingual 2
UNSPEC 762 BUILTIN attribute 409 format items 343
UPOS 765 declaring names for built-in insertion 360
UPPERCASE 766 functions 112 picture specification 33
USUBSTR 767 BX (bit hex) bit string constant 37 sets
USUPPLEMENTARY 768 BY DIMACROSS option of assignment double-byte 11
UTCDATETIME 769 statement single-byte 1
UTCSECS 770 description 214 special 3
UTF8 771 when specified in structure using in comparison operations 67
UTF8STG 772 assignment 218 zero suppression 359
UTF8TOCHAR 773 BY NAME option of assignment CHARGRAPHIC (CHARG) built-in
UTF8TOWCHAR 774 statement function 469
UVALID 776 description 214 CHARGRAPHIC option 140
UWIDTH 778 when not specified in structure CHARVAL built-in function 471
VALID 779 assignment 217 CHECKSTG built-in function 472
VALIDDATE 780 when specified in structure CHECKSUM built-in function 473
VARGLIST 781 assignment 218 CLOSE statement 309
VARGSIZE 782 BY option of DO statement 225 COBOL option 140
VERIFY 783 BYADDR attribute 139 coded arithmetic data
VERIFYR 784 BYADDR option 139 attributes
WCHARVAL 785 BYTE built-in function 461 abbreviations 23
WEEKDAY 786 byte, definition 172 types 19, 21
WHIGH 787 BYVALUE attribute 139 BINARY and DECIMAL attributes 24
WHITESPACECOLLAPSE 788 BYVALUE option 139 binary fixed-point data 26
WHITESPACEREPLACE 789 binary floating-point 28
WIDECHAR conversion target 82
converting data 78
WIDECHAR (WCHAR) 790
C decimal fixed-point 27
decimal floating-point 29
C-format item 344
WLOW 791 FIXED and FLOAT attribute 24
CALL option on INITIAL attribute 291
XMLCHAR 792 PRECISION attribute 24
CALL statement 133
XMLCLEAN 794 REAL and COMPLEX attributes 24
calling conventions
Y4DATE 795 syntax 22
OPTLINK 142
Y4JULIAN 796 COLLATE built-in function 474
SYSTEM 142
Y4YEAR 797
Index 903
controlled (continued)
variables
D data elements
attributes 15
description 256 data constants
multiple generations 259 alignment 172 named 16
using the ALLOCATE area 271 punctuating 16
statement 257 arithmetic character 40 quotation marks 16
using the FREE statement 259 attributes 17 data item 15
CONTROLLED (CTL) attribute 256 binary fixed-point 26 discussion 15
controlling storage 253 binary floating-point 28 preprocessor 813
CONV (CONVERSION) condition 385 bit 36 data items
conversion bit constant 36 complex 24
data 77 character 34 definition 15
errors 90 character constant 34 expression 52
in arithmetic operations 57 A (ASCII) character constant 35 mode 24
in concatenation operations 69 E (EBCDIC) character constant 35 data sets
mode 80 computational 17 consecutive 298
of arithmetic precision 80 conversion indexed 298
of locator data 264 description 77 regional 299
operands 61 errors 90 relative 299
source to target rules 81 in arithmetic operations 57 storing 298
string lengths 79 source-to-target rules 81 transmission of data from 297
to other data attributes 80 using built-in functions 78 types 298
using built-in functions 78 decimal fixed-point 27 data specification options for stream i/o
CONVERSION (CONV) condition 385 decimal floating point 29 data transmitted 311
CONVERSION condition prefix 372 element 15 data-directed 329
conversion errors 90 elements 813 definition 321
conversion of graphic to character entry 119 discussion of 324
(CHARGRAPHIC) 469 format 48 data transmission
converting data format items 343 area variables 312
arithmetic precision 80 graphic 37 data aggregates 311
arithmetic-to-bit-string, example 89 item 15 data-directed 321
arithmetic-to-character string, label 47 data-list-items 328
example 90 LABEL attribute discussion of 311
computational data 78 valid OPTIONS options 47 edit-directed 321
conversion errors 90 labels, on language statements 47 graphic strings 311
description 77 locator 264 input 297
initiating with built-in functions 78 mixed 38 output 297
mode 80 numeric character 357 record-oriented 311
rules 78 offset 273 record-oriented statements
source-to-target rules 81 program-control DELETE 314
string lengths 79 description 17 discussion 312
COPY built-in function 478 types and attributes 47 LOCATE 314
COPY macro facility built-in sharing between threads 408 READ 312
function 826 specifications 324 REWRITE 313
COPY option 323 transmission 297 WRITE 313
COS built-in function 479 types 17 stream-oriented 321
COSD built-in function 480 widechar 39 stream-oriented statements
COSH built-in function 481 data alignment discussion 321
COUNT built-in function 482 discussion 172 GET 322
COUNTER macro facility built-in storage addresses 172 PUT 322
function 827 using ALIGNED and UNALIGNED type 3 do-group 325
credit (CR) picture character 366 attributes 173 TRANSMIT condition 397
cross sections of arrays of data conversion unaligned bit strings 311
structures/unions 199 arithmetic precision 80 varying length strings 311
cross sections, of arrays 188 errors 90 data transmission statements options
CS built-in function 483 in arithmetic operations 57 COPY 323
CTL (CONTROLLED) attribute 256 mode 80 discussion 323
currency symbol source-to-target rules 81 FILE 325
defining 362 string lengths 79 LINE 326
description 364 data declarations PAGE 326
CURRENTSIZE built-in function 485 array 184 SKIP 326
CURRENTSTORAGE (CSTG) built-in description 159 STRING 327
function 486 explicit 159 data types
implicit 162 computational 17
language-specified defaults for discussion 17
attributes 178 data-directed data specification
structures 188 discussion 329
unions 190
Index 905
ENTRY attribute expressions (continued) files (continued)
description 121 preprocessor 813 variable 302
valid OPTIONS options 135 restricted FILESEEK built-in function 512
entry constants 119 applying built-in functions 74 FILETELL built-in function 513
entry data description 74 FILEWRITE built-in function 514
attributes example 75 FINISH condition 389
classification 20, 21 scalar 52 FIRST type function 803
ENTRY 121 structure 52 FIXED attribute
GENERIC 130 syntax 51 description 24
LIMITED 129 types 52 FIXED built-in function 515
LIST 125 EXT (EXTERNAL) attribute 165 fixed-point
OPTIONAL 124 extent binary data 26
constants 119 BASED declarations 261 decimal data 27
description 119 parameter descriptor 123 format item
direct entry declaration 119 extent (of dimension) 184 description 348
generic 130 EXTERNAL (EXT) attribute specifying a picture scaling
generic entry declaration 130 description 165 factor 369
invocation of references 133 using 109 FIXEDBIN built-in function 516
variables 120 external procedure FIXEDDEC built-in function 517
entry points 97 description 98 FIXEDOVERFLOW (FOFL)
entry reference invocation 133 dynamic loading 107 condition 389
ENTRY statement 99 extralingual character 2 FIXEDOVERFLOW condition prefix 372
ENTRY statement, valid OPTIONS FLOAT attribute 24
options 136 FLOAT built-in function 518
entry-constant
using with a FETCH statement 109
F FLOATBIN built-in function 519
FLOATDEC built-in function 520
F picture character 369
ENTRYADDR built-in function 499 floating-point
F-format item 348
ENTRYADDR pseudovariable 500 binary data 28
factoring of attributes 161
ENV (ENVIRONMENT) attribute 304 data conversion 84
FETCH statement
ENVIRONMENT (ENV) attribute 304 decimal data 29
description 108
ENVIRONMENT option 404 format item 346
dynamically loading external
EPSILON built-in function 501 floating-point inquiry built-in functions
procedures 107
equal sign 6 EPSILON 501
restrictions 108
ERF built-in function 502 HUGE 535
FETCHABLE option 141
ERFC built-in function 503 ISFINITE 547
fields 357
ERROR condition ISINF 549
FILE attribute 299
abnormal termination of ISNAN 552
file data 21
procedures 105 ISNORMAL 553
FILE option
description 388 ISZERO 555
description 325
established action 374 MAXEXP 597
for record-oriented data
established condition 371 MINEXP 612
transmission 314
evaluation order for expressions and PLACES 653
for stream-oriented data
references 70 RADIX 696
transmission 312
evaluation order of expressions 53 summary 418
FILE specification in OPEN
exclusive-or operator 65 TINY 751
statement 306
EXE (file extension) 91 floating-point manipulation built-in
FILEDDINT built-in function 506
EXIT statement 105 functions
FILEDDTEST built-in function 507
EXP built-in function 504 EXPONENT 505
FILEDDWORD built-in function 508
explicit declaration 159 PRED 691
FILEID built-in function 509
explicitly locator-qualified reference 265 SCALE 713
FILEOPEN built-in function 510
EXPONENT built-in function 505 SUCC 740
FILEREAD built-in function 511
exponent specifiers 368 summary 419
files
exponentiation, special cases 65 FLOOR built-in function 521
additive attribute 300
EXPORTS option 95 FOFL (FIXEDOVERFLOW)
alternative attributes 299
expressions condition 389
attributes 20
array 72 FORCE attribute 171
constant 299
assigning values 219 FORMAT attribute
declaration 299
description 51 classification by variable type 21
definition of 299
element 52 description 48
description attributes 299
evaluation order 53 format data 48
FILE attribute 299
intermediate results of format items
implicit opening 307
expressions 63 A 343
opening and closing 305
of targets 54 B 344
PRINT 341
operational C 344
sharing between threads 408
classes 55 COLUMN 345
specifying a reference 302
definition 51 description 334
SYSIN 310
discussion 55 E 346
SYSPRINT 310
Index 907
integer manipulation built-in functions JSON built-in functions (continued) language-specified defaults
IAND 536 JSONPUTARRAYEND 567 defining 178
ICLZ 537 JSONPUTARRAYSTART 568 discussion of 178
IEOR 538 JSONPUTCOLON 569 restoring 184
INOT 545 JSONPUTCOMMA 570 LAST type function 804
IOR 546 JSONPUTMEMBER 571 LBOUND built-in function 578
ISIGNED 548 JSONPUTOBJECTEND 573 LBOUND macro facility built-in
ISLL 550 JSONPUTOBJECTSTART 574 function 831
ISRL 554 JSONPUTVALUE 575 LBOUNDACROSS built-in function 579
IUNSIGNED 556 JSONVALID 576 LEAVE statement 242
LOWER2 594 summary 420 LEFT built-in function 580
RAISE2 697 JSONGETARRAYEND built-in length
summary 420 function 557 controlled parameter 101
integral boundary 172 JSONGETARRAYSTART built-in simple parameter 101
interlanguage communication function 558 LENGTH built-in function 581
LINKAGE option 142 JSONGETCOLON built-in function 559 LENGTH macro facility built-in
linkages JSONGETCOMMA built-in function 560 function 832
OPTLINK 142 JSONGETMEMBER built-in function 561 level-number (of structure elements) 200
SYSTEM 142 JSONGETOBJECTEND built-in levels of structures
interleaved subscripts 199 function 563 description 188
intermediate results of expressions JSONGETOBJECTSTART built-in specifying unique names 190
discussion 54 function 564 levels of unions 190
example 63 JSONGETVALUE built-in function 565 LIKE attribute 193
INTERNAL (INT) attribute 165 JSONNAME attribute 197 Lilian format 416
internal procedure 98 JSONOMIT attribute 198 LIMITED attribute
internal to, definition 163 JSONPUTARRAYEND built-in description 129
INTO option of data transmission function 567 example 130
statements 316 JSONPUTARRAYSTART built-in limits 869
INVALIDOP condition 390 function 568 LINE directive 243
INVALIDOP condition prefix 372 JSONPUTCOLON built-in function 569 LINE format item 351
invocation of entry references 133 JSONPUTCOMMA built-in function 570 LINE option 326
invoked procedure 104 JSONPUTMEMBER built-in LINENO built-in function 582
invoking block 104 function 571 LINESIZE specification in OPEN
invoking built-in functions and JSONPUTOBJECTEND built-in statement 307
pseudovariables 410 function 573 LINKAGE option 142
invoking built-in subroutines 410 JSONPUTOBJECTSTART built-in list
invoking main procedure 92 function 574 bidirectional 278
invoking type functions 799 JSONPUTVALUE built-in function 575 chained 277
IOR built-in function 546 JSONVALID built-in function 576 parameter descriptor 122
IRREDUCIBLE (IRRED) option 143 JULIANTOSMF built-in function 577 processing 277
ISFINITE built-in function 547 unidirectional 278
ISIGNED built-in function 548 LIST attribute
ISINF built-in function 549
ISLL built-in function 550
K description 125
list-directed
K picture character 368
ISMAIN built-in function 551 data specification 338
KEY condition 391
ISNAN built-in function 552 data transmission 321
KEY option of data transmission
ISNORMAL built-in function 553 GET statement 339
statements 316
ISRL built-in function 554 input 339
KEYED attribute 305
iSUB output 340
KEYFROM option of data transmission
defining 283, 286 PUT statement 340
statements 316
unconnected 285 listing control statements 809
KEYTO option of data transmission
ISZERO built-in function 555 LITTLEENDIAN attribute 280
statements 317
ITERATE statement 241 load module
keyword statement 10
iteration factor 291, 292, 334 description 91
keywords
IUNSIGNED built-in function 556 file extensions 91
definition 5
locate mode 318
LOCATE statement 314
J L
LOCATION (LOC) built-in function 583
locator
JSON built-in functions
L-format item 350 conversion 264
JSONGETARRAYEND 557
label 9 data
JSONGETARRAYSTART 558
LABEL attribute attributes 21
JSONGETCOLON 559
description 47 description 264
JSONGETCOMMA 560
label constants 47 offset variable 264
JSONGETMEMBER 561
label data pointer variable 264
JSONGETOBJECTEND 563
attributes 20, 21 qualification 265
JSONGETOBJECTSTART 564
description 47 levels of qualification 266
JSONGETVALUE 565
Index 909
N OMITTED built-in function 624
ON statement 374
operators (continued)
logical 7
N ON-units string 7
FIXED DECIMAL, maximum dynamically descendant 375 using 6
precision 78, 411 for file variables 376 OPTIMIZATION, raising conditions
LIMITS(FIXEDDEC(N1,N2)) 78, 411 null 375 under 373
NAME condition 392 scope 375 OPTIONAL attribute 124
named coded arithmetic attributes 19 ONAREA built-in function 625 options
named constant 45 ONCHAR built-in function 626 ASSEMBLER 138
named constants, description 16 ONCHAR pseudovariable 627 DESCRIPTORS option 181
named string data attributes 20 ONCODE built-in function 628 DLLEXTERNAL 141
names using 371 DLLINTERNAL 141
preprocessor 814 ONCONDCOND built-in function 629 EXPORTS 95
names, typed 145 ONCONDID built-in function 630 FETCHABLE 141
NEW type function 805 ONCOUNT built-in function 631 GRAPHIC 38
NOCHARGRAPHIC option 140 ONFILE built-in function 632 GRAPHIC ENVIRONMENT 38
NODESCRIPTOR option 140 ONGSOURCE built-in function 633 NORESCAN 854
NOEXECOPS option 142 ONGSOURCE pseudovariable 634 of data transmission statements 314,
NOINIT attribute 196 ONKEY built-in function 635 323
NOINLINE option 141 ONLINE built-in function 636 OPTIONS 135
NOMAP option 142 ONLOC built-in function 637 RANGE 180
NONASSIGNABLE attribute 279 ONOFFSET built-in function 638 RECURSIVE 106
NONCONNECTED (NONCONN) ONSOURCE built-in function 639 REPEAT 226
attribute 282 ONSOURCE pseudovariable 640 REPLY 223
nonconnected storage 188 ONSUBCODE built-in function 641 RESCAN 854
nondata attributes 18 ONSUBCODE2 built-in function 642 RESERVES 96
NONVARYING (NONVAR) attribute 32 ONWCHAR built-in function 643 RETURNS 144
NOPRINT directive 243 ONWCHAR pseudovariable 644 SCAN 854
NORESCAN option 854 ONWSOURCE built-in function 645 SET 109
NORMAL attribute 279 ONWSOURCE pseudovariable 646 SNAP 374
normal termination of a program 93 OPEN statement 305 SYSTEM 374
not operator 65 opening and closing files 305 TITLE 109
NOTE directive 244 operands value specification 181
null arguments, using in built-in conversion 61 OPTIONS attribute 135
functions 411 definition 51 OPTIONS options
NULL built-in function 617 operational expressions ASSEMBLER 138
null ON-unit 375 classes 55 BEGIN statement 135
null statement conversion rules 55 BYADDR 139
definition 10 definition 51 BYVALUE 139
description 244 description 55 characteristic list 135
NULLENTRY built-in function 618 example 56 CHARGRAPHIC 140
NULLINIT attribute 196 restrictions on data types 55 COBOL 140
NULLSTRPTR suboption of the operations description 135
DEFAULT built-in function arithmetic 57 DESCRIPTOR 140
using with pointer expressions 56 bit 65 ENTRY declaration 135
numeric character data classes 55 FORTRAN 141
conversion 85 combinations 70 FROMALIEN 141
definition 40 comparison INLINE 141
fields 357 description 67 IRREDUCIBLE 143
picture specifiers 357 example of 68 LINKAGE 142
subfields 357 concatenation 69 MAIN 142
numeric character pictured item handle 55 NOCHARGRAPHIC 140
description 355 infix 55 NODESCRIPTOR 140
discussion 357 logical 65 NOEXECOPS 142
pointer 56 NOINLINE 141
prefix NOMAP 142
O description 55 ORDER 143
OFFSET attribute 273 example 72 PROCEDURE statements 138
OFFSET built-in function 619 operators RECURSIVE 106
offset data 273 arithmetic REDUCIBLE 143
offset variable 264 description 57 REENTRANT 143
OFFSETADD built-in function 620 using 7 REORDER 143
OFFSETDIFF built-in function 621 bit 7 RETCODE 143
OFFSETSUBTRACT built-in comparison 7 syntax 135
function 622 infix WINMAIN 143
OFFSETVALUE built-in function 623 discussion 73 OPTIONS options, ENTRY
OFL (OVERFLOW) condition 392 using with pointer expressions 56 statement 136
Index 911
precision-handling built-in functions procedures (continued) program element (continued)
(continued) description 97 single-byte character set (SBCS)
summary 423 dynamically loading (continued)
UNSIGNED 761 discussion 107 statement elements 5
PRED built-in function 691 rules 108 statement
prefix using the FETCH statement 108 compound 10
condition using the RELEASE discussion 8
example 372 statement 109 simple 10
syntax 371 external 98 program organization 91
using 371 internal 98 program-checkout conditions
preprocessor passing an argument to main 117 STRINGRANGE 395
%ACTIVATE 853 passing arguments STRINGSIZE 396
%assignment 854 discussion 114 SUBSCRIPTRANGE 397
%CALL 820 using BYVALUE and program-control data
%DEACTIVATE 854 BYADDR 115 description 17
%DECLARE 855 using dummy arguments 116 types and attributes 47
%DO 858 using INONLY, INOUT and using 47
%END 858 OUTONLY 115 programmer-defined names 6
%GO TO 858 preprocessor 814 pseudovariables
%IF 859 recursive 106 declaring 409
%INCLUDE 860 specifying attributes 100 description 54
%INSCAN 861 termination 105 ENTRYADDR 500
%ITERATE 861 transferring control out 105 IMAG 540
%LEAVE 861 PROCESS directive 246 invoking 410
%NOTE 862 processing lists 277 ONCHAR 627
%null 863 processing modes ONGSOURCE 634
%REPLACE 863 description 318 ONSOURCE 640
%SELECT 863 locate 318 ONWCHAR 644
%XINCLUDE 864 move 318 ONWSOURCE 646
%XINSCAN 864 PROD built-in function 694 REAL 701
built-in functions 820 program STRING 736
examples of 864 activation 92 SUBSTR 738
facilities 809 blocks summary 424
input 809 activation 93 TYPE 756
input text 809, 811 description 93 UNSPEC 764
listing control 809 definition (for PL/I) 91 PTR (POINTER) attribute 266
listing control statements 810 elements PTRADD (POINTERADD) built-in
names, scope of 814 entry invocation 133 function
output 809 entry value 133 using with pointer operations 56
output text 810 elements of PTRVALUE (POINTERVALUE) built-in
preprocessor 809 begin-blocks 118 function
procedures 814 built-in functions 114 using 57
references and expressions 813 CALL statement 133 punctuating constants 16
scan description 1 PUSH directive 247
and input text 811 entry data 119 PUT statement
and listing control statements 811 functions 112 data-directed 332
and preprocessor statements 811 OPTIONS options 135 edit-directed 336
discussion of 811 RETURN statement 134 list-directed 340
statements subroutines 110 STREAM output 322
description of 809 organization of 91 strings 336
list of 811 packages 94 PUTENV built-in function 695
statements, list of 853 procedures 97
variables and data elements 813 RETURN 134
PRESENT built-in function 692
PRINT attribute 341
structure 91
subroutines 97
Q
qualification
PRINT directive 246 definition 110
description 265
priority of operators 70 termination 93
using as a delimiter 6
PROC (PROCEDURE) statement 98 program block definition 91
structure 191
PROCEDURE (PROC) statement program checkout conditions 372
unions 191
description 98 program element
qualified reference 191
using 92 description 1
quotation marks in strings 16
valid OPTIONS 137 double-byte character set (DBCS)
QUOTE macro facility built-in
PROCEDURE statement 138 discussion 11
function 841
PROCEDURENAME (PROCNAME) statement elements 12
quotes (single or double), enclosing string
built-in function 693 group 11
data 16
procedures single-byte character set (SBCS)
activation 104 discussion 1
Index 913
source-to-target conversion rules statements (continued) STORAGE (STG) built-in function 733
(continued) group 11 STORAGE condition 395
character 86 IF 238 storage control built-in functions
coded arithmetic 82 ITERATE 241 ADDR 433
fixed binary 83 keyword 10 ADDRDATA 434
fixed decimal 83 LEAVE 242 ALLOC31 437
float binary 84 LOCATE 314 ALLOCATE 438
float decimal 84 null 244 ALLOCATION 439
graphic 89 ON 374 ALLOCSIZE 440
numeric character 85 OPEN 305 AUTOMATIC 446
widechar 89 PACKAGE 94 AVAILABLEAREA 447
SOURCEFILE built-in function 728 PROCEDURE BINARYVALUE 457
SOURCELINE built-in function 729 description 98 BITLOCATION 459
spacing format item 354 using to invoke main CHECKSTG 472
specification procedure 92 CURRENTSIZE 485
edit-directed 333 PUT CURRENTSTORAGE 486
list-directed 338 data-directed 332 EMPTY 497
repetitive 325 edit-directed 336 ENTRYADDR 499
transmission of data list items 328 list-directed 340 HANDLE 526
specification characters 355 STREAM output 322 LOCATION 583
SQRT built-in function 730 READ 312 LOCSTG 586
SQRTF built-in function 731 REINIT 248 LOCVAL 587
STACKADDR built-in function 732 RELEASE NULL 617
stacking 107 description 109 NULLENTRY 618
standards xx dynamically loading external 107 OFFSET 619
statement elements example 110 OFFSETADD 620
for DBCS 12 restrictions 108 OFFSETDIFF 621
for SBCS 5 RESIGNAL 378 OFFSETSUBTRACT 622
STATEMENT option 817 RETURN OFFSETVALUE 623
statements description 134 POINTER 683
%PROCEDURE 816 returning from a function 134 POINTERADD 684
ALLOCATE 267 syntax 134 POINTERDIFF 685
ANSWER using 105 POINTERSUBTRACT 686
using in a preprocessor using in a preprocessor POINTERVALUE 687
procedure 818 procedure 817 SIZE 725
ASSERT 211 using with subroutines 134 STORAGE 733
assignment 10, 213 REVERT 377 summary 424
ATTACH 404 REWRITE SYSNULL 742
BEGIN 118 description 313 SYSTEM 743
CALL 133 SELECT UNALLOCATED 760
CLOSE 309 description 249 STREAM attribute 302
coding recommendations 8 example 250 stream-oriented data transmission
compound 10 SIGNAL 377 definition 297
DECLARE 160 simple 10 list directed 321
DEFAULT 179 STOP STRG (STRINGRANGE) condition 395
DEFINE ALIAS 145 using 105 STRING built-in function 734
DEFINE ORDINAL 146 syntax 8 string data
DEFINE STRUCTURE 148 WAIT 406 attributes
DELAY 222 WRITE abbreviations 31
DELETE 314 description 313 classification 20
DETACH 406 static allocation 253 specifying length 31
discussion 211 STATIC attribute bit 36
DISPLAY 223 description 254 BIT attribute 30
DO 223 with INITIAL attribute 293 CHARACTER attribute 30
END 236 static storage 253, 254 character data 34
ENTRY 99 STOP statement definition 17
EXIT 105 using 105 graphic 37
FETCH 107 storage GRAPHIC attribute 30
FORMAT 337 allocation 253 mixed 38
FREE 259, 268 automatic 255 NONVARYING attribute 32
GET based 261 PICTURE attribute 33
data-directed 331 classification 253 quotation marks 16
edit-directed 335 connected 282 repetition factor 34, 292
list-directed 339 control 253 transmission of varying length 311
STREAM input 322 controlled 256 VARYING attribute 32
GET STRING 322 nonconnected 188 VARYING4 attribute 32
GO TO 237 static 254 VARYINGZ attribute 32
Index 915
TASK attribute 407 typed variables, declaring (continued) UTCDATETIME built-in function 769
task data, attributes, classification 21 qualifying 152 UTCSECS built-in function 770
task variable 407 types UTF-handling built-in functions
termination DEFINE STRUCTURE statement 148 ULENGTH 757
begin-block 118 defining 145 ULENGTH16 759
block 94, 236 description 150 ULENGTH8 758
procedure 105 HANDLE built-in function 150 UPOS 765
program 93 handles 150 USUBSTR 767
thread 405 qualifying 152 USUPPLEMENTARY 768
THEN clause of %IF statement 859 type functions 157 UTF8 771
THEN clause of IF statement 238 variables 150 UTF8TOCHAR 773
thread UTF8TOWCHAR 774
ATTACH statement 404 UVALID 776
canceling 406
condition handling 407
U UWIDTH 778
UTF8 built-in function 771
UFL (UNDERFLOW) condition 399
creation of 403 UTF8STG built-in function 772
ULENGTH built-in function 757
detaching 406 UTF8TOCHAR built-in function 773
ULENGTH16 built-in function 759
ENVIRONMENT option 404 UTF8TOWCHAR built-in function 774
ULENGTH8 built-in function 758
sharing data 408 UVALID built-in function 776
UNALIGNED attribute
sharing files 408 UWIDTH built-in function 778
description and syntax 173
TASK attribute 407
effect on structure mapping 202
task variable 407
example 177
termination 405
THREAD option 404
storage alignment requirements 173 V
UNALLOCATED built-in function 760 V picture specification character 358
TSTACK option 405
UNBUF (UNBUFFERED) attribute 304 V-format item 353
uses of 403
UNBUFFERED (UNBUF) attribute 304 VALID built-in function 779
waiting 406
unconnected storage 188, 285 VALIDDATE built-in function 780
THREAD option 404
UNDEFINEDFILE (UNDF) VALUE attribute
THREADID built-in function 748
condition 398 description 45
TIME built-in function 749
UNDERFLOW (UFL) condition 399 ordinals 147
TIMESTAMP built-in function 750
UNDERFLOW condition prefix 372 VALUE option 180, 181
TINY built-in function 751
UNDF (UNDEFINEDFILE) VALUE type function 808
TITLE option 109
condition 398 VARGLIST built-in function 781
TITLE specification on the OPEN
UNION attribute 190 VARGSIZE built-in function 782
statement 307
UNION, synonym for 190 VARIABLE attribute 49
TO option 225
unions variables
TO option on INITIAL attribute 292
cross sections of arrays 199 array 184
TRANSLATE built-in function 752
declaration 190 automatic 107
TRANSLATE macro facility built-in
description 190 based
function 850
example 190 identifying 261
transmission of data 297
levels 190 using 267
TRANSMIT condition 397
names 190 controlled 256
TRIM built-in function 753
qualifying names 191 definition 16
TRUNC built-in function 754
UNION attribute, classification 21 discussion 257
TSTACK option 405
UNSIGNED attribute entry 120
TYPE attribute 150
data storage requirements 26 offset 264
TYPE built-in function 755
description 25 pointer 264, 266
type definitions, description 145
ordinals 147 preprocessor 813
type functions 157
UNSIGNED built-in function 761 reference 16
arguments 799
UNSPEC built-in function 762 representing complex data items 24
BIND 801
UNSPEC pseudovariable 764 structure 188
CAST 802
UNTIL option targets 54
discussion 799
description 224 variables, as handles 150
FIRST 803
using with a type 2 DO variables, typed 150
LAST 804
specification 226 VARYING (VAR) attribute 32
list 799
UPDATE attribute 303 VARYING4 attribute 32
NEW 805
UPOS built-in function 765 VARYINGZ (VARZ) attribute 32
RESPEC 806
UPPERCASE built-in function 766 VERIFY built-in function 783
SIZE 807
UPTHRU option VERIFY macro facility built-in
VALUE 808
description 225 function 853
type functions, invoking 799
example 234 VERIFYR built-in function 784
TYPE pseudovariable 756
using with a type 3 DO
typed names 145
specification 229
typed structures in HANDLE built-in
function 526
UPTHRU, using with ordinals 234
USUBSTR built-in function 767
W
typed variables, declaring 150 WAIT statement 406
USUPPLEMENTARY built-in
handles 150 WCHARVAL built-in function 785
function 768
X
X (hex) character string constant 35
X picture specification character 356
X-format item 354
XMLATTR attribute 196
XMLCHAR built-in function 792
XMLCLEAN built-in function 794
XMLCONTENT attribute 196
XMLOMIT attribute 197
XN (binary hex) constant 27
XU (binary hex) constant 27
Y
Y zero replacement picture
character 366
Y4DATE built-in function 795
Y4JULIAN built-in function 796
Y4YEAR built-in function 797
Z
Z zero suppression picture character 359
ZDIV (ZERODIVIDE) condition 400
zero replacement character 366
zero suppression characters 359
ZERODIVIDE (ZDIV) condition 400
ZERODIVIDE condition prefix 372
Index 917
918 Enterprise PL/I for z/OS Language Reference
Readers Comments We'd Like to Hear from You
Enterprise PL/I for z/OS
PL/I for AIX
Rational Developer for System z PL/I for Windows
Language Reference
Version 5 Release 1
We appreciate your comments about this publication. Please comment on specific errors or omissions, accuracy,
organization, subject matter, or completeness of this book. The comments you send should pertain to only the
information in this manual or product and the way in which the information is presented.
For technical questions and information about products and prices, please contact your IBM branch office, your
IBM business partner, or your authorized remarketer.
When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any
way it believes appropriate without incurring any obligation to you. IBM or any other organizations will only use
the personal information that you supply to contact you about the issues that you state on this form.
Comments:
Name Address
Company or Organization
_ _ _ _ _ _ _Fold
_ _ _and
_ _ _Tape
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Please
_ _ _ _ _do
_ _not
_ _ staple
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Fold
_ _ _and
_ _ Tape
______
NO POSTAGE
NECESSARY
IF MAILED IN THE
UNITED STATES
IBM
H150/090
555 Bailey Avenue
San Jose, CA
USA 95141-1099
_________________________________________________________________________________________
Fold and Tape Please do not staple Fold and Tape
Cut or Fold
SC27-8940-00 Along Line
IBM
Printed in USA
SC27-8940-00