HP 3000 Manuals HP 3000 Manuals
A
Chapter 10 The RPG Interface to VPLUS
VPLUS Communication Area Access
New COMAREA Enhancement
A new enhancement is now available for VPLUS application users, with
RPG/iX version A.00.14 and later. This enhancement now allows read/write
access to the VPLUS Communication Area (COMAREA). In the past this area
was managed only by RPG, consistent with the philosophy of making all
lower level I/O transparent to the user. One problem with this approach
is that, for certain errors on VPLUS intrinsic calls, the application
aborts with no possibility of recovery. With terminals and printers now
being attached to systems over networks where noise may be a problem,
this is no longer acceptable.
The new enhancement is enabled for your application by placing a
$CONTROL VPLUSCOM
record prior to your H-specification record. If you make no other
changes to your program, it will continue to run as before, with the
exception of certain errors on return from VPLUS intrinsic calls (COMAREA
status word not equal to zero). In general, these errors are on
intrinsic calls that access the terminal or printer, and will be
discussed in more detail later. If an error does occur in this case,
your program will not abort, and unexpected things could happen. To take
care of this situation, read on.
The VPLUS COMAREA is specified to be either 60 or 85 16-bit words in
length (see Chapter 6 of the HP VPLUS Reference Manual). It contains a
mix of binary integer, double integer, logical, and ASCII data. RPG/iX
allocates a space of 100 16-bit words for this, located in a special area
of the run-time data space (the additional space is there just in case
VPLUS ever expands the COMAREA). This area is zeroed out prior to running
a VPLUS application. When RPG/iX calls VOPENTERM to begin everything, it
makes the following initial settings:
* COMAREA length (word 3) to 85 (this is arbitrary, but allows
3075/6 terminals to be used)
* Language (word 2) to 5 (this specifies PASCAL, but works equally
well for C, in which RPG/iX is written)
* LABEL'OPTION (word 10) to the value specified in in the
workstation File Specification column 50
* FORM'STORE'SIZE (word 39) to the value specified in the
workstation File Specification FORMSDL continuation record (if
used)
$CONTROL VPLUSCOM
When the RPG/iX compiler detects the statement $CONTROL VPLUSCOM it sets
a flag used to control certain items, both at compile time and at run
time. It first creates two new reserved-word variables, *VC and *VSTAT.
*VC is declared to be a 200 character alpha-numeric array of 1 character
per element. Do NOT enter a File Extension Specification for this
variable. *VSTAT is declared to be a 6 digit numeric variable with 0
decimal places.
NOTE If you try using these items without the $CONTROL statement, you
will get a compile-time error. Since these are declared for you,
all you need to do is use them. No other declarations are
necessary.
Reserved word *VC.
The new reserved word *VC is initialized by the compiler to point to the
start of the COMAREA. Thus, *VC,1 and *VC,2 point to the left and right
bytes of the status word, for example. Since RPG does not have an
internal binary data type, management of the COMAREA by the user can be
somewhat tricky. This will be discussed later.
Reserved word *VSTAT.
The reserved word *VSTAT may be used as an ordinary 6-digit numeric
variable, but has special properties. For certain actions (SHOWMSG,
SHOW, RDTERM, SHODATA, PRINTX, CLRMSG) the COMAREA status word is copied
to this item on return from its VPLUS intrinsic call. The COMAREA status
word (the first 16-bit word of the COMAREA) contains the result of a
VPLUS intrinsic call. If the intrinsic executes correctly, this value
will be 0. If it fails, the value returned will be a binary integer
equal to an error number indicating the reason for the failure. It is
the user's responsibility to test *VSTAT immediately after the EXCPT
statement that initiates the action. An example will be shown later.
If *VSTAT is non-zero, you must set it to zero before taking any other
action (except possibly calling VERRMSG using INTR/IPARM operators - an
example of this will also be given later). To reset the status word to 0
do "Z-ADD0 *VSTAT ". This will set both *VSTAT and the COMAREA status
word to 0. ONLY the Z-ADD operator will do this. If you Z-ADD a
non-zero value to *VSTAT, *VSTAT will be set to this value but the
COMAREA status word will still be set to zero.
VPLUS Intrinsics
You may now call VPLUS intrinsics directly from your RPG program using
the INTR/IPARM operators. On return from the intrinsic call, *VSTAT is
updated with the COMAREA status word. You must test this yourself to
verify correct operation. This may only be done if you have specified
$CONTROL VPLUSCOM in your program, it is a workstation application, and
the intrinsic begins with the letter 'V' (a potential limitation, but OK
for now).
If HP releases a new intrinsic beginning with 'V', and you use it in your
VPLUS application, *VSTAT would still be updated from the status word in
the COMAREA, but it would be meaningless for the new call (unless,of
course, it is a new VPLUS intrinsic).
Due to the philosophy of managing lower-level I/O for the user, RPG/iX
takes care of calling VOPENTERM and VCLOSETERM. Since these intrinsics
also communicate with the terminal, it is possible they can also fail,
with the resultant abort. With this enhancement, RPG now tests the
status word on return from the call, and if non-zero will retry the
intrinsic up to 5 times, with a one second pause between each retry,
before aborting. This is done regardless of whether or not you have
specified the $CONTROL VPLUSCOM statement. It is also done for the
intrinsic VSHOWFORM where it is called from certain error routines not
accessible to the user.