APIs, user spaces, etc.

From MidrangeWiki
Jump to: navigation, search

Summary

Here's a sample of using an API which outputs to a user space in COBOL. This example lists and processes members in a file. Error handling would need to be coded.

You can either use your own definition for the APIs or the definition in the QSYSINC library. I generally use my own because I can tailor defaults for our environment. YMMV (Your Mileage May Vary). In our shop, we keep our definitions of the API interfaces in copy members. In the example below, I have included the actual code for the complete picture.

Working-storage section.

     *
     *    API error code parameter
     *
      01   API-errors.
          05  API-error-length        pic 9(8)    binary
                                                  value 16.
              88  Return-error-code-only          value 16.
              88  Return-exception-data-132       value 148.
          05  Error-length            pic 9(8)    binary.
              88  API-processed-okay              value 0.
          05  Error-ID                pic x(7).
          05  filler                  pic x(1).
          05  Exception-data          pic x(132).
     *
     * User space APIs
      01  User-space-api.
          05  User-space-name.
              10  Space-name          pic x(10)   value spaces.
              10  Space-library       pic x(10)   value 'QTEMP'.
          05  User-space-attribute    pic x(10)   value spaces.
          05  Initial-size            pic 9(8)    binary
                                                  value 11100.
      05  Initial-value               pic x       value X'00'.
      05  Public-authority            pic x(10)   value '*ALL'.
      05  Space-text                  pic x(50)   value spaces.
      05  Replace-space               pic x(10)   value '*YES'.
      77  User-space-pointer          pointer.
     *
     * Member list
      01  Member-list-api.
          05  User-space-name.
              10  Space-name          pic x(10)   value spaces.
              10  Space-library       pic x(10)   value 'QTEMP'.
          05  Member-list-format      pic x(8)    value 'MBRL0200'.
          05  Member-list-file.
              10  Member-list-file-name
                                      pic x(10)   value spaces.
              10  Member-list-library pic x(10)   value '*LIBL'.
          05  Members-to-list         pic x(10)   value '*ALL'.
          05  Member-list-overrides   pic x       value '0'.
              88  Member-list-ignore-ovrdbf       value '0'.
              88  Member-list-use-ovrdbf          value '1'.
          05  Member-list-return-header.
              10  File-name-used      pic x(10).
              10  File-library-used   pic x(10).
              10  File-attribute      pic x(10).
              10  Text-description    pic x(10).
              10  Number-of-members   pic s9(8)   binary.
              10  File-type           pic x.
                  88  Data-file                   value '0'.
                  88  Source-file                 value '1'.
      01  List-entry-address          pointer.
     *
     *    Member Description API
     *
      01   Member-desc-api.
         05   QUSRMBRD              pic x(10)     value 'QUSRMBRD'.
         05   Member-data.
            10   Returned-bytes     pic 9(8)      binary.              Rtn B
            10   Available-bytes    pic 9(8)      binary.              Avail B
            10   Return-file        pic x(10).                         DBF Name
            10   Return-library     pic x(10).                         DBF Lib
            10   Return-member      pic x(10).                         Member
            10   File-attributes    pic x(10).                         File Atr
            10   Source-type        pic x(10).                         Src Type
            10   Date-added         pic x(13).                         Crt DS
            10   Date-changed       pic x(13).                         SrcChgDS
            10   Member-text        pic x(50).                         Descript
            10   Source-file        pic x.                             Src File
            10   Remote-file        pic x.                             Rmt File
            10   File-type          pic x.                             LF / PF
            10   ODP-sharing        pic x.                             ODP Shr
            10   filler             pic xx.                            *Rsrvd*
            10   Number-of-records  pic 9(8)      binary.
            10   Deleted-records    pic 9(8)      binary.
            10   Data-space-size    pic 9(8)      binary.
            10   Access-path-size   pic 9(8)      binary.
            10   Based-on-members   pic 9(8)      binary.
            10   Change-timestamp   pic x(13).
            10   Save-timestamp     pic x(13).
            10   Restore-timestamp  pic x(13).
            10   Expiration-date    pic x(7).
            10   filler             pic x(6).
            10   Number-days-used   pic 9(8)      binary.
            10   Date-last-used     pic x(7).
            10   Use-reset-date     pic x(7).
            10   filler             pic xx.
            10   DS-size-multiplier pic 9(8)      binary.
            10   AP-size-multiplier pic 9(8)      binary.
            10   Description-CCSID  pic 9(8)      binary.
            10   Offset-to-MBRD0200 pic 9(8)      binary.
            10   Length-of-MBRD0200 pic 9(8)      binary.
            10   Nbr-rcds-all-mbrs  pic 9(8)      binary.
            10   Nbr-deleted-recds  pic 9(8)      binary.
            10   filler             pic x(6).
         05   Return-length         pic 9(8)      binary value 144.
            88   Number-of-records-length         value 144.
            88   MBRD0100-length                  value 134.
            88   MBRD0200-length                  value 265.
         05   Format-name           pic x(8)      value  'MBRD0200'.
            88   MBRD0100-format                  value  'MBRD0100'.
            88   MBRD0200-format                  value  'MBRD0200'.
         05   Qual-file-name.
            10   Work-file          pic x(10).
            10   Work-library       pic x(10).
         05   Member-name           pic x(10)     value '*FIRST'.
         05   Override-processing   pic x.
            88   Ignore-overrides                 value '0'.
            88   Process-overrides                value '1'.

Linkage section.

      01  File-parm.
          05  File-name-parm          pic x(10).
          05  Library-name-parm       pic x(10).
     * Record lock handling
      copy UTBLSRLCK.
     * Generic list API header structure
      01  List-header-info.
          05  f                       pic x(124).
          05  Offset-to-list-data     pic 9(8)    binary.
          05  Size-of-list-data       pic 9(8)    binary.
          05  Number-of-entries       pic 9(8)    binary.
          05  Size-of-list-entry      pic 9(8)    binary.
     * Member list API entry format
      01  MBR0200-data-format.
          05  Member-name             pic x(10).
          05  Source-type             pic x(10).
          05  Member-date-and-time.
              10  Member-date         pic 9(6)    display.
              10  Member-time         pic 9(7)    display.
          05  Source-change-date-and-time.
              10  Change-date         pic 9(6)    display.
              10  Change-time         pic 9(7)    display.
          05  Member-text             pic x(50).
          05  Member-text-ccsid       pic 9(8)    binary.


Procedure Division

              using File-parm
          .
      0000-Begin-here.
          perform 0010-Initialization
          if Number-of-entries > 0
              perform 1000-Build-member-list
          end-if
          perform 0500-Wrap-up
          goback
          .
      0010-Initialization.
          move 'MBRLIST'  to Space-name       of User-space-api
          move 'List of inventory sheet sequence members'
                          to Space-text       of User-space-api
          call 'QUSCRTUS'
              using   User-space-name         of User-space-api
                      User-space-attribute    of User-space-api
                      Initial-size
                      Initial-value
                      Public-authority
                      Space-text
                      Replace-space
                      API-errors
          end-call
          move File-parm      to  Member-list-file
          call 'QUSLMBR'
              using   User-space-name         of User-space-api
                      Member-list-format
                      Member-list-file
                      Members-to-list
                      Member-list-overrides
                      Api-errors
          end-call
          call 'QUSPTRUS'
              using   User-space-name         of User-space-api
                      User-space-pointer
                      Api-errors
          end-call
          set address of List-header-info to User-space-pointer
          .
      0500-Wrap-up.
     * Do any clean-up processing needed here
     *   In this example the user space is created in QTEMP so it will go away at the
     *   end of the job.  Perhaps files could be closed, etc.
          .
      1000-Build-member-list.
          set List-entry-address to User-space-pointer
          set List-entry-address up by Offset-to-list-data
          move zero to Subfile-rrn
          perform Number-of-entries times
              set address of MBR0200-data-format to List-entry-address
              move File-name to Qual-file-name of Member-desc-api
              move Member-name of MBR0200-data-format
                             to Member-name    of Member-desc-api
     *********************************************************
     *  More processing would be done here
     *********************************************************
              set List-entry-address up by Size-of-list-entry
          end-perform
          .

Categories