HP 3000 Manuals HP 3000 Manuals
VGETFIELD
Copies contents of specified field from data buffer in memory to an
application.
Syntax
VGETFIELD {comarea,fieldnum,fieldbuf,buflen,actualen,nextfldnum}
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
VGETFIELD:
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.
VGETFIELD may set the following comarea items:
cstatus Set to nonzero if call unsuccessful, or
if requested field has an error, or if
fieldnum is unacceptable.
fieldnum Two-byte integer variable containing the number assigned
to the field by FORMSPEC.
fieldbuf Character string in an application to which data entered
in specified field is copied.
buflen Two-byte integer variable that specifies the number of
bytes in fieldbuf.
actualen Two-byte integer to which VGETFIELD returns the number
of bytes actually moved to fieldbuf.
nextfldnum Two-byte integer to which VGETFIELD returns the number
of the next field in screen order. If there are no more
fields, zero is returned. If fieldnum was set to zero
or a negative number by an application, this is an
error. In this case, VGETFIELD returns the number of
the first field in screen order in nextfieldnum.
Discussion
VGETFIELD transfers the contents of the field specified by fieldnum from
the data buffer to a variable in an application. This is in contrast to
VGETBUFFER which retrieves data according to the current field layout.
When considering what is transferred by VGETFIELD, keep in mind that all
the fields defined for a particular form in FORMSPEC are assigned
numbers. The number assigned to a field by FORMSPEC does not change
regardless of any changes to the field's position in the form or to its
length and does not necessarily correspond to the screen order. The
field numbers on a form can only be changed with the batch command,
RENUMBER, as described in Section 7. The field number must not be
confused with the field's position in the data buffer, which corresponds
to its position in the form according to screen order, not assigned field
number.
If the number of bytes specified by buflen is less than the field size,
the rightmost bytes are truncated. If the requested field has an error,
its value is returned, but cstatus is set to an error number indicating
the field error flag is set.
Following a successful transfer, actualen contains the exact number of
bytes transferred to fieldbuf, the user buffer; nextfldnum is set to the
number of the next field in screen order, or to zero after the last field
is processed.
Note that VGETFIELD does not convert the data it moves. If you want to
convert the field, you must use VGETtype, where type specifies the data
type to which the field is converted.
Example
COBOL
DATA DIVISION.
77 ORD-LEN PIC S9(4)COMP.
77 ITEM-LEN PIC S9(4)COMP.
77 FIELD-NUM PIC S9(4)COMP.
77 ACTUAL-LENGTH PIC S9(4)COMP.
77 NEXT-FIELD PIC S9(4)COMP.
01 ORDER-ENTRY.
03 PART-NO PIC X(8).
03 UNIT-PR PI C 9 (4) V9 (2).
03 QUANTITY PIC S9(4)COMP.
03 TOTAL-PR PIC 9(5)V9(2).
03 PART-DESCR PIC X(12). <----------------- field number "2"
:
:
PROCEDURE DIVISION.
:
:
MOVE 12 TO ITEM-LEN.
MOVE 2 TO FIELD-NUM.
CALL "VGETFIELD" USING COMAREA, FIELD-NUM, PART-DESCR OF ORDER-ENTRY,
ITEM-LEN, ACTUAL-LENGTH, NEXT-FIELD.
BASIC
350 F1=2
355 L1=12
360 CALL VGETFIELD(C(*),F1,P$,L1,A1,N1)
FORTRAN
FIELD=2
LEN=12
CALL VGETFIELD(COMAREA,FIELD,PARTDES,LEN,LENFLD,NXTFLD)
SPL/PASCAL
INTEGER
FIELD,
LEN;
BYTE ARRAY PARTDES(0:11);
:
:
FIELD:=2;
LEN:=12;
VGETFIELD(COMAREA,FIELD,PARTDES,LEN,ACTUAL'LEN,NEXT'FLD);
Assume that the contents of field number "2" is to be copied, and that
the length of this field is 12 bytes. The calls shown above copy the
contents of this field into a variable in an application.