HP 3000 Manuals HP 3000 Manuals
DATA
Prompts for a value and changes the appropriate location in the data,
argument, match, and/or update registers.
Syntax
DATA[(modifier)][item-name][("prompt-string")][,option-list][:item-name...] ... ;
DATA prompts the user for a value and, depending on the syntax option
chosen, places the value in one or more registers. The registers
affected depend on the verb modifier. Available modifiers are:
none Places value in data register. (See Syntax Option 1.)
ITEM Prompts for item name and if found, places value in data
register. (See Syntax Option 2.)
KEY Places value in argument register. (See Syntax Option 3.)
MATCH Places value in data register. Sets up match criteria in
match register. (See Syntax Option 4.)
PATH Places value in data register and in argument register. (See
Syntax Option 5.)
SET Places value in data register unless user presses carriage
return. (See Syntax Option 6.)
UPDATE Places value in data register. Places item name and value in
update register. (See Syntax Option 7.)
The user enters a value in response to a prompt-string or to the
item-name. At execution time, Transact validates the input value as to
type, length, and other characteristics defined in the data dictionary or
by a DEFINE(ITEM) statement. It validates the data before the register
is modified. If Transact detects an error, then it displays an
appropriate error message and reissues the prompt.
With native language support, Transact validates numeric data using the
thousands and decimal indicators of the language in effect. (See
Appendix E, "Native Language Support" for more information.)
You normally use the DATA verb to change the value for a data item that
has already been specified in the list register. DATA searches the list
register from the top of the stack to the bottom to find the requested
item-name. If there are multiple occurrences of the same item in the
list register, it uses the last one placed on the list.
Statement Parts
modifier Changes or enhances the action of DATA; often
indicates the register to which the input value
should be added or the register whose value should
be changed. The Syntax Options subsection below
describes the impact of each modifier in detail.
item-name The name of the data item in the list register
whose value should be added or changed in the
appropriate register.
* The item at the top of the list register; that is,
the one referenced by the last LIST or PROMPT
statement unless explicitly changed by a more
recent SET or RESET command.
prompt-string The string that prompts the user for the input
value; if not specified, the user is prompted by
the item name or by an entry text specified in the
DEFINE(ITEM) statement or in the data dictionary,
if one exists.
option-list A field specifying how the data should be formatted
and/or other checks to be performed on the entered
value. Include one or more of the following
options (separated by commas) unless you use the
ITEM modifier (Syntax Option 2):
BLANKS Does not suppress leading
blanks supplied in the input
value; leading and trailing
blanks are normally
stripped.
CHECK=set-name Checks input value against
the master set set-name to
ensure that the value
already exists. If the
condition is not met at
execution time, Transact
displays an appropriate
error message and reissues
the prompt. You cannot use
this option with a KSAM or
MPE file, in a DATA(MATCH)
statement, nor with child
items.
CHECKNOT=set-name Checks input value against
the master set set-name to
ensure that the value does
not already exist. If the
option condition is not met
at execution time, then
Transact issues an
appropriate error message
and reissues the prompt.
You cannot use this option
with a KSAM or MPE file, in
a DATA(MATCH) statement, nor
with child items.
NOECHO Does not echo the input
value to the terminal.
NULL Fills item with ASCII null
characters (binary zeros)
instead of blanks.
RIGHT Right-justifies the input
value within the register
field.
STATUS Suppresses normal processing
of "]" and "]]", which cause
an escape to a higher
processing or command level.
Status Meaning
Register
Value
-1 User entered a "]".
-2 User entered a "]]".
-3 User entered one or more blanks and
no non-blank characters.
-4 If timeout is enabled with a
FILE(CONTROL) statement, a timeout
has occurred.
> 0 Number of characters (includes
leading blanks if BLANKS option is
specified); no trailing blanks are
counted.
The STATUS option allows you
to control subsequent
processing by testing the
contents of the register
with an IF statement.
If the CHECK or CHECKNOT
option is also used, then
"]", "]]", a carriage
return, or one or more
blanks suppress the DATA
operation and control passes
to the next statement.
Syntax Options
(1) DATA
{item-name[(subscript)]}[("prompt-string)"][,option-list][:item-name...]...;
{ * }
DATA with no modifier places the value entered as a response to
prompt-string in the data register. It is added in an area associated
with the current data item if "*" is used or with item-name if it is
specified. item-name can be modified with subscript if the referenced
item is an array item. (See "Array Subscripting" in Chapter 3.)
(2) DATA(ITEM) "prompt-string"[,REPEAT];
The ITEM modifier is typically used to update or correct one or more
values in the data register. DATA(ITEM) issues a prompt prompt-string to
request an item name. When the user enters an item name in response to
this prompt, Transact looks for this item in the list register. If the
item name cannot be found, it displays an error message and reissues the
prompt. If the item name is in the list register, this item name is
issued as a second prompt to which the user responds with a value. If
the entered value passes all edit checks, it is placed in the data
register area associated with the item name. Otherwise, the user is
prompted for another value. If the user responds with a "]", Transact
reissues the prompt-string prompt. If the user responds with "]]",
Transact returns to command mode.
If you use the REPEAT option, then the operation is repeated until a
termination character (] or ]]) or a null response (carriage return) is
entered in response to the prompt-string prompt.
(3) DATA(KEY) {item-name}[("prompt-string")][,option-list][:item-name...]...;
{ * }
DATA(KEY) places the value entered as a response to prompt-string in the
argument register. If item-name is specified, this name is used as the
prompt for user input, unless this name is overridden by a prompt-string.
If "*" is specified, then the current name in key register is used as the
prompt for user input. The key register is changed by this verb only if
it is empty. If the key register is not empty, this verb does not change
the item name already in the key register.
(4) DATA(MATCH)
{item-name}[("prompt-string")][,option-list][:item-name...]...;
{ * }
DATA(MATCH) places the value entered as a response to item-name or
prompt-string in the data register. You cannot specify either CHECK= or
CHECKNOT= with DATA(MATCH). It places the value in the data register in
an area associated with the current data item if the "*" is used or in an
area associated with a named data item if an item name is specified. The
item name and value are also placed in the match register as a selection
criterion for subsequent database or file operations.
[REV BEG]
If the item name is an unsubscripted array, only the value of the first
element of the array will be set in the data register. This value from
the data register will be set up as match criterion in the match
register.[REV END]
You should note that when a single key value is entered for the match,
Transact performs a chained read on the data set if the item is a search
or key item. However, if a range of values or non-key value is
specified, a serial read is performed.
User responses to the DATA(MATCH) prompt are further explained in the
discussion of "Match Register" in Chapter 4. (See also "MATCH
Specification Characters" and "Responding to a MATCH Prompt" in Chapter
5.) The MATCH modifier allows one or more of the option-list items
allowed with all DATA options. (See list above.) You may also select
one of the following options, which specify that a match selection is to
be performed on a basis other than equality.
If you specify one of the options listed below, the entire user input is
treated as a single value. The match specification characters described
in Chapter 5 are not allowed as user input with the options listed below.
MATCH option-list:
NE Not equal to
LT Less than
LE Less than or equal to
GT Greater than
GE Greater than or equal to
LEADER Matched item must begin with the input string;
equivalent to the use of trailing "^" on input
SCAN Matched item must contain the input string;
equivalent to the use of trailing "^^" on input
TRAILER Matched item must end with the input string;
equivalent to the use of a leading "^" on input
For example, if the program contains the data statement
DATA(MATCH) CUSTNO,GE;
and if the user responds to the prompt by entering 079333, then only
customer numbers greater than or equal to 079333 will be selected.
(5) DATA(PATH){item-name}[("prompt-string")][,option-list][:item-name...]...;
{ * }
DATA(PATH) places the value entered as a response to prompt-string in the
data register. The value is placed in the data register in an area
associated with the current data item if the "*" is used or with
item-name if it is specified. The value is also placed in the argument
register and the item name in the key register for subsequent keyed
access to KSAM files or data sets. The key register is changed by this
verb only if it is empty. If the key register is not empty, this verb
does not change the item name already there.
(6) DATA(SET) {item-name[(subscript)]}[("prompt-string")][,option-list]
{ * }
[:item-name...]...;
The primary use of the SET modifier is to update values in the data
register for existing items in the list register. DATA(SET) places the
value entered as a response to item-name or prompt-string in the data
register. It is placed in the data register in an area associated with
item-name, if it is used, or with the current item if "*" is used.
item-name may be modified with (subscripts) if the referenced item is an
array item. (See "Array Subscripting" in Chapter 3.)
If the user responds to the prompt with a carriage return, then the
existing value in the data register is not touched. Note that this
differs from the other DATA statements which add blanks to the data
register if the user responds with a carriage return.
If you use the CHECK= or CHECKNOT= options and the specified condition is
not met, the item remains in the data register. In this case, you should
reset the data register to the previous item to avoid creating an endless
loop should the user respond with a carriage return to the reissued
prompt. Both CHECK= and CHECKNOT= look for the item in the master set
even if the user enters a carriage return.
A special option, SHOW, is available only with the (SET) modifier. SHOW
causes the old value to appear in the prompt for a new value. This
allows the user to see what the item will contain if a carriage return is
entered. The values are displayed left justified, with trailing blanks
suppressed. One blank is displayed when an alphanumeric item is all
blank. The SHOW option can only be used in the DATA(SET) statement. The
following example uses the SHOW option:
DEFINE(ITEM) PRODUCT X(40):
QUANTITY I(3);
LIST PRODUCT,INIT:
QUANTITY,INIT;
DATA(SET) PRODUCT,SHOW:
QUANTITY,SHOW;
This example causes the following prompts to be displayed the first time
data is entered:
PRODUCT(= )>
QUANTITY(=0)>
If the values "grapefruit" and "10" are entered, the prompts appear like
this when displayed again:
PRODUCT(=grapefruit)>
QUANTITY(=10)>
If an alphanumeric string is longer than 30 characters, the first 30
characters are displayed:
PRODUCT(=mason valley delightful grapef...)>
The trailing periods (...) indicate that the value is too long.
(7) DATA(UPDATE) {item-name}[("prompt-string")][,option-list]
{ * }
[:item-name...]...;
DATA(UPDATE) places the value entered as a response to prompt-string in
the data register. It is placed in the data register in an area
associated with the current data item if the "*" is used or with item
name if it is specified. The item name and value are also placed in the
update register for subsequent use with the REPLACE verb.
Examples
This example asks the user for an account number, which is placed in the
argument register for subsequent access to the ACCOUNT-MASTER set. The
value is checked first, however, to see if it already exists in
ACCOUNT-MASTER. If it does not, then an error message is displayed and
the prompt is reissued.
DATA(KEY) ACCT-NO ("Account number?"),
CHECK=ACCOUNT-MASTER;
This example asks the user for a response. If the response is a carriage
return, the data register is not changed. If a value is entered, the new
value replaces the existing value in the data register space allocated to
the item QUANTITY.
DATA(SET) QUANTITY("New stock quantity?");
In response to the prompt for ADDRESS, the user can enter the entire
address with each item separated by commas; or the user can enter one
item of the address at a time. If the entire address is entered at once,
the remaining item prompts are not issued.
DATA ADDRESS ("Enter customer address"):
CITY ("Enter city"):
STATE ("Enter 2-letter state code"):
ZIP ("Enter 5-digit zip code");
For example, the following dialogue could occur:
Enter customer address> 312 Alba Road, San Jose, CA, 95050
Alternatively, if the user wants to wait for each prompt, the dialogue
could be:
Enter customer address> 312 Alba Road
Enter city> San Jose
Enter 2-letter state code> CA
Enter 5-digit zip code> 95050
In either case, the entered data is moved to the data register locations
associated with ADDRESS, CITY, STATE, and ZIP. If the user presses Return
in response to any single prompt, the associated area of the data
register is set to blanks. If you want Return to leave the existing
data, you must use a DATA(SET) statement.