bpm_get_data_c

	status.i4.v = bpm_get_data_c(type.i4.v, frame.i4.v, num_frames.i4.v
				     [,horz_pos.r4a.r] [,vert_pos.r4a.r]
				     [,horz_status.i1a.r] [,vert_status.i1a.r]
				     [,timestamp.u4.r] [,file_title.i1p.r]
				     [,time_in_cycle.r4a.r] [,frames_ret.i4.r]
				     [,scale_it.i4.v] [,returned_type.i4.r]
				     [,data_view.u4.v] [,turn_numbers.i4a.r]
				     [,cycle.i4.r] [,num_timing.i4.r]
				     [,timing_params.i4a.r] [,timestamps.u4a.r]
				     [,nano_offsets.u4a.r]
				     [,readout_spec.g.v] [,attributes.u4.r]
				     [,metadata.g.v])

	This routine retrieves BPM data for the machine last requested by
	a call to bpm_machine_c.

	type		type of BPM frame
			(BPM_DISPLAY_FRAME -> display frame,
			 BPM_SNAPSHOT -> snapshot frame,
			 BPM_SLOW_SNAPSHOT -> slow snapshot frame
					      (Tevatron only),
			 BPM_PROFILE -> profile frame,
			 BPM_USER_FRAME -> user triggered closed orbit frame
					   (Tevatron only),
			 BPM_FLASH -> flash frame,
			 BPM_BACKGROUND_FLASH -> background flash frame
						 (Recycler only),
			 BPM_INJECTION_FRAME -> injection closed orbit frame
						(Tevatron only),
			 BPM_RMS_FRAME -> RMS position frame (Recycler only),
			 BPM_DFG_FRAME -> closed orbit at DFG breakpoint
					  (Booster only),
			 BPM_AVERAGED_FRAME -> averaged data frame
					       (MI-8 Line only),
			 BPM_CALIBRATION_DATA -> calibration data (Main Injector
						 and development only)
	frame		frame number (Note: If this is negative, the data
			is retrieved from a save file using the absolute
			value of this parameter as its file number.)
	num_frames	number of frames  (If a value of zero is passed
			for this argument when retrieving file data,
			all saved frames will be returned.)
	[horz_pos]	returned array of horizontal position values
			in millimeters (default is NULL)
	[vert_pos]	returned array of vertical position values
			in millimeters (default is NULL)
	[horz_status]	returned array of horizontal position detector
			status values
			(BPM_OK -> successful read,
			 BPM_INVALID ->invalid data,
			 BPM_ALARM -> reading was above alarm limit,
			 BPM_ABORT -> reading was above abort limit)
			(default is NULL)
	[vert_status]	returned array of vertical position detector
			status values (default is NULL)
			(may be same status values as for horizontal)
	[timestamp]	returned timestamp in clinks when the data was retrieved
			(default is NULL)
	[file_title]	returned pointer to null-terminated file name
			(default is NULL)
	[time_in_cycle]	returned time in seconds in the cycle that the data
			was taken (default is NULL)
	[frames_ret]	number of frames actually returned (default is NULL)
	[scale_it]	flag indicating whether or not to scale the returned
			positions to engineering units (only used for
			BPM_MAIN_INJECTOR, BPM_RECYCLER, BPM_R20_LINE, and
			BPM_R30_LINE)
			(TRUE -> scale positions (default),
			 FALSE -> return unscaled or normalized values)
	[returned_type]	type of BLM frame returned  (This is most useful
			for file data.) (default is NULL)
	[data_view]	data view requested which may result in data being
			returned for multiple machines
			(BPM_VIEW_DEFAULT -> single machine view (default),
			 BPM_VIEW_P1_ONLY -> P1 Line only (P1 Line),
			 BPM_VIEW_P1_P2 -> P1 and P2 lines (P1 Line),
			 BPM_VIEW_P1_P2_M1 -> P1, P2, and M1 lines (P1 Line),
			 BPM_VIEW_P1_P2_M1_M3 -> P1, P2, M1, amd M3 lines
						 (P1 Line),
			 BPM_VIEW_P1_P2_P3 -> P1, P2, and P3 lines (P1 Line),
			 BPM_VIEW_M1_ONLY -> M1 Line only (M1 Line),
			 BPM_VIEW_M1_M3 -> M1 and M3 lines (M1 Line))
	[turn_numbers]	returned array of turn numbers when data was taken
			(default is NULL)
	[cycle]		cycle event that data was taken on
			(default is NULL)
	[num_timing]	returned number of timing parameters (files only)
			(default is NULL)
	[timing_params]	returned timing parameters (files only)
			(default is NULL)
	[timestamps]	returned array of timestamps in clinks
			(default is NULL)
	[nano_offsets]	returned array of timestamp fractions of a second
			in nanoseconds (default is NULL)
	[readout_spec]	readout specification
			(BPM_TEVATRON -> structure of type
					 BPM_TEVATRON_READOUT_SPEC,
			 BPM_TEV_DEVL -> structure of type
					 BPM_TEVATRON_READOUT_SPEC,
			 BPM_MAIN_INJECTOR -> structure of type
					      BPM_MI_READOUT_SPEC,
			 BPM_MI_DEVL -> structure of type
					BPM_MI_READOUT_SPEC,
			 BPM_RECYCLER -> structure of type
					 BPM_RECYCLER_READOUT_SPEC,
			 BPM_RR_DEVL -> structure of type
					BPM_RECYCLER_READOUT_SPEC,
			 BPM_R20_LINE -> structure of type
					 BPM_RECYCLER_READOUT_SPEC,
			 BPM_R30_LINE -> structure of type
					 BPM_RECYCLER_READOUT_SPEC,
			 BPM_8_GEV_LINE -> structure of type
					   BPM_EIGHT_GEV_AND_MI_READOUT_SPEC)
			(default is NULL)
	[attributes]	returned data attributes
			(BPM_ATTR_CALIB_DATA -> data is calibration data)
			(default is NULL)
	[metadata]	returned metadata structure
			(BPM_TEVATRON -> structure of type
					 BPM_TEVATRON_METADATA,
			 BPM_TEV_DEVL -> structure of type
					 BPM_TEVATRON_METADATA,
			 BPM_MAIN_INJECTOR -> structure of type
					      BPM_MI_METADATA,
			 BPM_MI_DEVL -> structure of type
					BPM_MI_METADATA,
			 BPM_RECYCLER -> structure of type
					 BPM_RECYCLER_METADATA,
			 BPM_8_GEV_LINE -> structure of type
					   BPM_EIGHT_GEV_METADATA)

	This function returns ACNET status values as follows:

	OK			success
	CBS_NOTYET		data is not available for the requested frame
	CBS_INVARG		invalid number of frames requested
	CBS_INVTYP		frame(s) retrieved, but frame type differs
				from requested type
	otherwise		other ACNET error

	This function requires the following include files:

	ul_cbsaux/bpmuti.h, acnet_errors_h

	Related functions:

	bpm_machine_c, bpm_get_names, bpm_query, bpm_name_to_index_c,
	bpm_data_source_c, bpm_beam_cycle_info, blm_get_data_c,
	bpm_get_intensity_c, bpm_plot_data, bpm_save_data, bpm_set_save_file,
	bpm_get_detector_status, bpm_get_crates_and_channels

	C/C++ usage:

	char		*horz_status;
	char		*vert_status;
	char		**file_title = (char **) NULL;
	int		status;
	int		type = BPM_SNAPSHOT;
	int		frame = 0;
	int		num_frames = NUM_FRAMES;
	int		frames_ret;
	int		scale_it = TRUE;
	int		returned_type;
	int		num_horz_bpms;
	int		num_vert_bpms;
	int		ortho_plane = BPM_MODE_NORMAL;
	int		num_to_allocate;
	int		turn_numbers[NUM_FRAMES];
	int		cycle;
	int		num_timing;
	int		timing_params[BPM_MAX_TIMING_PARAMS];
	unsigned int	timestamp;
	unsigned int	data_view = BPM_VIEW_DEFAULT;
	unsigned int	timestamps[NUM_FRAMES];
	unsigned int	nano_offsets[NUM_FRAMES];
	unsigned int	attributes;
	float		*horz_pos;
	float		*vert_pos;
	float		time_in_cycle[NUM_FRAMES];
	void		*readout_spec = (void *) NULL;
	void		*metadata = (void *) NULL;

	bpm_query(&num_horz_bpms,&num_vert_bpms,ortho_plane);

	num_to_allocate = MAX(num_horz_bpms,num_vert_bpms);

	horz_status = (char *) malloc(num_to_allocate);
	vert_status = (char *) malloc(num_to_allocate);
	horz_pos = (float *) malloc(num_to_allocate*(sizeof(float)));
	vert_pos = (float *) malloc(num_to_allocate*(sizeof(float)));

	status = bpm_get_data_c(type,frame,num_frames,horz_pos,vert_pos,
				horz_status,vert_status,&timestamp,
				file_title,time_in_cycle,&frames_ret,
				scale_it,&returned_type,data_view,
				turn_numbers,&cycle,&num_timing,timing_params,
				timestamps,nano_offsets,readout_spec,
				&attributes,metadata);