/****************************** Module Header *******************************
*
* Module Name: readfilepart.e
*
* E wrapper routine to access the NEPMD library DLL.
* Include of nepmdlib.e.
*
* Copyright (c) Netlabs EPM Distribution Project 2002
*
* $Id$
*
* ===========================================================================
*
* This file is part of the Netlabs EPM Distribution package and is free
* software.  You can redistribute it and/or modify it under the terms of the
* GNU General Public License as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* Netlabs EPM Distribution.  This library is distributed in the hope that it
* will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
* of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
* General Public License for more details.
*
****************************************************************************/

/*
@@NepmdReadFilePart@PROTOTYPE
EnvValue = NepmdReadFilePart( Filename, ReadLen, OffLen)

@@NepmdReadFilePart@CATEGORY@FILE

@@NepmdReadFilePart@SYNTAX
This function reads a part of a file.

@@NepmdReadFilePart@PARM@Filename
This parameter specifies the filename of the read file.

@@NepmdReadFilePart@PARM@ReadLen
This parameter is optional. It specifies the length of the read part in bytes.
The default value is 64.

@@NepmdReadFilePart@PARM@OffLen
This parameter is optional. It specifies the length of the offset from the
file begin in bytes. The default value is 0, which means that the first bytes
of the file are read.

If this is specified, all parameters before must be specified, too. To use
the default value for ReadLen, an empty value must be specified. It may not
be omitted then.

@@NepmdReadFilePart@RETURNS
*NepmdReadFilePart* returns the file part data.
In case of an error an empty string is returned.

This procedure sets the implicit universal var *rc*. rc is set to an
[inf:cp2 "Errors" OS/2 error code] or to zero for no error.

@@NepmdReadFilePart@TESTCASE
You can test this function from the *EPM* commandline by
executing:
.sl
- *NepmdReadFilePart* [.IDPNL_EFUNC_NepmdReadFilePart_PARM_Filename Filename]
  - or
- *ReadFilePart* [.IDPNL_EFUNC_NepmdReadFilePart_PARM_Filename Filename]

Executing this command will
open up a virtual file and
display the first 64 bytes of the file with the specified filename.

*Examples:*
.fo text
  ReadFilePart c:\config.sys
  ReadFilePart c:\config.sys 16
.fo on

@@
*/

; ---------------------------------------------------------------------------
; Allow editor command to call function
; ---------------------------------------------------------------------------
compile if NEPMD_LIB_TEST

defc NepmdReadFilePart, ReadFilePart

   do i = 1 to 1

      parse arg Args
      Args = strip( Args)
      if leftstr( Args, 1) = '"' then
         parse value Args with '"'Filename'"' Bufflen
      else
         parse value Args with Filename Bufflen
      endif

      Filename = strip( Filename)
      Bufflen = strip( Bufflen)

      if (Filename = '') then
         sayerror 'Error: no filename specified.'
         leave
      endif
      if Bufflen = '' then
         Bufflen = 64  -- Not required, just for the virtual file.
      endif            -- 64 is the default value for NepmdReadFilePart.

      FilePart = NepmdReadFilePart( Filename, Bufflen)
      BytesRead = length( FilePart)

      if rc then
         sayerror 'Error from NepmdReadFilePart, rc = 'rc'.'
         leave
      endif

      HelperNepmdCreateDumpfile( 'NepmdReadFilePart', Args)
      insertline 'The first 'BytesRead' bytes of 'Filename' are:'
      insertline FilePart
      .modify = 0

   enddo

compile endif

; ---------------------------------------------------------------------------
; Procedure: NepmdReadFilePart
; ---------------------------------------------------------------------------
; E syntax:
;    FilePart = NepmdReadFilePart( Filename [, Bufflen [, OffLen]])
; ---------------------------------------------------------------------------
; C prototype:
;    APIRET EXPENTRY NepmdReadFilePart( PSZ pszName,
;                                       ULONG ulOffset,
;                                       PVOID pvBuffer,
;                                       ULONG ulBufflen,
;                                       PULONG pulBytesRead);
; ---------------------------------------------------------------------------

defproc NepmdReadFilePart( Filename)
   Bufflen = arg( 2)
   OffLen  = arg( 3)
   if Bufflen = '' then
      Bufflen = 64
   endif
   if OffLen = '' then
      OffLen = 0
   endif

   -- Strange: Must check if file exists first. If NepmdReadFilePart tries
   -- to open a non-existant file, an OS/2 window (start /win) closes
   -- immediately and an EPM command shell fails with SYS0006. This works
   -- around that E flaw:
   if not Exist( Filename) then
      rc = 2
      return
   endif

   BytesRead = 1234

   -- Prepare parameters for C routine
   FilePart = copies( \0, Bufflen)
   FilenameZ = Filename\0

   -- Call C routine
   LibFile = HelperNepmdGetLibFile()
   rc = dynalink32( LibFile,
                    "NepmdReadFilePart",
                    address( FilenameZ)  ||
                    atol( OffLen)        ||
                    address( FilePart)   ||
                    atol( Bufflen)       ||
                    address( BytesRead), 2)
   HelperNepmdCheckLibError( LibFile, rc)
   BytesRead = ltoa( BytesRead, 10)

   if rc then
      return
   else
      -- Cut trailing \0 chars if BytesRead < BuflLen
      return leftstr( FilePart, BytesRead)  -- not \0-terminated (PVOID)
   endif