TOCPREVNEXTINDEX

ACUCOBOL-GT Reference Manual
Version 6.0

ACCEPT Statement

The ACCEPT statement makes low-volume data available to the program. See section 6.4.9, "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:

Depending on the Format and options used, an ACCEPT statement can return the following pre-defined 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)

General Format
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                       }   
                          {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, please see Appendix Q, "HP COBOL Compatibility," in Book 4, Appendices.

  1. Dest-item is a data item that receives the accepted data. It must be USAGE DISPLAY unless the WITH CONVERSION phrase is also used.
  2. 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.

  3. Screen-name is the name of a screen entry declared in the program's Screen Section. See section 5.8, "Screen Section," for more information.
  4. 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.
  5. In Format 7, the AT, LINE, COLUMN, CLINE, and CCOL phrases may be used only if the CONTROL phrase is also used.
  6. Line-num, col-num, cline-num, and ccol-num are numeric data items or literals. Note that they may be non-integer, unless the value is in pixels.
  7. 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.
  8. 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 section 6.4.9, "FOREGROUND-COLOR and BACKGROUND-COLOR Phrases," for a more detailed discussion of color settings and values.
  9. Prompt-lit is a single-character alphanumeric literal or the figurative constant SPACE, ZERO, or QUOTE.
  10. Default is a literal or data item. It specifies the default entry value.
  11. Key-dest is a numeric data item. It receives the value of the key that terminated input.
  12. Thread-1 is a USAGE HANDLE or HANDLE OF THREAD data item.
  13. Statement-1 and statement-2 are any imperative statements.
  14. Condition-1 is any conditional expression.
  15. Cntrl-string and env-name are nonnumeric literals or data items.
  16. 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 section 4.2.3, "Special-Names Paragraph," for a list of valid devices.
  17. Object-name must be an alphanumeric literal or data item.
  18. 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.
  19. Value can be any data item. It receives the current value of the control when the ACCEPT statement terminates.
  20. Code-dest is a numeric data item.
  21. If the AT phrase is specified, neither the LINE nor the COLUMN phrase may be specified.
  22. If the COLOR phrase is specified, neither the FOREGROUND-COLOR nor the BACKGROUND-COLOR phrase may be specified.
  23. The CURSOR phrase may not be specified if a CURSOR phrase is specified in the program's Configuration Section.
  24. AUTO, AUTO-SKIP, and AUTOTERMINATE are equivalent.
  25. NO-ECHO, NO ECHO, OFF, and SECURE are equivalent.
  26. BLANK and ERASE are equivalent.
  27. BOLD, HIGH, and HIGHLIGHT are equivalent.
  28. LOWLIGHT and LOW are equivalent.
  29. COLUMN, COL, POSITION, and POS are equivalent.
  30. BELL and BEEP are equivalent.
  31. REVERSE-VIDEO, REVERSE, and REVERSED are equivalent.
  32. BLINK and BLINKING are equivalent.
  33. UNDERLINE and UNDERLINED are equivalent.
  34. CONVERSION and CONVERT are equivalent.
  35. REQUIRED and EMPTY-CHECK are equivalent.
  36. FULL and LENGTH-CHECK are equivalent.
  37. EXCEPTION and ESCAPE are equivalent.
  38. 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).
  39. 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 "(RM)".
  40. 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.
  41. 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.
  42. If the CONTROL KEY phrase is used, the key-dest option of the ON EXCEPTION phrase may not be specified.
  43. 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.
  44. 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).
  45. 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.

  46. 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)
  1. 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.
  2. 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.
  3. 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.
  4. The effects of the CURSOR, CONTROL KEY, BEFORE TIME, ON EXCEPTION, and AT END clauses are described below. The effects of the remaining optional clauses are described in section 6.4.9, "Common Screen Options."

CURSOR Phrase

  1. 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.
  2. 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.
  3. 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).
  4. 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 section 4.2.3, "Special-Names Paragraph," for details.

CONTROL KEY Phrase

  1. The CONTROL KEY clause allows for the entry of special keys and the recording of which key terminated input. (For additional information, see User's Guide, section 4.3, "The Keyboard Interface.") When the CONTROL KEY clause is specified, all of the special keys named in the following table can be used.
  2. 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:
  3. 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".

  4. 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.)
  5. 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 User's Guide, section 4.3.2.1, "The Keyboard Variable," subsection 3, "CHECK-NUMBERS."
  6. 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 section 4.3.2, "Redefining the Keyboard," in Book 1, User's Guide, for details on how to do this.

BEFORE TIME Phrase

  1. 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.
  2. 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".
  3. 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.

  4. 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 Book 1, User's Guide, section 6.8.

ALLOWING MESSAGES Phrase

  1. The ALLOWING MESSAGES phrase causes the ACCEPT statement to terminate when a message is sent from the appropriate thread, as follows:
    1. The THREAD thread-1 option allows messages from the thread identified by thread-1.
    2. The LAST THREAD option allows for messages from the "last" thread (see section 6.8.1, Book 1, User's Guide for a discussion of the last thread).
    3. The ANY THREAD option allows messages from any thread.
  2. 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.
  3. 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:
    1. In Format 1, dest-item is not updated.
    2. In Format 2, any VALUE, USING, or TO data items in the Screen Section are not updated.
    3. 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.

  4. An ACCEPT statement that is suspended (because another thread has an active ACCEPT) terminates when an allowed message arrives.
  5. If the ALLOWING MESSAGES phrase is omitted, messages will not terminate the ACCEPT. Instead, they are queued as normal.

ON EXCEPTION Phrase

  1. When this phrase is used, statement-1 is executed when an exception condition occurs. An exception condition occurs under the following circumstances:
    1. An end-of-file condition occurs on the console.
    2. A BEFORE TIME phrase was specified and the ACCEPT statement timed out.
    3. An exception key was used to terminate input. This may be disabled with the "-Ve" compile-time option.
    4. 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.
    5. A message terminates the ACCEPT.
    6. An event terminates the ACCEPT.
    7. the screen contains no input fields, or all input fields are protected or disabled.
  2. 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.
  3. 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.
  4. If the NEXT SENTENCE option is used, then control will pass to the next executable sentence when an exception condition exists.
  5. If the NOT ON EXCEPTION phrase is specified, then statement-2 executes if no exception condition exists.
  6. 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

  1. The AT END phrase causes the following statement-1 to execute if an end-of-file occurs during the ACCEPT.
  2. If NEXT SENTENCE is specified instead of statement-1, control passes to the next executable sentence if an end-of-file occurs.
  3. If the NOT AT END phrase is used, then statement-2 executes if an end-of-file does not occur during the ACCEPT.
  4. 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. For details, see section 4.3.2, "Redefining the Keyboard," in Book 1, User's Guide.
  5. The AT END phrase may not be specified when the ON EXCEPTION phrase is.
Format 2 (ACCEPT screen-name)
  1. 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 section 5.8, "Screen Section," for a complete description of a screen item.
  2. The AT, LINE, and COLUMN phrases describe the starting location of the screen item. These phrases are described in detail in section 6.4.9, "Common Screen Options." If either the line or column number is missing or zero, then line or column number 1 is used.
  3. 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.
  4. The ALLOWING MESSAGES phrase works in the same manner as described above for a Format 1 ACCEPT.
  5. 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.
  6. 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.

  7. Note: You can code Screen Section entries that reference embedded procedures or an event procedure for Format 2 ACCEPT statements. See section 5.9.6, "PROCEDURE Clause," for more information.

    You can also code a Special-Names entry that allows an embedded procedure to control an ACCEPT statement. See section 4.2.3, "Special-Names Paragraph," for more information.

  8. If condition-1 is specified, then the ACCEPT statement executes repeatedly until condition-1 evaluates "true". The effect is exactly the same as coding:
  9.     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)
  1. The Format 3 ACCEPT statement causes information to be transferred to dest-item according to the rules for the MOVE statement.
  2. 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.
  3. 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.
  4. 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.
  5. The compiler option "-Zy" lets you treat ACCEPT FROM DATE as ACCEPT FROM CENTURY-DATE, and ACCEPT FROM DAY as ACCEPT FROM CENTURY-DAY. For details, see the User's Guide section 2.1.10, "Miscellaneous Options."

  6. The TIME option causes the current time of day to be moved to dest-item. The format of the time is the hour (24-hour 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". TIME acts as if it were described by a PICTURE 9(8) clause.
  7. Generally speaking, older UNIX machines keep time only to the nearest second. Thus the hundredths portion of the value returned by ACCEPT FROM TIME is typically zero on UNIX machines. However, System V Release 4 and some other UNIX versions have an alternate method for determining the time with greater precision. The runtime system will use this alternate method if it is available, and then the hundredths portion will be filled in.

  8. 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.
  9. 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":
  10.     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).   
    1. The TERMINAL-NAME field contains a short descriptive name of the terminal type being used (e.g., "vt100", "tvi925", "pc-color"). 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.
    2. 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.
    3. 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 User's Guide, section 4.5, "Restricted Attribute Handling."
    4. 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.
    5. 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").
    6. 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 95/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.
    7. USABLE-SCREEN-WIDTH is the same as USABLE-SCREEN-HEIGHT except that it returns the width instead of the height.
    8. 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 95/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.
    9. PHYSICAL-SCREEN-WIDTH is the same as PHYSICAL-SCREEN-HEIGHT except that it returns the screen's width instead of the screen's height.
    10. 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.

    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.

  11. 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"):
  12.     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-AOS                VALUE "AOS/VS".   
                88  OS-IS-WINDOWS            VALUE "WINDOWS".   
                88  OS-IS-WIN-NT             VALUE "WIN/NT".   
                88  OS-IS-WIN-FAMILY         VALUES "WINDOWS",   
                                                    "WIN/NT".   
                88  OS-IS-AMOS               VALUE "AMOS".   
                88  OS-IS-MPE                VALUE "MPE/iX".   
                88  OS-IS-MPEIX              VALUE "MPE/iX".   
            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".   
    1. The OPERATING-SYSTEM field returns information about the operating system the runtime is ported to. It may contain one of the following values:
    2. Value
      Host System
      Unix
      Any version of Unix
      MPE/iX
      Running on HP machines
      VMS
      VMS or OpenVMS
      WINDOWS
      Microsoft Windows 95 or 98
      WIN/NT
      Microsoft Windows NT 3.5 or 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.def" in the "samples" directory of your ACUCOBOL-GT installation.

    3. 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 "USERNAME". If it is not set, the literal "USER" is placed in this field.
    4. 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.
    5. On Windows machines, the value of the symbol "STATION" will 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.

    6. 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.
    7. 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".
    8. 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.
    9. 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.
    10. 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.
    11. 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 the separate Acucorp book titled A Programmer's Guide to the Internet for more information about the Web Runtime.
    12. The SERIAL-NUMBER field is filled with the serial number of the runtime.
    13. 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".
  13. 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.
  14. 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. For more about threads, see section 6.8 of Book 1, User's Guide.

    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.

  15. 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).
  16. 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.
  17. 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.
  18. On Windows machines, the command line is limited to 126 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 section. You can also access the command line buffer from a C program. The buffer is an external data array named Acmd_line.

  19. 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:
  20. 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 MEDIUM-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 in Appendix H, Book 4, Appendices).
    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 Book 2, section 4.8, "Layout Managers."

    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.

  21. The ACCEPT FROM THREAD statement moves the thread ID of the executing thread to dest-item.
  22. 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)
  1. 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.
  2. 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.

  3. 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.
  4. 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.
  5. 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:
    1. If the LINE phrase is used (and is not zero), then column one is used.
    2. Otherwise, the current cursor column is used.
  6. 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.
  7. 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.
  8. 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.
  9. 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:
  10. 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.

  11. Technical Note: 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:
  12.     INSPECT ... CONVERTING   
                X'0102030405060708090A0B0C0D0E0F1011'   
            TO " -|+++++++++|-|- "   
Format 5 (ACCEPT ENVIRONMENT)
  1. 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.
  2. This verb will search for env-name in the following places:
    1. 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. The list of configuration variables that can be returned is detailed in Appendix H, Book 4, Appendices.
    2. 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.
    3. 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 1.4 of the User's Guide.
    4. 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.

  3. 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.
  4. 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.
  5. If a legal matching entry is found, then statement-2 (if specified) is executed.
Format 6 (ANSI ACCEPT)
  1. 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.
  2. 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.
  3. 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:
  4. For these reasons, you must be careful when using ANSI ACCEPT. Here are some useful guidelines:

    1. 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.
    2. 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.
    3. 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. See Appendix I, Book 4, Appendices for additional information.
    4. 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)
  1. 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.
  2. 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).
  3. 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.   
  4. 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.
  5. 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.
  6. The BEFORE TIME phrase operates in the same manner as it does in a Format 1 ACCEPT statement.
  7. The WITH BELL phrase causes the station's bell to sound when the control is initially activated.
  8. The ALLOWING MESSAGES phrase works in the same manner as described above for a Format 1 ACCEPT.
  9. 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.
  10. 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.

  11. 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)
  1. 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".
  2. 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).   
  3. 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.
  4. 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.

  5. 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.
  6. 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.
  7. 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)
  1. 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.
  2. 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.
  3. The BEFORE TIME phrase operates in the same manner as it does in a Format 1 ACCEPT statement.
  4. The ALLOWING MESSAGES phrase works in the same manner as described above for a Format 1 ACCEPT.
  5. 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.
  6. 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.
  7. 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)
  1. 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).
  2. The value data item should be of a size and type that will accommodate the value of the environment or configuration variable.

Acucorp, Inc.
Voice: (800) 262-6585 (U.S.A. and Canada)
Voice: (858) 689-4500
Fax: (858) 689-4550

Please share your comments on this manual
or on any Acucorp documentation with the
Acucorp Communications Department.
TOCPREVNEXTINDEX
1988-2003 Acucorp, Inc.
All rights reserved.