HP 3000 Manuals HP 3000 Manuals
PUT
Moves data from the data register to a file, data set, or a VPLUS form.
Syntax
PUT[(modifier)] destination [,option-list];
PUT moves an entry from the list and data registers into a file or a data
set; or it displays data in a VPLUS form.
Statement Parts
modifier To specify the type of access from the data set or file,
choose one of the following modifiers.
none Adds an entry, based on the list and data
registers, into a file or a data set.
FORM Displays a VPLUS form on any VPLUS compatible
terminal, and moves data to the form from the
data register. If this modifier is not used,
the destination must be a file or data set.
destinationThe file, data set, or form to be accessed in the write
operation.
If the destination is a data set that 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)
In a PUT(FORM) statement, the destination must identify a form
in a forms file that was named in the SYSTEM statement. For
PUT(FORM) only, destination can be specified as any of the
following:
form-name Name of the form to be displayed by PUT(FORM).
(item-name Name of an item that contains the name of the
[(sub- form to be displayed by PUT(FORM). The item-name
script)]) can be subscripted if an array item is being
referenced. (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)
that 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.
option- The LIST= option and the STATUS option are always available.
list The other options described below, may be used only without or
only with the FORM modifier.
The list of items from the list register to be used for the
PUT operation. For data sets, no child items can be specified
in the range list. For PUT(FORM) only, items in the range
list can be child items.
If the LIST= option is omitted with any modifier except FORM,
all the items named in the list register are used. If the
LIST option is omitted for PUT(FORM), the list of items 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.
LIST= The list of items from the list register to be
(range-list) used for the PUT operation. For PUT(FORM) only,
items in the range list can be child items.
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
for files or data sets.
The options for range-list and the records upon
which they operate include the following:
(item-name) A single data item.
(item-nameX: All the data items in the range
item-nameY) from item-nameX through the last
occurrence of 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 follows,
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 DEFINE(ITEM)
verb) and if there are no data
items between the two in the list
register, no database access is
performed.
(item- All data items in the range from
nameX:) the last entry through the
occurrence of item-nameX closest
to the top of the list register.
(:item- All data items in the range from
nameY) the occurrence of item-nameY
closest to the top through the
bottom of the list register
(item-nameX, The data items are selected from
item-nameY, the list register. For databases,
... data items can be specified in any
item-nameZ) order. For KSAM and MPE files and
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. Do not
include child items in the list
unless they are defined in the
VPLUS form. This option incurs
some system overhead.
(@) Specifies a range list of all data
items of destination as defined in
a dictionary. This range is
defined as item-name-1:item-name-n
for the file.
(#) Specifies an enumeration of all
data items of destination 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 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, or
displays the form, but does not
transfer any data.
STATUS Suppresses the action defined in Chapter 7 under
"Automatic Error Handling." If you use this
option, you should program your own error
handling procedures.
When STATUS is specified, the effect of a PUT
statement is described by the 32-bit integer
value in the status register:
Status Meaning
Register
Value
0 The PUT operation was successful.
-1 A KSAM or MPE end-of-file condition
occurred.
> 0 For a description of the condition
that occurred, refer to the
condition word or MPE/KSAM file
system error documentation
corresponding to the value.
PUT with the STATUS option could be used as
shown in the following example. When a data set
is full, you may want to write to an overflow
file. To trap and display the full error
condition, you could use the following code:
PUT DATA-SET,
LIST=(A:N),
STATUS;
IF STATUS <> 0 THEN << Error, check it out >>
IF STATUS <> 16 THEN << Unexpected error >>
GO TO ERROR-CLEANUP
ELSE << Write to overflow >>
DO << Set full >>
PUT OVERFLOW,
LIST=(A:N),
STATUS;
IF STATUS <> 0 THEN
GO TO ERROR-CLEANUP;
DISPLAY "OVERFLOW FILE USED";
DOEND;
Options Available Without the Form Modifier
ERROR=label Suppresses the default error return that Transact
([item-name]) normally takes. Instead, the program branches to the
statement identified by label, and Transact sets the
list register pointer 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 do not specify an 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. If a data set
is being accessed, the lock is set the whole time
that PUT executes. If the LOCK option is not
specified but the database is opened in mode 1, then
automatic locking will execute the lock.
For a KSAM or MPE file, if LOCK is not specified on
PUT but is specified for the file in the SYSTEM
statement, then the file is locked before each entry
is retrieved, remains locked while the entry is
processed by any PERFORM= statements, but is unlocked
briefly before the next entry is retrieved.
Including the LOCK option will override the
SET(OPTION) NOLOCK for the execution of the PUT verb.
A database opened in mode 1 must be locked while PUT
executes. For transaction locking, you can use the
LOCK option on the LOGTRAN verb instead of the LOCK
option on PUT if SET(OPTION) NOLOCK is specified. If
a lock is not specified (for a database opened in
mode 1) an error is returned.
See "Database and File Locking" in Chapter 6 for more
information on locking.
NOMSG Suppresses the standard error message produced by
Transact as a result of a file or database error.
RECNO=item-name Places the record number of the new entry into the
[(subscript)] data register space for item-name. Item-name must be
defined as a 32-bit integer. such as I(10,,4). It
can be subscripted if an array item is being
referenced. (See "Array Subscripting" in Chapter 3.)
Options Available Only With the Form Modifier
APPEND Appends the next form to the specified form,
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.
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 resets the FREEZAPP field
of the VPLUS comarea to zero.
CURRENT Uses the form currently displayed on the terminal
screen. That is, performs all the PUT(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. The
item-name field-name identifies the field and the item-name
[(subscript)] identifies the item which names 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 for the form immediately before displaying
it.
FKEY=item-name Moves the number of the function key pressed by the
[(subscript)] user in this operation to the single word integer
item-name. The function key number is a digit from 1
through 8 for function keys f1 through f8, or zero
for the ENTER key. Transact determines which
function key was pressed from the value of the field
LAST-KEY in the VPLUS comarea. The item-name may be
subscripted if an array item is being referenced.
(See "Array Subscripting" in Chapter 3.)
Fn=label Control passes to the labeled statement if the user
presses function key n. n can have a value of 0
through 8, inclusive, where zero indicates the ENTER
key. This option can be repeated as many times as
necessary in a single PUT(FORM) statement.
FREEZE Freezes the specified form on the screen and appends
the next form to it, overriding any freeze or append
condition specified for the form in its FORMSPEC
definition. FREEZE sets the FREEZAPP field of the
VPLUS comarea to 2.
INIT Initializes the fields in the displayed form to any
initial values defined for the form by FORMSPEC, or
performs any Init Phase processing specified for the
form by FORMSPEC. PUT(FORM) performs the INIT
processing before it transfers any data from the data
register and before it displays the form on the
screen.
WAIT=[Fn] Does not return control to the program until the
terminal user has pressed the function key n. n can
have a value of 0 through 8, where 1 through 8
indicate the keys f1 through f8 and 0 indicates the
ENTER key.
If the user presses any function key other than one
requested by the WAIT option, Transact displays a
message in the window and waits for the next function
key to be pressed. If Fn is any key other than f8,
the f8 exit function is disabled.
If Fn is omitted, PUT(FORM) waits until any function
key is pressed. If the user presses any of the
function keys f1 through f7, the next record will be
PUT; f8 retains its exit function.
If the WAIT option is omitted altogether, PUT(FORM)
clears the screen and returns control to the program
immediately after displaying the form with its data.
For example:
PUT(FORM) (FORMNAME), << Display form named in FORMNAME >>
LIST=(A:C),
WAIT=; << Wait for user to press any key >>
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 within parentheses
which will contain the data item
of the field to be enhanced at
run time.
message Either a "string" in quotes that
specifies the message to be
displayed, or an item-name within
parentheses containing the
message string to be displayed in
the window.
The following example shows this
option when the field name and
message are specified directly:
PUT(FORM) FORM1,
LIST=(A,C,E),
WINDOW=(A,"Press f1 if data is correct."),
WAIT=F1;
In the next 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 may not be changed";
PUT(FORM) *, << Display current form >>
LIST=(),
WINDOW=((ENHANCE),(MESSAGE));
Examples
The following command sequence prompts for new customer information and
adds this information to the customer master file:
$$ADD:
$CUSTOMER:
PROMPT CUST-NO:
CUST-NAME:
CUST-ADDR:
CUST-CITY:
CUST-STATE:
CUST-ZIP;
PUT CUST-MAST, LIST=(CUST-NO:CUST-ZIP);
The next example displays a header form and then appends a form with data
to the header. After appending the data form 10 times, each time with
new data, the program asks the user if he wants to continue. The data to
be displayed is taken from the data register; the particular items are
determined by the LIST= option. In this example, the data in the data
register is retrieved from a data set by the FIND statement.
LIST CUST-NO:
LAST-NAME:
FIRST-NAME:
COUNT;
PUT(FORM) HEADER, << Freeze header form on screen >>
LIST=(),
FREEZE;
LET (COUNT) 0;
FIND(SERIAL) CUSTOMER, << Get data from database >>
LIST=(CUST-NO:FIRST-NAME),
PERFORMLIST-FORM;
:
LIST-FORM:
IF (COUNT) < 10 THEN << Append data form 9 times >>
DO
LET (COUNT) = (COUNT) + 1;
PUT(FORM) CUSTLIST,
LIST=(CUST-NO:FIRST-NAME),
APPEND;
DOEND
ELSE
DO
LET (COUNT) = 0;
PUT(FORM) CUSTLIST, << At 10th iteration, >>
LIST=(CUST-NO:FIRST-NAME), << wait for user input >>
WINDOW=("Press any function key to continue"),
APPEND,
WAIT=;
DOEND;
RETURN;
The last example shows how the LIST=(#) option works, given a data set
defined as follows:
NAME: SUP-MASTER, MANUAL(13/12,18), DISC1
ENTRY: SUPPLIER(1),
STREET-ADD,
CITY,
STATE,
ZIP,
CAPACITY: 200;
The statement:
PUT SUP-MASTER,LIST=(#);
is equivalent to the statement:
PUT SUP-MASTER,LIST=(SUPPLIER,STREET-ADD,CITY,STATE,ZIP);