home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Media Share 9
/
MEDIASHARE_09.ISO
/
misc
/
psy_kit.zip
/
PDFM.DOC
< prev
next >
Wrap
Text File
|
1993-10-29
|
15KB
|
338 lines
╔══════════════════════════════════════════════════════════════════════════╗
║ P S Y C H O S E D A T A F I L E M A K E R ║
║ & ║
║ 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 ║
║ ║
║ for Assembly language programming ║
╟──────────────────────────────────────────────────────────────────────────╢
║ ║
║ This is the documentation file for the Psychose Datafile Maker ║
║ and for the Psychose Datafile Interface Kit ║
║ ║
║ -=≡≡≡ P D F M & P D F I K ≡≡≡=- ║
║ ║
╟──────────────────────────────────────────────────────────────────────────╢
║ (C)opyright 1993 by NAPALM from PSYCHOSE, Inc. ║
╚══════════════════════════════════════════════════════════════════════════╝
= ] ------ Table of contents ------ [ =
1. [Introduction] ........... Hey...ya! What is the PDFM ?
2. [License] ................ Yep yep ! Don't forget it dude...
3. [A matter of food] ....... How to feed this 'byte-eater' utility.
4. [Related stuff: PDFIK] ... Whoa! Cool! But what now ?
5. [PDFIK functions] ........ At last! Calling PDFIK from assembly.
5.1 What you need to include in your source code
5.2 Calling conventions
6. [To contact me] .......... BBS, Minitel and all that.
7. [Good bye user] .......... Latest information.
= ] ------------------------------- [ =
1. [Introduction]
The PSYCHOSE Datafile Maker (PDFM) is a small utility designed to help
you create special files, called datafiles, where you put all the
data (such as images, musics or texts ) you need for a demo.
The original data is compressed using a standard Lempel-Ziv algorithm
which can achieve good compression ratios, saving space (and also disks
when it's time to release your demo...).
Even if this is supposed to be a standard utility, you'll need at least
a 386 to run this program, because I used several 386 instructions
during coding. (I know what ya're goin' to tell me but forget it !!!)
2. [License]
You are free to use, distribute or copy PDFM and PDFIK, but only under
the following conditions:
■ The program using PDFM and PDFIK is not a commercial one
(Shareware is considered as commercial software)
■ You must mention in your program and/or in its documentation
you used PDFM and/or PDFIK, that is give us credits for the work
we've done!
■ PDFM and PDFIK are not modified in any way, and stay in their
original form. If you decide to copy PDFM and PDFIK to a friend
(and you are encouraged to do so...), please copy the full package
with its documentation, include and executable files.
3. [A matter of food]
You'll have to provide the PDFM with a Listfile, that is, a file
containing the name of the Datafile (were the packed data is stored)
and the names of the files you want to include in that Datafile.
The Listfile is an ASCII file organized as follows:
┌────────────┐
│DATANAME.EXT│ <───■ Datafile name (MUST be the first one...)
│FILE1.EXT │ <───■ File name n°1
│FILE2.EXT │ <───■ File name n°2
│ . │
│ . │
│ . │
│FILEn.EXT │ <───■ The last file name
│∞ │ <───■ [ALT 236] character for 'end of input'
└────────────┘
note: there must be only one name per line.
4. [Related stuff: PDFIK]
The Datafile is nice, isn't it dear ? wha ah ah ah ah! ...hum...
So now you got a Datafile ready but a simple question flashed through
your mind...: Hey Dude! How do I use the Datafile from my source code ?
Well...er... PSYCHOSE is here again to help you!
I coded a special interface called PSYCHOSE Datafile Interface Kit
(PDFIK) which implements cool functions for lazy loading of a specified
file from the Datafile (where it's stored...) into a memory buffer.
This lazy interface offers full support of 32BMM (another cool OBJ from
...? Guess who...? PSYCHOSE evidently...)
See the next section for more precise details.
5. [PDFIK functions]
Remember you must have at least a 386 to run any of these routines!
and when using .386P or .486 directives don't forget to specify
the USE16 directive in segment(s) declaration(s).
(besides the functions will not test any of these for you...)
5.1 What you need to include in your source code
just insert the following line in your code:
include PDFIK.INC
The PDFIK.INC file contains the necessary declarations and
data stuctures to communicate with the PDFIK.
Here is a copy of its contents:
EXTRN PDFIK_ASM : FAR ; Main routine (external)
PARAM_STRUC STRUC ; Structure to pass & receive parameters
Function db ? ; Function number
DtaSeg dw ? ; Segment of related datas
DtaOfsPdf dw ? ; Offset in DtaSeg of datafile name (ASCIIZ)
DtaOfsFil dw ? ; Offset in DtaSeg of file name (ASCIIZ)
OfsInPdf dd ? ; Offset from beginning of Datafile
OfsInFil dd ? ; Offset from beginning of File
NumBytes dd ? ; Number of bytes to decompress
BufSeg dw ? ; Segment of buffer where to unpack the data
BufOfs dw ? ; Offset in BufSeg
FlatMode db ? ; 0=No 32BMM, 1=32BMM use/compatible.
MemMode db ? ; Memory mode of output buffer (see 32BMM ref.)
MemHandle dw ? ; Handle of output buffer (32BMM support)
LinearOfs dd ? ; 32bit linear offset of output buffer (32BMM)
NormSize dd ? ; Size of the normal file (unpacked)
PackSize dd ? ; Size in the datafile (packed)
ErrorCode db ? ; Return code from PDFIK
PARAM_STRUC ENDS ; End of structure
I think all the fields are self-explanatory (Ok, Ok I'm the coder
so it's normal no?) except perhaps the OfsInPdf field.
This field is used when the Datafile is integrated in the EXE,
that is when you (and everyone for sure!) want the Datafile to be
part of the EXE file, so that you release only one (Big!) EXE.
This 32 bit number represents the size of the EXE just after
compile process is complete. To include the Datafile in the EXE just
type: COPY /B PROG.EXE+DATAFILE.EXT NEWPROG.EXE
and remember to use the 'NEWPROG.EXE' filename for the DtaOfsPdf
field (that is, as the Datafile name!).
coder's advice:
You don't need to set up all the fields each time you call one
function (this will lead to a real nightmare! huhu...).
In fact fill the "general purpose" fields in some initilization
routine at the beginning of yar program and then you just have to fill
3 or 4 fields at each call (unless ya wanna change some settings!).
5.2 Calling conventions
Please refer to the 32BMM reference for detailed explanations about
the fields referencing use of 32BMM.
We assume here that the 'x' label refers to a PARAM_STRUC type
structure declared and allocated in your Data Segment as follows:
x PARAM_STRUC <,,,,,,,,,>
At this moment only three functions are available. The first one is
called [GetInfo] and is used to obtain information (i.e: the size
of the original file, and its size in the Datafile) about a specified
file stored in the Datafile. The second function is [Extract] and...
huhu... is used to extract a file from the Datafile to a memory
buffer. The third one is [Extract2] and provides the laziest loading
of a file because it takes less parameters and allocates directly
the memory (which has to be de-allocated by user..).
You can call the three routines like this:
mov x.Function,(Function number)
...
<Fill all necessary fields>
...
mov ES,(Segment of x)
mov BX,(Offset of x)
call PDFIK_ASM
<Check the return code>
[GetInfo routine]
■ before call:
x.Function = 0
x.DtaSeg = Address of DATA segment (for following datas)
x.DtaOfsPdf = Offset of ASCIIZ string for Datafile name
(string example: Datafile db 'DATA1.DTA',0 )
x.DtaOfsFil = Offset of ASCIIZ string for file name
(string example: File db 'TEXT.DOC',0 )
x.OfsInPdf = Offset for beginning of Datafile in EXE
(i.e: size of the EXE file)
This value is 0 when Datafile is not integrated
in a EXE.
ES:BX = pointer to the x structure (PARAM_STRUC type)
■ after call:
x.NormSize = Size of original file (for memory allocation)
x.PackSize = Size of packed file
x.ErrorCode = return code from PDFIK
0 = OK, no problemo!
1 = Datafile not found (wrong name, ...)
2 = Invalid format (not a PSYCHOSE Datafile)
3 = File not found in Datafile (wrong name, ...)
4 = Memory allocation error (used by [Extract2])
ES:BX = pointer to the x structure (PARAM_STRUC type)
[Extract routine]
■ before call:
x.Function = 1
x.DtaSeg = Address of DATA segment (for following datas)
x.DtaOfsPdf = Offset of ASCIIZ string for Datafile name
(string example: Datafile db 'DATA1.DTA',0 )
x.DtaOfsFil = Offset of ASCIIZ string for file name
(string example: File db 'TEXT.DOC',0 )
x.OfsInPdf = Offset for beginning of Datafile in EXE
(i.e: size of the EXE file)
This value is 0 when Datafile is not integrated
in a EXE.
x.BufSeg = Segment of buffer where we unpack
(allocated by user)
x.BufOfs = Offset in BufSeg
ES:BX = pointer to the x structure (PARAM_STRUC type)
■ after call:
x.ErrorCode = return code (see GetInfo)
ES:BX = pointer to the x structure (PARAM_STRUC type)
[Extract2 routine - 32BMM compatible]
■ before call:
x.Function = 2
x.DtaSeg = Address of DATA segment (for following datas)
x.DtaOfsPdf = Offset of ASCIIZ string for Datafile name
(string example: Datafile db 'DATA1.DTA',0 )
x.DtaOfsFil = Offset of ASCIIZ string for file name
(string example: File db 'TEXT.DOC',0 )
x.OfsInPdf = Offset for beginning of Datafile in EXE
(i.e: size of the EXE file)
This value is 0 when Datafile is not integrated
in a EXE.
x.OfsInFil = Offset from which we begin to unpack
(i.e: how many bytes we jump in the original
file before unpacking)
x.NumBytes = How many bytes we unpack
(0 means unpack ALL)
x.FlatMode = 0 means standard DOS memory allocation
1 means 32BMM Flat Real Mode memory allocation
ES:BX = pointer to the x structure (PARAM_STRUC type)
■ after call:
x.ErrorCode = return code (see GetInfo)
if x.FlatMode was 1
x.LinearOfs = 32bits linear address of output buffer
x.MemMode = Memory mode of output buffer (Save it!)
x.MemHandle = Handle of output buffer (Save it!)
else
x.BufSeg = Segment of output buffer
ES:BX = pointer to the x structure (PARAM_STRUC type)
Note: this is very easy to convert a standard segment to a 32bits
linear address compatible with 32BMM. Just multiply the
segment value by 16 and you'll get it ! For example if AX
contains the segment value, ESI will contain the 32bits linear
address after the follwing lines:
movzx esi,ax
shl esi,4
...
6. [To contact me] (Hey! no illegal stuff ok?)
If you're French use your Minitel:
3615 RTEL
BAL NAPALM
(alors les p'tits gars ça flotte ? Hehe...)
For a personal contact write to:
┌───────────────────────┐
│ Rémy Chibois (NAPALM) │
└───────────┬───────────┘
┌──────────────────────────┐ │ ┌───────────────────┐
│ 1 ter Av. de l'étang │<───┴───>│ 43 rue de Chabrol │
│ 78320 Le Mesnil St Denis │ │ 75010 Paris │
│ FRANCE │ │ FRANCE │
└──────────────────────────┘ └───────────────────┘
7. [Good bye user]
I intend to improve the compression algorithm, of course, and new
functions will also be added to ensure a more flexible use.
(is that possible ? Haha..)
Well now you're on your own, and I wish this utility will be usefull
to you.
Please don't make lame with this utility and give us the credits we
deserve if you decide to use this program.
You can send me your demos if you're pleased with PDFM & PDFIK !!
Have a pleasant coding.