IBM Mainframe Forum

  Text        USR1051T Library SYSEXT         

 Interface to various PRD data                     PRD
 .
 Name of Interface ..... USR1051N    /*  Cataloged Interface
 Name of Program ....... USR1051P    /*  Example for the Programmer
 .
 Function .............. Interface Program for PRD.
                         This routine gives access on various parts of
                         PRD data. Possible accesses are depending on the
                         PRD object to processed (listed below).
 .
 Keywords .............. FDIC, DESCR, FIELD-LIST, SELECT, PRD
 .
 Extends ...............
              PRD 4.2.1. Layout of object type 'EL' has been changed
 .
 Parameter Layout:
 -----------------
 see PDA  USR1051A
 .
 How to Use the Application Interface:
 -------------------------------------
 The interface 'USR1051N' should be copied to the library 'SYSTEM'
 or the steplib library respectively, or to any application.
 .
 The parameters listed above must be defined via DEFINE DATA in
 structured mode or via RESET in reporting mode.
 .
    Access FDIC of PRD 4.2:
 .
    INFO-TYPE   Possible Acceses      Proccessed Object
    ---------   ------------------    -----------------------------
       'E'      R, S, W, D, C         Description
       'O'         S        C         Objects (UDE or predefined)
       'O'      R, S        C         PRD objects of type 'EL'
 .
 .
 .
 .
 Description of the parameters:
 ------------------------------
 .
    Input ...... USER
                        Natural-USER. *USER unsuitable in batch in
                        NON-NSC environments, because *USER is Jobname.
 .
    Input ...... DBID, FNR, PASSWORD, CIPHERCODE
                        Definition of the data base environment. If
                        no values are entered, the current FDIC
                        definition is used.
                        This FDIC switching is only active while
                        interface is running.
 .
    Input ...... INFO-TYPE
                        Predict information type.
                        'E' := Ext.Description
                        'O' := Object (UDE or predefined PRD Object)
 .
    Input ...... OBJECT-TYPE
                        Predict object type.
 .
    In/Output .. OBJECT-NAME (A32)
                        Name of the Predict object.
                        Name will be translated to upper case, when
                        switch OBJ-UP of the FDIC is set to 'U'.
 .
    Input ...... OTHER-KEY
                 - OBJECT-NAME-2            redefines OTHER-KEY
                      If OBJECT-TYPE = 'EL' PRD Filename
                      If INFO-TYPE   = 'D'  PRD Filename
                   OBJECT-NAME-3
                      If INFO-TYPE   = 'D'  PRD Fieldname
 .
                 - IMPL-POINTER             redefines OTHER-KEY
                      If OBJECT-TYPE = 'PR' or ='SY' this field is
                      Usable instead of the OBJECT-NAME
                      MEM-DBID
                      MEM-FNR
                      MEM-LIB   /* Name of a Natural library
                      MEM-NAME  /* Name of the Natural source
 .
    Input ...... OPT-ACCESS
                        Access type. Possible values are:
                        'S' - Select all objects fitting to the key.
                        'R' - Read data from FDIC.
                        'W' - Write data to FDIC.
                              The existing description will be deleted
                              with the first 'W'rite access.
                        'D' - Delete INFO-TYPE. The access 'C'lose is
                              implicitly performed.
                        'C' - Close processing.
                              After any modifying access 'C'lose-Call is
                              necessary, because the maintenance log and
                              other flags have to be set.
                              After retrieval accesses the 'C'lose-Call
                              is not neccessary. Excepted in a NAT/C
                              environment to force the end of processing.
                              In a data base environment a BT will be
                              issued.
                              Note: A 'C'lose processing must be done
                              between 'R'ead and 'W'rite access
                              to prevent DIC1609 / DIC1068 when 'R'ead
                              and 'W'rite is done in the same program.
 .
    Input ...... OPT-ET
                        Option for transaction handling.
                        ' ' will be handled like 'N'.
                        When OPT-ACCESS = 'S'
                           No ET or BT at all.
                        When OPT-ACCESS = 'R'
                           'Y' - Read with hold option.
                           'N' - Read without hold option.
                        other cases
                           'Y' - ET performed by the subprogram during
                                 the close call. If an error occurrs,
                                 a BT will be issued by the subprogram.
                           'N' - No ET or BT will be performed by
                                 the subprogram
 .
    Input ...... OPT-REPLACE
                        'N' - No replace will be performed.
                        'Y' - Replace if necessary.
                              In the case of OPT-ACCESS='R' (READ)
                              OPT-REPLACE='Y' activate a READ_TO_UPDATE
                              That means all checks will be done, that
                              would prevent the OPT-ACCESS='W'.
 .
    Input ...... OPT-SESNUM
                        = 0 - Use USR1051-SL for data communication.
                        > 0 - Use this SPF session instead of the array.
                        < 0 - Open a SPF session and use this instead
                              of the array (only on PRD33 FDIC)
    Input ...... OPT-LINE-NUM
                        'Y' - Return line numbers. Default is 'Y'.
                        'N' - Do not return line numbers
 .
    Input ...... OPT-AMOUNT
                        Amount of lines requested.
                        Corresponding to the array USR1051-SL.
                        Negative values will be changed to zero.
                        Must be 14 if OBJECT-TYPE = 'EL'
                        and OPT-ACCESS = 'R'
 .
    Input ...... OPT-LINESIZE
                        Length of each line.
                        Value must not be greater than 250.
                        Corresponding to the array USR1051-SL.
                        Must be 70 if OBJECT-TYPE = 'EL'
                        and OPT-ACCESS = 'R'
 .
    In/Output .. OPT-SL-TYPE
                        In case of different data-types communicated by
                        one OPT-ACCESS/INFO-TYPE this parameter will
                        qualify actual data-type stored in USR1051-SL.
0                       When INFO-TYPE ='E':
                        ' ' - Extended description of PRD
                        'A' - Abstract of a PRD object
                        'C' - Natural Construct (CST) specification
 .
    Output ..... FDIC-VERSION
                        '   ' - when given DBID/FNR is no FDIC.
                         nnn  - when the file is a Predict file,
                                nnn is the Predict version number.
 .
    Output ..... TIMESTMP
                        TIMESTMP is set by OPT-ACCESS = 'R'.
                        Time of last modification
                        The value of the field is converted from internal
                        Natural format (T) to (N13).
 .
    In/Output .. NEXT-SEQ, NEXT-NUM
                        The sequence number and the line number to
                        be used as starting value for the next
                        subprogram call.
                        Filled by the subprogram to initialize the
                        next loop. Do not change.
 .
    In/Output .. USR1051-TEXT
                        For internal use. Do not change.
 .
                        In the case of INFO-TYPE ='E'
                        USR1051-TEXT is redefined in:
                   -- FILLER            (A54)
                   -- DESC-SKELETON-USE (A01)  (Output only)
                        'Y'  - PRD default description is read, when a
                               PRD Object without a description was
                               found and OPT-REPLACE = 'Y'
                        'N'  - default description will not be used.
 .
                   -- DESC-FLAG (A01)          (Output only)
                        'D' - ext.descr. disallowed by DDA
                        'F' - ext.descr. exists and ext.descr. is forced
                        'E' - modifiable ext.descr. existing
                        'N' - Object without ext.descr. existing
                        ' ' - No PRD-Object for the ext.desc. found
 .
                   -- DESC-UP (A01)            (Output only)
                        'L' - ext.descr. not translated to upper case
                        'U' - ext.descr. will be translated to upper case
                              Warning: MSG-TYPE=0 and MSG-NR=1554 is set
                        This flag depends on the PRD general defaults |
 .
    Input ...... USR1051-RESTR (A1/1:V)
                        Selection criteria. Just used for OPT-ACCESS='S'.
 .
                        Dynamic array, with redefinition into
                        - the general PRD restrictions;
                        - object type depending selction criteria.
 .
                        USR1051-RESTR is defined as a variable array in
                        interface. So it is possible to call PRD001 with
                        smaller arrays than (A1/1:V), when not all or
                        even no restrictions are used. Possible values
                        instead of V are 3 thru 439.
 .
                        Minimum array is (A1/1:3). In this case
                        RESTR-LENGTH has to be 3.
 .
                        In all other cases RESTR-LENGTH gives number of
                        bytes of USR1051-RESTR(*) that will be processed
                        by interface program.
 .
                        For details of restriction definition see
                        redefinition of USR1051-RESTR(*) in PDA:USR1051A.
                        Description of some fields of this redefinition:
                   -- RESTR-LENGTH (N3)
                           < 4  := No USR1051-RESTR given.
                           > 3  := Used bytes of USR1051-RESTR(*)
                   -- RESTR-LAN (A1)
                        When OBJECT-TYPE = 'PR'
                            Programming language
                        When OBJECT-TYPE = 'EL'
                            Position of language of RESTR-EL-SYNONYM
                   -- RESTR-EL-SORT (A01)
                        Only used for OBJECT-TYPE 'EL'
                           F =  Field list sorted by File
                           else Field list sorted by Field
                   -- RESTR-FI-SEL (A1)
                        File selection criterion
                            M = Only masterfiles
                            R = Only files wich can have related files
                            V = Only DB2 files (tables and views)
 .
    Output ..... SL-RETURN (P03)
                        Number of filled occurrences.
                        For OPT-ACCESS = 'W':
                        0 := means all filled occurrences of SL-TEXT
                             are written, until a negative SL-NUM is
                             reached.
 .
    Output ..... SL-NUM (N04/1:nn), SL-TEXT (A01/1:nn,1:mm),
                        Line number, data line,
                        The upper index of the arrays is variable.
                        nn  corresponds to OPT-AMOUNT;
                        mm  corresponds to OPT-LINESIZE.
 .
                        A negative value in SL-NUM (nn) indicates the end
                        of input data (nn being the first empty line).
                        There is no data in SL-TEXT(nn).
 .
    Output ..... SL-SEQ (B02/1:nn), SL-LONG (A01/1:nn)
                        Sequence number where the line has been found
                        and a long line indicator.
                        SL-LONG (nn) = '-' means that the next line
                        has to be appended.
 .
                        When OPT-ACCESS=R,INFOTYPE=O and OBJECT-TYPE=EL
                        SL-NUM SL-SEQ and SL-LONG will not be used.
                        Only minimum arrays (A1/1:1) are necessary.
 .
    Output ..... USR1051-MSG (group name)
                        Data used for message exchange.
 .
                        MSG (A79)  Keeps the error text
                        MSG-TYPE (I2)
                            0 := Just a message (DIC or NAT)
                            1 := OPT-ACCESS not executed
                                 MSG-NR is a DIC or NAT msg
                            2 := OPT-ACCESS not executed.
                                 MSG-NR isn't a DIC or NAT msg
                                 MSG keeps the error text
                        MSG-NR (I2)
                            =   0 := everything o.k.
                            = 100 := end of data reached
                            >   0 := any DIC message (without above)
                            <   0 := any NAT message
 .
    Output ..... USR1051-FLD (group name)
                        Value of the field in error.
                        For further information see the PDA USR1051A.
                        To be used for cursor position on (RE)INPUT MAP.
    Layouts:
    --------
    - Select - Layout
         Each selected PRD object is returned in a string of 35 bytes.
         OBJECT-TYPE (A02)
         BLANK       (A01)
         OBJECT-ID   (A32)
         For PRD objects of type EL a string of 68 bytes is returned.
         First 35 bytes see above
         BLANK       (A01)
         FILE-NAME   (A32)
 .
    - Read - Layout for elementary fields
         For each elementary field a string with the following
         layout is returned:
         TYPE             (A2)
         FORMAT           (A2)
         CHARACTER-SET    (A1)
         LENGTH           (N5.2)  /* physical length
         LENGTH-UNIT      (A1)    /* ' ' - bytes
                                  /* 'K' - Kilo bytes
                                  /* 'M' - Mega bytes
                                  /* 'G' - Giga bytes
         OCCURRENCES      (N5)
         SHORT-NAME       (A2)
         HEADER           (A30/1:3)
         SOURCE-FIELD     (A41/1:20)
         CNT-SOURCE-FIELD (N2)
         MASTER-FILE-NAME (A32)   /* Only filled if the field belongs
                                  /* to a file of type 'U' or 'W'
         The layout of every SOURCE-FIELD is as follows
         SC-FIELD-NAME    (A32)
         SC-FORMAT        (A2)
         SC-LENGTH        (N5.2)  /* physical length
 .
 .
    User exits:
    -----------
    User exits specified below will be used when activated in the Predict
    DEFAULT USER EXIT menu.
    Please ensure when using USR1051 and running Predict with activated
    user exists, that user exists are available from the library you
    are using USR1051 from.
    - U-MNT
    - U-MNT1
    - U-ACMR
    - U-DESC
 .
 ************************************************************************
 .
 The calling program has to use the following statement:
 .
 CALLNAT 'USR1051N' USR1051A
                    USR1051-TEXT
                    USR1051-RESTR (1:RESTR-LENGTH)
                    USR1051-SL
                    USR1051-MSG
                    USR1051-FLD
 .
 *****  End of description  *****