HP 3000 Manuals HP 3000 Manuals
GET
Moves data to the data register from a data set, file, or formatted
screen.
Syntax
GET[(modifier)] source[,option-list];
GET retrieves a single entry from a data set or KSAM or MPE file after
rewinding the file or data set. It is also used to move data values into
the data register from a terminal under the control of a VPLUS screen.
Statement Parts
modifier To specify the type of access to the data set or
file, choose one of the following modifiers:
none For master sets, retrieves a
master set entry based on the
value in the argument
register. For MPE files, the
next entry is serially read.
For KSAM files, this option
does not use the match
register.
CHAIN Retrieves an entry from a
detail set or KSAM chain. It
retrieves the first entry to
meet any match criteria set
up in the match register.
The matching items must be
included in a LIST= option.
The contents of the key and
argument registers specify
the chain in which the
retrieval occurs. If no
match criteria are specified,
it retrieves the first entry
in the chain. If no matching
entry is found, GET issues a
run-time error.
CURRENT Retrieves the last entry that
was accessed from the data
set or the MPE or KSAM file.
DIRECT Retrieves the entry stored at
a specified record number in
an MPE or KSAM file, or a
detail or master set. Before
using this modifier, you must
store the record number as a
32-bit integer in the item
specified in the RECNO=
option.
FORM GET(FORM) displays a VPLUS
form on any VPLUS compatible
terminal and then waits for
the user to press ENTER to
transfer data from the form
to the data register. If the
user presses a function key
instead of ENTER, no data is
transferred unless the
AUTOREAD option is used.
KEY Executes a calculated access
on a master set using the key
and argument register
contents, but transfers no
data. The LIST= option
cannot be specified with this
modifier. (Use GET with no
modifier for a calculated
retrieval from a master set.)
This modifier is most useful
when you combine it with the
ERROR and/or NOFIND options
to check for the existence of
a key value in a master set.
It allows programmatic
control of the result of the
checking. It is the
equivalent of a CHECK or
CHECKNOT on a PROMPT
statement.
PRIMARY Retrieves the master set
entry stored at the primary
address of a synonym chain.
The primary address is
located through the key value
contained in the argument
register.
RCHAIN Retrieves an entry from a
detail set or a KSAM chain in
the same manner as the CHAIN
option, only in reverse
order. For a KSAM file this
operation is identical to
CHAIN.
RSERIAL Retrieves an entry from a
data set in the same manner
as the SERIAL option, except
in reverse order. If an
equal match without match
characters exists, Transact
will convert an RSERIAL
option to an RCHAIN option to
improve the application's
efficiency. For a KSAM or
MPE file, this operation is
identical to SERIAL.
SERIAL Retrieves an entry in serial
mode from an MPE or KSAM file
or a detail or master set.
It retrieves the first entry
that matches any match
criteria set up in the match
register. If an equal match
without match characters
exists, Transact will convert
an SERIAL option to an CHAIN
option to improve the
application's efficiency. If
no match criteria are
specified, it retrieves the
first entry in the file or
data set. The match items
must be included in a LIST=
option. If no entry matches
or if the file is empty, GET
issues a run-time error.
source The file, data set, or form to be accessed by the
retrieval operation. If the data set is not in the
home base as defined in the SYSTEM statement, the
base name must be specified in parentheses as
follows:
set-name(base-name)
For GET(FORM) only, source can be specified as any
of the following:
form-name Name of the form to be
displayed by GET(FORM).
(item-name Name of an item that contains
[(subscript)]) the name of the form to be
displayed by GET(FORM).
subscript can be included if
the referenced item is an
array item. (See "Array
Subscripting" in Chapter 3.)
* Displays the form identified
by the "current" form name;
that is, the form name most
recently specified in a
statement that references
VPLUS forms. Note that this
option is not the same as the
CURRENT option (described
under option-list), which
indicates the currently
displayed form.
& Displays the form identified
as the "next" form name; that
is, the form name defined as
"NEXT FORM" in the FORMSPEC
definition of the current
form, where current form
means the form name most
recently specified in a
statement that references
VPLUS forms.
option-list The LIST option is available with or without the
FORM modifier. Other options, described below, are
restricted for use as specified.
LIST=(range- list) The list of items from the
list register to be used for
the GET operation. For
GET(FORM) ONLY, items in the
range list can be child
items.
If the LIST= option is
omitted for GET(FORM), the
list of items named in the
list register, and either in
the SYSTEM statement or the
data dictionary for the form
are used.
The LIST= option should not
be used when specifying an
asterisk (*) as the source.
When the LIST= option is
used, only the items
specified in a LIST= option
have their match conditions
applied when the items are
included in the match
register. When the LIST=
option is omitted, items
which appear in the list
register and the match
register have their match
conditions applied.
Otherwise, the match
conditions for an item are
ignored.
The match register can be
used only with the modifiers
CHAIN, RCHAIN, SERIAL, or
RSERIAL.
For all options of
range-list, the data items
selected are the result of
scanning the data items in
the list register from top to
bottom, where top is the last
or most recent entry. (See
Chapter 4 for more
information on registers.)
The LIST= option has a limit
of 64 individually listed
item names. A range
limitation of 255 items for
TurboIMAGE data sets and 128
items for VPLUS forms also
exists.
All item names specified must
be parent items.
The options for range-list
and the data items they cause
GET to retrieve include the
following:
(item-name) A
single
data
item.
(item-nameX: All the
item-nameY) data
items
in the
range
from
item-nameX
through
item-nameY.
In
other
words,
the
list
register
is
scanned
for the
occurrence
of
item-nameY
closest
to the
top of
the
list
register.
From
that
entry,
the
list
register
is
scanned
for
item-nameX.
All
data
items
between
are
selected.
An
error
is
returned
if
item-nameX
is
between
item-nameY
and the
top of
the
list
register.
Duplicate
data
items
can be
included
or
excluded
from
the
range,
depending
on
their
position
on the
list
register.
For
example,
if
range-list
is A:D
and the
list
register
is as
shown,
Click here to view figure.
then
data
items
A, B,
C, D,
and D
are
selected.
For
database
files,
an
error
is
returned
if
duplicate
entries
are
selected.
If
item-nameX
and
item-nameY
are
marker
items
(see
the
DEFINE(ITEM)
verb),
and if
there
are no
data
items
between
the two
on the
list
register,
no
database
access
is
performed.
(item-nameX:) All
data
items
in the
range
from
the
last
entry
through
the
occurrence
of
item-nameX
closest
to the
top of
the
list
register.
(:item-nameY) All
data
items
in the
range
from
the
occurrence
of
item-nameY
closest
to the
top
through
the
bottom
of the
list
register.
(item-nameX, The
item-nameY, ... data
item-nameZ) items
are
selected
from
the
list
register.
For
databases,
data
items
can be
specified
in any
order.
For
KSAM
and MPE
files
or for
VPLUS
forms,
data
items
must be
specified
in the
order
of
their
occurrence
in the
physical
record
or
form.
This
order
need
not
match
the
order
of the
data
items
on the
list
register.
Does
not
include
child
items
in the
list
unless
they
are
defined
in the
VPLUS
form.
This
option
is less
efficient
to use
than
the
options
listed
above.
(@) Specifies
a range
of all
data
items
of
file-name
as
defined
in a
data
dictionary.
The
range-list
is
defined
as
item-
name1:item-
namen
for the
file.
(#) Specifies
an
enumeration
of all
data
items
of
file-name
as
defined
in the
data
dictionary.
The
data
items
are
specified
in the
order
of
their
occurrence
in the
physical
record
or form
as
defined
in the
data
dictionary.
This
order
need
not
match
the
order
of the
data
items
in the
list
register.
() A null
data
item
list.
That
is,
accesses
the
file or
data
set,
but
does
not
retrieve
any
data.
Options Available Without the Form Modifier
ERROR=label Suppresses the default error return that Transact
([item-name]) normally takes. Instead, branches to the statement
identified by label, and sets the stack pointer for
the list register to the data item item-name.
Transact generates an error at execution time if the
item cannot be found in the list register. The
item-name must be a parent.
If you specify no item-name, as in ERROR=label();,
the list register is reset to empty. If you use an
"*" instead of item-name, as in ERROR=label(*);, then
the list register is not changed. For more
information, see "Automatic Error Handling" in
Chapter 7.
LOCK Locks the specified file or database. The lock is
active the whole time that the GET executes. If LOCK
is not specified and a TurboIMAGE data set is being
accessed, no locking is done.
For a KSAM or MPE file, if LOCK is not specified on
GET but is specified for the file in the SYSTEM
statement. The file is then locked before each entry
is retrieved, remains locked while the entry is
processed by any PERFORM= statements, and is unlocked
briefly before the next entry is retrieved.
Including the LOCK option overrides SET(OPTION)
NOLOCK for the execution of the GET verb.
For transaction locking, you can use the LOCK option
on the LOGTRAN verb instead of the LOCK option on GET
if SET(OPTION) NOLOCK is specified.
For more information on locking, see "Database and
File Locking" in Chapter 6.
NOFIND Ensures that a matching entry is not present in the
referenced master set. If such an entry is found, an
error message is generated. If the STATUS option has
also been specified, the code returned in the STATUS
register for the error condition is 1, meaning that a
record was found.
NOMATCH Ignores any match criteria set up in the match
register.
NOMSG Suppresses the standard error message produced as a
result of a file or database error. All other error
actions occur.
RECNO=item-name With the DIRECT modifier, you must define item-name
[(subscript)] to contain the 32-bit integer. number (I(9,,4)) of
the record to be retrieved.
With other modifiers, Transact returns the record
number of the retrieved record in the 32-bit integer
item-name.
The item-name can be modified with subscript if the
referenced item is an array item. (See "Array
Subscripting" in Chapter 3.)
STATUS Suppresses the action defined in the Chapter 7 under
"Automatic Error Handling." You may want to add
status checking to your code if you use this option.
When STATUS is specified, the effect of a GET
statement is described by the 32-bit integer value in
the status register:
Status Meaning
Register
Value
0 The GET operation was successful.
-1 A KSAM or MPE end-of-file condition
for serial read or end-of-chain for
chain read has occurred.
>0 For a description of the condition
that occurred, refer to database or
MPE/KSAM file system error
documentation that corresponds to
the value.
1 If NOFIND is used and the record is
found.
STATUS causes the following with GET:
* The normal rewind done by the GET is
suppressed, so CLOSE should be used before
GET(SERIAL).
* The normal find of the chain head by the GET
is suppressed, so PATH should be used before
GET(CHAIN).
See "Using the STATUS Option" in Chapter 7.
Options Available Only With the Form Modifier
APPEND Appends the next form to the form specified in
this statement, overriding any freeze or append
condition specified for the form in its FORMSPEC
definition. APPEND sets the FREEZAPP field of the
VPLUS comarea to 1.
AUTOREAD Accepts any function key not specified in an
Fn=label option to transfer data from the form to
the data register. If a key has been specified in
an Fn=label option, GET does not execute AUTOREAD
for that key.
CLEAR Clears the previously displayed form when the
requested form is displayed, overriding any freeze
or append condition specified for the form in its
FORMSPEC definition. CLEAR sets the FREEZAPP
field of the VPLUS comarea to zero.
CURRENT Uses the form currently displayed on the terminal
screen; that is, it performs all the GET(FORM)
processing except retrieving and displaying the
form. Use this option to avoid the processing
that normally occurs when a new form is displayed.
CURSOR=field-name| Positions the cursor within the specified field.
item- Field-name identifies the field and the item-name
name[(subscript)] names the item identifying the field. The
item-name can be subscripted if an array item is
being referenced. (See "Array Subscripting" in
Chapter 3.)
_________________________________________________
NOTE To ensure that the cursor will be positioned
on the correct field, you must have a one to
one correspondence between the fields
defined in VPLUS. Transact determines where
to position the cursor by counting the
fields.
_________________________________________________
FEDIT Performs the field edits defined in the FORMSPEC
definition immediately before displaying the form.
FKEY=item-name Moves the number of the function key the operator
[(subscript)] presses in this retrieval operation to the single
word integer (I(4)) item-name. The item-name can
be subscripted if an array item is being
referenced. (See "Array Subscripting" in Chapter
3.) The function key is determined by the
contents of the field LAST-KEY in the VPLUS
comarea. It can have a value of 0 through 8,
inclusive, where 0 indicates the ENTER key and 1
through 8 indicate function keys 1 through 8,
respectively. Note that pressing f8 returns an 8
in the item field and does not cause an automatic
exit.
Fn[(AUTOREAD)]= label Control passes to the labelled statement if the
operator presses function key n. This option can
be repeated for each desired function key as many
times as necessary in a single GET(FORM)
statement. If (AUTOREAD) is included, transfers
the data from the form to the data register before
going to the specified label. F0, or ENTER,
always transfers data. This option is cancelled
by the STATUS option.
FREEZE Freezes the specified form and appends the next
form to the specified form, overriding any freeze
or append conditions specified for the form in the
FORMSPEC definition. FREEZE sets the FREEZAPP
field of the VPLUS comarea to 2.
INIT Initializes the fields in a VPLUS form to any
initial values specified for the form by FORMSPEC,
or performs any Init Phase processing specified
for the form by FORMSPEC. The INIT processing is
performed before the form is displayed on the
screen.
STATUS Suppresses the display of VPLUS field edit error
messages in window; Transact conversion messages
are sent to the window. Transfer control
immediately back to the program after the user has
pressed ENTER or the appropriate function key.
The STATUS option suppresses any branch specified
by Fn= label. If field edit errors exist,
Transact sets the value of the status field to a
negative count of the number of errors (given by
the NUMERRS field of the VPLUS comarea).
Otherwise, the value in the status field is 0.
WINDOW= ([field,] Places a message in the window area of the screen
message) and, optionally, enhances a field in the form.
The fields field and message can be specified as
follows:
field Either the name of the data
item for the field to be
enhanced, or an
item-name[(subscript)]
within parentheses which
will contain the data item
of the field to be enhanced
at run time.
message Either a string enclosed in
quotation marks that
specifies the message to be
displayed, or an
item-name[(subscript)]
within parentheses
containing the message
string to be displayed in
the window.
Examples
The following example shows the use of the WINDOW option when the field
name and the message are specified directly.
GET(FORM) FORM1,
INIT,
LIST=()
WINDOW=(field1,"This field must be numeric.");
In the following example, both the field and the message are specified
through an item-name reference:
DEFINE(ITEM) ENHANCE U(16):
MESSAGE U(72);
MOVE (ENHANCE) = "field1";
MOVE (MESSAGE) = "This field must be numeric.";
:
GET(FORM) *,
INIT,
WINDOW=((ENHANCE),(MESSAGE));
The first entry in the chain is retrieved from the data set DETAIL using
the items CUST-NAME through CUST-PHONE in the list register.
PROMPT(PATH) CUST-NO;
LIST CUST-NAME:
CUST-PHONE;
GET(CHAIN) DETAIL,
LIST=(CUST-NAME:CUST-PHONE);
The first GET retrieves the last record in the chain. The second GET
reads the chain in reverse order until a record matches the criteria set
up by the DATA(MATCH) statement.
PROMPT(PATH) CUST-ID;
LIST CUST-NAME:
CUST-PHONE;
GET(RCHAIN) DETAIL, LIST=(CUST-NAME:CUST-PHONE);
:
DATA(PATH) CUST-ID;
DATA(MATCH) CUST-NAME;
GET(RCHAIN) DETAIL, LIST=(CUST-NAME:CUST-PHONE);
This statement displays the form CUSTFORM, performs any initialization
specified by FORMSPEC, retrieves values entered into the form, performs
any FORMSPEC edits, and then transfers the entered values to the data
register areas associated with the specified list items.
GET(FORM) CUSTFORM, INIT, LIST=(CUST-NAME, CUST-ADDR, CUST-PHONE);
In the following example, GET with the STATUS option allows you to
process the "nonexistent permanent file" error yourself. This coding
lets you access a file that may be in another account by setting up a
file equation through a PROC call to the command intrinsic.
<<1st access, no CLOSE required before SERIAL operation>>
GET(SERIAL) DATA-FILE, LIST=(A:N), STATUS;
IF STATUS <> 0 THEN <<An error occurred, check further >>
IF STATUS <> 52 THEN <<Error is other than expected >>
GO TO ERROR-CLEANUP
ELSE <<52 - Nonexistent permanent file >>
DO
LET (CR) = 8205; <<8205 = space,carriage return >>
<<Could have used (CR)=3360 for carriage>>
<<return,space >>
MOVE (COM-STRING) = "FILE DATAFILE=DATAFILE.PUB.OTHERONE"+(CR);
<<Try opening DATAFILE in another group >>
PROC COMMAND (%(COM-STRING),(ERROR),(PARM));
IF (ERROR) <> 0 THEN <<Command error >>
GO TO ERROR-CLEANUP;
<<Try again, give up if unsuccessful >>
GET(SERIAL) DATA-FILE, LIST=(A:N), STATUS;
IF STATUS <> 0 THEN GO TO ERROR-CLEANUP;
DOEND;
The following example shows a method for "structured programming" with
VPLUS forms. Each RETURN statement passes control back to the PERFORM
statement.
START:
DISPLAY "Start of program";
PERFORM GETINFO;
DISPLAY "End of program";
EXIT;
GETINFO:
GET(FORM) MENU,
F1=ADD,
F2=UPDATE,
F3=DELETE,
F4=LIST,
F5=START,
F6=START,
F7=START,
F8=ENDIT;
<<Process ENTER here>>
.
.
.
ADD:
<<Process F1 here>>
RETURN;
UPDATE:
<<Process F2 here>>
RETURN;
DELETE:
<<Process F3 here>>
RETURN;
LIST:
<<Process F4 here>>
RETURN;
ENDIT:
EXIT;
An alternate method is to use the FKEY=item-name construct, and then test
the value of item-name with an IF statement.