 |
» |
|
|
|
Every application that calls VPLUS intrinsics must allocate
a data area in the application for communication with the intrinsics.
This area (called the comarea) is the first, and often the only, parameter in every
call to a VPLUS intrinsic. Table 6-4 “Outline of Communication Area Contents” briefly outlines
the contents of this communication area; Table 6-5 “Communication Area Contents for Data Capture
Devices” outlines
the items used for data capture devices. It is essential to successful
operation of your application that the comarea be defined exactly as shown in these tables; items
that are "Reserved for system use" should not be set or used after
they are initialized. The comarea items listed in Table 6-4 “Outline of Communication Area Contents” and are defined
below. Table 6-4 Outline of Communication Area Contents Data Type | Position | Offset | Name | Function |
|---|
Integer (Two-byte) | 1 | 0 | cstatus | status, error returns | 2 | 1 | language | programming language of calling program | 3 | 2 | comarealen | length of comarea length of comarea in two-byte words | 4 | 3 | usrbuflen | comarea extension length (BASIC) | 5 | 4 | cmode | current mode (collect or browse) | 6 | 5 | lastkey | code of last key pressed | 7 | 6 | numerrs | number of errors in current form | 8 | 7 | windowenh | code for window enhancement | 9 | 8 | multiusage | Child of previous form | 10 | 9 | labeloption | function key label indicator | Character Array (16-byte) | 11-18 | 10-17 | cfname | current form name (15 characters) | 19-26 | 18-25 | nfname | next form name (15 characters) | Integer (Two-byte) | 27 | 26 | repeatapp | current form flag (repeat/append) | 28 | 27 | freezapp | next form flag (freeze/append) | 29 | 28 | cfnumlines | number of lines in current form | 30 | 29 | dbuflen | data buffer length (in bytes) | Integer (Two-byte) | 31 | 30 | Reserved for system use. | — | Logical (Two-byte) | 32 | 31 | lookahead | flag for background form load in VREADFIELDS | | | 33 | 32 | deleteflag | delete current batch record | | | 34 | 33 | showcontrol | control flags for VSHOWFORM | Integer (Two-byte) | 35 | 34 | Reserved for system use. | — | Integer (Two-byte) | 36 | 35 | printfilnum | MPE file number of forms file print file | | | 37 | 36 | filerrnum | MPE file error number from FCHECK | | | 38 | 37 | errfilenum | MPE file number, error message file | | | 39 | 38 | formstoresize | number of forms in buffer | Integer (Two-byte) | 40-42 | 39-41 | Reserved for system use. | — | Integer (4-byte) | 43-44 | 42-43 | numrecs | number of records in batch file | | | 45-46 | 44-45 | recnum | record # of current batch record | Integer (Two-byte) | 47-48 | 46-47 | Reserved for system use. | — | Logical (Two-byte) | 49 | 48 | filen | MPE file number of terminal | Integer (Two-byte) | 50-54 | 49-53 | Reserved for system use | — | Logical (Two-byte) | 55 | 54 | retries* | max number of retries | | 56 | 55 | termoptions* | suppress msgs. and autoread | | 57 | 56 | environ | term environment: Sys LDEV | | 58 | 57 | usertime* | user defined time out period in seconds | | 59 | 58 | identifier | type of terminal | | 60 | 59 | labinfo | number of function keys; length | Integer (Two-byte) | 61-64 | 60-63 | Reserved for system use | — | | 65 | 64 | buffercontrol | control ARB processing | | 66 | 65 | bufferstatus | indicate successful data conversion | | 68-70 | 67-69 | Reserved for system use | — | Refer to Table 6-5 “Communication Area Contents for Data Capture
Devices” | 71-85 | 70-84 | — | These comarea items are only referenced when using data capture
devices. |
Not supported on data capture devices. Table 6-5 Communication Area Contents for Data Capture
Devices Data Type | Position | Offset | Name | Function |
|---|
Integer (Two-byte) | 61-70 | 60-69 | Reserved for system use | — | | 71 | 70 | numflds | number of fields on current form | | 72 | 71 | splitpause | length of pause (in seconds) | | 73 | 72 | leftmodule | type of terminal options | | 74 | 73 | rightmodule | type of terminal options | | 75 | 74 | keyboard | type of keyboard | | 76 | 75 | display | type of display | | 77 | 76 | keyboardover | whether to override or not | Character (Two-byte) | 78 | 77 | errorlight | error detection light | Logical (two-byte) | 79-80 | 78-79 | userlightson | Lights on/off indicator | Integer (two-byte) | 81-85 | 80-84 | Reserved for system use | — |
| | | |  | NOTE: The comarea size required for each feature can be summarized
as follows: FEATURE COMAREALEN Data Capture Terminal 85
ARB Feature 70
All Others 60 | | | | |
The position of each item in comarea is given as a two-byte word offset in the table;
for SPL programs the word offset starts with zero; for all other
programs, it starts with one. The comarea must be at least 60 two-byte words long (120 bytes) unless you
are working with an ARB. To take advantage of the ARB feature, the comarea must be at least 70 words long.
The COMAREA array size must be at least as large as the sum of the
values of comarealen plus usrbuflen. For BASIC programs, the area must be extended to include space
for the form and data buffers and for internal tables. For non-BASIC
programs, the DL area is used for these buffers and internal tables,
and the communication area need not be extended. However, non-BASIC
programs must be careful not to use the DL area for other purposes
when using VPLUS. Refer to Appendix E for more information on the
DL area. Before calling the first VPLUS intrinsic, you should initialize
the entire comarea to binary zeroes. Do not change comarea values between calls except under documented conditions. Then,
if you are coding in a programming language other than COBOL, you
must set language to the code for the programming language you are
using. If you are coding in BASIC, you must set usrbuflen to the number of two-byte words needed for the comarea extension.
This value is displayed on the forms file listing generated by FORMSPEC. Finally,
in order to provide for possible future extensions to comarea, set comarealen to its current total length. Parameters | |
- cstatus
Two-byte integer to which the intrinsic status is
returned. Set to zero if the call is successful; to a nonzero value
if an error occurs. If the error is an MPE file error, a file error
number is also returned to filerrnum (Refer to Appendix B for a list of the error codes
that may be returned to cstatus with their meaning.) It is up to the user to provide
error-handling routines and to reset cstatus. - language
Two-byte integer that indicates the programming
language of the calling program: 5 = PASCAL//HP FORTRAN 77//HP BUSINESS BASIC //C/XL
The language must be set by the calling program before any intrinsic
is called. - comarealen
Two-byte integer that indicates the total length
of comarea (use 6 0 for terminals; 85 for data capture devices).
The comarealen should be specified for each comarea to simplify future changes to the length of comarea. - usrbuflen
For BASIC programs only, usrbuflen must be set to the number of two-byte words to be
appended to comarea for the form and data buffers and internal tables.
(Note that the number of bytes required for this extension is printed
when a form is listed through FORMSPEC.) The usrbuflen need not be set by other languages since VPLUS automatically uses
the DL area for buffers and internal tables. The usrbuflen does not include the comarea length specified in comarealen, but it must be contiguous to and immediately follow comarea. - cmode
Indicates whether current mode of data entry is
collect. If you want to save the form sequence for $RETURN, you must set cmode to zero before calling VGETNEXTFORM. - lastkey
Two-byte integer set to a number between -256 and
26 (or -999) by VREADFIELDS to indicate user response, which can be ENTER or the last function key pressed at a standard terminal,
the last field touched for a touch terminal, or the last key pressed
for data capture devices. The value returned can be interpreted
as follows: For standard terminals, 0-8 is returned: For touch, in addition to 0-8, -256 to -1 (or -999) is returned: -1 to -256 = field number of touched field -999 = no field in area touched by user
For data capture devices, - 1 to 26 is returned: - numerrs
Two-byte integer set to the number of errors found
when a form is edited according to FORMSPEC edit specifications. - windowenh
Two-byte integer in which the right byte contains
a USASCII code for the window line enhancement. The code specifies
any combination of enhancements according to Table 6-6 “Codes for the Window Line Enhancement”;
zero indicates no enhancement. For example, to indicate Half -Bright,
Inverse Video, windowenh is set to the character J. Specifying an enhancement code with windowenh is independent, and in addition to, any color enhancement
specified with FORMSPEC. On data capture devices any enhancement except blinking is
ignored. The entire display blinks, not just the field in error.
Table 6-6 Codes for the Window Line Enhancement | @ | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O |
|---|
Half-Bright | | | | | | | | | X | X | X | X | X | X | X | X | Underline | | | | | X | X | X | X | | | | | X | X | X | X | Inverse Video | | | X | X | | | X | X | | | X | X | | | X | X | Blinking | | X | | X | | X | | X | | X | | X | | X | | X | Stop enhancement | X | | | | | | | | | | | | | | | |
- multiusage
Two-byte integer that indicates whether the current
form is in the same family as the previous form but is not the parent
form. 0 = Not in the current family 1 = Child or sibling to previous form
- labeloption
Two-byte integer that indicates whether function
key labels are to be used. 0 = Default function key labels are used (F1 - F8 ). 1 = User-defined labels are to be used
Space to store the labels defined either in FORMSPEC or specified
with VSETKEYLABELS is allocated in the user stack by VOPENFORMF. The labeloption must be set prior to a call to VOPENFORMF so that it can be determined whether or not to
allocate space for user-defined function key labels. - cfname
A 16-byte character array containing the name of
the current form (15 characters). Updated by VGETNEXTFORM. | | | | | NOTE: All comarea entries start on two- or four-byte word boundaries.
Thus, the 16-byte character array items cfname and nfname are each followed by one filler byte that is not
part of the name. | | | | |
- nfname
A 16-byte character array containing the name of
the next form (15 characters). Required by VGETNEXTFORM and updated when necessary by VGETNEXTFORM. The nfname may be set by an application. The nfname may contain one of the following values: - formname
Identifies the form to be read from the forms file. - $REFRESH
Clear and reset the terminal. Set the internal flags
to indicate to VSHOWFORM to redisplay the current form, window and data buffer.
For terminals with local form storage, clear form storage memory
and reinitialize the form storage directory. - $RETURN
Retrieve previous different form; if current form
is the head form, the current form is retrieved. There is a maximum
of eight forms; after eight, each additional form replaces the most
recent form. - $HEAD
Retrieve first form displayed when the forms file
is executed (the "head" form). - $END
For ENTRY only, terminate execution of VGETNEXTFORM; return to calling program without resetting any comarea items.
- repeatapp
Two-byte integer that indicates whether the current
form is a repeating form and, if so, whether it is to be appended
to itself: 0 = Normal sequence, neither repeat nor append 2 = Repeat current form, appending it to itself
- freezapp
Two-byte integer that indicates whether the screen
is to be cleared when the next form is displayed, or whether next
form is to be appended to current form, and, if appended, whether
current form is to be frozen on the screen. If the current form
is frozen, it remains on the screen and the next form is rolled
off when the screen is full; otherwise, the current form is rolled
off the screen when the screen is full. The freezeapp is specified as: 0 = Clear screen, neither freeze nor append current
form 1 = Append next form to current form 2 = Freeze current form and append next form to
it
- cfnumlines
Two-byte integer that specifies the number of lines
in the current form. The cfnumlines is used by VPRINTFORM to print the form off-line. - dbuflen
Two-byte integer that specifies the number of bytes
in the data buffer for the current form. Set by VGETNEXTFORM, this length is the sum of all the concatenated
data fields in the form, including any display-only fields. - lookahead
Two-byte integer that indicates whether or not look-ahead
form loading is to occur when VREADFIELDS is called. - 0 - ON
The next form, as defined in FORMSPEC, is loaded
before the current form is read if point-to-point data communications
is being used. If multipoint data communications is being used,
the next form is loaded after the current form is read. The least
recently used form in the terminal's local form storage memory could
be purged to make room for the new form if there is no room in the
terminal or there are no available entries in the form storage directory. - 1 - OFF
No look-ahead form loading is performed, and no
forms in the terminal's local form storage memory are purged (however,
forms could still be purged if VSHOWFORM is called to preload forms; see the discussion
of VSHOWFORM later in this section).
If lookahead is zero and a family member of the form specified
as the next form is already in the terminal's local form storage
memory, the new form is not loaded. Instead, the family member is
changed into the required form when it is displayed. The lookahead feature is ignored if the terminal does not have
form storage capability. - deleteflag
Two-byte logical flag that indicates whether the
current batch record has been or is to be deleted. The deleteflag is returned by VREADBATCH and used by VWRITEBATCH: FALSE (all zeros) = Current batch record not deleted TRUE (all ones) = Delete current batch record
- showcontrol
Control options for VSHOWFORM or VREADFIELDS. These bits remain set until an application resets
them. The following bits can be set: - bit 15 = 1
Force form to be written to the terminal screen;
overrides VPLUS optimization. - 14 = 1
Force data and field enhancements to be written
to the terminal screen; overrides VPLUS optimization. - 13 = 1
Force window line to be written to the terminal
screen; overrides VPLUS optimization. - 12 = 0
Stop after displaying a form without fields (default);
data capture devices only. - 1
Do not stop after displaying a form without fields;
data capture devices only. - 11 = 0
Do not put a right closing bracket (]) on all input
fields (default); data capture devices only. - 1
Put a right closing bracket (]) on all input fields;
data capture devices only. - 10 = 0
Enable the keyboard for input (default). - 1
Do not enable the keyboard. - 9 = 0
Do not preload form into the terminal's local form
storage memory but write it directly to the screen (however, VSHOWFORM always checks to see if the form is in local storage
already) (default). - 1
Preload form into the terminal's local form storage memory
if it is not already there. Forms could be purged from local form
storage if there is not room for the form (this could occur even
when lookahead is 1). - 8 = 0
Do not enable AIDS, MODES, or USERKEYS (default). - 1
Enable AIDS, MODES, and USERKEYS. These keys are enabled after a form is displayed on the
screen and remain enabled until bit 8 is reset to 0. - 7-1 = 0
The undefined bits (7-1) must be initialized to
zero. - 0 = 0
Do not enable the touch feature (default). - 1
Enable the touch feature.
Bits 15, 14, and 13 are used to override VSHOWFORM optimization (where only information that has
changed since the last call to VSHOWFORM is written to the terminal screen). Bits 12 and
11 are used with VREADFIELDS on data capture devices. Bit 10 is used when consecutive
calls are made to VSHOWFORM (no call to VREADFIELDS in between). Bit 9 is used with terminals having
local form storage capability. Bit 8 is used to allow access to the function control keys
on the HP 239X and HP 262X terminals. For example, device control
and device mode keys can be used for local printing to an integral
printer. Enabling the function control keys using bit 8 is recommended
for experienced users only. Misuse or accidental use of certain
function control keys could yield undesirable results. Bit 0 is used to activate touch available with terminals with
the touch feature. VREADFIELDS returns lastkey with the field number of the touched field (as a
negative number). - printfilnum
MPE file number to which a form is printed by VPRINTFORM. The formal designator is FORMLIST. - filterrnum
MPE file error number (FCHECK number) returned by VPLUS intrinsics when an MPE
file error occurs. (Refer to Appendix B for a list of the errors that
return a number to filerrnum). - errfilenum
MPE file number of the error message file used by VERRMSG. - formstoresize
Two-byte integer that indicates the number of entries
allowed in the form storage directory. - -1
No local form storage is to be performed. For the
HP 2626A terminal the workspace configuration is under user control.
VPLUS does not modify terminal workspace, window, or datacomm configuration,
and either terminal port can be used. - 0
No local form storage is to be performed. For the
HP 2626A terminal VPLUS reconfigures the workspaces and windows
to the terminal's default values, but only the first terminal port
can be used. - 1..255
One through 255 forms can be stored locally. For
the HP 2626A terminal any value greater than four defaults to four
(allowing an application to run on either the HP 2626A, HP 2394A,
or HP 2624B terminals), where four indicates that one form is the
displayed form and three forms are stored in the HP 2626A local
forms storage. VPLUS reconfigures the HP 2626A terminal workspaces and
windows to support local form storage, but only the first terminal
port can be used.
The formstoresize allows the user to control the number of entries allowed
in the form storage directory on the user stack and must be set prior
to opening the terminal and the forms file. The space required is listed
on the forms file listing generated by FORMSPEC. When designing forms for local form storage terminals, keep
in mind that large forms need a substantial amount of terminal display
memory. For forms that are greater than 24 lines, so much terminal
display memory may be used that insufficient terminal memory is
available for form storage. If so, VPLUS resets formstoresize to zero and no local form storage is performed. - numrecs
Four-byte integer that contains the number of nondeleted
records in the current batch file. It is used by the V..BATCH intrinsics. - recnum
Four-byte integer set to the current record number
in the batch file. (Note that record numbers start with zero.) The recnum must be set by the program before writing to or reading
from the batch file. It is used by the VREADBATCH and VWRITEBATCH intrinsics. - filen
MPE file number used to identify the terminal. - retries
Maximum number of retries. value = 0 Use default value (four retries) value > 0 Use this value as maximum value < 0 do not perform any retries
- termoptions
Terminal control options: - bits
Title not available (Parameters ) - 0-8
reserved for system use - 9-10
01 = enables ENTER /function key timeout in VREADFIELDS. 11 or 00 = disables ENTER /function key timeout in VREADFIELDS. (default) - 11-12
10 = do not clear the screen at terminal open or
close. - 13-14
01 = enables AUTOREAD in VREADFIELDS. 11 or 00 = disables AUTOREAD. (default) (AUTOREAD causes the terminal to do a programmatic enter instead
of waiting for the user to press ENTER.) - 15
0 = Sound bell as usual, (default) 1 = Suppress bell.
- environ
First byte is the logical device number of the terminal.
The remaining byte is reserved for system use. - usertime
If enabled, the value in this position is used as
the number of seconds to wait for either ENTER or a function key to be pressed. Consult Appendix G for
more information regarding enabling user timeouts. - identifier
VPLUS identifier for the terminal model being used.
See Appendix G for the interpretation of the contents of this word. - labinfo
First byte is the length of key labels (in bytes);
Second byte is the number of key labels that VPLUS uses on the terminal. - buffercontrol
Controls the ARB options. The bit settings are as
follows: Bit 15 (ARB option) 0 = return data "raw": no reordering or conversion. 1 = reorder and convert data according to ARB specifications. The remaining bits must be set to zero. Note that VGETBUFFER will not change these settings (see Section 6, VGETBUFFER, for special considerations). - bufferstatus
Return parameter indicating that VGET/PUTBUFFER performed the data conversion successfully (but
15 in offset 65 will be set to 1).
| | | | | NOTE: STATUS in the COMAREA will be non-zero if the conversion is not successful. | | | | |
In addition to the above comarea descriptions, the data capture devices use the following items: Parameters | |
- splitpause
Length of time in seconds to pause between the presentation
of lines of text on the single line alpha display. Default is 3
seconds. -1 - wait for user to press key >0 - pause specified number of seconds
- leftmodule
MPE determines which, if any, module is present. - rightmodule
MPE determines which, if any, module is present. | | | | | NOTE: VPLUS does not communicate with the RS-232 interface
(3) or the HP-IB interface (7). | | | | |
- keyboard
Type of keyboard used with terminal. 1 - standard keyboard (12 function keys with values
of -1,0,17...26). 2 - alphanumeric keyboard (28 function keys with
values of - 1,0...26).
- display
Indicates the terminal type of display. VPLUS does not support the terminal that has numeric display. - keyboardover
Two-byte integer determining whether to override
input on the keyboard or not. Default is 0. -1 - Override and enable the keyboard without regard
to forms design. 0 - Do not override. Allow input from the devices
specified during the form design (in the Processing Specification
area).
- errorlight
Indicates which light to be turned on when an error
is detected. The default is E, but this can be changed to @ or any letter from A to P. The second byte is reserved for system use. - lightsOn
Two two-byte integers to indicate whether or not
lights are to be turned on during run time. The turning on of lights
here does not affect the lights turned on during form design (in
the Process Specification area of the form). The default value is OFF, but this may be changed as follows: TWO-BYTE WORD 1, a "1" in:
bit position 0 > turns light of key "@" ON
1 "A" ON
2 "B" ON
... ...
14 "N" ON
15 "O" ON
TWO-BYTE WORD 2, a "1" in:
bit position 0 > turns light of key "P" ON |
The remaining bits are reserved for system use.
|
