     **
     **  Program summary
     **  ---------------
     **
     **  HFS file APIs:
     **    QHFOPNSF      Open HF stream file   Opens and optionally creates a
     **                                        streamfile. Can also be used to
     **                                        check if the file exists.
     **
     **    QHFRDSF       Read HF stream file   Reads a specified number of bytes
     **                                        from a stream file. The file poin-
     **                                        ter is automatically increased by
     **                                        the number of bytes read.
     **
     **    QHFCLOSF      Close HF stream file  Closes the stream file and releases
     **                                        any locks held.
     **
     **  NLS data conversion APIs:
     **    QtqIconvOpen  Code conversion       Initializes conversion as described
     **                  allocation            by the to- and fromcode parameters
     **                                        and then returns the conversion
     **                                        descriptor to be used by the iconv
     **                                        function.
     **
     **    Iconv         Code conversion       Converts the buffer specified by the
     **                                        inbuf parameter as defined by the
     **                                        conversion descriptor. All parameters
     **                                        are updated on return to reflect the
     **                                        progress of the conversion.
     **
     **    Iconv_close   Code conversion       Closes the conversion descriptor and
     **                  deallocation          frees resources allocated.
     **
     **  Work management APIs:
     **    QUSRJOBI      Retrieve job          Retrieves specific specific informa-
     **                  information           tion about a job. The information
     **                                        is grouped in the various formats
     **                                        available.
     **
     **  Sequence of events:
     **    1. The specified stream file is opened - Bytes available in API error
     **                                             data structure > 0 indicates
     **                                             failure
     **
     **    2. The stream file is read into the    - same as above
     **       data buffer parameter
     **
     **    3. The document text is identified and
     **       extracted
     **
     **    4. The document codepage is compared
     **       to the current job CCSID and if
     **       necessary a text conversion is
     **       performed
     **
     **    4a.  A conversion descriptor is opened - failure is signalled by -1
     **
     **    4b.  The conversion is performed       - same as above
     **
     **    4c.  The conversion descriptor is      - same as above
     **         closed
     **
     **    5. The opened stream file is closed    - bytes available in API error
     **                                             data structure > 0 indicates
     **                                             failure
     **
     **  Programmer's note:
     **    This program handles office vision documents to a maximum size of
     **    32767 bytes - for larger documents the retrieval and conversion
     **    of document text will have to be adjusted accordingly.
     **
     **    The functions provided by this program is not comparable to a full
     **    blown commercial conversion product but serves primarily as a
     **    starting point for the use of the APIs involved.
     **
     **    The following DCS-RFT instructions are identified and applied or
     **    ignored in this program:
     **
     **      Attr.  Instruction
     **      -----  --------------------
     **      x'3A'  New page
     **      x'15'  Line feed automatic
     **      x'06'  Line feed controlled
     **      x'0C'  Page end
     **      x'05'  Tabulate
     **      x'41'  Fixed space
     **
     **
     **  Parameters:
     **    PxPthNam    INPUT      Document path name specified as:
     **                           foldername/.../documentname
     **                           - do not specify a preceding '/'
     **
     **    PxDocTxt    OUTPUT     Returns the body text retrieved from the
     **                           specified office document in the form of
     **                           an array.  If a retrieved line is longer
     **                           than the array entry length truncation will
     **                           occur.  To avoid truncation redefine entry
     **                           length accordingly and adjust array dim()
     **                           to fit a current maximum of 32767 bytes.
     **
     **    PxRtnCod    OUTPUT     Code set to indicate the return state of
     **                           the requested document retrieval:
     **
     **                            0   No error occured
     **                           -1   Undefined error    - no text returned
     **                           -2   Line length error  - text truncated
     **                           -3   Conversion error   - text not converted
     **
     **
     **  Compile options:
     **    CRTBNDRPG ...  DBGVIEW(*LIST)
     **
     **
     **-- Control spec:  -----------------------------------------------------**
     H Option( *SrcStmt )  DftActGrp( *No )
     **-- API error data structure:  -----------------------------------------**
     D ApiError        Ds
     D  AeBytPro                     10i 0 Inz( %Size( ApiError ))
     D  AeBytAvl                     10i 0
     D  AeExcpId                      7a
     D                                1a
     D  AeExcpDta                   128a
     **-- Api parameters:  ---------------------------------------------------**
     D HfPthNam        s             63a    Varying
     D HfOpnHnd        s             16a
     D HfDtaBuf        s          32767a
     D HfActTkn        s              1a
     D HfBytRtn        s             10i 0
     **-- Document parameters:  ----------------------------------------------**
     D DocParms        Ds
     D  DpLenByt                      5i 0
     D  DpClsByt                      1a   Inz( x'E2' )
     D  DpTypByt                      1a   Inz( x'05' )
     D  DpFmtByt                      1a   Inz( x'00' )
     D  DpCgCsGid                     4a
     D   DpGcsGid                     5u 0 Overlay( DpCgCsGid: 1 )  Inz
     D   DpCpgId                      5u 0 Overlay( DpCgCsGid: 3 )  Inz
     D  DpRsv                        14a
     D  DpPrcInf                      1a
     D  DpScaDctId                    2a
     D  DpSysTxtUniNm                 6a
     D  DpFmtInf                      1a
     D  DpPriLng                      2a
     D  DpGrdLvl                      1a
     **-- Body text format definition:  --------------------------------------**
     D BdyTxt          Ds
     D  BtLenByt                      5i 0
     D  BtClsByt                      1a   Inz( x'E8' )
     D  BtTypByt                      1a   Inz( x'07' )
     D  BtFmtByt                      1a   Inz( x'00' )
     **-- Multi byte control definition:  ------------------------------------**
     D MltBytCtl       Ds
     D  MbCtlSeqPfx                   1a   Inz( x'2B' )
     D  MbClsByt                      1a
     D  MbCntByt                      3i 0
     D  MbTypByt                      1a
     **-- Global variables:  -------------------------------------------------**
     D DtaBuf          s          32767a   Varying
     D End             s              5i 0
     D Pos             s              5i 0
     D Lin             s              5i 0
     D rc              s             10i 0
     D inbuf_siz       s             10i 0
     D outbuf_siz      s             10i 0
     D inbuf_p         s               *
     D outbuf_p        s               *
     **-- Global constants:  -------------------------------------------------**
     D EupPat          c                   x'0005E10600'
     D DopPat          c                   x'E20500'
     D BtxPat          c                   x'E80700'
     D MbcPat          c                   x'2B'
     D LFC             c                   x'06'
     D LFA             c                   x'15'
     D EPG             c                   x'0C'
     D NPG             c                   x'3A'
     D AT1             c                   x'06150C3A0541'
     D AT2             c                   x'151500154040'
     D Null            c                   ''
     D CurJobDft       c                   0
     **-- Structure definitions:  --------------------------------------------**
     D QtqCode_T       Ds                  Based( pQtqCode_T )
     D  Qtq_CcsId                    10i 0
     D  Qtq_CnvAlt                   10i 0
     D  Qtq_SubAlt                   10i 0
     D  Qtq_ShfSttAlt                10i 0
     D  Qtq_InpLenOpt                10i 0
     D  Qtq_ErrOptMxd                10i 0
     D  Qtq_Rsv                       8a
     **
     D iconv_t         Ds
     D  t_rtnval                     10i 0
     D  t_cd
     D  t_cdi                        10i 0 Dim( 12 )  Overlay( t_cd )
     **
     D fromcode        s                   Like( QtqCode_T )  Inz( *Allx'00' )
     D tocode          s                   Like( QtqCode_T )  Inz( *Allx'00' )
     **-- HFS file APIs:  ----------------------------------------------------**
     D OpnStmf         Pr                  ExtPgm( 'QHFOPNSF' )
     D  OsOpnHnd                     16a
     D  OsPthNam                    256a   Const Options( *VarSize )
     D  OsPthNamLen                  10i 0 Const
     D  OsOpnInf                     10a   Const
     D  OsAtrTbl                   1024a   Const Options( *VarSize )
     D  OsAtrTblLen                  10i 0 Const
     D  OsActTkn                      1a
     D  OsError                   32767a         Options( *VarSize )
     **
     D ReadStmF        Pr                  ExtPgm( 'QHFRDSF' )
     D  RsOpnHnd                     16a   Const
     D  RsDtaBuf                  32767a         Options( *VarSize )
     D  RsBytGet                     10i 0 Const
     D  RsBytRtn                     10i 0
     D  RsError                   32767a         Options( *VarSize )
     **
     D CloseStmF       Pr                  ExtPgm( 'QHFCLOSF' )
     D  CsOpnHnd                     16a   Const
     D  CsError                   32767a         Options( *VarSize )
     **-- Convert string functions:  -----------------------------------------**
     D iconv_open      Pr            52a   ExtProc( 'QtqIconvOpen' )
     D  fromcode                       *   Value
     D  tocode                         *   Value
     **
     D iconv           Pr            10i 0 ExtProc( 'iconv' )
     D  cd                           52a   Value
     D  inbuf                          *   Value
     D  inbytesleft                  10i 0
     D  outbuf                         *   Value
     D  outbytesleft                 10i 0
     **
     D iconv_close     Pr            10i 0 ExtProc( 'iconv_close' )
     D  cd                           52a   Value
     **-- Get job ccsid:  ----------------------------------------------------**
     D JobCcsId        Pr            10i 0
     **-- Parameters:  -------------------------------------------------------**
     D PxPthNam        s             63a
     D PxDocTxt        s             80a   Dim( 409 )
     D PxRtnCod        s              1p 0
     **
     C     *Entry        Plist
     C                   Parm                    PxPthNam
     C                   Parm                    PxDocTxt
     C                   Parm                    PxRtnCod
     **
     **-- Mainline -----------------------------------------------------------**
     **
     C                   Eval      PxRtnCod   =  -1
     C                   Eval      PxDocTxt   =  *Blanks
     **
     C                   Eval      HfPthNam   =  '/QDLS/' + %TrimR( PxPthNam )
     **
     C                   CallP     OpnStmF( HfOpnHnd
     C                                    : HfPthNam
     C                                    : %Len( HfPthNam )
     C                                    : '100 200  '
     C                                    : ''
     C                                    : *Zero
     C                                    : HfActTkn
     C                                    : ApiError
     C                                    )
     **
     C                   If        AeBytAvl   =  *Zero
     **
     C                   CallP     ReadStmF( HfOpnHnd
     C                                     : HfDtaBuf
     C                                     : %Size( HfDtaBuf )
     C                                     : HfBytRtn
     C                                     : ApiError
     C                                     )
     **
     C                   If        AeBytAvl   =  *Zero
     C                   Eval      PxRtnCod   =  *Zero
     **
     C                   If        HfBytRtn   >  *Zero
     C                   ExSr      ExtDocTxt
     C                   EndIf
     C                   EndIf
     **
     C                   CallP     CloseStmF( HfOpnHnd
     C                                      : ApiError
     C                                      )
     C                   EndIf
     **
     C                   Return
     **
     **-- Extract document text:  --------------------------------------------**
     C     ExtDocTxt     BegSr
     **
     C                   ExSr      RtvDtaBuf
     C                   ExSr      StripMbc
     **
     C     AT1:AT2       Xlate     DtaBuf        DtaBuf
     **
     C                   Eval      Lin        =  0
     C                   Eval      Pos        =  1
     **
     C                   Eval      End        =  %Scan( LFA: DtaBuf )
     **
     C                   DoW       End        >  *Zero
     **
     C                   If        End - Pos  >  %Size( PxDocTxt )
     C                   Eval      PxRtnCod   =  -2
     C                   EndIf
     **
     C                   Eval      Lin        =  Lin + 1
     C                   Eval      PxDocTxt(Lin) = %SubSt( DtaBuf
     C                                                   : Pos
     C                                                   : End - Pos
     C                                                   )
     **
     C                   Eval      Pos        =  End + 1
     C                   Eval      End        =  %Scan( LFA: DtaBuf: Pos )
     C                   EndDo
     **
     C                   If        JobCcsId   <> DpCpgId
     C                   ExSr      CvtDocTxt
     C                   EndIf
     **
     C                   EndSr
     **-- Retrieve data buffer:  ---------------------------------------------**
     C     RtvDtaBuf     BegSr
     **
     C                   Eval      DtaBuf     =  %SubSt( HfDtaBuf
     C                                                 : 1
     C                                                 : HfBytRtn
     C                                                 )
     **
     C                   Eval      Pos        =  %Scan( DopPat: DtaBuf )
     **
     C                   If        Pos        >  *Zero
     C                   Eval      DocParms   =  %SubSt( DtaBuf
     C                                                 : Pos - 2
     C                                                 : 2
     C                                                 )
     **
     C                   Eval      DocParms   =  %SubSt( DtaBuf
     C                                                 : Pos - 2
     C                                                 : DpLenByt
     C                                                 )
     C                   EndIf
     **
     C                   Eval      Pos        =  %Scan( BtxPat: DtaBuf )
     **
     C                   If        Pos        >  *Zero
     C                   Eval      BdyTxt     =  %SubSt( DtaBuf
     C                                                 : Pos - 2
     C                                                 : %Size( BdyTxt )
     C                                                 )
     **
     C                   Eval      DtaBuf     =  %SubSt( DtaBuf
     C                                                 : Pos + 3
     C                                                 : BtLenByt
     C                                                 )
     C                   EndIf
     **
     C                   Eval      Pos        =  %Scan( EupPat: DtaBuf )
     **
     C                   If        Pos        >  *Zero
     C                   Eval      DtaBuf     =  %Replace( Null
     C                                                   : DtaBuf
     C                                                   : Pos
     C                                                   : %Size( EupPat )
     C                                                   )
     C                   EndIf
     **
     C                   EndSr
     **-- Strip multi byte controls:  ----------------------------------------**
     C     StripMbc      BegSr
     **
     C                   Eval      Pos        =  %Scan( MbcPat: DtaBuf )
     C                   DoW       Pos        >  *Zero
     **
     C                   Eval      MltBytCtl  =  %SubSt( DtaBuf: Pos: 4 )
     **
     C                   Eval      DtaBuf     =  %SubSt( DtaBuf
     C                                                 : 1
     C                                                 : Pos - 1
     C                                                 ) +
     **
     C                                           %SubSt( DtaBuf
     C                                                 : MbCntByt + Pos + 2
     C                                                 )
     **
     C                   Eval      Pos        =  %Scan( MbcPat: DtaBuf: Pos )
     C                   EndDo
     **
     C                   EndSr
     **-- Convert document text:  --------------------------------------------**
     C     CvtDocTxt     BegSr
     **
     C                   Eval      pQtqCode_T =  %Addr( fromcode )
     C                   Eval      Qtq_CcsId  =  DpCpgId
     **
     C                   Eval      pQtqCode_T =  %Addr( tocode )
     C                   Eval      Qtq_CcsId  =  CurJobDft
     **
     C                   Eval      iconv_t    =  iconv_open( %Addr( tocode )
     C                                                     : %Addr( fromcode ))
     **
     C                   If        t_rtnval   =  -1
     C                   Eval      PxRtnCod   =  -3
     **
     C                   Else
     C                   Eval      inbuf_p    =  %Addr( PxDocTxt )
     C                   Eval      outbuf_p   =  %Addr( PxDocTxt )
     **
     C                   Eval      inbuf_siz  =  %Size( PxDocTxt ) * Lin
     C                   Eval      outbuf_siz =  inbuf_siz
     **
     C                   Eval      rc         =  iconv( iconv_t
     C                                                : %Addr( inbuf_p  )
     C                                                : inbuf_siz
     C                                                : %Addr( outbuf_p )
     C                                                : outbuf_siz
     C                                                )
     **
     C                   Eval      rc         =  iconv_close( iconv_t )
     C                   EndIf
     **
     C                   EndSr
     **-- Get job ccsid:  ----------------------------------------------------**
     P JobCcsId        B
     D                 Pi            10i 0
     **-- Retrieve job information:  -----------------------------------------**
     D RtvJobInf       Pr                  ExtPgm( 'QUSRJOBI' )
     D  RiRcvVar                  32767a         Options( *VarSize )
     D  RiRcvVarLen                  10i 0 Const
     D  RiFmtNam                      8a   Const
     D  RiJobNamQ                    26a   Const
     D  RiJobIntId                   16a   Const
     **-- Optional:
     D  RiError                   32767a         Options( *NoPass: *VarSize )
     **-- Job info format JOBI0400:
     D J4RcvDta        Ds
     D  J4BytRtn                     10i 0
     D  J4BytAvl                     10i 0
     D  J4JobNam                     10a
     D  J4UsrNam                     10a
     D  J4JobNbr                      6a
     D  J4CcsId                      10i 0 Overlay( J4RcvDta: 301 )
     D  J4CcsIdDft                   10i 0 Overlay( J4RcvDta: 373 )
     **
     C                   CallP     RtvJobInf( J4RcvDta
     C                                      : %Size( J4RcvDta )
     C                                      : 'JOBI0400'
     C                                      : '*'
     C                                      : *Blank
     C                                      : ApiError
     C                                      )
     **
     C                   Select
     C                   When      AeBytAvl    > *Zero
     C                   Return    -1
     **
     C                   When      J4CcsId     = 65535
     C                   Return    J4CcsIdDft
     **
     C                   Other
     C                   Return    J4CcsId
     C                   EndSl
     **
     P JobCcsId        E
