Application relationships
Option 9, Relationship, is used to create and maintain application relationships for use in the Extract/Load and Selection Criteria functions of File-AID for IMS/ISPF.
An application relationship is a File-AID for IMS/ISPF-defined relationship between one segment and the root segment of another database. The segment that contains the keys of the root segment is called the source segment in the source DBD, while the root segment is called the target segment in the target DBD.
Application Relationship Dataset Specification
The Application Relationship - Dataset Specification screen is displayed when you select Option 9 on the Primary Option Menu.
Application Relationship - Dataset Specification Screen
COMMAND ===>
ENV: TEST - IMS ENVIRONMENT
Enter dataset name of application relationship to be edited:
+ Appl Relationship dataset . . 'CW.FISAMP.APPLREL'
Member . . (Must be a DBD name in the DBDLIB or
Blank or pattern for member list)
-------------------------------------------------------------------------------
Enter DBD dataset name to which application relationship will be defined:
+ DBDLIB dataset 1 . . 'CW.FISAMP.DBDLIB'
Dataset 2 . .
Appl Relationship Dataset and Member
The application relationship data set name and member name that you enter must conform to the characteristics of a valid application relationship data set as described in Application Relationship Data set Concatenation. When specifying a member name, the member name must be a DBD name in the DBDLIB data set specified in the next section of the screen. This DBD name is the source DBD that the application relationship is based on.
DBDLIB Dataset 1 and Dataset 2
You can enter two DBDLIB data sets to serve as the concatenated source. If you enter two DBD load library names and their block sizes are different, you must enter the library with the larger block size on the first data set name line. When two DBD libraries are entered, File-AID for IMS/ISPF searches the first library before the second when looking for the DBD member. If you specify only one DBD library, it can be entered on either DBDLIB DATASET line.
Terminating the Screen
Do one of the following to terminate the Application Relationship Dataset Specification screen:
- Press ENTER to proceed to the Application Relationship Segment List Screen. (If errors are encountered during the validation process, Application Relationship Error Summary Screen displays.)
- Enter the END command to terminate editing and return to the Primary Option Menu.
Error Summary
If you are editing an application relationship that was previously created in Option 9, the application relationship data set is validated after you press ENTER from the Application Relationship Dataset Specification screen. If errors are encountered in the validation process, the Application Relationship Error Summary screen is displayed. If no errors are encountered, this screen is skipped.
Application Relationship Error Summary Screen
COMMAND ===>
001 INVALID OR MISSING RECORD - SKIPPED TO NEXT VALID SOURCE SEGMENT
005 THE NUMBER OF KEYS FOR TGT (PCUST ) DOES NOT MATCH THE EXPECTED TOTAL
004 THE NUMBER OF TARGETS FOR SEG (ORDR040 ) DOES NOT MATCH THE EXPECTED TOTAL
Enter END command to terminate Application Relationship Edit without saving
Enter FORWARD command to proceed to Edit Application Relationships
Errors can occur in the validation process for either of the following reasons:
- Incorrect DBD libraries were entered on the Application Relationship Dataset Specification screen.
- The application relationship was modified outside Option 9 (for example, in ISPF/PDF Option 2).
There are six different errors that can occur in the validation process. The text and a description of each message follows:
Application Relationship - Validation Errors
Error | Description |
|---|---|
001 | INVALID OR MISSING RECORD - SKIPPED TO NEXT VALID SOURCE This error occurs when File-AID for IMS encounters an invalid record or determines that a record is missing from the application relationship data set. This can occur only when the application relationship was modified outside Option 9. File-AID for IMSattempts to skip to the next valid application relationship record. |
002 | SEG (seg-name) NOT FOUND IN DBD (DBD-name) - SKIPPED TO NEXT VALID SEG This error occurs when the segment name was not found in the DBD defined in the specified DBD library. File-AID for IMS discards the application relationship for the segment identified by seg-name in the message. |
003 | THE NUMBER OF SEGS IN THE APPL REL MBR DOES NOT MATCH THE EXPECTED TOTAL This error occurs when File-AID for IMS encounters a mismatch between the number of source segments defined in the application relationship and the number of segments in the DBD defined in the DBD library. This can occur when an incorrect DBD library was specified or when the application relationship was modified outside Option 9. |
004 | THE NUMBER OF TARGETS FOR SEG (seg-name) DOES NOT MATCH THE EXPECTED TOTAL This error occurs when File-AID for IMS encounters a mismatch between the number of target DBDs for the seg-name actually found in the application relationship and the expected count contained in the application relationship. This can occur only when the application relationship was modified outside Option 9. |
005 | THE NUMBER OF KEYS FOR TGT (DBD-name) DOES NOT MATCH THE EXPECTED TOTAL This error occurs when File-AID for IMS encounters a mismatch between the actual number of keys defined for the DBD-name target DBD in the application relationship and the expected count contained in the application relationship. This can occur only when the application relationship was modified outside Option 9. |
006 | THE NUMBER OF TGTS IN THE APPL REL MBR DOES NOT MATCH THE EXPECTED TOTAL This error occurs when File-AID for IMS encounters a mismatch between the actual number of target DBDs defined in the application relationship and the expected count contained in the application relationship. This can occur only when the application relationship was modified outside Option 9. |
Terminating the Screen
Do one of the following to terminate the Application Relationship Error Summary screen:
- Press ENTER to proceed with editing the application relationship despite the errors.
- Enter the END command to terminate editing and return to the Application Relationship - Dataset Specification screen.
Application Relationship Segment List
If there are no errors in the application relationship validation process or if there are errors and you pressed Enter on the Application Relationship Error Summary screen, the Application Relationship Segment List screen is displayed. This screen is used to select and delete application relationships for a source segment in the primary DBD.
Application Relationship Segment List Screen
COMMAND ===> SCROLL ===> CSR
Description ===> A/R ORDER LINE - PART ROOT
Line Application Source Segment
Cmd Relation -----Level----- Segment Length
_ 1 DBD-PORDR ORDR010 167
_ * 2 ORDR020 50: 200
_ 3 ORDR030 45
_ 2 ORDR040 40
_ 2 ORDR050 47 LCHILD SEG
*** END OF SEGMENT LIST ***
Enter "S" to specify source fields that construct target root key
Enter "D" to delete target DBD(s) from application relationship
Description
Enter up to a 30-character description of the application relationship. The description is displayed whenever an Application Relationship Member List screen is used.
Line Cmd
Enter one of the following:
S | Selects a source segment type to create or maintain an application relationship. Only one S line command can be entered per interaction. When you select a source segment type, the Target DBD Specification Screen is displayed. |
D | Deletes all application relationships created for the source segment. Any number of D line commands can be entered simultaneously with or without an occurrence of a select line command. |
Application Relation
A protected, non-modifiable field that displays an asterisk when an application relationship exists for the source segment.
Level
The segment type’s hierarchical level number in the database (for the root segment type, the primary DBD name is displayed next to the level number).
Source Segment
The name of the source segment as specified in the DBD.
Segment Length
The segment length as specified in the DBD. For variable length segment types, both the minimum and maximum defined lengths are shown.
For additional information, File-AID for IMS identifies a logical child segment with "LCHILD SEG" displayed at the end of the segment line.
Terminating the Screen
Do one of the following to terminate the Application Relationship Segment List screen:
- Enter the END or RETURN command to terminate editing of the application relationship. A save operation is performed.
- Enter the CANCEL command to terminate editing of the application relationship. A save operation is not performed.
Primary Commands
See Primary Commands for an explanation of the primary commands available.
Target DBD Specification
When you enter an S line command from the Application Relationship Segment List screen, the Target DBD Specification screen is displayed. This screen is used to specify the target DBDs and fields in the source segment type that construct the target root keys.
Target DBD Specification Screen
COMMAND ===> SCROLL ===> 7
Source data base name: PORDR Segment name: ORDR020
Source segment exit name ===> (Optional: To manipulate target key data)
----------------------- Source fields --------------------
Line Start Start Start
Cmd Target DBD Position 1 Length Position 2 Length Position 3 Length
__ PPART___ 14___ 6__ _____ ___ _____ ___
******************************* Bottom of data ********************************
Source segment exit name
Optionally, specify your own source segment exit name, called during File-AID for IMS’ extract process, to manipulate the target key data. For more information, see Source Segment Exit Module.
Line Cmd
Enter a D line command to delete a target DBD from the application relationship. Enter an I line command to insert a target DBD. Enter an R line command to repeat a target DBD.
Target DBD
Enter the target DBD that contains the sources that construct the root keys.
Start Position and Length
Starting in the Start Pos 1 field, specify up to three source fields and the order in which these source fields construct the root target key. File-AID for IMS uses the start position and length you specified to identify each source field.
Source Segment Exit Module
The source segment exit name you specify identifies an optional user-written module called during the extract process. The source segment exit module is called after the target key is constructed from the Source Segment fields. This exit module can manipulate the target key and include up to 29 other target root keys to be extracted. The Application Relationship exit can be used for the following reasons:
- To convert a packed source field into a zoned target key.
- To add a constant prefix or suffix to the constructed target key.
- To add up to 29 more target root keys to extract based on one source segment.
- To convert an encoded source key to a fully decoded target root key.
- To change the target key based on several fields in the source segment.
- To decide whether to chase this source’s relationship based on data in this source segment.
Your source segment exit module can be written in COBOL, PL/I, or Assembler. The exit module can be compiled and linked into the same load library where File-AID for IMS resides. For an example of the exit module’s compilation and linkage, see the person responsible for File-AID for IMS at your installation. A sample application relationship exit module and JCL are included on the File-AID for IMS installation tape. The following call sequence and parameters are used to interface with the source segment exit module:
CALL SEQUENCE
TARGET-ROOT-KEYS-TABLE,
SOURCE-SEGMENT-DATA,
CONCATENATED-KEY,
AR-EXIT-WORK-AREA)
SOURCE-SEGMENT-EXIT-PARMS LAYOUT
03 INPUT-PARMS.
05 SOURCE-DBD-NAME PIC X (8).
05 SOURCE-SEGMENT-NAME PIC X (8).
05 SOURCE-SEGMENT-LENGTH PIC S9(4) COMP.
05 TARGET-DBD-NAME PIC X (8).
05 TARGET-SEGMENT-NAME PIC X (8).
05 CONSTRUCTED-TARGET-KEY-LENGTH PIC S9(4) COMP.
(see below)
03 INPUT-OUTPUT-PARMS.
05 TARGET-NO-TO-EXTRACT PIC S9(4) COMP.
(see below)
03 OUTPUT-PARMS.
05 EXTRACT-ROOT-IND PIC X.
(see below)
05 EXTRACT-CHANGED-SOURCE-SEG PIC X.
(see below)
CONSTRUCTED-TARGET-KEY-LENGTH is the sum of the lengths of the source fields that construct the target root key.
TARGET-NO-TO-EXTRACT is the number of target root keys that reside in the TARGET-ROOT-KEYS-TABLE. When calling the exit module, File-AID for IMS places the constructed target root key in the first entry of the TARGET-ROOT-KEYS-TABLE and sets this value to one. Upon return from the exit module, File-AID for IMS uses this value, (0-30), as the number of target keys in the TARGET-ROOT-KEYS-TABLE. If the value is zero, File-AID for IMS assumes there are no target root segments to be extracted.
EXTRACT-ROOT-IND (Y/N) indicates whether the application relationship for this source segment is to be extracted.
The EXTRACT-CHANGED-SOURCE-SEG (Y/N) indicates whether the extracted segment should be taken from the SOURCE-SEGMENT-DATA area. If N, the extracted segment is taken from the database. If Y, the segment is taken from the SOURCE-SEGMENT-DATA area instead. The default is N. This action allows the exit to modify the extracted segment. The area is refreshed from the database on each invocation of the exit. The segment is written to the extract data set following the last invocation of the exit module. Therefore, if the exit is invoked multiple times for the same segment, the exit should set EXTRACT-CHANGED-SOURCE-SEG to Y and make all changes to the source segment only on the last invocation.
TARGET-ROOT-KEYS-TABLE LAYOUT
This layout contains up to ten target root keys. When the exit module is called, the first entry contains the constructed target root key based on the application relationship. The exit module can manipulate this key and add up to 29 more target root keys in this table to be extracted. The TARGET-NO-TO-EXTRACT contains the number of target root keys in the TARGET-ROOT-KEYS-TABLE.
03 TARGET-ROOT-KEY OCCURS 30 PIC X(255).
SOURCE-SEGMENT-DATA LAYOUT
This layout is a 30720-byte field that contains the source segment being extracted. The exit module can manipulate the source segment in this area. Changes made here do not affect the source segment in the database. See the EXTRACT-CHANGED-SOURCE-SEG field in the SOURCE-SEG-EXIT-PARMS to find where the segment written to the extract data set is obtained.
CONCATENATED-KEY LAYOUT
This layout is a 3825-byte area that contains the fully concatenated key of the source segment. The length of 3825-bytes allows for the maximum individual key length of 255 bytes multiplied by the maximum number of hierarchical database levels of 15. The layout of the concatenated key in the CONCATENATED-KEY field is identical to its layout in the key feedback area of a standard IMS PCB.
AR-EXIT-WORK-AREA LAYOUT
This layout is a 4096-byte work area initialized to binary zeros. This area is unchanged by File-AID for IMS/ISPF during the entire extract and can be used to retain information across multiple calls to the application relationship exit.
Example of Creating an Application Relationship
To create another application relationship to the PORDR database, select the appropriate source segment type on the Application Relationship Segment List screen. In the following figure, the ORDR040 source segment type is selected to define an application relationship.
Creating an Application Relationship - Selecting a Segment Type
COMMAND ===> SCROLL ===> CSR
Description ===> A/R ORDER LINE - PART ROOT
Line Application Source Segment
Cmd Relation -----Level----- Segment Length
_ 1 DBD-PORDR ORDR010 167
_ * 2 ORDR020 50: 200
_ 3 ORDR030 45
S 2 ORDR040 40
_ 2 ORDR050 47 LCHILD SEG
*** END OF SEGMENT LIST ***
Enter "S" to specify source fields that construct target root key
Enter "D" to delete target DBD(s) from application relationship
When the ORDR040 segment type is selected, the Target DBD Specification screen is displayed. This screen is used to specify an optional source segment exit module, the target DBDs, and up to three source fields to construct the target’s root key.
In the following table, PMATL is the target DBD with a key constructed from two source fields in ORDR040. The first source field starts in position 24 for a length of one. The second source field starts in position 11 for a length of five. Together, the two source fields construct a six-byte target root key to be used to extract PMATL’s root.
Creating an Application Relationship - Specify Target Root Keys
COMMAND ===> SCROLL ===> 7
Source data base name: PORDR Segment name: ORDR040
Source segment exit name ===> (Optional: To manipulate target key data)
----------------------- Source fields --------------------
Line Start Start Start
Cmd Target DBD Position 1 Length Position 2 Length Position 3 Length
__ PMATL___ 24___ 1__ 11___ 5__ _____ ___
******************************* Bottom of data ********************************
Terminating the Screen
Do one of the following to terminate the Target DBD Specification screen:
- Enter the END or RETURN command to terminate editing of the application relationship. A save operation is performed.
- Enter the CANCEL command to terminate editing of the application relationship. A save operation is not performed.