The ACCEPT statement makes low-volume data available to the program. See
Common Screen Options for more information on many of the optional clauses shown below.
The different forms of the ACCEPT statement perform the following functions:
- Format 1, ACCEPT (an individual field)
- Format 2, ACCEPT (a Screen Section item, one or more fields)
- Format 3, ACCEPT FROM (returns selected data from the operating environment)
- Format 4 , ACCEPT SCREEN
(accepts data found on screen)
- Format 5, ACCEPT ENVIRONMENT (accepts value of variable from user's environment or from ACUCOBOL-GT's runtime configuration settings)
- Format 6, ACCEPT (ANSI style)
- Format 7, ACCEPT (activates a specific control)
- Format 8, ACCEPT (accepts HTML forms)
- Format 9, ACCEPT EVENT (accepts an
event)
- Format 10, ACCEPT (HP COBOL)
- Format 11, ACCEPT (HP COBOL)
- Format 12, ACCEPT (HP COBOL)
- Format 13, ACCEPT FROM ENVIRONMENT-VALUE (returns the value of the special register ENVIRONMENT-NAME)
Depending on the Format and options used, an ACCEPT statement can return the following predefined exception values. The numbers
listed here are the actual values that are returned. Exception values can be found in the file
acugui.def. The names given here are the level 78 data items found in that file.
|
95 W-MESSAGE
|
- message received
(ACCEPT ALLOWING MESSAGES)
|
|
96 W-EVENT
|
- ACCEPT terminated by an event
|
|
97 W-NO-FIELDS
|
- no input fields, or all fields protected or hidden
|
|
98 W-CONVERSION-ERROR
|
- numeric conversion error
|
|
99 W-TIMEOUT
|
- ACCEPT timed out
(ACCEPT BEFORE TIME)
|
Note that ACCEPT works differently on Windows and character-based systems. In Windows, an entry field is automatically in
insert mode—that is, typing characters moves other characters instead of overwriting them. In character-based systems, entry
fields start in overwrite mode, so typing new characters overwrites characters that already exist.
Format 1
ACCEPT {dest-item}
{OMITTED }
Remaining phrases are optional, can appear in any order.
AT screen-loc
{FROM} LINE NUMBER line-num
{AT }
{FROM} {COLUMN } NUMBER col-num
{AT } {COL }
{POSITION}
{POS }
WITH PROTECTED SIZE length
WITH NO ADVANCING
{ERASE} [TO END OF] {LINE } (VAX, ICOBOL)
{BLANK} {SCREEN}
{ERASE} [EOS] (RM)
{BLANK} [EOL]
WITH [NO] {BELL}
{BEEP}
{UNDERLINE }
{UNDERLINED}
WITH {BLINKING}
{BLINK }
{HIGHLIGHT}
{HIGH }
{BOLD }
{LOWLIGHT }
{LOW }
{STANDARD }
{REVERSE-VIDEO}
{REVERSE }
{REVERSED }
SAME
WITH {COLOR } color-val
{COLOUR}
{FOREGROUND-COLOR } IS fg-color
{FOREGROUND-COLOUR}
{BACKGROUND-COLOR } IS bg-color
{BACKGROUND-COLOUR}
SCROLL [UP ] [ BY scrl-num {LINE } ]
[DOWN] {LINES}
OUTPUT {JUSTIFIED} {LEFT }
{JUST } {RIGHT }
{CENTERED}
WITH {CONVERSION}
{CONVERT }
{WITH NO ECHO}
{NO-ECHO }
{SECURE }
{OFF }
PROMPT [ CHARACTER IS prompt-lit ]
{DEFAULT [IS default]}
{UPDATE }
ECHO
{AUTO }
{AUTO-SKIP }
{AUTOTERMINATE}
{TAB }
{UPPER}
{LOWER}
CURSOR curs-offset
CONTROL cntrl-string
{REQUIRED }
{EMPTY-CHECK}
{FULL }
{LENGTH-CHECK}
{ZERO-FILL }
{NUMERIC-FILL}
CONTROL KEY IN key-dest
BEFORE TIME timeout
ALLOWING MESSAGES FROM { THREAD thread-1 }
{ LAST THREAD }
{ ANY THREAD }
[ { ON EXCEPTION [key-dest] } {statement-1 } ]
{ ON ESCAPE [key-dest] } {NEXT SENTENCE}
{ AT END }
[ NOT { ON EXCEPTION } statement-2 ]
{ ON ESCAPE }
{ AT END }
[ END-ACCEPT ]
Format 2
ACCEPT screen-name
Remaining phrases are optional, can appear in any order.
AT screen-loc
{FROM} LINE NUMBER line-num
{AT }
{FROM} {COLUMN } NUMBER col-num
{AT } {COL }
{POSITION}
{POS }
BEFORE TIME timeout
ALLOWING MESSAGES FROM { THREAD thread-1 }
{ LAST THREAD }
{ ANY THREAD }
[ UNTIL condition-1 ]
[ ON {EXCEPTION} statement-1 ]
{ESCAPE }
[ NOT ON {EXCEPTION} statement-2 ]
{ESCAPE }
[ END-ACCEPT ]
Format 3
ACCEPT dest-item FROM {DATE }
{DAY }
{CENTURY-DATE }
{DATE YYYYMMDD }
{CENTURY-DAY }
{DAY YYYYDDD }
{TIME }
{MICROSECOND-TIME }
{DAY-OF-WEEK }
{TERMINAL-INFO }
{SYSTEM-INFO }
{INPUT STATUS }
{ESCAPE KEY }
{LINE NUMBER }
{COMMAND-LINE }
{STANDARD OBJECT object-name}
{THREAD HANDLE }
{WINDOW HANDLE }
Format 4
ACCEPT dest-item FROM SCREEN
Remaining phrases are optional, can appear in any order.
AT screen-loc
{FROM} LINE NUMBER line-num
{AT }
{FROM} {COLUMN } NUMBER col-num
{AT } {COL }
{POSITION}
SIZE length
Format 5
ACCEPT dest-item FROM {CONFIGURATION} env-name
{ENVIRONMENT }
[ ON EXCEPTION statement-1 ]
[ NOT ON EXCEPTION statement-2 ]
[ END-ACCEPT ]
Format 6
ACCEPT dest-item [ FROM mnemonic-name ]
Format 7
ACCEPT {control-handle}
{CONTROL }
Remaining phrases are optional, can appear in any order.
VALUE IN [ MULTIPLE ] value
AT screen-loc [CELL ]
[CELLS ]
[PIXEL ]
[PIXELS]
AT LINE NUMBER line-num [CELL ]
[CELLS ]
[PIXEL ]
[PIXELS]
AT {COLUMN } NUMBER col-num [CELL ]
{COL } [CELLS ]
{POSITION} [PIXEL ]
{POS } [PIXELS]
AT CLINE NUMBER cline-num [CELL ]
[CELLS]
AT CCOL NUMBER ccol-num [CELL ]
[CELLS]
WITH {BELL}
{BEEP}
BEFORE TIME timeout
CONTROL KEY IN key-dest
ALLOWING MESSAGES FROM { THREAD thread-1 }
{ LAST THREAD }
{ ANY THREAD }
ON {EXCEPTION} [key-dest] statement-1
{ESCAPE }
NOT ON {EXCEPTION} statement-2
{ESCAPE }
END-ACCEPT
Format 8
ACCEPT external-form-item
Format 9
ACCEPT EVENT
Remaining phrases are optional.
BEFORE TIME timeout
ALLOWING MESSAGES FROM { THREAD thread-1 }
{ LAST THREAD }
{ ANY THREAD }
[ { ON EXCEPTION [code-dest] } {statement-1 } ]
{ ON ESCAPE [code-dest] } {NEXT SENTENCE}
{ AT END }
[ NOT { ON EXCEPTION } statement-2 ]
{ ON ESCAPE }
{ AT END }
[ END-ACCEPT ]
Format 10 (HP COBOL)
ACCEPT identifier [FREE] [FROM { SYSIN }]
{ CONSOLE }
{ mnemonic-name }
Format 11 (HP COBOL)
ACCEPT identifier FREE [FROM { SYSIN }]
{ CONSOLE }
{ mnemonic-name }
[ON INPUT ERROR imperative-statement-1]
[NOT ON INPUT ERROR imperative-statement-2]
[END-ACCEPT]
Format 12 (HP COBOL)
ACCEPT identifier FROM { DATE }
{ DAY }
{ DAY-OF-WEEK }
{ TIME }
Format 13
ACCEPT value FROM ENVIRONMENT-VALUE
Syntax Rules
Note: For Syntax Rules and General Rules specific to Formats 10, 11, and 12, see
HP COBOL Conversions, in
Transitioning to ACUCOBOL-GT.
- dest-item is a data item that receives the accepted data. It must be USAGE DISPLAY unless the WITH CONVERSION phrase is also used.
If the Format 3 STANDARD OBJECT, THREAD HANDLE, or WINDOW HANDLE phrase is used,
dest-item must be a USAGE HANDLE data item of the appropriate type. If the WINDOW HANDLE phrase is used,
dest-item can also be a PIC X(10) item.
- screen-name is the name of a screen entry declared in the program's Screen Section. See
Screen Section for more information.
- screen-loc is a numeric literal or data item containing either 4 or 6 digits. It may also be a group item of 4 or 6 characters. If a
numeric item is used, it must be a non-negative integer.
- In Format 7, the AT, LINE, COLUMN, CLINE, and CCOL phrases may be used only if the CONTROL phrase is also used.
- line-num,
col-num,
cline-num, and
col-num are numeric data items or literals. Note that they may be non-integer, unless the value is in pixels.
- length,
color-val,
curs-offset,
timeout, and
scrl-num are numeric literals or data items. They must specify non-negative integers. You may also specify the value of
line-num,
col-num,
length, and
color-val with an arithmetic expression.
- fg-color and
bg-color are integer literals or numeric data items. They may be arithmetic expressions. They may not be subscripted or reference
modified. See
FOREGROUND-COLOR and BACKGROUND-COLOR Phrases, for a more detailed discussion of color settings and values.
- prompt-lit is a single-character alphanumeric literal or the figurative constant SPACE, ZERO, or QUOTE.
- Default is a literal or data item. It specifies the default entry value.
- Key-dest is a numeric data item. It receives the value of the key that terminated input.
- thread-1 is a USAGE HANDLE or HANDLE OF THREAD data item.
- statement-1 and
statement-2 are any imperative statements.
- condition-1 is any conditional expression.
- cntrl-string and
env-name are nonnumeric literals or data items.
- mnemonic-name must be a user-defined word declared in Special-Names that refers to a display device, or it must be the name of the display
device itself. See
Special-Names Paragraph for a list of valid devices.
- object-name must be an alphanumeric literal or data item.
- control-handle must be USAGE HANDLE. If
control-handle is a typed handle, it must be associated with a control. It should hold a handle returned by a DISPLAY Control-Type (Format
14) statement.
- value can be any data item. It receives the current value of the control when the ACCEPT statement terminates.
- code-dest is a numeric data item.
- If the AT phrase is specified, neither the LINE nor the COLUMN phrase may be specified.
- If the COLOR phrase is specified, neither the FOREGROUND-COLOR nor the BACKGROUND-COLOR phrase may be specified.
- The CURSOR phrase may not be specified if a CURSOR phrase is specified in the program's Configuration Section.
- AUTO, AUTO-SKIP, and AUTOTERMINATE are equivalent.
- NO-ECHO, NO ECHO, OFF, and SECURE are equivalent.
- BLANK and ERASE are equivalent.
- BOLD, HIGH, and HIGHLIGHT are equivalent.
- LOWLIGHT and LOW are equivalent.
- COLUMN, COL, POSITION, and POS are equivalent.
- BELL and BEEP are equivalent.
- REVERSE-VIDEO, REVERSE, and REVERSED are equivalent.
- BLINK and BLINKING are equivalent.
- UNDERLINE and UNDERLINED are equivalent.
- CONVERSION and CONVERT are equivalent.
- REQUIRED and EMPTY-CHECK are equivalent.
- FULL and LENGTH-CHECK are equivalent.
- EXCEPTION and ESCAPE are equivalent.
- If the OMITTED option is used, then none of the following phrases may be specified: SIZE, JUSTIFIED, CONVERT, NO ECHO, PROMPT,
DEFAULT, ECHO, UPPER, LOWER, REQUIRED, FULL, ZERO-FILL, NUMERIC-FILL or any of the attribute setting phrases (such as COLOR
or REVERSE).
- The ERASE phrase has two forms. In VAX COBOL and ICOBOL compatibility modes, the ERASE LINE/SCREEN form must be used. In RM/COBOL
mode, the ERASE EOS/EOL form must be used. This is indicated in the General Format by the symbols
(VAX, ICOBOL) and
.
- A NOT AT END phrase may not be paired with an ON EXCEPTION phrase, nor may a NOT ON EXCEPTION phrase be paired with an AT
END phrase.
- In a Format 6 ACCEPT statement, if you omit the FROM phrase, you must use the
-Ca compile-time option. Otherwise, the compiler treats the statement as a Format 1 ACCEPT instead.
- If the CONTROL KEY phrase is used, the key-dest option of the ON EXCEPTION phrase may not be specified.
- You may add FROM CRT to a Format 1 ACCEPT statement to distinguish it from a Format 6 ACCEPT statement. You need to do this
only if you use the
-Ca compile-time option.
- external-form-item is an input record for an HTML form when used in a Common Gateway Interface (CGI) program. It is a group data item (declared
with the IS EXTERNAL-FORM clause) that has one or more elementary items associated with CGI variables. The association is
made with the IS IDENTIFIED BY clause in the description of the elementary item(s).
External-form-item may also be an output record for an HTML form. In this case, the group item is declared with both the IS
EXTERNAL-FORM and IDENTIFIED BY clauses.
See the IS EXTERNAL-FORM clause for more information about declaring external forms.
- For Format 13, value is a Working-Storage data item of the type needed to receive the value of the environment or configuration
value stored in ENVIRONMENT-NAME (see DISPLAY Format 17).
General Rules Format 1 (ACCEPT dest-item)
- The ACCEPT statement accepts data typed by the user. The data accepted is placed in
dest-item. If the OMITTED option is used instead of
dest-item, then the user is required to enter a termination key, and no data is transmitted to the program. This can be used if you
want to enter a function key only and do not need any other data from the user.
- The precise action of the ACCEPT statement depends both on the various clauses specified and the compatibility mode that the
compiler is using. The compiler is run in RM/COBOL, VAX COBOL, or ICOBOL compatibility mode.
- Use of the AUTO phrase causes a field to terminate as soon as it is filled with data--this is the default mode in RM COBOL.
Use of the TAB phrase forces the user to finish with a termination key--this is the standard mode except for RM COBOL.
The effects of the CURSOR, CONTROL KEY, BEFORE TIME, ALLOWING MESSAGES, ON EXCEPTION, and AT END clauses are described below.
The effects of the remaining optional clauses are described in section
Common Screen Options.
CURSOR Phrase
- The CURSOR phrase specifies the initial cursor offset from the beginning of the field. The leftmost position of the ACCEPT
field is offset one. If the CURSOR phrase is omitted or zero, then an offset of one is used.
- The offset specified is reduced as needed to keep the cursor in the bounds of the field. Also, the offset is reduced to keep
the cursor within the data contained in the field. This means that an offset of one will always be used if the DEFAULT (or
UPDATE) phrase is not used.
- If
curs-offset is a numeric data item, then the ending cursor offset will be assigned to it when the ACCEPT statement terminates. This can
be used to find the current cursor location (field column +
curs-offset - 1).
- If a CURSOR clause is specified in the program's Configuration Section, then that clause is used to determine the cursor's
initial offset. See
Special-Names Paragraph for details.
CONTROL KEY Phrase
- The CONTROL KEY clause allows for the entry of special keys and the recording of which key terminated input. When the CONTROL
KEY clause is specified, all of the special keys named in the following table can be used.
- key-dest is a numeric item that receives the value of the key that terminated input. The keys allowed by the CONTROL KEY phrase and
their returned values are:
| Key
|
Value
|
Key
|
Value
|
| Enter/Return
|
13
|
F-13
|
13*
|
| Tab
|
9
|
F-14
|
14*
|
| F-1
|
1*
|
F-15
|
15*
|
| F-2
|
2*
|
F-16
|
16*
|
| F-3
|
3*
|
F-17
|
17*
|
| F-4
|
4*
|
F-18
|
18*
|
| F-5
|
5*
|
F-19
|
19*
|
| F-6
|
6*
|
F-20
|
20*
|
| F-7
|
7*
|
Do (Command)
|
40*
|
| F-8
|
8*
|
Up Arrow
|
52*
|
| F-9
|
9*
|
Down Arrow
|
53*
|
| F-10
|
10*
|
Page Up
|
67*
|
| F-11
|
11*
|
Page Down
|
68*
|
| F-12
|
12*
|
Help
|
90*
|
Control keys may also be used. They return their underlying ASCII value (for example, Control-B returns the value 2). If a
field is entered in AUTO mode and the ACCEPT terminates because the field was filled with data, then key-dest receives the
value zero. If the BEFORE TIME phrase is specified and a time-out occurs, then key-dest receives the value
99.
- The keys marked with "*" are exception keys. These keys may be used only if a CONTROL KEY or ON EXCEPTION phrase is specified
for the ACCEPT statement (alternately, the
-Vx compile-time option can be used). If these keys are not allowed, then the runtime system will ignore them when they are typed.
Note that if you use the
-Ve compile-time option to disable the ON EXCEPTION phrase for exception keys, then using the ON EXCEPTION phrase will not enable
exception keys. (See also rule number 2 under ALLOWING MESSAGES Phrase.)
- By using the
-Ve compile-time option, you can cause ACUCOBOL-GT to return numeric conversion errors to the program. If you use this option
to enable program handling of conversion errors, then key-dest will be assigned the value
98 whenever a conversion error occurs. See
CHECK-NUMBERS for more information.
- For compatibility with programs written under other systems, the values returned by these keys may be changed at runtime.
Also, other keys may be added or removed from this table. See
Redefining the Keyboard for details on how to do this.
BEFORE TIME Phrase
- The BEFORE TIME phrase allows you to automatically terminate an ACCEPT statement after a certain amount of time has passed.
The timeout value specifies the time to wait in hundredths of a second. For example,
BEFORE TIME 500 specifies a timer value of 5 seconds.
- The user must enter data to the ACCEPT statement before the timer elapses. As soon as the user starts entering data, the timer
is canceled and the user may take as much time as desired to complete the entry. If the user does not enter any data before
the timer elapses, then the ACCEPT statement terminates and returns a value exactly as if the user had typed the "enter" key.
An exception condition is then raised and the exception key value is set to
99.
- The precise amount of time waited can vary significantly from machine to machine. Factors involved include the rate of the
system clock and the current load on the machine. For example, some UNIX systems update the system clock only once every second.
The ACUCOBOL-GT runtime system takes the specified value and rounds it up to a whole number of
ticks of the system clock. It then calls the system's alarm mechanism to interrupt the ACCEPT after this many
ticks have elapsed. Different operating systems will handle this interrupt with varying degrees of accuracy. You should think of
the timeout value as only an approximate one.
Note: If you want to program a task that executes at a regular interval, such as updating an on-screen clock, it is best to program
the task in a separate thread (as opposed to timing out all of your ACCEPT statements). The periodic task would be placed
inside a loop in a separate thread. The task would sleep for some period, wake and perform the update, and then loop back
to the sleep state. This approach allows the runtime's thread manager to schedule the update, and ensures that no input, such
as a mouse click, is missed when the update takes place. For more about threads, see
Multiple Execution Threads.
ALLOWING MESSAGES Phrase
- The ALLOWING MESSAGES phrase causes the ACCEPT statement to terminate when a message is sent from the appropriate thread,
as follows:
- The THREAD
thread-1 option allows messages from the thread identified by
thread-1.
- The LAST THREAD option allows for messages from the "last" thread. See
Thread Fundamentals for a discussion of the last thread.
- The ANY THREAD option allows messages from any thread.
- If an allowed message is available when the ACCEPT begins, or one arrives while the ACCEPT is active, the ACCEPT terminates
with an exception value of
95. The exception occurs even if exceptions are not otherwise allowed in the ACCEPT.
- When an ACCEPT terminates due to a message, the target data item is not updated with the data entered by the user up to that
point. This affects the following cases:
- In Format 1,
dest-item is not updated.
- In Format 2, any VALUE, USING, or TO data items in the Screen Section are not updated.
- In Format 7,
value is not updated.
Note: Testing of the data item is not performed (such as the REQUIRED phrase). Essentially, you get the termination status, but
no other information. This allows you to share a data item between two controls. When the user changes one of them, it can
send a message to the other to have that control update its appearance. If this rule was not in place, the message would terminate
any ACCEPT on that control, and that control's current contents would overwrite the correct data in the shared data item.
If you need to determine the current value of a control in response to a message, you can INQUIRE the control's value directly.
- An ACCEPT statement that is suspended (because another thread has an active ACCEPT) terminates when an allowed message arrives.
- If the ALLOWING MESSAGES phrase is omitted, messages will not terminate the ACCEPT. Instead, they are queued as normal.
ON EXCEPTION Phrase
Note: The
-Ve compiler option alters the rules that determine which conditions cause an ON EXCEPTION phrase to receive control in a Format
1 ACCEPT statement. See
Video Options for more information.
- When this phrase is used,
statement-1 is executed when an exception condition occurs. An exception condition occurs under the following circumstances:
- An end-of-file condition occurs on the console.
- A BEFORE TIME phrase was specified and the ACCEPT statement timed out.
- An exception key was used to terminate input. This may be disabled with the
-Ve compile-time option.
- A conversion error occurred when numeric data was entered with the CONVERSION phrase. You must use the
-Ve compile-time option to enable program handling of conversion errors for this exception condition to be used. Normally, the
ACUCOBOL-GT runtime system does not allow invalid numeric data to be entered.
- A
message terminates the ACCEPT.
- An
event terminates the ACCEPT.
- the screen contains no input fields, or all input fields are protected or disabled.
- key-dest, if specified, causes this phrase to have all of the effects of the CONTROL KEY phrase in addition to its normal effects.
See the CONTROL KEY phrase above for details. If you specify
key-dest, then exception keys will cause
statement-1 to execute even if you have used the
-Ve compile-time option to turn off handling of exception keys by the ON EXCEPTION phrase.
- If you specify an ON EXCEPTION phrase, then exception keys will be allowed for the ACCEPT statement. Otherwise exception keys
will be disabled unless you use the CONTROL KEY phrase or the
-Vx compile-time option. However, if you use the
-Ve compile-time option to disable exception key handling, then an ON EXCEPTION phrase will not enable exception keys unless
the key-dest option is also used.
- If the NEXT SENTENCE option is used, then control will pass to the next executable sentence when an exception condition exists.
Note that the ANSI standard states that
NEXT SENTENCE is an archaic feature and its use should be avoided.
- If the NOT ON EXCEPTION phrase is specified, then
statement-2 executes if no exception condition exists.
- The ON EXCEPTION phrase may not be specified if the AT END phrase is used. The
key-dest option may not be used if the CONTROL KEY phrase is specified.
AT END Phrase
- The AT END phrase causes the following
statement-1 to execute if an end-of-file occurs during the ACCEPT.
- If NEXT SENTENCE is specified instead of
statement-1, control passes to the next executable sentence if an end-of-file occurs. Note that the ANSI standard states that
NEXT SENTENCE is an archaic feature and its use should be avoided.
- If the NOT AT END phrase is used, then
statement-2 executes if an end-of-file does not occur during the ACCEPT.
- By default, ACUCOBOL-GT does not have a method of generating end-of-file conditions from a terminal. The runtime system can
be reconfigured, however, to generate an end-of-file for selected keys. See
Redefining the Keyboard for more information.
- The AT END phrase may not be specified when the ON EXCEPTION phrase is.
Format 2 (ACCEPT screen-name)
- This is a form level ACCEPT. A Format 2 ACCEPT statement allows the user to enter data into all of the input and update fields
(as well as every control that can be activated) contained in screen-name.
screen-name must be a screen item declared in the program's Screen Section. After the user finishes, each input and update field is moved
to its corresponding data item. See
Screen Section for a complete description of a screen item.
- The AT, LINE, and COLUMN phrases describe the starting location of the screen item. These phrases are described in detail
in section
Common Screen Options. If either the line or column number is missing or zero, then line or column number 1 is used.
- The BEFORE TIME phrase works in the same manner as described above for a Format 1 ACCEPT. If multiple input fields are being
entered, then the timer is set only for the first field. As soon as the user starts entering data, as much time as desired
may be taken to enter the screen.
- The ALLOWING MESSAGES phrase works in the same manner as described above for a Format 1 ACCEPT.
- If an exception condition occurs, the ON EXCEPTION phrase causes control to be transferred to
statement-1. (Exception codes are stored in the variable named in SPECIAL-NAMES with the CRT STATUS phrase.) See rule number 1 under
ON EXCEPTION phrase (above) for a list of the conditions that cause an exception. Exception keys are listed under the heading
CONTROL KEY Phrase above. If an exception does not occur, and the NOT EXCEPTION phrase is specified, then
statement-2 executes.
- Specifying the EXCEPTION phrase allows the user to terminate input with an exception key. Otherwise, exception keys are disabled
unless the program is compiled with the
-Vx option.
Note: You can code Screen Section entries that reference embedded procedures or an event procedure for Format 2 ACCEPT statements.
See
PROCEDURE Clause for more information.
You can also code a Special-Names entry that allows an embedded procedure to control an ACCEPT statement. See
Special-Names Paragraph for more information.
- If
condition-1 is specified, then the ACCEPT statement executes repeatedly until
condition-1 evaluates
true. The effect is exactly the same as coding:
PERFORM, WITH TEST AFTER, UNTIL condition-1
ACCEPT screen-name, accept options
END-PERFORM
This can be convenient when you are retrieving data from a graphical screen. For example, you could use a statement like
the following to get data from a dialog box until the user presses the box's
OK button:
ACCEPT screen-1, UNTIL ok-button-pressed
Format 3 (ACCEPT FROM)
- The Format 3 ACCEPT statement causes information to be transferred to dest-item according to the rules for the MOVE statement.
- The DATE option causes the current date to be moved to
dest-item. The date is composed of the year of the century, the month of the year, and the day of the month. Each element occupies
two digits. For example, December 25, 1998, would be expressed
981225. DATE is treated as if it were described by a PICTURE 9(6) clause.
- The DAY option causes the current date to be moved to
dest-item. The format of the date is the year of the century (2 digits) followed by the day of the year (3 digits). For example, December
25, 1998, is
98359. DAY acts as if it were described by a PICTURE 9(5) clause.
- ACCEPT FROM CENTURY-DATE returns the current date in the format
YYYYMMDD (year/month/day). ACCEPT FROM DATE YYYYMMDD is equivalent to ACCEPT FROM CENTURY-DATE. ACCEPT FROM CENTURY-DAY returns the
current date in the format
YYYYDDD (year/day-of-year). ACCEPT FROM DAY
YYYYDDD is equivalent to ACCEPT FROM CENTURY-DAY. These are the same as ACCEPT FROM DATE and ACCEPT FROM DAY, except that the year
field is 4 digits instead of 2 digits.
The compiler option
-Zy lets you treat ACCEPT FROM DATE as ACCEPT FROM CENTURY-DATE, and ACCEPT FROM DAY as ACCEPT FROM CENTURY-DAY. See
Miscellaneous Options for more information.
- The TIME option causes the current time of day to be moved to
dest-item. For a
dest-item described by a PICTURE 9(8) clause, the format of the time is the hour (24hour clock), the minutes, the seconds and the hundredths
of a second. Each element occupies two digits. For example, 2:41 PM would be expressed
14410000. A
dest-item described by a PIC 9(12) clause (or larger) has the same effect as the MICROSECOND-TIME option (described below).
- The MICROSECOND-TIME option includes microsecond precision for
dest-item described by a PIC 9(12) clause (or larger). It produces a format that includes six decimal places for fractional second
values: HHMMSSUUUUUU (Hours, Minutes, Seconds, Microseconds).
Note: The precision and accuracy of the time values provided depend on the operating system. As of the current date, UNIX and Linux
systems will generally provide microsecond precision values while Windows systems will provide millisecond precision values
with the trailing three digits being zero.
- The DAY-OF-WEEK option causes the current day of the week to be moved to
dest-item. The format of this item is a single digit where 1 represents Monday, 2 represents Tuesday, up through 7 for Sunday. DAY-OF-WEEK
acts as if it were described by a PICTURE 9 clause.
- The TERMINAL-INFO option causes information about the user's terminal to be moved to
dest-item. This information is returned in the following format, as contained in the TERMINAL-ABILITIES group item defined in
acucobol.def:
01 TERMINAL-ABILITIES.
03 TERMINAL-NAME PIC X(10).
03 FILLER PIC X.
88 HAS-REVERSE VALUE "Y".
03 FILLER PIC X.
88 HAS-BLINK VALUE "Y".
03 FILLER PIC X.
88 HAS-UNDERLINE VALUE "Y".
03 FILLER PIC X.
88 HAS-DUAL-INTENSITY VALUE "Y".
03 FILLER PIC X.
88 HAS-132-COLUMN-MODE VALUE "Y".
03 FILLER PIC X.
88 HAS-COLOR VALUE "Y".
03 FILLER PIC X.
88 HAS-LINE-DRAWING VALUE "Y".
03 NUMBER-OF-SCREEN-LINES PIC 9(3).
03 NUMBER-OF-SCREEN-COLUMNS PIC 9(3).
03 FILLER PIC X.
88 HAS-LOCAL-PRINTER VALUE "Y".
03 FILLER PIC X.
88 HAS-VISIBLE-ATTRIBUTES VALUE "Y".
03 FILLER PIC X.
88 HAS-GRAPHICAL-INTERFACE VALUE "Y".
03 USABLE-SCREEN-HEIGHT PIC X(2) COMP-X.
03 USABLE-SCREEN-WIDTH PIC X(2) COMP-X.
03 PHYSICAL-SCREEN-HEIGHT PIC X(2) COMP-X.
03 PHYSICAL-SCREEN-WIDTH PIC X(2) COMP-X.
03 FILLER PIC X.
88 IS-REMOTE VALUE "Y".
03 CLIENT-MACHINE-NAME PIC X(64).
03 FILLER PIC X.
88 ACU-NO-TERMINAL VALUE "Y".
03 CLIENT-USER-ID PIC X(20).
03 ATW-BROWSER-NAME PIC X(30).
03 ATW-BROWSER-VERSION PIC X(10).
03 ATW-ENGINE-NAME PIC X(30).
03 ATW-ENGINE-VERSION PIC X(10).
03 ATW-CLIENT-OS-NAME PIC X(30).
03 ATW-CLIENT-OS-VERSION PIC X(10).
03 ATW-CLIENT-DEVICE-TYPE PIC X(30).
03 ATW-CLIENT-DEVICE-VENDOR PIC X(30).
03 ATW-CLIENT-DEVICE-MODEL PIC X(30).
78 MAX-MONITORS VALUE 10.
03 MONITOR-INFO REDEFINES ATW-INFO.
05 MONITOR-COUNT PIC 99.
05 ONE-MONITOR-INFO OCCURS MAX-MONITORS TIMES.
07 OMI-PHYSICAL.
09 OMIP-LEFT SIGNED-INT.
09 OMIP-TOP SIGNED-INT.
09 OMIP-RIGHT SIGNED-INT.
09 OMIP-BOTTOM SIGNED-INT.
07 OMI-WORK.
09 OMIW-LEFT SIGNED-INT.
09 OMIW-TOP SIGNED-INT.
09 OMIW-RIGHT SIGNED-INT.
09 OMIW-BOTTOM SIGNED-INT.
07 OMI-FLAGS SIGNED-INT.
88 IS-PRIMARY-MONITOR VALUE 1.
- The TERMINAL-NAME field contains a short descriptive name of the terminal type being used (e.g., "vt100", "tvi925", "pc-color").
For the Windows runtime and thin client, the TERMINAL-NAME field contains the string "Windows". The number-of-lines and number-of-columns
fields contain the number of lines and columns the screen contains in its current configuration. The remaining fields contain
a
Y if the user's terminal has the named feature and an
N if it does not.
- The NUMBER-OF-SCREEN-LINES and NUMBER-OF-SCREEN-COLUMNS fields hold the number of whole lines and columns (respectively) in
the current floating window. If no window has been created, these values are set to the size of the default application window.
- The HAS-VISIBLE-ATTRIBUTES field is set to
Y if setting a video attribute on the terminal causes a character to be taken up on the screen. Terminals that behave in this
fashion have additional restrictions over the terminals that have
hidden attributes. For additional information on these restrictions, see
Restricted Attribute Handling.
- The HAS-GRAPHICAL-INTERFACE item is set to TRUE (value "Y") if the runtime is using a graphical user interface. Otherwise,
it is FALSE (value
N). You can generally assume that graphical systems can support non-integer row/column positions and window/control sizes.
- Non-graphical (i.e., character-based) systems will truncate non-integer row and column positions, along with window and control
sizes to the nearest integer that is smaller (e.g.,
line 1.5 will be treated as
line 1).
- The USABLE-SCREEN-HEIGHT field holds the height of the usable portion of the user's display device in
base units. This value represents character cells for character-based systems or pixels for graphical systems. On graphical systems,
this value can be larger than the area used by your program (it is the largest area that a program could conceivably use).
Under Windows 98, this value excludes the Taskbar if the user has set the
Always on top Taskbar option. On character-based systems, this value is the size of the actual screen, or the current application window
if you are running in a character-emulator such as the Windows console-mode (DOS box) or an X-term.
- USABLE-SCREEN-WIDTH is the same as USABLE-SCREEN-HEIGHT except that it returns the width instead of the height.
- PHYSICAL-SCREEN-HEIGHT is the same as USABLE-SCREEN-HEIGHT except that it includes the entire screen instead of just the usable
portion of the screen. Under Windows 98, this is the actual screen resolution. Under character-based systems, this value is
normally the same as USABLE-SCREEN-HEIGHT because most character-based systems do not provide a method for measuring the physical
screen.
- PHYSICAL-SCREEN-WIDTH is the same as PHYSICAL-SCREEN-HEIGHT except that it returns the screen's width instead of the screen's
height.
- IS-REMOTE is set to TRUE (value
Y) if the program is running with the Thin Client. When IS-REMOTE is true: CLIENT-MACHINE-NAME is set to the name of the client
that is running acuthin, plus a hyphen ("-") and the hex value of the client process ID. For example:
techxp-2ef1
CLIENT-USER-ID is set to the client-side login name of the current user. This is the name the user entered when logging in
to the client that is running acuthin. If it is not set, acuthin looks for the environment variable
USERNAME. If that is not set, then the literal "USER" is placed in the field.
- CLIENT-MACHINE-NAME provides the name of the client machine. When executing using Thin Client, the Process ID of the server
runtime is appended to the client machine name in order to distinguish multiple instances of acuthin running against the same
server.
- ACU-NO-TERMINAL is set to TRUE if the runtime was started with the
-b option (-b inhibits terminal initialization and implies that no terminal is attached to the process). In this scenario, terminal I/O
is undefined and should be avoided. When ACU-NO-TERMINAL is TRUE, other fields in TERMINAL-ABILITIES return their default
value.
- The ATW- prefixed fields remain blank if you are not running through AcuToWeb.
- The MAX-MONITORS constant and MONITOR-INFO group mimics that returned by the Win32 API
GetMonitorInfo, providing information about the physical and work area of up to 10 attached monitors. Because the primary monitor may not
be the furthest left monitor, some of the values for the rectangle bounds may be negative. The order is the order returned
by Microsoft, and is not sorted in any way.
Note: This information is not available when running with AcuToWeb (which is why the ATW area is redefined); however, it is available
when running under thin client, in which it returns information about the display host.
On many UNIX systems, the runtime can use ACCEPT FROM TERMINAL-INFO to determine the initial size of its window when it is
running under the X Window system, Motif, OpenLook, or Sunview. It uses this information to set the number of rows and columns
available to the program, and to scroll the screen correctly. The size found overrides the size specified in the
a_termcap entry for the terminal. If you need to, you can override these settings with the LINES and COLUMNS environment variables.
- The SYSTEM-INFO option causes some general information about the runtime to be moved to
dest-item. The information is returned in the following format (SYSTEM-INFORMATION is defined in
acucobol.def):
01 SYSTEM-INFORMATION.
03 OPERATING-SYSTEM PIC X(10).
88 OS-IS-MSDOS VALUE "MS-DOS".
88 OS-IS-OS2 VALUE "OS/2".
88 OS-IS-VMS VALUES "VMS",
"VAX/VMS".
88 OS-IS-UNIX VALUES "Unix",
"Unix-V", "Unix-4",
"UNOS".
88 OS-IS-WINDOWS VALUE "WINDOWS".
88 OS-IS-WIN-NT VALUE "WIN/NT".
88 OS-IS-WIN-FAMILY VALUES "WINDOWS",
"WIN/NT".
03 USER-ID PIC X(12).
03 STATION-ID PIC X(12).
03 FILLER PIC X.
88 HAS-INDEXED-READ-PREVIOUS VALUE "Y".
03 FILLER PIC X.
88 HAS-RELATIVE-READ-PREVIOUS VALUE "Y".
03 FILLER PIC X.
88 CAN-TEST-INPUT-STATUS VALUE "Y".
03 FILLER PIC X.
88 IS-MULTI-TASKING VALUE "Y".
03 RUNTIME-VERSION.
88 VERSION-PRIOR-TO-2-2 VALUE SPACES.
05 RUNTIME-MAJOR-VERSION PIC 99.
05 RUNTIME-MINOR-VERSION PIC 99.
05 RUNTIME-RELEASE PIC 99.
03 FILLER PIC X.
88 IS-PLUGIN VALUE "Y".
03 SERIAL-NUMBER PIC X(20).
03 FILLER PIC X.
88 HAS-LARGE-FILE-SUPPORT VALUE "Y".
03 FILLER PIC X.
88 HAS-BIS-SUPPORT VALUE "Y".
03 FILLER PIC X.
88 IS-64-BIT VALUE "Y".
- The OPERATING-SYSTEM field returns information about the operating system the runtime is ported to. It may contain one of
the following values:
| Value
|
Host System
|
| Unix
|
Any version of Unix
|
| VMS
|
VMS or OpenVMS
|
| WINDOWS
|
Microsoft Windows 98
|
| WIN/NT
|
Microsoft Windows NT 4.0, or Windows 2000
|
These values are intended to give the program fundamental information about the runtime.
Note: The sample copy library
acucobol.def includes some useful level 88 descriptions of operating system labels. For example,
OS-IS-UNIX covers all UNIX platforms. For a complete list, see
acucobol.defin the
samples directory of your ACUCOBOL-GT installation.
- The USER-ID field is filled in with the login name of the current user. If it is not set, the runtime looks for the symbol
. If it is not set, the literal
USER is placed in this field.
- The STATION-ID field is filled in with the station name of the video terminal attached to the executing program. For UNIX
systems, the initial
/dev/ is removed from the name first.
On Windows machines, the value of the symbol
STATIONwill be returned if it is set in the host environment. If it is not set, then the literal "CON" will be placed in this field.
If the program is displaying on a thin client, STATION-ID is filled with "at<pid>" where pid is the process ID of the runtime
running on the server.
- The HAS-INDEXED-READ-PREVIOUS field is
Y if the READ PREVIOUS and START LESS THAN verbs are available for indexed files on the host system. If these verbs are not
available, this field is set to
N. If more than one indexed file system is being used, then this field is set to
Y only if all of the file systems support READ PREVIOUS.
- The HAS-RELATIVE-READ-PREVIOUS field is
Y if the READ PREVIOUS and START LESS THAN verbs are available for relative files on the host system. If these verbs are not
available, this field is set to
N.
- The CAN-TEST-INPUT-STATUS field is
Y if the ACCEPT FROM INPUT STATUS verb is available on the host system. If not, it is set to
N. Most machines can use this verb, but a few cannot. On these machines, executing this verb will return a constant value that
you can pre-select with a configuration file option. There is a runtime configuration variable called
SCRIPT_STATUS that controls the behavior of ACCEPT FROM INPUT STATUS when the input is not attached to a terminal.
- The IS-MULTI-TASKING field is
Y if the host system can run multiple tasks at once and has record locking facilities installed. This can be used to determine
whether or not multiple copies of the runtime system can be run with correct file handling.
- RUNTIME-VERSION fields are filled in with numbers that identify the major version number, minor version number, and release
number. For example, ACUCOBOL-GT Version 3.2.0 would return 03 as the major version, 02 as the minor version, and 00 as the
release number.
- The IS-PLUGIN field is
Y if the runtime is the Web Runtime running within a Web browser. Otherwise, it is set to
N. See
A Programmer's Guide to the Internet for more information about the Web Runtime.
- The SERIAL-NUMBER field is filled with the serial number of the runtime.
- The HAS-LARGE-FILE-SUPPORT field is
Y if the UNIX port in question has extended support for large sequential and relative files. Otherwise, it is set to
N.
- The IS-64-BIT field is
Y if the runtime is 64-bit; otherwise, the runtime is 32-bit.
- The INPUT STATUS form of the ACCEPT statement returns a value that indicates whether or not there is data currently available
from the standard input. Normally, when an ACCEPT statement executes, the program pauses until the user types in some data.
The INPUT STATUS option can be used to test to see if the user has entered some data before executing an ACCEPT.
This can be useful in a loop that constantly updates information while still allowing for user input.
The INPUT STATUS option causes this information to be moved to dest-item. It is treated as if the source item were described
as PICTURE 9(1). The value is 1 if input is currently available, 0 if not.
If the input is being redirected, by default the value returned is zero. You can control this with the configuration variables
INPUT_STATUS_DEFAULT and
SCRIPT_STATUS.
A small number of hardware platforms do not have the ability to test for pending input. On these machines, this verb returns
a constant value. By default, this value is zero, but it may be set to another value via the configuration variable INPUT_STATUS_DEFAULT.
Note: Another method of waiting for input while performing another operation is to use threads. A separate thread is used to perform
the regular ACCEPT (for example), while the original thread performs the ongoing operation. See
Multiple Execution Threads for more information.
When you use the INPUT STATUS phrase of the ACCEPT verb with controls, and especially with ActiveX controls, the results may
be undefined. A much better way of handling detection of user input in programs using controls is to employ event procedures
or a separate thread for that purpose.
- The ESCAPE option of the ACCEPT statement returns the termination key value of the last Format 1 or Format 2 ACCEPT statement.
These values are listed under the heading
CONTROL KEY Phrase above. The value is treated as a COMP-1 data item that is moved to dest-item using the standard rules for a numeric move
(exception: in ICOBOL compatibility mode, the value is treated as a PIC 99 data item).
- The ACCEPT FROM LINE NUMBER option returns a 3-digit number corresponding to the console device that is controlling the executing
program. Because most of the machines that run ACUCOBOL-GT do not use device numbers, but use alphanumeric names instead,
ACUCOBOL-GT computes the device number by the following procedure. First the device name is converted to upper case and hyphens
are converted to underscores (on UNIX systems, the initial
/dev/ is removed). This name is then searched for in the environment (including the configuration file). If it is found, then the
value of the name is returned. This allows you to assign a customized value for each device. If the name is not found in the
environment, then a number is formed from any digits found in the original device name (for example,
tty15 would return as
15). If there are no digits in the device name, the value 0 is used.
If the program is displaying on a thin client, ACCEPT FROM LINE NUMBER returns the last three digits of the process ID of
the runtime running on the server.
- The ACCEPT FROM COMMAND-LINE option causes the contents of the original command line to be moved to dest-item. Only those
elements of the command line that appear after the program name are returned. No parsing is done; you must parse the command
line into separate arguments yourself.
On Windows machines, the command line is limited to 1024 characters. The command line remains unchanged regardless of the
actions of any CHAIN, CALL PROGRAM, or CALL RUN verbs (which all start new run units).
For an alternate method in which the runtime system parses the arguments for you, see the
CHAIN Statement.
To change the contents of the command-line buffer, see the DISPLAY UPON COMMAND-LINE statement (Format 8) in this topic. You
can also access the command-line buffer from a C program. The buffer is an external data array named Acmd_line.
- The STANDARD OBJECT option returns a handle to one of the system's pre-defined resources. The resource returned depends on
the value of
object-name, as described in the following table:
| Object-Name
|
Resource
|
|
FIXED-FONT
|
The host system's default fixed-size font. This is the default font used for textual displays. Under Microsoft Windows, this
font is Windows' SYSTEM-FIXED-FONT.
|
|
TRADITIONAL-FONT
|
Also a fixed-size font. This font uses the standard character set associated with the host hardware (as opposed to the host
graphical system). On many systems, this font is the same as FIXED-FONT. Under Microsoft Windows, this font is Windows' OEM-FIXED-FONT
and uses the "OEM" character set instead of the ANSI character set.
|
|
DEFAULT-FONT
|
This is the default font used by controls. On a graphical system, this font is usually a proportional font, and usually the
same as SMALL-FONT. On non-graphical systems, this is the same as the FIXED-FONT. You can specify the default font with the
DEFAULT_FONT configuration variable. See
DEFAULT_FONT for more information.
|
|
LARGE-FONT
|
A moderately large font that is appropriate for controls. On graphical systems, this is a proportionally spaced font. Under
Microsoft Windows, this is Windows' SYSTEM-FONT. On non-graphical systems, this is the same as FIXED-FONT. On some systems,
this is the same as MEDIUM-FONT.
|
|
MEDIUM-FONT
|
An average size font that is appropriate for controls. On graphical systems, this is a proportionally spaced font. Under Microsoft
Windows, this font is a boldface version of Windows' ANSI-VAR-FONT. On non-graphical systems, this is the same as FIXED-FONT.
|
|
SMALL-FONT
|
A small font that is appropriate for controls. On graphical systems, this is a proportionally spaced font. Under Microsoft
Windows, this font is Windows' ANSI-VAR-FONT. On non-graphical systems, this is the same as FIXED-FONT. On some systems, this
is the same as MEDIUM-FONT.
|
|
LM-RESIZE
|
A standard layout manager that assists in moving or resizing controls when a window changes size. See
Layout Managers for more information.
|
You may use either upper-case or lower-case values in
object-name. If object-name does not match any of the allowed values,
dest-item is set to NULL.
- The ACCEPT FROM THREAD statement moves the thread ID of the executing thread to dest-item.
- The WINDOW HANDLE option causes
dest-item to receive the handle of the initial or current floating window. Note that this is the only way to get the handle of the
default main application window. You do this by performing an ACCEPT FROM WINDOW HANDLE prior to creating any floating windows
in your application.
Format 4 (ACCEPT SCREEN)
- The ACCEPT FROM SCREEN verb returns data present on the user's terminal. This differs from the Format 1 ACCEPT statement in
that the user does not enter the data. Instead, the data is what is already present on the screen. This can be used to obtain
an image of the user's current screen. Note however that screen attributes such as underlines and reverse colors are not returned.
On graphical systems, this verb does not return any information contained in controls. To determine the current value of a
control, use the INQUIRE verb.
- dest-item must specify an alphanumeric data item without the JUSTIFIED phrase. It is filled with the returned screen contents.
dest-item is space-filled on the right if it is larger than the returned screen contents.
- The LINE phrase specifies the screen line to use for the ACCEPT. Line one refers to the top line of the current window. If
the LINE phrase is missing or
line-num is zero, the current cursor line is used.
- The COLUMN phrase specifies the screen column to use. Column one refers to the leftmost column of the current window. If the
COLUMN phrase is missing or zero, then the column depends on the following:
- If the LINE phrase is used (and is not zero), then column one is used.
- Otherwise, the current cursor column is used.
- The SIZE phrase specifies the number of screen positions to return. If the SIZE phrase is missing, then the size of dest-item
is used. If the SIZE phrase specifies fewer characters than the size of dest-item, then
dest-item is space-filled on the right.
- The ACCEPT FROM SCREEN verb does not change the cursor position or modify the screen in any way. A single ACCEPT FROM SCREEN
can "wrap around" the right edge of the window to return characters from multiple screen lines.
- Except as specified in the following rule, all characters on the terminal screen are returned using the underlying representation
of the character in the native character set. This is usually the ASCII value of the character.
- The ACUCOBOL-GT Terminal Manager returns consistent values for certain special characters, regardless of the hardware being
used. This is done for certain characters used by the Terminal Manager that do not have an ASCII representation. These special
characters are the following:
| Character
|
Value
|
| Unknown
|
1
|
| Horizontal Line
|
2
|
| Vertical Line
|
3
|
| Upper Left Corner
|
4
|
| Upper Right Corner
|
5
|
| Lower Left Corner
|
6
|
| Lower Right Corner
|
7
|
| "Tee" Up
|
8
|
| "Tee" Right
|
9
|
| "Tee" Down
|
10
|
| "Tee" Left
|
11
|
| 4-Way Intersection
|
12
|
| Bottom Endpoint
|
13
|
| Left Endpoint
|
14
|
| Top Endpoint
|
15
|
| Right Endpoint
|
16
|
| Visible Attribute
|
17
|
The "Unknown" value is returned for any screen position that cannot be determined by ACUCOBOL-GT. The "Visible Attribute"
character is used by certain types of terminals when they are displaying video attributes. On these types of terminals, video
attributes take up screen positions. They usually appear as spaces on the screen. The remaining special characters are various
line segments used by the DISPLAY WINDOW, DISPLAY LINE, and DISPLAY BOX verbs.
- It is often desirable to translate the special case characters into ASCII values. You can do this easily with the INSPECT
CONVERTING verb. For example, the following statement converts the line-drawing characters into hyphens, vertical bars, and
plus signs, and translates the "unknown" and "visible attribute" characters into spaces:
INSPECT ... CONVERTING
X'0102030405060708090A0B0C0D0E0F1011'
TO " -|+++++++++|-|- "
Format 5 (ACCEPT ENVIRONMENT)
- A Format 5 ACCEPT statement returns values from the user's environment or the ACUCOBOL-GT runtime system's configuration settings.
env-name is the name of the environment setting whose value is to be returned. If you provide the literal name of this item (such
as CURSOR-MODE), you must enclose it in quotes. The value returned from this item is moved to
dest-item.
- This verb will search for
env-name in the following places:
- First, the runtime system sees if
env-name matches any of its configuration variables. If it does, the configuration variable's current setting is moved to
dest-item. Not all configuration variables can be returned by the ACCEPT verb, because some of them have multiple settings.
- Next,
env-name is searched for in the runtime system's local environment. This environment consists of all of the entries in the ACUCOBOL-GT
configuration file plus any entries made with the SET ENVIRONMENT verb. This excludes the runtime system's configuration variables
that are covered in rule (a) above. Note that any entry in the ACUCOBOL-GT configuration file that is also in the user's host
environment has its initial value set the same as the entry in the user's environment.
- Finally, on machines that have a user-maintained environment, that environment is searched for env-name. A description of
the user's environment for each machine is given in section
Supported Hardware of the
ACUCOBOL-GT User's Guide.
When the runtime system searches for env-name, only the first 30 characters are used. Also, any lower-case characters in env-name
are treated as upper-case, and any hyphens are treated as underscores. If the truncated name is not found, the runtime searches
again, this time looking for
env_name exactly as specified.
- If an entry is found, then its value is moved to
dest-item. For numeric configuration variables, the source item is treated as if it were a COMP-1 data item. For all other entries,
the source item is treated as an alphanumeric data item. The value is moved to
dest-item according to the rules for the MOVE statement. Note that if the source item is numeric, then dest-item may be defined either
as a numeric field or as an alphanumeric field of five or more characters. If
dest-item is alphanumeric and is larger than five characters, the value that is returned will occupy the leftmost five characters of
dest-item.
- If no matching entry is found, or if the
env-name is the name of a configuration variable whose value cannot be returned, spaces are moved to
dest-item and
statement-1, if specified, is executed.
- If a legal matching entry is found, then
statement-2 (if specified) is executed.
Format 6 (ANSI ACCEPT)
- A Format 6 ACCEPT statement reads a line of input from the standard input device (usually the user's console). This data is
then moved into dest-item. If the data is longer than the size of
dest-item, it is truncated on the right. If it is smaller, then it is space-filled on the right.
- Prior to reading the line, the runtime system places the user's terminal into the state it normally occupies when it is used
by the operating system. The runtime then requests the input from the operating system. The operating system usually provides
some form of input editing, such as backspacing. The exact editing available depends on the host operating system.
- Technical Note: Because this verb requests input directly from the operating system, ACUCOBOL-GT's Terminal Manager is not
aware of the changes that are occurring to the screen. This can cause problems if you mix ANSI-style and ACUCOBOL-GT-style
ACCEPT and DISPLAY verbs in the same program. On many machines, ACUCOBOL-GT's Terminal Manager maintains an image of the user's
screen. (This improves efficiency by removing redundant screen output and is also used to implement pop-up windows.) Bypassing
the Terminal Manager can cause the Terminal Manager's screen image to become incorrect. This can cause strange effects when
it is mixed with an ACUCOBOL-GT-style ACCEPT or DISPLAY verb, including:
- lost data
- incorrect functioning of CLOSE WINDOW
- incorrect cursor position
- incorrect character attributes
- incorrect display in debugger
For these reasons, you must be careful when using ANSI ACCEPT. Here are some useful guidelines:
- If your statement does not affect the screen image, then it can be used safely. For example, sending a control sequence to
an attached cash register is safe.
- If you use only ANSI-style ACCEPT and DISPLAY verbs, then you should not experience any problems except that the debugger
will not be able to show the user's screen.
- If you must mix formats, then you can use the library routine
W$FORGET to correct the behavior of the Terminal Manager. This routine causes the Terminal Manager to enter its initial state. It
will assume that it does not know the screen image or current attribute settings. Calling this routine after a series of ANSI-style
ACCEPT or DISPLAY verbs will place the Terminal Manager into a state where it can operate correctly.
- You can safely use the verb if your ANSI-style ACCEPT or DISPLAY sends data to a device other than the user's console, such
as the standard error file.
Note: When you are running a 32-bit Windows CGI program with the
-f option or with the A_CGI environment variable set, the runtime reads only the number of bytes specified by the web server
in the CONTENT_LENGTH environment variable. The runtime does not wait for an end of file condition. If you are running without
the
-f option and have not set the A_CGI environment variable, then the runtime reads until an end of file condition occurs. Note
that some web servers such as Microsoft Internet Information Server 4.0 do not terminate input to a CGI program with an end
of file condition. Instead, they rely upon the CGI program to read exactly the number of bytes specified in the CONTENT_LENGTH
variable. When running an ANSI ACCEPT style CGI program using these web servers, you must use the
-f option or set the A_CGI environment variable.
Format 7 (ACCEPT control-handle)
- The ACCEPT Control-Handle statement activates the control identified by control-handle. The user interacts with the control
until some terminating event occurs. The event that caused the termination is then stored in key-dest, and the control's current
value is stored in value. The ACCEPT statement then terminates.
- If the CONTROL phrase is used, the runtime activates the control located at the screen position specified by the AT, LINE,
and COLUMN phrases in the current window (on non-graphical systems, the CLINE and CCOL phrases also apply). The runtime maintains
a list of controls in each window. When attempting to activate a control at a specific location, the runtime searches this
list, using the first control it finds that exactly matches the given location. The list is maintained in order in which the
controls are created. If the runtime does not find a control at the specified location, it returns an exception value of
96 (the same as doing an ACCEPT of a invalid control handle).
The following example creates an anonymous entry field and then ACCEPTs it, using its screen position.
DISPLAY ENTRY-FIELD, LINE 2, COL 5, SIZE 15.
ACCEPT CONTROL, VALUE MY-DATA, LINE 2, COL 5.
- key-dest names a data item that will receive a code indicating the terminating event. The program's CRT STATUS (if any) also receives
the termination code.
- When the ACCEPT statement terminates, the current value of the control is moved to value in accordance with the rules for
the MOVE statement. The type of control determines the source format of the value.
- The BEFORE TIME phrase operates in the same manner as it does in a Format 1 ACCEPT statement.
- The WITH BELL phrase causes the station's bell to sound when the control is initially activated.
- The ALLOWING MESSAGES phrase works in the same manner as described above for a Format 1 ACCEPT.
- The ACCEPT statement can terminate in several different ways. These ways are classified as either normal terminations or as
exceptions. If an exception caused the termination, then
statement-1 is executed. Otherwise,
statement-2 is executed. If you do not specify the ON EXCEPTION phrase, then the ACCEPT statement ignores exception keys (function keys).
You can override this behavior with the
-Vx compile-time option.
If you attempt to ACCEPT a disabled or otherwise invalid control, or if the active control is hidden during the ACCEPT either
by an event procedure or by code running in a different thread, the ACCEPT will immediately terminate, returning a CRT STATUS
value of
97. For a Screen Section ACCEPT, this will occur only if all of the referenced controls are disabled.
- You may also activate a control with a Format 2 ACCEPT statement (a Screen Section ACCEPT). If the referenced Screen Section
entry defines any controls, they are activated as appropriate.
Format 8 (ACCEPT external-form-item)
- The
external form of Format 8 is called an
output form if the IDENTIFIED BY clause is used to associate it with an HTML template file. If the IDENTIFIED BY clause is omitted, it
is called an
input form.
For example, the following is an input form:
01 CGI-FORM IS EXTERNAL-FORM.
03 CGI-VAR1 PIC X(10).
03 CGI-VAR2 PIC X(10).
and this is an output form:
01 HTML-FORM IS EXTERNAL-FORM IDENTIFIED BY
"tmplate1".
03 HTML-VAR1 PIC X(10).
03 HTML-VAR2 PIC X(10).
- The ACCEPT verb treats input and output forms the same. ACCEPT sets the value of each elementary item, in order, to the value
of its associated CGI variable, padding with trailing spaces. ACCEPT automatically decodes and translates the CGI input data
before moving it to the elementary items of
external-form-item. The value of each CGI variable is converted to the appropriate COBOL data type when it is moved to the external form.
CGI variable names are case-sensitive. However, for convenience, if ACCEPT cannot identify a CGI variable, it will repeat
the search for the variable ignoring the case.
- If the CGI variable is empty or does not exist, ACCEPT sets the value of numeric data items to zero and nonnumeric data items
to spaces. This behavior is configurable. If you do not want ACCEPT to clear the value of the data item when its CGI variable
does not exist in the CGI input data, set the CGI_CLEAR_MISSING_VALUES configuration variable to
0 (off, false, no). See the entry for
CGI_CLEAR_MISSING_VALUES for details.
- If the CGI variable is repeated in the CGI input data (as it would be in the case where multiple items have been selected
from a
choose-many list), the external form item that is identified with the CGI variable must be in a table. Otherwise, only the first CGI
value is moved to the external form item.
For example:
01 CGI-FORM IS EXTERNAL-FORM.
03 CGI-TABLE OCCURS 10 TIMES.
05 CGI-VAR1 PIC X(10).
05 CGI-VAR2 PIC X(10).
or
01 CGI-FORM IS EXTERNAL-FORM.
03 CGI-VAR1 PIC X(10) OCCURS 10 TIMES.
03 CGI-VAR2 PIC X(10) OCCURS 10 TIMES.
ACCEPT moves the values of the CGI variable to the items in the table. After all of the CGI values have been moved to items
in the COBOL table, the remaining items in the table are set to 0 if they are numeric items, and set to spaces otherwise.
Format 9 (ACCEPT EVENT)
- The ACCEPT EVENT statement waits for a terminating event to occur. The event that caused the termination is stored in
code-dest. The ACCEPT statement then terminates.
- code-dest names a data item that will receive a code indicating the terminating event. The program's CRT STATUS (if any) also receives
the termination code.
- The BEFORE TIME phrase operates in the same manner as it does in a Format 1 ACCEPT statement.
- The ALLOWING MESSAGES phrase works in the same manner as described above for a Format 1 ACCEPT.
- ACCEPT EVENT is similar to ACCEPT OMITTED except that it does not display a default initial window and it does not detect
keyboard termination or exception keys.
- The ACCEPT EVENT statement is designed for use in programs without a user interface. However, if the program has a user interface
and interacting with it causes a terminating event to occur, ACCEPT EVENT will terminate. In the debugger, ACCEPT EVENT will
terminate if the user presses the Enter key.
- The ACCEPT EVENT statement can terminate in several different ways. These ways are classified as either normal terminations
or as exceptions. If an exception caused a termination, then
statement-1 is executed. Otherwise,
statement-2 is executed.
Code Example - Format 9
The following program uses the Microsoft Agent Control (ActiveX) to create a
genie character and then directs it to speak
Hello World. It does not have a visible initial window or a user interface that allows keyboard or mouse input.
identification division.
program-id. no-ui.
environment division.
special-names.
copy "msagent.def".
.
data division.
working-storage section.
77 genie1-handle usage handle of Agent.
77 request-handle usage handle of IAgentCtlRequest.
77 request-status pic 9.
procedure division.
Main-Logic.
display initial window visible = 0.
display Agent of AgentObjects handle in genie1-handle.
modify genie1-handle
Characters::Load("Genie1", "genie.acs").
use genie1-handle Characters::Item("Genie1")
modify ^LanguageID 1033
^Show()
^Speak "Hello World" giving request-handle
perform until request-status = 1
ACCEPT EVENT BEFORE TIME 1000
inquire request-handle status in request-status
end-perform
destroy request-handle
modify ^Hide()
end-use.
destroy genie1-handle.
stop run.
Format 13 (ACCEPT FROM ENVIRONMENT-VALUE)
- Use a Format 13 ACCEPT to fetch the value of an environment or configuration variable stored with a Format 17 DISPLAY statement
(DISPLAY UPON ENVIRONMENT-NAME).
- The
value data item should be of a size and type that will accommodate the value of the environment or configuration variable.