HP 3000 Manuals HP 3000 Manuals
VGETBUFFER
Copies entire contents of data buffer from memory to an application.
Syntax
VGETBUFFER {comarea,buffer,buflen}
Parameters
comarea Must be comarea name specified when the forms file was
opened with VOPENFORMF. If not already set, the
following comarea items must be set before calling
VGETBUFFER:
cstatus Set to zero.
language Set to the code identifying the
programming language of the calling
program.
comarealen Set to total number of two-byte words
in comarea. Must be at least 70 words
in length if the ARB feature is used.
buffercontrol Set bit 15 to 1 to indicate that data
is to be transformed according to the
ARB specifications.
VGETBUFFER may set the following comarea items:
cstatus Set to nonzero value if call
unsuccessful.
bufferstatus Bit 15 set to 1 if data conversion
successful.
buffer Character string in an application to which the data in
the data buffer is copied. Could also be a record
describing the ARB, i.e., non-CHAR data.
buflen Two-byte integer variable that specifies the number of
bytes to be transferred to the user buffer.
Discussion
This intrinsic transfers data from the data buffer in memory to the area
in an application specified by the buffer parameter. The data includes
everything in the unprotected and display-only fields on a form.
Previously, data in the data buffer was stored in the order of the fields
on the form, and specific fields could be moved from the buffer with
VGETFIELD or VGETtype. Now, the Application-ready Buffer (ARB) allows
you to specify, using the FORMSPEC ARB feature, the order in which the
application should receive the fields in the buffer, and the data type
conversion to be performed on each (see the discussion on creating an ARB
in Section 3). You need no longer use VGETtype to convert individual
fields; a call to VGETBUFFER accomplishes the task.
The number of bytes moved from the data buffer is based on the number of
bytes specified in the buflen parameter, or the number of bytes specified
by the dbuflen item in the comarea (refer to Table 6-5), whichever is
less. The dbuflen item is set by VGETNEXTFORM when the current form is
read into memory. For example, if there are 20 bytes in the data buffer
(dbuflen is 20), and the user requests 50 bytes in the buflen parameter,
only 20 bytes are transferred. Conversely, if the user requests 10 bytes
through the buflen parameter, but there are 20 bytes in the data buffer
(dbuflen is 20), only 10 bytes are transferred.
Special Considerations
Designers using the ARB feature in VGETBUFFER should be aware that
damaging run-time errors could occur if the application is inadvertently
run on a system that has a VPLUS/V version earlier than B.05.00.
To prevent this, the designer should do three things:
1. Document the product with a clear warning that VPLUS/V version
B.05.00 or later MUST be used.
2. Use the VPLUS/V intrinsic HP32209 in the code. This intrinsic
checks to make sure that you are using the proper VPLUS/V version.
If not, the application should terminate with an appropriate
message.
3. Check offset 65 (bufferstatus) in the comarea on return from
VGETBUFFER. Bit 15 will be set to 1 if VGETBUFFER performed the
conversion successfully. In other words, the application must
check both status and bufferstatus to be sure that the data was
correctly converted.
Example
COBOL
01 ORDER-ENTRY.
03 PART-NO PIC X(7).
03 DESCR PIC X(12).
03 QTY PIC S9(4).
03 UNIT-PR PIC S9(4)V9(2).
03 TOTL-PR PIC S9(6)V9(2).
:
:
CALL "VGETBUFFER" USING COMAREA, ORDER-ENTRY, DBUFLEN.
BASIC
340 L1=D1 <----D1 is the dbuflen word in C
350 CALL VGETBUFFER(C(*),D$,L1)
FORTRAN
CALL VGETBUFFER(COMAREA,D1,DBFLEN)
SPL/PASCAL
BYTE ARRAY D1 (0:36) ;
:
:
VGETBUFFER(COMAREA,D1,DBUFLEN);
The examples above transfer the contents of the data buffer in memory to
an application. The current value of dbuflen is specified as the user
buffer length.