;*************************** AMUS Program Label ******************************
; Filename: GETFID.M68                                      Date: 12/13/92
; Category: ESP          Hash Code: 117-562-336-114      Version: 1.0(100)       
; Initials: GR/AM        Name: JAMES A. JARBOE IV
; Company: EDUCATIONAL VIDEO NETWORK, INC          Telephone #: 4092955767
; Related Files: GETFID.SCR, GETFID.BAS
; Min. Op. Sys.: 1.3D                          Expertise Level: BEG
; Special: Must have TOOLBX.SYS installed on your system
; Description: Returns an ESP screen's field's FIELD NUMBER of the requested
; field's FIELD PERMANENT NUMBER. See GETFID.BAS and GETFID.M68 for usage
; 
;*****************************************************************************
;*; Updated on 13-Dec-92 at 11:48 PM by James A. Jarboe I V; edit time: 0:47:47
;*; Created on 11-Dec-92 at 1:04 AM by James A. Jarboe I V; edit time: 1:50:11
;***************************************************************************
;*                                                                         *
;*	                        GETFID.M68                                 *
;*                                                                         *
;*		       Written By: James A. Jarboe IV                      *
;*			      1401 19th Street                             * 
;*			    Huntsville, TX 77340                           *
;*				409-295-5767                               *
;*                                                                         *
;*			    	 11-Dec-92                                 *
;*                                 GR/AM                                   *
;***************************************************************************
;*                Copyright (c) 1992 - James A. Jarboe IV                  *
;*                   Unpublished - All rights reserved.                    *
;***************************************************************************
; GET Field ID number.
;
; Description: - AlphaBASIC interface to find an ESP screen's field's
;		 FIELD NUMBER using the field's PERMANENT ID number
;		 and return the current FIELD NUMBER. (entry sequence number).
;		 Each field in an ESP screen has a PERMANENT ID number
;		 or what is called a Field ID (FL.FID). Once a field
;		 is created in ESP it will always retain this field ID
;		 number as a permanent value.  This is NOT to be confused
;		 with the FIELD NUMBER as indicated as the first field
;		 in CHANGE mode in SEDIT. The FIELD NUMBER can be
;		 set to a different value which is the Sequence number
;		 that the field accessed by. The FIELD ID (Permanent ID)
;		 is the field's permanent number. An ESP field's 
;	         Permanent ID never changes once it is created.
;
; -NOTE on PERMANENT ID #-
;  While normally an ESP screen field's permanent ID number is never changed
;  (I believe), there is an exception. Say you create an ESP screen with
;   25 fields, and then incorporate it into a program. The permanent ID
;  fields will remain the same. Edit the ESP Screen and the permanent ID
;  fields will still remain the same.  Edit the ESP screen, delete 
;  permanent field number 20 and the fields still remain the same minus
;  permanent field number 20. Edit the ESP screen add a field and the
;  new field will have a permanent field number of 26. Edit the ESP screen
;  delete permanent fields 19-26 and add a new field. The new field will
;  have a new permanent field number of 19, the next new field will have
;  a permanent field number of 20 and so on. ESP references the last 
;  largest permanent field number to offset the new permanent field number.
;                
; USAGE:
;
;	XCALL GETFID, SCREEN, PERM'FIELD, FIELD'NUM
;
; Where:
;	SCREEN 		= ESP screen to access.
;	PERM'FIELD 	= Permanent Field Number to access.
;	FIELD'NUM	= Returned value containing the Field's
;			  current FIELD NUMBER.
;
;
; Notes:
;    The purpose of this routine is to use the PERM'FIELD number as an offset
;    to always get or set the proper value for a screen field, no matter
;    what value the FIELD NUMBER is. This is so that proper values can
;    be set or get even if a user changes the FIELD NUMBER Sequence for
;    whatever reaseon. SEE GETFID.BAS for specific examples.
;    It is possible to see an ESP screen's PERMANENT FIELD NUMBER in SEDIT
;    change field mode if your USRIMP READ SECURITY LEVEL is set to 254
;    or greater. By using that number as a refererence for field 
;    manipulation with this subroutine, it is possible to let the user
;    change the FIELD NUMBER sequence and NOT have to modify the 
;    program to set or get variable information.
;
; Edit History:
;
;[100] 12-Dec-92 Correct some comments as to what happens. 
;	         No Code change.				/JAJIV
;[100] 11-Dec-92 Created by James A. Jarboe IV.     		/JAJIV
;
;	

	PAGE
;***************************************************************************
;                                                                          *
;                            S Y M B O L I C S                             *
;                                                                          *
;***************************************************************************
;
	SEARCH	SYS			; Std AM defs, etc.
	SEARCH	SYSSYM			; More Am defs, etc.
	SEARCH	TOOLBX			; Tool Box interface defs, etc.

;***************************************************************************
;                                                                          *
;                              V E R S I O N                               *
;                                                                          *
;***************************************************************************
;
	VMAJOR	=	1		; Major versoin number.
	VMINOR	=	0		; Minor version number.
	VEDIT	=	100.		; Edit level number.  11-Dec-92

	OBJNAM	0, 0, [SBR]		; Becomes xxxxxx.SBR

	S..ARG	=	3.		; Minimum argument count.

;***********
;  GETFID  *
;***********
; Returns a permanent field's field number.
;
; Incoming:
;		A3 -> Indexes Xcall variable address.
; Outgoing:
;		A3 -> Indexes Xcall variable address.
;		Z = Set if field's Permanent ID is found.
;		    Cleared if not found.
;
GETFID:	PHDR	-1, 0, PH$REE!PH$REU	; SBR is reentrant & reusable.

; Check number of arguments.
;
	MOVW	ARGCNT(A3), D7		; Get argument count.
	CMPW	D7, #S..ARG		; Right number of arguments.
	BNE	99$			; No..so quit.

; Index screen and test for reasonably sized variable.
;
	MOV	A1.ADR(A3), A1		; Index the screen buffer.
	CMP	A1.LEN(A3), #40.	; Test for reasonable screen size.
	BLO	99$			;  Unreasonably small, forget it.

; Get the PERMANENT ID number the user wants us to get the FIELD NUMBER of.
; FIELD NUMBER is returned in D1
;
	MOV	#A2.TYP, D1		; Indicate the FIELD argument.
	TOOLBX	TBX$GTARG		; Get the field number.
	BNE	99$			; Opps..field not there..quit.


; Get the field's FIELD NUMBER using the fields PERMANENT ID number.
; Use little known undocumented FNDFID Toolbox call.
;
	PUSH	A3			; Save XCALL address.
	MOV	D1, D6			; Set field to find perm id.
	TOOLBX	TBX$FNDFID,SJT,A0,PSH	; Find Field ID number.
	POP	A3			; Restore XCALL address.
	BNE	99$			; Opps..not found.
	MOV	D6, D1			; Set the Field Number.
	MOV	#A3.TYP, D6		; Get return argument type.
	TOOLBX	TBX$RTARG, SJT		; Return value to variable.
99$:	RTN				; All done.return to basic.

	END


.