JHExtras.library V37.58 Copyright (c) 1993 by Jan Hagqvist COPYRIGHT Copyright (c) 1993, Jan Hagqvist, All Rights Reserved. This library is FREEWARE. You may freely use and distribute this library under the following conditions: 1) No modifications are made into the library or this documentation and all the files are spread together. However, you are allowed to compress all the files into an archive for distribution. 2) No money (other than nominal copying fees) is charged for its distribution. DISCLAIMER THIS LIBRARY IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED. THE AUTHOR WILL NOT BE LIABLE FOR ANY DAMAGES, DIRECT, INDIRECT, INCIDENTAL OR CONSEQUENTIAL, RESULTING FROM THE USE OF THE LIBRARY. THE ENTIRE RISK AS TO THE USE OF THIS LIBRARY IS ASSUMED BY THE USER. ------------------------------------------------------------------------------ jhextras.library/JHCopyString NAME JHCopyString - copy a string (V37) SYNOPSIS JHCopyString(string,dest) a0 a1 FUNCTION Simply copies a null terminated string to another memory location. This function preserves both a0 and a1. INPUTS string - string to be copied dest - destination area to hold the copy of the string ------------------------------------------------------------------------------ jhextras.library/JHCreateIORequest NAME JHCreateIORequest - create an IORequest structure (V37) SYNOPSIS ioReq=JHCreateIORequest(ioReplyPort,size) d0 a0 d0 FUNCTION Creates a new IO request block of size bytes. INPUTS ioReplyPort - Pointer to a port for replies size - the size of the IO request to be created RESULT ioReq - A pointer to the new IO request block, or NULL SEE ALSO JHDeleteIORequest, JHCreateMsgPort, exec/CreateIORequest (V36) ------------------------------------------------------------------------------ jhextras.library/JHCreateMsgPort NAME JHCreateMsgPort - Allocate and initialize a new message port (V37) SYNOPSIS msgPort=JHCreateMsgPort() d0 FUNCTION Allocates and initializes a new non-public message port. To add this port to the public port list, fill in the ln_Name and ln_Pri fields, then call exec/AddPort(). RESULT msgPort - A new msgport ready for use, or NULL if out of memory or signals. SEE ALSO JHDeleteMsgPort, exec/AddPort, exec/CreateMsgPort (V36) ------------------------------------------------------------------------------ jhextras.library/JHDeleteIORequest NAME JHDeleteIORequest - Free a IO request made by JHCreateIORequest (V37) SYNOPSIS JHDeleteIORequest(ioReq) a0 FUNCTION Frees up an IO request as allocated by JHCreateIORequest. INPUTS ioReq - A pointer to the IORequest block to be freed SEE ALSO JHCreateIORequest, exec/DeleteIORequest (V36) ------------------------------------------------------------------------------ jhextras.library/JHDeleteMsgPort NAME JHDeleteMsgPort - Free a message port created by JHCreateMsgPort (V37) SYNOPSIS JHDeleteMsgPort(msgPort) a0 FUNCTION Frees a message port created by JHCreateMsgPort. There must not be unreplied messages in the port. INPUTS msgPort - A message port. SEE ALSO JHCreateMsgPort, exec/DeleteMsgPort (V36) ------------------------------------------------------------------------------ jhextras.library/JHEasyCloseDevice NAME JHEasyCloseDevice - closes a device (V37) SYNOPSIS JHEasyCloseDevice(iorequest) a1 FUNCTION Closes a device and automatically deletes the msgport and iorequest reserved. INPUTS iorequest - the iorequest reserved by JHEasyOpenDevice SEE ALSO JHEasyOpenDevice() ------------------------------------------------------------------------------ jhextras.library/JHEasyOpenDevice NAME JHEasyOpenDevice - opens a device (V37) SYNOPSIS iorequest=JHEasyOpenDevice(name,unit,flags,reqsize) d0 a0 d0 d1 d2 FUNCTION Opens a device and automatically creates the msgport and iorequest required by the device. INPUTS name - the device name to be opened unit - the unit number of the device to be opened flags - the flags to be passed to exec/OpenDevice() reqsize - the iorequest block size RESULTS iorequest - the iorequest block used to access the device, or NULL if the device couldn't be opened SEE ALSO JHEasyCloseDevice() ------------------------------------------------------------------------------ jhextras.library/JHFormatAString NAME JHFormatAString - format data into a string (V37) SYNOPSIS JHFormatAString(formatstring,datastream,dest) a0 a1 a2 FUNCTION Perform "C"-language-like formatting of a data stream, outputting the result in to dest. Exec's RawDoFmt-routine will be used for the task. INPUTS formatstring - a "C"-language-like null terminated format string datastream - a stream of data that is interpreted according to the format string dest - the destination area where the finished string is output SEE ALSO exec.library/RawDoFmt ------------------------------------------------------------------------------ jhextras.library/JHGetMenu NAME JHGetMenu - Translate IntuiMessage Code to menu numbers (V37) SYNOPSIS JHGetMenu(code,destarea) d0 a0 FUNCTION Translates IntuiMessage Code to MenuNum, ItemNum and SubNum. The result is written to a 3-byte area of MenuNum, ItemNum and SubNum one byte at a time, so the area doesn't need to be word-aligned. Note that MenuNum, ItemNum and SubNum are all bytes, and the order between them must be preserved. INPUTS code - the code field of intuimessage received destarea - pointer to a 3-byte destarea were the menunum, subnum and itemnum are to be written ------------------------------------------------------------------------------ jhextras.library/JHGetString NAME JHGetString - get a null terminated string from user (V37) SYNOPSIS bool=JHGetString(window,title,buffer,maxchars) d0 a0 a1 a2 d0 FUNCTION Gets a null terminated string from the user using the screen's own font. The requester window will be opened in the middle of the screen and the length of the window title will determine the window width. Note that if the window width would be larger than the screen width, the window width will be truncated to the screen width. The maxchars argument will indicate the buffer length plus null. So, if you can handle 20 chars the buffer should be 21 bytes long. INPUTS window - pointer to a window whose screen will be used for the requester, or null for Workbench screen title - the window title buffer - the buffer to hold the string maxchars - the buffer length RESULTS bool - returns null if there was an error (no window etc.) ------------------------------------------------------------------------------ jhextras.library/JHLowerChar NAME JHLowerChar - Make char lowercase (V37) SYNOPSIS lowerchar=JHLowerChar(char) d0 d0 FUNCTION Returns the char in lowercase. Handles A-Z and also Å,Ä and Ö. INPUTS char - any char RESULTS lowerchar - the char in lowercase SEE ALSO JHUpperChar() ------------------------------------------------------------------------------ jhextras.library/JHLowerString NAME JHLowerString - Make string lowercase (V37) SYNOPSIS lowerstring=JHLowerString(string) d0 a0 FUNCTION Returns the string in lowercase. Handles a-z and also å,ä and ö. INPUTS string - any string RESULTS string - the string in lowercase SEE ALSO JHLowerChar(), JHUpperChar(), JHUpperString() ------------------------------------------------------------------------------ jhextras.library/JHOpen NAME JHOpen - Open a file for input or output (V37) SYNOPSIS file=JHOpen(name,accessmode,window) d0 d1 d2 a0 FUNCTION The named file is opened and a file handle returned. On V35 and earlier this function acts just as dos.library/Open(). In V36+ the following will happen: If the accessmode is MODE_NEWFILE and the file already exists, the user will be consulted whether to overwrite the old file or cancel the operation. If the accessmode is MODE_OLDFILE and the file cannot be opened, the user will be notified. INPUTS name - pointer to a null-terminated string accessmode - integer window - pointer to a window whose screen will be used for the requester, or null for Workbench screen RESULTS file - BCPL pointer to a file handle SEE ALSO dos.library/Open() ------------------------------------------------------------------------------ jhextras.library/JHReadBytes NAME JHReadBytes - Reads some bytes from a floppy disk (V37) SYNOPSIS bool=JHReadBytes(buffer,iorequest,offset,length) d0 a0 a1 d0 d1 FUNCTION Reads a defined amount of bytes from a floppy disk starting at offset and using the device specified in iorequest. The buffer is the place where the bytes are read. This function only supports normal DOS disks. INPUTS buffer - the memory where the bytes are read iorequest - an IORequest block such as returned by JHEasyOpenDevice offset - byte offset from the start of the disk where to begin the read length - the amount of bytes to be read RESULTS bool - non-NULL, if an error occurred, otherwise NULL SEE ALSO JHReadSector(), JHReadTrack(), JHStopDisk() ------------------------------------------------------------------------------ jhextras.library/JHReadSector NAME JHReadSector - Reads a sector from a floppy disk (V37) SYNOPSIS bool=JHReadSector(sectorbuffer,iorequest,sector) d0 a0 a1 d0 FUNCTION Reads a sector from a floppy disk via trackdisk.device. This function is for normal 3.5"-inch DSDD drives. The sectorbuffer is the place where the sector is read and its length must be 512 bytes. This function only supports normal DOS disks. INPUTS sectorbuffer - the data that is to be written iorequest - an IORequest block such as returned by JHEasyOpenDevice sector - the sector number to be written (0-1759) RESULTS bool - non-NULL, if an error occurred, otherwise NULL BUGS Doesn't check whether the sector number is valid (0-1759). SEE ALSO JHReadBytes(), JHReadTrack(), JHStopDisk ------------------------------------------------------------------------------ jhextras.library/JHReadTrack NAME JHReadTrack - Reads a track from a floppy disk (V37) SYNOPSIS bool=JHReadTrack(trackbuffer,iorequest,track) d0 a0 a1 d0 FUNCTION Reads a track from a floppy disk via trackdisk.device. This function is for normal 3.5"-inch DSDD drives. The trackbuffer is the place where the track is read and its length must be 5632 bytes. Each track contains 11 sectors and each sector consists of 512 bytes. Each 3.5"- inch DSDD disk contains 160 tracks. This function only supports normal DOS disks. INPUTS trackbuffer - the memory where the track is read iorequest - an IORequest block such as returned by JHEasyOpenDevice track - the track number to be read (0-159) RESULTS bool - non-NULL, if an error occurred, otherwise NULL BUGS Doesn't check whether the track number is valid (0-159). SEE ALSO JHReadBytes(), JHReadSector(), JHStopDisk() ------------------------------------------------------------------------------ jhextras.library/JHRnd NAME JHRnd - Generate a random number (V37) SYNOPSIS num=JHRnd(upperlimit) d2 d2 FUNCTION Returns a 16-bit random number between 0 and upperlimit. INPUTS upperlimit - a 16-bit integer RESULTS num - a 16-bit random integer ------------------------------------------------------------------------------ jhextras.library/JHStopDisk NAME JHStopDisk - Turns a floppy disk drive motor off (V37) SYNOPSIS JHStopDisk(iorequest) a1 FUNCTION Stops the drive motor from the drive specified in iorequest. Use this to stop the drive you read from or written to with JHReadxx/JHWritexx. INPUTS iorequest - an IORequest block such as returned by JHEasyOpenDevice ------------------------------------------------------------------------------ jhextras.library/JHStrCmp NAME JHStrCmp - Compare two null-terminated strings (V37) SYNOPSIS bool=JHStrCmp(string1,string2) d0 a0 a1 FUNCTION Compares two strings and returns 0, if the strings are not same. If the strings are exactly same, the function returns 1. Note that this function is case-sensitive. For case-insensitive operation, see JHStrCmpNoCase function. INPUTS string1 - any null terminated string string2 - any null terminated string RESULTS bool - 1 if the strings are equal, 0 otherwise SEE ALSO JHStrCmpNoCase() ------------------------------------------------------------------------------ jhextras.library/JHStrCmpNoCase NAME JHStrCmpNoCase - Compare two null-terminated strings (V37) SYNOPSIS bool=JHStrCmpNoCase(string1,string2) d0 a0 a1 FUNCTION Compares two strings and returns 0, if the strings are not same. If the strings are exactly same, the function returns 1. Note that this function is case-insensitive. For case-sensitive operation, see JHStrCmp function. INPUTS string1 - any null terminated string string2 - any null terminated string RESULTS bool - 1 if the strings are equal, 0 otherwise SEE ALSO JHStrCmp() ------------------------------------------------------------------------------ jhextras.library/JHStrInStr NAME JHStrInStr - Search string from another (V37) SYNOPSIS position=JHStrInStr(string1,string2) d0 a0 a1 FUNCTION Searches string2 from string1 and returns the position where the string2 can be found. If the string2 can't be found in the string1 -1 will be returned. Otherwise the value returned tells the position of string2 in string1 starting from 0 meaning the first position in string1. Note that this function is case-sensitive. For case- insensitive operations use JHStrInStrNoCase. INPUTS string1 - any null terminated string string2 - any null terminated string RESULTS position - the position of string2 in string1, or -1 if the string2 can't be found in the string1 SEE ALSO JHStrInStrNoCase() ------------------------------------------------------------------------------ jhextras.library/JHStrInStrNoCase NAME JHStrInStrNoCase - Search string from another (V37) SYNOPSIS position=JHStrInStrNoCase(string1,string2) d0 a0 a1 FUNCTION Searches string2 from string1 and returns the position where the string2 can be found. If the string2 can't be found in the string1 -1 will be returned. Otherwise the value returned tells the position of string2 in string1 starting from 0 meaning the first position in string1. Note that this function is case-insensitive. For case- sensitive operations use JHStrInStr. INPUTS string1 - any null terminated string string2 - any null terminated string RESULTS position - the position of string2 in string1, or -1 if the string2 can't be found in the string1 SEE ALSO JHStrInStr() ------------------------------------------------------------------------------ jhextras.library/JHStrLen NAME JHStrLen - Get the string length (V37) SYNOPSIS length=JHStrLen(string) d0 a0 FUNCTION Returns the string length. Note that the string may also be null and a0 is preserved, so after the function it still holds the string pointer. The string must be null terminated. INPUTS string - any null terminated string RESULTS length - the string length excluding the null ------------------------------------------------------------------------------ jhextras.library/JHUpperChar NAME JHUpperChar - Make char uppercase (V37) SYNOPSIS upperchar=JHUpperChar(char) d0 d0 FUNCTION Returns the char in uppercase. Handles a-z and also å,ä and ö. INPUTS char - any char RESULTS upperchar - the char in uppercase SEE ALSO JHLowerChar() ------------------------------------------------------------------------------ jhextras.library/JHUpperString NAME JHUpperString - Make string uppercase (V37) SYNOPSIS upperstring=JHUpperString(string) d0 a0 FUNCTION Returns the string in uppercase. Handles a-z and also å,ä and ö. INPUTS string - any string RESULTS string - the string in uppercase SEE ALSO JHLowerChar(), JHUpperChar(), JHLowerString() ------------------------------------------------------------------------------ jhextras.library/JHWriteBytes NAME JHWriteBytes - Writes some bytes to a floppy disk (V37) SYNOPSIS bool=JHWriteBytes(buffer,iorequest,offset,length) d0 a0 a1 d0 d1 FUNCTION Writes a defined amount of bytes to a floppy disk starting at offset and using the device specified in iorequest. The buffer is the place where the bytes are written from. This function only supports normal DOS disks. INPUTS buffer - the memory where the bytes are written from iorequest - an IORequest block such as returned by JHEasyOpenDevice offset - byte offset from the start of the disk where to begin the write length - the amount of bytes to be written RESULTS bool - non-NULL, if an error occurred, otherwise NULL SEE ALSO JHWriteSector(), JHWriteTrack(), JHStopDisk() ------------------------------------------------------------------------------ jhextras.library/JHWriteSector NAME JHWriteSector - Writes a sector to a floppy disk (V37) SYNOPSIS bool=JHWriteSector(sectorbuffer,iorequest,sector) d0 a0 a1 d0 FUNCTION Writes a sector to a floppy disk via trackdisk.device. This function is for normal 3.5"-inch DSDD drives. The sectorbuffer should contain the information to be written and its length must be 512 bytes. This function only supports normal DOS disks. INPUTS sectorbuffer - the data that is to be written iorequest - an IORequest block such as returned by JHEasyOpenDevice sector - the sector number to be written (0-1759) RESULTS bool - non-NULL, if an error occurred, otherwise NULL BUGS Doesn't check whether the sector number is valid (0-1759). SEE ALSO JHWriteBytes(), JHWriteTrack(), JHStopDisk() ------------------------------------------------------------------------------ jhextras.library/JHWriteTrack NAME JHWriteTrack - Writes a track to a floppy disk (V37) SYNOPSIS bool=JHWriteTrack(trackbuffer,iorequest,track) d0 a0 a1 d0 FUNCTION Writes a track from a floppy disk via trackdisk.device. This function is for normal 3.5"-inch DSDD drives. The trackbuffer should contain the data to be written and its length must be 5632 bytes. Each track contains 11 sectors and each sector consists of 512 bytes. Each 3.5"- inch DSDD disk contains 160 tracks. This function only supports normal DOS disks. INPUTS trackbuffer - the memory where the track is write iorequest - an IORequest block such as returned by JHEasyOpenDevice track - the track number to be written (0-159) RESULTS bool - non-NULL, if an error occurred, otherwise NULL BUGS Doesn't check whether the track number is valid (0-159). SEE ALSO JHWriteBytes(), JHWriteSector(), JHStopDisk() ------------------------------------------------------------------------------