Tektronix products are covered by U.S. and foreign patents, issued and pending. Information in this publication supercedes
that in all previously published material. Specifications and price change privileges reserved.
Tektronix Berlin GmbH & Co. KG
Wernerwerkdamm 5
13629 Berlin
GERMANY
TEKTRONIX and TEK are registered trademarks of Tektronix, Inc.
Microsoft, Windows and the Windows Logo are registered trademarks of the Microsoft Corporation.
With the record file API it is possible to write records in K15 format and to read
record files of the K1205, the K1103 and the K1297 Protocol Testers. You can
use this tool for analysis, statistics, filtering, converting and processing of
existing record files.
This DLL is usable under Microsoft Windows XP, Windows 2000, Windows NT,
or Windows 98 or 95. This documentation is designed for the programming
languages C and C++.
Record File API Description
1
Preface
2
Record File API Description
Installation
List of Files
The following files are part of the installation in the RecFileAPI directory:
H\K12RecFl.dll
This DLL that makes the functions for reading and writing record files
available. Place the DLL into the windows\system directory (Windows 9x) or
in the %systemroot%\system32 directory (Windows NT).
H\K12RecFl.lib
Library for VC 6.0 that automatically tries to load the DLL. You can link this
library to your project.
HLib_VC42\K12RecFl.lib
Library for VC 4.2 that automatically tries to load the DLL. You can link this
library to your project.
H\header\K12RecFl.h
How to Install
Header file that defines values needed as parameters of some DLL functions
and the structure of events. You have to include this header into your
source-code.
H\sample\ListEvt.cpp
Demo that shows how to use the DLL (lists all events of an given record
file).
1. Copy the DLL into the Windows system directory
(such as system32 for Windows XP and system32 for Windows NT
and Windows\system for Windows 98 and 95).
2. Copy the header files into your project directory or into the header directory
of your compiler.
3. If you want to use it, add the .lib file to your compiler library directory.
Record File API Description
3
Installation
Used Data Types
Default Settings
Table 1: Used data types
Data TypeLength
integer32 bit signed
long32 bit signed
unsigned long32 bit unsigned
unsigned short16 bit unsigned
unsigned char8 bit unsigned
Table 2: Parameters and default values
Limitations
ParameterPossible valuesDefault value
Swap ModeK12_REC_NO_SWAP (0)
K12_REC_AUTO_SWAP (1)
K12_REC_DO_SWAP (2)
Timestamp ModeK12_REC_DO_NOT_CALC (0)
K12_REC_DO_CALC (1)
With the record file tool it is possible to open (read open or write open) up to 100
files at the same time.
The size of one record file is limited to 2 GByte.
K12_REC_AUTO_SWAP (1)
K12_REC_DO_NOT_CALC (0)
4
Record File API Description
Event Structures
The events in a record file are always stored in a certain fixed sequence:
HThe first events in the file are the configuration events specifying the
configuration of the hardware. The first configuration event is an LDS
(logical data source) followed by one or more LL (logical link) configuration
events.
Within these configuration events, cross-references to other files (for
example stack files) may appear. The interpretation of this data depends upon
the availability of the referenced files. Subsequent changes to the referenced
files thus entails a new interpretation of the configuration events.
HAfter the configuration events, frame, signaling and information events may
follow in any arbitrary sequence. The source of frame and signaling events is
the data measured by the hardware measuring devices.
Protocol Tester applications store configurations, text events, frame events and
signaling events.
Use the Get..(..) commands to access events (see chapter Command Set, section
Reading Commands). These functions always return a pointer to an event header
(see section Event Header). From the header you can extract the event type
contained behind the structure.
The following sections describe the event types. The structures are defined in the
header file event.h.
Record File API Description
5
Event Structures
Event Header
The event header is placed at the beginning of all events (returned by the Get...()
functions). With this header it is possible to check, how long the event is and
what the event type is. The structure of the event header is shown below.
typedef struct
{
unsigned long ulLength;
unsigned short usGroup;
unsigned short usType;
} K12_REC_stEventHead_t;
ulLength (offset: 0x0)
This variable contains the total size of the event, including this header with this
size variable and the number of padding bytes.
usGroup (offset: 0x04) / usType (offset: 0x06)
The values of usGroup and usType are shown in Table 3.
6
Record File API Description
Event Structures
Table 3: Event types
usGroupusTypeName of event
K12_REC_EVENTGRP_DATA
(0x0001)
K12_REC_EVENTGRP_DATA
(0x0001)
K12_REC_EVENTTYP_FRAME
(0x0020)
K12_REC_EVENTTYP_TRANS
(0x0021)
Frame event
(normal HDLC
data)
Transparent
frame
K12_REC_EVENTGRP_DATA
(0x0001)
K12_REC_EVENTGRP_TEXTL1
(0x0002)
K12_REC_EVENTGRP_TEXTL1
(0x0002)
K12_REC_EVENTGRP_TEXTL1
(0x0002)
K12_REC_EVENTGRP_TEXTL1
(0x0002)
K12_REC_EVENTGRP_RFCONF
(0x0007)
K12_REC_EVENTGRP_RFCONF
(0x0007)
K12_REC_EVENTGRP_DATA
(0x0001)
K12_REC_EVENTTYP_BIT
(0x0022)
K12_REC_EVENTTYP_TEXT
(0x0030)
K12_REC_EVENTTYP_L1
(0x0031)
K12_REC_EVENTTYP_L1BAI
(0x0032)
K12_REC_EVENTTYP_L1VX
(0x0033)
K12_REC_EVENTTYP_LDS_CONF
(0x0040)
K12_REC_EVENTTYP_LL_CONF
(0x0041)
K12_REC_EVENTTYP_FRAG
(0x0024)
Bit data
(TRAU frame)
Text event
L1 event
L1 event (BAI)
L1 event (VX)
LDS (Logical
Data Source)
configuration
event
LL (Logical Link)
configuration
event
With Frame–,
Bit–, and Transparent–Events:
used to mark the
frame which is a
fragment ( bit 3)
Record File API Description
K12_REC_EVENTGRP_DATA
(0x0001)
K12_REC_EVENTGRP_DATA
(0x0001)
K12_REC_EVENTTYP_BITFRAG
(0x0026)
K12_REC_EVENTTYP_GEN
(0x0028)
With Frame–,
Bit–, and Transparent–Events:
used to mark the
frame which is a
fragment ( bit 3)
With Frame–,
Bit–, and Transparent–Events:
used to mark the
frame which is
generated by the
LSA (bit 4)
7
Event Structures
Table 3: Event types (Cont.)
usGroupName of eventusType
K12_REC_EVENTGRP_DATA
(0x0001)
K12_REC_EVENTTYP_BITGEN
(0x002A)
With Frame–,
Bit–, and Transparent–Events:
used to mark the
frame which is
generated by the
LSA (bit 4)
K12_REC_EVENTGRP_RFCONF
(0x0007)
K12_REC_EVENTGRP_RFCONF
(0x0007)
K12_REC_EVENTTYP_LDS_CONF
(0x0040)
K12_REC_EVENTTYP_LL_CONF
(0x0041)
Recordingfile–
Config–Events:
LDS (Logical
Data Source)
configuration
Configuration events are used to store the settings of the measurement device.
There are two types of configuration events: LDS (logical data source) configuration events and LL (logical link) configuration events.
LDS (Logical Data Source) configuration events are used to group the configuration events: A configuration always starts with an LDS followed by one or more
LL configuration events. The LDS keeps the number of LL configuration events.
It stores a unique (in the record file) ID. The ID is also part of each LL configuration event, that belongs to this LDS.
typedef struct
{
K12_REC_stEventHead_t eh;
unsigned long ulLDSId;
unsigned long ulNumberOfLLs;
char czLdsName[4];
} K12_REC_stEventLDSConfig2_t;
Record File API Description
ulLDSId (offset: 0x08)
An unique label of the LDS (logical data source) used for the measurement.
ulNumberOfLLs (offset: 0x0C)
The number of LL configuration events, which belong to this LDS.
An LL (logical link) configuration event stores the settings of a logical link that
was created by the measurement device. It contains the source of the signal
(Board, Port), the names of the links (plain text), and the decoding stack used.
typedef struct
{
K12_REC_stEventHead_t eh;
unsigned long ulLDSId;
unsigned long ulSymLLId;
unsigned long ulColor;
unsigned short usSystemId;
unsigned short usBoardType;
unsigned char ucBoardId;
unsigned char ucPortNr;
unsigned char ucPortType;
unsigned char ucLLType;
unsigned short usVarPartLen;
unsigned short usHWPartLen;
unsigned short usLLNameLen;
unsigned short usStackPathLen;
char cVarData[4];
} K12_REC_stEventLLConfig3_t;
10
ulLDSId (offset: 0x08)
ID of the corresponding LDS (logical data source).
ulSymLLId (offset: 0x0c)
Symbolic LL (Logical Link) ID: Each Logical Link that has been created has his
unique ID specifying the relationship between an LL configuration event and the
Data–Events. This ID is registered in ‘ulOrigin’ of each data event that belongs
to this LL configuration event (Frame–, Bit– and Transparent–Events).
Record File API Description
Event Structures
ulColor (offset: 0x10)
Foreground and background color of the logical link when it is displayed in the
monitor window. Bits 0–7 represent the background color, bits 8–15 the
foreground color. The values of the supported colors are shown in Table 4.
Table 4: Color values
ColorValue
blackK12_REC_COL_BLACK (0x00)
blueK12_REC_COL_BLUE (0x01)
greenK12_REC_COL_GREEN (0x02)
cyanK12_REC_COL_CYAN (0x03)
magentaK12_REC_COL_MAGENTA (0x05)
brownK12_REC_COL_BROWN (0x06)
light grayK12_REC_COL_LT_GRAY (0x07)
grayK12_REC_COL_GRAY (0x08)
light blueK12_REC_COL_LT_BLUE (0x09)
light greenK12_REC_COL_LT_GREEN (0x0A)
light cyanK12_REC_COL_LT_CYAN (0x0B)
light magentaK12_REC_COL_LT_MAGENTA (0x0D)
yellowK12_REC_COL_YELLOW (0x0E)
whiteK12_REC_COL_LT_WHITE (0x0F)
Record File API Description
usSystemId (offset: 0x14)
ID of the device responsible for the measurement (Tektronix internal use).
11
Event Structures
usBoardType (offset: 0x16)
Indicates what kind of measurement-board is related with the Logical Link
Table 5: Board values
Board typeValue
unknownK12_REC_BOARD_UNKNOWN (0x0000)
PRIMOK12_REC_BOARD_PRIMO (0x0001)
BAIK12_REC_BOARD_BAI (0x0002)
PRIMO 32K12_REC_BOARD_PRIMO_32 (0x0003)
APK12_REC_BOARD_AP (0x0004)
PRIMEK12_REC_BOARD_PRIME (0x0005)
ATMK12_REC_BOARD_ATM (0x0006)
AP4K12_REC_BOARD_AP4 (0x0007)
PCK12_REC_BOARD_PC (0x0008)
ETHERNETK12_REC_BOARD_ETHERNET (0x0009)
ATM PowerAALK12_REC_BOARD_MIDAS (0x000A)
ATM PCEK12_REC_BOARD_PCE (0x000B)
PowerWANK12_REC_BOARD_POWERWAN (0x000C)
ucBoardId (offset: 0x18)
The BoardID is the number of the measurement–board in the device. This
number is necessary because there can be more than one measurement board in
the device. It is used to identify from which board the data came.
ucPortNr (offset: 0x19)
The number of the port on the measurement board the data came from.
Port A = 0,
Port B = 1,
...
12
Record File API Description
ucPortType (offset: 0x1a)
Describes the kind of port the data came from.
Table 6: Port type value
Port typeValue
unknownK12_REC_PORT_UNKNOWN (0x00)
PRIMOK12_REC_PORT_PRIMO (0x01)
S0K12_REC_PORT_S0 (0x02)
U2B1QK12_REC_PORT_U2B1Q (0x03)
OfflineK12_REC_PORT_OFFLINE (0x04)
E1K12_REC_PORT_E1 (0x05)
T1K12_REC_PORT_T1 (0x06)
ATM E1/T1K12_REC_PORT_ATME1T1 (0x07)
ATM E3/T3K12_REC_PORT_ATME3T3 (0x08)
ATM STM1EK12_REC_PORT_ATMSTM1E (0x09)
ATM STM1OK12_REC_PORT_ATMSTM1O ( 0x0A)
ATM STM4K12_REC_PORT_ATMSTM4 (0x0B)
ATM IBM25K12_REC_PORT_ATMIBM25 (0x0C)
VXK12_REC_PORT_VX (0x0D)
PRIMO2K12_REC_PORT_PRIMO2 (0x0E)
DS0K12_REC_PORT_DS0 (0x0F)
PRIMO_NEWK12_REC_PORT_PRIMO_NEW (0x10)
ETHERNETK12_REC_PORT_ETHERNET (0x11)
ABK12_REC_PORT_AB (0x12)
AB_NETK12_REC_PORT_AB_NET (0x13)
PCE: ATM2_E1DS1K12_REC_PORT_ATM2_E1DS1 (0x14)
PCE: ATM2_E3DS3K12_REC_PORT_ATM2_E3DS3 (0x15)
PCE: ATM2_STM1ELK12_REC_PORT_ATM2_STM1EL (0x16)
PCE: ATM2_STM1OPK12_REC_PORT_ATM2_STM1OP (0x17)
POWERWANK12_REC_PORT_POWERWAN (0x18)
Event Structures
Record File API Description
ucLLType (offset: 0x1b)
This shows the mode, in which the Logical Link works.
usVarPartLen (offset: 0x1c)
13
Event Structures
The length of the variable part of an LL configuration event. The beginning of
the variable part is cVarData[0], the end is cVarData[usVarPartLen – 5].
14
Record File API Description
Event Structures
usHWPartLen (offset: 0x1e)
The hardware parameters are a content of the variable part of an LL configuration event. The beginning of the hardware part is cVarData[0], the end is
cVarData[usHWPartLen – 1]. The hardware part must end with \0.
usLLNameLen (offset: 0x20)
The LL name is the string that is displayed in the monitor window. It is just as
the hardware parameter part of the variable part of the LL configuration event.
The beginning of the LL name is cVarData[usHWPartLen], the end is cVarData[usHWPartLen + usLLNameLen – 1]. LL name must end with \0.
usStackPathLen (offset: 0x22)
The stack path is a string that gives the name of the stack with which the
recording should be decoded. It is also a content of the variable part of the LL
configuration event. The beginning of the stack path is
cVarData[usHWPartLen + usLLNameLen].
The end is cVarData[usHWPartLen + usLLNameLen + usStackPathLen – 1]. The
stack path must end with \0.
cVarData[4] (offset: 0x24)
Stores four bytes of the variable part of the LL configuration event.
Record File API Description
15
Event Structures
Data Events
Frame Events
Group 0x001 / Type 0x0020 (frame data)
Group 0x001 / Type 0x0024 (fragmented frame data)
Group 0x001 / Type 0x0028 (frame data generated by the LSA)
This event stores data frames that were measured by the hardware, for example
by a E1/DS-1 board.
typedef struct
{
K12_REC_stEventHead_t eh;
unsigned long ulFrameLength;
unsigned long ulOrigin;
unsigned long ulStatus;
unsigned long ulFrameId;
unsigned long ulTimestampHigh;
unsigned long ulTimestampLow;
unsigned char ucData[4];
} K12_REC_stEventFrame_t;
ulFrameLength (offset: 0x08)
Frame (data) length in bytes.
The frame dData is stored in the data[4] field in the structure. The data begins at
data[0] and ends at data[ulFrameLength - 1].
ulOrigin (offset: 0x0c)
The ID of the logical link the data came from. See section LL configuration
events.
This event stores messages that were created by Protocol Tester applications.
Text events are used for information within the record file. For example: When a
recording is started, a text–event is created to indicate the start time.
Layer 1 events are used to give a status of the physical layer of the protocol.
They are generated by the measuring hardware whenever error conditions are
met.
Special CEPT error generatedK12_REC_L1ERR_CEPT_GEN (114)
ulEventValue (offset: 0x0c)
Tektronix internal use.
ulErrorCount (offset: 0x10)
Tektronix internal use.
ulFrameId (offset: 0x14)
The unique number of this frame.
ulTimestampHigh (offset: 0x18)
Bits 32–64 of the timestamp.
ulTimestampLow (offset: 0x1c)
Bits 0–31 of the timestamp.
usSystemId (offset: 0x20)
ID of the device responsible for the measurement: Tektronix internal use.
24
Record File API Description
Event Structures
usBoardType (offset: 0x22)
Indicates what kind of measurement board is related to the logical link.
See table 8.
Table 8: Board type value
Board typeValue
unknownK12_REC_BOARD_UNKNOWN (0x0000)
PRIMOK12_REC_BOARD_PRIMO (0x0001)
BAIK12_REC_BOARD_BAI (0x0002)
PRIMO 32K12_REC_BOARD_PRIMO_32 (0x0003)
APK12_REC_BOARD_AP (0x0004)
PRIMEK12_REC_BOARD_PRIME (0x0005)
ATMK12_REC_BOARD_ATM (0x0006)
AP4K12_REC_BOARD_AP4 (0x0007)
PCK12_REC_BOARD_PC (0x0008)
ETHERNETK12_REC_BOARD_ETHERNET (0x0009)
ATM PowerAALK12_REC_BOARD_MIDAS (0x000A)
ATM PCEK12_REC_BOARD_PCE (0x000B)
PowerWANK12_REC_BOARD_POWERWAN (0x000C)
ucBoardId (offset: 0x24)
The Board ID is the number of the measurement board in the device. This
number is necessary because there can be more than one measurement board in
the device. It is used to identify the board from which the data came.
ucPortNr (offset: 0x25)
The number of the port on the measurement board, the data came from.
Port A = 0,
Port B = 1
...
Record File API Description
25
Event Structures
ucPortType (offset: 0x26)
The kind of port the data came from. See Table 9.
Table 9: Port type value
Port typeValue
unknownK12_REC_PORT_UNKNOWN (0x00)
PRIMOK12_REC_PORT_PRIMO (0x01)
S0K12_REC_PORT_S0 (0x02)
U2B1QK12_REC_PORT_U2B1Q (0x03)
OfflineK12_REC_PORT_OFFLINE (0x04)
E1K12_REC_PORT_E1 (0x05)
T1K12_REC_PORT_T1 (0x06)
ATM E1/T1K12_REC_PORT_ATME1T1 (0x07)
ATM E3/T3K12_REC_PORT_ATME3T3 (0x08)
ATM STM1EK12_REC_PORT_ATMSTM1E (0x09)
ATM STM1OK12_REC_PORT_ATMSTM1O ( 0x0A)
ATM STM4K12_REC_PORT_ATMSTM4 (0x0B)
ATM IBM25K12_REC_PORT_ATMIBM25 (0x0C)
VXK12_REC_PORT_VX (0x0D)
PRIMO2K12_REC_PORT_PRIMO2 (0x0E)
DS0K12_REC_PORT_DS0 (0x0F)
PRIMO_NEWK12_REC_PORT_PRIMO_NEW (0x10)
ETHERNETK12_REC_PORT_ETHERNET (0x11)
ABK12_REC_PORT_AB (0x12)
AB_NETK12_REC_PORT_AB_NET (0x13)
PCE: ATM2_E1DS1K12_REC_PORT_ATM2_E1DS1 (0x14)
PCE: ATM2_E3DS3K12_REC_PORT_ATM2_E3DS3 (0x15)
PCE: ATM2_STM1ELK12_REC_PORT_ATM2_STM1EL (0x16)
PCE: ATM2_STM1OPK12_REC_PORT_ATM2_STM1OP (0x17)
POWERWANK12_REC_PORT_POWERWAN (0x18)
26
ucDummy (offset: 0x27)
Dummy field for alignment.
Record File API Description
Event Trailer
Event Structures
Note. Existing trailer structures are modified and new trailers are added on short term
notice. Whilst the information is prepared in good faith, no warranty is given as to its
accuracy or completeness. Tektronix reserves the right to change the contents of this
document in any way for any reason and at any time.
The Event Trailer may exist in events of type K12_REC_stEventFrame_t and
contains specific data, for example from ATM connections or Frame Processing
Methods (FPM). This data is appended directly to the event frame data and is
part of the Event data.
The existence of an Event Trailer and its length can be calculated using the two
length values ulLength in structure
in structure
Each Event Trailer consists of a common and specific trailer section.
The offset used in the following sections refer to the beginning of the Event
Trailer and not to the Event.
Trailers have a minimum length of 8 bytes. A calculated TrailerLen of less then 8
Note.
can be ignored.
Some trailers are aligned and some are not aligned. Not aligned trailers begin direct after
frame data. Aligned trailers begin on a long-aligned address (address can be divided by
4). There may be 1 to 3 bytes unused data between frame data and trailer.
Record File API Description
27
Event Structures
Common Section
unsigned short usTrailerType (offset 0x0)
This value defines the FPM Trailer type:
0x10 UMTS FP Iub/Iur data frame (not handled by reassembler)
0x11 UMTS FP Iub/Iur control frame
0x30 UMTS FP Iub/Iur data frame (handled by reassembler)
0x50 UMTS FP Iu UP data frame
0x80 ATM connection data
UMTS FP Iub/Iur reasembled data frame (creator: reassembler/LSA, first
0x91
version)
UMTS FP Iub/Iur reasembled data frame (creator: reassembler/LSA)
0x92
unsigned short usVersion (offset 0x2)
Each type of trailer (see above) may have its own version control.
For example, for UMTS FP Iub/Iur the following usVersion values are used:
0K1297-G20 V2.01
1K1297-G20 V2.01.04 (Patch)
2K1297-G20 V2.40
3K1297-G20 V2.50
Note. The ATM connection data (usTrailerType 0x80) has only one version, that
is 1.
unsigned long ulLength (offset 0x4)
The length of the Event Trailer (supported since usVersion 1)
28
Record File API Description
ATM Connection Data
Event Structures
usTrailerType=0x80
usVersion=1
The usTrailerType 0x80 indicates the following ATM connection data.
Note. This trailer is created by the ATM device software running on PCE and
PowerAAL boards. If any Frame Processing Method (FPM) is configured for an
ATM connection, the appropriate FPM Trailer is created instead of this ATM
connection data trailer.
unsigned short usVpi (offset 0x8)
Virtual Path Identifier
unsigned short usVci (offset 0xa)
Virtual Channel Identifier
unsigned char ucCid (offset 0xc)
Channel Identifier
unsigned char ucAalType (offset 0xd)
ATM Adaptation Layer Type:
0none
1AAL–2 path
2AAL–2 SSSAR
3AAL–2 CPS
4AAL–2 SSTED
5AAL–5
6AAL–0
Record File API Description
29
Event Structures
unsigned char ucDirection (offset 0xe)
ATM connection direction:
1Rx
2Tx
3RxTx
unsigned char ucMultiPvcGroup (offset 0xf)
internally used M–PVC group number, 0=none
30
Record File API Description
UMTS FP Iub/Iur Data
Frame Trailer Section
(V. 0 or 1)
Event Structures
usTrailerType=0x10 (not handled by reassembler)
or
usTrailerType=0x30 (handled by reassembler)
usVersion= 0 or 1
(0...14; 255 for definite logical channel without CT id)
unsigned char ucLayerAboveRlc (offset 0x15)
Layer above RLC (see RELATION in stack file also)
1RRC_BCCH_FACH
2RRC_BCCH_BCH
3RRC_CCCH_DL
4RRC_CCCH_UL
5RRC_DCCH_DL
6RRC_DCCH_UL
7RRC_SHCCH_DL
8RRC_SHCCH_UL
9RRC_PCCH
21USER DATA (PDCP transparent)
Record File API Description
22PDCP (non–transparent)
57
Event Structures
unsigned short usBitlen (offset 0x16)
Length of reassembled data in Bits
unsigned long ulError (offset 0x18)
Not used
unsigned char ucCrcChkResult (offset 0x60)
CRC check for FP Header and Payload:
0no CRC error
1Payload CRC error
2Header CRC error
58
Record File API Description
UMTS FP Iub/Iur
Reassembled Data Frame
Trailer Section (V. 2)
Event Structures
usTrailerType=0x92
usVersion= 2
unsigned short usVPI (offset 0x8)
Virtual Path Identifier
unsigned short usVCI (offset 0xa)
Virtual Channel Identifier
unsigned char ucCID (offset 0xc)
Sub–Channel Identifier
unsigned char ucIfID (offset 0xd)
Interface Identifier
unsigned char ucRadioMode (offset 0xe)
Radio mode:
1FDD
2TDD 3.84 Mcps
3TDD 1.28 Mcps
unsigned char ucDirection (offset 0xf)
Port Direction:
0Unknown
1Uplink
2Downlink
unsigned char ucInterface (offset 0x10)
Record File API Description
UTRAN Interface type:
1FP Iub
2FP Iur
59
Event Structures
unsigned char ucTrChType (offset 0x14)
Type of Transport Channel:
1Broadcast Channel (BCH)
2Paging Channel (PCH)
3Common Packet Channel (CPCH)
4Random Access Channel (RACH)
5Forward Link Access Channel (FACH)
6Uplink Shared Channel (USCH)
7Downlink Shared Channel (DSCH)
8Dedicated Channel (DCH)
unsigned char ucDirection (offset 0x15)
Port Direction:
0Unknown
1Uplink
2Downlink
unsigned char ucRlcMode (offset 0x16)
RLC Mode:
1Transparent Mode, segmented
2Transparent Mode, non–segmented
3Unacknowledged Mode
4Acknowledge Mode
60
Record File API Description
unsigned char ucLgChType (offset 0x17)
Type of Logical Channel:
1Broadcast Control Channel (BCCH)
2Paging Control Channel (PCCH)
3Dedicated Control Channel (DCCH)
4Common Control Channel (CCCH)
5Common Traffic Channel (CTCH)
6Dedicated Traffic Channel (DTCH)
7Shared Channel Control Channel (SHCCH)
unsigned char ucCTid (offset 0x18)
Identification of Logical Channel
Event Structures
(0...14; 255 for definite logical channel without CT id)
unsigned char ucLayerAboveRlc (offset 0x19)
Layer above RLC (see RELATION in stack file also)
1RRC_BCCH_FACH
2RRC_BCCH_BCH
3RRC_CCCH_DL
4RRC_CCCH_UL
5RRC_DCCH_DL
6RRC_DCCH_UL
7RRC_SHCCH_DL
8RRC_SHCCH_UL
9RRC_PCCH
21USER DATA (PDCP transparent)
Record File API Description
22PDCP (non–transparent)
61
Event Structures
unsigned short usBitlen (offset 0x1a)
Length of reassembled data in Bits
unsigned long ulError (offset 0x1c)
Not used
unsigned char ucCrcChkResult (offset 0x8c)
CRC check for FP Header and Payload:
0no CRC error
1Payload CRC error
2Header CRC error
62
Record File API Description
UMTS FP Iub/Iur
Reassembled Data Frame
Trailer Section (V. 3)
Event Structures
usTrailerType=0x92
usVersion= 3
unsigned short usVPI (offset 0x8)
Virtual Path Identifier
unsigned short usVCI (offset 0xa)
Virtual Channel Identifier
unsigned char ucCID (offset 0xc)
Sub–Channel Identifier
unsigned char ucIfID (offset 0xd)
Interface Identifier
unsigned char ucRadioMode (offset 0xe)
Radio mode:
1FDD
2TDD 3.84 Mcps
3TDD 1.28 Mcps
unsigned char ucDirection (offset 0xf)
Port Direction:
0Unknown
1Uplink
2Downlink
Record File API Description
63
Event Structures
unsigned char ucInterface (offset 0x10)
UTRAN Interface type:
1FP Iub
2FP Iur
unsigned char ucTrChType (offset 0x14)
Type of Transport Channel:
1Broadcast Channel (BCH)
2Paging Channel (PCH)
3Common Packet Channel (CPCH)
4Random Access Channel (RACH)
5Forward Link Access Channel (FACH)
6Uplink Shared Channel (USCH)
7Downlink Shared Channel (DSCH)
8Dedicated Channel (DCH)
unsigned char ucDirection (offset 0x15)
Port Direction:
0Unknown
1Uplink
2Downlink
unsigned char ucRlcMode (offset 0x16)
RLC Mode:
1Transparent Mode, segmented
2Transparent Mode, non–segmented
3Unacknowledged Mode
64
4Acknowledge Mode
Record File API Description
unsigned char ucLgChType (offset 0x17)
Type of Logical Channel:
1Broadcast Control Channel (BCCH)
2Paging Control Channel (PCCH)
3Dedicated Control Channel (DCCH)
4Common Control Channel (CCCH)
5Common Traffic Channel (CTCH)
6Dedicated Traffic Channel (DTCH)
7Shared Channel Control Channel (SHCCH)
unsigned char ucCTid (offset 0x18)
Identification of Logical Channel
Event Structures
(0...14; 255 for definite logical channel without CT id)
unsigned char ucLayerAboveRlc (offset 0x19)
Layer above RLC (see RELATION in stack file also)
1RRC_BCCH_FACH
2RRC_BCCH_BCH
3RRC_CCCH_DL
4RRC_CCCH_UL
5RRC_DCCH_DL
6RRC_DCCH_UL
7RRC_SHCCH_DL
8RRC_SHCCH_UL
9RRC_PCCH
21USER DATA (PDCP transparent)
Record File API Description
22PDCP (non–transparent)
65
Event Structures
unsigned short usBitlen (offset 0x1a)
Length of reassembled data in Bits
unsigned long ulError (offset 0x1c)
Not used
unsigned char ucCrcChkResult (offset 0x17c)
CRC check for FP Header and Payload:
0no CRC error
1Payload CRC error
2Header CRC error
66
Record File API Description
UMTS FP Iu UP Data
Frame Trailer Section
(V. 1)
Event Structures
usTrailerType=0x50
usVersion= 1
unsigned short usVPI (offset 0x8)
Virtual Path Identifier
unsigned short usVCI (offset 0xa)
Virtual Channel Identifier
unsigned char ucCID (offset 0xc)
Sub–Channel Identifier
unsigned char ucIfID (offset 0xd)
Interface Identifier, Port number 0...31
unsigned char ucCrcChkResult (offset 0xe)
CRC check for FP Header and Payload:
0no CRC error
1Payload CRC error
2Header CRC error
Record File API Description
67
Event Structures
68
Record File API Description
Using the DLL
Loading the Library
To use the library you have to load the DLL. There are two ways to do this:
HInclude the K12RecFl.lib, this is the easiest way to use the functions under
Visual C++
(see section Loading of the DLL by Using K12RecFl.lib)
HImport the DLL directly. This capability is available in most programming
languages (programming manual of your compiler). You have to load all the
needed functions of the DLL manually (see section Importing of NeededFunctions).
Loading of the DLL by
Using K12RecFl.lib
The easiest way to use a DLL under Visual C++ is to link the K12RecFl.lib with
your project. To do so, proceed as follows:
1. Copy the K12RecFl.lib into your project directory (or into a standard library
directory).
2. Add the library to your link list (Project–>Settings–>Linker–>object/library–
module).
Now you can use the all commands of the DLL in your own program.
...
#include ”K12RecFt.h”
...
int iRecFilehandle = K12_REC_OpenRecFileRead (”TestFile.rf5”, OPEN_FILE); // Opens the Record file
K12_REC_stEventHead_t * pstEventHead;
long plEvNo, lEventLen;
pstEventHead = K12_REC_GetFirst (iRecFilehandle, &plEvNo, &lEventLen); // Gets the first event
...
Record File API Description
69
Using the DLL
Importing of Needed
Functions
With more effort you can load each used function manually. Similar to this you
can also use the DLL from other programming languages.
The following code fragment shows an example of how to load the DLL under C
and C++:
...
#include ”K12RecFl.h”
...
HINSTANCE hLibInstance = LoadLibrary(”K12RecFl”);// Open the Library
...
K12_REC_PROC_OPEN_RECFILE_READ OpenRecFileRead;
OpenRecFileRead = (K12_REC_PROC_OPEN_RECFILE_READ)GetProcAddress(hLibInstance,”K12_REC_OpenRecFileRead”);
K12_REC_PROC_GET_FIRST GetFirst;
GetFirst = (K12_REC_PROC_GET_FIRST)GetProcAddress(hLibInstance,”K12_REC_GetFirst”);
...
int iRecFilehandle = K12_REC_OpenRecFileRead (”TestFile.rf5”, OPEN_FILE); // Opens the record file
K12_REC_stEventHead_t * pstEventHead;
long plEvNo, lEventLen;
pstEventHead = GetFirst (iRecFilehandle, &plEvNo, &lEventLen); // Gets the first event
...
FreeLibrary(hLibInstance); // Close the library
...
1. You have to include the K12RecFl.h first, which defines all needed parame-
ters and prototypes (for example the definition of
K12_REC_PROC_OPEN_RECFILE_READ).
2. The next step is to load the DLL.
HINSTANCE hLibInstance = LoadLibrary(”K12RecFl”); // Open the Library
3. Then you have to create a pointer to each used filetool function:
The prototypes of all usable functions are defined in the header file K12RecFl.h.
Use the prototype name defined in the command description (Function Proto-type).
5. At the end of your application you should close the DLL:
FreeLibrary(hLibInstance);
70
Record File API Description
Handling Events
Using the DLL
The following sample code fragment is an extract of an program that gets the
next event and looks after an LDS (logical data source) or a frame event. If it
matches, it coverts the pointer to the event header structure into the event specific
structure. A complete sample is shown in the demo file ListEvnt.c
...
K12_REC_stEventHead_t * pstEventHead;
long plEvNo, lEventLen;
...
pstEventHead = pGetNextFunc (hRecFilehandle, &plEvNo, &lEventLen); // Gets the next Event
if (pstEventHead)
{
switch(pstEventHead–>usGroup)
{
case K12_REC_EVENTGRP_RFCONF: // it’s a config. Event
if(pstEventHead–>usType == K12_REC_EVENTTYP_LDS_CONF)
{ // Event is an LDS–Config Event –> cast Pointer to Event–Header to LDS–Event–structure
K12_REC_stEventLDSConfig2_t * pstLDSEvent;
pstLDSEvent = (K12_REC_stEventLDSConfig2_t *) pstEventHead;
...
}
break;
case K12_REC_EVENTGRP_DATA: // it’s a data. Event
if(pstEventHead–>usType == K12_REC_EVENTTYP_FRAME)
{ // Event is an Frame Event –> cast Pointer to Event–Header to Event–Frame–structure
K12_REC_stEventFrame_t * pstFrameEvent;
pstFrameEvent = (K12_REC_stEventFrame_t *) pstEventHead;
...
}
break;
}
...
}
...
Record File API Description
71
Using the DLL
72
Record File API Description
Command Set
In the following command description, the values of the parameters or results of
some commands are defined in the header file K12RecFl.h. If you cannot use the
header file – for example because you do not use C or C++ as programming
languages – use the value that follows in parentheses.
Record File API Description
73
Command Set
Commands to Read Record Files
Control Commands
int K12_REC_OpenRecFileRead (
char * pczFilename,
long lFlags)
Description
Input Parameters
Return Value
Function Prototyp
Example
Opens a file to read.
pczFilename
Name of record file (including path, filename and file extension).
lFlags
For future use (should be set to 0L).
Handle
When opening was successful (has to be stored, because the handle is used for
any other handling with the file).
0
If it wasn’t possible to open the file.
K12_REC_PROC_OPEN_RECFILE_READ
int iReadFileHandle =
K12_REC_OpenRecFileRead(”c:\\Recordfiles\\DemoRec.rf5”, 0L);
74
See also:
K12_REC_CloseRecFile
Record File API Description
Command Set
K12_REC_RetVal_tK12_REC_SetTimestampCalcMode (
int ihandle ,
K12_REC_TimestampMode_t TimestampMode)
Description
Input Parameters
Return Value
Determinates whether a timestamp from a non K1205 type record file should be
translated (calculated).
ihandle
Handle to an open file (returned from K12_REC_OpenRecFileRead see ControlCommands in section Commands to Read Record Files).
TimestampMode
HK12_REC_DO_NOT_CALC (0)
Do not calculate timestamps (increases speed). If the record file is not a
K1205 type, the timestamps in the returned events are set to zero (default).
HK12_REC_DO_CALC (1)
The timestamp will be converted to the K1205 format.
See also:
K12_REC_OpenRecFileRead,
K12_REC_GetTimestampCalcMode,
K12_REC_GetTimestampFormat
75
Command Set
Status Commands
K12_REC_RetVal_t K12_REC_ShouldSwap (
int ihandle,
int *piResult)
Description
Input Parameters
Output Parameters
Return Value
If the byte order of the record file is not the same as the byte order of the local
machine, the data must be swapped to use them. This function indicates whether
the record file has the same byte order as the local CPU.
ihandle: Handle to an open file (returned from K12_REC_OpenRecFileRead see
Control Commands in section Commands to Read Record Files).
piResult:
Address of a long that returns the result.
H0
Same byte order (don’t need to swap).
H1
Different byte order (need to swap).
K12_REC_OK (1)
Ok
K12_REC_ERROR (0)
Error
76
Function Prototyp
Example
K12_REC_PROC_SHOULD_SWAP
int iResult;
K12_REC_RetVal_t Ret = K12_REC_ShouldSwap(iReadFileHandle, &iResult);
if (Ret == K12_REC_OK)
printf(”Result: %d”, iResult);
See also:
K12_REC_OpenRecFileRead,
K12_REC_GetSwapMode,
K12_REC_SetSwapMode
Record File API Description
K12_REC_RetVal_t K12_REC_GetFileType (
int ihandle ,
K12_REC_FileType_t * pFileType)
Command Set
Description
Input Parameters
Output Parameters
Return Value
Gets the type of the record file opened.
ihandle: Handle to an open file (returned from K12_REC_OpenRecFileRead see
Control Commands in section Commands to Read Record Files).
pFileType
Address of a K12_REC_FileType that returns the type of file.
HK12_REC_K1205TYP (1)
a K15, K1205, K1297-G20 record file is open.
HK12_REC_K1103TYP (2)
a K1103 record file is open.
HK12_REC_K1297TYP (5)
a K1297-Classic record file is open.
K12_REC_OK (1)
Ok
K12_REC_ERROR (0)
Error
Function Prototyp
Example
Record File API Description
K12_REC_PROC_GET_FILE_TYPE
K12_REC_FileType_t FileType ;
K12_REC_RetVal_t Ret = K12_REC_GetCaptureType(iReadFileHandle,
&FileType);
if ((Ret == K12_REC_OK) && (FileType == K12_REC_K1205TYP))
printf(”K1205 file”);
See also:
K12_REC_OpenRecFileRead
77
Command Set
K12_REC_RetVal_t K12_REC_GetTimestampCalcMode (
int ihandle
K12_REC_TimestampMode_t * pTimestampMode)
Description
Input Parameters
Output Parameters
Returns whether a timestamp should be translated (calculated).
The translation–mode can be changed by K12_REC_SetCalcTimestamp(...) (see
Control Commands in section Commands to Read Record Files).
ihandle
Handle to an open file (returned from K12_REC_OpenRecFileRead see
Control Commands in section Commands to Read Record Files).
pTimestampMode
Address of an K12_REC_TimestampMode_t that returns the
timestamp mode.
HK12_REC_DO_NOT_CALC (0)
Don’t calculate timestamps. If the record file isn’t a K1205 type, the
timestamps in the returned events are set to Zero.
HK12_REC_DO_CALC (1)
If the record file is not a K1205 type, it has another timestamp format. The
timestamp will be converted to the K1205 format.
Return Value
Function Prototyp
Example
K12_REC_OK (1)
Ok
K12_REC_ERROR (0)
Error
K12_REC_PROC_GET_TIMESTAMP_MODE
K12_REC_TimestampMode_t TimestampMode;
K12_REC_RetVal_t Ret = K12_REC_GetTimestampCalcMode(iReadFileHandle, &TimestampMode);
See also:
K12_REC_OpenRecFileRead,
K12_REC_SetTimestampCalcMode,
K12_REC_GetTimestampFormat
78
Record File API Description
K12_REC_RetVal_t K12_REC_GetTimestampFormat (
int ihandle,
long * plSecsOfBase,
long * plTicksPerSec)
Command Set
Description
Input Parameters
Output Parameters
Return Value
Function Prototyp
Returns information about the timestamp format that was used to create the
record file.
ihandle
Handle to an open file (returned from K12_REC_OpenRecFileRead see
Control Commands in section Commands to Read Record Files).
plSecsOfBase
Address of a long that returns the Seconds of Base.
plTicksPerSec
Address of a long that returns the Ticks per second.
K12_REC_OK (1)
Ok
K12_REC_ERROR (0)
Error
K12_REC_PROC_GET_TIMESTAMP_FORMAT
Example
Record File API Description
long lSecsOfBase, lTicksPerSec;
if(K12_REC_GetTimestampFormat (iReadFileHandle, &SecsOfBase,
&TicksPerSec))
printf (”Seconds of Base: %ld ; Ticks per second: %ld”, SecsOfBase,
TicksPerSec);
See also:
K12_REC_OpenRecFileRead,
K12_REC_SetTimestampCalcMode,
K12_REC_GetTimestampCalcMode
79
Command Set
Note. In most cases the 64 bit time stamp is a 64 bit value that represents ‘X’
ticks per second since absolute date ‘Y’. The ‘seconds of base’ are the seconds
that have past since 01.01.1970 00:00:00. When you load K15, K1297-G20,
K1205, or K1103 record files, the standard base is 631.152.000 (representing
01.01.1990 00:00:00). For K1297-Classic recordings normally the base is
788.918.400 (01.01.1995 00:00:00).
The returned value of ‘Ticks per second’ depends on the timer of the measurement system: The reciprocal of this value is the timer base of the system (in
seconds).
In both returned values are zero, another kind of timestamp format is indicated.
This format has two 32 bit values instead of one 64 bit value. The upper 32 bit
represent the seconds since 01.01.1970 00:00:00 (so you can use all standard C
time() functions on it), and the lower 32 bits represent the nanoseconds inside
this second. This format (called general timestamp format) is not currently used
but may be used in the future.
80
Record File API Description
Command Set
K12_REC_RetVal_t K12_REC_GetEventPosInPercent (
int ihandle,
int * piPosition)
Description
Input Parameters
Output Parameters
Return Value
Function Prototyp
Example
Gives a rough position of the last read event relative to all existing events in the
record file.
ihandle
Handle to an open file (returned from K12_REC_OpenRecFileRead see
Control Commands in section Commands to Read Record Files).
piPosition
Address of an integer that returns the position in the file (as a percent).
K12_REC_OK (1)
Ok
K12_REC_ERROR (0)
Error
K12_REC_PROC_GET_EVENT_POS_IN_PERCENT
int iPosition ;
K12_REC_RetVal_t Ret = K12_REC_GetEventPosInPercent(iReadFileHandle,
&iPosition);
if (Ret == K12_REC_OK)
printf(”Position is at %d \%”, iPosition);
Record File API Description
See also:
K12_REC_OpenRecFileRead,
K12_REC_GetFirst
81
Command Set
Reading Commands
const K12_REC_stEventHead_t * K12_REC_GetFirst (
int ihandle,
long * plEventNo,
long * plEventLen)
Description
Input Parameters
Output Parameters
Return Value
Function Prototyp
Gets the first event in the record file.
ihandle
Handle to an open file (returned from K12_REC_OpenRecFileRead see
Control Commands in section Commands to Read Record Files).
plEventNo
Address of a long that returns the number of the event.
plEventLen
Address of a long that returns the length of the event.
<> NULL
Pointer to an eventhead structure (see section Event Header)
NULL
No valid event exists.
K12_REC_PROC_GET_FIRST
82
Example
long lEventNo, lEventLen;
K12_REC_stEventHead_t * pstEventHead;
pstEventHead = K12_REC_GetFirst(iReadFileHandle, &lEventNo,
& lEventLen);
if(!pstEventHead)
return; // no event present
See also:
K12_REC_OpenRecFileRead, K12_REC_GetLast,
K12_REC_GetPrev, K12_REC_GetNext,
K12_REC_GetThis, K12_REC_GetFirstConf,
K12_REC_GetNextConf
Record File API Description
Command Set
const K12_REC_stEventHead_t * K12_REC_GetLast (
int ihandle,
long * plEventNo,
long * plEventLen)
Description
Input Parameters
Output Parameters
Return Value
Function Prototyp
Gets the last event in the record file.
ihandle
Handle to an open file (returned from K12_REC_OpenRecFileRead see
Control Commands in section Commands to Read Record Files).
plEventNo
Address of a long that returns the number of the event.
plEventLen
Address of a long that returns the length of the event.
<> NULL
Pointer to an eventhead structure (see section Event Header).
NULL
No valid event exists.
K12_REC_PROC_GET_LAST
Example
Record File API Description
long lEventNo, lEventLen;
K12_REC_stEventHead_t * pstEventHead;
pstEventHead = K12_REC_GetLast(iReadFileHandle, &lEventNo,
& lEventLen);
if(!pstEventHead)
return; // no event present
See also:
K12_REC_OpenRecFileRead, K12_REC_GetFirst,
K12_REC_GetPrev, K12_REC_GetNext,
K12_REC_GetThis, K12_REC_GetFirstConf,
K12_REC_GetNextConf
83
Command Set
const K12_REC_stEventHead_t * K12_REC_GetPrev (
int ihandle,
long * plEventNo,
long * plEventLen)
Description
Input Parameters
Output Parameters
Return Value
Function Prototyp
Gets the previous event and decrements the readout position in the record file.
ihandle
Handle to an open file (returned from K12_REC_OpenRecFileRead see
Control Commands in section Commands to Read Record Files).
plEventNo
Address of a long that returns the number of the event.
plEventLen
Address of a long that returns the length of the event.
<> NULL
Pointer to an eventhead structure (see section Event Header).
NULL
No valid event exists.
K12_REC_PROC_GET_PREV
84
Example
long lEventNo, lEventLen;
K12_REC_stEventHead_t * pstEventHead;
pstEventHead = K12_REC_GetPrev(iReadFileHandle, &lEventNo,
& lEventLen);
if(!pstEventHead)
return; // no event present
See also:
K12_REC_OpenRecFileRead, K12_REC_GetFirst,
K12_REC_GetLast, K12_REC_GetNext,
K12_REC_GetThis, K12_REC_GetFirstConf,
K12_REC_GetNextConf
Record File API Description
Command Set
const K12_REC_stEventHead_t * K12_REC_GetNext (
int ihandle,
long * plEventNo
long * plEventLen)
Description
Input Parameters
Output Parameters
Return Value
Function Prototyp
Gets the next event and increments the readout position in the record file.
ihandle
Handle to an open file (returned from K12_REC_OpenRecFileRead see
Control Commands in section Commands to Read Record Files).
plEventNo
Address of a long that returns the number of the event.
plEventLen
Address of a long that returns the length of the event.
<> NULL
Pointer to an eventhead structure (see section Event Header).
NULL
No valid event exists.
K12_REC_PROC_GET_NEXT
Example
Record File API Description
long lEventNo, lEventLen;
K12_REC_stEventHead_t * pstEventHead;
pstEventHead = K12_REC_GetNext(iReadFileHandle, &lEventNo,
& lEventLen);
if(!pstEventHead)
return; // no event present
See also:
K12_REC_OpenRecFileRead, K12_REC_GetFirst,
K12_REC_GetLast, K12_REC_GetPrev,
K12_REC_GetThis, K12_REC_GetFirstConf,
K12_REC_GetNextConf
85
Command Set
const K12_REC_stEventHead_t * K12_REC_GetThis (
int ihandle,
long lWantedEventNo,
long * plEventNo,
long * plEventLen)
Description
Input Parameters
Output Parameters
Return Value
Gets an specific event in the record file.
ihandle
Handle to an open file (returned from K12_REC_OpenRecFileRead see
Control Commands in section Commands to Read Record Files).
lWantedEventNo
Position of the wanted event (number of the event).
plEventNo
Address of a long that returns the number of the event.
plEventLen
Address of a long that returns the length of the event.
<> NULL
Pointer to an eventhead structure (see section Event Header).
NULL
No valid event exists.
86
Function Prototyp
Example
K12_REC_PROC_GET_THIS
long lEventNo, lEventLen;
K12_REC_stEventHead_t * pstEventHead;
pstEventHead = K12_REC_GetThis(iReadFileHandle, 100, &lEventNo,
& lEventLen);
// Try to get the entry no. 100
if(!pstEventHead)
return; // no event present
See also:
K12_REC_OpenRecFileRead, K12_REC_GetFirst,
K12_REC_GetLast, K12_REC_GetPrev,
K12_REC_GetNext, K12_REC_GetFirstConf,
K12_REC_GetNextConf
Record File API Description
Command Set
const K12_REC_stEventHead_t * K12_REC_GetFirstConf (
int ihandle,
long * plEventNo,
long * plEventLen)
Description
Input Parameters
Output Parameters
Return Value
An interface to get only the configuration events. Needed to get LDS (logical
data source) configuration and LL configuration events without scanning the
whole record file and without knowing the details of this record file format. Gets
the first configuration event in the record file.
ihandle
Handle to an open file (returned from K12_REC_OpenRecFileRead see
Control Commands in section Commands to Read Record Files).
plEventNo
Address of a long that returns the number of the event.
plEventLen
Address of a long that returns the length of the event.
<> NULL
Pointer to an eventhead structure (see section Event Header).
NULL
No valid event exists.
Function Prototyp
Example
Record File API Description
K12_REC_PROC_GET_FIRST_CONF
long lEventNo, lEventLen;
K12_REC_stEventHead_t * pstEventHead;
pstEventHead = K12_REC_GetFirstConf(iReadFileHandle, &lEventNo,
& lEventLen);
if(!pstEventHead)
return; // no event present
See also:
K12_REC_OpenRecFileRead, K12_REC_GetFirst,
K12_REC_GetLast, K12_REC_GetPrev,
K12_REC_GetNext, K12_REC_GetThis,
K12_REC_GetNextConf, K12_REC_GetNumConfigEvents
87
Command Set
const K12_REC_stEventHead_t * K12_REC_GetNextConf (
int ihandle,
long * plEventNo,
long * plEventLen)
Description
Input Parameters
Output Parameters
Return Value
An interface to get only the configuration events. Needed to get LDS (logical
data source) configuration and LL configuration events without scanning the
whole record file and without knowing the details of this record file format. Gets
the next configuration event in the record file.
ihandle
Handle to an open file (returned from K12_REC_OpenRecFileRead see
Control Commands in section Commands to Read Record Files).
plEventNo
Address of a long that returns the number of the event.
plEventLen
Address of a long that returns the length of the event.
<> NULL
Pointer to an eventhead structure (see section Event Header).
NULL
No valid event exists.
88
Function Prototyp
Example
K12_REC_PROC_GET_NEXT_CONF
long lEventNo, lEventLen;
K12_REC_stEventHead_t * pstEventHead;
pstEventHead = K12_REC_GetNextConf(iReadFileHandle, &lEventNo,
& lEventLen);
if(!pstEventHead)
return; // no event present
See also:
K12_REC_OpenRecFileRead, K12_REC_GetFirst,
K12_REC_GetLast, K12_REC_GetPrev,
K12_REC_GetNext, K12_REC_GetThis,
K12_REC_GetFirstConf, K12_REC_GetNumConfigEvents
Record File API Description
Command Set
Note. To use this command, first place the ‘event–pointer’ at the beginning of the
configuration events (use K12_REC_GetFirstConf(...) see section Reading
Commands).
pczFilename
Name of record file(including path, filename and file extension).
Writemode:
HK12_REC_WMODE_VAR_SIZE (8)
Files have a variable size (minimum 1 block, maximum disk full) and grow
with the number of written blocks (endless).
HK12_REC_WMODE_MAX_SIZE (16)
No write possible when maximum file size is reached (file size grows like
K12_REC_WMODE_VAR_SIZE). The given file size (Parameter ‘Filesize’)
is rounded down to the next full block.
HK12_REC_WMODE_FIX_SIZE (48)
Like K12_REC_WMODE_MAX_SIZE, but the file size is specified (file
size cannot grow).
lFilesize
Maximum size of the written File. Only needed for ‘Writemode’
K12_REC_WMODE_MAX_SIZE and K12_REC_WMODE_FIX_SIZE.
90
Openmode
HK12_REC_OMODE_OVERWRITE (50)
Create a new file or overwrite an existing file.
HK12_REC_OMODE_APPEND (51)
Continue existing file or create a new one.
CAUTION. Appended files must have the same file properties as the opened file.
Record File API Description
Command Set
Return Value
Function Prototyp
Example
> 0
Handle to opened file (is used for any other handling
with the file).
< 0
Error
K12_REC_PROC_OPEN_RECFILE_WRITE
int iWritehandle = K12_REC_OpenRecFileWrite(
”test.rf5”,K12_REC_ WMODE_VAR_SIZE, 0L,
K12_REC_OMODE_APPEND);
if(iWritehandle < 0)
{
const char * pczErrString = K12_REC_GetErrorString(iWritehandle);
printf(”File open error: %s”, pczErrString);
return;// Can’t open file
}
See also:
K12_REC_CloseRecFile,
K12_REC_GetErrorString
Possible Error Codes
ERRWR_WRONG_OMODE (–1)
Wrong open–mode
ERRWR_WRONG_WMODE (–2)
Wrong write–mode; can also happen when continued. File was created with a
different write–mode than the current one
ERRWR_CANT_OPEN_FILE (–3)
No filename or wrong filename–length
ERRWR_IO_ERROR (–4)
Error in open(), lseek(), write() or read()
ERRWR_ISOPEN (–5)
Record file is already open
ERRWR_NO_MEMORY (–6)
No memory available
ERRWR_MUST_REP (–7)
Record file must be repaired
Record File API Description
91
Command Set
ERRWR_WRONG_OLD_FILE (–8)
File that should be appended is not a K15, a K1297-G20, or a K1205 record file
WRBL_IO_FAILED (–10)
lseek() or write() failed
WRBL_BAD_READ (–11)
Read error
WRBL_CANT_OPEN (–12)
No filename or wrong filename–length
WRBL_BAD_SIZE (–13)
Wrong file size (file too big)
WRBL_NO_FD (–14)
It was not possible to create a duplicate of the file handle
92
Record File API Description
Status Commands
const char * K12_REC_GetErrorString (
int iErrorNumber)
Command Set
Description
Input Parameters
Return Value
Function Prototyp
Example
Returns the English plain text of the error of the K12_REC_OpenRecFileWrite
function.
iErrorNumber
error number (< 0) returned by K12_REC_OpenRecFileWrite (see ControlCommands in section Commands to Write Record Files).
Pointer to English error string.
K12_REC_PROC_GET_ERROR_STRING
int iWritehandle = K12_REC_OpenRecFileWrite(”test.rf5”,
WMODE_VAR_SIZE, 0L, OMODE_OVERWRITE);
K12_REC_RetVal_t K12_REC_Write (
int ihandle,
K12_REC_stEventHead_t * pstOrgEvent)
Description
Input Parameters
Output Parameters
Return Value
Function Prototyp
Write one event to the open file. All written events are buffered in a block, and
only full blocks are written to the disk. After a write error, the file has to be
closed normally.
ihandle
Handle to an open file (returned from K12_REC_OpenRecFileWrite see ControlCommands in section Commands to Write Record Files).
pstOrgEvent
Pointer to event, which should be written to file.
K12_REC_OK (1)
Ok
K12_REC_ERROR (0)
Error (no write possible, because file size – see Control Commands in sectionCommands to Write Record Files – is reached or disk is full; event is not saved!
if(!pEventheader)
return; // no event present
if(!iK12_REC_Write(iWritehandle, pEventheader))
printf(”Can’t write event to file”);
See also:
K12_REC_OpenRecFileWrite,
K12_REC_CloseRecFile,
K12_REC_Flush
Record File API Description
Command Set
Note. All data in a record file should be in Motorola format (MSBF). The Write()
function only swaps (if necessary) the values of the event header
(’K12_REC_stEventHead_t’) and not the rest of an event!
Record File API Description
95
Command Set
K12_REC_RetVal_t K12_REC_Flush (
int ihandle,
K12_REC_FlushFlag_t Flags)
Description
Input Parameters
Return Value
Flushes the current data to file. The file header does not contain the current data.
ihandle
Handle to an open file (returned from K12_REC_OpenRecFileWrite see ControlCommands in section Commands to Write Record Files).
Flags:
HK12_REC_FLUSH_QUICK (0)
writes all ’full’ blocks to file (quick).
HK12_REC_FLUSH_ALL (1)
writes all ’full’ blocks plus the current (part filled) block including the last
written events.