Managing IMS Metadata

Creating Synonyms

How to:

Create a Synonym

Reference:

Synonym Creation Parameters for IMS
Managing Synonyms
Defining Subsets of DBD Segments and IMS Fields in Segments

xSynonyms define unique names (or aliases) for each IMS PSB that is accessible from a server. Synonyms are useful because they hide location information and the identity of the underlying data source from client applications. They also provide support for extended metadata features of the server, such as virtual fields and additional security mechanisms.

For the Adapter for IMS to access an IMS PSB, you must create a synonym for each IMS PSB you access. The logical description of an IMS file is stored in a Master File, which describes the field layout.

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

Procedure: How to Create a Synonym

From the Web Console sidebar, click Applications or Connect to Data.

The Applications page opens.
If you started from the Applications page, right-click an application folder, point to New, and click Synonym on the context menu.

The Connect to Data page opens.
On the Configured list, click the down arrow next to a connection for the configured adapter, or right-click a connection.
Depending on the type of adapter you chose, one of the following options appears on the context menu.
- Show DBMS objects. This opens the page for selecting synonym objects and properties.
- Create metadata objects. This opens the page for selecting synonym objects and properties.
- Show files. This opens a file picker. After you choose a file of the correct type, the page for selecting synonym objects and properties opens.
- Show local files. This opens a file picker. After you choose a file of the correct type, the page for selecting synonym objects and properties opens.
- Show topics. This opens the page for selecting synonym objects and properties for topics within the Kafka environment.
Enter values for the parameters required by the adapter as described in the chapter for your adapter.
After entering the parameter values, click the highlighted button on the ribbon.

The button may be labeled Next, Create Synonym, Create Base Synonyms, Create Cluster Synonym, or Update Base Synonyms.

The synonym creation process for most adapters has been consolidated so that you can enter all necessary parameters on one page. However, for some adapters such as LDAP, you must click Next buttons until you get to a page that has a Create Synonym button.

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

Note: When creating a synonym, if you choose the Validate check box (where available), the server adjusts special characters and checks for reserved words. For more information, see Validation for Special Characters and Reserved Words.

Reference: Synonym Creation Parameters for IMS

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.

Filter PSB Name

Selecting this check box adds a Name input field that allows you to filter the PSB names for which you wish to create synonyms.

Enter a string for filtering the PSB names, inserting the wildcard character (%) as needed at the beginning and/or end of the string. For example, enter ABC% to select PSBs which begin with the letters ABC; %ABC to select PSBs which end with the letters ABC; %ABC% to select PSBs which contain the letters ABC at the beginning, middle, or end

DBD library name

Is the MVS library name that corresponds to the IMS DBDLIB. This must be a fully qualified MVS data set name.

PSB library name

Is the MVS library name that corresponds to the IMS PSBLIB. This must be a fully qualified MVS data set name.

PSB Selection

Select a member name from the drop-down list.

COBOL FD Selection Options

Map using COBOL FDs

Select this option if you have a Cobol FD library available that describes the PCB view. You have to select segments in this case.

If you do not select this option, the final screen opens without the option to select a Cobol FD entry. Create Synonym then creates a skeleton synonym using the Data Base Definition defined fields.

File System

Select one of the following from the drop-down list:

Fully qualified PDS name to enter a fully qualified MVS Library in the entry box.
Absolute HFS directory pathname to enter the HFS location that contains the COBOL FD.
Applications to enter a pre-configured HFS directory.

PDS name or Directory name

Depending on your selection for File System, enter the fully qualified PDS name or absolute directory path that contains the COBOL FD.

Member Name or File Name

Depending on your selection for File System, enter the member name or file that contains the COBOL FD.

You can enter a string for filtering these names, inserting the wildcard character (%) as needed at the beginning and/or end of the string. For example, enter ABC% to select names which begin with the letters ABC; %ABC to select names which end with the letters ABC; %ABC% to select names which contain the letters ABC at the beginning, middle, or end.

File Extension

If you selected Absolute HFS directory pathname as the file system, enter the extension of the file that contains the COBOL FD.

COBOL FD

For each segment that you want to map using a COBOL FD, select the appropriate COBOL FD from the drop-down list.

Additional Options

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.

Customize

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.

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.

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.

Default Synonym Name

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

Example: Creating a Synonym

Use the following steps to create a synonym for the AIHDAM data source:

From the Web Console menu bar, click Applications.
The Applications page opens.
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.
Click IMS DBCTL.
Note: You can also create a synonym from the Adapters page by right-clicking the configured IMS connection and selecting Create Synonym.
Enter the fully qualified DBD library name in the DBD Library input box. For example:
```
IMS.V7R1M0.B.DBDLIB
```
Enter the fully qualified PSB library name in the PSB Library input box. For example:
```
IMS.V7R1M0.B.PSBLIB
```
Check Filter PSB Name and enter the following mask in the text box that displays:
```
ai%
```
Click Next.
The PSB Selection screen opens.
Select the appropriate PSB name from the drop-down list, for example: AIHDPSB.
If you have a COBOL FD for the database, check Map using COBOL FDs.
Click Next.
The PCB Selection screen opens.
Select the appropriate PCB, for example, PCB number 5 (which has a secondary index defined).
Optionally, edit the name for the synonym in the Default Synonym Name column and select the application under which you want to create this synonym (the default application is baseapp).
If you checked Map using COBOL FDs in Step 9, enter the information about the COBOL FD for the file system you use for each segment:
- If you select Fully qualified PDS name, enter the name of the PDS that contains the COBOL FD and the member name of the COBOL FD.
- If you select Absolute HFS directory pathname enter the path to the COBOL FD and its file name and extension.
- If you select Applications, choose from the provided HFS directories.
Click Create Synonym.
You should get a message indicating that the synonym was created successfully.
To view the Master File created, go to the Metadata page, open the application under which you created the synonym, click the synonym name, and select Edit as Text from the context menu. This example resulted in the following Master File:
```
FILENAME=AIHDAM, SUFFIX=IMS     , $
  SEGMENT=LANGUAGE, SEGTYPE=S0, $
$  GROUP=AIHDAM_IO, ALIAS=E1, USAGE=A19, ACTUAL=A19, $
    FIELDNAME=EMPL6, ALIAS=EMPL6.HKY, USAGE=I11, ACTUAL=I4, $
    FIELDNAME=LANG6, ALIAS=LANG6.IMS, USAGE=A15, ACTUAL=A15, $
```
To view the Access File created, go to the Metadata page, open the application under which you created the synonym, click the synonym name, and select Edit Access File as Text from the context menu. This example resulted in the following Master File:
```
PSB=AIHDPSB, WRITE=NO, PCBNUMBER=5, PL1=NO, $
  SEGNAME=LANGUAGE, KEYTYPE=S0, $
      XDFLD=IXEMP6, SRCH=EMPL6, ALTPCBNUMBER=5, $
```

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

For a list of options, see Synonym Management Options.

Reference: Defining Subsets of DBD Segments and IMS Fields in Segments

The SENSEG parameter is used in a PCB description to define a subset of accessible DBD segments. CREATE SYNONYM produces Master File segments based on the SENSEG information obtained from the PSB, and not from the database definition.

The SENSFLD parameter is used in a PCB description to define a subset of accessible IMS fields in a segment. IMS fields are defined in the DBD. The list of fields in a Master File SEGMENT is generated based on the SENSFLD information, and not on the DBD field definitions.

SENSFLD macros can redefine the layout of an IMS database segment record by using the "START = xx" parameter. Different layouts can be defined in the DBD and SENSFLD. The Master File segment layout (field information) is derived from the SENSFLD.

	WebFOCUS