Amiga ISO Collection/AmigaUtilCD2.iso/Programming/Basic/wst!blz1.dms/in.adf/docs/ElmoreLibs.doc

Text File | 1994-09-05 | 26.3 KB | 956 lines

Library Name:
  elmoreinclib      #111  ;see other doc
  elmoredoslib      #109
  elmoresyslib      #107
  elmoremathlib     #105
  elmorehardwarelib #103
  elmorefuncslib    #101

Author:
  Richard T Elmore, HeadSoft, 126 STATE ST. #20, SPEARFISH, SD 57783, USA

OverView:
  These are the same libraries as included in BUM6, there are a lot
  of people happily using elmore's libraries, I hope they all send
  him a letter to the above adress.

Commands:

  Later Dude...

Authors Documentation:

(For the uninitiated:)


NOTE ON FUNCTIONS, STATEMENTS and COMMANDS:
-------------------------------------------

"FUNCTIONS" are Blitz2 tokens that require parameters in
parentheses, and return a value:
n=ABS(m)

"STATEMENTS" are Blitz2 tokens that only perform an action
but do not return a value.  Their arguments do not require
parentheses:
PRINT "HELLO!"

"COMMANDS" are Blitz2 tokens that can be used as either a
FUNCTION or a STATEMENT, depending upon whether the arguments
were in parentheses or not.

[Function form:]
n=REQUEST("TITLE","SELECT YES OR NO","YES|NO")

[Statement form:]
REQUEST "TITLE","SELECT OK TO CONTINUE","OK"

------------------------------------------------------------------------------




Command: CHDIR
--------------
Syntax: CHDIR "Path:"  -or-  IF CHDIR("Path:") Then...

This command will change the current working directory for ALL disk-
related commands.  Used as a function, a value of TRUE will be returned
if the directory change was successful, or FALSE if it was unsuccessful.


Function: PATHLOCK
------------------
Syntax: Lock.l=PATHLOCK

This function will return the BCPL pointer to the lock of the current
directory.  You should NEVER "Unlock_" this lock, but it is useful to
use command "NameFromLock_" with it to determine the full pathname of
the current directory, for example.  (NOTE: NameFromLock_ requires 2.0
and above!)


Command: COPYFILE
-----------------
Syntax: COPYFILE "First","SECOND"  -or-  IF COPYFILE("FIRST","SECOND") Then...

This command will copy files, much like the CLI command "Copy."  In the
function form, it will return TRUE for success, and FALSE for failure.
Note that the speed at which it copies can be increased by increasing the
"CopyBuffer," which defaults to 8192 bytes.  (See below)


Statement: SetCopyBuffer
------------------------
Syntax: SetCopyBuffer BUFFERSIZE

This statement is used to set the size of the COPYFILE command's memory
buffer.  The default size is 8192 bytes, but this can be adjusted from
256 bytes to nearly all your free memory.  A larger buffer will normally
increase the speed at which the COPYFILE command operates, but only up to
the size of the largest file you're copying.  For example, if the largest
file you need to copy is 25000 bytes, then it will be useless to set the
COPYBUFFER above 25000.


Command: NAMEFILE
-----------------
Syntax: NAMEFILE "Oldname","Newname"  -or-
        IF NAMEFILE("Oldname","Newname") Then...

This command returns FALSE for failure, TRUE for success:
The file "oldname" is renamed to "newname," if possible, and may be moved
to other directories within the same volume.  It is not yet possible to
use NAMEFILE to move a file from one volume to another, however.


Command: MAKEDIR
----------------
Syntax: NAMEFILE "Path:Dir"  -or-  If NAMEFILE("Path:Dir") Then...

This command will attempt to create a new directory with the given pathname.
It is only possible to create one level at a time, however.  For example,
MAKEDIR will fail if you attempt to MAKEDIR "RAM:New/Data" if the directory
"RAM:New" does not yet exist.  Used as a function, MAKEDIR returns TRUE for
success, and FALSE for failure.


Command: MOREENTRIES
--------------------
Syntax: MOREENTRIES  -or-  If MOREENTRIES Then...

This command will read the next entry in the current directory for
inspection with other "ENTRY" commands.  Used within a loop, it is easy
to read an entire directory with these commands, similar to the "DIR" or
"LIST" commands of AmigaDOS.  (See below.  An example follows)


Function: ENTRYNAME$
--------------------
Syntax: n$=ENTRYNAME$

This function returns the name of the current directory entry.  If used
before the fist "MOREENTRIES" command, it will return the name of the
current directory.  (Just the current directory's name, not the full
path name)


Function: ENTRYDIR
------------------
Syntax: If ENTRYDIR Then...

This function returns TRUE if the current entry is a sub-directory, or
FALSE if it is a file.


Function: ENTRYBITS$
--------------------
Syntax: n$=ENTRYBITS$

This function returns a string containing the protection-bits status of
the current file or directory.  An example may be "----RWED"  the same
format as given by the AmigaDOS "LIST" command.  Possible bit settings
are HSARWED:  H=HIDDEN, S=SCRIPT, A=ARCHIVED, R=READABLE, W=WRITEABLE,
E=EXECUTEABLE, D=DELETEABLE.
Any bits that are not set will have the "-" character in their place.


Function: ENTRYSIZE
-------------------
Syntax: n.l=ENTRYSIZE

This function returns the size in bytes of the current directory entry.
Note that sub-directories return a size of zero whether they are empty
or not.


Function: ENTRYDATE
-------------------
Syntax: d$=DATE$(ENTRYDATE)

This function returns the date the current entry was last modified, in
the same format as SYSTEMDATE uses.  (The number of days since 1/1/1978)
Thus, you may use the DATE$ and DATEFORMAT commands to translate it into
a string with a more human-readable string.


Function: ENTRYHOUR, ENTRYMINS, ENTRYSECS
-------------------
Syntax: h=ENTRYHOUR:m=ENTRYMINS:s=ENTRYSECS

ENTRYHOUR:
This function is related to ENTRYDATE, above, but returns the hour of the
day (0-23) at which the entry was last modified.

ENTRYMINS:
Returns the minute (0-59) of the time at which the entry was modified.

ENTRYSECS:
Returns the second (0-59) of the time at which the entry was modified.



Function: ENTRYCOMMENT$
-----------------------
Syntax: c$=ENTRYCOMMENT$

This function will return the string containing the filenote for the
current directory entry, or "" if there is none.



*********************
* DIRECTORY EXAMPLE *
*********************

This example will list the entries in RAM: in a format very similar
to the AmigaDOS "LIST" command.  Note that you need to "ChDir" to
a directory in order to read it from the first entry again.


ChDir "RAM:"

While MoreEntries
  Print LSet$(EntryName$,30)
  If EntryDIR then Print "Dir   " Else Print LSet$(Str$(EntrySize),6)
  Print EntryBits$," ",Date$(EntryDate)," "
  Print EntryHour,":",Right$("0"+Str$(EntryMins),2),":"
  NPrint Right$("0"+Str$(EntrySecs),2)
Wend

MouseWait




Command: ANALYZEDISK
--------------------
Syntax: ANALYZEDISK "DRIVE:"  -or-  If ANALYZEDISK "DRIVE:" Then...

This command returns FALSE if the specified device or pathname was not
valid.  If successful, details about the specified drive can be read with
the following "DISK" functions.  The values for these functions will not
change until ANALYZEDISK is executed again, either on the same drive or
another one.
Note:  If given a full pathname, such as "DF0:System/Utilities" this
command will still know enough to analyze the disk "DF0:"


Function: DISKUNIT
------------------
Syntax: n=DISKUNIT

This function will return the unit number of the most recently analyzed
disk.  DF0: for example, would return zero, while DF1: would return 1.


Function: DISKERRS
------------------
Syntax: n=DISKERRS

This function will return the number of soft errors DOS knows about on
the last analyzed disk.  This should normally be zero.



Function: DISKCAPACITY
----------------------
Syntax: n=DISKCAPACITY

This function returns the capacity in bytes of the last analyzed drive.
For example, a fastfilesystem-formatted disk's max capacity is 837K, so
DISKCAPACITY would return 857904, which divided by 1024 is 837.



Function: DISKUSED
------------------
Syntax: n=DISKUSED

This function returns the number of bytes actually in-use on the last
analyzed drive.



Function: DISKFREE
------------------
Syntax: n=DISKFREE

The opposite of DISKUSED, DISKFREE returns the number of bytes free
on the disk.  This function would be very useful, for example, in a
program that needed to save information to disk.  You would be able
to first determine if the specified SAVE disk had sufficient space.


Function: DISKBLOCKS
--------------------
Syntax: n=DISKBLOCKS

This function returns the number of bytes each block on a disk uses,
making it possible to convert the byte-values of the above functions
to number of blocks.


OverView:
  Not only has Aaron kindly fixed up passing of argumens in our
  cliargslib but has also donated this library which similar to
  the Reflective Images version allows access to information
  from the programs workbench icon.

Commands:
  GetIconInfo:  boolean.w=GetIconInfo(icon#,iconname$)
  IconTool$:    tool$=IconTool$(icon#,toolname$)
  IconSubTool$: boolean.w=IconSubTool$(toolname$,subtool$)
  IconType:     type.w=IconType(icon#)
  IconStack:    stackSize.l=IconStack(icon#)
  IconDefTool$: deftool$.w=IconDefTool$(icon#)

Authors Documentation:



  Library names: FUNCTIONS.ElmoreLib
                 HARDWARE.Elmorelib
                 MATH.ElmoreLib
                 SYS.ElmoreLib

Library Numbers: 101, 103, 105 and 107, respectively
     Written by: Richard T. Elmore
      Copyright: 1994 HeadSoft Software




******************************************************************************
***************************** HARDWARE PROGRAMMING ***************************
******************************************************************************





Statement: QUIET
****************
     Syntax: Quiet ChannelMask
      Modes: Amiga or Blitz
Description:
This command will silence the sound channels specified by ChannelMask.
See the description for "Envelope" for more information on channelmasks.


Statement: FREQ
***************
     Syntax: Freq Channelmask,period
      Modes: Amiga or Blitz
Description:
This command allows you to change the period, or pitch, of the
currently playing sound effect.  Note that the lower the period,
the higher the frequency; Thus, a period of 100 would be very
high-pitched, whereas a period of 30000 would be low-pitched.




Function: TICKS
***************
     Syntax: n=Ticks
      Modes: Amiga or Blitz
Description:
This function returns the number of "ticks" since the Amiga was switched
on, or since the last "RESETTIMER" command.  The unit of measurement is
1/60 of a second for NTSC machines, and 1/50 of a second for PAL machines.
 See Also:
 ResetTimer




Statement: RESETTIMER
*********************
     Syntax: ResetTimer
      Modes: Amiga or Blitz
Description:
Resets the Amiga's hardware timer to zero "ticks."  Read the description
for "TICKS" for more information.


Function: JOYC
**************
     Syntax: n=JoyC (Port)
      Modes: Amiga or Blitz
Description:
This function works similarly to the JoyB() function, however it allows
you to read the second fire button on two-button joysticks.  It will
return a 1 if the normal fire button is pressed, a 2 if the second button
is pressed, or 3 if both buttons are pressed.  Otherwise, it will return
a zero (no buttons pressed.)



Statement: VWAITPOS
*******************
     Syntax: VWaitPos RasterLine
      Modes: Amiga or Blitz
Description:
This command is similar to VWAIT, except it allows you to wait for
any raster position, not just the top of the display.  This is useful
for interesting graphics effects.



Function: CHECKAGA
******************
     Syntax: n=CheckAGA
      Modes: Amiga or Blitz
Description:
Returns 'TRUE' for AGA machines, otherwise returns 'FALSE.'
Using ExecVersion alone will not detect an AGA machine.  Kickstart version
39 can and does run on pre-AGA machines, such as the A3000, etc.  Therefore,
this function is provided to allow you to accurately determine if the
AGA chipset is present.




Function: PEEKTO$
*****************
     Syntax: n$=PeekTo$ (Address,byte)
      Modes: Amiga or Blitz
Description:
PeekTo$() is similar to the Peek$() function, except you can specify
what terminator byte to use.  With Peek$() the terminator will always
be zero, but PeekTo$() will accept any byte value as a terminator.



Statement: FORCEPAL
*******************
     Syntax: ForcePAL
      Modes: Amiga or Blitz
Description:
This command switches the current screen from NTSC to PAL.



Statement: FORCENTSC
********************
     Syntax: ForceNTSC
      Modes: Amiga or Blitz
Description:
This command switches the current screen from PAL to NTSC.



Function: DEPTH
***************
     Syntax: n=Depth (Bitmap#)
      Modes: Amiga or Blitz
Description:
This function returns the depth of the specified Blitz2 bitmap object.



Statement: CLICKMOUSE
*********************
     Syntax: ClickMouse
      Modes: Amiga or Blitz
Description:
Similar to Mousewait, this command halts program execution until
the user clicks the mouse.  There must must be a separate mouseclick
for each CLICKMOUSE command, unlike Mousewait, which will continue
through without pausing if the left mouse button was already being
pressed.    NOTE:  Avoid using this command in Amiga mode, as it
seriously degrades multitasking.



Function: CHIPFREE
******************
     Syntax: n=ChipFree
      Modes: Amiga or Blitz
Description:
This function will return the size, in bytes, of the largest block
of free CHIP memory in your system.
 See Also:
 FastFree
 LargestFree



Function: FASTFREE
******************
     Syntax: n=FastFree
      Modes: Amiga or Blitz
Description:
This function returns the size of the largest block of FAST memory.



Function: LARGESTFREE
*********************
     Syntax: n=LargestFree
      Modes: Amiga or Blitz
Description:
This function will return the size of the largest chunk of memory
available.  This memory may be FAST or CHIP, depending on your system.





******************************************************************************
***************************** MATH/NUMERIC FUNCTIONS *************************
******************************************************************************



Function: XOR
*************
     Syntax: n=Xor (expression,expression)
      Modes: Amiga or Blitz
Description:
Returns Exclusive OR of two expressions
This function returns the "exclusive-OR" or the two supplied arguments.
For example, Xor(255,170) will return 85, and Xor(-1) will return 0.



Function: LARGEST.L
*******************
     Syntax: n=Largest.l (Long Integer1,Long Integer2)
      Modes: Amiga or Blitz
Description:
This function will return the larger of the two supplied long integers.
For example, Largest.l(255,20045) would return 20045.


Function: SMALLEST.L
********************
     Syntax: n=Smallest.l (Long Integer1,Long Integer2)
      Modes: Amiga or Blitz
Description:
This function will return the smaller of two supplied long integers.
For example, Smallest.l(-999,5) would return -999.


Function: LARGEST.Q
*******************
     Syntax: n=Largest.q (Quick1,Quick2)
      Modes: Amiga or Blitz
Description:
Identical to the function "Largest.l" (above) except that it accepts
quick-type variables or expressions.


Function: SMALLEST.Q
********************
     Syntax: n=Smallest.q (Quick1,Quick2)
      Modes: Amiga or Blitz
Description:
Identical to "Smallest.q" but uses quick-types.


Function: LARGEST
*****************
     Syntax: n=Largest (Integer1,Integer2)
      Modes: Amiga or Blitz
Description:
This is the fastest "Largest()" function.  Note that if passed floats
or quick-types, the fraction will be cut off.  See description for
Largest.l() and Largest.q().


Function: SMALLEST
******************
     Syntax: n=Smallest (Integer1,Integer2)
      Modes: Amiga or Blitz
Description:
Like Smallest.l() and Smallest.q(), above, with less accuracy, but
faster than the long-integer and quick-type versions.



Function: AVG.L
***************
     Syntax: n=Avg.l (Long Integer 1,Long Integer 2)
      Modes: Amiga or Blitz
Description:
This function will return the average of two long-integers (although
the fraction is cut off.)  Thus, Avg.l(5,15)=10, and Avg.l(1,2)=1.
(Since fractions will be cut off with this function, you may wish to
use the quick-type version of this function for more accuracy.)


Function: AVG.Q
***************
     Syntax: n=Avg.q (Quick1,Quick2)
      Modes: Amiga or Blitz
Description:
See the description for "Avg.l()" (above)


Function: AVG
*************
     Syntax: n=Avg (Integer1,Integer2)
      Modes: Amiga or Blitz
Description:
See the description for "Avg.l()" (above)
This version is the fastest Avg() function available.



Statement: RRANDOMIZE
*********************
     Syntax: RRandomize Seed
      Modes: Amiga or Blitz
Description:
Given a float-type expression or variable, RRandomize will "seed" the
reproducible random number generator.  The sequence of pseudo-random
numbers produced by "RRND" will be the same for each seed given it.
If you require trully random numbers, try "RRandomize Ticks."


Function: RRND
**************
     Syntax: n=RRnd (Low,High)
      Modes: Amiga or Blitz
Description:
Given a range such as (1,6) this function will return a random number
based on the seed given it by "RRandomize."  These sets of "random"
numbers can be repeated if you provide the same seed.  This can be
useful in games, etc. so that using "RRandomize Level#" and then using
the RRnd() function to randomly draw the screen, each time the player
returns to that particular level, it will be the same.



*****************************************************************************
********************************* ARRAY FUNCTIONS ****************************
*****************************************************************************



Function: INDEX
***************
     Syntax: n=Index List()
      Modes: Amiga or Blitz
Description:
Returns index from top of LIST
This function will return the current index number of the supplied
List() array passed to it.  For example, if the list pointer is currently
at item 10 in the list, Index would return 10.






******************************************************************************
***************************** INTUITION PROGRAMMING **************************
******************************************************************************




Statement or Function: REQUEST
******************************
     Syntax: Request "Title","Text Line|Text Line","Gadget1|Gadget2..."
             n=Request "Title","Text Line|Text Line","Gadget1|Gadget2..."

      Modes: Amiga

***************************************************************************
*  This command is 2.0-specific.  If you're still using 1.3, this command *
*  will be unavailable to you.                                            *
***************************************************************************

Description:
"Request" can be used as both a command or a function.  You may
provide an optional title (or "" for default window title) a string
of text (separated by pipes "|" for each line) and a string containing
text for gadgets within the requester.  (Separate with "|" if you
need more than one.)
Used as a command, it merely displays the requester on the current
screen and waits for the user to click a gadget.  As a function, it
will also return a number corresponding to the gadget selected.
The gadget on the right should be reserved for negative responses
such as "CANCEL" or "NO" and will always return zero.  Other gadgets
will return values in the order that they appear, beginning with
1 for the first gadget, 2 for the next, etc.



Function: ACTIVESCREEN
**********************
     Syntax: n=ActiveScreen
      Modes: Amiga
Description:
This function returns ADDRESS of current Intuition screen.  This is
useful with many Intuition library commands, or to find out information
about the currently active screen.



Function: SCREENWIDTH
*********************
     Syntax: n=ScreenWidth
      Modes: Amiga
Description:
This function returns the pixelwidth of the currently active screen.


Function: SCREENHEIGHT
**********************
     Syntax: n=ScreenHeight
      Modes: Amiga
Description:
This function returns the pixelheight of the active screen


Function: ACTIVEWINDOW
**********************
     Syntax: n=ActiveWindow
      Modes: Amiga
Description:
This function returns the address of the current window.
This address is mainly used in conjunction with Intuition library
commands.



Statement or Function: WAITFOR
******************************
     Syntax: WaitFor IDCMP Code
             n=WaitFor (IDCMP Code)

      Modes: Amiga
Description:
Similar to WaitEvent, WAITFOR puts the Amiga to "sleep" until a specified
IDCMP code wakes it up.  For example, WaitFor $400 would wait until the
user strikes a key, and WaitFor $8 would wait until the "close" gadget
of the current window was clicked on.  These IDCMP codes are additive,
so WaitFor $408 would wait until either the "close" gadget was selected,
or a key was pressed.  Refer to the section on "windows" in the Blitz2
Reference Manual for more information on IDCMP codes.



Statement: SHOWREQUESTERS
*************************
     Syntax: ShowRequesters OPTION
      Modes: Amiga or Blitz
Description:

OPTIONS:  0=Cancel all requesters
          1=Show requesters on Workbench Screen
          2=Direct requesters to current window

This command allows you to force system requesters like "Please insert
volume Foo in any drive" etc. to either be turned off, directed to the
workbench, or directed to the current window.  When requesters are turned
off, the system will behave as if the "CANCEL" gadget was selected for
each requester that would otherwise have been displayed.  Be sure to
re-activate requesters before exiting your program!



******************************************************************************
********************************** STRING HANDLING ***************************
******************************************************************************





Function: CHECKSUM
******************
     Syntax: n=Checksum (String$)
      Modes: Amiga or Blitz
Description:
Given a string, Checksum() will return a unique 32-bit integer as
a checksum, useful in situations such as serial transfers, etc. to
ensure both parties have the same data.





Function: CHARCOUNT
*******************
     Syntax: n=CharCount (String$,byte)
      Modes: Amiga or Blitz
Description:
This function will return the number of occurances of a given byte
within a string.  For example, CharCount(text$,32) will count the
number of spaces in text$.



Function: SEARCHBEGIN
*********************
     Syntax: n=SearchBegin (String$,byte,# from Begin)
      Modes: Amiga or Blitz
Description:
Similar to Instr(), SearchBegin will search the given string
for the specified byte.  For example, SearchBegin(a$,32,1)
will return the character position of the first space in a$,
while SearchBegin(a$,32,3) will return the position of the
third space.  If the byte is not found in the string, SearchBegin
will return a zero.



Function: SEARCHEND
*******************
     Syntax: n=SearchEnd (String$,byte,# from End)
      Modes: Amiga or Blitz
Description:
Like SearchBegin() (above) except it searches from the end of
the string to the front.  For example, SearchBegin(a$,asc("A"),2)
will return the character position of the second-from-last letter
"A" in the string 'a$.'


Function: CIPHER$
*****************
     Syntax: n=Cipher$ (String$)
      Modes: Amiga or Blitz
Description:
The Cipher$() function will encrypt or decrypt a string passed to it.
This is especially handy if you don't want users "zapping" your executeable
or data files to read it's contents.  Note that Cipher$() can only
decrypt strings previously created with Cipher$().



Function: NULL
******************
     Syntax: n=Null (String$)
      Modes: Amiga or Blitz
Description:
Many Amiga shared libraries (like the DOS library) require addresses
of null-terminated strings as arguments.  This function will return
a long-integer address of a null-terminated string in memory for such
commands.



Function: REPEATS
*****************
     Syntax: n=Repeats (String$)
      Modes: Amiga or Blitz
Description:
This function will return the number of repeated bytes at the
beginning of your string.  Thus, Repeats("...Test") would return 3,
while Repeats("Example") would return 1.  If the string is null,
Repeats() will return zero.


Function: SPACE$
****************
     Syntax: n$=SPACE$ (number of spaces)
      Modes: Amiga or Blitz
Description:
This function is identical to the Space$ function in many other dialects
of BASIC.  It will return a string containing the desired number of
spaces, making it easier to align tables etc. to the screen or printer.


Function: Hex#
**************
     Syntax: n=Hex#(HexString$)
      Modes: Amiga or Blitz
Description:
This function accepts a hexadecimal value stored in a string and returns
the decimal value.



Function: Bin#
**************
     Syntax: n=Bin#(BinString$)
      Modes: Amiga or Blitz
Description:
This function accepts a binary value stored in a string and returns
the decimal value.





******************************************************************************
***************************** LIBRARY PROGRAMMING ****************************
******************************************************************************


These functions will return the base address of their respective libraries,
for advanced system programming.  Note that register A6 will also be
loaded with this address, to make programming a bit easier for assembly
routines.



Function: INTUITIONBASE
***********************
     Syntax: n=IntuitionBase
      Modes: Amiga or Blitz
Description:
Returns Intuition Library base


Function: DOSBASE
*****************
     Syntax: n=DosBase
      Modes: Amiga or Blitz
Description:
Returns DOS Library base


Function: GRAPHICSBASE
**********************
     Syntax: n=GraphicsBase
      Modes: Amiga or Blitz
Description:
Returns Graphics Library base


Function: FFPBASE
*****************
     Syntax: n=FFPBase
      Modes: Amiga or Blitz
Description:
Returns FFP Math Library base


Function: DISKFONTBASE
**********************
     Syntax: n=DiskFontBase
      Modes: Amiga or Blitz
Description:
Returns DiskFont Library base


Function: COMMODITIESBASE
*************************
     Syntax: n=CommoditiesBase
      Modes: Amiga or Blitz
Description:
Returns Commodities Library base


Function: ICONBASE
******************
     Syntax: n=IconBase
      Modes: Amiga or Blitz
Description:
Returns Icon Library base


Function: REXXSYSBASE
*********************
     Syntax: n=RexxSysBase
      Modes: Amiga or Blitz
Description:
Returns RexxSys Library base