Manually Describing RMS Files

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.

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:

RMS

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:

• Keyed (indexed) RMS uses the keyed RMS File System to access data using information in the Access File declarations, where FIX and COM are fopen() accessed. Alternately you can use an RMSFILE= attribute in the Access File or override the DATASET= value with a FILEDEF. For more information, see Associating an RMS Data Source to a Master File.
• Index related declarations do not apply to fixed-sequential or comma-delimited files.

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

{DATASET|DATA}={'filename'|app/filename[.extension]}

where:

filename

Is the platform-dependent physical name of the data source. In a prior release, the physical name was required to be in single quotes. This is still valid syntax, but not required. A direct logical name such as MYQ2DATA: is also valid but must include the colon character, so it is distinct from an app-based name.

app/filename[.extension]

Is an app-based logical name of the data source. The default extension when no extension is supplied is .dat.

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.

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...

The SEGTYPE attribute for RMS files is specified as S0.

The required syntax is:

SEGTYPE=S0

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.

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 ,$

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:

A

D

F

I

P

YYMD

D,W,M,Q or Y

H

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

%

B

c

C

DMY

E

L

M

MDY

N

R

S

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.

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

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:

An

D8

F4

In

Pn

Zn

DEFINE /NOLOG IBI_ZONED_OUT_TYPE {1|2}

DATE

H

SET VMSTIMESTAMP = VMS

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

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.

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.

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,$
  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.

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      ,$
         .
         .
         .

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,$
   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.

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.

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.

• Fields of USAGE I have an internal storage length of 4.
• Fields of USAGE F have an internal storage length of 4.
• Fields of USAGE P have an internal storage length of either 8 or 16.
• Fields of USAGE D have an internal storage length of 8.
• Alphanumeric fields have an internal storage length equal to the number of characters they contain as their field length. For example, fields of type An have an internal storage length of n.
• Natural date formats that are treated as integers have an internal storage length of 4.

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.