HP 3000 Manuals HP 3000 Manuals
VSHOWFORM
Displays on the terminal screen the current form from local form storage
or from the form definition buffer, any data in the data buffer, and any
messages from the window buffer. Displays any labels from the key label
buffer.
Syntax
VSHOWFORM {comarea}
Parameters
comarea Must be the comarea name specified when the terminal
file was opened with VOPENTERM. If not already set, the
following comarea items must be set before calling
VSHOWFORM:
cstatus Set to zero
comarealen Set to total number of two-byte words
in comarea.
windowenh Set to window enhancement code; may be
set before call to code for nondefault
enhancement; otherwise, set by
VOPENFORMF to default enhancement
specified in forms file. If set to
zero, window is not enhanced. (Refer
to windowenh discussion under
"Communication Area" earlier in this
section.)
The following comarea item can be set:
showcontrol Set to change VSHOWFORM control
options. The particular settings are
described below.
VSHOWFORM may set the following comarea values:
cstatus Set to nonzero value if call
unsuccessful.
filerrnum Set to file error code if MPE file
error.
(Note that showcontrol is not cleared by VSHOWFORM.)
Discussion
VSHOWFORM displays, on an open terminal screen, the form currently stored
as a form image in the terminal's local form storage or in the form
definition area of memory. Any enhancements specified for the form are
used for the display. Data currently in the data buffer in memory is
moved to the appropriate fields of the displayed form. Any message in
the window buffer of memory is displayed in the line of the form selected
as the status line. Also, any current form or global function key labels
in the key label buffer are displayed.
Performance Optimization
In order to optimize VSHOWFORM performance, only changed information is
written to the terminal. Thus, if the window has not been changed by
VPUTWINDOW or VSETERROR since the last execution of VSHOWFORM, or if the
current form is being repeated in place, these areas are not rewritten.
Also, when a form is repeating in place, only the changed values in the
data buffer area of memory are written by VSHOWFORM. This will be
sufficient for most applications; however, these three optimizations
(form, data, window) can be overridden by setting the comarea item
showcontrol as follows:
bit 15 = 1 Force form to be written to the terminal screen.
14 = 1 Force data and field enhancements to be written to the
terminal screen.
13 = 1 Force window line to be written to the terminal screen.
Depending on the bits set, VSHOWFORM writes a form or data or the window
to the terminal whether or not it has changed. Anything that has changed
is always written to the terminal regardless of showcontrol. Any
combination of these bits may be set. For example, if you want to force
a write of all data:
![[]](../../pic3k/M000076/F0603E3c50.gif)
showcontrol = octal 2
Or, if you want to force the window to be written:
![[]](../../pic3k/M000076/F0603F3c50.gif)
showcontrol = octal 4
Display and Local Form Storage
Prior to display on terminals with local form storage, the form can be
loaded into the terminal with any of the following methods:
* by a call to VLOADFORMS,
* by the previous call to VREADFIELDS if look-ahead form loading is
enabled, or
* by VSHOWFORM if preload is enabled.
A prior call to VGETNEXTFORM reads the form into the form definition area
of memory prior to display by VSHOWFORM. The form definition includes the
form image, any field editing specifications and all enhancements.
The field enhancements are specified with the form definition. If a
field has an error, VSHOWFORM changes its enhancement to the error
enhancement defined for the form by FORMSPEC.
The data buffer may contain data as a result of initialization by
VINITFORM, retrieval of user-entered data by VREADFIELDS, data formatting
or movement caused by editing specified with each field and executed by
VINITFORM, VFIELDEDITS, or VFINISHFORM. Data may also be transferred
directly to the data buffer, either from an application with VPUTBUFFER
or VPUTtype, or from a batch file with VREADBATCH.
The window contains any message set by VSETERROR or VPUTWINDOW.
Controlling the Keyboard
As soon as the form is displayed, VSHOWFORM normally enables the keyboard
so the user can enter data. The next call is usually to VREADFIELDS,
which locks the keyboard after the entered data is read. In case of
consecutive calls to VSHOWFORM, the following showcontrol bit can be set:
bit 10 = 0 Enable the keyboard.
1 Do not enable the keyboard.
The scenario is as follows:
* the last VREADFIELDS call locked the keyboard,
* for each of a series of consecutive calls to VSHOWFORM; set bit 10 of
showcontrol to one so the keyboard is not enabled,
* for the last of the consecutive calls to VSHOWFORM, set bit 10 to
zero to enable the keyboard.
This ensures that keystrokes do not change a form while it is being
displayed. Consecutive calls to VSHOWFORM could be used to display a
form with no fields, append another form to it, and display this second
form without doing a read in between.
Controlling Preload of Forms
On terminals with local form storage, VSHOWFORM first determines if the
current form is already in the terminal. If the form is in local
storage, it is displayed from local storage. If the form is not in local
storage, it is preloaded into the terminal from the form definition area
of memory depending on showcontrol, which can be set as follows:
bit 9 = 0 Do not preload the form.
1 Preload the form.
If bit 9 is zero, the form is written directly from the form definition
area of memory to the terminal screen. If bit 9 is one, the form is
preloaded into local storage and then displayed from local storage. One
or more forms could be purged from local storage if there is not room for
the form that is being loaded. Note that purging could occur even when
lookahead is set to one.
Controlling the Touch Feature
On terminals with the touch feature, touch can be enabled or disabled
with showcontrol, which can be set as follows:
bit 0 = 0 Do not enable the touch feature.
1 Enable the touch feature.
Controlling the Bell
By default (termoptions bit 15 is set to zero), VSHOWFORM sounds the bell
if neither the screen nor the window line have been redisplayed. The
bell can be suppressed in all cases by setting the termoptions bit to
one.
Example
COBOL
CALL "VSHOWFORM" USING COMAREA.
BASIC
120 CALL VSHOWFORM(C(*))
FORTRAN
CALL VSHOWFORM(COMAREA)
SPL/PASCAL
VSHOWFORM (COMAREA);
The calls shown above display a form with optional data and enhancements
on the terminal screen opened with the comarea, COM1.