PTLIST

Lists point data in a dataset.

Format

PTLIST dataset [keywords]

Parameter

dataset	ADDE dataset name and position; specify one of the following formats:
		group/descriptor.position alias.position
	a position greater than zero represents an absolute position in the dataset; a position less than or equal to zero represents a relative position in the dataset based on date and time, for example, 0 is the most recent and -1 is the next most recent; the position ALL represents all positions in the dataset (no default for group/descriptor or alias; position default=ALL if DAY is specified with the SELECT keyword, otherwise default=0)

Keywords

PARam=	p1 . . pn list of parameters to plot; the list can contain native and/or computed parameters in the following formats:
		native_parameter [unit] native parameter and its output units; native parameters are those that are stored in the point file (no default for parameter; unit default=from dataset)
		'computed_parameter [unit]=expression' computed parameter, its output units, and the mathematical expression used to compute it; computed parameters do not exist in the point file but are derived with the specified mathematical expression containing math operators (+ - * etc.) and the native parameters specified in the Pn keywords, for example, PAR=ID T[F] TD[F] 'TDD[F]=P1-P2' PSL[MB]; see the Remarks and the Pn keyword description for more information (no default for parameter or expression; unit default=from dataset)
SELect=	'clause1; clause2; . . ; clausen' finds only the data matching the values in the select clauses; single quotes are mandatory; separate select clauses with semicolons; specify clause as a range or a list using one of the following formats:
		range:	parameter [unit] bval eval
		list:	parameter [unit] val1,val2, . . ,valn
		parameter	point file parameter
		[unit]	units for the parameter values; units are optional but must be in square brackets if specified; see the Remarks (default=from dataset)
		bval eval	range of parameter values; see the Remarks
		val1, . .,valn	list of parameter values

Mathematical Operations Keyword

Pn=	parameter [unit] 'clause1; clause2; . . ; clausen' native parameters to use in the math expressions specified in the PARAM keyword; use a number between 1 and 99 in the keyword name (P1,P2,..,P99); each keyword specifies a single native parameter and units to substitute in matching Pn values in the math expressions, where:
		parameter [unit] is the native parameter name and units; unit defaults to those for the parameter in the dataset; there is no default for parameter
		'clause1; clause2; ..; clausen' are the clauses used to select data for this keyword; only data matching their criteria is used; they are specified exactly as in the SELECT keyword; the Pn keywords inherit the clauses specified in the SELECT keyword, therefore, you should specify a Pn keyword clause only if a value differs from that in the SELECT keyword or you need to add additional clauses; for example, to set the values of P1 and P2 to the 850 and 1000 mb temperatures in degrees Celsius at 0 UTC, respectively, specify the following keywords: SEL='TIME 0; P 850' P1=T[C] P2=T[C] 'P 1000'

Output Keywords

BYTecount=	YES	lists the number of bytes received from the server
	NO	does not list the number of bytes (default)
FORM=	DATA	lists parameter values in the point file (default)
	FILE	bpos epos
		lists only the point file directories; all other keywords are ignored; bpos is the beginning position number or ALL; epos is the ending position number or LAST; bpos and epos override the position specified in the dataset parameter (bpos default=position specified in the dataset parameter, epos default=bpos)
		ALL	lists all point file directories
	PARAM	lists the parameter names, units and default formats in the point file; this option is useful for determining parameters valid with the SELECT and PARAM keywords
FORMAT=	f1 . . fn	output format for each parameter specified with the PARAM keyword; valid formats are A, I, F, E, DM and DMS; see the Remarks (default=from dataset)
HEAder=	'textline1' . . 'textlinen' header lines at the top of the data output; replaces the default header, which consists of a line of parameter names followed by a line of dashes
NUM=	number of records matching the criteria defined with the SELECT keyword to list; if you specify NUM=50, the first 50 records matching the SELECT keyword are listed (default=1)
	ALL	list all records matching the SELECT keyword; you may get thousands of lines of output with this option; see the Remarks
SUPpress=	s1 . . sn	suppress text from the default output; specify one or more of the following options:
		DASH	suppress the line of dashes from the header
		HEADER	suppress the entire header: parameter names and dashes
		MISS	suppress printing "missing" as a record value; applies only when the PARAM keyword is not specified
		NUMMATCH	suppress the "Number of matches found" line

Remarks

PTLIST lists data from records in one or more point data files in a dataset. The SELECT keyword defines which records to match and the PARAM keyword defines which parameters in the matching records to list. The NUM keyword defines how many matching records to list. Since each file may contain thousands of records, you may get thousands of lines of output if you specify NUM=ALL but don't narrow the search criteria enough with the SELECT keyword.

If you use the range format for the SELECT keyword and bval is less than eval, all values between and including bval and eval are selected. For example, if you specify SELECT='LON -177 177', the longitude values -177, -176, . . , 176, 177 are selected. If bval is greater than eval, all values greater than bval or less than eval, including bval and eval, are selected. For example, if you specify SELECT='LON 177 -177', the longitude values 177, 178, 179, 180, -179, -178 and -177 are selected. This feature also allows you to select only wind directions from northwest to northeast with SELECT='DIR 315 45'.

If you do not specify the PARAM keyword, PTLIST lists all the parameters in each matching record in two columns. If you use the default listing (FORM=DATA), PTLIST reorders the output so the data is listed chronologically.

Use the FORMAT keyword options below to format output based on FORTRAN designators for data output:

Designator	Description
A	character
I	integer
F	floating point
E	exponential

To specify a parameter's output format, use a designator followed by a number. For example, I4 specifies an integer of up to four digits; A4 specifies up to four characters; F10.1 specifies a floating point decimal of up to 10 digits (including the decimal point) with one digit to the right of the decimal; E10.3 specifies an exponential number of up to 10 characters (including the decimal point and the four-character exponential flag) with three digits to the right of the decimal. Specify an X to use the parameter's default format. Use a number preceding an X (e.g., 0X, 1X, 4X) to specify spaces between parameters in the output. The default is one space (1X) between each parameter. If the specified integer or floating point format is too small for the parameter's value, a series of asterisks (***) is listed.

Use the DM and DMS formats to list latitude and longitude values in degrees:minutes and degrees:minutes:seconds, respectively. The default format for latitude and longitude values is decimal (which can be altered with the F format).

When using the SELECT and PARAM keywords, use the following units:

Unit type	UNIT=	Definition
Distance	CM	centimeters
	DM	decameters
	FT	feet
	GPM	geopotential meters
	IN	inches
	KM	kilometers
	M	meters
	MI	miles
	MM	millimeters
	NMI	nautical miles
	YD	yards
Pressure	HPA	hectopascals
	INHG	inches of mercury
	MB	millibars
Speed	KT or KTS	knots
	MPH	miles per hour
	MPS	meters per second
Temperature	C	Celsius
	F	Fahrenheit
	K	Kelvin

The PARAM keyword contains the parameters to output. The list can contain native and/or computed parameters.

Native parameters are those stored in the point file. They are specified in the PARAM keyword list in the format parameter [unit], where parameter is the parameter name in the file, and [unit] is the output units, which are optional but must be in square brackets if specified.

Computed parameters do not exist in the point file but are derived with a mathematical expression. Computed parameters are specified in the PARAM keyword list in the format 'parameter [unit]=expression', where parameter is the user-defined parameter name; [unit] is the label units, which are optional but must be in square brackets if specified; and expression is the mathematical expression consisting of math operators and one or more native parameters defined in the Pn keywords.

The table below lists the math operators valid in the computed parameter expression in the PARAM keyword.

Math Operator	Function
+	addition
–	subtraction
*	multiplication
/	division
**	power
SQRT	square root
EXP	exponential (the number e raised to a power)
LOG	natural logarithm
LOG10	base 10 logarithm
SIN	sine
COS	cosine
TAN	tangent
ASIN	arcsine
ACOS	arccosine
ATAN	arctangent
ABS	absolute value
MIN	minimum of two grids
MAX	maximum of two grids

To compute a power of ten, such as 102 or 10-3 in the math expression of a computed parameter in the PARAM keyword, specify it in either the 1epower or 10**(power) format. For example, both 1e-5 and 10**(-5) represent 10-5. You must include the parenthesis with 10**(-5) for it to be interpreted correctly.

The following character limits exist for the PARAM keyword:

256 characters maximum for the entire PARAM keyword list
12 characters maximum for the computed parameter name
12 characters maximum for the computed parameter units

When using point/MD files with CYD (ccyyddd) date units (e.g., FO14, IRAB, ISEN, ISFC, ISHP, PIRP and SYN schema MD files created with McIDAS-XCD 7.5 and later), commands PTCON, PTCOPY, PTDISP and PTLIST default to the current year if you don't specify a four-digit year and the nearest century if you specify only the last two digits of the year. For example, if the file uses CYD units for the DAY parameter and its value is 2004260, then you can specify the DAY in the SELECT keyword as 2004260 or 04260. If the current year is 2004, you can also specify it as 260. Use the PTLIST command with FORM=PARAM to list the file's parameters and units.

The PTCON, PTCOPY, PTDISP and PTLIST commands continue to work with point/MD files using the old SYD (ssyyddd) date units (e.g., FO14, IRAB, ISEN, ISFC, ISHP, PIRP and SYN schema MD files created with versions of McIDAS-XCD prior to 7.5), with the following exception: If you want to specify DAY in the SELECT keyword and the ss portion of the MD file's DAY value is nonzero, then you must specify the units with DAY in the SELECT keyword. For example, if the MD file uses SYD units for DAY and its value is 7197240, then it must appear as SELECT='DAY[SYD] 7197240'. If the MD file uses SYD units for DAY but has a zero (blank) ss value, you don't have to specify the units in the SELECT keyword. For example, if the MD file uses SYD units for DAY and its value is 97240 then it can appear as either SELECT='DAY 97240' or SELECT='DAY[SYD] 97240'.

Examples

PTLIST SURFACE/ISFC FORM=FILE ALL

This entry lists the directories for all point files in dataset SURFACE/ISFC.

PTLIST SURFACE/SHIP.1 FORM=PARAM

This entry lists the names, units and default formats for all parameters in the point file in position 1 of dataset SURFACE/SHIP. Use this information to determine the valid parameters for the SELECT and PARAM keywords.

PTLIST SURFACE/ISFC

This entry lists all the parameters and their values in the first record of the most recent point file in dataset SURFACE/ISFC.

PTLIST SURFACE/ISFC SELECT='ID KSAN ; TIME 0,6,12,18' PARAM=ID ST DAY TIME HMS T TD DIR SPD WX NUM=ALL

This entry lists San Diego's 0, 6, 12 and 18 UTC data from the most recent point file in dataset SURFACE/ISFC. The station ID, state, day, time, observation time, temperature, dew point temperature, wind direction, wind speed and weather type are listed from all matching records.

PTLIST SURFACE/ISFC.5 SELECT='ID KSAN ; TIME 0,6,12,18' PARAM=ID ST DAY TIME HMS T TD DIR SPD WX1 NUM=ALL

This entry requests the same information as the previous entry, but searches for data in the point file in position 5 of dataset SURFACE/ISFC.

PTLIST SURFACE/ISFC.ALL SELECT='ID KSAN ; TIME 0,6,12,18' PARAM=ID ST DAY TIME HMS T TD DIR SPD WX1 NUM=ALL

This entry requests the same information as the previous two entries, but searches for data in all the point files in dataset SURFACE/ISFC.

PTLIST SURFACE/ISFC SELECT='ID KSAN ; TIME 0,6,12,18 ; DAY 96120 96122' PARAM=ID ST DAY TIME HMS T TD DIR SPD WX1 NUM=ALL

This entry lists San Diego's 0, 6, 12 and 18 UTC data from days 96120 through 96122; it searches for data in all the point files in the dataset SURFACE/ISFC. You do not need to specify .ALL as the dataset position because you specified DAY in the SELECT keyword.

PTLIST SURFACE/ISFC SELECT='TIME 10 13 ; CO US,CA,MX ; T[F] -100 32' PARAM=CO ID DAY HMS T[F] T[C] WX1 FORMAT=X 2X X 2X X 2X X 2X F5.1 2X F5.1 2X NUM=ALL

This entry lists data for all stations in the United States, Canada and Mexico reporting a temperature below 32 degrees Fahrenheit between 10 and 13 UTC; it searches for data in the most recent point file in dataset SURFACE/ISFC. The country, station ID, day, observation time, temperature and weather type are listed. Temperature is listed twice: in degrees Fahrenheit and Celsius. The values specified in the FORMAT keyword result in two spaces between each parameter and both temperatures being listed to the nearest tenth degree.

PTLIST RTPTSRC/SFCHOURLY SEL='DAY #Y;TIME 18;ST CA' PAR=ID T[F] TD[F] 'DEPR[F]=P1-P2' P1=T[F] P2=TD[F] FORMAT=X I4 I5 I7 NUM=ALL

This entry lists the temperature, dew point temperature, and dew point depression for stations in California at 18 UTC today. The wider I5 and I7 formats for dew point temperature and dew point depression are specified so the units (F) for those parameters appear in the header at the top of the output.

PTLIST RTPTSRC/SFCHOURLY SEL='DAY #Y;TIME 12;ST MI' PARAM=ID 'RH[%]=(EXP(5423*(1/P1-1/P2))*100)' T[K] TD[K] P2=TD[K] P1=T[K] FORMAT=X I5 F5.1 F5.1 NUM=ALL

This entry lists the relative humidity, temperature, and dew point temperature for stations in Michigan at 12 UTC today. The relative humidity is calculated using the RH equation in the PARAM keyword.