home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / misc / psy_kit.zip / PDFM.DOC < prev    next >
Text File  |  1993-10-29  |  15KB  |  338 lines
  1.  
  2.                                   
  3.  ╔══════════════════════════════════════════════════════════════════════════╗
  4.  ║              P S Y C H O S E   D A T A   F I L E   M A K E R             ║
  5.  ║                                    &                                     ║
  6.  ║      P S Y C H O S E   D A T A   F I L E   I N T E R F A C E   K I T     ║
  7.  ║                                                                          ║
  8.  ║                     for Assembly language programming                    ║
  9.  ╟──────────────────────────────────────────────────────────────────────────╢
  10.  ║                                                                          ║
  11.  ║      This is the documentation file for the Psychose Datafile Maker      ║
  12.  ║                and for the Psychose Datafile Interface Kit               ║
  13.  ║                                                                          ║
  14.  ║                     -=≡≡≡ P D F M  &  P D F I K ≡≡≡=-                    ║
  15.  ║                                                                          ║
  16.  ╟──────────────────────────────────────────────────────────────────────────╢
  17.  ║             (C)opyright 1993 by NAPALM from PSYCHOSE, Inc.               ║
  18.  ╚══════════════════════════════════════════════════════════════════════════╝
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.                     = ] ------ Table of contents ------ [ =
  26.  
  27.  
  28.   1. [Introduction] ........... Hey...ya! What is the PDFM ?
  29.   2. [License] ................ Yep yep ! Don't forget it dude...
  30.   3. [A matter of food] ....... How to feed this 'byte-eater' utility.
  31.   4. [Related stuff: PDFIK] ... Whoa! Cool! But what now ?
  32.   5. [PDFIK functions] ........ At last! Calling PDFIK from assembly.
  33.      5.1 What you need to include in your source code
  34.      5.2 Calling conventions
  35.   6. [To contact me] .......... BBS, Minitel and all that.
  36.   7. [Good bye user] .......... Latest information.
  37.  
  38.  
  39.                     = ] ------------------------------- [ =
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.   1. [Introduction]
  48.  
  49.      The PSYCHOSE Datafile Maker (PDFM) is a small utility designed to help
  50.      you create special files, called datafiles, where you put all the
  51.      data (such as images, musics or texts ) you need for a demo.
  52.      The original data is compressed using a standard Lempel-Ziv algorithm
  53.      which can achieve good compression ratios, saving space (and also disks
  54.      when it's time to release your demo...).
  55.      Even if this is supposed to be a standard utility, you'll need at least
  56.      a 386 to run this program, because I used several 386 instructions
  57.      during coding. (I know what ya're goin' to tell me but forget it !!!)
  58.  
  59.  
  60.  
  61.  
  62.   2. [License]
  63.  
  64.      You are free to use, distribute or copy PDFM and PDFIK, but only under
  65.      the following conditions:
  66.  
  67.      ■ The program using PDFM and PDFIK is not a commercial one
  68.        (Shareware is considered as commercial software)
  69.  
  70.      ■ You must mention in your program and/or in its documentation
  71.        you used PDFM and/or PDFIK, that is give us credits for the work
  72.        we've done!
  73.  
  74.      ■ PDFM and PDFIK are not modified in any way, and stay in their
  75.        original form. If you decide to copy PDFM and PDFIK to a friend
  76.        (and you are encouraged to do so...), please copy the full package
  77.        with its documentation, include and executable files.
  78.  
  79.  
  80.  
  81.  
  82.   3. [A matter of food]
  83.  
  84.      You'll have to provide the PDFM with a Listfile, that is, a file
  85.      containing the name of the Datafile (were the packed data is stored)
  86.      and the names of the files you want to include in that Datafile.
  87.      The Listfile is an ASCII file organized as follows:
  88.  
  89.      ┌────────────┐
  90.      │DATANAME.EXT│ <───■ Datafile name (MUST be the first one...)
  91.      │FILE1.EXT   │ <───■ File name n°1
  92.      │FILE2.EXT   │ <───■ File name n°2
  93.      │    .       │
  94.      │    .       │
  95.      │    .       │
  96.      │FILEn.EXT   │ <───■ The last file name
  97.      │∞           │ <───■ [ALT 236] character for 'end of input'
  98.      └────────────┘
  99.  
  100.      note: there must be only one name per line.
  101.  
  102.  
  103.  
  104.  
  105.   4. [Related stuff: PDFIK]
  106.  
  107.      The Datafile is nice, isn't it dear ? wha ah ah ah ah! ...hum...
  108.      So now you got a Datafile ready but a simple question flashed through
  109.      your mind...: Hey Dude! How do I use the Datafile from my source code ?
  110.      Well...er... PSYCHOSE is here again to help you!
  111.      I coded a special interface called PSYCHOSE Datafile Interface Kit
  112.      (PDFIK) which implements cool functions for lazy loading of a specified
  113.      file from the Datafile (where it's stored...) into a memory buffer.
  114.      This lazy interface offers full support of 32BMM (another cool OBJ from
  115.      ...? Guess who...? PSYCHOSE evidently...)
  116.      See the next section for more precise details.
  117.  
  118.  
  119.  
  120.  
  121.   5. [PDFIK functions]
  122.  
  123.      Remember you must have at least a 386 to run any of these routines!
  124.      and when using .386P or .486 directives don't forget to specify
  125.      the USE16 directive in segment(s) declaration(s).
  126.      (besides the functions will not test any of these for you...)
  127.  
  128.  
  129.      5.1 What you need to include in your source code
  130.  
  131.          just insert the following line in your code:
  132.          include PDFIK.INC
  133.  
  134.          The PDFIK.INC file contains the necessary declarations and
  135.          data stuctures to communicate with the PDFIK.
  136.          Here is a copy of its contents:
  137.  
  138.          EXTRN PDFIK_ASM : FAR   ; Main routine (external)
  139.  
  140.          PARAM_STRUC     STRUC   ; Structure to pass & receive parameters
  141.          Function        db ?    ; Function number
  142.          DtaSeg          dw ?    ; Segment of related datas
  143.          DtaOfsPdf       dw ?    ; Offset in DtaSeg of datafile name (ASCIIZ)
  144.          DtaOfsFil       dw ?    ; Offset in DtaSeg of file name     (ASCIIZ)
  145.          OfsInPdf        dd ?    ; Offset from beginning of Datafile
  146.          OfsInFil        dd ?    ; Offset from beginning of File
  147.          NumBytes        dd ?    ; Number of bytes to decompress
  148.          BufSeg          dw ?    ; Segment of buffer where to unpack the data
  149.          BufOfs          dw ?    ; Offset in BufSeg
  150.          FlatMode        db ?    ; 0=No 32BMM, 1=32BMM use/compatible.
  151.          MemMode         db ?    ; Memory mode of output buffer (see 32BMM ref.)
  152.          MemHandle       dw ?    ; Handle of output buffer (32BMM support)
  153.          LinearOfs       dd ?    ; 32bit linear offset of output buffer (32BMM)
  154.          NormSize        dd ?    ; Size of the normal file (unpacked)
  155.          PackSize        dd ?    ; Size in the datafile (packed)
  156.          ErrorCode       db ?    ; Return code from PDFIK
  157.          PARAM_STRUC     ENDS    ; End of structure
  158.  
  159.          I think all the fields are self-explanatory (Ok, Ok I'm the coder
  160.          so it's normal no?) except perhaps the OfsInPdf field.
  161.          This field is used when the Datafile is integrated in the EXE,
  162.          that is when you (and everyone for sure!) want the Datafile to be
  163.          part of the EXE file, so that you release only one (Big!) EXE.
  164.          This 32 bit number represents the size of the EXE just after
  165.          compile process is complete. To include the Datafile in the EXE just
  166.          type:  COPY /B PROG.EXE+DATAFILE.EXT NEWPROG.EXE
  167.          and remember to use the 'NEWPROG.EXE' filename for the DtaOfsPdf
  168.          field (that is, as the Datafile name!).
  169.  
  170.          coder's advice:
  171.          You don't need to set up all the fields each time you call one
  172.          function (this will lead to a real nightmare! huhu...).
  173.          In fact fill the "general purpose" fields in some initilization
  174.          routine at the beginning of yar program and then you just have to fill
  175.          3 or 4 fields at each call (unless ya wanna change some settings!).
  176.  
  177.  
  178.      5.2 Calling conventions
  179.  
  180.          Please refer to the 32BMM reference for detailed explanations about
  181.          the fields referencing use of 32BMM.
  182.  
  183.          We assume here that the 'x' label refers to a PARAM_STRUC type
  184.          structure declared and allocated in your Data Segment as follows:
  185.          x      PARAM_STRUC <,,,,,,,,,>
  186.  
  187.          At this moment only three functions are available. The first one is
  188.          called [GetInfo] and is used to obtain information (i.e: the size
  189.          of the original file, and its size in the Datafile) about a specified
  190.          file stored in the Datafile. The second function is [Extract] and...
  191.          huhu... is used to extract a file from the Datafile to a memory
  192.          buffer. The third one is [Extract2] and provides the laziest loading
  193.          of a file because it takes less parameters and allocates directly
  194.          the memory (which has to be de-allocated by user..).
  195.          You can call the three routines like this:
  196.  
  197.          mov x.Function,(Function number)
  198.              ...
  199.          <Fill all necessary fields>
  200.              ...
  201.          mov ES,(Segment of x)
  202.          mov BX,(Offset of x)
  203.          call PDFIK_ASM
  204.          <Check the return code>
  205.  
  206.  
  207.          [GetInfo routine]
  208.          ■ before call:
  209.            x.Function  = 0
  210.            x.DtaSeg    = Address of DATA segment (for following datas)
  211.            x.DtaOfsPdf = Offset of ASCIIZ string for Datafile name
  212.                          (string example:  Datafile db 'DATA1.DTA',0 )
  213.            x.DtaOfsFil = Offset of ASCIIZ string for file name
  214.                          (string example:  File db 'TEXT.DOC',0 )
  215.            x.OfsInPdf  = Offset for beginning of Datafile in EXE
  216.                          (i.e: size of the EXE file)
  217.                          This value is 0 when Datafile is not integrated
  218.                          in a EXE.
  219.            ES:BX       = pointer to the x structure (PARAM_STRUC type)
  220.  
  221.  
  222.          ■ after call:
  223.            x.NormSize  = Size of original file (for memory allocation)
  224.            x.PackSize  = Size of packed file
  225.            x.ErrorCode = return code from PDFIK
  226.                          0 = OK, no problemo!
  227.                          1 = Datafile not found (wrong name, ...)
  228.                          2 = Invalid format (not a PSYCHOSE Datafile)
  229.                          3 = File not found in Datafile (wrong name, ...)
  230.                          4 = Memory allocation error (used by [Extract2])
  231.            ES:BX       = pointer to the x structure (PARAM_STRUC type)
  232.  
  233.  
  234.  
  235.          [Extract routine]
  236.          ■ before call:
  237.            x.Function  = 1
  238.            x.DtaSeg    = Address of DATA segment (for following datas)
  239.            x.DtaOfsPdf = Offset of ASCIIZ string for Datafile name
  240.                          (string example:  Datafile db 'DATA1.DTA',0 )
  241.            x.DtaOfsFil = Offset of ASCIIZ string for file name
  242.                          (string example:  File db 'TEXT.DOC',0 )
  243.            x.OfsInPdf  = Offset for beginning of Datafile in EXE
  244.                          (i.e: size of the EXE file)
  245.                          This value is 0 when Datafile is not integrated
  246.                          in a EXE.
  247.            x.BufSeg    = Segment of buffer where we unpack
  248.                          (allocated by user)
  249.            x.BufOfs    = Offset in BufSeg
  250.            ES:BX       = pointer to the x structure (PARAM_STRUC type)
  251.  
  252.  
  253.          ■ after call:
  254.            x.ErrorCode = return code (see GetInfo)
  255.            ES:BX       = pointer to the x structure (PARAM_STRUC type)
  256.  
  257.  
  258.  
  259.          [Extract2 routine - 32BMM compatible]
  260.          ■ before call:
  261.            x.Function  = 2
  262.            x.DtaSeg    = Address of DATA segment (for following datas)
  263.            x.DtaOfsPdf = Offset of ASCIIZ string for Datafile name
  264.                          (string example:  Datafile db 'DATA1.DTA',0 )
  265.            x.DtaOfsFil = Offset of ASCIIZ string for file name
  266.                          (string example:  File db 'TEXT.DOC',0 )
  267.            x.OfsInPdf  = Offset for beginning of Datafile in EXE
  268.                          (i.e: size of the EXE file)
  269.                          This value is 0 when Datafile is not integrated
  270.                          in a EXE.
  271.            x.OfsInFil  = Offset from which we begin to unpack
  272.                          (i.e: how many bytes we jump in the original
  273.                           file before unpacking)
  274.            x.NumBytes  = How many bytes we unpack
  275.                          (0 means unpack ALL)
  276.            x.FlatMode  = 0 means standard DOS memory allocation
  277.                          1 means 32BMM Flat Real Mode memory allocation
  278.            ES:BX       = pointer to the x structure (PARAM_STRUC type)
  279.  
  280.  
  281.          ■ after call:
  282.            x.ErrorCode = return code (see GetInfo)
  283.            if x.FlatMode was 1
  284.                 x.LinearOfs = 32bits linear address of output buffer
  285.                 x.MemMode   = Memory mode of output buffer (Save it!)
  286.                 x.MemHandle = Handle of output buffer (Save it!)
  287.            else
  288.                 x.BufSeg    = Segment of output buffer
  289.            ES:BX       = pointer to the x structure (PARAM_STRUC type)
  290.  
  291.            Note: this is very easy to convert a standard segment to a 32bits
  292.                  linear address compatible with 32BMM. Just multiply the
  293.                  segment value by 16 and you'll get it ! For example if AX
  294.                  contains the segment value, ESI will contain the 32bits linear
  295.                  address after the follwing lines:
  296.  
  297.                         movzx esi,ax
  298.                         shl esi,4
  299.                         ...
  300.  
  301.  
  302.  
  303.  
  304.   6. [To contact me]  (Hey! no illegal stuff ok?)
  305.  
  306.      If you're French use your Minitel:
  307.        3615 RTEL
  308.        BAL NAPALM
  309.      (alors les p'tits gars ça flotte ? Hehe...)
  310.  
  311.      For a personal contact write to:
  312.  
  313.                              ┌───────────────────────┐
  314.                              │ Rémy Chibois (NAPALM) │
  315.                              └───────────┬───────────┘
  316.          ┌──────────────────────────┐    │    ┌───────────────────┐
  317.          │   1 ter Av. de l'étang   │<───┴───>│ 43 rue de Chabrol │
  318.          │ 78320 Le Mesnil St Denis │         │    75010 Paris    │
  319.          │          FRANCE          │         │      FRANCE       │
  320.          └──────────────────────────┘         └───────────────────┘
  321.  
  322.  
  323.  
  324.  
  325.   7. [Good bye user]
  326.  
  327.      I intend to improve the compression algorithm, of course, and new
  328.      functions will also be added to ensure a more flexible use.
  329.      (is that possible ?  Haha..)
  330.      Well now you're on your own, and I wish this utility will be usefull
  331.      to you.
  332.      Please don't make lame with this utility and give us the credits we
  333.      deserve if you decide to use this program.
  334.      You can send me your demos if you're pleased with PDFM & PDFIK !!
  335.      Have a pleasant coding.
  336.  
  337.  
  338.