HP Deskjet 3000 User manual

HP RPG/XL Utilities
HP 3000 MPE/iX Computer Systems
Edition 1
Manufacturing Part Number: 30318-90006
E1089
U.S.A. October 1989

2
Notice
The information contained in this document is subject to change
without notice.
Hewlett-Packard makes no warranty of any kind with regard to this
material, including, but not limited to, the implied warranties of
merchantability or fitness for a particular purpose. Hewlett-Packard
shall not be liable for errors contained herein or for direct, indirect,
special, incidental or consequential damages in connection with the
furnishing or use of this material.
Hewlett-Packard assumes no responsibility for the use or reliability of
its software on equipment that is not furnished by Hewlett-Packard.
This document contains proprietary information which is protected by
copyright. All rights reserved. Reproduction, adaptation, or translation
without prior written permission is prohibited, except as allowed under
the copyright laws.
Restricted Rights Legend
Use, duplication, or disclosure by the U.S. Government is subject to
restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in
Technical Data and Computer Software clause at DFARS 252.227-7013.
Rights for non-DOD U.S. Government Departments and Agencies are
as set forth in FAR 52.227-19 (c) (1,2).
Acknowledgments
UNIX is a registered trademark of The Open Group.
Hewlett-Packard Company
3000 Hanover Street
Palo Alto, CA 94304 U.S.A.
© Copyright 1989 by Hewlett-Packard Company

5
HP RPG/XL Utilities-Part 1 XSORT
1 PREFACE
EXTRA FUNCTION SORT FOR RPG (XSORT)
This manual is intended for the use of inexperienced as well as seasoned programmers. To answer the
needs of programmers with varied backgrounds, the manual presents information of varying complexity,
especially in explaining the XSORT specifications. Most of this manual will be devoted to the five-part
specifications. The information will be presented under the following headings:
Overview of XSORT Specifications
shows you which columns of the specifications you must consider when you are preparing a sort.
Overviews serve as a quick reminder to those who are familiar with the program
Overview of Column Entries
lists all possible entries for each column in the specifications. These are brief descriptions and
explanations of the entries and their purposes. Column Entries
provide detailed discussions of the meanings of all possible entries, their relationships to other entries
within the specifications type and other entries in other specification types. They are intended for new
users of XSORT.
Using XSORT Commands
gives you the various MPE commands necessary to use XSORT in job stream and interactive session, with
different arrangements of input and output files.
XSORT Applications
demonstrate how specifications are adapted to the requirements of particular jobs.
The more extensive the user's experience, the more readily will XSORT's versatility and efficiency become
apparent. The manual takes into consideration that some users will be employing the program for the first
time. Information and instruction are provided for several levels of experience so that the new user should
be able to put XSORT to work after reading the manual.
In using XSORT, you may have programs and systems that interface with the Keyed Sequential Access
Method (KSAM/3000), the IMAGE Data Base Management System (IMAGE/3000), and the Data Entry
and Forms Management System (V/3000). For information about these systems, please read:
Manual Title
IMAGE/3000 Data Base Management Reference System
KSAM/3000 Reference Manual
VPLUS/3000 Reference Manual

6
Conventions
NOTATION DESCRIPTION
UPPERCASE Within syntax statements, characters in
uppercase must be entered in exactly the
order shown, though you can enter them in
either uppercase or lowercase. For
example:
SHOWJOB
Valid entries: showjob ShowJob
SHOWJOB
Invalid entries: shojwob ShoJob
SHOW_JOB
italics Within syntax statements, a word in
italics represents a formal parameter or
argument that you must replace with an
actual value. In the following example,
you must replace
filename with the
name
of the file you want to release:
RELEASE
filename
punctuation Within syntax statements, punctuation
characters (other than brackets, braces,
vertical parallel lines, and ellipses)
must be entered exactly as shown.
{ } Within syntax statements, braces enclose
required elements. When several elements
within braces are stacked, you must
select one. In the following example,
you must select ON or OFF:
{ON }
SETMSG {OFF}
[ ] Within syntax statements, brackets
enclose optional elements. In the
following example, brackets around ,TEMP
indicate that the parameter and its
delimiter are optional:
PURGE {
filename } [,TEMP]
When several elements with brackets are

7
stacked, you can select any one of the
elements or none. In the following
example, you can select
devicename or
deviceclass or neither:
SHOWDEV [
devicename ]
[
deviceclass ]
[...] Within syntax statements, a horizontal
ellipsis enclosed in brackets indicates
that you can repeatedly select elements
that appear within the immediately
preceding pair of brackets or braces. In
the following example, you can select
itemname and its delimiter zero or
more
times. Each instance of
itemname must
be
preceded by a comma:
[
,itemname ][...]
If a punctuation character precedes the
ellipsis, you must use that character as
a delimiter to separate repeated
elements. However, if you select only
one element, the delimiter is not
required. In the following example, the
comma cannot precede the first instance
of
itemname :
[
itemname ][,...]
|...| Within syntax statements, a horizontal
ellipsis enclosed in parallel vertical
lines indicates that you can select more
than one element that appears within the
immediately preceding pair of brackets or
braces. However, each element can be
selected only one time. In the following
example, you must select ,A or ,B or ,A,B
or ,B,A :
{,A}
{,B}|...|
If a punctuation character precedes the
ellipsis, you must use that character as
a delimiter to separate repeated
elements. However, if you select only
one element, the delimiter is not
required. In the following example, you

8
must select A or B or AB or BA. The first
element cannot be preceded by a comma:
{A}
{B}|,...|
... Within examples, horizontal or vertical
ellipses indicate where portions of the
example are omitted.
Å Within syntax statements, the space
symbol Å shows a required blank. In the
following example, you must separate
modifier and variable with a
blank:
SET[(
modifier )]Å( variable );
underlining User input is underlined. For
example:
PROMPT?response
In a syntax statement, brackets, braces
or ellipses are underlined if you must
enter them. For example:
COMMAND
[[
ParameterA ] ] = ParameterB
Conventions (continued)
NOTATION DESCRIPTION
shading Within an example of interactive dialog,
shaded characters indicate user input or
responses to prompts. In the following
example, OMEGA is the user's response to
the NEW NAME prompt:
NEW NAME? OMEGA
The symbol indicates a key on the
terminal's keyboard. For example, CTRL
indicates the Control key.
CTRL
char CTRL char indicates a control
character.
For example, CTRLY means you have to
simultaneously press the Control key and

9
the Y key on the keyboard.
base prefixes The prefixes %,#, and $ specify the
numerical base of the value that follows:
%
num specifies an octal number.
#
num specifies a decimal number.
$
num specifies a hexadecimal
number.
When no base is specified, decimal is
assumed.

10

1- 11
2 Introduction
Hewlett-Packard's Extra Function Sort for RPG/XL, hereaft er referred to as XSORT, enables users to
rearrange data in their files, drop records from their files, and reformat records, as shown in figure 1-1.
XSORT runs on the MPE XL computer system and is primarily used in conjunction with the RPG
programming language. Its origin was the unsupported utility SORT3 which was designed to perform
most of the functions of IBM's System/3 $DSORT and System/34 #GSORT. Similarities and differences are
covered in appendix A.
Figure 1-1. Uses of XSORT

1- 12
Characteristics of XSORT:
In extending and enhancing your sort capabilities, XSORT:
• Uses from one to nine input files.
• Employs multiple logical criteria to select records from MPE (disk and non-disk) and KSAM files, so you
can process a subset of your input records.
• Builds a different sort key for each type of record using input record fields and forced control fields. This
facilitates the input of files with different data structures.
• Reformats each type of record upon output to give you a choice of record layouts.
• Can perform a count-only pass on the input files. This permits you to conduct a preliminary search of
your records or provide statistics on selected subsets of records.
How XSORT Works
XSORT follows a logical sequence in performing a sort. This sequence is described below:
1 XSORT reads a record from the input file.
2 XSORT checks your specifications to make sure the record is one you want to sort. You may not
wish to sort all the records in the file you have specified.
3 XSORT builds a work record containing sort control fields and data fields. It also formats the data
portion according to your specifications. Work record formatting is important because it controls
the format of your output.
4 XSORT submits the work records to the SORT subsystem for sorting.
5 XSORT retrieves records from SORT after sorting is complete.
6 XSORT writes records into the output file, retaining or dropping control fields, according to your
specifications
NOTE Control fields are input fields whose characteristics are used as a basis for the com-
parisons required by the sort. Control fields are discussed in detail in the section on
Field Descriptions. (See chapter 6.)
-------------------------------------------------------
| | | |
| Control field | Data | Control field |
| A | | B |
| | | |
-------------------------------------------------------
1 10 11 29 30 36
Suppose that you wanted to rearrange the input file above because a proposed sort job requires the
following changes:
1 Change the contents of positions 30 through 36 placed in positions 1 through 7 of the work record.
2 Change the contents of positions 1 through 10 of the input file placed in positions 8 through 17 of
the work file.
3 Change the contents of positions 11 through 29 of the input record placed in positions 18 through

1- 13
36 of the work record.
The following is an example of how XSORT builds your work record to reflect your specifications:
-------------------------------------------------------
| | | |
| Control field | Control field | Data |
| | | |
-------------------------------------------------------
1 7 8 17 18 36
NOTE The control fields must precede the data fields in the work record. They will be re-
tained on output unless you wish to drop them. Reasons for retaining or dropping con-
trol fields will be discussed in the Header Specifications section.
Three Types of Sort
Figure 1-2 illustrates XSORT's sort capability--Address-out, Record-out, and Count-only.
Figure 1-2. Three Types of Sort
Address-Out Sort (SORTA)
The output from an Address-out sort job consists of 4-byte binary relative record numbers of the records in
the input file.
An Address-out sort allows you to process a file in sorted order without using up disk or tape space copying
the entire file in order to process it.

1- 14
Record-Out Sort (SORTR)
The output from a Record-out sort is a file of complete records that are immediately available for
processing. These sorted records can contain:
• Control fields and data.
• Control fields only.
• Data only.
A Record-out sort offers faster processing than the Address-out as well as enabling you to reformat files
and to create new files from reformatted records.
Count-Only Sort (SORTC)
This sort performs a Count-only pass on the input files.
Using a Count-only sort, XSORT can provide you with a statistical analysis of the sort with-
out actually performing the sort or producing an output file.
Running the XSORT Program
The following figure illustrates how XSORT sorts your files.
Figure 1-3. How XSORT Sorts Files
1 MPE statements are your job or session control commands to MPE XL.
1 Sort specifications include type of sort, sequence, record information, and instructions formatting
output.
2 File or files can be KSAM or sequential MPE (including non-disk files such as magnetic tape).
3 XSORT passes work records to be sorted to SORT which, in turn, sorts them in a work file. What-
ever work is required can then be performed without any disturbance to the input files.
4 Output files can contain:

1- 15
• The relative record numbers of the records in the input file.
• Part or all of the records in the input files.
• A count of the number of records selected for processing from the input files.
Supplying the Sort Specifications
XSORT specifications are normally entered through a job stream. Interactive entry of specs
is not recommended because XSORT does not prompt for input. You can use either XSORTEXT or
$STDIN to supply sort statements.
XSORT reads your specifications from the file whose formal file designation is XSORTEXT. By
default, XSORTEXT is associated with the actual file designator, $STDIN. Specifications are
read from XSORTEXT (or $STDIN) and any errors in syntax are detected and communicated to you
on $STDLIST.
XSORT specifications must always be entered in the following order.
1 Header.
2 Alternate Collating Sequence.
3 S Option.
4 Record Type.
5 Field Description

1- 16
.

1- 17
You do not always need to use all the specification types for every sort; but the order in which the
specifications are used doesn't vary. You always fill out Header Specifications first.
The ALTSEQ (Alternate Collating Sequence) and the S (Special) Option specifications can be ignored if
they are not to be used in the sort. However, S Option specifications must be supplied when your Input is
from non-disk devices or when you are sorting multiple files.
It is not necessary to fill out the Record Type entries if you wish to have all the records in the file sorted
and they are all written in the same format.
------------------------------------------------------------------------------------------
| | | |
|Number of Records | Format of Records | Order of Specification |
|to be Sorted | to be Sorted | |
| | | |
------------------------------------------------------------------------------------------
| | | |
| All the records in the | All the same. | 1. Header** |
| file. | | 2. Field descriptions |
| | | |
------------------------------------------------------------------------------------------
| | | |
| Some of the records in | All the same. | 1. Header** |
| the file. | | 2. Record Type specs |
| | | 3. Field descriptions |
| | | |
------------------------------------------------------------------------------------------
| | | |
| All or some of the | Several different formats| For first record format: |
| records in the file. | (record sections)* | 1. Header** |
| | | 2. Record Type specs |
| | | 3. Field descriptions |
| | | |
| | | For second record forma |
| | | 4. Record Type specs |
| | | 5. Field descriptions |
| | | |
| | | One set for each additional |
| | | record format: |
| | | 6. Record Type specs |
| | | 7. Field descriptions |
| | | |
------------------------------------------------------------------------------------------
* This does not mean that the records in the input file must be grouped in sections by format type. Just
the specifications must be grouped (one section of Record Type and Field Description lines for each
format type). The input records can be in any order.
** ALTSEQ and S Option, if used, would be entered following the Header Specification.
Forms are provided in appendix D to facilitate your organizing specifications before entering them. The
forms include 72 column spaces but entries can be extended to 80 columns. Copies of the forms may be
made at your convenience.
Detailed Instructions on how to enter the specifications and the optional entries appear in chapters 2
through 6 of the manual.
MPE Commands and Their Uses
You must supply the necessary commands to your system in order for it to perform the sort
job you require. Instructions concerning files, file locations, and the name of the program
are typical of the information supplied by MPE commands.
An unsupported program similar to XSORT called SORT3 has been in existence for some time.

1- 18
A discussion of the commands for SORT3 as compared to XSORT appears in appendix A.
Your MPE Commands Provide:
• Name of the program--XSORT.PUB.SYS
• Nameofthefilesyouwanttosort. Theformaldesignatorforasingle-filesortisXSORTIN.Formultiple-
file sorts, formal file designators are XSORTIN1 through XSORTIN9.
If XSORT can open the file XSORTIN, it assumes you want to do a single-filesort. If XSORTIN cannot
be opened, XSORT assumes you want to do a multiple-filesort, starting with XSORTIN1. (See "Use of
the MPE RESET Command" below for a description of how to avoid problems that may occur when run-
ning a multiple-file sort after a single-file sort.)
• Name of your output file. The formal designator is XSORTOUT.
• Name of the file containing specifications of the sort. The formal designator is XSORTEXT, which de-
faults to $STDIN.
Use of the MPE RESET Command:
To ensure that succeeding executions of XSORT use the correct files, it is recommended that you use MPE
RESET commands after each use of XSORT to reset all the MPE FILE equations issued for your input,
output, and text files.
For example, in a job stream:
.....
!FILE XSORTIN=TESTFILE
!FILE XSORTOUT=TESTFILE
!FILE XSORTEXT=TESTSPEC
!RUN XSORT.PUB.SYS
!RESET XSORTIN
!RESET XSORTOUT
!RESET XSORTEXT
....
Without the RESETs, the next sort could accidentally use the file TESTFILE for input (if the new sort is a
multiple-file sort, naming XSORTIN1 instead of XSORTIN) or TESTSPEC for the sort specifications (if an
overriding file equation for XSORTEXT is not issued).
Input Files
XSORT can input sequential MPE files, including files on non-disk devices such as tape. (Please see
Section 7 for the commands required.)
KSAM files may be input. Caution should be taken, however, because XSORT will skip deleted records. A
deleted record has its first two bytes set to -1 (to hex "FFFF"). For Address-out sorts (SORTA), XSORT
reads KSAM files in chronological sequence and determines record numbers accordingly.
XSORT will normally assure that the first record for a KSAM file is record number 0. If you wish to start
the Address-out numbering at 1, then you must supply the S Option spec with a "1" in column 7 or build
the KSAM file with the Firstrec=1 option. (See Section 4 for further information regarding S Option
specification.)
NOTE XSORT will not process IMAGE data base files.
The formal designator for a single-file sort is XSORTIN. For multiple-file sorts, formal file designators are
XSORTIN1 through XSORTIN9. The multiple-file designators do not have to be continuous. You can skip
file numbers, selecting XSORTIN1, XSORTIN7, and XSORTIN3, for example. However, you must start

1- 19
with XSORTIN1.
When you use more than one input file:
• You cannot do an Address-out (SORTA) sort.
• You cannot do an in place sort, in which output file overlays input file.
• XSORT bases its operations on the characteristics of the first file opened. All the other files are as-
sumed to have the same, or compatible, characteristics (file type and record length).
• You must be sure that all your specifications apply to all the records in all the files you wish to use in a
multifile sort.
• Youcan ensure thatyoudo notaccidentallydo a single-filesort(instead of amultiple-filesort) byissuing
the following MPE command prior to running your XSORT program:
RESET XSORTIN
(See "Use of the MPE RESET Command.")
If single file input is from $STDIN, the specification records cannot be from $STDIN. They must be from a
file referenced by the formal designator XSORTEXT.
Work Space
• XSORT tells SORT how much work space will be required for performing the actual sort. For single-file
input from disk, it determines the space needed to sort by the number of records in the input file. You
can directly supply this number by specifying the "maximum numbers of records to be sorted", using the
S Option (See Section 4). This must be done in the following two cases:
• Single-file non-disk input--including $STDIN.
• Multiple-file input.
If only a small percentage of the records from a single-file sort are being selected and sorted, XSORT will
make more efficient use of resources if a reasonably accurate "maximum number of records to be sorted" is
specified using the S Option.
Output File
The output file is your sorted file. It can be a sequential MPE file or an already existing KSAM file. The
output can be given in one of three formats:
• Address-out.
• Record-out.
• Count-only. (No output file is produced. XSORT only prints sort statistics.)
The formal file designator is XSORTOUT.
If XSORTOUT does not already exist (non-disk files by definition already exist) then XSORT will create it
as a job temporary disk file. If XSORTOUT does already exist, then it must be the same file as XSORTIN.
In such an instance, the sort is an in place sort. (This requirement can be overridden by coding a "Y" in
column 8 of the S Option specs to allow output to an existing file other than XSORTIN.) XSORTOUT can
never be the same as any of the XSORTIN1 through XSORTIN9 files in a multiple-file sort.

1- 20
Data and Timing
Data Considerations
• Maximum data input record size is 8192 bytes.
• The collating sequence may be altered by the ALTSEQ specs. (See appendix C for further information
concerning data.)
Timing Factors
The time it takes to run a sort depends on the following factors:
• The number of records to be sorted. The fewer the records specified for sorting, the shorter the sort will
take.
• The record size. Larger records take longer to sort.
• The number of specifications you enter. The more specifications you have, the longer the sort will take.
• The alternating sequence. If you use ALTSEQ, your program will take longer to run.
Overview of XSORT Specifications
Specifications for Record-Out Sort (SORTR)
The columns that are shaded must be considered when you are planning a Record-out sort job.

1- 21
Specifications for Address-Out Sort (SORTA)
The columns that are shaded must be considered when you are planning an Address-out sort job.

1- 22
Specifications for Count-Only Sort (SORTC)
The Columns that are shaded must be considered when you are planning a Count-only sort.