Manuals >cktsim >Chapter 20: Working with Data Files
Print version of this Book (PDF file)
prevnext

CITIfile Data Format

This section describes the CITIfile format definitions of key terms, and file examples. It also includes:

  • Keyword reference

  • File guidelines

  • Instructions for converting between disk formats

  • Device-specific definitions

  • File name requirements

Overview

CITIfile is a standardized data format that is used for exchanging data between different computers and instruments. CITIfile stands for Common Instrumentation Transfer and Interchange file format.

This standard is a group effort between instrument and computer-aided design program designers. As much as possible, CITIfile meets current needs for data transfer, and it is designed to be expandable so it can meet future needs.

CITIfile defines how the data inside an ASCII package is formatted. Since it is not tied to any particular disk or transfer format, it can be used with any operating system, such as DOS or UNIX, with any disk format, such as DOS or HFS, or with any transfer mechanism, such as by disk, LAN, or GPIB.

By careful implementation of the standard, instruments and software packages using CITIfile are able to load and work with data created on another instrument or computer. It is possible, for example, for a network analyzer to directly load and display data measured on a scalar analyzer, or for a software package running on a computer to read data measured on the network analyzer.

Data Formats

There are two main types of data formats: binary and ASCII. CITIfile uses the ASCII text format. Although this format requires more space than binary format, ASCII data is a transportable, standard type of format which is supported by all operating systems. In addition, the ASCII format is accepted by most text editors. This allows files to be created, examined, and edited easily, making CITIfile easier to test and debug.

File and Operating System Formats

CITIfile is a data storage convention designed to be independent of the operating system, and therefore may be implemented by any file system. However, transfer between file systems may sometimes be necessary. You can use any software that has the ability to transfer ASCII files between systems to transfer CITIfile data. Refer to Converting Between Disk Formats for more information.

The descriptions and examples shown here demonstrate how CITIfile may be used to store and transfer both measurement information and data. The use of a single, common format allows data to be easily moved between instruments and computers.

CITIfile Definitions

This section defines: package, header, data array, and keyword.

Package

A typical CITIfile package is divided into two parts:

  • The header is made up of keywords and setup information.

  • The data usually consists of one or more arrays of data.

The following example shows the basic structure of a CITIfile package:

When stored in a file there may be more than one CITIfile package. With the Agilent 8510 network analyzer, for example, storing a memory all will save all eight of the memories held in the instrument. This results in a single file that contains eight CITIfile packages.

Header

The header section contains information about the data that will follow. It may also include information about the setup of the instrument that measured the data. The CITIfile header shown in the first example has the minimum of information necessary; no instrument setup information was included.

Data Array

An array is numeric data that is arranged with one data element per line. A CITIfile package may contain more than one array of data. Arrays of data start after the BEGIN keyword, and the END keyword follows the last data element in an array.

A CITIfile package does not necessarily need to include data arrays. For instance, CITIfile could be used to store the current state of an instrument. In that case the keywords VAR, BEGIN, and END would not be required.

Keywords

Keywords are always the first word on a new line. They are always one continuous word without embedded spaces. A listing of all the keywords used in version A.01.00 of CITIfile is shown in CITIfile Keyword Reference.

CITIfile Examples

The following are examples of CITIfile packages.

Display Memory File

This example shows an Agilent 8510 display memory file. The file contains no frequency information. Some instruments do not keep frequency information for display memory data, so this information is not included in the CITIfile package.

Note that instrument-specific information (#NA = network analyzer information) is also stored in this file.

CITIFILE A.01.00
#NA VERSION HP8510B.05.00
NAME MEMORY
#NA REGISTER 1
VAR FREQ MAG 5
DATA S RI
BEGIN
-1.31189E-3,-1.47980E-3
-3.67867E-3,-0.67782E-3
-3.43990E-3,0.58746E-3
-2.70664E-4,-9.76175E-4
0.65892E-4,-9.61571E-4
END

Agilent 8510 Data File

This example shows an 8510 data file, a package created from the data register of an Agilent 8510 network analyzer. In this case, 10 points of real and imaginary data was stored, and frequency information was recorded in a segment list table.

CITIFILE A.01.00
#NA VERSION HP8510B.05.00
NAME DATA
#NA REGISTER 1
VAR FREQ MAG 10
DATA S[1,1] RI
SEG_LIST_BEGIN
SEG 1000000000 4000000000 10
SEG_LIST_END
BEGIN
0.86303E-1,-8.98651E-1
8.97491E-1,3.06915E-1
-4.96887E-1,7.87323E-1
-5.65338E-1,-7.05291E-1
8.94287E-1,-4.25537E-1
1.77551E-1,8.96606E-1
-9.35028E-1,-1.10504E-1
3.69079E-1,-9.13787E-1
7.80120E-1,5.37841E-1
-7.78350E-1,5.72082E-1
END

Agilent 8510 3-Term Frequency List Cal Set File

This example shows an 8510 3-term frequency list cal set file. It shows how CITIfile may be used to store instrument setup information. In the case of an 8510 cal set, a limited instrument state is needed in order to return the instrument to the same state that it was in when the calibration was done.

Three arrays of error correction data are defined by using three DATA statements. Some instruments require these arrays be in the proper order, from E[1] to E[3]. In general, CITIfile implementations should strive to handle data arrays that are arranged in any order.

CITIFILE A.01.00
#NA VERSION HP8510B.05.00
NAME CAL_SET
#NA REGISTER 1
VAR FREQ MAG 4
DATA E[1] RI
DATA E[2] RI
DATA E[3] RI
#NA SWEEP_TIME 9.999987E-2
#NA POWER1 1.0E1
#NA POWER2 1.0E1
#NA PARAMS 2
#NA CAL_TYPE 3
#NA POWER_SLOPE 0.0E0
#NA SLOPE_MODE 0
#NA TRIM_SWEEP 0
#NA SWEEP_MODE 4
#NA LOWPASS_FLAG -1
#NA FREQ_INFO 1
#NA SPAN 1000000000 3000000000 4
#NA DUPLICATES 0
#NA ARB_SEG 1000000000 1000000000 1
#NA ARB_SEG 2000000000 3000000000 3
VAR_LIST_BEGIN
1000000000
2000000000
2500000000
3000000000
VAR_LIST_END
BEGIN
1.12134E-3,1.73103E-3
4.23145E-3,-5.36775E-3
-0.56815E-3,5.32650E-3
-1.85942E-3,-4.07981E-3
END
BEGIN
2.03895E-2,-0.82674E-2
-4.21371E-2,-0.24871E-2
0.21038E-2,-3.06778E-2
1.20315E-2,5.99861E-2
END
BEGIN
4.45404E-1,4.31518E-1
8.34777E-1,-1.33056E-1
-7.09137E-1,5.58410E-1
4.84252E-1,-8.07098E-1
END

When an instrument's frequency list mode is used, as it was in this example, a list of frequencies is stored in the file after the VAR_LIST_BEGIN statement. The unsorted frequency list segments used by this instrument to create the VAR_LIST_BEGIN data are defined in the #NA ARB_SEG statements.

CITIfile Keyword Reference

Table 20-1 lists keywords, definitions, and examples.
Table 20-1. CITIfile Keywords and Definitions 
Keyword
Example and Explanation
CITIFILE
Example: CITIFILE A.01.00
Identifies the file as a CITIfile and indicates the revision level of the file. The CITIFILE keyword and revision code must precede any other keywords.


The CITIFILE keyword at the beginning of the package assures the device reading the file that the data that follows is in the CITIfile format.The revision number allows for future extensions of the CITIfile standard.


The revision code shown here following the CITIFILE keyword indicates that the machine writing this file is using the A.01.00 version of CITIfile as defined here. Any future extensions of CITIfile will increment the revision code.
NAME
Example: NAME CAL_SET


Sets the current CITIfile package name. The package name should be a single word with no embedded spaces. Some standard package names:


RAW_DATA: Uncorrected data.


DATA: Data that has been error corrected. When only a single data array exists, it should be named DATA.


CAL_SET: Coefficients used for error correction.


CAL_KIT: Description of the standards used.


DELAY_TABLE: Delay coefficients for calibration.
VAR
Example: VAR FREQ MAG 201


Defines the name of the independent variable (FREQ); the format of values in a VAR_LIST_BEGIN table (MAG) if used; and the number of data points (201).
CONSTANT
Example: CONSTANTname value


Lets you record values that do not change when the independent variable changes.
#
Example: #NA POWER1 1.0E1


Lets you define variables specific to a particular type of device. The pound sign (#) tells the device reading the file that the following variable is for a particular device.
The device identifier shown here (NA) indicates that the information is for a network analyzer. This convention lets you define new devices without fear of conflict with keywords for previously defined devices. The device identifier can be any number of characters.
SEG_LIST_BEGIN
Indicates that a list of segments for the independent variable follows.


Segment Format: segment type start stop number of points


The current implementation supports only a signal segment. If you use more than one segment, use the VAR_LIST_BEGIN construct. CITIfile revision A.01.00 supports only the SEG (linear segment) segment type.
SEG_LIST_END
Sets the end of a list of independent variable segments.
VAR_LIST_BEGIN
Indicates that a list of the values for the independent variable (declared in the VAR statement) follows. Only the MAG format is supported in revision A.01.00.
VAR_LIST_END
Sets the end of a list of values for the independent variable.
DATA
Example: DATA S[1,1] RI


Defines the name of an array of data that will be read later in the current CITIfile package, and the format that the data will be in. Multiple arrays of data are supported by using standard array indexing as shown above. CITIfile revision A.01.00 supports only the RI (real and imaginary) format, and a maximum of two array indexes.


Commonly used array names include:
S                                         S parameter
E                                         Error Term
Voltage Voltage
VOLTAGE_RATIO a ratio of two voltages (A/R)

CITIfile Guidelines

The following general guidelines aid in making CITIfiles universally transportable:

Line Length.    The length of a line within a CITIfile package should not exceed 80 characters. This allows instruments which may have limited RAM to define a reasonable input buffer length.

Keywords.    Keywords are always at the beginning of a new line. The end of a line is as defined by the file system or transfer mechanism being used.

Unrecognized Keywords.    When reading a CITIfile, unrecognized keywords should be ignored. There are two reasons for this:

  • Ignoring unknown keywords allows new keywords to be added, without affecting an older program or instrument that might not use the new keywords. The older instrument or program can still use the rest of the data in the CITIfile as it did before. Ignoring unknown keywords allows "backwards compatibility" to be maintained.

  • Keywords intended for other instruments or devices can be added to the same file without affecting the reading of the data.

Adding New Devices.    Individual users are allowed to create their own device keywords through the # (user-defined device) mechanism. (Refer to CITIfile Keywords and Definitions for more information.) Individual users should not add keywords to CITIfiles without using the # notation, as this could make their files incompatible with current or future CITIfile implementations.

File Names.    Some instruments or programs identify a particular type of file by characters that are added before or after the file name. Creating a file with a particular prefix or ending is not a problem. However in general an instrument or program should not require any such characters when reading a file. This allows any file, no matter what the filename, to be read into the instrument or computer. Requiring special filename prefixes and endings makes the exchange of data between different instruments and computers much more difficult

Converting Between Disk Formats

Most current Agilent Technologies instruments use disks formatted in the Logical Interchange Format (LIF). Some instruments also use DOS-formatted disks. CITIfiles created on one file system (LIF, DOS, HFS, etc.) may be transferred to other file systems. This is useful for designers using test equipment in addition to ADS to read/write CITIfiles.

HFS

Several LIF and DOS utilities are available for HP-UX workstations. The HP-UX utilities lifcp and doscp can transfer CITIfiles to and from LIF and DOS disks. Using lifcp and doscp are similar; using lifcp is described below. Several other LIF and DOS utilities are also available. Consult the manuals for these utilities for more detailed information. Listing the contents of a LIF disk when using HP-UX would be similar to the following example:

lifls /dev/rdsk/1s0.0

The device name used will depend on how your system was configured. Copying a CITIfile named DD_FILED1 from a LIF disk to HFS would be similar to the following example:

lifcp /dev/rdsk/1s0.0:DD_FILED1 DD_FILED1

To copy a standard HFS ASCII file to a LIF disk:

lifcp DD_FILED1 /dev/rdsk/1s0.0:DD_FILED1

When used on an HFS disk, The HP-UX program RMB/UX (Rocky Mountain BASIC for HP-UX) has the ability to write a CITIfile in either as a standard HFS ASCII file, or as a LIF volume file. The LIF volume file is the default. This type of file is not directly readable when using the HP-UX operating system, and the copy commands listed above will not work correctly.

BASIC program writers are encouraged to detect when writing to an HFS disk, and to use the standard HFS format. The program examples CITIWRITE and CITIDOALL show how this can be done. However CITIfiles stored in the LIF volume format can still be transferred to LIF disks, or converted to standard HFS files. To copy a LIF volume file named DD_FILED stored on an HFS disk and move it to a LIF disk:

lifcp DD_FILED1:WS_FILE /dev/rdsk/1s0.0:DD_FILED1

To copy the LIF volume file DD_FILED1 to a standard HFS file named NEWFILE:

lifcp DD_FILED1:WS_FILE NEWFILE

DOS

Utilities are available for DOS machines that enable them to transfer files to and from a LIF formatted disk. Many of these programs are menu-driven, and are available from the following companies: HP, Oswego, Meadow Soft Works, and Innovative Software Systems.

CITIfile Device-Specific Definitions

CITIfile is a generic definition of a data storage format for any type of computer or instrument. However each type of device may need to define certain conventions for itself. This section describes the device-specific keywords and conventions for current implementations.

Network Analyzer (#NA) Definitions

Data Grouping    Data arrays of the same type, obtained during a single measurement operation, are stored in a single CITIfile package. For example, all error correction arrays are stored in the same CITIfile package, and all parameters acquired during an s-parameter measurement operation are stored in the same CITIfile package.

A CITIfile package is as described in the main CITIfile documentation: the CITIFILE keyword, followed by a header section, usually followed by one or more arrays of data.

Network Analyzer Keywords    The definition of CITIfile allows for statements that are specific to a certain type of device. Table A-2 lists the currently defined commands for the #NA (network analyzer) keyword.
Table 20-2. Network Analyzer Keyword Commands 
Statement
Explanation
#NA ARB_SEG x y p
A list segment, as entered by the user.
xx = start value
y = stop value
p = number of points.
#NA REGISTER nn
Register in instrument that the current data package was stored in.
nn = number of register.
#NA SWEEP_TIME tt
The sweep time of the analyzer.
tt = time in seconds.
#NA POWER1 pp
Power level of signal source #1.
pp = power in dBm.
#NA POWER2 pp
Power level of signal source #2.
pp = power in dBm.
#NA PARAMS aa
Bitmap of valid parameters for a calibration. Bit positions 1-8 represent the following:
Bit #1 = S11
Bit #2 = S21
Bit #3 = S12
Bit #4 = S22
Bit #5 = user1
Bit #6 = user2
Bit #7 = user3
Bit #8 = user4
A bit equal to one means that the calibration is valid for that parameter; a zero means that the calibration is not valid for that parameter. Bit #0 is the least significant bit.
NA# CAL_TYPE cc
The type of calibration used:
1 = response calibration.
2 = response and isolation calibration.
3 = one-port calibration on port 1.
4 = one-port calibration on port 2.
5 = two-port calibration (includes one-path full & TRL)
NA# POWER_SLOPE ss
Change in power versus frequency.
ss = dBm/GHz
NA# SLOPE_MODE mm
On/off flag for power slope.
mm = 0 = off
mm = 1 = on
NA# TRIM_SWEEP tt
Linearity adjustment value for swept sources.
NA# SWEEP_MODE ss
Type of sweep done to make measurement.
0 = swept
1 = stepped
2 = single-point
3 = fast CW
4 = list
NA# LOWPASS_FLAG ff
Low-pass time domain flag.
ff = 0 = low-pass time domain enabled.
ff = 1 = low-pass time domain disabled.
NA# FREQ_INFO ii
The frequency information flag.
ii = 0 = frequency information displayed on instrument screen.
ii = 1 = frequency information not displayed on instrument screen.
NA# DUPLICATES dd
Delete duplicates flag. Determines if points listed more than once should be measured more than once.
dd = 0 = points listed more than once are measured as many times as they are listed.
dd = 1 = points are measured only once.
NA# SPAN xx yy pp
The sweep parameters:
xx = start value
yy = stop value
pp = number of points
NA# IF_BW gg
The IF bandwidth setting of the receiver.
gg = IF bandwidth in Hertz.

Error Array Numbering

Current network analyzer implementations use between one and twelve error coefficient arrays in order to perform error correction. The CAL_TYPE keyword description in Network Analyzer (#NA) Definitions lists the currently defined calibration types. Table A-3 defines the meanings of each coefficient array with respect to the error model used.
Table 20-3. Network Analyzer Error Coefficient Arrays 
Error Array Name
Frequency Response
Response
& Isolation

All 1-Port
All 2-Port
E1
Er or Et
Ed or Ex
Ed
Edf
E2
Ô
Er or Et
Es
Esf
E3
Ô
Ô
Er
Erf
E4
Ô
Ô
Ô
Exf
E5
Ô
Ô
Ô
Elf
E6
Ô
Ô
Ô
Etf
E7
Ô-
Ô-
Ô
Edr
E8
Ô
Ô
Ô-
Esr
E9
Ô
Ô
Ô
Err
E10
Ô
Ô
Ô
Exr
E11


Ô
Elr
E12
Ô
Ô

Etr

Disk Filename Requirements

Some instruments or programs identify a particular type of file by characters that are added before or after the file name. In general an instrument or program should not require any such characters when reading a file.

There exist CITIfile implementations which do have file naming restrictions. This section explains how to work around these restrictions.

Agilent 8510 Series CITIfile

The 8510 checks the first 3 letters of the filename to determine what is stored in the file. The file prefixes for an 8510 CITIfile are listed in Table A-4.
Table 20-4. Agilent 8510 CITIfile Prefixes 
File Prefix
File Contents
Notes
RD_
Raw Data
Raw (uncorrected data array(s).
DD_
Data Data
Error corrected data array(s)
FD_
Formatted Data
Corrected & formatted data array.
DM_
Display Memory
File holds one memory.
MA_
Display Memory All
Holds all memories in 8510.
CS_
Cal Set
One set of calibration data.
CA
Cal Set All
All sets of calibration data.
DT_
Delay Table
One delay table.

DD_MYDATA is an example of a file name for a file that contains one array of corrected data.

The current 8510 CITIfile implementation is unable to read files unless they have the prefixes above. It is expected that a future 8510 revision will remove this restriction.

Agilent 8700 Series CITIfile

Storing a data file from an 8700-series analyzer in CITIfile format requires that you choose the SAVE USING ASCII option.

The 8700 series of instruments check the last two characters of the filename to determine what is stored in the file. The file endings for an 8700 CITIfile are listed in Table A-5.
Table 20-5. Agilent 8700 CITIfile Filenames 
Last 2 Chars
of File Name

File Contents
Notes
Rx
Raw Data
x = 1 = channel 1.
x = 5 for channel 2.
Dx
Data Data
x = channel number.
Fx
Formatted Data
x = channel number.
Mx
Display Memory
x = channel number.
xy
Cal Set
x = channel number.
y = number of error coefficient arrays in the file. y is displayed in hexadecimal.

FILE1D1 is an example of a file name for a file that contains corrected data for channel #1. FILE1R5 is a filename for raw data arrays from channel #2. MYFILE2C is an example of a name for a file that contains a cal set used by channel #2, with 12 arrays of data (hexadecimal C).

To load data from disk into an 8700-series instrument, there must be a matching instrument state file to go with the data that is being loaded. Consult the 8700-series documentation for more information.


prevnext