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,
![[FFN12]](../../pic3k/M017291/FFN12.gif)
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.
[REV BEG]
When the STATUS option is placed on the
PUT(FORM), the PUT(FORM) only writes to the
form. It does not read the function keys or the
data from the form to the VPLUS buffer. For
additional information, see the PUT flowcharts
in Appendix A.
PUT with the STATUS option could be used as
shown in one of the examples shown in the
Examples section.[REV END]
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.
item- The field-name identifies the field and the
name[(subscript)] item-name 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
[(subscript)]
the user in this operation to a 16-bit 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),
PERFORM=LIST-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;
This 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);
[REV BEG]
Use PUT with the STATUS option to check for error conditions. This
example writes to an overflow file and issues an error message when the
data set is full.
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;
[REV END]