home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / CRAIGS.ZIP / CRAIGS.DOC < prev    next >
Text File  |  1991-04-10  |  9KB  |  253 lines
  1.  
  2.    Ever tried to open a file with DosFileOpen and got confused about what byte or offset
  3.    to push when? Having trouble with screen handling? Ever wished you had an easier
  4.    way to work with numbers? I have an answer, CRAIGS.DLL contains some assembly
  5.    language routines to take the drudgery out of some of these tasks. The most notable
  6.    of all, the OpenFile function, makes opening a file under OS/2 as simple as passing
  7.    two zero (0) delimited strings to the function and letting it take care of the gory details
  8.    of opening the file.
  9.  
  10.    First things, first. You may feel free to use this DLL with any of your own code whether
  11.    it be for profit or not without my permission, I wrote it with the intention of making life
  12.    easier for us. However, if you should decide to use CRAIGS.DLL with a package that
  13.    you are distributing for profit please include all the files associated this .DLL so that
  14.    others may benefit from the package as well. Lastly, a donation of $5 to the address
  15.    on the last page of this file would be greatly welcomed. You don't have to make any
  16.    donation to use the .DLL, the decision is entirely up to you. I don't think $5 is too much
  17.    to ask, try opening a file with it once, you'll like how easy it is.
  18.  
  19.    Programming concerns. This .DLL was written in 100 percent Assembly, it has no
  20.    provisions as of yet for interfacing with C, it should have this capability with the next
  21.    release. Make sure you are compiling so that case is ignored, or make sure any
  22.    references made to the routines contained in the .DLL are in LOWER CASE. Declare
  23.    the routines as FAR references with an EXTRN statement. And then follow the calling
  24.    conventions laid out in this DOC file. Some of the routines make heavy use of the
  25.    stack, as many as 42 bytes in some cases, so plan accordingly.
  26.  
  27.    Link with the command;
  28.  
  29.     LINK myprog,,,craigs.lib;
  30.  
  31.    Make sure that the file CRAIGS.DLL is in a directory in your LIBPATH so that the system
  32.    can find the .DLL when it loads your program, that's all there is to it!
  33.  
  34.    What follows is an explanation of each function, you will see the function's name and
  35.    what is expected to be in the registers upon entry to each function. When references
  36.    are made to 64 bit integers, AX holds the low order word, BX holds the next and so on.
  37.    When you are asked for a pointer to a 64 bit integer, the first word pointed to should
  38.    contain the low order word and so on..
  39.  
  40.     Function name:    print_byte
  41.  
  42.         Print a byte to the display
  43.  
  44.         Input:    AL holds byte to be output
  45.         Output:    Byte is displayed
  46.  
  47.     Function name:    conv_2_asc
  48.  
  49.         Converts a 64 bit integer to an ASCIIZ string
  50.  
  51.         Input:    AX,BX,CX,DX contain 64 bit integer
  52.             DS:SI points to a buffer to receive ASCIIZ string
  53.         Output:    ASCIIZ string in buffer specified.
  54.  
  55.     Function name:    write_string
  56.  
  57.         Writes an ASCIIZ string to the display.
  58.  
  59.         Input:    DS:SI pointed at ASCIIZ string.
  60.         Output:    Screen group associated with process.
  61.  
  62.     Function name:    div_32
  63.  
  64.         Performs a 64 bit by 64 bit unsigned integer divide.
  65.  
  66.         Input:    DS:SI far pointer to 64 bit (4 word) denominator
  67.             ES:DI far pointer to 64 bit numerator.
  68.         Output:    DS:SI points to result, replaces denominator
  69.             ES:DI points to remainder, replaces numerator
  70.  
  71.     Function name:    mul_32
  72.  
  73.         64 bit by 64 bit unsigned integer multiplication
  74.  
  75.         Input:    DS:SI far pointer to 64 bit multiplicand
  76.             ES:DI far pointer to 64 bit multiplier
  77.         Output:    AX,BX,CX,DX hold product
  78.  
  79.     Function name:    asc_2_int
  80.  
  81.         Converts an ASCIIZ string to a 64 bit integer.
  82.  
  83.         Input:    DS:SI pointing to ASCIIZ string.
  84.         Output:    AX,BX,CX,DX contains 64 bit integer.
  85.  
  86.     Function name:    set_cursor
  87.  
  88.         Sets cursor position using VioSetCurPos
  89.  
  90.         Input:    AX=Row
  91.             BX=Column
  92.         Output:    Cursor set to position in AX:BX
  93.  
  94.     Function name:    get_cursor
  95.  
  96.         Gets cursor position
  97.  
  98.         Input:    None
  99.         Output:    AX=Cursor Row
  100.             BX=Cursor Col
  101.  
  102.     Function name:    beeper
  103.  
  104.         A simple little noisemaker
  105.  
  106.         Input:    none
  107.  
  108.     Function name:    readrec
  109.  
  110.         Reads specified record from a file
  111.  
  112.         Input: DS:SI far pointer to a structure
  113.         Structure is laid out like this:
  114.  
  115.                 word, file handle
  116.                 double word, record number
  117.                 word, record size/bytes read on return
  118.                 Buffer area for data to be read
  119.  
  120.         Output:    AX contains 0 if function is successful
  121.             If AX <> 0 it contains an error code
  122.  
  123.     Function name:    writerec
  124.  
  125.         Writes specified record to a file
  126.  
  127.         Input: DS:SI far pointer to a structure
  128.         Structure is laid out like this:
  129.  
  130.                 word, file handle
  131.                 double word, record number
  132.                 word, record size/bytes written on return
  133.                 Buffer area for data to be written
  134.  
  135.         Output:    AX contains 0 if function is successful
  136.             If AX <> 0 it contains an error code
  137.  
  138.     Function name:    closefile
  139.  
  140.         Closes a previously opened file
  141.  
  142.         Input:    BX should contain a valid file handle
  143.  
  144.     Function name:    openfile
  145.  
  146.         Input:    ES:DI pointer access string, DS:SI pointer filename
  147.         Output:    AX = 0 if file is opened
  148.             BX = Action taken
  149.             CX = File handle
  150.  
  151.             AX >= 0 if file open failed, value is error code
  152.             BX & CX don't care
  153.  
  154.     If ES:DI points to a null (0) byte the defaults for open are:
  155.  
  156.                 Open and retain size if file exists
  157.                 Fail Dos Open if the file does not exist
  158.                 Read only
  159.                 Deny write
  160.                 Don't let child inherit handle
  161.                 Return error codes, no pop-up
  162.                 Write through cache
  163.                 Filename is a filename
  164.  
  165.    I saved the most complicated for last, even though as bad as this seems it is
  166.    still much simpler than trying to remember what all the values are for all the
  167.    required entries for opening a file. The access string is nothing more than a
  168.    series of two character mnemonics which tells the function how to open your
  169.    file. Here's an example;
  170.  
  171.     access_string    db 'ernfardwincpcwff',0
  172.  
  173.    The mnemonics are not case sensitive, lower case or upper case is fine. There
  174.    should be no spaces in the string, unless you are creating a file and want to
  175.    pass a value for the initial file size, like so;
  176.  
  177.     access_string    db 'efncardwincpcwff 65535',0
  178.  
  179.    The mnemonics are expected to be in a certain order, which just happens to
  180.    be the order that I am going to present them to you now. Pick the one from
  181.    each group that applies to your file, but only pick ONE from each group.
  182.    If you want to select the default for a group leave its mnemonic out of the string.
  183.  
  184.     Description                    Mnemonic
  185. ------------------------------------------------------------------------------------------------------------------------
  186.    If the file exists:
  187.     Fail Dos Open                    EF    ;
  188. *    Open file and retain size            ER    ; Group #1
  189.     Open file and truncate it            ET    ;
  190.    If the file doesn't exist:
  191. *    Fail Dos Open                    NF    ;
  192.     Create File                    NC    ; Group #2
  193.    Access mode:
  194. *    Read Only                    AR    ;
  195.     Write Only                    AW    ; Group #3
  196.     Read and Write                AB    ;
  197.    Sharing mode:
  198.     Deny Read and Write                DA    ;
  199. *    Deny Write                    DW    ; Group #4
  200.     Deny Read                    DR    ;
  201.     Deny None                    DN    ;
  202.    Inheritance flag:
  203.     Let child inherit handle            IC    ;
  204. *    Don't let child inherit handle            IN    ; Group #5
  205.    Critical error handling:
  206.     Let OS/2 pop-up and handle errors        CO    ;
  207. *    Let process handle errors            CP    ; Group #6
  208.    Cache writing:
  209.     Lazy write                    CL    ;
  210. *    Always write through                CW    ; Group #7
  211.    Disk Access:
  212. *    Filename is a filename            FF    ;
  213.     Filename is a disk name            FD    ; Group #8
  214.  
  215.  * Denotes default for the group.
  216.  
  217.    I hope I made that clear enough, if not drop me a note and I'll try to clean up
  218.    the explanation a bit. Opening files under a multitasking operating system
  219.    may be a chore because of all the necessary sharing and file access information
  220.    the system needs, but no one said it had to be hard. I kind of like my solution
  221.    to the problem, I hope you do too.
  222.  
  223.    Things to come...  As I mentioned earlier, interfacing to C is a big concern of
  224.    mine, not because I am a C programmer, but simply because I think those that
  225.    do could benefit from my creations also. Other functions will be SortIndex,
  226.    LockFile and UnlockFile.
  227.  
  228.    What I am trying to create is a basic .DLL that contains all the nit-picking little
  229.    things that are a real pain to have to mess with all the time. I am certainly open
  230.    to suggestions, either drop me a note in the mail, or leave a message for me on
  231.    the OS/2 Shareware BBS. Good luck with the link library.
  232.  
  233.     My address is:
  234.  
  235.             Craig Morrison
  236.             3036 Chaffee Ct.
  237.             Lafayette, IN 47905
  238.  
  239.     For those of you who are being kind enough to donate, I cannot be
  240.     responsible for any CASH that is mailed, send either a personal
  241.     check or a money order made out to me. I will send you the source
  242.     code in return, just my way of saying thanks.
  243.  
  244.  
  245.     Legal Stuff
  246.  
  247.     I, as the author, make no claims to any warranty of any kind with regards
  248.     to the use of this Dynamic Link Library. While every effort has been made
  249.     to ensure that the code contained in the Dynamic Link Library works as
  250.     mentioned in this document, I shall not be held responsible for any
  251.     damages whether caused or alledged to be caused from the use of this
  252.     Dynamic Link Library.
  253.