ASL & ARP FILE REQUESTERS  

			       Programming Hints


			       by George Knight


   Ed: See George's program EasyAccess this issue which makes use of both
  these requestors, as an example of what he explains in this article.


   ### 30 ### 30 ### 30 ### 30 ### 30 ### 30 ### 30 ### 30 ### 30 ### 30 ###


INTRODUCTION

   On and off over the last year or so, I have attempted to unravel the
  mysteries of the Arp file requester; at one stage, in disgust, I developed
  my own. The documentation that I found was, not unusually, written for
  those who already know how to go about it anyway.

   When I converted to WB 2, I discovered the Asl file requester, apparently
  the newly adopted Amiga standard. I had a look for docs, found a few,
  added some of my own guesses and eventually found out all about it.  Having
  done this, it wasn't difficult to work out how to include the Arp requester
  in a program.

   The amount of intelligible documentation on this topic is conspicuous
  only by its absence.  Perhaps there is some tucked away somewhere but I was
  not able to find it.  I thought it would be time well spent to document
  what I know so that others avoid the frustration I suffered.

   In what follows, I will describe what needs to be done in general terms so
  that the information is useful to all programmers, irrespective of the
  language they use.

   I will explain, firstly, how to use the Asl requester and then give the
  additional info needed to use the Arp requester.


ASL REQUESTER

   The use of this requester is appropriate for those with WB 2.0, who will
  have "asl.library" in their libs directory.

   At the beginning of your program, open the asl.library in the way that you
  open any other library, i.e., by using the Exec library function
  OpenLibrary.  When you have finished, close it.

   Before calling for a requester, call the Asl function "AllocAslRequest" to
  allocate storage and to initialise a requester structure (see below):

		requester = AllocAslRequest(type,tags);
		    d0  	  -48        d0   a0

   Set both d0 and a0 to zero, and save the contents of d0 (requester)
  because it becomes part of the "AslRequest" function call when you get
  round to the presentation of a requester to the innocent user:

		result = AslRequest(requester,tags);
		  d0       -60         a0      a1

   Put the result from the AllocAslRequest call in a0.  If you are satisfied
  with the asl default (a small requester in the top LH corner), you can
  simply zero a1.  You may opt to put in a1 a pointer to a tag structure and
  this allows you to set some of the parameters which define the requester.

   A tag structure is made up of a chain of "tags", each tag having 2 long
  words.  The first long word has a code which indicates the parameter to be
  modified and the second has the value the parameter is to take., e.g., if
  you want to change the height of the requester to say 200 pixels, you would
  set the first long word to $80080006 and the second long word to 200.
  Place a zero long word after the last tag to act as a terminator.

   Other codes that you may want to use are:-

		$80080003     LeftEdge
		$80080004     TopEdge
		$80080001     TitlePointer

   TitlePointer points to a null terminated text string to go in the title
  bar of the requester.

   The result of the AslRequest in d0 is zero if the user cancels or the
  system aborts.

   Towards the end of proceedings use:

			FreeAslRequest(requester);
			     -54	  a0

   to release the storage allocated in AllocAslRequest.

   To see what the user has done you need to look at the requester structure
  which was set up with the call to AllocAslRequest. There will be a pointer
  to the file name at +4 and a pointer to the pathname at +8. These names
  are null terminated.

   There is a bit more to it than this but, to my mind, the other options
  tend to confuse already bewildered programmers and users. C users ought to
  have a look at the Asl include file to get function and variable names
  right.


ARP REQUESTER

   The approach is similar to that with the Asl requester.  The main
  difference is that the programmer must allocate space for, and initialise
  the requester structure and provide space for the filename and pathname.
  He must also write an assembler routine if he is dissatisfied with the
  default options.

   First open the arp.library.  Remember to close it when you no longer need
  it.

   To present a requester use the arp function FileRequest:

		result = FileRequest(requester)
		 d0          -294      a0

   where a0 has a pointer to the requester structure that you provide. The
  structure looks like his:-

		arpstruct:      dc.l    hail
				dc.l    filename
				dc.l    pathname
				dc.l    0
				dc.b    8       ; or 40 for colours
				dc.b    0
				dc.l    0       ; or arpcode
				dc.l    0

   As with the Asl equivalent, d0 = 0 if the user cancels.

   "hail" is a pointer to the requester title text string (null terminated).

   "filename" and "pathname" are pointers to blocks that you must allocate
  (say 30 bytes for filename and 70 or more for pathname).

   "arpcode", if used, is a pointer to your assembler code.  When the arp
  library is about to open the requester window, it passes control to this
  routine with a0 set to the NewWindow structure used by the requester's
  window. The program must return control to asl (RTS).

   For example if you want to set LeftEdge to 170 and TopEdge to 50, you
  would have:

		arpcode:	move    #170,(a0)
				move    #50,2(a0)
				rts

   There's little else that you can do usefully.


   Hope all of this makes more sense than anything you've read on this
  subject before. If it doesn't, either I've failed miserably or there is
  something out there that I've missed!


						George Knight
						1 Audie Pde
						Berkeley Vale 2259



   ### 30 ### 30 ### 30 ### 30 ### 30 ### 30 ### 30 ### 30 ### 30 ### 30 ###