C+
C NAME:
C	XMAP_SC_POS
C PURPOSE:
C	Calculate the 'modified Carrington variable' for a given spacecraft
C	position at a given time iYr,Doy
C CATEGORY:
C	Celestial mechanics
C CALLING SEQUENCE:
	function XMAP_SC_POS(SC_NAME, iYr, Doy, nCar, JDCar)
C INPUTS:
C	SC_NAME		real			external function; identifies spacecraft
C	iYr		integer			year
C	Doy		real			day of year, including fraction for time of day
C	nCar		integer			# Carrington start times
C						(see PROCEDURE for meaning of negative nCar)
C	JDCar(*)	double precision	Carrington start times (Julian days)
C OUTPUTS:
C	XMAP_SC_POS	real			modified Carrington variable
C CALLS:
C	Julian, BadR4, SC_NAME
C RESTRICTIONS:
C	The time iYr,Doy for which the modified Carrington variable is required
C	must be inside the time range covered by JDCar
C REMARK:
C	The Carrington rotation number in the discussion below refers to the
C	array index of JDCar. If the 'spacecraft' is EARTH this corresponds
C	to the conventional Carrington rotation number except for an offset
C	which depends on the exact call to MAP_TZERO, which calculates JDCar.
C PROCEDURE:
C >	SC_NAME must be declared EXTERNAL in the calling program
C	SC_NAME is a user-written function which calculates the heliographic
C		longitude Lng of a spacecraft for a given time iYr,Doy
C	The call to SC_NAME has the form:
C		Lng = SC_NAME(iYr,Doy)
C	where iYr (integer*4) and Doy (real*4) are input and Lng (real*4)
C	is output.
C >	DEFINITION: Carrington start time
C	Time at which the spacecraft heliographic longitude is zero.
C	A list of Carrington start times JDCar is calculated by subroutine
C	MAP_TZERO.
C >	DEFINITION: Carrington rotation N
C	The spacecraft moves across Carrington rotation N between times
C	JDCar(N) and JDCar(N+1). Between these times the spacecraft
C	heliographic longitude decreases from 360 to 0.
C >	DEFINITION: Modified Carrington variable
C	For a given time T the spacecraft position is inside Carrington
C	rotation N at heliographic location (Lng,Lat).
C	The rotation number N and the longitude Lng are combined in the
C	'modified Carrington variable' by
C		XS = N+(360.-Lng)/360.
C	i.e. the integer part of XS identifies the Carrington rotation,
C	and the fraction the heliographic longitude; as the spacecraft
C	moves across Carrington rotation N, XS increases from N to N+1.
C
C >	If the specified time lies outside the range covered by the
C	JDCar array then program execution stops if nCar is set to a
C	positive value; for negative values BadR4() is returned. 
C MODIFICATION HISTORY:
C	JAN-1991, Paul Hick (UCSD/CASS)
C	JUN-2002, Paul Hick (UCSD/CASS)
C	    Fixed bug for input times very close to the start/end of a
C	    Carrington rotation. The result sometimes would be off by +/- 1.
C	OCT-2007, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
C	    Bugfix. Changed declaration JDCar(nCar) to JDCar(*).
C	    nCar can be negative!
C-
	    real		SC_NAME
	    integer		iYr
	    real		Doy
	    integer		nCar
	    double precision	JDCar(*)

	character		cSay*11		/'XMAP_SC_POS'/
	character		cFlt2Str*14

	double precision	JD
	double precision	JEpoch

	call Julian(0,iYr,Doy,JD,JEpoch)	! Convert iYr,Doy to Julian days JD

	!-------
	! Find the array index I such that JDCar(I-1) < JD <= JDCar(I)

	if (JDCar(1) .le. JD .and. JD .le. JDCar(abs(nCar))) then
 
	    I = 1
	    do while (JDCar(I) .lt. JD)
		I = I+1
	    end do

	    !------- !!!! KLUDGE

	    ! The difference JDCar(I)-JD is always >= 0, and is related to the heliographic
	    ! longitude in [0,360]: HLng1/360 ~ (JDCar(I)-JD)/SynodicPeriod (JDCar is used
	    ! to get the synodic rotation rate; do not use SUN__SYNODICP since this only
	    ! applies to Earth and not e.g. to the Helios spacecraft).
	    ! SC_NAME gives a more accurate value for the heliographic longitude in [0,360].
	    ! The values could be inconsistent if the time iYr,Doy is very close to the
	    ! start of a rotation. The absolute difference abs(HLng1-HLng2) could be close
	    ! to 360.0, instead of 0.0. If this happens I is adjusted by +/-1.

	    HLng1 = sngl( (JDCar(I)-JD) / (JDCar(max(I,2))-JDCar(max(I-1,1))) )
	    HLng2 = SC_NAME(iYr,Doy)/360.0
	    dHLng = HLng1-HLng2			! Should be close to -1, 0 or +1

	    Ip = nint(dHLng)

	    if (Ip .ne. 0) then			! Difference dHLng close to +/- 1
		call Say(cSay,'W','Fix','inconsistency: dHLng ='//cFlt2Str(dHLng*360.0,4))
		I = I-Ip
	    end if

	    !------- !!!! END KLUDGE

	    !-------
	    ! Calculate 'modified Carrington variable' XMAP_SC_POS.

	    XMAP_SC_POS = I-HLng2

	else if (nCar .lt. 0) then

	    XMAP_SC_POS = BadR4()

	else

	    call Say(cSay,'E','Stop','input time outside range covered by JDCar array')

	end if

	return
	end