Generating for OS/400

#### Search Results

Search

# 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 product short code for the OS/400 Shell Environment that includes all database- and file-mapping programs.

- FDT: "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:

PRD Field Type | Description | FDT Type in AFS | DDS Source Lines will be: | Remarks
--- | --- | --- | --- | ---
blank | plain field | blank | generated, but not as part of a PE array |
GR | Group | G | not generated |
MU, MC | Multiple value field | M | generated | Overall field length in DDS/FFD = (field length * Occ) + 2
PE, PC | Periodic group | P | generated | Overall field length in DDS/FFD = (sum of all field lengths * Occ) + 2
SB | Subfield | S | not generated | The FDT-field name matches the parent field name. The FDT-field offset is derived from the relative start- and end-character offset within the PRD field.
SP | Superfield |
T | indicates the Superfield name
U | indicates the Superfield elements
| not generated | The FDT offsets of the Superfield elements are derived from the relative start- and end-character offsets of the parent fields.

#### 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:

PRD Format | Description | FDT Format | DDS Format | Max. length | Remarks
--- | --- | --- | --- | --- | ---
A | Alphanumeric / Character | A | A | 253 bytes |
AV | Varchar | - | - |  | not processed
B | Binary | B | H | 126 digits |
I | Integer |  |  |  | Treated like Format B
N, NS, U, US | Numeric unpacked | N | S | 31 digits |
P, PS (in digits) | Packed numeric | P (in bytes) | P (in digits) | 16 digits | See the table below for examples.
D | Date | P4 (4 bytes) | P6 (6 digits) |  | Change message displayed
T | Time | P7 (7 bytes) | P12 (12 digits) |  | Change message displayed
F | Floating point | - | - |  | not processed
L | Logical | - | - |  | not processed

of Packed Format notations:

Format in | Units are in | Ex. 1 | Ex. 2 | Ex. 3 | Ex. 4 | Ex. 5 | Ex. 6
--- | --- | --- | --- | --- | --- | --- | ---
PRD (Natural) | digits | 5.0 | 6.0 | 5.2 | 6.2 | 7.2 | 8.2
DDS (OS/400 source) | digits | 5P | 6P | 7P02 | 8P02 | 9P02 | 10P02
FDT (AFS file-mapping) | bytes | 3 | 4 | 4 | 5 | 5 | 6
FFD (OS/400 buffer length in physical record) | bytes | 3 | 4 | 4 | 5 | 5 | 6

## 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:

Input Field | Explanation / Options
--- | ---
File ID | The file object to be generated from. This is the only mandatory input field.
Phys. File number | This file number must not yet be available in the AFS Database-Mapping file list of the target DBID. The physical file name (specified in the first 10 characters of the file's Abstract field) must not yet exist in the OS/400 database library.
Contained in DA | The Predict database name. Note that the database library name will be extracted from the first 10 characters of the database's Abstract field.
Phys. Database number | The DBID of the target database library. Note that this DBID must be available in the AFS Database-Mapping Interface and the library (specified in the first 10 characters of the database's Abstract field) must exist physically.
List generated code |
The physical OS/400 file name, file number, database name and database number are always displayed. Depending on this parameter, additionally the following will be displayed:
if Y (yes) | the generated code.
if N (no) | only messages and the affected fields.
Truncation |
This parameter describes how long field names should be truncated to 10 characters. The following options are possible:
R (right) | Trailing characters will be truncated. This is the default.
L (left) | Leading characters will be truncated.
M (middle) | Middle characters will be truncated.
Validate |
This parameter indicates how characters that are invalid within OS/400 field names should be handled:
Blank | Field names stay unchanged. If invalid characters are identified, error messages will be displayed for the relevant fields.
A replacement character | This character will replace all invalid characters that are found within field names. Valid replacement characters are the letters A through Z, the digits 0 through 9, and the special characters $, #, @ and underscore(_).
* | Invalid characters within field names will be truncated. This is the default.

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

Type | Message | Explanation / Action
--- | --- | ---
Error | END-VALUE NOT WITHIN SOURCE FIELD | The end value of a Superfield is not located within a source field.
SOURCE FIELD HAS INVALID FORMAT | Parent fields with Format P are invalid in Super- and Subfields. Parent fields with Format N are invalid in Subfields.
INVALID SOURCE FIELD | Multi-occurrence structures are not allowed for parent fields of Sub- and Superfields.
RECORD IS LONGER THAN 32K | OS/400 only supports file records shorter than 32K.
INVALID FIELD NAME | The field name contains invalid characters and the Validate parameter is blank.
FIELD IN USERVIEW LONGER THAN IN MASTERFILE | A field in a userview cannot be longer than the corresponding field in the master file.
INVALID SUPPRESSION OPTION | The suppression options U and R are not allowed for OS/400 files.
DUPLICATE FIELD-NAME GENERATED | OS/400 database-field names must be unique.
Warning | NUMBER OF OCCURRENCES MISSING | On OS/400, the number of occurrences has been set to the default value of 199.
Change | FORMAT NOT SUPPORTED | The specified field format is not supported on OS/400. It was changed to the format displayed.
DESCRIPTOR OPTION DELETED | An invalid descriptor option was deleted. Multiple fields and periodic groups mapped to an OS/400 file field cannot contain descriptors.
FORMAT ''D''/''T'' CHANGED TO ''P'' | The OS/400 field description table does not support Date or Time. The format was changed to packed.
UNIQUE OPTION DELETED | The unique option was deleted because the field has no descriptor.
MULTI BYTE CHARACTER SET SUPPRESSED | Mixed data character set is not supported.
FIELD NAME TRUNCATED | The field name was shortened to 10 characters corresponding to the truncation rules specified.
FIELD NAME SET TO FILLER | The field name was set to FILLERn because it consisted of invalid characters only.

## Changing an OS/400 Database File

Important
If you plan to change the physical layout of an existing OS/400 database file, your starting point must always be the Predict file definition.

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.

### On this page

- Principles
- Defining an OS/400 File Object
- Calling the Generate Function
- Changing an OS/400 Database File