Define Command [D]
Defines fields that can be used in the Duplicate, Extract, If, Item, Sort, Table, and
Total commands. With Define, you can do selection on ordinary data files using the same kind of readable "expression" that you use with databases. You can also access data fields that are not actually structured as defined in the database (e.g., implicit subfields within an IMAGE field).
DEFINE field, definition
field is an identifier up to 32 characters long, must begin with a letter, and can consist of letters A through Z, digits 0 through 9, or the following symbols:
+ - * / ? # % & @ _ $ '
In the case where the field name is written to a self-describing file, only the first 16 characters are used.
definition can be in two different forms: absolute or relative.
Absolute Definitions
DEFINE field, byteposition, sublen [,type]
[,subcount]
(Default: type=BYTE, subcount=1)
The byteposition is a positive integer giving the byte index where the field starts. The first byte is always number 1, not 0. The sublen is the number of bytes in the field.
When the subcount is 1 (default), the sublen is the total number of bytes in the field.
When you specify a subcount, the sublen is the byte-length of each subfield.
See Data-Types below for the definition of type.
>input uxfile,r 40, lf {input from a disc file}
>def qty,14,4,double {double integer (PIC S9(9) COMP)}
>def name,5,6 {character string of 6 bytes}
>sort name {sort using the field "name"}
>total qty {total all the values of the field "QTY"}
>exit
Relative Definitions
[,subcount]
DEFINE field,
fieldname [ (subscript) ] [ [offset] ]
[,sublen] [,type] [,subcount]
(Default: sublen/type=same as fieldname)
The fieldname is a field from an Eloquence dataset specified in Get or Chain, or a column from a table specified in Select, or a field from a self-describing file, or another Defined field. Relative definitions are similar to COBOL's Redefine verb.
Suprtool 4.6 for HP-UX: Suprtool Suprtool Commands
• 69
The sublen and type are optional. They default to the total byte length and type of the
fieldname. The (subscript) parameter is an optional sub-item index for arrays such as
Eloquence compound items like 5J2 or 4X20. The first sub-item is number 1, and if no subscript is provided, Suprtool uses the first sub-item. The [offset] parameter is optional and specifies a byte offset from the position that would otherwise be used.
This allows you to define fields relative to other fields. The [offset] starts at 1 and not at 0 (i.e., FIELD[1] is the first byte of the field).
To define a field that corresponds to the second index of the address array of the customer file, you would use:
>in customer {self-describing file}
>define city,address(2)
>if city="Vancouver"
>list
>xeq
Data-Types
Here are the valid types:
Type Description
PACKED packed-decimal
PACKED* packed-decimal, last nibble unused
DISPLAY zoned-decimal numeric field
CHARACTER for Native Language Support
The Define command also accepts Fpoint as the data-type for IEEE numbers.
The following table shows the Suprtool definitions for the IMAGE data-types:
IMAGE Type
I1
I2
Number of Bytes COBOL
Declaration
2
4
S9(4) COMP
S9(9) COMP
SUPRTOOL
Definition
>define a,1,2,integer
>define a,1,4,double
J1
J2
2
4
S9(4) COMP
S9(9) COMP
>define a,1,2,integer
>define a,1,4,double
70
• Suprtool Commands
Pn n/2 S9(n-1) COMP-3
>define a,1,n/2,packed
K1 2 >define
Suprtool 4.6 for HP-UX: Suprtool
Suprtool 4.6 for HP-UX: Suprtool
K2 4 >define
E2 4 >define
E4 8 >define
Data-type Display may have a trailing overpunch sign.
Packed-Decimal Fields
When defining packed-decimal fields, you must convert the number of decimal digits into a byte count. The last digit of a decimal field is always used for the sign.
There are two data-types for decimal fields: PACKED for those that end on a byte boundary and PACKED* for those that end in the middle of a byte. Here are some example definitions of packed-decimal fields:
Suprtool Definition
>define m,1,2,packed
>define n,1,2,packed*
>define p,1,6,packed
Description
s9(3) COMP-3, P4 in IMAGE, 2 bytes, 4 nibbles, last is sign digit s9(2) COMP-3, P4 in IMAGE, 2 bytes, 4 nibbles, last digit is unused s9(11) COMP-3, P12 in IMAGE, 6 bytes, 3 words, 11 digits
Data-Type Warning
The Define command accepts field definitions of any combination of byte-length and data-type. However, many combinations have limited usefulness in Suprtool. In these cases, Suprtool prints a warning. For example:
>def field,1,1,integer
Warning: Length of 1 is of limited use for the data-type INTEGER
Examples
The following examples show the various data-types and combinations that are available with the Define command:
>define a,11,4,double {J2 or I2, S9(9) COMP}
>define b,21,2,int {J1 or I1, S9(4) COMP}
>define e,21,8 {character string}
>define f,address(5) {fifth occurrence of address}
>define g,address(5)[3],4 {relative offset}
>define h,address(5)[4],2,byte {middle of the address}
>define i,x[6],4 {starts at sixth byte of X}
>define j,invoice,6,byte {redefine field as Byte}
Absolute Example
The following example shows the most basic use of the Define command to create a new field definition at an absolute location in the input record.
Suprtool Commands
• 71
72
• Suprtool Commands
{"amt" is an integer that starts at the 11th byte of file}
>def amt,11,2,int
>if amt > 1000 {"amt" is now a field we can select on}
>output outfile
Absolute Example with Subcount
IMAGE and Suprtool allow fields to be repeated. In the next example, we define an amount field that repeats twelve times (e.g., once for each month of the year). We use a subscript when we want to refer to a specific month.
>def amt,11,2,int,12 {"amt" is an integer that repeats 12 times}
>if amt(5) > 1000 {we select on the 5th subfield}
>output outfile
Relative Examples
Use the simplest form of relative definitions to rename existing fields.
>def quantity,qty {"quantity" is a more readable name}
>if quantity = "100 " {selection on the new field}
The Define command copies the byteposition, sublength, and type to the new field, but it does not copy the subcount. Define assumes that you want the first subfield:
>def amount,amt {amt is 12J2}
>if amount > 1000 {amount is 1J2 and is the same as amt(1)}
Relative Example with Subcount
Because Suprtool defaults the subcount to one, you might want to specify an explicit subcount when giving a new name to an existing field.
>def amount,amt,,,12 {amt is 12J2; same length and type}
>if amount(5) > 1000 {amount is 12J2; we are selecting for May}
Relative Example with Subscript
Use subscripts to define a new field that corresponds to a specific subfield.
>def may,amt(5) {amt is 12J2}
>if may > 1000 {may is the fifth subfield}
Relative Example with Offset
Many applications define subfields within a larger character field. A common example is a part-number where the first four digits are the warehouse location, the second four digits are the bin number, and the last four digits are a serially assigned number. Use the offset parameter to define new fields that are relative to the start of the part number. The file INVOICES is a self-describing file.
>in invoices {part is 12 bytes}
>def warehouse,part,4 {warehouse starts at part}
>def bin,part[5],4 {bin is second four bytes}
>def release,part[9],4 {release is the last four bytes}
>if bin = "100" {use any field for selection}
Note that redefining the digits of a larger numeric field only works when the field is a character field (type X, U, or A).
Suprtool 4.6 for HP-UX: Suprtool
The Extract command may be used for data conversion. See
the Data Conversion section
of the Extract command for details.
Relative Example Combining Subscripts and Offsets
If we have ten part numbers combined into one field (e.g., 10X12) we can still define a single field that corresponds to the bin number of one of the parts.
>in invoices {allparts is 10X12}
>def bin3,allparts(3)[5],4 {we are checking starting at the fifth byte …}
>if bin3 = "100" {… of the third part}
Notes
The purpose of the Define command is to tell Suprtool to look at a portion of the input record in a certain way. For example, if the record contains ASCII digits in the first ten bytes, Define could be used to assign a field definition to the first six bytes.
In this case, the field must be defined as data-type Byte, Char or Display.
The Define command cannot be used to convert data from one format to another.
Using the same example, the Define command could not be used to treat the first six digits of the ten digit ASCII field as Integer, Packed, Real, or any other numeric data format. If the input record contains ASCII digits, Define cannot change them to another data-type.
It may be helpful to think of the Suprtool Define command as similar to a COBOL
REDEFINES clause, or a FORTRAN EQUIVALENCE statement.
Suprtool 4.6 for HP-UX: Suprtool Suprtool Commands
• 73
