HP 3000 Manuals HP 3000 Manuals
OUTPUT
Performs a multiple data retrieval from a file or data set and displays
the data.
Syntax
OUTPUT[(modifier)] file-name[,option-list];
OUTPUT specifies a database or file retrieval operation. It adds each
retrieved record to the data register, but only selects for output those
records that satisfy any selection criteria in the match register. For
each selected record, OUTPUT displays all the items in the current list
register. If you want to select items from the list register, you should
precede the OUTPUT statement with a FORMAT statement.
The OUTPUT statement displays the selected entries after PERFORM=
statements are executed. This allows you to display the results of
PERFORM= statements. However, this makes nesting of OUTPUT statements
difficult. The output from the most deeply nested OUTPUT statement is
displayed first. To produce nested output in the more usual order, you
can use a FIND statement to retrieve the data with a PERFORM= option to
display the data.
If a FORMAT statement appears before the OUTPUT statement, then the
display is formatted according to the specifications in that statement.
If there is no preceding FORMAT statement, the display is formatted
according to the default format described below. Once all entries have
been displayed according to a preceding FORMAT statement, subsequent
OUTPUT statements revert to the default format unless control passes
again through a FORMAT statement.
The default format for OUTPUT is:
* Displays values in the order in which they appear in data
register.
* Accompanies each value with a heading consisting of:
* the heading specified for that value in a HEAD= option of a
DEFINE(ITEM) statement,
* the heading taken from a dictionary definition of the item,
or
* the associated data item name in the list register.
* Displays each value in a field whose length is either the data
item size or the heading length, whichever is longer.
* A single blank character separates each value field from the next.
If a field cannot fit on the current display line, then the field
begins on a new line.
NOTE After the first retrieval, Transact uses an asterisk (*) for the
call list to optimize subsequent retrievals of that data set.
Statement Parts
modifier To specify the type of access to the data set or file, choose
one of the following modifiers:
none Retrieves an entry from a master set based on
the key value in the argument register. This
option does not use the match register.
CHAIN Retrieves entries from a KSAM file key or a
detail chain. The entries must meet any match
criteria set in the match register in order to
be collected. The contents of the key and
argument registers specify the chain or KSAM key
in which the retrieval is to occur. If no match
criteria are specified, all entries are
selected. If match criteria are specified, the
match items must be included in a LIST= option
of the OUTPUT statement.
CURRENT Retrieves the last entry that was accessed from
the MPE or KSAM file or data set.
DIRECT Retrieves the entry stored at a specified record
number from an MPE or KSAM file or a data set.
Before using this modifier, store the record
number as a 32-bit integer I(10,,4) in the item
referenced by the RECNO= option.
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 entries from a detail set in the same
manner as the CHAIN option, only in reverse
order. For a KSAM file, this operation is
identical to CHAIN.
RSERIAL Retrieves entries from a data set in the same
manner as the SERIAL option, except in reverse
order. For a KSAM or MPE file, this operation
is identical to SERIAL.
SERIAL Retrieves entries in serial mode from an MPE or
KSAM file or a data set that meet any match
criteria set up in the match register. If no
match criteria are specified, all entries are
selected. If match criteria are specified, the
match items must be included in a LIST= option
of the OUTPUT statement.
file-name The file or data set 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)
option- One or more of the following options separated by commas:
list:
ERROR=label Suppresses the default error return that
([item-name]) Transact 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.
LIST=(range-list) The list of items from the list register
to be used for the data retrieval portion
of the OUTPUT operation. The display
portion follows the same rules as the
DISPLAY statement. If the LIST= option is
omitted, the entire list register is used
for the data retrieval.
Only the items specified in a LIST= option
have their match conditions applied if
match conditions are set up in the match
register. (The match register can be used
only with the modifiers CHAIN, RCHAIN,
SERIAL, or RSERIAL.)
Each retrieved entry is placed in the area
of the data register indicated by LIST=
before any PERFORM= is executed.
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 and a limit
of 255 items specified by a range for a
TurboIMAGE data set.
All item names specified must be parent
items.
The options for range-list and the data
items retrieved by OUTPUT include the
following:
(item-name) A single data item.
(item-nameX: All the data items in the
item-nameY)
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,
![[]](../../pic3k/M013424/FFN293c50.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, and if
there are no data items
between the two on the list
register, no database access
is performed. (See the
DEFINE(ITEM) verb
description.)
(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- 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. Do
not include child items in
the list unless they are
associated with a VPLUS
forms file. This option
incurs some system overhead.
(@) Specifies a range of all
data items of file-name as
defined in a 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.
Accesses the file or data
set, but does not retrieve
any data.
LOCK Locks the specified file or database. The
lock is active the entire time that the
OUTPUT executes. If LOCK is not specified
and a TurboIMAGE data set is being
accessed, no locking is done.
When a KSAM or MPE file is being accessed,
if LOCK is not specified on the OUTPUT
statement 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 overrides
SET(OPTION) NOLOCK for the execution of
the OUTPUT verb.
For transaction locking, you can use the
LOCK option on the LOGTRAN verb instead of
the LOCK option on OUTPUT if SET(OPTION)
NOLOCK is specified.
See "Database and File Locking" in Chapter
6 for more information on locking.
NOCOUNT Suppresses the message normally generated
to indicate the number of entries found.
NOHEAD Suppresses default headings for the
displayed values.
NOMATCH Ignores any match criteria set up in the
match register. This option is useful if
you want to leave the match register set
up but do not want to use it.
NOMSG Suppresses the standard error message
produced as a result of a file or database
error. All other error recovery actions
occur.
PERFORM=label Executes the code following the specified
label for every entry retrieved by the
OUTPUT operation. The entries can be
optionally selected by MATCH criteria, in
which case the PERFORM= statements are
executed only for the selected entries.
This option allows operations to be
performed on retrieved entries without
having to code loop control logic. You
can nest up to 10 PERFORM= options.
RECNO=item-name With the DIRECT modifier, you must
[(subscript)] initialize item-name to contain the 32-bit
integer number (I(10,,4)) of the record to
be retrieved. With other modifiers,
Transact returns the record number of the
retrieved record in item-name, a 32-bit
integer (I(10,,4)).
The item-name can be subscripted if an
array item is being referenced. (See
"Array Subscripting" in Chapter 3.)
SINGLE Retrieves and displays only the first
entry that satisfies any selection
criteria.
SOPT Suppresses the optimization of database
calls. This option is primarily intended
to support a database operation in a
performed routine that is called
recursively. The option allows a
different path for the same detail set to
be used at each recursive entry, rather
than optimizing to the same path. It also
suppresses generation of a call list of
"*" after the first call is made. Use
SOPT if you are calling TurboIMAGE through
the PROC or CALL verbs. For an example of
how SOPT is used, see "Examples" at the
end of the FIND verb description.
SORT=[(item-name1:item-name2)] (item-name3[(ASC)]
[(DES)]
[,item-name4[(ASC)]]...);
[(DES)]
This option sorts each occurrence of
item-name3 and, optionally, item-name4,
and so forth. The list used to define the
sort file record is either the range of
items specified by item-name1:item-name2,
or if item-name1 and item-name2 are
omitted, the entire list register. You
can use the optional range to prevent
unneeded variables from being written to
the sort file. In general, only send to
the sort file the items that will be
formatted for output.
The OUTPUT statement always sorts after
processing any PERFORM= statements. The
processing sequence for the sort is:
* first, retrieves each selected
record,
* then, executes any PERFORM=
statements,
* then, writes the specified items to
the sort file, and, after writing
all the records to the sort file,
* sorts the sort file, and
* displays the sorted output.
The SYSTEM statement determines the size
of the sort file.
You can specify either ascending or
descending sort order. The default is
ascending order. (See the FIND verb
description for a different processing
sequence.)
STATUS Suppresses the action defined in Chapter 7
under "Automatic Error Handling." You will
need to add code to check the value of
STATUS, as shown in the example below.
When STATUS is specified, the effect of an
OUTPUT statement is described by the
32-bit integer value in the status
register:
Status Meaning
Register
Value
0 The OUTPUT operation was successful.
-1 A KSAM or MPE end-of-file condition
occurred.
>0 For a description of the condition
that occurred, refer to database or
MPE/KSAM file system error
documentation corresponding to the
value.
STATUS causes the following with OUTPUT:
* Normal multiple accesses become
single.
* The normal rewind done by OUTPUT is
suppressed, so CLOSE should be used
before OUTPUT(SERIAL).
* The normal find of the chain head
by OUTPUT is suppressed, so
PATH should be used before
OUTPUT(CHAIN).
See "Using the STATUS Option" in Chapter
7.
Examples
The following two examples of OUTPUT retrieve data according to a value
entered by the user. Then they display the data according to the
preceding FORMAT statement.
Example 1 Example 2
LIST NAME: PROMPT(PATH) CUST-NO;
ADDRESS: LIST COMPANY:
CITY: CO-ADDR:
ZIP; CO-STATE:
PROMPT(KEY) CUST-NO; ZIP
FORMAT NAME,COL=5: FORMAT COMPANY, COL=5:
ADDRESS,COL=20: CO-ADDR,COL=40:
CITY,SPACE=5: CO-STATE,LINE,COL=5:
ZIP,SPACE=5; ZIP, COL=40;
OUTPUT MASTER, OUTPUT(CHAIN) DETAIL,
LIST=(NAME:ZIP); LIST=(COMPANY:ZIP);
The following example retrieves the entries that satisfy the match
criterion LAST-NAME = Smith from the data set CUSTOMER, then sorts the
entries according to FIRST-NAME and displays only the sorted names.
LIST LAST-NAME:
FIRST-NAME;
MOVE (LAST-NAME) = "Smith";
SET(MATCH) LIST(LAST-NAME);
FORMAT LAST-NAME: << Items to be displayed >>
FIRST-NAME, JOIN=2;
OUTPUT(SERIAL) CUSTOMER,
NOCOUNT, NOHEAD,
SORT=(FIRST-NAME); << Sort on first name >>
The resulting display looks like:
Smith Abraham
Smith John
Smith Joseph
Smith Mary
Smith Thomas
In the next example, some of the items selected for sorting and
displaying are calculated in a PERFORM= routine.
LIST INV-NO:
PRICE:
QUANTITY:
AMOUNT:
TOT-AMT;
OUTPUT(SERIAL) INVENTRY,
LIST=(INV-NO:QUANTITY), PERFORM=TOTAL,
SORT=(INV-NO:AMOUNT) (AMOUNT);
TOTAL:
LET (AMOUNT) = (PRICE) * (QUANTITY);
LET (TOT-AMT) = (TOT-AMT) + (AMOUNT);
RETURN;