HP 3000 Manuals HP 3000 Manuals
PATH
Establishes a chained access path to a data set or a KSAM file.
Syntax
PATH file-name[,option-list];
PATH uses the key and argument registers that correspond to the KSAM key
for setting up chained access for the KSAM file or chained access for a
detail data set. If you do not include a STATUS option in the PATH
statement, the status register is set to the number of entries in the
chain of a detail set. The number of entries is not returned for a KSAM
file.
You must use a PATH statement to establish the path for chained access to
a KSAM file or a data set when the STATUS option is included in a
subsequent data access statement. The PATH verb cannot be used with MPE
files.
PATH performs file and key validations during program execution. If the
attributes do not match the current database or file, an error message is
displayed.
Statement Parts
file-name The KSAM file or data set to be accessed. 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)
If you specify a set name and do not include the
STATUS option, the status register is set to the
number of entries in the data set chain; the status
register will not contain the number of entries for
a KSAM file.
option-list One or more of the following fields, separated by
commas:
ERROR=label Suppresses the default error
([item-name]) return that 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) Used only with KSAM files to
map out a record. The list
option is needed to locate the
key in the KSAM record.
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.)
All item names specified must
be parent items.
The LIST= option has a limit of
64 individually listed item
names and a limit of 255 items
specified by a range.
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
item-nameY) data items
in the
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,
![[FFN11]](../../pic3k/M017291/FFN11.gif)
then data
items A, B,
C, D, and D
are
selected.
(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-nameY) All data
items in
the range
from the
occurrence
of
item-nameY
closest to
the top
through the
bottom of
the list
register.
(item-nameX, The data
item-nameY, ... items are
item-nameZ) selected
from the
list
register.
For KSAM
files, data
items must
be
specified
in the
order of
their
occurrence
in the
physical
record.
This order
need not
match the
order of
the data
items on
the list
register.
This option
incurs some
system
overhead.
(@) 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.
Operates on
the file
but does
not
retrieve
any data.
NOMSG Suppresses the standard error
message produced by Transact as
a result of a file or database
error.
STATUS Suppresses the action defined
in Chapter 7 under "Automatic
Error Handling." You will need
to add code to check the value
of STATUS. When STATUS is
specified, the effect of a PATH
statement is described by the
value in a 32-bit integer
status register:
Status Meaning
Register
Value
0 The PATH operation was successful.
-1 A KSAM end-of-file condition
occurred.
>0 For a description of the condition
that occurred, refer to the database
or KSAM file system error
documentation that corresponds to
the value.
Note that when STATUS is
omitted, the status register
contains a -1 if the argument
value for a PATH operation on a
detail set is not found in the
associated master set. [REV
BEG](See Table 7-4 for other
status register values.)[REV
END]
Examples
The following example uses a PATH statement to locate the head of a KSAM
chain, and then retrieves the first item in that chain.
LIST DEL-WORD:
CUST-NO:
LAST-NAME:
FIRST-NAME:
INITIAL;
PROMPT(KEY) CUST-NO ("Enter Customer Number");
<<Set up key/arg registers >>
PATH KFILE, <<Locate head of chain in KFILE >>
LIST=(DEL-WORD:INITIAL); <<Map KFILE record >>
IF STATUS <> 0 THEN
GET(CHAIN) KFILE, <<Retrieve first record >>
STATUS,
LIST=(DEL-WORD:INITIAL);
The next example uses a PATH statement to determine the number of records
in a detail set.
PROMPT(PATH) CUST-NO;
PATH CUST-DETAIL;
LET (NUM-RECS) = STATUS;
DISPLAY NUM-RECS, NOHEAD:
"Records in this Path";
PATH is required before you use the STATUS option in a database access
statement because the STATUS option suppresses the usual determination of
a chain head. In the following example, the PATH statement is needed
prior to the FIND(CHAIN) statement that includes a STATUS option:
SET(KEY) LIST(CUST-NO);
PATH CUST-DETAIL;
GET-NEXT:
FIND(CHAIN) CUST-DETAIL,
LIST=(CUST-NO:ZIP),
STATUS,
PERFORM=PROCESS-ENTRY;
IF STATUS <> 0 THEN
GO TO ERROR-ROUTINE
ELSE
GO TO GET-NEXT;
Note that the STATUS option also suppresses the normal multiple retrieval
performed by FIND; you must specifically code the loop logic.