Managing RMS Metadata

In this section:

When the server accesses a data source, it needs to know how to interpret the data stored there. For each data source the server will access, you create a synonym that describes the structure of the data source and the server mapping of the RMS data types.

You can create metadata:

Both methods describe data files to the server for OpenVMS with a Master and an Access File.

The Master File describes the type of data file you are using, the structure, and the fields it contains. The Access File provides a number of attribute parameters, including SHARED ACCESS to support READ/WRITE capabilities and an RMSFILE attribute, which offers one method for associating the data source with the Master File. For details about Access File uses, see When to Use an Access File With an RMS Data Source.


Top of page

x
Creating Synonyms

How to:

Reference:

x

Synonyms define unique names (or aliases) for each RMS table or view that is accessible from the server. Synonyms are useful because they hide the underlying data source location and identity from client applications. They also provide support for extended metadata features of the server, such as virtual fields and additional security mechanisms. Using synonyms allows an object to be moved or renamed while allowing client applications to continue functioning without modification. The only modification required is a redefinition of the synonym on the server. The result of creating a synonym is a Master File and an Access File, which represent the server metadata.



x
Procedure: How to Create a Synonym

To create a synonym, you must have previously configured the adapter. You can create a synonym from the Applications or Adapters pages of the Web Console.

  1. From the Web Console menu bar, click Applications.

    The Applications page opens.

  2. Click the New button and select Synonym from the drop-down menu.

    The Select adapter to configure or Select connection to create synonym pane opens.

  3. Click a connection for the configured adapter.

    The first of a series of synonym creation panes opens.

  4. Enter values for the parameters required by the adapter as described in the synonym creation parameters reference.
  5. After entering the parameter values, click Create Synonym.

    The Status pane indicates that the synonym was created successfully.

The synonym is created and added under the specified application directory.

Note:



x
Reference: Synonym Creation Parameters for RMS

The following list describes the parameters for which you will need to supply values, and related tasks you will need to complete in order to create a synonym for the adapter. These options may appear on multiple panes. To advance from pane to pane, click the buttons provided, ending with the Create Synonym button, which generates the synonym based on your entries.

Select potential candidates for synonyms:

Synonym Candidates

You can base your synonym on either CDD definitions or COBOL definitions. Choose one of these options from the drop-down list.

Next, you must specify the locations of either the CDD or COBOL definitions. Options vary depending on the selection you make here.

For related information about COBOL File Descriptions, see Translating COBOL File Descriptions.

For CDD definitions:

Location of CDDs

If your repository is in a non-standard location (that is, one which is not declared by CDD$DEFAULT), you can supply the CDD location here.

If CDD$DEFAULT is declared, its current value appears in the input box, where you may leave it as is or change it.

CDD name

Type a filter for retrieving a partial list of CDD references (for example, those starting with V%).

You must supply filter values in uppercase characters, followed by a % sign. OpenVMS wildcards are not permitted.

For COBOL definitions:

Directory Path

Specify a full path directory name where the COBOL definitions are located. (Wild card characters are not permitted.)

For information about specific layout and syntax requirements, see COBOL FD Syntax Requirements.

File Name/File Extension

If you wish to limit retrieval, you can type a file name and/or file extension:

  • In the File name box, type a full name or a partial name with a wildcard symbol %. A full name returns just that entry. A name with a wildcard symbol may return many entries.
  • In the File extension box, type an extension with or without the wildcard symbol %.

You must supply filter values in uppercase characters.

Location of RMS data files:

Directory path

Specify a full path directory name where RMS is located. This may be a logical that points to the full directory path or a directory path that uses a logical. OpenVMS wildcards are not allowed.

File Name

Type a filter for retrieving a partial list of RMS file names in the directory (for example, those starting with V%).

You must supply filter values in lowercase characters, followed by a % sign. OpenVMS wildcards are not allowed.

File Extension

Type a filter for retrieving a partial list of RMS files based on the file extensions within the directory.

The normal default for RMS files, dat%, is pre-populated in the input box and must not be changed if you wish to search for .dat files.

You can change the .dat value by specifying a filter to access files that do not use the RMS normal default (that is, those starting with rms%). You must supply filter values in lowercase characters, followed by a % sign. OpenVMS wildcards are not allowed.

Get Candidates button

Click this button to obtain the selection list of candidates for which synonyms can be created.

Select actual candidates for synonyms:

Application

Select an application directory. The default value is baseapp.

Prefix/Suffix

If you have tables with identical table names, assign a prefix or a suffix to distinguish them. For example, if you have identically named human resources and payroll tables, assign the prefix HR to distinguish the synonyms for the human resources tables. Note that the resulting synonym name cannot exceed 64 characters.

If all tables and views have unique names, leave the prefix and suffix fields blank.

Tip: While you can change individual names in the list, entering a prefix or suffix enables you to make global changes that are particularly useful when many synonyms are being created.

An alternate method for dealing with duplicate names is to store them in separate application directories and change the application path as needed for a particular table.

Overwrite Existing Synonyms

To specify that this synonym should overwrite any earlier synonym with the same fully qualified name, select the Overwrite existing synonyms check box.

Note: The connected user must have operating system write privileges in order to recreate a synonym.

Set COBOL FD translation options

For a COBOL FD, optionally, select Customize COBOL FD conversion options to customize how the COBOL FD is translated. If you do not select the check box, default translation settings are applied.

For more information, see Customization Options for COBOL File Descriptions.

Validate

Select the Validate check box if you wish to convert all special characters to underscores and perform a name check to prevent the use of reserved names. (This is accomplished by adding numbers to the names.) This parameter ensures that names adhere to specifications. See Validation for Special Characters and Reserved Words for more information.

When the Validate option is unchecked, only the following characters are converted to underscores: '-'; ' '; ' \'; '/'; ','; '$'. No checking is performed for names.

Make unique

Select the Make unique check box if you wish to set the scope for field and group names to the entire synonym. This ensures that no duplicate names are used, even in different segments of the synonym. When this option is unchecked, the scope is the segment.

For CDD definitions:

Default Synonym Name

This column displays the name that will be assigned to each synonym. To assign a different name, replace the displayed value.

Select CDD records

To select all CDD records in the list, select the check box to the left of the Default Synonym Name column heading.

To select specific records, select the corresponding check boxes.

Associate records to physical files

In the list of CDD objects and data files, use the pull-down menu on the right to associate the CDD record with the physical data file.

For COBOL definitions:

Default Synonym Name

This column displays the name that will be assigned to each synonym. To assign a different name, replace the displayed value.

Select COBOL records

To select all COBOL records in the list, select the check box to the left of the Default Synonym Name column heading.

To select specific records, select the corresponding check boxes.

Associate records to physical files

In the list of COBOL objects and data files, use the pull-down menu on the right to associate the COBOL record with the physical data file.



Example: Creating a Synonym Using a COBOL File Description

To generate the following synonym from the Web Console or the Data Management Console Create Synonym panes:

  1. On the first Create Synonym pane, select COBOL FD from the Synonym Candidate drop down list.
  2. To specify the location of the COBOL FD, enter mydata:[RMS] as the Directory Path.
  3. Leave the File Name field blank and accept the default extension, cbl, to filter the list of COBOL FDs.
  4. Next, specify the location of the RMS data files. Enter mydata:[RMS] as the Directory Path.
  5. Leave the File Name field blank and accept the default extension, dat.
  6. Click the Get Candidates button.
  7. The list of candidates is displayed on the second Create Synonym pane. Click the check box for rmscar.cbl in the first column.
  8. To associate the selected candidate with a particular COBOL data file, choose rmscar.dat from the pull-down menu in the RMS data file column.

    Tip: If you wish, you can choose a different data file at a later time using a FILEDEF, as described in Associating an RMS Data Source to a Master File.

  9. For this example, the default translation options are suitable, so leave the Customization options box unchecked.
  10. Click the Create Synonym button.

    The synonym is created and added under the specified application directory (baseapp is the default).

    A status window displays the message: All Synonyms Created Successfully

  11. From the message window, click Applications on the menu bar.
  12. Open the baseapp application folder in the navigation pane and click the synonym rmscar.
  13. Choose Edit as Text from the menu to view the generated Master File.

    Generated Master File:

    FILENAME=RMSCAR, SUFFIX=RMS     ,
     DATASET=TSCQDATA:[TSCQDATA.RMS]rmscar.dat, $
      SEGMENT=ROOT, SEGTYPE=S0, $
       GROUP=ROOT, ALIAS=E2, USAGE=A62, ACTUAL=A62, $
       GROUP=PRIMARYKEY, ALIAS=KEY, USAGE=A50, ACTUAL=A50, $
        FIELDNAME=COUNTRY, ALIAS=E3, USAGE=A10, ACTUAL=A10, $
        FIELDNAME=CAR, ALIAS=E4, USAGE=A16, ACTUAL=A16, $
        FIELDNAME=MODEL, ALIAS=E5, USAGE=A24, ACTUAL=A24, $
        FIELDNAME=BODYTYPE, ALIAS=E6, USAGE=A12, ACTUAL=A12, $
        FIELDNAME=SEATS, ALIAS=E7, USAGE=I8, ACTUAL=I4, $
        FIELDNAME=RETAIL_COST, ALIAS=E8, USAGE=I8, ACTUAL=I4, $
        FIELDNAME=DEALER_COST, ALIAS=E9, USAGE=I8, ACTUAL=I4, $
        FIELDNAME=SALES, ALIAS=E10, USAGE=I8, ACTUAL=I4, $
  14. To see the Access File, choose Edit Access File as Text.

    Generated Access File:

    ACCESS=SHARED, $


Example: Creating a Synonym Using CDD Record Definitions

To generate the following synonym from the Web Console or the Data Management Console Create Synonym panes:

  1. On the first Create Synonym pane, select CDD Definition from the Synonym Candidate drop down list.
  2. To specify the location of the CDDs, enter mydata:[RMS.CDDPLUS] as the Directory Path.
  3. In the CDD Name field, enter R% to filter the list of CDD definitions. (Uppercase characters are required.)
  4. Next, specify the location of the RMS data files. Enter mydata:[RMS.CDDPLUS as the Directory Path.
  5. Click the Get Candidates button.
  6. The list of candidates is displayed on the second Create Synonym pane. Click the check box for rmscar in the first column.
  7. To associate the selected candidate with a particular CDD data file, choose rmscar.dat from the pull-down menu in the RMS data file column.

    Tip: If you wish, you can choose a different data file at a later time using a FILEDEF, as described in Associating an RMS Data Source to a Master File.

  8. Click the Create Synonym button.

    The synonym is created and added under the specified application directory (baseapp is the default).

    A status window displays the message: All Synonyms Created Successfully

  9. From the message window, click Applications on the menu bar.
  10. Open the baseapp application folder in the navigation pane and click the synonym rmscar.
  11. Choose Edit as Text from the menu to view the generated Master File.

    Generated Master File:

    FILENAME=RMSCAR, SUFFIX=RMS     ,
     DATASET=TSCQDATA:[TSCQDATA.RMS]rmscar.dat, $
      SEGMENT=ROOT, SEGTYPE=S0, $
       GROUP=PRIMARYKEY, ALIAS=KEY, USAGE=A50, ACTUAL=A50, $
        FIELDNAME=COUNTRY, ALIAS=COUNTRY, USAGE=A10, ACTUAL=A10, $
        FIELDNAME=CAR, ALIAS=CAR, USAGE=A16, ACTUAL=A16, $
        FIELDNAME=MODEL, ALIAS=MODEL, USAGE=A24, ACTUAL=A24, $
        FIELDNAME=SEATS, ALIAS=SEATS, USAGE=P7, ACTUAL=I4, $
        FIELDNAME=RETAIL_COST, ALIAS=RCOST, USAGE=P7, ACTUAL=I4, $
        FIELDNAME=DEALER_COST, ALIAS=DCOST, USAGE=P7, ACTUAL=I4, $
        FIELDNAME=SALES, ALIAS=SALES, USAGE=P7, ACTUAL=I4, $
  12. To see the Access File, choose Edit Access File as Text.

    Generated Access File:

    ACCESS=SHARED, $


x
Reference: Managing Synonyms

Once you have created a synonym, you can right-click the synonym name in the Adapter navigation pane of either the Web Console or the Data Management Console to access the following options.

Option

Description

Open

Opens the Master File for viewing and editing using a graphical interface. If an Access file is used it will be also available.

Edit as Text

Enables you to view and manually edit the Master File synonym.

Note: To update the synonym, it is strongly recommended that you use the graphical interface provided by the Open option, rather than manually editing the Master File.

Edit Access File as Text

Enables you to view and manually edit the Access File synonym.

Note: This option is available only when an Access File is created as part of the synonym.

Sample Data

Retrieves up to 20 rows from the associated data source.

Data Profiling

Data Profiling provides the data characteristics for synonym columns.

Alphanumeric columns provide the count of distinct values, total count, maximum, minimum, average length, and number of nulls.

Numeric columns provide the count of distinct values, total count, maximum, minimum, average value, and number of nulls.

Refresh Synonym (if applicable)

Regenerates the synonym. Use this option if the underlying object has been altered.

Data Management

Followed by these options, if applicable:

Recreate DBMS Table. Recreates the data source table. You are asked to confirm this selection before the table is regenerated. (Note that the table will be dropped and recreated. During the process, data may be lost.)

Delete All Data. Deletes all existing data. You are asked to confirm this selection before the data is deleted.

Insert Sample Data. Inserts specified number of sample records, populating all fields with counter values.

Reorganize. Recreates the data source table preserving original data.

Note: This option is not available in the Web Console.

Impact Analysis

Generates reports on procedures, synonyms, and columns that provide information on the flows/stored procedures available on a particular server, and the synonyms and columns they use. These reports enable you to evaluate changes before they are made by showing which components will be affected. See the Server Administration for UNIX, Windows, OpenVMS, IBM i, and z/OS manual for details about Impact Analysis reports.

Copy

Copies the synonym to the clipboard.

Delete

Deletes the synonym. You are asked to confirm this selection before the synonym is deleted.

Cut

Deletes the synonym and places it on the clipboard.

Properties

Displays the properties of the synonym, including physical location, last modified date, description, and privileges.


iWay Software