HP 3000 Manuals HP 3000 Manuals
VGETFORMINFO
Returns information about specified forms to an application.
Syntax
VGETFORMINFO {comarea,infobuf,infobuflen}
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
VGETFORMINFO:
cstatus Set to zero.
comarealen Set to total number of two-byte words
in comarea.
VGETFORMINFO sets the following field:
cstatus Set to nonzero value if call
unsuccessful.
infobuf A record through which you pass the request for form
information and to which the intrinsic returns the
specified information. This parameter must be
initialized to spaces before filling in your request and
calling VGETFORMINFO. The layout of infobuf is shown in
Table 6-12. The two required fields of infobuf pass
user-supplied parameters to VGETFORMINFO as follows:
numofentries Specifies how many forms you want
information about.
entrylength Indicates how many two-byte words of
information (maximum 36 as shown in
Table 6-12) you want about each form.
The rest of infobuf (beginning with word 3) must consist
of entrylength number of two-byte words for each form
you want information about. Thus, the total length of
infobuf in two-byte words must be as follows;
2 + (entrylength * numofentries)
You may pass one or both of the two permissible keys,
which must be passed in the position indicated in the
table. Remember that infobuf must be initialized to
spaces before filling in the parameters and any key.
infobuflen Two-byte integer variable set to the number of two-byte
words in infobuf.
Discussion
This intrinsic accesses an internal table and places information about
forms into infobuf. You tell VGETFORMINFO how many forms and how much
information you want about each form.
Table 6-12. Form Information Buffer
------------------------------------------------------------------------------------------
| |
| Data Type Position Contents Comments |
| |
------------------------------------------------------------------------------------------
| |
| Integer (Two-byte) 1 numofentries Required |
| |
| |
| |
| 2 entrylength Required |
| |
------------------------------------------------------------------------------------------
| |
| Character Array 3-10 Form name Permissible key; last |
| (16-byte) byte of position 10 is |
| unused (15 bytes |
| maximum). |
| |
------------------------------------------------------------------------------------------
| |
| Integer (Two-byte) 11 Form number Permissible key; forms |
| are ordered within the |
| forms file in alphabetic |
| order, thus this argument |
| reflects the order of the |
| form within the file, not |
| a permanently assigned |
| form numeric identifier. |
| As a result, the number |
| may change if the forms |
| file is recompiled. |
| |
| |
| |
| 12 Number of fields in form. |
| |
| |
| |
| 13 Data buffer length in |
| bytes. |
| |
------------------------------------------------------------------------------------------
| |
| Character Array 14-21 Name of next form. Last byte of position 21 |
| (16-byte) is unused. |
| |
------------------------------------------------------------------------------------------
| |
| Character 22 Repeat option. First byte of position |
| (Two-byte) 22; may be N, A, or R. |
| |
| |
| |
| 22 Next form option Last byte of position 22; |
| may be C, A, or F. |
| |
------------------------------------------------------------------------------------------
| |
| Integer Array 23-38 Fields in error. Bit map; bit is on if |
| (32-byte) field is in error. |
| |
------------------------------------------------------------------------------------------
Passing INFOBUF Without Entering Keys
Keys are optional. If you do not supply a key to indicate the first form
you want information about, VGETFORMINFO starts with the first form not
already reported on by the current call.
As an example, suppose you want information about 3 forms, and you enter
form number 6 as a key. VGETFORMINFO returns information about forms 6,
7, and 8. If you enter no keys, VGETFORMINFO returns information about
forms 1 through 3.
Table Wraparound
VGETFORMINFO starts over with the first form in the file if you request
information about more forms than are in the file or, if when you pass a
key, your request goes beyond the end of the file.
Suppose a file has 10 forms. If you request information about 5 of the
forms and enter form number 8 as a key, VGETFORMINFO returns information
about forms 8 through 10, and then goes to the beginning of the file and
returns information about forms 1 and 2.
Error Determination
To enable applications to determine which fields are in error for a given
form at run-time, VGETFORMINFO optionally returns a 32-byte bit map
containing these error flags to show which fields failed the edit checks.
Each field in a form is represented by a bit in the bit map according to
its field creation number. The bit map is a 32-byte logical array to
accommodate the maximum of 255 field numbers. The most significant (left
most) bit of the first byte in the bit map array represents the field
with the field number equal to 1 as assigned by FORMSPEC. For example,
the field assigned a field number of 17 would be represented by the
most-significant bit of the third byte in the array. If a field is in
error, the corresponding bit representing that field will be set to a
one. Otherwise, the value will be zero.
The bit map is valid for the current form only. If the bit map is
requested for any other form, it will contain all zeros. Therefore, a
value of zero should not be interpreted to mean the field is not in error
for the current form, (i.e., the last form retrieved by VGETNEXTFORM).
Furthermore, bit positions representing nonexistent field numbers for a
given form will contain a value of zero.
To retrieve the bit map, the user-supplied parameter entrylength in
infobuf should contain a value of 36. This is to inform VPLUS/V to
supply 36 two-byte words of information pertaining to the form requested.
The last 16 two-byte words will contain the bit map indicating which
fields are in error.
The infobuflen parameter normally passed to VGETFORMINFO is calculated
using the entrylength of 36. To request the bit map for the current
form, the calculation is as follows:
2 + (entrylength * numofentries)
where entrylength is equal to 36 and numofentries is equal to 1. Thus,
the infobuflen parameter should contain a value of 38 when calling
VGETFORMINFO.
For languages which provide bit manipulation capability, the bits can be
shifted left or right to determine which bits are on. For other
languages, a mask may be used with the bit map to determine whether a bit
is on or off. An intrinsic called BITMAPCNV is available to help decode
and set bits in the bit map. Refer to Appendix I for more information.
Example
COBOL
DATA DIVISION.
:
WORKING-STORAGE SECTION.
01 INFOBUF.
05 NUMBER-OF-ENTRIES PIC S9(4) COMP.
05 ENTRY-LENGTH PIC S9 (4) COMP.
05 ENTRY-TABLE OCCURS 9 TIMES.
10 FORM-NAME PIC X15.
10 FILLER PIC X.
10 FORM-NUMBER PIC S9(4) COMP.
10 NUMBER-OF-FIELDS PIC S9(4) COMP.
10 BUF-LENGTH PIC S9(4) COMP.
10 NEXT-FORM PIC X(15).
10 FILLER PIC X.
10 REPEAT-OPTION PIC X.
10 NFORM-OPTION PIC X.
01 INFOBUFLEN PIC S9(4) COMP VALUE 62.
:
PROCEDURE DIVISION.
:
MOVE SPACES TO INFOBUF.
:
MOVE 3 TO NUMBER-OF-ENTRIES.
MOVE 20 TO ENTRY-LENGTH.
MOVE "FORM1 " TO FORM-NAME.
CALL "VGETFORMINFO" USING COMAREA, INFOBUF, INFOBUFLEN.
The example shown above illustrates the data declaration of infobuf and
infobuflen and the passing of parameters to VGETFORMINFO. Note that
before the intrinsic is called, infobuf is initialized to spaces (not
zeros). The intrinsic copies 20 two-byte words of information about 3
forms in collating sequence order, beginning with the form named FORM 1,
into infobuf.