Managing IMS Metadata

In this section:

When the server accesses a data source, it needs information on 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 IMS data types.


Top of page

x
Creating Synonyms

How to:

Reference:

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 (and a FOCPSB for XMI server mode) 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.



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

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:

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

    Note: You can also create a synonym from the Adapters page by right-clicking the configured IMS connection and selecting Create Synonym.

  4. Enter the fully qualified DBD library name in the DBD Library input box. For example:
    IMS.V7R1M0.B.DBDLIB
  5. Enter the fully qualified PSB library name in the PSB Library input box. For example:
    IMS.V7R1M0.B.PSBLIB
  6. Check Filter PSB Name and enter the following mask in the text box that displays:
    ai%
  7. Click Next.

    The PSB Selection screen opens.

  8. Select the appropriate PSB name from the drop-down list, for example: AIHDPSB.
  9. If you have a COBOL FD for the database, check Map using COBOL FDs.
  10. Click Next.

    The PCB Selection screen opens.

  11. Select the appropriate PCB, for example, PCB number 5 (which has a secondary index defined).
  12. 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).
  13. 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.
  14. Click Create Synonym.

    You should get a message indicating that the synonym was created successfully.

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


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.



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


Top of page

x
Creating Supplementary Metadata in the IMS XMI Server Environment

How to:

Reference:

Important: This topic is not relevant for the IMS DBCTL environment. However, the manual steps described here are required for XMI and, along with synonym generation, must be completed before you can retrieve data.

If you are working in the IMS XMI environment, in addition to creating the synonym Master File required to retrieve IMS data (as described in Managing IMS Metadata), you must also manually create a FOCPSB to describe a PSB to FOCUS. The topics in this section describe this process in detail.



x
Procedure: How to Define a FOCPSB

An IMS PSB consists of PCBs. Each PCB represents a view of an IMS database. A FOCPSB describes a PSB to FOCUS and associates a Master File with each PCB in the PSB. Optionally, the FOCPSB can also partition and concatenate PCBs.

In z/OS, PSBs are stored as members of a partitioned dataset. FOCPSBs are also stored as members of a partitioned data set. The member name for a FOCPSB must be identical to the member name of its corresponding PSB.

A FOCPSB is a comma-delimited, free-format file that consists of attributes (keyword=value pairs).

Rules for declarations are as follows:

The following sections summarize the syntax for each type of declaration and then present detailed explanations for each attribute.



x
Reference: FOCPSB Attributes

The required FOCPSB attributes describe the PSB to FOCUS and associate a Master File with each PCB you will access.

For a description of additional attributes for partitioning and concatenating PCBs, see Extended FOCPSB Attributes.

Header Record

Each FOCPSB starts with a header record. The syntax is

FOCPSB=EXTENDED [,PL1=YES] ,$

where:

FOCPSB=EXTENDED

Indicates that the FOCPSB is in comma-delimited format.

PL1=YES

Optionally, indicates that the PSB was created for a PL/I application program. You must include this attribute when the IMS PSB specifies LANG=PLI, otherwise, omit it.

Note that you must code the attribute exactly as shown, with the numeric digit 1 in PL1 and the value YES.

PCB Record

Each PCB in the PSB must have a corresponding record in the FOCPSB. The order of PCB records in the FOCPSB must correspond to the order of the PCBs in the PSB.

If any PCB in the PSB includes the attribute LIST=NO, do not include a corresponding record for that PCB in the FOCPSB.

The syntax for a PCB record in the FOCPSB is

PCBNAME=mfdname,PCBTYPE=DB [,LOWVALUE=val1] [,HIGHVALUE=val2],$
PCBNAME=, PCBTYPE={TERM|SKIP} [,LOWVALUE=val1] [,HIGHVALUE=val2],$

where:

PCBNAME=mfdname

Indicates the one- to eight-character name of the Master File for the corresponding database PCB (PCBTYPE=DB). To report from the PCB, specify TABLE FILE mfdname.

PCBNAME= Applies when no Master File is necessary (see TERM or SKIP for details).

TERM

Indicates that the corresponding PCB is an I/O PCB. (You need an I/O PCB to connect to IMS online through a teleprocessing monitor such as IMS/DC.) All I/O PCBs must be listed before any database PCB. Since no Master File is necessary, PCBNAME is blank.

Note that if the IMS PSB specifies CMPAT=YES, an I/O PCB is automatically generated at the top of the PSB for batch checkpointing; in this case, you must add an additional I/O PCB at the top of the FOCPSB.

SKIP

Indicates that you will not access the corresponding PCB. Since no Master File is necessary, PCBNAME is blank. Note that SKIP is a reserved word for the FOCPSB.

Important: Never use SKIP as a Master File name.

val1

Is used for partitioning. See Extended FOCPSB Attributes for a complete discussion.

val2

Is used for partitioning. See Extended FOCPSB Attributes for a complete discussion.

A PSB can have duplicate PCBs that provide identical views of an IMS database. Give each of these identical PCBs the same PCBNAME value in the FOCPSB. The XMI server environment uses this technique to give multiple users concurrent access to a database. You can also use duplicate PCBs to facilitate a recursive join.

The following is an IMS PSB named TSTPSB01. It has two database PCBs that access the PATDB01 database, the first through the primary index, and the second through a secondary index named IXNAME. For information on describing secondary indexes in the FOCPSB, see Secondary Index Considerations.

PCB TYPE=TP,MODIFY=YES,EXPRESS=YES
PCB TYPE=TP,EXPRESS=NO,MODIFY=YES,SAMETRM=YES
PCB TYPE=DB,DBDNAME=PATDB01,PROCOPT=GO,KEYLEN=9
SENSEG NAME=PATINFO,PARENT=0
PCB TYPE=DB,DBDNAME=PATDB01,PROCOPT=GO,KEYLEN=28,PROCSEQ=PATDBIX1
SENSEG NAME=PATINFO,PARENT=0
PSBGEN LANG=COBOL,PSBNAME=TSTPSB01,CMPAT=YES
END

The corresponding FOCPSB is shown:

FOCPSB=EXTENDED,$
PCBNAME= ,PCBTYPE=TERM,$
PCBNAME= ,PCBTYPE=TERM,$
PCBNAME= ,PCBTYPE=TERM,$
PCBNAME=PATINFO ,PCBTYPE=DB,$
PCBNAME=IXNAME ,PCBTYPE=DB,$


x
Reference: Extended FOCPSB Attributes

IMS limits the size of its databases. A site that needs a larger database may be able to create several smaller databases by partitioning the large database based on root key values.

Using extended FOCPSB attributes, you can describe a partition to FOCUS, describe how to concatenate the parts, and assign a name to the concatenated PCB. When you issue a report request, you can report from the concatenated PCB or from any of the individual partitions depending on the file name you reference in the request.



x
Syntax: How to Describe a Partition in the FOCPSB

A partition assigns each record to a specific database depending on its root key value. The first partition contains records with the lowest key values. The next partition contains records with higher key values, and so on. The last partition contains records with the highest key values.

Each partition is a separate IMS database and, therefore, has a separate PCB in the PSB. Partitioning is not supported for HDAM databases.

To describe the key range in each partition to FOCUS, add the LOWVALUE and HIGHVALUE attributes to the appropriate PCB records in the FOCPSB. The syntax is

PCBNAME=mfdname, PCBTYPE=DB, LOWVALUE= {val1|0} ,HIGHVALUE= {val2|FF},$

where:

mfdname

Is the name of the Master File for one partition of the large database. (Since the partition is a separate database with its own DBD, it needs its own PCB and Master File.)

val1

Is the lowest key value, in alphanumeric format, in the partition accessed with Master File mfdname. The default is 0.

val2

Is the highest key value, in alphanumeric format, in the partition accessed with Master File mfdname. The default is hexadecimal FF.

Note:

Concatenating Partitioned PCBs shows a sample FOCPSB with partitioning.



x
Syntax: How to Describe a Concatenated PCB in the FOCPSB

In a FOCPSB, you can concatenate individual PCBs by assigning a name to the concatenation and issuing a report request against it.

The PCBs that you concatenate do not have to be partitioned. That is, their FOCPSB records do not have to include the LOWVALUE and HIGHVALUE attributes. However, if they do include the partitioning information, the adapter can examine the report request and determine which PCBs satisfy the request. Without the partitioning information, the adapter must access every PCB that participates in the concatenation.

To concatenate PCBs, include a CONCATNAME record after all PCBNAME records in the FOCPSB. The syntax is

CONCATNAME=cname, USE=mfd1/mfd2/.../mfdi ,$

where:

cname

Indicates the concatenation name. You can issue a request from the concatenated PCBs using the syntax TABLE FILE cname.

The CONCATNAME record can span more than one line; however, you cannot split an individual Master File name between two lines.

mfd1/.../mfdi

Are Master File names from the individual PCBNAME records in the FOCPSB. The key fields for all PCBs you concatenate must be the same length and type. You can issue a request from an individual PCB by referencing its individual Master File name in the request (for example, TABLE FILE mfd1).



Example: Concatenating Partitioned PCBs in the FOCPSB

The following example illustrates how to concatenate partitioned PCBs:

FOCPSB=EXTENDED,$
PCBNAME= , PCBTYPE=TERM,$
PCBNAME= , PCBTYPE=TERM,$
PCBNAME= , PCBTYPE=TERM,$
PCBNAME=EMPDB01, PCBTYPE=DB, LOWVALUE=000000001, HIGHVALUE=000001667,$
PCBNAME=EMPDB02, PCBTYPE=DB, LOWVALUE=000001668, HIGHVALUE=000003334,$
PCBNAME=EMPDB03, PCBTYPE=DB, LOWVALUE=000003335, HIGHVALUE=000005000,$
CONCATNAME=EMPDBJ, USE=EMPDB01/EMPDB02/EMPDB03, $

Consider the following request (the key field is named SSNALPHA):

TABLE FILE EMPDBJ
.
.
.
IF SSNALPHA IS 000001775
.
.
.

The adapter satisfies the request using the EMPDB02 PCB only. If the WHERE clause had requested key values less than 000001775 (rather than equal to 000001775), the adapter would have used the EMPDB01 and EMPDB02 PCBs.

Note:



x
Reference: Secondary Index Considerations

The FOCPSB must also reflect the secondary indexes. The IMS PSB includes a PCB for the normal entry point into the database and an additional PCB for entry through each secondary index. Each PCB for a secondary index includes the parameter

PROCSEQ=indexdbdname

where:

indexdbdname

Comes from the LCHILD NAME parameter in the database DBD.

The FOCPSB must have a one-to-one correspondence with the PSB.

The FOCPSB entry that corresponds to the PCB for the normal entry point into the database must identify the name of the Master File. This example illustrates the PCB for the normal entry point into the PATDB01 database and its corresponding FOCPSB entry.

PCB:

PCB TYPE=DB,DBDNAME=PATDB01,PROCOPT=GO,KEYLEN=9
SENSEG NAME=PATINFO,PARENT=0

FOCPSB:

PCBNAME=PATINFO, PCBTYPE=DB,$

Any FOCPSB entry that corresponds to a secondary index PCB must identify the name of the index. This index name is the ALIAS of the GROUP record for the index in the Master File. It is also the value of the XDFLD NAME parameter in the DBD.

The next example illustrates a secondary index PCB and its corresponding FOCPSB entry for the PATDB01 database.

PCB:

PCB TYPE=DB,DBDNAME=PATDB01,PROCOPT=GO,KEYLEN=9,PROCSEQ=PATDBIX1
SENSEG NAME=PATINFO,PARENT=0

FOCPSB:

PCBNAME=IXNAME,PCBTYPE=DB,$

When the Interface generates DL/I calls for retrieval, it examines the record selection tests in the request to determine which PCB offers the most efficient access path to the required data.

Note: Since the PSB most likely includes only one PCB for each secondary index, each Master File that accesses the same index PCB must contain the same GROUP ALIAS value for the index.



x
Reference: FOCPSB Data Set

For z/OS, each FOCPSB is stored as a member of a partitioned data set (PDS). By convention, the FOCPSB data set is named

prefix.FOCPSB.DATA

where:

prefix

Is the high-level qualifier used at your site for your adapter production libraries.

The member name for a FOCPSB within its PDS must be identical to the member name of the corresponding IMS PSB within its PDS. (IMS PSB library names have the form prefix1.prefix2.PSBLIB or prefix1.prefix2.ACBLIB.)

In most environments, you select the PSB to use before you invoke the adapter, and you only allocate that FOCPSB member in your CLIST or JCL.



x
Reference: PSBs for the XMI Server

Since IMS uses the PCB to maintain an application program position in the database, concurrent users who are serviced by the same XMI job cannot share PCBs.

Each user application that accesses the server queries all the XMI jobs to which it is linked through the communication files, until it finds one that has a free PCB appropriate for reporting on the database. (The search for an available PCB is transparent to the user.) The PCB remains occupied for the duration of the retrieval portion of a request and is freed prior to the output portion of the request.

Thus, if ten users need concurrent access to the SALES database, the PSB must contain at least ten PCBs that correspond to the Master File for SALES. The eleventh user will receive a diagnostic message indicating that there is no free PCB available at the time. (In this case, the user should initiate another XMI server, as illustrated in previous sections.)

The ten SALES PCBs can reside in one of the following:

The IMS DBA must determine which configuration is best for the site. The tradeoff is between a single large PSB that ties up only one XMI region or several XMI regions, each running a non-duplicated and therefore smaller PSB.

Note: If the PSB contains multiple PCBs for the same database, in order to allow access through secondary indexes, you must duplicate the whole block of PCBs.


iWay Software