-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy path7.texi
More file actions
5096 lines (4174 loc) · 284 KB
/
7.texi
File metadata and controls
5096 lines (4174 loc) · 284 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
@comment *********************************************************************
@comment ** 7. PROCEDURE DIVISION **
@comment *********************************************************************
@newchapter{7,PROCEDURE DIVISION}
@diagram{PROCEDURE DIVISION,PD-Overview-Info,PD-Overview-TeX,None}
The @code{PROCEDURE DIVISION} of any GnuCOBOL program marks the point where all executable code is written.
@menu
* 7.1: PROCEDURE DIVISION USING.
* 7.2: PROCEDURE DIVISION CHAINING.
* 7.3: PROCEDURE DIVISION RETURNING.
* 7.4: PROCEDURE DIVISION Sections and Paragraphs.
* 7.5: DECLARATIVES.
* 7.6: Common Clauses on Executable Statements.
@detailmenu
* 7.6.1: AT END + NOT AT END.
* 7.6.2: CORRESPONDING.
* 7.6.3: INVALID KEY + NOT INVALID KEY.
* 7.6.4: ON EXCEPTION + NOT ON EXCEPTION.
* 7.6.5: ON OVERFLOW + NOT ON OVERFLOW.
* 7.6.6: ON SIZE ERROR + NOT ON SIZE ERROR.
* 7.6.7: ROUNDED.
@end detailmenu
* 7.7: Special Registers.
* 7.8: GnuCOBOL Statements.
@end menu
@comment *********************************************************************
@comment ** 7.1 PROCEDURE DIVISION USING **
@comment *********************************************************************
@page
@newsection{7.1,PROCEDURE DIVISION USING}
@diagram{PROCEDURE DIVISION Subprogram-Argument,PD-USING,PD-USING,None}
The @code{USING} clause defines the arguments that will be passed to a GnuCOBOL program which is serving as a subprogram.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{BY} and @code{IS} are optional and may be omitted. The presence or absence of these words have no effect upon the program.
@comment Semantic Specifications:
@item
The
@syntaxidx{USING} clause should only be used on the procedure division header of subprograms (subroutines or user-defined functions).
@item
The calling program will pass zero or more data items, known as arguments, to this subprogram --- there must be exactly as many @var{identifier-1} data items specified on the @code{USING} clause as the maximum number of arguments the subprogram will ever be passed.
@item
If a subprogram does not expect any arguments, it should not have a @code{USING} clause specified on its procedure division header.
@item
The order in which arguments are defined on the @code{USING} clause must correspond to the order in which those arguments will be passed to the subprogram by the calling program.
@item
The identifiers specified on the @code{USING} clause must be defined in the linkage section of the subprogram. No storage is actually allocated for those identifiers in the subprogram as the actual storage for them will exist in the calling program.
@item
A GnuCOBOL subprogram expects that all arguments to it will be one of two things:
@itemize @bullet
@item
The memory address of the actual data item (allocated in the calling program) that is being passed to the subprogram.
@item
A numeric, full-word, binary value (i.e. @syntaxrefalt{USAGE BINARY-LONG,USAGE}) which is the actual argument being passed to the subprogram.
@end itemize
In the case of the former, the @code{USING} clause on the procedure division header should describe the argument via the
@syntaxidx{BY REFERENCE} clause --- in the latter case, a
@syntaxidx{BY VALUE} specification should be coded. This allows the code generated by the compiler to properly reference the subprogram arguments at run-time.
@item
@code{BY REFERENCE} is the assumed default for the first @code{USING} argument should no @code{BY} clause be specified for it. Subsequent arguments will assume the @code{BY} specification of the argument prior to them should they lack a @code{BY} clause of their own.
@item
Changes made by a subprogram to the value of an argument specified on the @code{USING} clause will ``be visible'' to the calling program only if @code{BY REFERENCE} was explicitly specified or implicitly assumed for the argument on the subprogram's procedure division header @i{and} the argument was passed to the subprogram @code{BY REFERENCE} by the calling program. @xref{Subprogram Arguments}, for additional information on the mechanics of how arguments are passed to subprograms.
@item
The optional @code{SIZE} clause allows you to specify the number of bytes a @code{BY VALUE} argument will occupy, with @code{SIZE DEFAULT} specifying 4 bytes (this is the default if no @code{SIZE} clause is used), @code{SIZE AUTO} specifying the size of the argument in the calling program and @code{SIZE @var{integer-1}} specifying a specific byte count.
@item
The optional @code{UNSIGNED} keyword, legal only if @code{SIZE AUTO} or @code{SIZE @var{integer-1}} are coded, will add the @code{unsigned} attribute to the argument's specification in the C-language function header code generated for the subprogram. While not of any benefit when the calling program is a GnuCOBOL program, this can improve compatibility with a C-language calling program.
@item
The
@syntaxidx{OPTIONAL} keyword, legal only on @code{BY REFERENCE} arguments, allows calling programs to code
@syntaxidx{OMITTED} for that corresponding argument when they call this subprogram. @xref{CALL}. for additional information on this feature.
@end enumerate
@comment *********************************************************************
@comment ** 7.2 PROCEDURE DIVISION CHAINING **
@comment *********************************************************************
@page
@newsection{7.2,PROCEDURE DIVISION CHAINING}
@diagram{PROCEDURE DIVISION Main-Program-Argument,PD-CHAINING,PD-CHAINING,None}
The @code{CHAINING} term provides one mechanism a programmer may use to retrieve command-line arguments passed to a program at execution time.
@enumerate
@comment Syntactical Specifications:
@comment Semantic Specifications:
@item
@code{PROCEDURE DIVISION CHAINING} may only be coded in a main program (that is, the first program executed when a compiled GnuCOBOL compilation unit is executed). It cannot be used in any form of subprogram.
@item
The @code{CHAINING} clause defines arguments that will be passed to a main program from the operating system. The argument identifiers specified on the @code{CHAINING} clause will be populated by character strings comprised of the parameters specified to the program on the command line that executed it, as follows:
@enumerate A
@item
When a GnuCOBOL program is executed from a command-line, the complete command line text will be broken into a series of @i{tokens}, where each token is identified as being a word separated from the others in the command text by at least one space. For example, if the command line was @command{/usr/local/myprog THIS IS A TEST}, there will be five tokens identified by the operating system --- @samp{/usr/local/myprog}, @samp{THIS}, @samp{IS}, @samp{A} and @samp{TEST}.
@item
Multiple space-delimited tokens may be treated as a single token by enclosing them in quotes. For example, there are only three tokens generated from the command line @command{C:\Pgms\myprog.exe @samp{THIS IS A} TEST} --- @samp{C:\Pgms\myprog.exe}, @samp{THIS IS A} and @samp{TEST}. When quote characters are used to create multi-word tokens, the quote characters themselves are stripped from the token's value.
@item
Once tokens have been identified, the first one (the command) will be discarded; the rest will be stored into the @code{CHAINING} arguments when the program begins execution, with the 2nd token going to the 1@sup{st} argument, the 3rd token going to the 2nd argument and so forth.
@item
If there are more tokens than there are arguments, the excess tokens will be discarded.
@item
If there are fewer tokens than there are arguments, the excess arguments will be initialized as if the @syntaxrefalt{INITIALIZE @var{identifier-1},INITIALIZE} statement were executed.
@item
All identifiers specified on the @code{CHAINING} clause should be defined as @code{PIC X, PIC A}, group items (which are treated implicitly as @code{PIC X}) or as @code{PIC 9 USAGE DISPLAY}. The use of @code{USAGE BINARY} (or the like) data items as @code{CHAINING} arguments is not recommended as all command-line tokens will be retained in their original character form as they are moved into the argument data items.
@item
If an argument identifier is smaller in storage size than the token value to be stored in it, the right-most excess characters of the token value will be truncated as the value is moved in. Any @code{JUSTIFIED RIGHT} clause on such an argument identifier will be ignored.
@item
If an argument is larger in storage size than the token value to be stored in it, the token value will be moved into the argument identifier in a left-justified manner. unmodified-modified byte positions in the identifier will be space filled, unless the argument identifier is defined as @code{PIC 9 USAGE DISPLAY}, in which case unmodified bytes will be filled with @samp{0} characters from the systems native character set.
This behaviour when the argument is defined as @code{PIC 9} may be unacceptable, as an argument defined as @code{PIC 9(3)} but passed in a value of @samp{1} from the command line will receive a value of @samp{100}, not @samp{001}. Consider defining ``numeric'' command line arguments as @code{PIC X} and then using the @intrinsicref{NUMVAL} function to determine the proper numeric value.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 7.3 PROCEDURE DIVISION RETURNING **
@comment *********************************************************************
@page
@newsection{7.3,PROCEDURE DIVISION RETURNING}
@diagram{PROCEDURE DIVISION RETURNING,PD-RETURNING,PD-RETURNING,None}
The RETURNING clause on the PROCEDURE DIVISION header documents that the subprogram in which the clause appears will be returning a numeric value back to the program that called it. This is only available for functions as it does not work for programs and has issues depending on the platform (operating system) in use - You must test for this for the specific platform.
@comment Semantic Specifications:
@enumerate
@item
The @code{RETURNING} clause is optional within a subroutine, as not all subroutines return a value to their caller.
@item
The @code{RETURNING} clause is mandatory within a user-defined function, as all such must return a numeric result.
@item
The @var{identifier-1} data item should be defined as a @code{USAGE BINARY-LONG} data item.
@item
Main programs that wish to ``pass back'' a return code value to the operating system when they exit do not use @code{RETURNING} - they do so simply by MOVEing a value to the @code{RETURN-CODE} special register.
@item
This is not the only mechanism that a subprogram may use to pass a value back to its caller. Other possibilities are:
@enumerate A
@item
The subprogram may modify any argument that is specified as @code{BY REFERENCE} on its @code{PROCEDURE DIVISION} header. Whether the calling program can actually ``see'' any modifications depends upon how the calling program passed the argument to the subprogram. @xref{CALL}, for more information.
@item
A data item with the @syntaxref{GLOBAL} attribute specified in its description in the calling program is automatically visible to and updatable by a subprogram nested with the calling program. @xref{Independent vs Contained vs Nested Subprograms}, for more information on subprogram nesting.
@item
A data item defined with the @syntaxref{EXTERNAL} attribute in a subprogram and the calling program (same name in both programs) is automatically visible to and updatable by both programs, even if those programs are compiled separately from one another.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 7.4 PROCEDURE DIVISION Sections and Paragraphs **
@comment *********************************************************************
@page
@newsection{7.4,PROCEDURE DIVISION Sections and Paragraphs}
The procedure division is the only one of the COBOL divisions that allows you to create your own sections and paragraphs. These are collectively referred to as
@define{Procedures}, and the names you create for those sections and paragraphs are called
@define{Procedure Names}.
Procedure names are optional in the procedure division and --- when used --- are named entirely according to the needs and whims of the programmer.
Procedure names may be up to thirty one (31) characters long and may consist of letters, numbers, dashes and underscores. A procedure name may neither begin nor end with a dash (@samp{-}) or underscore (@samp{_}) character. This means that @code{Main}, @code{0100-Read-Transaction} and @code{17} are all perfectly valid procedure names.
There are three circumstances under which the use of certain GnuCOBOL statements or options will require the specification of procedures. These situations are:
@enumerate
@item
When @syntaxref{DECLARATIVES} are specified.
@item
When the @statementref{ENTRY} is being used.
@item
When any procedure division statement that references procedures is used. These statements are:
@itemize @bullet
@item
@code{ALTER @var{procedure-name}}
@item
@code{GO TO @var{procedure-name}}
@item
@code{MERGE @dots{} OUTPUT PROCEDURE @var{procedure-name}}
@item
@code{PERFORM @var{procedure-name}}
@item
@code{SORT @dots{} INPUT PROCEDURE @var{procedure-name}} and/or @code{SORT @dots{} INPUT PROCEDURE @var{procedure-name}}
@end itemize
@end enumerate
@comment *********************************************************************
@comment ** 7.5 DECLARATIVES **
@comment *********************************************************************
@page
@newsection{7.5,DECLARATIVES}
@diagram{DECLARATIVES,PD-DECLARATIVES,PD-DECLARATIVES,PD-DECLARATIVES}
The @code{DECLARATIVES} area of the procedure division allows the programmer to define a series of ``trap'' procedures (referred to as declarative procedures) capable of intercepting certain events that may occur at program execution time. The syntax diagram above shows the format of a single such procedure.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{AFTER}, @code{FOR}, @code{ON}, @code{PROCEDURE} and @code{STANDARD} are optional and may be omitted. The presence or absence of these words has no effect upon the program.
@item
@code{EC} and @code{EXCEPTION CONDITION} are interchangeable.
@comment Semantic Specifications:
@item
The declaratives area may contain any number of declarative procedures, but no two declarative procedures should be coded to trap the same event.
@item
The following points apply to the
@syntaxidx{USE BEFORE REPORTING} clause:
@enumerate A
@item
@var{identifier-2} must be a report group.
@item
At run-time, the declaratives procedure will be executed prior to the processing of the specified report group's presentation; within the procedure you may take either of the following actions:
@itemize @bullet
@item
You may adjust the value(s) of any items referenced in @syntaxref{SUM} or @syntaxref{SOURCE} clauses in the report group.
@item
You may execute the @syntaxref{SUPPRESS} statement to squelch the presentation of the specified report group altogether. Note that you will be suppressing this one specific instance of that group's presentation and not all of them.
@end itemize
@end enumerate
@item
The following points apply to the
@syntaxidx{USE FOR DEBUGGING} clause:
@enumerate A
@item
This clause allows you to define a declarative procedure that will be invoked whenever@dots{}
@itemize @bullet
@item
@dots{}@var{identifier-1} is referenced on any statement.
@item
@dots{}@var{procedure-name-1} is executed.
@item
@dots{}any procedure is executed (@code{ALL PROCEDURES}).
@end itemize
@item
A @code{USE FOR DEBUGGING} declarative procedure will be ignored at @i{compilation} time unless @code{WITH DEBUGGING MODE} is specified in the @syntaxref{SOURCE-COMPUTER} paragraph. Neither the compiler's
@switchidx{-fdebugging-line} nor
@switchidx{-debug} will activate this feature.
@item
Any @code{USE FOR DEBUGGING} declarative procedures will be ignored at @i{execution} time unless the
@envvarruntimeref{COB_SET_DEBUG} has been set to a value of @samp{Y}, @samp{y} or @samp{1}.
@item
The typical use of a @code{USE FOR DEBUGGING} declarative procedure is to display the
@register{DEBUG-ITEM}, which will be implicitly and automatically created in your program for you if @code{WITH DEBUGGING MODE} is active.
The structure of @code{DEBUG-ITEM} will be as follows:
@example
01 DEBUG-ITEM.
05 DEBUG-LINE PIC X(6).
05 FILLER PIC X(1) VALUE SPACE.
05 DEBUG-NAME PIC X(31).
05 FILLER PIC X(1) VALUE SPACE.
05 DEBUG-SUB-1 PIC S9(4) SIGN LEADING SEPARATE.
05 FILLER PIC X(1) VALUE SPACE.
05 DEBUG-SUB-2 PIC S9(4) SIGN LEADING SEPARATE.
05 FILLER PIC X(1) VALUE SPACE.
05 DEBUG-SUB-3 PIC S9(4) SIGN LEADING SEPARATE.
05 FILLER PIC X(1) VALUE SPACE.
05 DEBUG-CONTENTS PIC X(31).
@end example
where@dots{}
@table @asis
@item @code{DEBUG-LINE}
@dots{} is the program line number of the statement that triggered the declaratives procedure.
@item @code{DEBUG-NAME}
@dots{} is the procedure name or identifier name that triggered the declaratives procedure.
@item @code{DEBUG-SUB-1}
@dots{} is the first subscript value (if any) for the reference of the identifier that triggered the declaratives procedure.
@item @code{DEBUG-SUB-2}
@dots{} is the second subscript value (if any) for the reference of the identifier that triggered the declaratives procedure.
@item @code{DEBUG-SUB-3}
@dots{} is the third subscript value (if any) for the reference of the identifier that triggered the declaratives procedure.
@item @code{DEBUG-CONTENTS}
@dots{} is a (brief) statement of the manner in which the procedure that triggered the declaratives procedure was executed or the first 31 characters of the value of the identifier whose reference triggered the declaratives procedure (the value after the statement was executed).
@end table
@end enumerate
@item
The
@syntaxidx{USE AFTER STANDARD ERROR PROCEDURE} clause defines a declarative procedure invoked any time a failure is encountered with the specified I/O type (or against the specified file(s)).
@item
The @syntaxref{GLOBAL} option, if used, allows a declarative procedure to be used across the program containing the @statement{USE} and any subprograms nested within that program.
@item
Declarative procedures may not reference any other procedures defined outside the scope of DECLARATIVES.
@end enumerate
@comment *********************************************************************
@comment ** 7.6 Common Clauses on Executable Statements **
@comment *********************************************************************
@newsection{7.6,Common Clauses on Executable Statements}
@menu
* 7.6.1: AT END + NOT AT END.
* 7.6.2: CORRESPONDING.
* 7.6.3: INVALID KEY + NOT INVALID KEY.
* 7.6.4: ON EXCEPTION + NOT ON EXCEPTION.
* 7.6.5: ON OVERFLOW + NOT ON OVERFLOW.
* 7.6.6: ON SIZE ERROR + NOT ON SIZE ERROR.
* 7.6.7: ROUNDED.
@end menu
@comment *********************************************************************
@comment ** 7.6.1 AT END + NOT AT END **
@comment *********************************************************************
@newsubsection{7.6.1,AT END + NOT AT END}
@diagram{AT END,PD-AT-END,PD-AT-END,None}
@code{AT END} clauses may be specified on @syntaxref{READ}, @syntaxref{RETURN}, @syntaxref{SEARCH} and @syntaxref{SEARCH ALL} statements.
@enumerate
@item
The following points pertain to the use of these clauses on @syntaxref{READ} and @syntaxref{RETURN} statements:
@enumerate A
@item
The @code{AT END} clause will --- if present --- cause @var{imperative-statement-1} (@pxref{Imperative Statement}) to be executed if the statement fails due to a file status of 10 (end-of-file). @xref{File Status Codes}, for a list of possible File Status codes.
An @code{AT END} clause @i{will not detect other non-zero file-status values}.
Use a @syntaxref{DECLARATIVES} routine or an explicitly-declared file status field tested after the @code{READ} or @code{RETURN} to detect error conditions other than end-of-file.
@item
A @code{NOT AT END} clause will cause @var{imperative-statement-2} to be executed if the @code{READ} or @code{RETURN} attempt is successful.
@end enumerate
@item
The following points pertain to the use of these clauses on @syntaxref{SEARCH} and @syntaxref{SEARCH ALL} statements:
@enumerate A
@item
An @code{AT END} clause detects and handles the case where either form of table search has failed to locate an entry that satisfies the search conditions being used.
@item
The @code{NOT AT END} clause is not allowed on either form of table search.
@end enumerate
@end enumerate
@comment *********************************************************************
@comment ** 7.6.2 CORRESPONDING **
@comment *********************************************************************
@page
@newsubsection{7.6.2,CORRESPONDING}
Three GnuCOBOL statements --- @syntaxrefalt{ADD,ADD CORRESPONDING}, @syntaxrefalt{MOVE,MOVE CORRESPONDING} and @syntaxrefalt{SUBTRACT,SUBTRACT CORRESPONDING} support the use of a @code{CORRESPONDING} option:
@verbatim
ADD CORRESPONDING group-item-1 TO group-item-2
MOVE CORRESPONDING group-item-1 TO group-item-2
SUBTRACT CORRESPONDING group-item-1 FROM group-item-2
@end verbatim
This option allows one or more data items within one group item (@var{group-item-1} --- the first named on the statement) to be paired with correspondingly-named (hence the name) in a second group item (@var{group-item-2} --- the second named on the statement). The contents of @var{group-item-1} will remain unaffected by the statement while one or more data items within @var{group-item-2} will be changed.
In order for @var{data-item-1}, defined subordinate to group item @var{group-item-1} to be a @i{corresponding} match to @var{data-item-2} which is subordinate to @var{group-item-2}, each of the following must be true:
@enumerate
@item
Both @var{data-item-1} and @var{data-item-2} must have the same name, and that name may not explicitly or implicitly be @code{FILLER}.
@item
Both @var{data-item-1} and @var{data-item-2}@dots{}
@enumerate A
@item
@dots{}must exist at the same relative structural ``depth'' of definition within @var{group-item-1} and @var{group-item-2}, respectively
@item
@dots{}and all ``parent'' data items defined within each group item must have identical (but non-@code{FILLER}) names.
@end enumerate
@item
When used with a @code{MOVE} verb@dots{}
@enumerate A
@item
@dots{}one of @var{data-item-1} or @var{data-item-2} (but not both) is allowed to be a group item
@item
@dots{}and it must be valid to move @var{data-item-1} TO @var{data-item-2}.
@end enumerate
@item
When used with @code{ADD} or @code{SUBTRACT} verbs, both @var{data-item-1} and @var{data-item-2} must be numeric, elementary, unedited items.
@item
Neither @var{data-item-1} nor @var{data-item-2} may be a @syntaxref{REDEFINES} or @syntaxref{RENAMES} of another data item.
@item
Neither @var{data-item-1} nor @var{data-item-2} may have an @syntaxref{OCCURS} clause, although either may contain subordinate data items that @i{do} have an @code{OCCURS} clause (assuming rule 3a applies)
@end enumerate
Observe the definitions of data items @samp{Q} and @samp{Y}@dots{}
@example
01 Q. 01 Y.
03 X. 02 A PIC X(1).
05 A PIC 9(1). 02 G1.
05 G1. 03 G2.
10 G2. 04 B PIC X(1).
15 B PIC X(1). 02 C PIC X(1).
05 C. 02 G3.
10 FILLER PIC X(1). 03 G5.
05 G3. 04 D PIC X(1).
10 G4. 03 G6 PIC X(1).
15 D PIC X(1). 02 E PIC 9(1).
05 E PIC X(1). 02 F PIC X(1).
05 F REDEFINES V1 02 G PIC X(4).
PIC X(1). 02 H OCCURS 4 TIMES
05 G. PIC X(1).
10 G6 OCCURS 4 TIMES 66 I RENAMES E.
PIC X(1). 02 J.
05 H PIC X(4). 03 K.
05 I PIC 9(1). 04 L.
05 J. 05 M.
10 K.
15 M PIC X(1).
@end example
The following are the valid @code{CORRESPONDING} matches, assuming the statement @code{MOVE CORRESPONDING X TO Y} is being executed (there are no valid corresponding matches for @code{ADD CORRESPONDING} or @code{SUBTRACT CORRESPONDING} because every potential match up violates rule #4):
@center A, B, C, G
The following are the @code{CORRESPONDING} match ups that passed rule #1 (but failed on another rule), and the reasons why they failed.
@multitable @columnfractions .1 .9
@headitem Data Item @tab Failure Reason
@item @code{D} @tab Fails due to rule #2b
@item @code{E} @tab Fails due to rule #3b
@item @code{F} @tab Fails due to rule #5
@item @code{G1} @tab Fails due to rule #3a
@item @code{G2} @tab Fails due to rule #3a
@item @code{G3} @tab Fails due to rule #3a
@item @code{G4} @tab Fails due to rule #1
@item @code{G5} @tab Fails due to rule #1
@item @code{G6} @tab Fails due to rule #6
@item @code{H} @tab Fails due to rule #6
@item @code{I} @tab Fails due to rule #5
@item @code{J} @tab Fails due to rule #3a
@item @code{K} @tab Fails due to rule #3a
@item @code{L} @tab Fails due to rule #1
@item @code{M} @tab Fails due to rule #2a
@end multitable
@comment *********************************************************************
@comment ** 7.6.3 INVALID KEY + NOT INVALID KEY **
@comment *********************************************************************
@newsubsection{7.6.3,INVALID KEY + NOT INVALID KEY}
@diagram{INVALID KEY,PD-INVALID-KEY,PD-INVALID-KEY,None}
@code{INVALID KEY} clauses may be specified on @syntaxref{DELETE}, @syntaxrefalt{READ,Random READ}, @syntaxref{REWRITE}, @syntaxref{START} and @syntaxref{WRITE} statements.
Specification of an @code{INVALID KEY} clause will allow your program to trap an I/O failure condition (with an I/O error code in the file's @syntaxrefalt{FILE-STATUS,SELECT} field) that has occurred due to a record-not-found condition and handle it gracefully by executing @var{imperative-statement-1} (@pxref{Imperative Statement}).
An optional
@syntaxidx{NOT INVALID KEY} clause will cause @var{imperative-statement-2} to be executed if the statement's execution was successful.
@comment *********************************************************************
@comment ** 7.6.4 ON EXCEPTION + NOT ON EXCEPTION **
@comment *********************************************************************
@newsubsection{7.6.4,ON EXCEPTION + NOT ON EXCEPTION}
@diagram{ON EXCEPTION,PD-ON-EXCEPTION,PD-ON-EXCEPTION,None}
@code{EXCEPTION} clauses may be specified on @syntaxref{ACCEPT}, @syntaxref{CALL} and @syntaxref{DISPLAY} statements.
Specification of an exception clause will allow your program to trap a failure condition that has occurred and handle it gracefully by executing @var{imperative-statement-1} (@pxref{Imperative Statement}). If such a condition occurs at runtime without having one of these clauses specified, an error message will be generated (by the GnuCOBOL runtime library) to the @code{SYSERR} device (pipe 2). The program may also be terminated, depending upon the type and severity of the error.
An optional
@syntaxidx{NOT ON EXCEPTION} clause will cause @var{imperative-statement-2} to be executed if the statement's execution was successful.
@comment *********************************************************************
@comment ** 7.6.5 ON OVERFLOW + NOT ON OVERFLOW **
@comment *********************************************************************
@newsubsection{7.6.5,ON OVERFLOW + NOT ON OVERFLOW}
@diagram{ON OVERFLOW,PD-ON-OVERFLOW,PD-ON-OVERFLOW,None}
@code{OVERFLOW} clauses may be specified on @syntaxref{CALL}, @syntaxref{STRING} and @syntaxref{UNSTRING} statements.
An @code{ON OVERFLOW} clause will allow your program to trap a failure condition that has occurred and handle it gracefully by executing @var{imperative-statement-1} (@pxref{Imperative Statement}). If such a condition occurs at runtime without having one of these clauses specified, an error message will be generated (by the GnuCOBOL runtime library) to the @code{SYSERR} device (pipe 2). The program may also be terminated, depending upon the type and severity of the error.
An optional
@syntaxidx{NOT ON OVERFLOW} clause will cause @var{imperative-statement-2} to be executed if the statement's execution was successful.
@comment *********************************************************************
@comment ** 7.6.6 ON SIZE ERROR + NOT ON SIZE ERROR **
@comment *********************************************************************
@newsubsection{7.6.6,ON SIZE ERROR + NOT ON SIZE ERROR}
@diagram{ON SIZE ERROR,PD-ON-SIZE-ERROR,PD-ON-SIZE-ERROR,None}
@code{SIZE ERROR} clauses may be included on @syntaxref{ADD}, @syntaxref{COMPUTE}, @syntaxref{DIVIDE}, @syntaxref{MULTIPLY} and @syntaxref{SUBTRACT} statements.
Including an @code{ON SIZE ERROR} clause on an arithmetic statement will allow your program to trap a failure of an arithmetic statement (either generating a result too large for the receiving field, or attempting to divide by zero) and handle it gracefully by executing @var{imperative-statement-1} (@pxref{Imperative Statement}). Field size overflow conditions occur silently, usually without any runtime messages being generated, even though such events rarely lend themselves to generating correct results. Division by zero errors, when no @code{ON SIZE ERROR} clause exists, will produce an error message (by the GnuCOBOL runtime library) to the @code{SYSERR} device (pipe 2) and will also abort the program.
An optional
@syntaxidx{NOT ON SIZE ERROR} clause will cause @var{imperative-statement-2} to be executed if the arithmetic statement's execution was successful.
@comment *********************************************************************
@comment ** 7.6.7 ROUNDED **
@comment *********************************************************************
@newsubsection{7.6.7,ROUNDED}
@diagram{ROUNDED,PD-ROUNDED,PD-ROUNDED,None}
GnuCOBOL provides for control over the final rounding process applied to the receiving fields on all arithmetic verbs. Each of the arithmetic statements (@syntaxref{ADD}, @syntaxref{COMPUTE}, @syntaxref{DIVIDE}, @syntaxref{MULTIPLY} and @syntaxref{SUBTRACT}) statements allow an optional @code{ROUNDED} clause to be applied to each receiving data item.
The following rules apply to the rounding behaviour induced by this clause.
@enumerate
@item
Rounding only applies when the result being saved to a receiving field with a @code{ROUNDED} clause is a non-integer value.
@item
Absence of a @code{ROUNDED} clause is the same as specifying @code{ROUNDED MODE IS TRUNCATION}.
@item
Use of a @code{ROUNDED} clause without a @code{MODE} specification is the same as specifying @code{ROUNDED MODE IS NEAREST-AWAY-FROM-ZERO}.
@end enumerate
The behaviour of the eight different rounding modes is defined in the following table. Note that a @samp{@dots{}} indicates the last digit repeats. The examples assume an integer receiving field.
@table @asis
@item @code{AWAY-FROM-ZERO}
Rounding is to the nearest value of larger magnitude.
@multitable @columnfractions .5 .5
@item -3.510 @result{} -4 @tab +3.510 @result{} +4
@item -3.500 @result{} -4 @tab +3.500 @result{} +4
@item -3.499@dots{} @result{} -4 @tab +3.499@dots{} @result{} +4
@item -2.500 @result{} -3 @tab +2.500 @result{} +3
@item -2.499@dots{} @result{} -3 @tab +2.499@dots{} @result{} +3
@end multitable
@item @code{NEAREST-AWAY-FROM-ZERO}
Rounding is to the nearest value (larger or smaller). If two values are equally near, the value with the larger absolute value is selected.
@multitable @columnfractions .5 .5
@item -3.510 @result{} -4 @tab +3.510 @result{} +4
@item -3.500 @result{} -4 @tab +3.500 @result{} +4
@item -3.499@dots{} @result{} -3 @tab +3.499@dots{} @result{} +3
@item -2.500 @result{} -3 @tab +2.500 @result{} +3
@item -2.499@dots{} @result{} -2 @tab +2.499@dots{} @result{} +2
@end multitable
@item @code{NEAREST-EVEN}
Rounding is to the nearest value (larger or smaller). If two values are equally near, the value whose rightmost digit is @i{even} is selected. This mode is sometimes called ``Banker's rounding''.
@multitable @columnfractions .5 .5
@item -3.510 @result{} -4 @tab +3.510 @result{} +4
@item -3.500 @result{} -4 @tab +3.500 @result{} +4
@item -3.499@dots{} @result{} -3 @tab +3.499@dots{} @result{} +3
@item -2.500 @result{} -2 @tab +2.500 @result{} +2
@item -2.499@dots{} @result{} -2 @tab +2.499@dots{} @result{} +2
@end multitable
@item @code{NEAREST-TOWARD-ZERO}
Rounding is to the nearest value (larger or smaller). If two values are equally near, the value with the smaller absolute value is selected.
@multitable @columnfractions .5 .5
@item -3.510 @result{} -4 @tab +3.510 @result{} +4
@item -3.500 @result{} -3 @tab +3.500 @result{} +3
@item -3.499@dots{} @result{} -3 @tab +3.499@dots{} @result{} +3
@item -2.500 @result{} -2 @tab +2.500 @result{} +2
@item -2.499@dots{} @result{} -2 @tab +2.499@dots{} @result{} +2
@end multitable
@item @code{PROHIBITED}
No rounding is performed. If the value cannot be represented exactly in the desired format, the @code{EC-SIZE-TRUNCATION} condition (exception code 1005) is set (and may be retrieved via the @syntaxrefalt{ACCEPT,ACCEPT FROM Runtime-Info} statement) and the results of the operation are undefined.
@multitable @columnfractions .5 .5
@item -3.510 @result{} Undefined @tab +3.510 @result{} Undefined
@item -3.500 @result{} Undefined @tab +3.500 @result{} Undefined
@item -3.499@dots{} @result{} Undefined @tab +3.499@dots{} @result{} Undefined
@item -2.500 @result{} Undefined @tab +2.500 @result{} Undefined
@item -2.499@dots{} @result{} Undefined @tab +2.499@dots{} @result{} Undefined
@end multitable
@item @code{TOWARD-GREATER}
Rounding is toward the nearest value whose algebraic value is larger.
@multitable @columnfractions .5 .5
@item -3.510 @result{} -3 @tab +3.510 @result{} +4
@item -3.500 @result{} -3 @tab +3.500 @result{} +4
@item -3.499@dots{} @result{} -3 @tab +3.499@dots{} @result{} +4
@item -2.500 @result{} -2 @tab +2.500 @result{} +3
@item -2.499@dots{} @result{} -2 @tab +2.499@dots{} @result{} +3
@end multitable
@item @code{TOWARD-LESSER}
Rounding is toward the nearest value whose algebraic value is smaller.
@multitable @columnfractions .5 .5
@item -3.510 @result{} -4 @tab +3.510 @result{} +3
@item -3.500 @result{} -4 @tab +3.500 @result{} +3
@item -3.499@dots{} @result{} -4 @tab +3.499@dots{} @result{} +3
@item -2.500 @result{} -3 @tab +2.500 @result{} +2
@item -2.499@dots{} @result{} -3 @tab +2.499@dots{} @result{} +2
@end multitable
@item @code{TRUNCATION}
Rounding is to the nearest value whose magnitude is smaller.
@multitable @columnfractions .5 .5
@item -3.510 @result{} -3 @tab +3.510 @result{} +3
@item -3.500 @result{} -3 @tab +3.500 @result{} +3
@item -3.499@dots{} @result{} -3 @tab +3.499@dots{} @result{} +3
@item -2.500 @result{} -2 @tab +2.500 @result{} +2
@item -2.499@dots{} @result{} -2 @tab +2.499@dots{} @result{} +2
@end multitable
@end table
@comment *********************************************************************
@comment ** 7.7 Special Registers **
@comment *********************************************************************
@page
@newsection{7.7,Special Registers}
GnuCOBOL, like other COBOL dialects, includes a number of data items that are automatically available to a programmer without the need to actually define them in the data division. COBOL refers to such items as registers or special registers. The special registers available to a GnuCOBOL program are as follows:
@table @asis
@item @code{COB-CRT-STATUS}
PIC 9(4) --- This is the default data item allocated for use by the @statementrefalt{ACCEPT @var{data-item},ACCEPT data-item}, if no @syntaxrefalt{CRT STATUS,SPECIAL-NAMES} clause was specified..
@item @code{DEBUG-ITEM}
Group Item --- A group item in which debugging information generated by a @code{USE FOR DEBUGGING} section in the declaratives area of the procedure division will place information documenting why the @code{USE FOR DEBUGGING} procedure was invoked. Consult the @syntaxref{DECLARATIVES} documentation for information on the structure of this register.
@item @code{LINAGE-COUNTER}
@code{BINARY-LONG SIGNED} --- An occurrence of this register exists for each selected file having a @syntaxrefalt{LINAGE,File/Sort-Description} clause. If there are multiple files whose file descriptions have @code{LINAGE} clauses, any explicit references to this register will require qualification (using @code{OF file-name}). The value of this register will be the current logical line number within the page body. The value of this register cannot be modified.
@item @code{LINE-COUNTER}
@code{BINARY-LONG SIGNED} --- An occurrence of this register exists for each report defined in the program (via an @syntaxrefalt{RD,REPORT SECTION}). If there are multiple reports, any explicit references to this register not made in the report section will require qualification (@code{OF report-name}). The value of this register will be the current logical line number on the current page. The value of this register cannot be modified.
@item @code{NUMBER-OF-CALL-PARAMETERS}
@code{BINARY-LONG SIGNED} --- This register contains the number of arguments passed to a subroutine --- the same value that would be returned by the @subpgmref{C$NARG}. Its value will be zero when referenced in a main program. This register, when referenced from within a user-defined function, returns a value of one (@samp{1}) if the function has any number of arguments and a zero if it has no arguments.
@item @code{PAGE-COUNTER}
@code{BINARY-LONG SIGNED} --- An occurrence of this register exists for each report having an @syntaxrefalt{RD,REPORT SECTION}. If there are multiple such reports, any explicit references to this register not made in the report section will require qualification ( @code{OF report-name}). The value of this register will be the current report page number. The value of this register cannot be modified.
@item @code{RETURN-CODE}
@code{BINARY-LONG SIGNED} --- This register provides a numeric data item into which a subroutine may @syntaxref{MOVE} a value (which will then be available to the calling program) prior to transferring control back to the program that called it, or into which a main program may @code{MOVE} a value before returning control to the operating system. Many built-in subroutines will return a value using this register. These values are --- by convention --- used to signify success (usually with a value of 0) or failure (usually with a non-zero value) of the process the program was attempting to perform. This register may also be modified by a subprogram as a result of that subprogram's use of the @syntaxrefalt{RETURNING,PROCEDURE DIVISION RETURNING} clause.
@item @code{SORT-RETURN}
@code{BINARY-LONG SIGNED} --- This register is used to report the success/fail status of a @syntaxref{RELEASE} or @syntaxref{RETURN} statement. A value of 0 is reported on success. A value of 16 denotes failure. An @syntaxrefalt{AT END,AT END + NOT AT END} condition on a @code{RETURN} is not considered a failure.
@item @code{WHEN-COMPILED}
@code{PIC X(16)} --- This register contains the date and time the program was compiled in the format @samp{mm/dd/yyhh.mm.ss}. Note that only a two-digit year is provided.
@end table
@comment * 1.3.21: LENGTH OF.
@comment *********************************************************************
@comment ** 1.3.21 LENGTH OF **
@comment *********************************************************************
@comment @newsubsection{1.3.21,LENGTH OF}
@page
@diagram{LENGTH OF,PD-LENGTH-OF,PD-LENGTH-OF,None}
Alphanumeric literals and identifiers may optionally be prefixed with the @code{LENGTH OF} clause. The compile-time value generated by this clause will be the number of bytes in the alphanumeric literal or the defined size (in bytes) of the identifier.
@enumerate
@item
The reserved word @code{OF} is optional and may be omitted. The presence or absence of this word has no effect upon the program.
Here is an example. The following two GnuCOBOL statements both display the same result (27):
@example
01 Demo-Identifier PIC X(27).
...
DISPLAY LENGTH OF "This is a LENGTH OF Example"
DISPLAY LENGTH OF Demo-Identifier
@end example
@item
The @code{LENGTH OF} clause on a literal or identifier reference may generally be used anywhere a numeric literal might be specified, with the following exceptions:
@itemize @bullet
@item
As part of the @code{FROM} clause of a @syntaxref{WRITE} or @statementref{RELEASE}.
@item
As part of the @code{TIMES} clause of a @statementref{PERFORM}.
@end itemize
@end enumerate
@comment *********************************************************************
@comment ** 7.8 GnuCOBOL Statements **
@comment *********************************************************************
@page
@newsection{7.8,GnuCOBOL Statements}
@comment The following menu is hidden in html mode because it makes
@comment makeinfo segfault on some Linux distributions, and it is not
@comment actually necessary in html mode.
@iftex
@menu
* 7.8.1: ACCEPT
@detailmenu
* 7.8.1.1: ACCEPT FROM CONSOLE
* 7.8.1.2: ACCEPT FROM COMMAND-LINE
* 7.8.1.3: ACCEPT FROM ENVIRONMENT
* 7.8.1.4: ACCEPT Data-Item
* 7.8.1.5: ACCEPT FROM DATE/TIME
* 7.8.1.6: ACCEPT FROM Screen-Info
* 7.8.1.7: ACCEPT FROM Runtime-Info
* 7.8.1.8: ACCEPT OMITTED
* 7.8.1.9: ACCEPT FROM EXCEPTION STATUS
@end detailmenu
* 7.8.2: ADD
@detailmenu
* 7.8.2.1: ADD TO
* 7.8.2.2: ADD GIVING
* 7.8.2.3: ADD CORRESPONDING
@end detailmenu
* 7.8.3: ALLOCATE
* 7.8.4: ALTER
* 7.8.5: CALL
* 7.8.6: CANCEL
* 7.8.7: CLOSE
* 7.8.8: COMMIT
* 7.8.9: COMPUTE
* 7.8.10: CONTINUE
* 7.8.11: DELETE
* 7.8.12: DISPLAY
@detailmenu
* 7.8.12.1: DISPLAY UPON device
* 7.8.12.2: DISPLAY UPON COMMAND-LINE
* 7.8.12.3: DISPLAY UPON ENVIRONMENT-NAME
* 7.8.12.4: DISPLAY data-item
* 7.8.12.5: DISPLAY data-item (Microsoft v1, 2)
@end detailmenu
* 7.8.13: DIVIDE
@detailmenu
* 7.8.13.1: DIVIDE INTO
* 7.8.13.2: DIVIDE INTO GIVING
* 7.8.13.3: DIVIDE BY GIVING
@end detailmenu
* 7.8.14: ENTRY
* 7.8.15: EVALUATE
* 7.8.15B: EXAMINE
* 7.8.16: EXHIBIT
* 7.8.17: EXIT
* 7.8.18: FREE
* 7.8.19: GENERATE
* 7.8.20: GOBACK
* 7.8.21: GO TO
@detailmenu
* 7.8.21.1: Simple GO TO
* 7.8.21.2: GO TO DEPENDING ON
@end detailmenu
* 7.8.22: IF
* 7.8.23: INITIALIZE
* 7.8.24: INITIATE
* 7.8.25: INSPECT
* 7.8.26: MERGE
* 7.8.27: MOVE
@detailmenu
* 7.8.27.1: Simple MOVE
* 7.8.27.2: MOVE CORRESPONDING
@end detailmenu
* 7.8.28: MULTIPLY
@detailmenu
* 7.8.28.1: MULTIPLY BY
* 7.8.28.2: MULTIPLY GIVING
@end detailmenu
* 7.8.29: OPEN
* 7.8.30: PERFORM
@detailmenu
* 7.8.30.1: Procedural PERFORM
* 7.8.30.2: Inline PERFORM
@end detailmenu
* 7.8.31: READ
@detailmenu
* 7.8.31.1: Sequential READ
* 7.8.31.2: Random READ
@end detailmenu
* 7.8.32: READY TRACE
* 7.8.33: RELEASE
* 7.8.34: RESET TRACE
* 7.8.35: RETURN
* 7.8.36: REWRITE
* 7.8.37: ROLLBACK
* 7.8.38: SEARCH
* 7.8.39: SEARCH ALL
* 7.8.40: SET
@detailmenu
* 7.8.40.1: SET ENVIRONMENT
* 7.8.40.2: SET Program-Pointer
* 7.8.40.3: SET ADDRESS
* 7.8.40.4: SET Index
* 7.8.40.5: SET UP/DOWN
* 7.8.40.6: SET Condition Name
* 7.8.40.7: SET Switch
* 7.8.40.8: SET ATTRIBUTE
* 7.8.40.9: SET LAST EXCEPTION
@end detailmenu
* 7.8.41: SORT
@detailmenu
* 7.8.41.1: File-Based SORT
* 7.8.41.2: Table SORT
@end detailmenu
* 7.8.42: START
* 7.8.43: STOP
* 7.8.44: STRING
* 7.8.45: SUBTRACT
@detailmenu
* 7.8.45.1: SUBTRACT FROM
* 7.8.45.2: SUBTRACT GIVING
* 7.8.45.3: SUBTRACT CORRESPONDING
@end detailmenu
* 7.8.46: SUPPRESS
* 7.8.47: TERMINATE
* 7.8.48: TRANSFORM
* 7.8.49: UNLOCK
* 7.8.50: UNSTRING
* 7.8.51: WRITE
@end menu
@end iftex
@comment *********************************************************************
@comment ** 7.8.1 ACCEPT **
@comment *********************************************************************
@newsubsection{7.8.1,ACCEPT}
@menu
* 7.8.1.1: ACCEPT FROM CONSOLE
* 7.8.1.2: ACCEPT FROM COMMAND-LINE
* 7.8.1.3: ACCEPT FROM ENVIRONMENT
* 7.8.1.4: ACCEPT data-item
* 7.8.1.5: ACCEPT FROM DATE/TIME
* 7.8.1.6: ACCEPT FROM Screen-Info
* 7.8.1.7: ACCEPT FROM Runtime-Info
* 7.8.1.8: ACCEPT OMITTED
* 7.8.1.9: ACCEPT FROM EXCEPTION STATUS
@end menu
@comment *********************************************************************
@comment ** 7.8.1.1 ACCEPT FROM CONSOLE **
@comment *********************************************************************
@newunit{7.8.1.1,ACCEPT FROM CONSOLE}
@diagram{ACCEPT FROM CONSOLE,PD-ACCEPT-1,PD-ACCEPT-1,None}
This format of the @statement{ACCEPT} is used to read a value from the console window or the standard input device and store it into a data item (@var{identifier-1}).
@enumerate
@comment Syntactical Specifications:
@item
If no @code{FROM} clause is specified, @code{FROM CONSOLE} is assumed.
@comment Semantic Specifications:
@item
The specified @var{mnemonic-name-1} must either be one of the built-in device names @code{CONSOLE}, @code{STDIN}, @code{SYSIN} or @code{SYSIPT}, or a user-defined (@pxref{SPECIAL-NAMES}) mnemonic name @i{attached} to one of those four device names.
@item
Input will be read either from the console window (@code{CONSOLE}) or from the system-standard input (pipe 0 = @code{STDIN}, @code{SYSIN} or @code{SYSIPT}) and will be saved in @var{identifier-1}.
@item
If @var{identifier-1} is a numeric data item, the character value read from the console or standard-input device will be parsed according to the rules for input to the @intrinsicref{NUMVAL}, except that none of the trailing sign formats are honoured.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.1.2 ACCEPT FROM COMMAND-LINE **
@comment *********************************************************************
@page
@newunit{7.8.1.2,ACCEPT FROM COMMAND-LINE}
@diagram{ACCEPT FROM COMMAND-LINE,PD-ACCEPT-2,PD-ACCEPT-2,None}
This format of the @statement{ACCEPT} is used to retrieve information from the program's command line.
@enumerate
@comment Syntactical Specifications:
@item
The reserved word @code{ON} is optional and may be omitted. The presence or absence of this word has no effect upon the program.
@comment Semantic Specifications:
@item
When you accept from the
@syntaxidx{COMMAND-LINE} option, you will retrieve the entire set of arguments entered on the command line that executed the program, exactly as they were specified. Parsing that returned data into its meaningful information will be your responsibility.
@item
Using @code{COMMAND-LINE} or @code{ARGUMENT-VALUE} in a *nix based platform and that includes Linux, OSX, BSD and under windows running msys or MinGW etc, the shell process will expand any arguments that have a @samp{*} in the list --- such as @samp{a*}, @samp{abc*.*}, etc. --- and create a list of all files that match the pattern. To avoid this if not wanted, put all such argument within quotes, @i{e.g.}, @code{progundertest "a*" b c d "ef*" "*hg"} and the text within quotes will be passed verbatim to the program (as in the example @command{progundertest}).
@item
By accepting from
@syntaxidx{ARGUMENT-NUMBER}, you will be asking the GnuCOBOL run-time system to parse the arguments from the command line and return the number of arguments found. Parsing will be conducted according to the following rules:
@enumerate A
@item
Arguments will be separated by treating spaces and/or tab characters as the delimiters between arguments. The number of such delimiters separating two non-blank argument values is irrelevant.
@item
Strings enclosed in double-quote characters (@samp{"}) will be treated as a single argument, regardless of how many spaces or tab characters (if any) might be embedded within the quotation characters.
@item
On Windows systems, single-quote, or apostrophe, characters (@samp{'}) will be treated just like any other data character and will @i{not} delineate argument strings.
@end enumerate
@item
By accepting from
@syntaxidx{ARGUMENT-VALUE}, you will be asking the GnuCOBOL run-time system to parse the arguments from the command line and return the ``current'' argument. You specify which argument number is ``current'' via the @code{ARGUMENT-NUMBER} option on the @statementrefalt{DISPLAY,DISPLAY UPON COMMAND-LINE}. Parsing of arguments will be conducted according to the rules set forth above.
@item
The optional @code{ON EXCEPTION} and @code{NOT ON EXCEPTION} clauses may be used to detect and react to the failure or success, respectively, of an attempt to retrieve an @code{ARGUMENT-VALUE}. @xref{ON EXCEPTION + NOT ON EXCEPTION}, for additional information.
@end enumerate
@comment *********************************************************************
@comment ** 7.8.1.3 ACCEPT FROM ENVIRONMENT **
@comment *********************************************************************
@page
@newunit{7.8.1.3,ACCEPT FROM ENVIRONMENT}
@diagram{ACCEPT FROM ENVIRONMENT,PD-ACCEPT-3,PD-ACCEPT-3,None}
This format of the @statement{ACCEPT} is used to retrieve environment variable values.
@enumerate
@comment Syntactical Specifications:
@item
The reserved word @code{ON} is optional and may be omitted. The presence or absence of this word has no effect upon the program.
@comment Semantic Specifications:
@item
By accepting from
@syntaxidx{ENVIRONMENT-VALUE}, you will be asking the GnuCOBOL run-time system to retrieve the value of the environment variable whose name is currently in the
@syntaxidx{ENVIRONMENT-NAME} register. A value may be placed into the @code{ENVIRONMENT-NAME} register using the @code{ENVIRONMENT-NAME} option of the @statementrefalt{DISPLAY,DISPLAY UPON ENVIRONMENT-NAME}.
@item
A simpler approach to retrieving an environment variables value is to use the
@syntaxidx{ENVIRONMENT} option, where you specify the environment variable whose value is to be retrieved right on the @code{ACCEPT} statement itself.
@item
The optional @code{ON EXCEPTION} and @code{NOT ON EXCEPTION} clauses may be used to detect and react to an attempt to retrieve the value of a non-existent environment variable or the successful retrieval of an environment variable's value, respectively. @xref{ON EXCEPTION + NOT ON EXCEPTION}, for additional information.
@end enumerate
@comment ********************************************************************
@comment ** 7.8.1.4 ACCEPT data-item **
@comment ********************************************************************
@page
@newunit{7.8.1.4,ACCEPT data-item}
@diagram{ACCEPT data-item,PD-ACCEPT-4,PD-ACCEPT-4,PD-ACCEPT-4}
This format of the @statement{ACCEPT} is used to retrieve data from a working storate item or a formatted console window screen.
@enumerate
@comment Syntactical Specifications:
@item
The reserved words @code{AFTER}, @code{IS}, @code{NUMBER} and @code{ON} are optional and may be omitted. The presence or absence of these words has no effect upon the program.
@item
The reserved words @code{COLUMN}, @code{COL} and @code{POSITION} are interchangeable.
@item
The reserved words @code{TIMEOUT} and @code{TIME-OUT} are interchangeable.
@comment Semantic Specifications:
@item
If @var{identifier-1} is defined in the @syntaxref{SCREEN SECTION}, any @code{AT}, @var{Attribute-Specification}, @code{LOWER}, @code{UPPER} or @code{SCROLL} clauses will be ignored. In these cases, an implied @syntaxrefalt{DISPLAY,DISPLAY data-item} of @var{identifier-1} will occur before input is accepted. Coding an explicit @code{DISPLAY identifier-1} before an @code{ACCEPT identifier-1} is redundant and will incur the performance penalty of painting the screen contents twice.
@item
The various @code{AT} clauses provide a means of positioning the cursor to a specific spot on the screen before the screen is read. One or the other (but not both) may be used, as follows:
@enumerate A
@item
The @code{LINE} and @code{COLUMN} clauses provide one mechanism for specifying the line and column position to which the cursor will be positioned before allowing the user to enter data. In the absence of one or the other, a value of 1 will be assumed for the one that is missing. The author's personal preference, however, is to explicitly code both.
@item
The @var{literal-3} or @var{identifier-4} value, if specified, must be a four- or six-digit value with the 1@sup{st} half of the number indicating the line where the cursor should be positioned and the second half indicating the column. You may code only one of each clause on any @code{ACCEPT}.
@end enumerate
@item
@code{WITH} options (including the various individual @var{Attribute-Specifications}) should be coded only once.
@item
The following @var{Attribute-Specification} clauses are allowed on the @code{ACCEPT} statement; these are the same as those allowed for @code{SCREEN SECTION} data items. A particular @var{Attribute-Specification} may be used only once in any @code{ACCEPT}:
@itemize @bullet
@item
@syntaxref{AUTO}, @syntaxref{AUTO-SKIP}, @syntaxref{AUTOTERMINATE}, @code{TAB}
@item
@syntaxref{BACKGROUND-COLOR}
@item
@syntaxref{BEEP}, @syntaxref{BELL}
@item
@syntaxref{BEFORE TIME}
@item
@syntaxref{BLINK}
@item
@syntaxref{FOREGROUND-COLOR}
@item
@syntaxref{FULL}, @syntaxref{LENGTH-CHECK}
@item
@syntaxref{HIGHLIGHT}
@item
@syntaxref{LEFTLINE}
@item
@syntaxref{LOWER}
@item
@syntaxref{LOWLIGHT}
@item
@syntaxref{NO UPDATE}
@item
@syntaxref{OVERLINE}
@item
@syntaxref{PROMPT}
@item
@syntaxref{PROTECTED}
@item
@syntaxref{REQUIRED}, @syntaxref{EMPTY-CHECK}
@item
@syntaxref{REVERSE-VIDEO}
@item
@syntaxref{SCROLL DOWN}
@item
@syntaxref{SCROLL UP}
@item
@syntaxref{SIZE}
@item
@syntaxref{SECURE}, @syntaxref{NO-ECHO}
@item