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 the name of the
[(sub- form to be displayed by GET(FORM). subscript
script)])
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- The list of items from the list register to
list) 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 data items in the range
item-nameY) 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- All data items in the range
nameX:) from the last entry through the
occurrence of item-nameX
closest to the top of the list
register.
(:item- All data items in the range
nameY) from the occurrence of
item-nameY closest to the top
through the bottom of the list
register.
(item-nameX, The data items are selected
item-nameY, from the list register. For
... databases, data items can be
item-nameZ) 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.