FUNCTION deg2dec, angle, ndp, status, NO_PAR_CHECK = no_par_check
; Description: This function converts a declination angle in degrees "angle" to a string of the
; format "pDD:MM:SS.SSS" representing a declination angle in degrees (DD, "00" to
; "90"), arcminutes (MM, "00" to "59"), and arcseconds (SS.SSS, "00.000" to "59.999")
; with a precision of "ndp" decimal points on the arcseconds, where "p" is a sign "+"
; or "-". The input parameter "angle" may be a scalar, vector, or array.
;
; Input Parameters:
;
; angle - BYTE/INTEGER/LONG/FLOAT/DOUBLE SCALAR/VECTOR/ARRAY - A scalar/vector/array containing
; a set of declination angles in
; degrees.
; ndp - INTEGER/LONG - The number of decimal points to return on the arcseconds in the formatted
; declination angle string(s). If this parameter is negative or greater than
; "16", then the function will return three decimal places on the arcseconds
; in the formatted declination angle string(s).
; status - ANY - A variable which will be used to contain the output status of the function on
; returning (see output parameters below).
;
; Output Parameters:
;
; status - INTEGER - If the function successfully processed the declination angle(s), then "status"
; is returned with a value of "1", otherwise it is returned with a value of "0".
;
; Return Value:
;
; The function returns a STRING type variable, with the same dimensions as the input parameter
; "angle", where each element represents a declination angle in the format "pDD:MM:SS.SSS" and in
; the range -90 to 90 degrees. Where elements of "angle" are not valid declination angles in the
; range -90 to 90 degrees, the string 'ERROR' is returned.
;
; Keywords:
;
; If the keyword NO_PAR_CHECK is set (as "/NO_PAR_CHECK"), then the function will not perform
; parameter checking on the input parameters, reducing function overheads.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 01/01/2010 - Module created (dmb).
;Set the default output parameter values
;Perform parameter checking if not instructed otherwise
;Check that "angle" and "ndp" are of the correct number types
;If "ndp" is outside the acceptable range, then use the default value of "3" to set the format
;of the declination angle strings
;Convert the elements of "angle" to double precision numbers
;Determine which of the elements of "angle" are in the range -90 to 90 degrees
;If none of the elements of "angle" are in the range -90 to 90 degrees
;Set "status" to "1"
;Return the results of the declination angle conversion of the elements of "angle"
;If all of the elements of "angle" are in the range -90 to 90 degrees
;Determine the signs of the declination angles stored in "angle"
;Determine the number of degrees, arcminutes, and arcseconds for each declination angle
;Enforce the format "SS.SSS" for the strings representing the arcseconds for each declination
;angle
;Convert the declination angles in degrees stored in "angle" into declination strings of the
;format "pDD:MM:SS.SSS"
;If not all of the elements of "angle" are in the range -90 to 90 degrees
;Prepare the set of output angles
;Extract the elements of "angle" that are in the range -90 to 90 degrees
;Determine the signs of the declination angles stored in "angle"
;Determine the number of degrees, arcminutes, and arcseconds for each declination angle
;Enforce the format "SS.SSS" for the strings representing the arcseconds for each declination
;angle
;Convert the declination angles in degrees stored in "angle" into declination strings of the
;format "pDD:MM:SS.SSS"
;Set "status" to "1"
;Return the results of the declination angle conversion of the elements of "angle"