Manually Describing RMS Files

In this section:

These topics outline the procedures necessary for manually describing RMS files.


Top of page

x
File Attributes

In this section:

File attributes are FILENAME, SUFFIX, and, optionally, DATASET, which name the file and describe the file type and data source location. For example:

FILENAME=LIBRARY1, SUFFIX=RMS, DATASET=mydata.DAT ,$


x
FILENAME

The FILENAME attribute is optional. It is recommended that you include the file name for documentation purposes. You can specify any name for this attribute, but you should use the same name that you give the Master File.

The syntax is

FILE[NAME] = name

where:

name

Is any name of 1 to 8 characters.



x
SUFFIX

The SUFFIX attribute describes the type of data file it will read.

The syntax is:

SUFFIX = type

where:

type

Is a suffix listed in the following table:

Type of File

Suffix

Physical Access Method

Keyed (Indexed) or unkeyed RMS file

RMS

RMSFILE in Access File

or

DATASET attribute in the Master File

Fixed-format sequential file

FIX
FILEDEF

Comma-delimited sequential file

COM
FILEDEF

The description of data and relationships between fields within a file is the same for keyed (indexed) RMS files, FIX (fixed-format sequential) files, and COM (comma-delimited) files, except for the following differences:



x
DATASET

DATASET is an optional attribute that specifies the physical location of the data source. It is used at the file declaration level of the Master File. The syntax is

{DATASET|DATA}='filename'

where:

filename

Is the platform-dependent physical name of the data source.


Top of page

x
Segment Attributes

In this section:

A Master File can be divided into segments, which are groups of fields that are related to one another. It is not always necessary to divide your file into segments.

Segment declarations identify and describe each segment in a file. They name the segments and indicate the relative positions in the file structure. In files with multiple record types, each record type will be described as a separate segment. Files with mixed singly- and multiply-occurring fields must also be described with separate segments defined for each type of occurrence. The attributes used to describe segments of different record types and multiply-occurring fields are described in Describing Multiple Record Types and in Describing Embedded Repeating Data.

The following is an example of a segment declaration:

SEGNAME=BOOKINFO, PARENT=PUBINFO, SEGTYPE=S0,$


x
SEGNAME

Each segment declaration starts with the SEGNAME (or SEGMENT) attribute, which names the segment.

The syntax is

{SEGNAME|SEGMENT}= name

where:

name

Is a unique name of 1 to 8 characters.



x
PARENT

Files with more than one segment are defined as multi-segment structures.

Segments in a multi-segment structure have a parent/child relationship. Each segment, except the top or "root" segment, is the descendant of another segment called the "parent." The PARENT attribute is used to identify a segment's parent segment. If no PARENT attribute is specified in the Master File, the default parent segment is the immediately preceding segment, except for the top segment, which has no parent.

The syntax is

PARENT = name

where:

name

Specifies a SEGNAME in the file.

For example:

...PARENT=PUBINFO...


x
SEGTYPE

The SEGTYPE attribute for RMS files is specified as S0.

The required syntax is:

SEGTYPE=S0

Top of page

x
Field Attributes

In this section:

Field attributes describe the actual fields in each segment. Each field declaration consists of at least four attributes. They are:

FIELDNAME   ALIAS   USAGE   ACTUAL

For example:

FIELDNAME=PUBNO ,ALIAS=PN ,USAGE=A10 ,ACTUAL=A10 ,$

There are also other optional attributes that can be used, such as DESCRIPTION, TITLE, and ACCEPT. DESCRIPTION enables you to include a description of the field. TITLE is the default report column title other than the field name. ACCEPT assigns a list or range of acceptable values to a field. ACCEPT is also used for RECTYPE values. These optional attributes are used by FOCUS, WebFOCUS, and various other client products. For further information about optional attributes, see the appropriate manuals.



x
FIELDNAME

Field names are unique names of 1 to 66 characters with the exception of indexes, which are limited to12. The field name appears as a default column heading when you name the field in a report request. Field names may consist of any alphanumeric characters, but the first character must be a letter from A to Z. Field names may include embedded blanks, but it is not recommended, and you will need to enclose such a field name in single quotation marks (') if you reference the complete name (including the blank) in a request. Avoid using special characters (+ - $ * /() ' ; . , = and " > <), since they may cause confusion if the field is used in calculations.

The syntax is

FIELD[NAME] = name

where:

name

Meets the criteria described above.



x
ALIAS

Aliases are optional field names. Each field can have an alias to be used interchangeably with the field name. The length and format rules for field names apply to aliases. Aliases are not used as column titles.

The syntax is

ALIAS = alias

where:

alias

Is a name of 1 to 66 alphanumeric characters meeting the same criteria as for field names.

If you omit the alias, you must indicate its absence with either the following entry in the field declaration

ALIAS=,

or by holding its place with a comma delimiter (,):

FIELDNAME=PUBNO , ,USAGE=A10 ,ACTUAL=A10 ,$


x
USAGE

The USAGE attribute describes the way you want to use the field and display its values on reports. This attribute includes the data field type, display length, and any edit options that are to be applied when the field values are printed.

The syntax is

USAGE = usage 

where:

usage

Describes the field in three parts: field type, field display length, and edit options.

The values that you specify for type and display length determine the number of print positions allocated for the field in any display or report. Edit options only affect printed or displayed fields; they are not active for extract files or other non-display retrievals.

The following table shows permissible USAGE field types and display lengths:

USAGE

Length

Description

A

1-9,095

Alphanumeric text

D

1-19

Decimal, double-precision numbers

F

1-9

Decimal, single-precision numbers

I

1-11

Integer values (no decimal places)

P

1-17

Packed decimal numbers

YYMD

10

Displayed as YYMD

D,W,M,Q or Y

Date

Date display

The following table shows edit options that may be applied to various A, D, F, I, or P usages:

Edit Option

Meaning

Effect

%

Percent sign

Percent sign Displays a percent sign along with numeric data. Does not calculate the percent.

B

Bracket negative

Encloses negative numbers in parentheses.

c

Comma suppress

Suppresses the display of commas. Used with numeric format options M and N (floating and non-floating dollar sign) and data format D (floating-point double-precision).

C

Comma edit

Inserts a comma after every third significant digit, or a period instead of a comma if continental decimal notation is in use.

DMY

Day-Month-Year

Displays alphanumeric or integer data as a date in the form day/month/year.

E

Scientific notation

Scientific notation Displays only significant digits.

L

Leading zeroes

Adds leading zeroes.

M

Floating $ (for US code page)

Places a floating dollar sign $ to the left of the highest significant digit.

Note: The currency symbol displayed depends on the code page used.

MDY

Month-Day-Year

Displays alphanumeric or integer data as a date in the form month/day/year.

N

Fixed $(for US code page)

Places a dollar sign $ to the left of the field. The symbol displays only on the first detail line of each page.

Note: The currency symbol displayed depends on the code page used.

R

Credit (CR) negative

Places CR after negative numbers.

S

Zero suppress

Zero suppress If the data value is zero, prints a blank in its place.

Note:

  • Edit options can be specified in any order.
  • The total length of the USAGE specification, including all edit options, may not exceed eight characters.
  • Options M and N (floating and fixed dollar sign) both automatically imply option C (comma edit).
  • Format type D (double-precision decimal number) implies option C.

The following table shows the various USAGE formats as they would be specified in a Master File. The USAGE formats contain type and length information as well as various edit options. The Value column shows the actual value as it would be read from the external file, and the Display column shows how the number would be displayed on a report.

USAGE

Value

Display

I7C
47693
47,693
D10.2S
0.00
 
P8.0CR
-4719
4,719 CR
F8.2MC
28148.00
$28,148.00
I5B
-341
(341)
D7M
8741
$8,741
D7N
8741
$8,741
P6L
21
000021
D12.5
E1234.56
0.123456D+04
I6MDY
20675
02/06/75
A6YMD
750601
75/06/01
A10
HELLO
HELLO


x
ACTUAL

The ACTUAL attribute describes the type and length of your data as it actually exists in a file. The source of this information is the existing description of the file.

The syntax is

ACTUAL = actual

where:

actual

Is any of the format types listed in the following table:

ACTUAL Type

Definition

An

Alphanumeric characters A to Z, 0 to 9, and other displayable ASCII characters, where n equals 1 to 4,095.

D8

Double-precision floating-point numbers stored internally in eight bytes (D_Floating).

F4

Single-precision floating-point numbers stored internally in four bytes (F_Floating).

In

Binary integers:

I1 - Single-byte signed, binary integer (signed byte)
I2 - 2-byte signed, binary integer (signed word)
I4 - 4-byte signed, binary integer (signed longword)
I8 - 8-byte signed, binary integer (signed quadword)

If an integer field contains an assumed decimal point (that is, if it is a scaled integer), represent the field as Im.n, where m is the total number of storage bytes, and n is the number of decimal places. Therefore, I4.1 means a 4-byte number with one decimal place.

USAGE on a scaled integer should be minimally set up as a Pm+2.n.

Octaword data types are not supported.

Pn

Packed decimal format (packed numeric string) where n is the number of bytes (1 to 16), each of which contains two digits, except for the last byte, which contains a digit and the sign. For example, P6 means 11 digits plus a sign, packed two digits to the byte for the total of 6 bytes of storage.

Zn

Zoned decimal format (numeric string) where n is the number of digits (1 to 31), each of which takes 1 byte of storage. The last byte contains a digit and the sign.

There are several standards for zoned data. For Read purposes, only right overpunched standards are supported and can be determined on Read since they are unique.

The specific format to use when writing data must be known for read/write purposes. The default is ASCII right overpunch. To change the default, you must edit the EDACONF [.BIN]EDAENV.COM file and add the following logical:

DEFINE /NOLOG IBI_ZONED_OUT_TYPE {1|2}

where:

1

Is the ASCII right overpunched standard (default).

2

Is the EBCDIC right overpunched standard.

Zoned right separate numeric or zoned left overpunched numeric formats are not supported. Zoned left separate is supported by using a Am+1 ACTUAL and a numeric USAGE format.

DATE

DATE indicates that the field is an OpenVMS 64-bit datetime stamp. This usage also requires an A4 filler field immediately following in the Master File.

DATE/TIMESTAMP. Full OpenVMS date and timestamps are not directly supported. However, using a DEFINE in the Master File, you can declare a field as USAGE=A8, ACTUAL=A8. and then use the virtual (DEFINEd) field with HINPUT ( ) and CVTSTIME ( ) to support HDATE formats for output purposes.

The following conversions from ACTUAL format to USAGE (display) format are permitted:

ACTUAL

USAGE

A
A, D, F, I, P, date format
D
D
DATE
date format
F
F
I
I,P date format
P
P, date format
Z
D, F, I, P

The following table shows the USAGE and ACTUAL formats for COBOL, FORTRAN, PL1, and Assembler field descriptions.

COBOL USAGE FORMAT

BYTES OF COBOL PICTURE

INTERNAL STORAGE

ACTUAL FORMAT

USAGE FORMAT

DISPLAY
X(4)
4
A4
A4
DISPLAY
S99
2
Z2
P3
DISPLAY
9(5)V9
6
Z6.1
P8.1
DISPLAY
99
2
A2
A2
COMP
S9
4
I2
I1
COMP
S9(4)
4
I2
I4
COMP*
S9(5)
4
I4
I5
COMP
S9(9)
4
I4
I9
COMP-1**
"
4
F4
F6
COMP-2***
"
8
D8
D15
COMP-3
9
8
P1
P1
COMP-3
S9V99
8
P2
P5.2
COMP-3
9(4)V9(3)
8
P4
P8.3
FIXED BINARY(7)
(COMP-4)
B or XL1
8
I4
I7

* Equivalent to INTEGER in FORTRAN, FIXED BINARY(31) in PL/1, and F in Assembler.

** Equivalent to REAL in FORTRAN, FLOAT(6) in PL/1, and E in Assembler.

*** Equivalent to DOUBLE PRECISION or REAL*8 in FORTRAN, FLOAT(16) in PL/1, and D in Assembler.

Note:

  • The USAGE lengths shown are minimum values. They may be larger if desired. Additional edit options may also be added.
  • In USAGE formats, an extra character position is required for the minus sign if negative values are expected.
  • PICTURE clauses are not permitted for internal floating-point items.
  • USAGE length should allow for maximum possible number of digits.
  • In USAGE formats, an extra character position is required for the decimal point.



x
Describing Indexed Files (SUFFIX=RMS)

RMS keyed (indexed) files may be described using a SUFFIX of RMS, an attribute called GROUP, and a FIELDTYPE of I to designate a key. The GROUP attribute designates a key that is comprised of one or more contiguous fields. Additional keys may be described using either the GROUP or FIELD attribute, and a FIELDTYPE of I.


Top of page

x
Segment Name for Indexed Files

The segment name (SEGNAME value) of the first segment in an indexed file (SUFFIX=RMS) must be ROOT. The remaining segments can have any valid segment name. The only exception to this rule is for unrelated record types where the first segment name value must be DUMMY.


Top of page

x
Describing Keys

In this section:

The primary key is defined by the GROUP attribute and an alias value of KEY in the Master File. If there is a secondary key consisting of more than one field, it must also be described by the GROUP attribute and a numbered key. Otherwise, the secondary key can be indicated by using a FIELDTYPE of I in the field description.

The primary key of an RMS file is defined using the GROUP attribute, consisting of one or more fields. A file might only have one keyfield, but it must still be described with the GROUP declaration. The GROUP must contain ALIAS=KEY. Coding KEY without ALIAS= is not sufficient.

The GROUP declaration has the following syntax

GROUP=keyname, ALIAS=KEY, USAGE=usage, ACTUAL=actual,$

where:

keyname

Is a name of 1 to 66 characters.

The secondary keys of an RMS file are indicated by using ALIAS=KEY(n) and FIELDTYPE=I in the GROUP or FIELD declaration for the key. For example

GROUP=keyname, ALIAS=KEYn, USAGE=usage, ACTUAL=actual, FIELDTYPE=I,$

where:

keyname

Is a name of 1 to 48 characters.

KEYn

Indicates the alternate key.

The first alternate key is designated as KEY1, the second as KEY2, and so on.

Alternatively, if the secondary key is made up of only one field, the following syntax can be used:

FIELD=keyname, ALIAS=KEYn, USAGE=usage, ACTUAL=actual, FIELDTYPE=I,$


x
GROUP (for Contiguous Keys)

Contiguous keys consist of adjacent fields.

The GROUP attribute is used to define a contiguous primary key or a secondary key that is comprised of more than one field. The syntax is

GROUP=groupname,ALIAS=KEY[n],USAGE=usage,ACTUAL=actual,FIELDTYPE=I,$
  FIELD=fieldname,ALIAS=alias,USAGE=usage,ACTUAL=actual,$
  .
  .
  .
  FIELD=fieldname,ALIAS=alias,USAGE=usage,ACTUAL=actual,$

where:

groupname

Is a name of 1 to 48 characters.

KEY[n]

Indicates a contiguous key. Use only KEY to specify a primary key. Use KEY[n] to specify a secondary key, where n is a number from 1 to 254 that indicates the key reference number.

FIELDTYPE=I

Makes the key accessible for reporting and indicates that the key can be used for direct retrieval. Do not use FIELDTYPE=I for a primary key.

usage

Is the data type and length designation.

actual

Is the data type and length designation.

For example, consider the contiguous key in the first part of the following Master File:

FILENAME=MANUALS,SUFFIX=RMS,$
  SEGMENT=ROOT,SEGTYPE=S0,$
  GROUP=MDOCNUM        ,ALIAS=KEY  ,USAGE=A9      ,ACTUAL=A9      ,$
    FIELDNAME=DOCNUM   ,ALIAS=DN   ,USAGE=A5      ,ACTUAL=A5      ,$
    FIELDNAME=CODE     ,ALIAS=CD   ,USAGE=I6      ,ACTUAL=I4      ,$
    FIELDNAME=MRELEASE ,ALIAS=MR   ,USAGE=A7      ,ACTUAL=A7      ,$
    FIELDNAME=MPAGES   ,ALIAS=MP   ,USAGE=I5      ,ACTUAL=I2      ,$
         .
         .
         .


x
GROUP (for Discontiguous Keys)

Discontiguous keys consist of non-adjacent fields. If the GROUP attribute is used with discontiguous keys, the syntax is

GROUP=groupname,ALIAS=DKEY[n],USAGE=usage,ACTUAL=actual,FIELDTYPE=I,$
   FIELD=      ,ALIAS=alias  ,USAGE=usage,ACTUAL=actual,$
   .
   .
   .
   FIELD=      ,ALIAS=alias  ,USAGE=usage,ACTUAL=actual,$

where:

DKEY[n]

Indicates that this GROUP is the key layout for a discontiguous key. The GROUP declaration must explicitly specify ALIAS=DKEY. Use only DKEY to specify a primary key. Use DKEY[n] to specify a secondary key, where n is a number from 1 to 254 that indicates the key reference number.

alias

Is the name of the base field to which the discontiguous key field corresponds. Note that the field name for the key field must be blank.

usage

Is the data type and length designation.

actual

Is the data type and length designation.

FIELDTYPE=I

Makes the key accessible for reporting and indicates that the key can be used for direct retrieval. Do not use FIELDTYPE=1 for a primary key.

The fields that comprise the discontiguous key are described in the order in which they appear in the record. They are then re-described using the GROUP attribute. The order within the GROUP is determined by their order of significance within the discontiguous key.

For example, consider the discontiguous keys in the first part of the following Master File:

FILENAME=MANUALS,SUFFIX=RMS,$
   SEGMENT=ROOT,SEGTYPE=S0,$
      FIELDNAME=DOCNUM   ,ALIAS=         ,USAGE=A5   ,ACTUAL=A5      ,$
      FIELDNAME=CODE     ,ALIAS=CD       ,USAGE=I6   ,ACTUAL=I4      ,$
      FIELDNAME=MRELEASE ,ALIAS=         ,USAGE=A7   ,ACTUAL=A7      ,$
      FIELDNAME=MPAGES   ,ALIAS=         ,USAGE=I5   ,ACTUAL=I2      ,$
   GROUP=MANUALS_KEY     ,ALIAS=DKEY     ,USAGE=A12  ,ACTUAL=A12     ,$
      FIELDNAME=         ,ALIAS=DOCNUM   ,USAGE=A5   ,ACTUAL=A5      ,$
      FIELDNAME=         ,ALIAS=MRELEASE ,USAGE=A7   ,ACTUAL=A7      ,$
      .
      .
      .

Note that within each segment, you can only have one instance of a key reference number. For example, consider the following: KEY5 and DKEY4 can be in the same segment because they do not reference the same key, but KEY4 and DKEY4 cannot be in the same segment because they reference the same key.

A GROUP of DKEY can occur only at the end of the segment, following all of the "real" field definitions since DKEY contains references to "real" fields as base fields.

Note: OCCURS segments cannot contain any key definitions. Non-OCCURS segments must contain either KEY or DKEY definitions.



x
USAGE and ACTUAL

For multi-field GROUPs, USAGE and ACTUAL formats are always alphanumeric. The ACTUAL attribute is An, where n is the sum of the actual lengths of the subordinate fields. The USAGE format is the sum of the internal storage lengths of the subordinate fields.

For example, consider the discontiguous keys in a part of the following Master File:

.
.
.
FIELDNAME=FIELD1   ,ALIAS=         ,USAGE=P6   ,ACTUAL=P2      ,$
FIELDNAME=FIELD2   ,ALIAS=         ,USAGE=I9   ,ACTUAL=I4      ,$
FIELDNAME=FIELD3   ,ALIAS=         ,USAGE=A2   ,ACTUAL=A2      ,$
GROUP=ALTERNATE    ,ALIAS=DKEY     ,USAGE=A10  ,ACTUAL=A4      ,$
FIELDNAME=         ,ALIAS=FIELD3   ,USAGE=A2   ,ACTUAL=A2      ,$
FIELDNAME=         ,ALIAS=FIELD1   ,USAGE=P6   ,ACTUAL=P2      ,$
.
.
.

The GROUP declaration USAGE attribute tells how many positions to use for the group key. If this length is wrong, the group key will not be used correctly.

In this example, the lengths of the ACTUAL attributes for subordinate fields FIELD3 and FIELD1 total 4, which is the length of the ACTUAL attribute of the GROUP key. The lengths of the USAGE attributes for the subordinate fields total 8. However, the length of the GROUP key USAGE attribute is found by adding their internal storage lengths as specified by the field types: 2 for USAGE=A2 and 8 for USAGE=P6, for a total of 10.


Top of page

x
Single-Field Secondary Keys

Single-field secondary keys must be described as fields with FIELDTYPE=I. The ALIAS must be the key reference number as described in the RMS File Description Language (FDL), that is, KEYn or DKEYn, where n is a number from 1 to 254. Secondary keys can be described as GROUPs if they consist of portions with dissimilar formats. For example,

FILENAME=CUST,SUFFIX=RMS,$
SEGNAME=ROOT,SEGTYPE=S0,$
  GROUP=G             ,ALIAS=KEY    ,USAGE=A10  ,ACTUAL=A10,$
    FIELDNAME=SSN     ,ALIAS=SSN    ,USAGE=A10  ,ACTUAL=A10,$
    FIELDNAME=FNAME   ,ALIAS=KEY1   ,USAGE=A10  ,ACTUAL=A10,FIELDTYPE=I,$
    FIELDNAME=LNAME   ,ALIAS=KEY2   ,USAGE=A10  ,ACTUAL=A10,FIELDTYPE=I,$

Here, SSN is a primary key and FNAME and LNAME are secondary keys.

If you are not sure of the secondary keys associated with a given file, you can use the OpenVMS ANALYSE facility. Refer to the OpenVMS documentation for ANALYSE/RMS. The DIRECTORY command with the /FULL qualifier will also show how many keys the file has.


iWay Software