Generating for OS/400

The following topics provide information needed to generate a native OS/400 file:

• Principles

• Defining an OS/400 File Object

• Calling the Generate Function

• Changing an OS/400 Database File

Principles

This section describes the principles of how the Predict file and field view is mapped on OS/400 database files. It also demonstrates the components that are used to create and manage a physical OS/400 file. The following topics are covered:

• Components

• Mapping Rules

Components

The diagram below shows the components in the Predict and AFS File-Mapping environment that enable you to create a physical OS/400 file from a Predict file object.

The following abbreviations are used on the diagram above:

• PRD: Product short code for Predict. In this document, PRD also denotes the Natural terminology of file field-level structures.

• AFS: The Software AG term AFS is the product short code for the OS/400 Shell Environment that includes all database- and file-mapping programs.

• FDT: The Software AG term "Field Description Table" describes the field-mapping information that is stored in the data-mapping library AFSvrsDTA. vrs denotes version, release and SM level.

• DDS: The IBM term "Data Description Specification" is a source file that is used to build a new database file.

• FFD: The IBM term "File Field Description" describes the field structure of an existing OS/400 database file.

When Natural accesses an OS/400 database file, it uses the FDT information to map its data view to the OS/400 data records. For details, see Using the AFS File-Mapping Environment in the Natural for OS/400 Administration document.

Mapping Rules

This section describes the rules of how Predict field types and field formats are mapped to the corresponding OS/400 file field structures.

In principle, Predict assumes that the generated file would be an Adabas file. Because an OS/400 FFD cannot provide all elements used by Adabas, this section also lists the limitations that are caused by differences in the database management systems.

Field Type Mapping

The following table lists how Predict field types (column Ty) are mapped to the corresponding FDT (column T) and OS/400 DDS field attributes:

Field Attribute Limitations

Due to the differences between the Adabas data view and and the OS/400 file field model, you have to consider the following limitations:

• Descriptors are not allowed for fields within multiple occurrence structures, such as MUs and PEs.

• Redefinitions in the Predict file document are ignored during the generation function.

• Under OS/400 it is efficient if you specify the maximum number of occurrences for field arrays (mupltiple fields and periodic groups). If a Predict array object does not contain a value for occurrence (Column Occ), the generation function creates 199 MU or PE elements (the maximum).

• Multi-occurrence structures are not allowed for parent fields of Sub- and Superfields.

• Parent fields with format P are invalid in Super- and Subfields.

• Parent fields with format N are invalid in Subfields.

• Predict suppression options are not fully covered under OS/400. See the details:

  PRD Suppression Option		FDT Option S	Remarks
  N	Null supression	N
  F	Fixed	blank
  blank	Normal supression	blank
  U	Null allowed		Not allowed in FDT. Generation stopped with Error message displayed.
  R	Not Null		Not allowed in FDT. Generation stopped with Error message displayed.

Field Format Mapping

The following table lists various Predict field formats and how they are mapped to the corresponding FDT and OS/400 DDS field formats:

of Packed Format notations:

Defining an OS/400 File Object

To create an OS/400 file object

1. Invoke Predict and add a new database object or select an existing one.

   The database object must comply with the following criteria:

   • The Predict database object must be of type A (Adabas).

   • The database number must exist in the AFS Database-Mapping environment with type "blank" (not "ADA" !!).

   • The first 10 characters of the Abstract field must denote the physical library name of the database. It must exist in the AFS File-Mapping environment. The name will be rejected during the generation function if it exceeds 10 characters or if it contains characters that are invalid within an OS/400 library name.

   The following screen excerpt displays a sample database-object definition:

   13:13:29 ***** P R E D I C T ***** 2007-05-31 - Display Database - Database ID ........ NAT-315-DB Type ............... Adabas, Local Added 2002-07-28 at 13:58 by SAG Physical DBnr ...... 1 Modified 2002-07-29 at 13:31 by SAG ------------------------------------------------------------------------------- Adabas attributes Nattural file numbers Maximal files ........ System file (FNAT) ... Checkpoint file ...... NAT-Security (FSEC) .. Adabas security ...... Predict (FDIC) ....... Size of RABN ......... 0 Distr. transaction ... N No Vista access only .... N Abstract NAT315DB *** End of report *** Command ===> Scroll ==> CSR Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Quit RFind Flip - + Left Right

   The example shows the specifications of the sample database NAT315DB that is delivered with Natural for OS/400 Version 3.1.5.

2. Add a new file object that must comply with the following criteria:

   • The first 10 characters of the Abstract field must denote the physical name of the target file. The name will be rejected during the generation function if it exceeds 10 characters or if it contains characters that are invalid within an OS/400 file name.

   The following screen excerpt displays a sample file-object definition:

   13:01:06 ***** P R E D I C T ***** 2007-05-31 - Display File - File ID ............ CUSTOMER Type ............... Adabas file File number ........ 19 Added 2002-07-29 at 13:00 by SAG Modified Fields modified 2002-07-29 at 13:01 by SAG ------------------------------------------------------------------------------- File attributes Sequence field .......... Adabas SQL usage ........ N Abstract CUST Description ========================================= File additional description Command ===> Scroll ==> CSR Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Quit RFind Flip - + Left Right

   where 19 is the Predict file-object number, CUSTOMER the Predict file ID and CUST the name of the physical OS/400 target file.

3. Add fields to your file object. The following screen excerpt displays sample elements that are also used later in this document:

   >> + Fi: CUSTOMER L: 1 S: 9 Ty L Field ID F Cs Length Occ D U DB S All *- - -------------------------------- *- * -------- ----- * * -- * 1 CUST-NAME A 20.0 D AA 1 CUST-NO N 8.0 D AB GR 1 ADDRESS AC 2 CITY A 20.0 D AD 2 STREET A 20.0 AE 1 SEX A 1.0 AF 1 DEBIT P 6.2 AG MC 1 PRODUCTS A 10.0 6 AH SB 1 CITY-SHORT A 3.0 S1

4. Link the new file object to the Adabas database object defined in Step 1:

   • You can use the Predict command LINK DATABASE FI database ID> to invoke the child list of your database.

   • Add the file object to the list. In the column PFnr specify the file number of the physical target file.

   • The physical file number must not yet exist in the file list of the target database ID. If you want to upgrade an existing OS/400 file, see the next topic.

   The following screen excerpt displays a child list reflecting the previous database and file sample:

   >> + DA: NAT-315-DB L: 1 S: 11 All Contains FI PFnr T Fnr DDM Impl Other -------------------------------- ----- -- ----- --- ---- ----- CUSTOMER 319 A 19

   Note:
   The file ID and the physical file name are different in the example above. However, they can be identical. This applies accordingly to the object-file number and the physical file number and to the database ID and the physical library name.

Calling the Generate Function

The Generate OS/400 File Definitions screen is displayed with function code G and object code O4 in a Predict main menu or with the command GENERATE OS4.

18:47:44             *****  P R E D I C T  *****             2007-05-31
Plan   0            - Generate OS/400 File Definitions - 
 
File ID ................ CUSTOMER
Phys. File number....... 
Contained in DA ........ 
Phys. Database number .. 



List generated code .... Y      (Y,N)

Truncation ............* R                       Validate ........... *


Command ===>
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
      Help  Next  Stop  Last  LnkEl  -     -    Impl  AdmFi SelFi Prof  Main

The screen's input fields are described below:

The excerpt below shows sample file field details if parameter List generated code was set to Y:

File ID .. CUSTOMER                                                           
                                                                              
*     FILENAME       = CUST
*     FILENUMBER     = 319
*     DATABASENAME   = NAT315DB 
*     DATABASENUMBER = 1
        T Lv DB O Name       From  F Len   S D U M-Len Occ Remarks
        - -- -- - ---------- ----- - ----- - - - ----- --- -------------
      *   01 AA O CUSTNAME       1 A    20   D
      *   01 AB O CUSTNO        21 N     8   D
      * G 01 AC   ADDRESS
      *   02 AD O CITY          29 A    20   D
      *   02 AE O STREET        49 A    20
      *   01 AF O SEX           69 A     1
      *   01 AG O DEBIT         70 P     5                  8 digits
      * M 01 AH O PRODUCTS      75 A    10          62   6  
        - -- -- - ---------- ----- - ----- - - - ----- --- -------------
      * S 01 S1   CITY             A                 1   3              
**

                R CUST 
                  CUSTNAME   00020A  B
                  CUSTNO     00008S  B
                  CITY       00020A  B
                  STREET     00020A  B
                  SEX        00001A  B 
                  DEBIT      00008P02B
                  PRODUCTS   00062H  B

When you page (by pressing ENTER) through the generated transfer list, all fields that caused problems are followed by a message line, which reports a warning, an error or changes that were performed by the system. See the section Field Check Messages for possible messages. If errors occur, the generation process will be interrupted abnormally.

If the generation process was performed successfully, you will be requested to execute the file creation. A request similar to the one below appears:

13:26:09             *****  P R E D I C T  *****             2007-05-31
                    - Generate OS/400 File Definitions - 
  
File ID ...... CUSTOMER                                         PFnr ...   319 
Database ID .. NAT-315-DB                                       PDBnr ..     1 
 
 
               +-------------------------------------------------+ 
               !        Do you want to execute: Y (Y/N)          ! 
               +-------------------------------------------------+ 




Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
      Help  Next  Stop  Last  LnkEl  -     -    Impl  AdmFi SelFi Prof  Main

The system will confirm the successful file creation. The following screen excerpt reflects the sample used above:

MORE 
Page      2                                                 02-07-31  13:19:04 

DIC1800 SUMMARY:     9 FIELD(S) PROCESSED.

The current step also inserted the new file's FDT into the File-Mapping data of the AFS Database Environment. Before Natural can access the new file, you must perform the steps described in the following paragraph.

To edit and catalog the generated OS/400 FDT information

1. Invoke the File Entries and Associations menu from the OS/400 Database Shell main menu by selecting Function Code F and the database ID that you specified as Physical DBnr in Predict. The file you just created should appear in the file list of your database.

2. Issue the command EDT or press PF6 (EDT) to edit the new file entry. The field list appears. First, press PF4 (CHK) to allow the check program to complete some information, e.g. adding field lengths to group definitions.

   Continuing with the example above, you should get the following field description table (FDT):

   13:07:37 SOFTWARE AG - OS/400 Database Shell 7/31/02 DB-Nbr 1 NAT315DB File-Nbr 319 CUST Status UNCATALOGED I T L DB O Name OS400 From F Leng S D U M-Len Occ Remarks __ _ __ __ _ __________ _____ _ _____ _ _ _ _____ ___ ____________________ 1 AA O CUSTNAME 1 A 20 D 1 AB O CUSTNO 21 N 8 D G 1 AC ADDRESS 29 40 2 AD O CITY 29 A 20 D 2 AE O STREET 49 A 20 1 AF O SX 69 A 1 1 AG O DEBIT 70 P 5 M 1 AH O PRODUCTS 75 B 10 62 6 S 1 S1 CITY 29 A 3 Command ________________________________________ Enter PF1 PF2 PF3 PF4 PF5 PF6 PF7 PF8 PF9 PF10 PF11 PF12 EXIT CHK SAV CAT UNC

   The FDT is still in UNCATALOGED state. You could now edit/modify field details, like adding descriptors. However, the physical layout of the fields cannot be changed any more. It is good practice to apply all changes also in the corresponding Predict file document to guarantee consistency for later file generations.

3. Issue the command CAT or press PF6 (CAT) to catalog the file information. During this step, also the logical files (descriptors) will be created in the file's library.

   If the cataloging has been ended successfully, the file is ready to be accessed by Natural.

Field Check Messages

Changing an OS/400 Database File

To change the layout of an OS/400 database file

1. From the OS/400 Database-Shell menu, invoke the Field Entries and Descriptions menu of your file to be changed. Uncatalog the file and remove it from the file list. The file is now no longer available for the mapping interface. In addition, all logical files (descriptors) in the file's library have disappeared.

2. Rename the physical OS/400 file to a save name.

3. Invoke Predict and apply your modification to the relevant file object. For example, add fields, delete fields or enhance field lengths.

   Warning: You must not change field names, otherwise the *MAP option of the CPYF copy file command will not find the counter field in the saved file. See the FMTOPT option below.

4. Generate a new OS/400 file from the Predict file object that you modified in the previous step. During this run, the corresponding file and field definitions will be added again to the AFS File-Mapping information. See the section Calling the Generate Function on how to perform the Generate function for OS/400 files.

5. From the OS/400 Database-Shell menu, invoke the Entries and Associations menu to edit, check and catalog the new file's FDT. The logical files (descriptors) will then be available again in the file's library.

6. Copy the data contents on a field-to-field basis from the saved file (see Step 2) to the new empty file using the OS/400 command CPYF. The Copy File run will consider the changed layout if you specify the option FMTOPT(*MAP). For example, new fields will be padded according the characteristic of the new file's field description. Use additionally the option FMTOPT(*DROP) to drop those fields in the save-file record format for which there are no fields of the same name in the new-file record format. For more details on the FMTOPT parameter, refer to IBM's File Management documentation (scan for the section database-to-database copies).

7. According to the changes in the file field layout, you may have to adjust the corresponding DDM definition, e.g. by generating the new DDM from the Predict file object.

8. The OS/400 file is now ready to be accessed by Natural.