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 to establish a KSAM key in a
KSAM file or to establish a detail set for chained access. 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 return that
([item- Transact normally takes. Instead, the
name]) 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= Used only with KSAM files to map out a
(range-list) 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 data items in the range
item-nameY) 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,
Click here to view figure.
then data items A, B, C, D, and
D are selected.
(item- All data items in the range
nameX:) 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
... KSAM files, data items must be
item-nameZ) 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. (See
Table 8-2 for other status register values.)
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.