IxChariot APIGuide

7.30 SP3, February 2016

Copyright and Disclaimer

Copyright 2016 Ixia. All rights reserved.
This publication may not be copied, in whole or in part, without Ixia's consent.
RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the U.S. Government is
subject to the restrictions set forth in subparagraph (c)(1)(ii) of the Rights in Technical
Data and Computer Software clause at DFARS 252.227-7013 and FAR 52.227-19.
Ixia, the Ixia logo, and all Ixia brand names and product names in this document are
either trademarks or registered trademarks of Ixia in the United States and/or other countries. All other trademarks belong to their respective owners.
The information herein is furnished for informational use only, is subject to change by Ixia
without notice, and should not be construed as a commitment by Ixia. Ixia assumes no
responsibility or liability for any errors or inaccuracies contained in this publication.
Ixia Worldwide Headquarters
Web site: www.ixiacom.com

26601 W. Agoura Rd.

General: info@ixiacom.com

Calabasas, CA 91302
Corporate
Headquarters

Investor Relations: ir@ixiacom.com

USA
+1 877 FOR IXIA (877 367 4942)
+1 818 871 1800 (International)
(FAX) +1 818 871 1805

Training: training@ixiacom.com
Support: support@ixiacom.com
+1 818 595 2599

sales@ixiacom.com
Ixia Europe Limited
Part 2nd floor,
Clarion House, Norreys Drive
EMEA

Maidenhead, UK SL6 4FL

Support: support-emea@ixiacom.com

+44 (1628) 408750

+40 21 301 5699

FAX +44 (1628) 639916

salesemea@ixiacom.com
Ixia Pte Ltd
Support: support-asiapac@ixiacom.com

210 Middle Road

Asia Pacific
#08-01 IOI Plaza

+91 80 4939 6410

Singapore 188994
Ixia KK
Japan

Nishi-Shinjuku Mitsui Bldg 11F

Support: support-japan@ixiacom.com

6-24-1, Nishi-Shinjuku, Shinjukuku

+81 3 5326 1980

- ii -

Tokyo 160-0023
Japan
Ixia Technologies Pvt Ltd
Tower 1, 7th Floor, UMIYA Business Bay
Cessna Business Park

India

Survey No. 10/1A, 10/2, 11 & 13/2 Support: support-india@ixiacom.com

Outer Ring Road, Varthur Hobli
Kadubeesanahalli Village

+91 80 4939 6410

Bangalore East Taluk

Bangalore-560 037, Karnataka,
India
+91 80 42862600
Ixia Technologies (Shanghai) Com- Support: support-chinpany Ltd
a@ixiacom.com
Chi na

Unit 3, 11th Floor, Raffles City,

Beijing

400 898 0598 (Greater China

Region)

Beijing, 100007 P.R.C.

+86 10 5732 3932 (Hong Kong)

For viewing the FAQs related to the product, go to Ixia Technical Support Online:
http://www.ixiacom.com/support-services/contact-support

- iii -

IxChariot APIGuide

Contents
About This Book

35

Intended Audience

35

The IxChariot Documentation Suite

35

Conventions

36

Welcome

36

What Can You Do with the Programs You Write?

36

What You Need to Know

36

Overview

37

Inter-Object Relationships

39

Error Checking Done by API

41

License Checking

41

Argument Validation

41

Management Addresses with Stack Manager

42

Stopping a Running Test

44

Object Descriptions and Default Values

45

Test Object

46

Test Object Default Values

47

Pair Object

48

Pair Object Default Values

49

Hardware Performance Pair Object

50

VoIP Hardware Performance Pair Object

51

Hardware Performance Pair Object Default Values

52

VoIP Hardware Performance Pair Object Default Values

53

Multicast Group Object

54

Multicast Group Object Default Values

55

Multicast Pair Object

56

Application Group Object

57

Application Group Object Default Values

58

Datagram Options Object

59

Datagram Options Object Default Values

60

-1-

IxChariot APIGuide

Run Options Object

61

Run Options Object Default Values

62

Timing Record Object

64

Traceroute Pair Object

65

Traceroute Pair Object Default Values

66

Hop Record Object

67

VoIP Pair Object

68

VoIP Pair Object Default Values

69

Video Pair Object

70

Video Pair Object Default Values

71

Video Multicast Group Object

72

Video Multicast Group Object Default Values

73

IPTV Channel Object

74

IPTV Channel Object Default Values

75

IPTV VPair Object

76

IPTV VPair Object Default Values

77

IPTV Receiver Group Object

78

IPTV Receiver Group Object Default Values

79

Results Extraction

80

Common Error Functions

83

API Utility Functions

84

Your First Program

85

C Program

86

Tcl Script

95

Program Notes

99

Interesting Examples

101

C Reference

102

Getting Started

103

IxChariot API Objects

104

String Parameters

105

Return Codes

106

Error Detail Levels

107

-2-

IxChariot APIGuide

Compiler Support

108

Compiling and Linking Your Program

109

C Functions

110

API Utility Functions

111

CHR_api_delete_qos_template

112

CHR_api_get_license_expiration_time

113

CHR_api_get_license_type

114

CHR_api_get_max_pairs

115

CHR_api_get_network_ip_list

116

CHR_api_get_pair_type

118

CHR_api_get_port_mgmt_ip_list

120

CHR_api_get_reporting_port

122

CHR_api_get_return_msg

123

CHR_api_get_version

124

CHR_api_initialize

125

CHR_api_initialize_with_license_details

126

CHR_api_license_change_borrow_time

128

CHR_api_license_change_license_server

129

CHR_api_license_checkin_pairs

130

CHR_api_license_checkout_pairs

131

CHR_api_license_get_borrow_days_remaining

132

CHR_api_license_get_license_server

133

CHR_api_license_get_test_pair_count

134

CHR_api_modify_qos_tos_template

135

CHR_api_new_qos_tos_template

137

CHR_api_set_reporting_port

139

Application Group Object Functions

140

CHR_app_group_add_event

141

CHR_app_group_add_pair

143

CHR_app_group_copy

144

CHR_app_group_delete

146

CHR_app_group_disable

147

-3-

IxChariot APIGuide

CHR_app_group_force_delete

148

CHR_app_group_get_address

149

CHR_app_group_get_address_count

151

CHR_app_group_get_comment

152

CHR_app_group_get_event

153

CHR_app_group_get_event_count

155

CHR_app_group_get_filename

156

CHR_app_group_get_lock

157

CHR_app_group_get_management_address

158

CHR_app_group_get_management_address_count

160

CHR_app_group_get_name

161

CHR_app_group_get_pair

162

CHR_app_group_get_pair_count

163

CHR_app_group_get_pair_management_protocol

164

CHR_app_group_get_pair_protocol

165

CHR_app_group_get_pair_qos_name

166

CHR_app_group_is_disabled

168

CHR_app_group_new

169

CHR_app_group_remove_event

170

CHR_app_group_remove_pair

171

CHR_app_group_save

172

CHR_app_group_set_address

173

CHR_app_group_set_comment

175

CHR_app_group_set_filename

176

CHR_app_group_set_lock

178

CHR_app_group_set_management_address

179

CHR_app_group_set_name

181

CHR_app_group_set_pair_management_protocol

183

CHR_app_group_set_pair_protocol

185

CHR_app_group_set_pair_qos_name

187

CHR_app_group_validate

189

Common Error Functions

190

-4-

IxChariot APIGuide

CHR_common_error_get_info

191

CHR_common_error_get_msg_num

193

Common Results Extraction Functions

194

CHR_common_results_get_bytes_recv_e1

195

CHR_common_results_get_bytes_recv_e2

196

CHR_common_results_get_bytes_sent_e1

197

CHR_common_results_get_dg_dup_recv_e1

198

CHR_common_results_get_dg_dup_recv_e2

199

CHR_common_results_get_dg_dup_sent_e1

200

CHR_common_results_get_dg_dup_sent_e2

201

CHR_common_results_get_dg_lost_e1_to_e2

202

CHR_common_results_get_dg_out_of_order

203

CHR_common_results_get_dg_recv_e1

204

CHR_common_results_get_dg_recv_e2

205

CHR_common_results_get_dg_sent_e1

206

CHR_common_results_get_e1_ack_to_fin_rx

207

CHR_common_results_get_e1_ack_to_fin_tx

208

CHR_common_results_get_e1_conn_established

209

CHR_common_results_get_e1_fin_rx

210

CHR_common_results_get_e1_fin_tx

211

CHR_common_results_get_e1_rst_rx

212

CHR_common_results_get_e1_rst_tx

213

CHR_common_results_get_e1_syn_failed

214

CHR_common_results_get_e1_syn_rx

215

CHR_common_results_get_e1_syn_tx

216

CHR_common_results_get_e1_tcp_retransmissions

217

CHR_common_results_get_e1_tcp_timeouts

218

CHR_common_results_get_est_clock_error

219

CHR_common_results_get_jitter_buffer_lost

220

CHR_common_results_get_max_clock_error

221

CHR_common_results_get_meas_time

222

CHR_common_results_get_rtd

223

-5-

IxChariot APIGuide

CHR_common_results_get_rtd_95pct_confidence

224

CHR_common_results_get_trans_count

225

Datagram Options Object Functions

226

CHR_dgopts_get_data_rate_limit

227

CHR_dgopts_get_limit_data_rate

228

CHR_dgopts_get_low_sender_jitter

229

CHR_dgopts_get_measured_interval

230

CHR_dgopts_get_recv_timeout

231

CHR_dgopts_get_retrans_count

232

CHR_dgopts_get_retrans_timeout

233

CHR_dgopts_get_RTP_use_extended_headers

234

CHR_dgopts_get_TTL

235

CHR_dgopts_get_window_size

236

CHR_dgopts_set_data_rate_limit

237

CHR_dgopts_set_limit_data_rate

238

CHR_dgopts_set_low_sender_jitter

239

CHR_dgopts_set_measured_interval

241

CHR_dgopts_set_recv_timeout

242

CHR_dgopts_set_retrans_count

243

CHR_dgopts_set_retrans_timeout

244

CHR_dgopts_set_RTP_use_extended_headers

245

CHR_dgopts_set_TTL

246

CHR_dgopts_set_window_size

247

Hop Record Object Functions

248

CHR_hoprec_get_hop_address

249

CHR_hoprec_get_hop_latency

250

CHR_hoprec_get_hop_name

251

CHR_hoprec_get_hop_number

252

IPTV Channel Object Functions

253

CHR_channel_delete

254

CHR_channel_get_bitrate

255

CHR_channel_get_codec

256

-6-

IxChariot APIGuide

CHR_channel_get_comment

257

CHR_channel_get_conn_send_buff_size

259

CHR_channel_get_console_e1_addr

260

CHR_channel_get_console_e1_protocol

262

CHR_channel_get_e1_addr

263

CHR_channel_get_frames_per_datagram

264

CHR_channel_get_lock

265

CHR_channel_get_media_frame_size

266

CHR_channel_get_multicast_addr

267

CHR_channel_get_multicast_port

268

CHR_channel_get_name

269

CHR_channel_get_protocol

270

CHR_channel_get_qos_name

271

CHR_channel_get_rtp_payload_type

272

CHR_channel_get_source_port_num

273

CHR_channel_get_use_console_e1_values

274

CHR_channel_new

275

CHR_channel_set_bitrate

276

CHR_channel_set_codec

277

CHR_channel_set_comment

278

CHR_channel_set_conn_send_buff_size

279

CHR_channel_set_console_e1_addr

280

CHR_channel_set_console_e1_protocol

281

CHR_channel_set_e1_addr

282

CHR_channel_set_frames_per_datagram

283

CHR_channel_set_lock

284

CHR_channel_set_media_frame_size

285

CHR_channel_set_multicast_addr

286

CHR_channel_set_multicast_port

287

CHR_channel_set_name

288

CHR_channel_set_protocol

289

CHR_channel_set_qos_name

290

-7-

IxChariot APIGuide

CHR_channel_set_rtp_payload_type

291

CHR_channel_set_source_port_num

292

CHR_channel_set_use_console_e1_values

293

IPTV Pair Object Functions

294

CHR_vpair_delete

295

CHR_vpair_get_channel

296

CHR_vpair_get_lock

297

CHR_vpair_get_no_of_timing_records

298

CHR_vpair_get_report

299

CHR_vpair_get_report_count

300

CHR_vpair_get_runStatus

301

CHR_vpair_get_timing_record

303

CHR_vpair_get_timing_record_count

304

CHR_vpair_get_tr_duration

305

CHR_vpair_new

306

CHR_vpair_set_lock

307

CHR_vpair_set_no_of_timing_records

308

CHR_vpair_set_channel

309

CHR_vpair_set_tr_duration

310

IPTV Receiver Object Functions

311

CHR_receiver_add_vpair

312

CHR_receiver_delete

313

CHR_receiver_disable

314

CHR_receiver_get_comment

315

CHR_receiver_get_conn_recv_buff_size

317

CHR_receiver_get_e2_addr

318

CHR_receiver_get_lock

320

CHR_receiver_get_name

321

CHR_receiver_get_no_of_iterations

323

CHR_receiver_get_vpair

324

CHR_receiver_get_vpair_count

325

CHR_receiver_get_setup_e1_e2_addr

326

-8-

IxChariot APIGuide

CHR_receiver_get_switch_delay

328

CHR_receiver_get_use_e1_e2_values

329

CHR_receiver_is_disabled

330

CHR_receiver_new

331

CHR_receiver_remove_vpair

332

CHR_receiver_set_comment

333

CHR_receiver_set_conn_recv_buff_size

334

CHR_receiver_set_e2_addr

335

CHR_receiver_set_lock

336

CHR_receiver_set_name

337

CHR_receiver_set_no_of_iterations

338

CHR_receiver_set_setup_e1_e2_addr

339

CHR_receiver_set_switch_delay

340

CHR_receiver_set_use_e1_e2_values

341

Multicast Group Object Functions

342

CHR_mgroup_add_mpair

343

CHR_mgroup_copy

344

CHR_mgroup_delete

346

CHR_mgroup_disable

347

CHR_mgroup_get_appl_script_name

348

CHR_mgroup_get_comment

349

CHR_mgroup_get_console_e1_addr

350

CHR_mgroup_get_console_e1_protocol

351

CHR_mgroup_get_console_e1_qos_name

352

CHR_mgroup_get_e1_addr

354

CHR_mgroup_get_e1_config_value

355

CHR_mgroup_get_mpair

357

CHR_mgroup_get_mpair_count

358

CHR_mgroup_get_multicast_addr

359

CHR_mgroup_get_multicast_port

360

CHR_mgroup_get_name

361

CHR_mgroup_get_payload_file

362

-9-

IxChariot APIGuide

CHR_mgroup_get_protocol

364

CHR_mgroup_get_qos_name

365

CHR_mgroup_get_script_embedded_payload

366

CHR_mgroup_get_script_filename

368

CHR_mgroup_get_script_variable

369

CHR_mgroup_get_use_console_e1_values

371

CHR_mgroup_is_disabled

372

CHR_mgroup_is_udp_RFC768_streaming

373

CHR_mgroup_new

374

CHR_mgroup_remove_mpair

375

CHR_mgroup_set_comment

376

CHR_mgroup_set_console_e1_addr

377

CHR_mgroup_set_console_e1_protocol

378

CHR_mgroup_set_console_e1_qos_name

379

CHR_mgroup_set_e1_addr

380

CHR_mgroup_set_script_embedded_payload

381

CHR_mgroup_set_lock

383

CHR_mgroup_set_multicast_addr

385

CHR_mgroup_set_multicast_port

387

CHR_mgroup_set_name

388

CHR_mgroup_set_payload_file

389

CHR_mgroup_set_protocol

391

CHR_mgroup_set_qos_name

392

CHR_mgroup_set_script_variable

393

CHR_mgroup_set_use_console_e1_values

396

CHR_mgroup_use_script_filename

397

Multicast Pair Object Functions

398

CHR_mpair_delete

399

CHR_mpair_get_e2_addr

400

CHR_mpair_get_e2_config_value

401

CHR_mpair_get_runStatus

403

CHR_mpair_get_setup_e1_e2_addr

405

- 10 -

IxChariot APIGuide

CHR_mpair_get_timing_record

406

CHR_mpair_get_timing_record_count

407

CHR_mpair_get_use_setup_e1_e2_values

408

CHR_mpair_new

409

CHR_mpair_set_e2_addr

410

CHR_mpair_set_lock

411

CHR_mpair_set_setup_e1_e2_addr

413

CHR_mpair_set_use_setup_e1_e2_values

414

Pair Object Functions

415

CHR_pair_copy

416

CHR_pair_delete

418

CHR_pair_disable

419

CHR_pair_get_appl_script_name

420

CHR_pair_get_comment

421

CHR_pair_get_console_e1_addr

422

CHR_pair_get_console_e1_protocol

423

CHR_pair_get_console_e1_qos_name

424

CHR_pair_get_e1_addr

426

CHR_pair_get_e1_config_value

427

CHR_pair_get_e2_addr

429

CHR_pair_get_e2_config_value

430

CHR_pair_get_payload_file

432

CHR_pair_get_protocol

434

CHR_pair_get_qos_name

435

CHR_pair_get_e1_qos_name

436

CHR_pair_get_e2_qos_name

437

CHR_pair_get_runStatus

438

CHR_pair_get_script_embedded_payload

440

CHR_pair_get_script_filename

442

CHR_pair_get_script_variable

443

CHR_pair_get_setup_e1_e2_addr

445

CHR_pair_get_timing_record

446

- 11 -

IxChariot APIGuide

CHR_pair_get_timing_record_count

447

CHR_pair_get_use_console_e1_values

448

CHR_pair_get_use_setup_e1_e2_values

449

CHR_pair_is_disabled

450

CHR_pair_is_udp_RFC768_streaming

451

CHR_pair_new

452

CHR_pair_set_comment

453

CHR_pair_set_console_e1_addr

454

CHR_pair_set_console_e1_protocol

455

CHR_pair_set_console_e1_qos_name

456

CHR_pair_set_e1_addr

457

CHR_pair_set_e2_addr

458

CHR_pair_set_lock

459

CHR_pair_set_payload_file

461

CHR_pair_set_protocol

463

CHR_pair_set_qos_name

465

CHR_pair_set_e1_qos_name

466

CHR_pair_set_e2_qos_name

467

CHR_pair_set_script_embedded_payload

468

CHR_pair_set_script_variable

470

CHR_pair_set_setup_e1_e2_addr

474

CHR_pair_set_use_console_e1_values

475

CHR_pair_use_script_filename

476

CHR_pair_set_use_setup_e1_e2_values

478

CHR_pair_swap_endpoints

479

Hardware Performance Pair Object Functions

480

CHR_hardware_pair_get_line_rate

481

CHR_hardware_pair_get_override_line_rate

482

CHR_hardware_pair_get_measure_statistics

483

CHR_hardware_pair_new

484

CHR_hardware_voip_pair_new

485

CHR_hardware_pair_set_line_rate

486

- 12 -

IxChariot APIGuide

CHR_hardware_pair_set_override_line_rate

487

CHR_hardware_pair_set_measure_statistics

488

Ixia Network Configuration Functions

489

CHR_test_clear_ixia_network_configuration

490

CHR_test_get_ixia_network_configuration

491

CHR_test_load_ixia_network_configuration

492

CHR_test_save_ixia_network_configuration

493

CHR_test_set_ixia_network_configuration

494

Pair/MPair Results Extraction Functions

495

CHR_pair_results_get_95pct_confidence

496

CHR_pair_results_get_average

498

CHR_pair_results_get_CPU_util_e1

500

CHR_pair_results_get_CPU_util_e2

501

CHR_pair_results_get_maximum

502

CHR_pair_results_get_minimum

504

CHR_pair_results_get_rel_precision

506

Report Object Functions

507

CHR_report_get_item_type

508

CHR_report_get_join_latency

509

CHR_report_get_leave_latency

510

CHR_report_get_report_group_id

511

Run Options Object Functions

512

CHR_runopts_get_allow_pair_reinit

513

CHR_runopts_get_allow_pair_reinit_run

514

CHR_runopts_get_apply_dod_only

515

CHR_runopts_get_clksync_external

516

CHR_runopts_get_clksync_hardware_ts

517

CHR_runopts_get_collect_tcp_statistics

518

CHR_runopts_get_connect_timeout

519

CHR_runopts_get_CPU_util

520

CHR_runopts_get_deconfigure_ports

521

CHR_runopts_get_fewer_setup_connections

522

- 13 -

IxChariot APIGuide

CHR_runopts_get_force_reporting_ack

523

CHR_runopts_get_HW_timestamps

524

CHR_runopts_get_init_recv_timeout

525

CHR_runopts_get_management_qos_console_name

526

CHR_runopts_get_management_qos_endpoint_name

527

CHR_runopts_get_num_result_ranges

528

CHR_runopts_get_overlapped_sends_count

529

CHR_runopts_get_pair_reinit_max

530

CHR_runopts_get_pair_reinit_max_run

531

CHR_runopts_get_pair_reinit_retry_interval

532

CHR_runopts_get_pair_reinit_retry_interval_run

533

CHR_runopts_get_poll_endpoints

534

CHR_runopts_get_poll_interval

535

CHR_runopts_get_poll_retrieving_type

536

CHR_runopts_get_random_new_seed

537

CHR_runopts_get_reporting_firewall

538

CHR_runopts_get_reporting_type

539

CHR_runopts_get_result_range

540

CHR_runopts_get_stop_after_num_pairs_fail

542

CHR_runopts_get_stop_on_init_failure

543

CHR_runopts_get_test_duration

544

CHR_runopts_get_test_end

545

CHR_runopts_get_validate_on_recv

546

CHR_runopts_set_allow_pair_reinit

547

CHR_runopts_set_allow_pair_reinit_run

548

CHR_runopts_set_apply_dod_only

549

CHR_runopts_set_clksync_external

550

CHR_runopts_set_clksync_hardware_ts

551

CHR_runopts_set_collect_tcp_statistics

553

CHR_runopts_set_connect_timeout

555

CHR_runopts_set_CPU_util

556

CHR_runopts_set_deconfigure_ports

557

- 14 -

IxChariot APIGuide

CHR_runopts_set_force_reporting_ack

558

CHR_runopts_set_fewer_setup_connections

559

CHR_runopts_set_HW_timestamps

560

CHR_runopts_set_init_recv_timeout

561

CHR_runopts_set_management_qos_console_name

562

CHR_runopts_set_management_qos_endpoint_name

563

CHR_runopts_set_num_result_ranges

564

CHR_runopts_set_overlapped_sends_count

566

CHR_runopts_set_pair_reinit_max

567

CHR_runopts_set_pair_reinit_max_run

568

CHR_runopts_set_pair_reinit_retry_interval

569

CHR_runopts_set_pair_reinit_retry_interval_run

570

CHR_runopts_set_poll_endpoints

571

CHR_runopts_set_poll_interval

572

CHR_runopts_set_poll_retrieving_type

573

CHR_runopts_set_random_new_seed

574

CHR_runopts_set_reporting_firewall

575

CHR_runopts_set_reporting_type

576

CHR_runopts_set_result_range

577

CHR_runopts_set_stop_after_num_pairs_fail

579

CHR_runopts_set_stop_on_init_failure

580

CHR_runopts_set_test_duration

581

CHR_runopts_set_test_end

582

CHR_runopts_set_validate_on_recv

583

Test Object Functions

584

CHR_test_abandon

585

CHR_test_add_app_group

586

CHR_test_add_channel

588

CHR_test_add_mgroup

589

CHR_test_add_pair

590

CHR_test_add_receiver

591

CHR_test_clear_results

592

- 15 -

IxChariot APIGuide

CHR_test_delete

593

CHR_test_force_delete

594

CHR_test_get_app_group_by_index

595

CHR_test_get_app_group_by_name

596

CHR_test_get_app_group_count

597

CHR_test_get_channel

598

CHR_test_get_channel_by_name

599

CHR_test_get_channel_count

600

CHR_test_get_dgopts

601

CHR_test_get_filename

602

CHR_test_get_grouping

603

CHR_test_get_how_ended

604

CHR_test_get_local_start_time

605

CHR_test_get_local_stop_time

606

CHR_test_get_mgroup

607

CHR_test_get_mgroup_count

608

CHR_test_get_pair

609

CHR_test_get_pair_count

610

CHR_test_get_receiver

611

CHR_test_get_receiver_by_name

612

CHR_test_get_receiver_count

613

CHR_test_get_runopts

614

CHR_test_get_start_time

615

CHR_test_get_stop_time

616

CHR_test_get_test_server_session

617

CHR_test_get_throughput_units

619

CHR_test_load

620

CHR_test_load_app_groups

622

CHR_test_new

624

CHR_test_query_stop

625

CHR_test_remove_app_group

626

CHR_test_remove_channel

627

- 16 -

IxChariot APIGuide

CHR_test_remove_receiver

628

CHR_test_save

629

CHR_test_set_filename

630

CHR_test_set_grouping_order

632

CHR_test_set_grouping_type

633

CHR_test_set_test_server_session

635

CHR_test_set_throughput_units

637

CHR_test_start

638

CHR_test_stop

640

Timing Record Object Functions

641

CHR_timingrec_get_df

642

CHR_timingrec_get_e1_BSSID

643

CHR_timingrec_get_e1_RSSI

644

CHR_timingrec_get_e2_BSSID

645

CHR_timingrec_get_e2_RSSI

646

CHR_timingrec_get_elapsed

647

CHR_timingrec_get_end_to_end_delay

648

CHR_timingrec_get_inactive

649

CHR_timingrec_get_jitter

650

CHR_timingrec_get_max_consecutive_lost

651

CHR_timingrec_get_max_delay_variation

652

CHR_timingrec_get_mlr

653

CHR_timingrec_get_one_way_delay

655

CHR_timingrec_get_R_value

656

CHR_timingrec_get_report_group_id

657

CHR_timingrec_get_result_frequency

658

Traceroute Pair Object Functions

659

CHR_tracert_pair_delete

660

CHR_tracert_pair_get_e1_addr

661

CHR_tracert_pair_get_e2_addr

662

CHR_tracert_pair_get_hop_record

663

CHR_tracert_pair_get_max_hops

664

- 17 -

IxChariot APIGuide

CHR_tracert_pair_get_max_timeout

665

CHR_tracert_pair_get_resolve_hop_name

666

CHR_tracert_pair_get_runStatus

667

CHR_tracert_pair_new

668

CHR_tracert_pair_query_stop

669

CHR_tracert_pair_results_get_hop_count

670

CHR_tracert_pair_run

671

CHR_tracert_pair_set_e1_addr

672

CHR_tracert_pair_set_e2_addr

673

CHR_tracert_pair_set_max_hops

674

CHR_tracert_pair_set_max_timeout

675

CHR_tracert_pair_set_resolve_hop_name

676

CHR_tracert_pair_stop

677

Video Multicast Group Object Functions

678

CHR_video_mgroup_get_bitrate

679

CHR_video_mgroup_get_codec

680

CHR_video_mgroup_get_frames_per_datagram

681

CHR_video_mgroup_pair_get_initial_delay

682

CHR_video_mgroup_get_media_frame_size

683

CHR_video_mgroup_get_no_of_timing_records

684

CHR_video_mgroup_get_rtp_payload_type

685

CHR_video_mgroup_get_source_port_num

686

CHR_video_mgroup_get_tr_duration

687

CHR_video_mgroup_new

688

CHR_video_mgroup_set_bitrate

689

CHR_video_mgroup_set_codec

691

CHR_video_mgroup_set_frames_per_datagram

692

CHR_video_mgroup_pair_set_initial_delay

693

CHR_video_mgroup_set_media_frame_size

694

CHR_video_mgroup_set_no_of_timing_record

695

CHR_video_mgroup_set_rtp_payload_type

696

CHR_video_mgroup_set_source_port_num

697

- 18 -

IxChariot APIGuide

CHR_video_mgroup_set_tr_duration
Video Pair Object Functions

698
699

CHR_video_pair_get_bitrate

700

CHR_video_pair_get_codec

701

CHR_video_pair_get_dest_port_num

702

CHR_video_pair_get_frames_per_datagram

703

CHR_video_pair_get_initial_delay

704

CHR_video_pair_get_media_frame_size

705

CHR_video_pair_get_no_of_timing_records

706

CHR_video_pair_get_rtp_payload_type

707

CHR_video_pair_get_source_port_num

708

CHR_video_pair_get_tr_duration

709

CHR_video_pair_new

710

CHR_video_pair_set_bitrate

711

CHR_video_pair_set_codec

713

CHR_video_pair_set_dest_port_num

714

CHR_video_pair_set_frames_per_datagram

715

CHR_video_pair_set_initial_delay

716

CHR_video_pair_set_media_frame_size

717

CHR_video_pair_set_no_of_timing_record

718

CHR_video_pair_set_rtp_payload_type

719

CHR_video_pair_set_source_port_num

720

CHR_video_pair_set_tr_duration

721

VoIP Pair Object Functions

722

CHR_voip_pair_get_additional_delay

723

CHR_voip_pair_get_codec

724

CHR_voip_pair_get_concurrent_voice_streams

725

CHR_voip_pair_get_datagram_delay

726

CHR_voip_pair_get_dest_port_num

727

CHR_voip_pair_get_initial_delay

728

CHR_voip_pair_get_jitter_buffer_size

729

CHR_voip_pair_get_source_port_num

730

- 19 -

IxChariot APIGuide

CHR_voip_pair_get_tr_duration

731

CHR_voip_pair_get_no_of_timing_records

732

CHR_voip_pair_get_use_PLC

733

CHR_voip_pair_get_use_silence_sup

734

CHR_voip_pair_get_voice_activ_rate

735

CHR_voip_pair_get_payload_file

736

CHR_voip_pair_new

738

CHR_voip_pair_set_additional_delay

739

CHR_voip_pair_set_codec

740

CHR_voip_pair_set_concurrent_voice_streams

741

CHR_voip_pair_set_datagram_delay

742

CHR_voip_pair_set_dest_port_num

743

CHR_voip_pair_set_initial_delay

744

CHR_voip_pair_set_jitter_buffer_size

745

CHR_voip_pair_set_no_of_timing_records

746

CHR_voip_pair_set_payload_file

747

CHR_voip_pair_set_payload_random

749

CHR_voip_pair_set_source_port_num

750

CHR_voip_pair_set_tr_duration

751

CHR_voip_pair_set_use_PLC

752

CHR_voip_pair_set_use_silence_sup

753

CHR_voip_pair_set_voice_activ_rate

754

Typedefs and Enumerations

755

Chapter 5: Tcl Reference

833

IxChariot API Objects

834

Error Returns in Tcl

835

Extended Error Information

836

Run Environment

837

Debugging Tips

838

Package Initialization

839

Tcl Version 8.0

839

Tcl Version 8.x

839

- 20 -

IxChariot APIGuide

Licensing API - Initialization with license details from TCL scripts

Chapter 6: Tcl Functions

841
842

API Utility Command

843

chrApi deleteQosTemplate

844

chrApi getDetail

845

chrApi getLicenseExpirationTime

846

chrApi getLicenseType

847

chrApi getMaxPairs

848

chrApi getNetworkIPLIst

849

chrApi getPairType

850

chrApi getPortMgmtIPLIst

851

chrApi getReportingPort

852

chrApi getReturnMsg

853

chrApi getVersion

854

chrApi licenseChangeBorrowTime

855

chrApi licenseChangeLicenseServer

856

chrApi licenseCheckinPairs

857

chrApi licenseCheckoutPairs

858

chrApi licenseGetBorrowDaysRemaining

859

chrApi licenseGetLicenseServer

860

chrApi licenseGetTestPairCount

861

chrApi modifyQosTosTemplate

862

chrApi newQosTosTemplate

863

chrApi setDetail

864

chrApi setReportingPort

865

Application Group Object Command

866

chrAppGroup addEvent

867

chrAppGroup addPair

868

chrAppGroup copy

869

chrAppGroup delete

870

chrAppGroup getAddress

871

chrAppGroup get

872

- 21 -

IxChariot APIGuide

chrAppGroup getCount

874

chrAppGroup getEventComment

875

chrAppGroup getEventName

876

chrAppGroup getPair

877

chrAppGroup new

879

chrAppGroup removeEvent

880

chrAppGroup removePair

881

chrAppGroup save

882

chrAppGroup setAddress

883

chrAppGroup set

884

chrAppGroup setPair

885

chrAppGroup validate

887

Common Error Command

888

chrCommonError getInfo

889

chrCommonError getMsgNum

891

Common Results Extraction Command

chrCommonResults get

892
893

Datagram Options Object Command

898

chrDgOpts get

899

chrDgOpts set

901

Hop Record Object Command

903

chrHopRec get

904

IPTV Channel Object Commands

905

chrChannel delete

906

chrChannel get

907

chrChannel new

910

chrChannel set

911

IPTV Pair Object Command

914

chrVPair delete

915

chrVPair get

916

chrVPair getReport

918

chrVPair getReportCount

919

- 22 -

IxChariot APIGuide

chrVPair getTimingRecord

920

chrVPair getTimingRecordCount

921

chrVPair new

922

chrVPair set

923

IPTV Receiver Object Commands

925

chrReceiver addVPair

926

chrReceiver delete

927

chrReceiver get

928

chrReceiver getVPair

930

chrReceiver getVPairCount

931

chrReceiver new

932

chrReceiver removeVPair

933

chrReceiver set

934

Multicast Group Object Command

937

chrMGroup addMPair

938

chrMGroup copy

939

chrMGroup delete

940

chrMGroup get

941

chrMGroup getEndpointConfig

943

chrMGroup getMPair

945

chrMGroup getMPairCount

946

chrMGroup getPayloadFile

947

chrMGroup getPayloadFileIsEmbedded

948

chrMGroup getScriptEmbeddedPayload

949

chrMGroup getScriptVar

950

chrMGroup new

951

chrMGroup removeMPair

952

chrMGroup set

953

chrMGroup setPayloadFile

956

chrMGroup setScriptEmbeddedPayload

958

chrMGroup setScriptVar

959

chrMGroup useScript

962

- 23 -

IxChariot APIGuide

Multicast Pair Object Command

963

chrMPair delete

964

chrMPair get

965

chrMPair getEndpointConfig

967

chrMPair getTimingRecord

969

chrMPair getTimingRecordCount

970

chrMPair new

971

chrMPair set

972

Pair Object Command

974

chrPair copy

975

chrPair delete

976

chrPair get

977

chrPair getEndpointConfig

980

chrPair getPayloadFile

982

chrPair getPayloadFileIsEmbedded

983

chrPair getScriptEmbeddedPayload

984

chrPair getScriptVar

985

chrPair getTimingRecord

986

chrPair getTimingRecordCount

987

chrPair new

988

chrPair set

989

chrPair setPayloadFile

992

chrPair setScriptEmbeddedPayload

994

chrPair setScriptVar

995

chrPair useScript

998

chrPair swapEndpoints

999

Hardware Performance Pair Object Commands

1000

chrHardwarePair get

1001

chrHardwarePair new

1002

chrHardwarePair set

1003

Pair/Mpair Results Extraction Command

chrPairResults get

1005
1006

- 24 -

IxChariot APIGuide

chrPairResults get95PctConfidence

1010

Report Object Commands

1011

chrReport get

1012

Run Options Object Command

1013

chrRunOpts get

1014

chrRunOpts getNumResultRanges

1017

chrRunOpts getResultRange

1018

chrRunOpts set

1019

chrRunOpts setNumResultRanges

1025

chrRunOpts setResultRange

1026

Test Object Command

1028

chrTest abandon

1029

chrTest addAppGroup

1030

chrTest addChannel

1031

chrTest addMGroup

1032

chrTest addPair

1033

chrTest addReceiver

1034

chrTest clearIxiaConfiguration

1035

chrTest clearResults

1036

chrTest delete

1037

chrTest get

1038

chrTest getAppGroupByIndex

1040

chrTest getAppGroupByName

1041

chrTest getAppGroupCount

1042

chrTest getChannel

1043

chrTest getChannelByName

1044

chrTest getChannelCount

1045

chrTest getDgOpts

1046

chrTest getGroupingOrder

1047

chrTest getGroupingType

1048

chrTest getMGroup

1049

chrTest getMGroupCount

1050

- 25 -

IxChariot APIGuide

chrTest getPair

1051

chrTest getPairCount

1052

chrTest getReceiver

1053

chrTest getReceiverByName

1054

chrTest getReceiverCount

1055

chrTest getTestServerSession

1056

chrTest isStopped

1057

chrTest load

1058

chrTest loadAppGroups

1059

chrTest loadIxiaConfiguration

1060

chrTest new

1061

chrTest removeAppGroup

1062

chrTest removeChannel

1063

chrTest removeReceiver

1064

chrTest save

1065

chrTest saveIxiaConfiguration

1066

chrTest set

1067

chrTest setGroupingOrder

1069

chrTest setGroupingType

1070

chrTest setTestServerSession

1071

chrTest start

1072

chrTest stop

1073

Timing Record Object Command

1074

chrTimingRec get

1075

chrTimingRec getResultFrequency

1077

Traceroute Pair Object Command

1079

chrTracertPair delete

1080

chrTracertPair get

1081

chrTracertPair getHopRecord

1083

chrTracertPair getHopRecordCount

1084

chrTracertPair isStopped

1085

chrTracertPair new

1086

- 26 -

IxChariot APIGuide

chrTracertPair run

1087

chrTracertPair set

1088

chrTracertPair stop

1090

Video Multicast Group Object Commands

1091

chrVideoMGroup get

1092

chrVideoMGroup new

1094

chrVideoMGroup set

1095

Video Pair Object Commands

1097

chrVideoPair get

1098

chrVideoPair new

1100

chrVideoPair set

1101

VoIP Pair Object Command

1104

chrVoIPPair get

1105

chrVoIPPair new

1107

chrVoIPPair set

1108

chrVoIPPair setPayloadFile

1111

chrVoIPPair setPayloadRandom

1113

VoIP Hardware Performance Pair Object Commands

1114

chrHardwareVoipPair get

1115

chrHardwareVoipPair new

1116

chrHardwareVoipPair set

1117

Chapter 7: The Stack Manager Tcl API Script Examples

Using the Tcl Scripts

1118
1118

Script Setup

1118

Sample IP Script

1120

Test Topology

1120

Plugin Layout

1120

IP Plugin Test Tcl Script Listing

1120

GUI Representation

1126

Sample MAC Range Script

1127

Test Topology

1127

Plugin Layout

1127

- 27 -

IxChariot APIGuide

MAC Range Tcl Script Listing

1127

GUI Representation

1133

Sample DHCP Script

1135

Test Topology

1135

Plugin Layout

1135

DHCP Tcl Script Listing

1135

GUI Representation

1141

Sample Impairment Script

1142

Test Topology

1142

Plugin Layout

1142

Impairment Test Tcl Script Listing

1142

GUI Representation

1148

Sample IPSec Script (port-to-port)

1150

Test Topology

1150

Plugin Layout

1150

IPSec Port-to-Port Tcl Script Listing

1150

GUI Representation

1157

Sample IPSec Script (port-to-DUT)

1158

Test Topology

1158

Plugin Layout

1158

IPSec Port-to-DUT Tcl Script Listing

1158

Sample PPP Script (port-to-port)

1166

Test Topology

1166

Plugin Layout

1166

PPP Port-to-Port Tcl Script Listing

1166

GUI Representation

1172

Sample PPP Script (port-to-DUT)

1173

Test Topology

1173

Plugin Layout

1173

PPP Port-to-Port Tcl Script Listing

1173

Appendix A: Return Code Summary

1180

0 CHR_OK

1181

- 28 -

IxChariot APIGuide

Message Returned

1181

Explanation

1181

Action Required

1181

101 CHR_HANDLE_INVALID

1182

Message Returned

1182

Explanation

1182

Action Required

1182

139 CHR_NO_APPLIFIER_CONFIGURATION

1183

Explanation

1183

Action Required

1183

138 CHR_PAYLOAD_FILE_TOO_LARGE

1184

Explanation

1184

Action Required

1184

137 CHR_APP_GROUP_DUPLICATE_NAME

1185

Explanation

1185

Action Required

1185

136 CHR_APP_GROUP_INVALID

1186

Explanation

1186

Action Required

1186

135 CHR_APP_GROUP_NOT_VALIDATED

1187

Explanation

1187

Action Required

1187

134 CHR_LICENSE_WILL_EXPIRE

1188

Explanation

1188

Action Required

1188

133 CHR_TEST_NOT_SAVED

1189

Explanation

1189

Action Required

1189

132 CHR_FUNCTION_NOT_SUPPORTED

1190

Explanation

1190

Action Required

1190

131 CHR_ERROR_ACCESSING_TESTSERVER_SESSION

- 29 -

1191

IxChariot APIGuide

Explanation

1191

Action Required

1191

130 CHR_INVALID_NETWORK_CONFIGURATION

1192

Explanation

1192

Action Required

1192

129 CHR_NO_NETWORK_CONFIGURATION

1193

Explanation

1193

Action Required

1193

128 CHR_LICENSE_HAS_EXPIRED

1194

Explanation

1194

Action Required

1194

127 CHR_SCRIPT_TOO_LARGE

1195

Explanation

1195

Action Required

1195

126 CHR_NOT_LICENSED

1196

Explanation

1196

Action Required

1196

125 CHR_NO_CODEC_IN_USE

1197

Message Returned

1197

Explanation

1197

Action Required

1197

124 CHR_NOT_SUPPORTED

1198

Message Returned

1198

Explanation

1198

Action Required

1198

123 CHR_TRACERT_RUNNING

1199

Message Returned

1199

Explanation

1199

Action Required

1199

122 CHR_TRACERT_NOT_RUN

1200

Message Returned

1200

Explanation

1200

- 30 -

IxChariot APIGuide

Action Required

1200

121 CHR_PGM_INTERNAL_ERROR

1201

Message Returned

1201

Explanation

1201

Action Required

1201

120 CHR_NO_MEMORY

1202

Message Returned

1202

Explanation

1202

Action Required

1202

119 CHR_BUFFER_TOO_SMALL

1203

Message Returned

1203

Explanation

1203

Action Required

1203

118 CHR_TIMED_OUT

1204

Message Returned

1204

Explanation

1204

Action Required

1204

117 CHR_NO_SCRIPT_IN_USE

1205

Message Returned

1205

Explanation

1205

Action Required

1205

116 CHR_NO_SUCH_VALUE

1206

Message Returned

1206

Explanation

1206

Action Required

1206

115 CHR_VALUE_INVALID

1207

Message Returned

1207

Explanation

1207

Action Required

1207

114 CHR_NO_RESULTS

1208

Message Returned

1208

Explanation

1208

- 31 -

IxChariot APIGuide

Action Required

1208

113 CHR_API_NOT_INITIALIZED

1209

Message Returned

1209

Explanation

1209

Action Required

1209

112 CHR_OBJECT_INVALID

1210

Message Returned

1210

Explanation

1210

Action Required

1210

111 CHR_PAIR_LIMIT_EXCEEDED

1211

Message Returned

1211

Explanation

1211

Action Required

1211

110 CHR_RESULTS_NOT_CLEARED

1212

Message Returned

1212

Explanation

1212

Action Required

1212

109 CHR_NO_TEST_FILE

1213

Message Returned

1213

Explanation

1213

Action Required

1213

108 CHR_OPERATION_FAILED

1214

Message Returned

1214

Explanation

1214

Action Required

1214

107 CHR_OBJECT_IN_USE

1215

Message Returned

1215

Explanation

1215

Action Required

1215

106 CHR_TEST_RUNNING

1216

Message Returned

1216

Explanation

1216

- 32 -

IxChariot APIGuide

Action Required

1216

105 CHR_TEST_NOT_RUN

1217

Message Returned

1217

Explanation

1217

Action Required

1217

104 CHR_NO_SUCH_OBJECT

1218

Message Returned

1218

Explanation

1218

Action Required

1218

103 CHR_POINTER_INVALID

1219

Message Returned

1219

Explanation

1219

Action Required

1219

102 CHR_STRING_TOO_LONG

1220

Message Returned

1220

Explanation

1220

Action Required

1220

140 CHR_CHANNEL_DUPLICATE_NAME

1221

Explanation

1221

Action Required

1221

141 CHR_RECEIVER_DUPLICATE_NAME

1222

Explanation

1222

Action Required

1222

142 CHR_IPTV_INVALID

1223

Explanation

1223

Action Required

1223

143 CHR_DUPLICATE_NAME

1224

Explanation

1224

Action Required

1224

144 CHR_LICENSE_ALREADY_BORROWED

1225

Explanation

1225

Action Required

1225

- 33 -

IxChariot APIGuide

Index

1226

- 34 -

IxChariot APIGuide

About This Book

The API Guide provides a reference for users of the IxChariot product. This book defines
terminology and various related concepts.

Intended Audience
This book provides information for individuals responsible for writing programs to the
IxChariot Application Programming Interface (API) and for individuals trying to understand
more about how IxChariot works.

The IxChariot Documentation Suite

The IxChariot documentation suite includes the following manuals:
l

Getting Started with IxChariot

Contains detailed instructions for installing and registering IxChariot. This guide also
provides an overview of the IxChariot user interfaces and includes simple examples of test
setup and execution.
l

IxChariot User Guide

Contains comprehensive guidance for using IxChariot, including test definition, test execution, and test results analysis.
l

IxChariot Runtime User Guide

Describes the IxChariot features that are included in the IxChariot Runtime product.
l

IxChariot Performance Endpoints

Provides step-by-step guidance for installing and configuring Performance Endpoints for different operating systems.
l

IxChariot Scripts and Streams Library Reference

Provides a detailed description of each of the IxChariot scripts and the Ixia streams that
are provided with IxChariot.
l

IxChariot Scripts Development and Editing Guide

Provides step-by-step guidance for creating and editing IxChariot scripts.

l

IxChariot API Reference (this guide)

Provides information about writing C programs or Tcl scripts to the IxChariot application
programming interface that use and extend the capabilities of IxChariot.
The following additional manuals are provided for customers who are using Ixia chassis in
their testing:
l

Stack Manager User Guide

Stack Manager API Reference

The IxChariot manuals are provided in CHM and PDF format.

The IxChariot manuals are provided in hardcopy and PDF format.

- 35 -

IxChariot APIGuide
The IxChariot Console also provides comprehensive context-sensitive online help.

Conventions
The library uses consistent conventions to help you identify items throughout the documentation. The following table summarizes these conventions.
C on v en tion

Use

Bold

Wi ndow and menu i tems. Techni cal ter ms,

when i ntr oduced.

Italics

Book and DVD-ROM ti tl es. Var i abl e names and

val ues. Emphasi zed wor ds

F i xed F ont

F i l e and f ol der names. Commands and code

exampl es. Text you must type. Text (output)
di spl ayed i n the command-l i ne i nter f ace.

Br ackets, such as
[val ue]

Opti onal par ameter s of a command

Br aces, such as
{val ue}

Requi r ed par ameter s of a command

Welcome
The IxChariot API lets you write programs or Tcl scripts that use and extend the capabilities of IxChariot. With the IxChariot API, you can write programs or Tcl scripts that do
the following:
l

Create tests

Run tests

Extract results from tests and perform additional processing

You cannot write programs that create new IxChariot scripts or modify the order of commands in IxChariot scripts.

What Can You Do with the Programs You Write?

Any programs or Tcl scripts that you write using the IxChariot API may be sold for profit or
given away without charge. However, you must not sell or give away any IxChariot .EXE or
.DLL files with your program or Tcl script. Any user who runs the programs or Tcl scripts
that you create must run them on a computer with a licensed version of IxChariot installed.

What You Need to Know

This manual assumes the following:
l
l

You are familiar with IxChariot and IxChariot terminology.

You are familiar with programming in C or Tcl and have a good understanding of data
structures and structured programming techniques.

- 36 -

IxChariot APIGuide

Overview
The IxChariot API lets you write C programs or Tcl scripts that drive the IxChariot engine.
As shown in the figure below, the C programs or Tcl scripts you write (shown in black background) use the API or the Tcl package to interact with the IxChariot engine, which contains the code that runs IxChariot tests and collects the results. Thus, by using the
IxChariot API, you can create tests, run tests, save tests, and extract results.
The IxChariot engine normally exists as a part of the IxChariot Console. The user interface
of the IxChariot Console communicates with the IxChariot engine to run tests and to
extract results from the tests. The API provides a well-defined external interface to the
core IxChariot functions implemented by the IxChariot engine. The following figure illustrates how the entire IxChariot package works together with the API and endpoints:

- 37 -

IxChariot APIGuide
The IxChariot API provides an object-based interface. Although an object-based interface
consists of objects, it does not have all the properties of an object-oriented interface, such
as inheritance and polymorphism. Implementation of an object-based interface does not
require an object-oriented language. Thus, the IxChariot API is implemented in C, which is
a procedural language. The Tcl package for the IxChariot API is implemented on top of the
IxChariot C API. An object-based implementation does not prevent the use of the API with
an object-oriented language such as C++. In fact, an object-based interface can easily be
encapsulated by a set of classes to provide an object-oriented interface.
The object-based IxChariot interface consists of a set of objects described in the following
topics. Some of the objects may be instantiated (or created) independently by a program,
whereas other objects, notably the datagram options and run options objects, may not be
instantiated independently. The datagram options and run options objects are only instantiated by the test object when the test object is instantiated.
The IxChariot API offers equivalent functions to both C programs and Tcl scripts. In C, each
object is implemented as a set of function calls. All the functions related to an object have
names similar to CHR_xxxx_yyyy(), where xxxx is the name of the object and yyyy is the
operation on the object. In Tcl, each object is implemented as a command and a set of subcommands. The command for a given object is similar to chrXxxx, where Xxxx is the name
of the object. In addition to functions and commands related to objects, the API also
provides utility and result-extraction functions and commands.

- 38 -

IxChariot APIGuide

Inter-Object Relationships
The objects in the IxChariot API are organized in a containment hierarchy. A containment
hierarchy identifies the objects that can be contained within other objects. The IxChariot
object containment hierarchy is shown in the figure below.
The test object is at the top of the containment hierarchy. The run options and datagram
options objects are always instantiated by a test object instance and remain a part of the
test object instance. The following objects are instantiated independently of test objects
and are added to a test object instance:
l

pair

hardware pair

VoIP pair

VoIP hardware pair

application group

video pair

multicast group

video multicast group

multicast pair

channel

receiver

Before a test can be run, it must contain at least one instance of a pair, hardware pair,
VoIP pair, video pair, multicast group, or video multicast group object. A multicast group
object instance must have at least one instance of a multicast pair object before it can be
added to a test object instance.
The traceroute pair object is independent of the test object. It contains the hop record
object.
The timing record object instances are created when the test is run and cannot be instantiated independently.
Once an object instance has been added to another object instance, it cannot be changed
or deleted.

- 39 -

IxChariot APIGuide

- 40 -

IxChariot APIGuide

Error Checking Done by API

This section describes the error checking that is done by the C and Tcl APIs.

License Checking
A floating license may expire while a Tcl shell is active. Further attempts to use the
licensed feature will generate an error indicating that the licensed feature is not available,
even after a new license has been obtained. It is necessary to restart the Tcl shell in order
to run the program.
It is recommended that Tcl scripts should be run from the command line, using the "tclsh
<script name>" syntax. For example:
c:\Program Files\Ixia\IxChariot>tclsh myTest.tcl
This syntax is preferable to starting the Tcl shell from the command prompt and issuing
successive "source <script name>" commands within this shell. If you do not have a valid
license, and you run a Tcl script using successive "source" statements within the Tcl shell,
IxChariot returns a CHR0315 error the first time that you run the script. However, for each
successive "source" statement, IxChariot returns an "API initialization failed" message
rather than the more precise CHR0315 error.

Argument Validation
The IxChariot API performs various checks on the arguments passed to the functions or
commands. See Return Code Summary to get a complete listing of errors detected by the
API. Some of the important error checks performed by the API are:
n

All parameters are checked to ensure that they are in the valid range.

Required pointer parameters are checked to ensure that they are valid. Pointers
to optional parameters may be NULL. This does not apply to the Tcl package.

All handles are checked to ensure that they are valid and refer to an object
instance of the required type.

- 41 -

IxChariot APIGuide

Management Addresses with Stack Manager

The default values for management addresses require special attention when the following
conditions are in effect:
l

You are using Ixia ports in a test, and

you are using Stack Manager to configure and assign those ports, and

your test uses any of the following types of objects:

n

regular pairs

VoIP pairs

video pairs

multicast pairs

Normally, the default values for the "Use Setup E1 E2" and "Use Console to Endpoint 1 values" parameters are both FALSE. However, under the conditions listed above, the API will
set these values to TRUE and will automatically set the management addresses based on
the Stack Manager configuration, unless you explicitly set either or both of the values to
FALSE.
Allowing the API to set the management addressed is the recommended approach for most
customers. In this case, the endpoints will use the management network to pass all management data and test results, and no further action is needed.
However, if you wish to use the test network (rather than the management network) to
transmit setup data or test results data, you must take either or both of the following
actions:
l

Set the "Use Setup E1 E2" parameter to FALSE if you want the endpoints to use the
test network to exchange management data.
Set the "Use Console to Endpoint 1 values" parameter to FALSE if you want the Console and Endpoint1 to use the test network to exchange management data.

The following Tcl script demonstrates how you would configure a test to use the test network to transmit management traffic between Endpoint1 and Endpoint2:
load C hariot Ex t
s et t es t [ c hrTes t new ]
s et pair [ c hrPair new ]
c hrTes t loadI x iaC onf igurat ion $t es t my c onf ig. ix n
c hrP ai r s et $pai r E 1_A D D R 172. 16. 1. 1
c hrP ai r s et $pai r E 2_A D D R 172. 16. 2. 1
c hrPair us eSc ript $pair Sc ript s / t hroughput . s c r
# S et t i ng U S E _ S E T U P _ E 1_E 2 t o F A LS E t o prev ent aut om at i c
# management addres s ex pans ion w hen adding a pair t o a
# t es t :
#
c hrP ai r s et $pai r U S E _ S E T U P _ E 1_E 2 0
# The f ollow ing get s t at ement w ill ret urn < N one> :
c hrP ai r get $pai r S E T U P _ E 1_E 2_ A D D R
#
# The API w ill us e Endpoint 2 as t he management addres s .

- 42 -

IxChariot APIGuide
Note that management addresses based on a Stack Manager configuration use a format
that designates the chassis, card, and port on which the address is configured. For
example:
192. 168. 7. 41 / 01 / 03
In this example, 192.168.7.41 is the IP address of the chassis, /01 designates card1 in the
chassis, and /03 designates port 3 on that card.

- 43 -

IxChariot APIGuide

Stopping a Running Test

The API provides methods for querying a running test to see if it has completed and for
stopping a running test. These include:
l

CHR_test_stop

CHR_test_query_stop

chrTest isStopped

chrTest abandon

chrTest stop

While a test appears to be running, use the function CHR_test_query_stop in C or in Tcl to

find out the test status. In C, the function CHR_test_stop stops the test, and if this function
fails, CHR_test_abandon cuts the connection between the Console and Endpoint 1. The corresponding commands in Tcl are ChrTest stop and ChrTest abandon. The abandon command should be used rarely because it may prevent test resources from being
relinquished.
However, it's important to recognize that abandoning a test or closing an API program
while a test is running does not guarantee that the endpoints have stopped executing their
script. The endpoints work independently after they receive their test setup instructions
from an API program. And therefore, if you terminate your API program while a test is running, the Endpoint 1 computers may still try to report their results to the non-existent API
program once, before failing and discarding any queued results. If subsequent tests are
run before an Endpoint 1 program has discarded the results it can't return, the new results
may be delayed, queued behind the results of previous tests that Endpoint 1 is trying in
vain to return.

- 44 -

IxChariot APIGuide

Object Descriptions and Default Values

This section provides a summary description of each API object and lists their default values.

- 45 -

IxChariot APIGuide

Test Object
The test object represents an IxChariot test. The test object lets a program load an
IxChariot test file, run a test, and then extract results of a run. It is also possible to create
a new test and save it into an IxChariot test file that can later be manipulated by using the
IxChariot Console.
The test object is the root object in the containment hierarchy of the IxChariot objects.
Pair and multicast group object instances are contained within test object instances. In
addition, every test object instance contains the datagram and run options object instances
for the test.
At least one pair or multicast group must be added to the test before it can be run or
saved. The filename attribute must be set before the test can be saved.

- 46 -

IxChariot APIGuide

Test Object Default Values

Attribu te

Value

Throughput units

Mbits/sec

Pair count

Multicast group count

Run options

A default run options object instance

Datagram options

A default datagram options object instance

- 47 -

IxChariot APIGuide

Pair Object
The pair object represents an IxChariot pair. The pairs in multicast groups are represented
by the multicast pair object as described below. A pair object instance by itself is not very
useful. A pair object instance must be contained in a test object before any results for the
pair can be collected or extracted.
Pair object instances cannot be added to a multicast group, even if their attributes are set
to match the attributes of the multicast group.
Before a pair object instance can be added to a test object instance, the following attributes must be set:
1. Endpoint 1 address
2. Endpoint 2 address
3. IxChariot script filename.
Some pair function calls will accept a VoIP pair object. See VoIP Pair Object for more
information.

- 48 -

IxChariot APIGuide

Pair Object Default Values

The CHR_pair_set_*() function topics contain information on the Console to Endpoint 1
default values. See Pair Object Functions.
Attribu te

Value

Use Setup E1 E2

False

Protocol

TCP

Use Console to Endpoint 1 values

False

Timing record count

- 49 -

IxChariot APIGuide

Hardware Performance Pair Object

The hardware performance pair object represents an Ixia pair. A hardware performance
pair object instance by itself is not very useful. An object instance must be contained in a
test object before any results for the pair can be collected or extracted.
Hardware Performance Pair object instances cannot be added to a multicast group.
Before a pair object instance can be added to a test object instance, the following attributes must be set:
1. Port 1 address
2. Port 2 address
3. Port 1 management address
4. Port 2 management address
5. Override line rate
6. Line rate
7. Measure statistics flag.

- 50 -

IxChariot APIGuide

VoIP Hardware Performance Pair Object

The VoIP hardware performance pair object represents an Ixia pair. A VoIP hardware performance pair object instance by itself is not very useful. An object instance must be contained in a test object before any results for the pair can be collected or extracted.
VoIP Hardware Performance Pair object instances cannot be added to a multicast group.
Before a pair object instance can be added to a test object instance, the following attributes must be set:
1. Port 1 address
2. Port 2 address
3. Port 1 management address
4. Port 2 management address

- 51 -

IxChariot APIGuide

Hardware Performance Pair Object Default Values

The CHR_hardware_pair_set_*() and CHR_pair_set_*() function topics contain information
on the Console to Endpoint 1 default values. See Pair Object Functions.
Attribu te

Value

Use Setup E1 E2

False

Use Console to Endpoint 1 values

False

Timing record count

Override Line Rate

False

Default Line Rate

100%

Measure Statistics

True

- 52 -

IxChariot APIGuide

VoIP Hardware Performance Pair Object Default Values

The CHR_hardware_pair_set_*() and CHR_voip_pair_set_*() function topics contain
information on the Console to Endpoint 1 default values. See "Pair Object Functions.
Attribu te

Value

Use Setup E1 E2

False

Use Console to Endpoint 1 values

False

Timing record count

Concurrent Voice Streams

Codec

G711u

Datagram Delay

G.723.1 MPLQ & ACELP: 30ms

All others: 20ms

Service Quality

<no default>

UDP source port

1024

UDP destination port

16384

Measure Statistics

True

- 53 -

IxChariot APIGuide

Multicast Group Object

A multicast group object, as the name suggests, represents an IxChariot multicast group.
A multicast group consists of a set of multicast pairs. Similar to the pair object, a multicast
group object instance must be contained in a test object instance before any results for the
contained multicast pairs may be collected or extracted.
Before a multicast group object instance can be added to a test object instance, the following attributes must be set:
1. Endpoint 1 address
2. Multicast address
3. Multicast port
4. IxChariot script filename
5. Group name

- 54 -

IxChariot APIGuide

Multicast Group Object Default Values

The CHR_mgroup_set_*() function topics contain information on the Console to Endpoint 1
default values. See Multicast Group Object Functions.
Attribu te

Value

Protocol

UDP

Setup E1 E2

False

Use Console to Endpoint 1 values

False

Multicast pair count

- 55 -

IxChariot APIGuide

Multicast Pair Object

The multicast pair object represents pairs contained in a multicast group or video multicast
group. A multicast pair object instance must be added to a multicast group object instance
before any results for the multicast pair can be collected.
Before a multicast pair object instance can be added to a multicast group object instance,
the following attribute must be set:
l

Endpoint 2 address

There are no multicast pair attributes with default values.

- 56 -

IxChariot APIGuide

Application Group Object

An application group object represents a group of pairs that belong to an application group.
Application groups provide the means to synchronize the actions of two or more scripts during a test. This allows you to simulate the behavior of applications that use more than one
simultaneous connection. An application group object instance must be contained in a test
object instance before any results for the contained application group pairs may be collected or extracted.
Before an application group object instance can be added to a test object instance, the
application group name attribute must be set, and at least one pair must be added to the
application group.

- 57 -

IxChariot APIGuide

Application Group Object Default Values

The CHR_app_group_set_*() functions provide the default values listed below. Note that
unlike a multicast group, an application group does not have a default protocol.
Attribu te

Value

Number of Pairs

Empty set (zero pairs)

Application Group Name

Empty string

Application Group Comment

Empty string

- 58 -

IxChariot APIGuide

Datagram Options Object

A datagram options object represents datagram options for a test. Every test object
instance creates a default datagram options object instance when the test object instance
is created. Datagram options objects cannot be instantiated independently.

- 59 -

IxChariot APIGuide

Datagram Options Object Default Values

Attribu te

Value

Data rate limit

100

Limit data rate

False

Low sender jitter

False

Measured interval

100

Receive timeout

10000 milliseconds

Retransmission count

50

Retransmission timeout

200 milliseconds

Use extended RTP headers

False

Time to live

Window size

1500 bytes

- 60 -

IxChariot APIGuide

Run Options Object

A run options object represents run options for a test. Every test object creates a default
run options object instance when the test object instance is created. Once the associated
test has been run, the run options object instance cannot be changed until the results of the
run are cleared. The run options object instance cannot be instantiated independently.

- 61 -

IxChariot APIGuide

Run Options Object Default Values

Attribu te

Value

Allow pair reinitialization at runtime

False

Allow pair reinitialization at setup

False

Apply DoD only

False

Collect TCP statistics

False

Connect timeout

0 minutes

Console management QoS

empty string

CPU utilization

False

Deconfigure Ixia ports after test ends

True

Endpoint management QoS

empty string

Firewall between Console and Endpoint 1

False

Interval between reinitialization attempts at setup

10 milliseconds

Interval between reinitialization attempts at runtime

10 milliseconds

Maximum reinitialization attempts at setup

Maxi mum r ei ni ti al i zati on attempts at

r unti me

Number of overlapped sends

Poll endpoints

False

Poll interval

1 minute

Random new seed

True

Record retrieval type

Retrieve timing records

Reporting type

Batch

Stop after number of pairs failed

Stop on initialization failure

True

Test duration

60 seconds

Test end

When pair completes

Use external clock synchronization

False

Use fewer connections for test setup

False *

Use hardware clock synchronization

False

Use hardware timestamps for video testing

True

- 62 -

IxChariot APIGuide

Attribu te

Value

Validate data on receipt

False

* If test contains >500 pairs. Set to True when 501st pair is added to test. For tests with
>1250 pairs, this option is invalid (it cannot be disabled).

- 63 -

IxChariot APIGuide

Timing Record Object

A timing record object represents an IxChariot timing record. After a test has run successfully, the timing records for pairs and multicast groups can be retrieved for further
analysis. Timing records can also be extracted during a running test; however, as the test
proceeds, the timing record object count for a pair or multicast group typically increases.
Timing records cannot be instantiated independently.
Once a test completes, the timing record objects are checked to make sure each was created on or before the precise test completion time. Timing record objects created after the
test completion time are silently and automatically deleted; such records reflect packets of
data that did not reach their destination during the appropriate test period. Any attempt to
reference one of these objects after the test completes will fail with a CHR_HANDLE_
INVALID return code. When using the timing record object functions (CHR_timingrec_*()),
make sure the handle you're using has not been deleted.
See Results Extraction for further details on results extraction.

- 64 -

IxChariot APIGuide

Traceroute Pair Object

A traceroute pair object represents a pair of endpoints used in an IxChariot traceroute
test. Individual hop records, identified by their numbers, can be extracted after a
traceroute test has run. You can also extract the run status and the number of hops while
the traceroute is running.
Traceroute pairs are not contained by other objects. They contain hop record objects.
When setting up a traceroute pair, you configure the addresses of Endpoint 1 and Endpoint
2, as well as the maximum number of hops and the maximum per-hop timeout. The CHR_
tracert_pair_new function lets you create a new traceroute pair.

- 65 -

IxChariot APIGuide

Traceroute Pair Object Default Values

Attribu te

Value

Maximum Timeout

3000 ms

Maximum Hops

30

Resolve Hop Names

True

- 66 -

IxChariot APIGuide

Hop Record Object

Hop record objects are contained by IxChariot traceroute pairs and can be extracted from
a traceroute pair after a traceroute test has started. Hop record extraction gets a series of
hop records, with a hop count.
The CHR_hoprec_get_hop_address function gets the network address of a hop in a
traceroute test. Once the traceroute test has results, you can also find the resolved hop
name, the hop record number, and the latency that was recorded during the traceroute
test.

- 67 -

IxChariot APIGuide

VoIP Pair Object

The VoIP pair object represents an IxChariot voice over IP pair. VoIP pairs can only be created if you've purchased the separately licensed VoIP Test Module. A VoIP pair object is
similar to a pair object. A VoIP pair object instance must be contained by a test object
before any results for the pair can be collected or extracted.
A VoIP pair object instance cannot be added to a multicast group, even if its attributes are
set to match the attributes of the multicast group.
Before a VoIP pair object instance can be added to a test object instance, the following
attributes must be set:
n

Endpoint 1 address

Endpoint 2 address

Codec

VoIP pair objects closely resemble pair objects, with a few exceptions. The following table
summarizes the pair functions that cannot be performed with VoIP pairs and, where appropriate, provides the VoIP pair equivalent:
P air F u n ction

VoI P P air Equ iv alen t

Pair Function

VoIP Pair Equivalent

pair_get_appl_script_name

none

pair_get_script_filename

none

pair_new

voip_pair_new

pair_set_protocol

Use pair_set_protocol

pair_set_script_variable

none

pair_use_script_filename

none

The pair_copy function may only be performed with like objects, for example, two pair
objects or two VoIP pair objects.

- 68 -

IxChariot APIGuide

VoIP Pair Object Default Values

Attribu te

Protocol

Value

RTP

Use Console to Endpoint 1 values

False

Timing record count

50

Ti mi ng r ecor d dur ati on

3 sec
G711u, G711a, G729, G.726 codec: 20 ms

Delay between datagrams

G723.1A, G723.1M codec: 30 ms
Setup E1 E2

False

Silence suppression

OFF

Voice activity rate

50%

Source and destination port numbers

CHR_PORT_AUTO

Initial delay

Jitter buffer size

2 datagrams

Codec

CHR_VOIP_CODEC_NONE

UDP Checksum

Off

See VoIP Pair Object Functions for more information.

- 69 -

IxChariot APIGuide

Video Pair Object

The video pair object represents an IxChariot video over IP pair. Video pairs can be created only if you have purchased the separately-licensed Video Test Module. A video pair
object is similar to a pair object. A video pair object instance must be contained by a test
object before any results for the pair can be collected or extracted.
A video pair object instance cannot be added to a multicast group, even if its attributes are
set to match the attributes of the multicast group. A separate Video Multicast Object is
provided for multicast video testing.
Before a video pair object instance can be added to a test object instance, the following
attributes must be set:
l

Endpoint 1 address

Endpoint 2 address

Codec

Video pair objects closely resemble pair objects, with a few exceptions. The following
table summarizes the pair functions that cannot be performed with video pairs and, where
appropriate, provides the video pair equivalent.
P air F u n ction

Video P air Equ iv alen t

CHR_pair_get_appl_script_name

none

CHR_pair_get_script_filename

none

CHR_pair_new

video_pair_new

CHR_pair_set_script_variable

none

CHR_pair_use_script_filename

none

- 70 -

IxChariot APIGuide

Video Pair Object Default Values

Attribu te

Value

Protocol

UDP

Service Quality

None

Codec (video encoding)

MPEG2

Frames per datagram

Bitrate

3.75 Mbps

Timing record count

50

Timing record duration

3 seconds

Source port

Auto

Destination port

Auto

Initial delay

Constant value, set to 0

Use Endpoint 1 as management address

True

Management network protocol

TCP

Management network service quality

none

Use Endpoint 2 as management address

True

Payload type

NO_COMPRESS

Media frame size

188

RTP payload type

32

- 71 -

IxChariot APIGuide

Video Multicast Group Object

A video multicast group object represents an IxChariot multicast video group. A video multicast group consists of a set of multicast pairs. Similar to the pair object, a video multicast group object instance must be contained in a test object instance before any results
for the contained multicast pairs may be collected or extracted.
Before a video multicast group object instance can be added to a test object instance, the
following attributes must be set:
1. Group name
2. Multicast address
3. Multicast port
4. Endpoint 1 network address
5. Codec (video encoding)

- 72 -

IxChariot APIGuide

Video Multicast Group Object Default Values

Attribu te

Value

Protocol

UDP

Service Quality

None

Codec (video encoding)

MPEG2

Frames per datagram

Bitrate

3.75 Mbps

Timing record count

50

Timing record duration

3 seconds

Source port

Auto

Destination port

Auto

Initial delay

Constant value, set to 0

Use Endpoint 1 as management address

True

Management network protocol

TCP

Management network service quality

none

Use Endpoint 2 as management address

True

Payload type

NO_COMPRESS

Media frame size

188

RTP payload type

32

- 73 -

IxChariot APIGuide

IPTV Channel Object

The IPTV channel object represents an individual IPTV channel that is multicast from a
source to one or more IPTV receivers. In an IxChariot test, Endpoint1 multicasts channel
video streams to Endpoint2. An IPTV channel object is associated with a test only if it is
added to a receiver group channel list. Each such channel is represented by a single VPair
in an IxChariot test.

- 74 -

IxChariot APIGuide

IPTV Channel Object Default Values

Attribu te

Value

Test network multicast address

None

Test network multicast port

Endpoint 1 network address

None

Test network protocol

RTP

Test network service quality

None

Use server test address as management address

True

Management network protocol

TCP

IPTV traffic encoding

MPEG2

RTP payload type

32

Media frames per datagram

Media frame size

188

Bitrate

3.75 Mbps

Source port number

- 75 -

IxChariot APIGuide

IPTV VPair Object

An IxChariot IPTV test includes at least one receiver group. Each receiver group contains
one or more VPair objects. Each such object is a test pair that emulates the multicast transmission and receipt of an IPTV video stream.

- 76 -

IxChariot APIGuide

IPTV VPair Object Default Values

Attribu te

Value

Channel

None

Number of timing records

50

Timing record duration (in seconds)

- 77 -

IxChariot APIGuide

IPTV Receiver Group Object

The IPTV receiver group object represents an individual subscriber to one or more IPTV
channels. In an IxChariot test, Endpoint2 (the subscriber) receives channel video streams
multicast from Endpoint1. An IPTV channel object is associated with a test only if it is
added to a receiver group channel list. Each receiver group includes one test pair for each
channel on the list.

- 78 -

IxChariot APIGuide

IPTV Receiver Group Object Default Values

Attribu te

Value

Endpoint2 address

None

Use server test address as management address

True

Number of iterations

20

Switch delay (in milliseconds)

1000

- 79 -

IxChariot APIGuide

Results Extraction
The IxChariot API supports results extraction during a running test. Be aware, however,
that the results you extract will change as the test progresses. Results may also be extracted after a test has been run, or after it is loaded from a saved IxChariot test file.
Once a test has completed, the extraction process is best described in pseudo code as follows:
1 I f (t es t ran s uc c es s f ully ) {
2 For eac h pair {
3 Get t he handle t o t he pair
4 I f (pair has error)
5 D is play error
6 I f (t iming rec ord c ount > 0) {
7 ex t rac t res ult s
8 }
9 }
10 }
Line 1
Whenever an IxChariot test is run, there is a possibility of failure due to network problems. Before extracting results, you should first check to make sure that results have
begun to amass, or that the test run ended with some results. To find out whether your test
has results, try to extract and examine results or get a timing record count; use CHR_pair_
results_get_average, or something similar. Examine the return code to find out if results
are present, as indicated by the presence of timing records, for example.
If you wait until a test run has completed before extracting results, use the functions and
commands listed below to find out how the test ended. For the rest of this topic, functions
in C are listed first, followed by commands in Tcl:
n

CHR_test_get_how_ended()

chrTest get HOW_ENDED

If the test ended normally (CHR_TEST_HOW_ENDED_NORMAL in C and "NORMAL" in Tcl),

the results can be extracted. If the test was stopped by your program (CHR_TEST_HOW_
ENDED_USER_STOPPED in C and "USER_STOPPED" in Tcl), or if the test ended with an
error (CHR_TEST_HOW_ENDED_ERROR in C and "ERROR" in Tcl), the test may also contain
results that can be extracted.
Line 2
Since a test may contain multiple pairs, use a loop to process each pair in the test. Use the
following commands to get the number of pairs in the test:
n

CHR_test_get_pair_count()

chrTest getPairCount

Line 3
The results of a test are associated with the pairs. To retrieve results, you must obtain
handles to the desired pairs. Use the following commands to retrieve handles to instances
of pairs:

- 80 -

IxChariot APIGuide

CHR_test_get_pair()

chrTest getPair

Line 4
Since some of the pairs of a test may have errors, use the following commands to find out
if a pair had an error during a run:
n

CHR_common_error_get_msg_num()

chrCommonError getMsgNum

Note that a pair may have an error and still have timing records. The pair completed successfully if CHR_NO_SUCH_VALUE is returned here.
Line 5
Use the following commands to get additional error information:
n

CHR_common_error_get_info()

chrCommonError getInfo

Line 6
Before extracting results, make sure that a pair has timing records. The results of a pair
are stored in its timing records. Therefore, pairs that had an error during the run may not
have timing records. Use the following commands to get the number of timing records
associated with the pair:
CHR_pair_get_timing_record_count()
chrPair getTimingRecordCount
Line 7
In line 5, the extraction of results can be implemented in different ways, depending on the
type of results desired. If you need raw information, such as throughput for individual timing records, use
n

CHR_pair_get_timing_record()

chrPair getTimingRecord

to retrieve handles to timing records. The timing record handle can then be passed into
n

CHR_timingrec_get_*()

chrTimingRec get

to retrieve specific results.

The timing record can also be passed into the following commands to retrieve other results:
n

CHR_common_*()

chrCommonResults get

If summarized information such as average throughput for the pair is needed, pass the
pair handle directly into the following commands:
n

CHR_pair_results_*()

- 81 -

IxChariot APIGuide

chrPairResults get

Note that the results of the test may be deleted by calling CHR_test_clear_results() or by
invoking the chrTest clearResults Tcl command. The results of a test are automatically
cleared if the test is run again.

- 82 -

IxChariot APIGuide

Common Error Functions

The common error functions are used to retrieve extended error information and the
IxChariot message number that applies to that information for tests, pairs, multicast pairs,
and multicast groups.

- 83 -

IxChariot APIGuide

API Utility Functions

In addition to the object-specific functions, the results extraction functions, and the common error functions, the IxChariot API provides other functions that perform the following
miscellaneous tasks:
l

Get the maximum pairs allowed by the current IxChariot license.

Get the port used by endpoints to report results to the IxChariot Console.

Get a text message that includes a description of a return code.

Get the API version.

Initialize the API (C only).

Set the port used by endpoints to report results to IxChariot.

- 84 -

IxChariot APIGuide

Your First Program

The following are examples of simple programs that demonstrate how the IxChariot API
can be used when coding in the C and Tcl languages. See Program Notes for more detail on
the numbered comments included in each program.

- 85 -

IxChariot APIGuide

C Program
To make this section concise, the C Program shown below is not complete and will not compile or link as shown. The file chrLBSimple.c has been included in the zip file C_samp in the
Samples\C folder of the SDK directory on the IxChariot DVD-ROM. Here you can find the
complete version of this script.
/**************************************************************
*
* I x ia C hariot API SD K
File: C hrLBSimple. c
*
* This module c ont ains c ode made av ailable by I x ia
* C orporat ion on an AS I S bas is . Any one rec eiv ing t he
* module is c ons idered t o be lic ens ed under I x ia C orporat ion
* c o p y r i g h t s t o u s e t h e I x i a -p r o v i d e d s o u r c e c o d e i n a n y
* w ay he or s he deems f it , inc luding c opy ing it , c ompiling
* it , modif y ing it , and redis t ribut ing it , w it h or w it hout
* modif ic at ions . N o lic ens e under any I x ia C orporat ion
* pat ent s or pat ent applic at ions is t o be implied f rom t his
* c opy right lic ens e.
*
* A us er of t he module s hould unders t and t hat I x ia
* C orporat ion c annot prov ide t ec hnic al s upport f or t he module
* and w ill not be res pons ible f or any c ons equenc es of us e of
* t he program.
*
* Any not ic es , inc luding t his one, are not t o be remov ed f rom
* t he module w it hout t he prior w rit t en c ons ent of I x ia
* C orporat ion.
*
* For more inf ormat ion, c ont ac t :
*
* Ixia
* 26601 W . Agoura R d.
* C alabas as , C A 91302 U SA
* W eb: ht t p: / / w w w . ix iac om. c om
* Phone: 818-871-1800
* Fax : 818-871-1805
*
* General I nf ormat ion:
*
e-mail: inf o@ ix iac om. c om
*
* Tec hnic al Support :
*
e-mail: s upport @ ix iac om. c om
*
*
* EXAMPLE: Your Firs t Program
*
* This program c reat es and runs a s imple loopbac k t es t us ing
* t he File Send, Short C onnec t ion s c ript , print s s ome res ult s ,
* and s av es it t o dis k .
*
* All at t ribut es of t his t es t are def ined by t his s c ript .

- 86 -

IxChariot APIGuide
*
**************************************************************/
#inc lude < s t dio. h>
#inc lude < s t dlib. h>
#inc lude < s t ring. h>
/*
* The header f ile w hic h def ines ev ery t hing in t he C hariot API :
* f unc t ions , c ons t ant s , et c .
*/
#inc lude " c hrapi. h"
/*
* Loc al f unc t ion t o print inf ormat ion about errors .
*/
s t at ic v oid
s how _error (
C H R _H AN D LE handle,
C H R _API _R C c ode,
C H R _STR I N G w here);
/*
* D at a f or t he t es t :
* C hange t hes e f or y our loc al net w ork if des ired.
*/
s t at ic
C H R _STR I N G e1 = " loc alhos t " ;
s t at ic
C H R _STR I N G e2 = " loc alhos t " ;
s t at ic
C H R _STR I N G s c ript = " c : / Program Files / I x ia/ I x C hariot / Sc ript s /
Throughput . s c r" ;
s t at ic
C H R _STR I N G t es t f ile = " lbt es t . t s t " ;
s t at ic
C H R _C OU N T t imeout = 120; / * 2 minut es in s ec onds */
/**************************************************************
*
* Program main
*
* I f t he ret urn c ode f rom any C hariot API f unc t ion c all
* i s not C H R _OK , t he s how _error () f unc t i on i s c al l ed t o
* dis play inf ormat ion about w hat happened t hen ex it .
*
* The numbers is parent hes es in t he c omment s ref er t o t he
* Program N ot es s ec t ion of t he C hariot API Programming Guide.
*
**************************************************************/
v oid main()
{
/*
* The objec t handles w e' ll need
*/
C H R _T E S T _H A N D LE t es t = (C H R _ T E S T _H A N D LE ) N U LL;
C H R _P A I R _H A N D LE pai r = (C H R _ P A I R _H A N D LE ) N U LL;
/*

- 87 -

IxChariot APIGuide
* Variables and buf f ers f or t he at t ribut es and res ult s
*/
C H R _C OU N T
pairC ount ;
C H R _PR OTOC OL prot oc ol;
c har addr[ C H R _MAX_AD D R ] ;
c har s c ript N ame[ C H R _MAX_FI LEN AME] ;
c har appl S c ri pt N am e[ C H R _ M A X _A P P L_S C R I P T _ N A M E ] ;
C H R _LEN GTH len;
C H R _C OU N T t imingR ec C ount ;
C H R _FLOAT av g, min, max ;
/*
* Buf f er f or ex t ended error inf o f or init ializ at ion
*/
c har errorI nf o [ C H R _M A X _E R R OR _ I N F O] ;
/*
* C hariot API ret urn c ode
*/
C H R _API _R C rc ;
/ * (1)
* You hav e t o init ializ e t he C hariot API
* bef ore y ou c an us e t he f unc t ions in it .
* This is t he only C hariot API f unc t ion
* w hic h inc ludes ex t ended error inf ormat ion
* in it s c alling paramet ers , s inc e it is
* not as s oc iat ed w it h an objec t .
*/
rc = C H R _api _i ni t i al i z e(C H R _ D E T A I L_LE V E L_A LL, errorI nf o,
C H R _MAX_ER R OR _I N FO, &len);
if (C H R _OK ! = rc ) {
/*
* Bec aus e init ializ at ion f ailed, w e c an' t
* as k t he API f or t he mes s age f or t his
* ret urn c ode, s o w e c an' t c all our
* s h o w _ e r r o r( ) f u n c t i o n . I n s t e a d , w e ' l l
* print w hat w e do k now bef ore ex it ing.
*/
print f (" I nit ializ at ion f ailed: rc = %d\ n" , rc );
print f (" Ex t ended error inf o: \ n%s \ n" , errorI nf o);
}
/ * (2)
* You mus t c reat e a t es t objec t t o def ine a new t es t
* or t o load an ex is t ing t es t f rom dis k .
*/
if (C H R _OK = = rc ) {
print f (" C reat e t he t es t . . . \ n" );
rc = C H R _t es t _new(&t es t );
if (rc ! = C H R _OK) {
s h o w _e r r o r ( ( C H R _ H A N D L E )N U L L , r c , " t e s t _ n e w " ) ;
}
}
/ * (3)
* You mus t c reat e a pair objec t in order t o def ine it .
*/

- 88 -

IxChariot APIGuide
if (C H R _OK = = rc ) {
print f (" C reat e t he pair. . . \ n" );
rc = C H R _pair_new(&pair);
if (rc ! = C H R _OK) {
s h o w _e r r o r ( ( C H R _ H A N D L E )N U L L , r c , " p a i r _ n e w " ) ;
}
}
/ * (4)
* Onc e y ou hav e a pair, y ou c an def ine it s at t ribut es .
*/
if (C H R _OK = = rc ) {
print f (" Set required pair at t ribut es . . . \ n" );
rc = C H R _ pai r_ s et _ e1_addr(pai r, e1, s t rl en(e1));
if (rc ! = C H R _OK) {
s how _error (pai r, rc , " pai r_s et _e1_ addr" );
}
}
if (C H R _OK = = rc ) {
rc = C H R _ pai r_ s et _ e2_addr(pai r, e2, s t rl en(e2));
if (rc ! = C H R _OK) {
s how _error (pai r, rc , " pai r_s et _e2_ addr" );
}
}
/ * (5)
* You mus t def ine a s c ript f or us e in t he t es t .
*/
if (C H R _OK = = rc ) {
print f (" U s e a s c ript . . . \ n" );
rc = C H R _pai r_ us e_s c ri pt _f i l enam e(pai r,
s c ript , s t rlen(s c ript ));
if (rc ! = C H R _OK) {
s how _error (pai r, rc , " pai r_us e_s c ri pt _ f i l enam e" );
}
}
/ * (6)
* N ow t hat t he pair is def ined, y ou c an add it t o t he t es t .
*/
if (C H R _OK = = rc ) {
print f (" Add t he pair t o t he t es t . . . \ n" );
rc = C H R _t es t _add_pair(t es t , pair);
if (rc ! = C H R _OK) {
s how _error (t es t , rc , " t es t _add_pai r" );
}
}
/ * (7)
* W e hav e a t es t def ined, s o now w e c an run it .
*/
if (C H R _OK = = rc ) {
print f (" R un t he t es t . . . \ n" );
rc = C H R _t es t _s t art(t es t );
if (rc ! = C H R _OK) {
s how _error (t es t , rc , " t es t _s t art " );
}

- 89 -

IxChariot APIGuide
}
/ * (8)
* W e hav e t o w ait f or t he t es t t o s t op bef ore w e c an look
* at t he res ult s f rom it . W e' ll w ait f or 2 minut es here,
* t hen c all it an error if it has not y et s t opped.
*/
if (C H R _OK = = rc ) {
print f (" W ait f or t he t es t t o s t op. . . \ n" );
rc = C H R _t es t _query _s t op(t es t , t imeout );
if (rc ! = C H R _OK) {
s how _error (t es t , rc , " t es t _query _ s t op" );
}
}
/ * (9)
* Let ' s print out how w e def ined t he t es t bef ore print ing
* res ult s f rom running it . Sinc e w e hav e t he pair handle
* f rom w hen w e c reat ed it , w e don' t need t o get it f rom
* t he t es t .
*/
if (C H R _OK = = rc ) {
print f (" = = = = = = = = = = = \ n" );
p r i n t f ( " T e s t s e t u p : \ n - -- -- -- -- -\ n " ) ;
rc = C H R _ t es t _ get _pai r_c ount (t es t , & pai rC ount );
if (rc ! = C H R _OK) {
s how _error (t es t , rc , " get _ pai r_c ount " );
}
print f (" N umber of pairs = %d\ n" , pairC ount );
}
if (C H R _OK = = rc ) {
rc = C H R _ pai r_ get _ e1_addr(pai r, addr, C H R _ M A X _ A D D R , & l en);
if (rc ! = C H R _OK) {
s how _error (pai r, rc , " pai r_get _e1_ addr" );
}
print f (" E1 addres s
: %s \ n" , addr);
}
if (C H R _OK = = rc ) {
rc = C H R _ pai r_ get _ e2_addr(pai r, addr, C H R _ M A X _ A D D R , & l en);
if (rc ! = C H R _OK) {
s how _error (pai r, rc , " pai r_get _e2_ addr" );
}
print f (" E2 addres s
: %s \ n" , addr);
}
/*
* W e didn' t s et prot oc ol, but let ' s s how it any w ay .
*/
if (C H R _OK = = rc ) {
rc = C H R _pair_get _prot oc ol(pair, &prot oc ol);
if (rc ! = C H R _OK) {
s how _error (pai r, rc , " pai r_get _prot oc ol " );
}
print f (" Prot oc ol
: %d\ n" , prot oc ol);
}
/*

- 90 -

IxChariot APIGuide
* W e' ll s how bot h t he s c ript f ilename and
* t he applic at ion s c ript name.
*/
if (C H R _OK = = rc ) {
rc = C H R _pai r_ get _s c ri pt _f i l enam e(pai r, s c ri pt N am e,
C H R _MAX_FI LEN AME, &len);
if (rc ! = C H R _OK) {
s how _error (pai r, rc , " pai r_get _s c ri pt _ f i l enam e" );
}
print f (" Sc ript f ilename : %s \ n" , s c ript N ame);
}
if (C H R _OK = = rc ) {
rc = C H R _ pai r_ get _appl _s c ri pt _ nam e(pai r, appl S c ri pt N am e,
C H R _M A X _A P P L_ S C R I P T _N A M E ,
&len);
if (rc ! = C H R _OK) {
s how _error (pai r, rc , " pai r_get _appl _ s c ri pt _nam e" );
}
print f (" Appl s c ript name: %s \ n" , applSc ript N ame);
}
/ * (10)
* N ow let ' s get s ome res ult s :
* t he number of t iming rec ords and
* t he t hroughput (av g, min, max ),
*/
if (C H R _OK = = rc ) {
p r i n t f ( " \ n T e s t r e s u l t s : \ n - -- -- -- -- -- -\ n " ) ;
rc = C H R _pai r_ get _t i m i ng_rec ord_ c ount (pai r, & t i m i ngR ec C ount );
if (rc ! = C H R _OK) {
s how _error (pai r, rc , " pai r_get _t i m i ng_ rec ord_c ount " );
}
print f (" N umber of t iming rec ords = %d\ n" , t imingR ec C ount );
}
/ * (11)
* W e' re not goi ng t o c hec k f or N O_S U C H _ V A LU E here
* alt hough w e s hould. This ret urn c ode s ignals t hat
* t he reques t ed res ult is not av ailable f or t his
* part ic ular t es t . Thes e k inds of res ult s are s how n
* as " n/ a" in t he C hariot c ons ole dis play . I n t his c as e,
* t hough, w e s hould be able t o get t hroughput . w e' ll c all
* any ot her ret urn c ode ex c ept C H R _OK an error.
*/
if (C H R _OK = = rc ) {
rc = C H R _ p a i r_ re s u l t s _ g e t _ a v e ra g e(p a i r,
C H R _R ESU LTS_TH R OU GH PU T,
&av g);
if (rc ! = C H R _OK) {
s how _error (pai r, rc , " pai r_res ul t s _ get _av erage" );
}
}
if (C H R _OK = = rc ) {
rc = C H R _pair_ res ult s _get _minimum(pair,
C H R _R ESU LTS_TH R OU GH PU T,

- 91 -

IxChariot APIGuide
&min);
if (rc ! = C H R _OK) {
s how _error (pai r, rc , " pai r_res ul t s _ get _m i ni m um " );
}
}
if (C H R _OK = = rc ) {
rc = C H R _pair_ res ult s _get _max imum(pair,
C H R _R ESU LTS_TH R OU GH PU T,
&max );
if (rc ! = C H R _OK) {
s how _error (pai r, rc , " pai r_res ul t s _ get _m ax i m um " );
}
/*
* W e' ll f ormat t hes e t o look lik e t he w ay t he C hariot
* c ons ole dis play s t hes e k inds of numbers .
*/
print f (" Throughput : \ n av g %. 3f min %. 3f max %. 3f \ n" ,
av g, min, max );
}
/ * (12)
* Finally , let ' s s av e t he t es t s o w e c an look at it again.
* W e hav e t o s et t he f ilename bef ore w e c an s av e it .
*/
if (C H R _OK = = rc ) {
print f (" = = = = = = = = = = \ nSav e t he t es t . . . \ n" );
rc = C H R _t es t _s et _f ilename(t es t ,
t es t f ile, s t rlen(t es t f ile));
if (rc ! = C H R _OK) {
s how _error (t es t , rc , " t es t _s et _f i l enam e" );
} els e {
rc = C H R _t es t _s av e(t es t );
}
if (rc ! = C H R _OK) {
s how _error (t es t , rc , " t es t _s av e" );
}
}
/ * (13)
* Ex plic it ly f ree alloc at ed res ourc es
*/
i f ( pai r ! = (C H R _ P A I R _H A N D LE ) N U LL ) {
C H R _ pai r_del et e(pai r);
}
i f ( t es t ! = (C H R _ T E S T _H A N D LE ) N U LL ) {
C H R _ t es t _del et e(t es t );
}
/*
* Ex it t es t w it h s uc c es s or error c ode.
*/
ex it (rc );
}
/**************************************************************
*
* Print inf ormat ion about an error and ex it .

- 92 -

IxChariot APIGuide
*
* Paramet ers : handle - w hat objec t had t he error
*
c ode - t he C hariot API ret urn c ode
*
w here - w hat f unc t ion c all f ailed
*
**************************************************************/
s t at ic v oid
s how _error (
C H R _H AN D LE handle,
C H R _API _R C c ode,
C H R _STR I N G w here)
{
c har
m s g [ C H R _M A X _R E T U R N _ M S G] ;
C H R _LEN GTH ms gLen;
c har
errorI nf o [ C H R _M A X _E R R OR _ I N F O] ;
C H R _LEN GTH errorLen;
C H R _API _R C rc ;
/*
* Get t he API mes s age f or t his ret urn c ode.
*/
rc = C H R _ a p i _ g e t _ re t u rn _ m s g(c o d e , m s g ,
C H R _M A X _R E T U R N _M S G, & m s gLen);
if (rc ! = C H R _OK) {
/ * C ould not get t he mes s age: s how w hy */
print f (" %s f ailed\ n" , w here);
print f (
" U nable t o get mes s age f or ret urn c ode %d, rc = %d\ n" ,
c ode, rc );
}
els e {
/ * Tell t he us er about t he error */
print f (" %s f ailed: rc = %d (%s )\ n" , w here, c ode, ms g);
}
/*
* See if t here is ex t ended error inf ormat ion av ailable.
* I t ' s meaningf ul only af t er t he C H R _OPER ATI ON _FAI LED
* and C H R _OBJ EC T_I N VALI D error ret urns . Af t er f ailed
* " new " f unc t ion c alls , w e don' t hav e a handle s o w e
* c annot c hec k f or ex t ended error inf ormat ion.
*/
if ((c ode = = C H R _OPER ATI ON _FAI LED
|| c ode = = C H R _OBJ EC T_ I N VALI D )
& & h a n d l e ! = ( C H R _ H A N D L E )N U L L ) {
rc = C H R _c ommon_error_get _inf o(handle,
C H R _D ETAI L_LEVEL_ALL,
errorI nf o,
C H R _MAX_ER R OR _I N FO,
&errorLen);
if (rc = = C H R _OK) {
/*
* W e c an ignore all non-s uc c es s ret urn c odes here
* bec aus e mos t s hould not oc c ur (t he api' s been
* init ializ ed, t he handle is good, t he buf f er

- 93 -

IxChariot APIGuide
* point er is v alid, and t he det ail lev el is ok ay ),
* and t he N O_ S U C H _V A LU E ret urn c ode here m eans
* t here is no inf o av ailable.
*/
print f (" Ex t ended error inf o: \ n%s \ n" , errorI nf o);
}
}
}

- 94 -

IxChariot APIGuide

Tcl Script
To keep it brief, the Tcl script shown below is not complete and does not compile or link as
shown. The file chrLBSimple.tcl has been included in the zip file Tcl_samp in the
Samples\Tcl folder of the SDK directory on the IxChariot DVD-ROM. The DVD-ROM
includes the complete version of this script.
#***************************************************************
#
# I x ia C hariot API SD K
File: C hrLBSimple. t c l
#
# This module c ont ains c ode made av ailable by I x ia
# C orporat ion on an AS I S bas is . Any one rec eiv ing t he
# module is c ons idered t o be lic ens ed under I x ia C orporat ion
# c opy right s t o us e t he I x ia-prov ided s ourc e c ode in any
# w ay he or s he deems f it , inc luding c opy ing it , c ompiling
# it , modif y ing it , and redis t ribut ing it , w it h or w it hout
# modif ic at ions . N o lic ens e under any I x ia C orporat ion
# pat ent s or pat ent applic at ions is t o be implied f rom t his
# c opy right lic ens e.
#
# A us er of t he module s hould unders t and t hat I x ia
# C orporat ion c annot prov ide t ec hnic al s upport f or t he module
# and w ill not be res pons ible f or any c ons equenc es of us e of
# t he program.
#
# Any not ic es , inc luding t his one, are not t o be remov ed f rom
# t he module w it hout t he prior w rit t en c ons ent of I x ia
# C orporat ion.
#
# For more inf ormat ion, c ont ac t :
#
# Ixia
# 26601 W . Agoura R d.
# C alabas as , C A 91302 U SA
# W eb: ht t p: / / w w w . ix iac om. c om
# Phone: 818-871-1800
# Fax : 818-871-1805
#
# General I nf ormat ion:
#
e-mail: inf o@ ix iac om. c om
#
# Tec hnic al Support :
#
e-mail: s upport @ ix iac om. c om
#
#
# EXAMPLE: Your Firs t Sc ript
#
# This s c ript c reat es and runs a s imple loopbac k t es t us ing
# t he File Send, Short C onnec t ion s c ript , print s s ome res ult s ,
# and s av es it t o dis k .
#
# All at t ribut es of t his t es t are def ined by t his s c ript .

- 95 -

IxChariot APIGuide
#
#***************************************************************
#***************************************************************
# D at a f or t he t es t :
# C hange t hes e f or y our loc al net w ork if des ired.
# N ot e: t imeout is s et t o t w o minut es in s ec onds
#***************************************************************
s et e1 " loc alhos t "
s et e2 " loc alhos t "
s et s c ript " c : / Program Files / I x ia/ I x C hariot / Sc ript s / Throughput . s c r"
s et t es t File " c : / Program Files / I x ia/ I x C hariot / t es t s / lbt es t . t s t "
s et t imeout 120
#***************************************************************
#
# Sc ript Main
#
# The numbers is parent hes es in t he c omment s ref er t o t he
# Program N ot es s ec t ion of t he C hariot API Programming Guide.
#
#***************************************************************
# (1)
# You mus t load t he C hariot pac k age bef ore y ou c an us e any
# of it s c ommands . I f t his f ails , det ailed inf ormat ion about
# t he reas on is print ed and is appended t o $errorI nf o.
#
# N OTE: I f y ou are us ing Tc l Vers ion 8. 0. p5 or older
# t hen y ou w ill need t o modif y t he f ollow ing lines t o load and
# us e C hariot ins t ead of C hariot Ex t . For ex ample:
# load C hariot
# pac k age require C hariot
load C hariot Ex t
pac k age require C hariot Ex t
# (2)
# You mus t c reat e a t es t objec t t o def ine a new t es t
# or t o load an ex is t ing t es t f rom dis k .
put s " C reat e t he t es t . . . "
s et t es t [ c hrTes t new ]
# (3)
# You mus t c reat e a pair objec t in order t o def ine it .
put s " C reat e t he pair. . . "
s et pair [ c hrPair new ]
# (4)
# Onc e y ou hav e a pair, y ou c an def ine it s at t ribut es .
put s " Set required pair at t ribut es . . . "
c hrP ai r s et $pai r E 1_A D D R $e1 E 2_A D D R $e2
# (5)
# You mus t def ine a s c ript f or us e in t he t es t .
put s " U s e a s c ript . . . "
c hrPair us eSc ript $pair $s c ript
# (6)
# N ow t hat t he pair is def ined, y ou c an add it t o t he t es t .
put s " Add t he pair t o t he t es t . . . "
c hrTes t addPair $t es t $pair

- 96 -

IxChariot APIGuide
# (7)
# W e hav e a t es t def ined, s o now w e c an run it .
put s " R un t he t es t . . . "
c hrTes t s t art $t es t
# (8)
# W e hav e t o w ait f or t he t es t t o s t op bef ore w e c an look at
# t he res ult s f rom it . W e' ll w ait f or 2 minut es here, t hen
# c all it an error if it has not y et s t opped.
put s " W ait f or t he t es t t o s t op. . . "
if {! [ c hrTes t is St opped $t es t $t imeout ] } {
put s " ER R OR : Tes t didn' t s t op in 2 minut es ! "
c hrTes t delet e $t es t f orc e
ret urn
}
# (9)
# Let ' s print out how w e def ined t he t es t bef ore print ing
# res ult s f rom running it . Sinc e w e hav e t he pair handle f rom
# w hen w e c reat ed it , w e don' t need t o get it f rom t he t es t .
put s " = = = = = = = = = = = "
p u t s " T e s t s e t u p : \ n - -- -- -- -- -"
put s " N umber of pairs = [ c hrTes t get PairC ount $t es t ] "
put s " E1 addres s
: [ c hrPair get $pair E1_AD D R ]"
put s " E2 addres s
: [ c hrPair get $pair E2_AD D R ]"
# W e didn' t s et t he prot oc ol, but let ' s s how it any w ay .
put s " Prot oc ol
: [ c hrPair get $pair PR OTOC OL] "
# W e' ll s how bot h t he s c ript f ilename and
# t he applic at ion s c ript name.
put s " Sc ript f ilename : [ c hrPair get $pair SC R I PT_FI LEN AME]"
put s " A ppl s c ri pt nam e: [ c hrP ai r get $pai r A P P L_ S C R I P T _N A M E ] "
# (10)
# N ow let ' s get s ome res ult s :
# t he number of t iming rec ords and
# t he t hroughput (av g, min, max )
put s " "
p u t s " T e s t r e s u l t s : \ n - -- -- -- -- -- -"
put s " N umber of t iming rec ords = \
[ c hrPair get TimingR ec ordC ount $pair] "
# (11)
# W e' re not going t o c hec k f or " N o s uc h v alue" here,
# alt hough w e s hould. This ret urn c ode s ignals t hat
# t he reques t ed res ult is not av ailable f or t his
# part ic ular t es t . Thes e k inds of res ult s are s how n
# as " n/ a" in t he C hariot c ons ole dis play . I n t his c as e,
# t hough, w e s hould be able t o get t hroughput . W e' ll let
# any t hing ot her t han t he res ult be handled as an error.
s et t hroughput [ c hrPairR es ult s get $pair TH R OU GH PU T]
# W e' ll f ormat t hes e t o look lik e t he w ay t he C hariot
# c ons ole dis play s t hes e k inds of numbers .
s et av g [ f ormat " %. 3f " [ lindex $t hroughput 0] ]
s et min [ f ormat " %. 3f " [ lindex $t hroughput 1] ]
s et max [ f ormat " %. 3f " [ lindex $t hroughput 2] ]
put s " Throughput : "
put s " av g $av g min $min max $max "

- 97 -

IxChariot APIGuide
# (12)
# Finally , let ' s s av e t he t es t s o w e c an look at it again.
put s " = = = = = = = = = = "
put s " Sav e t he t es t . . . "
c hrTes t s av e $t es t $t es t File
# (13)
# C lean up us ed res ourc es bef ore ex it ing.
# (Tes t w ill dealloc at e as s oc iat ed pairs aut omat ic ally )
c hrTes t delet e $t es t f orc e
# The t es t w as s av ed s uc c es s f ully , s o w e' re done!
ret urn

- 98 -

IxChariot APIGuide

Program Notes
The numbers below correspond to the numbers in the comments in the C program and the
Tcl script.
1. In the Tcl script, the IxChariot API must be initialized or loaded before any of its components can be used. Since initialization can fail for many reasons, extended information is available to describe exactly why it failed. In the C program, the return code
is shown rather than the corresponding message because there is no way to access
the message without the initialized API.
2. A test object must be instantiated to create a new test or before loading a test from a
file. The handle returned by this must be used whenever you want to get or set something for this test and when you want to run a test, stop a test, or determine if the
test is stopped.
3. Like the test object, you must create a pair object before you can get or set its attributes or add it to a test.
4. Attributes can be set and reset at will before the pair is owned by a test. After a pair
has been added to a test, its attributes cannot be changed.
5. Before a script can be added to a test, either a pair or a multicast group must have
the script in use. Since many factors can prevent a script from being read for use,
this function or command has extended information available to give more detail
about the reason for failure.
6. When the pair is added to the test, various things are checked to ensure that it is properly defined for a test. This procedure includes making sure that the endpoint
addresses are defined and that a script has been read for use by the pair. The attributes are also checked to make sure that they go together, such as checking to make
sure that the script can use the specified protocol. An error is returned if any of these
checks fail and details about what is not correct are given in the extended information.
7. Starting the test means telling the IxChariot engine to run it. From there, the test
runs on a separate thread from the C program or Tcl script that started it.
8. To determine that the test has finished, check the test status. You can do this by calling the check test status function or command with a timeout of two minutes
(although you can also choose a longer time period, even "infinite"). If the test is not
stopped in the amount of time we specified in this example, we'll consider it to be an
error. For other things, however, such as printing a heartbeat or checking for user
input requesting the test to stop, you can call the status checker with a shorter
timeout in a loop.
9. This shows how to get the attributes for the test and the pair owned by the test. Use
the pair handle you received from the CREATE call because it does not change when
you add the pair to the test. You can also get the pair handle from the test object.
10. This shows how to get some of the basic results from the pair, including the number
of timing records generated during the test run.
11. When getting results for a test, the return should always be checked for the CHR_NO_
SUCH_VALUE return code. This return signals that the requested result is not available for that specific test and is not necessarily an error. Results of this type are
shown as "n/a" in the IxChariot Console displays.

- 99 -

IxChariot APIGuide
12. This shows how to save the test so that it can be loaded again at a later time, perhaps
to compare results of this run of the test with another run at some other time.
13. It is important to explicitly free all allocated resources. Failure to do so may cause
your system to run out of memory after multiple runs.

- 100 -

IxChariot APIGuide

Interesting Examples
A makefile is included for the C language version of these examples in the SDK.
Loopback Test
n

C file: ChrLBSimple.c

Tcl file: ChrLBSimple.tcl

This example creates and runs a simple loopback test.

Pairs Test
n

C file ChrPairsTest.c

Tcl file: ChrPairsTest.tcl

This example builds and runs a test that only involves pairs. It demonstrates when to
handle the CHR_OPERATION_FAILED and CHR_OBJECT_INVALID error returns for possible
recovery.
Use the Print General Test Results example or the IxChariot Console to view the results
from this test.
Multicast Groups Test
n

C file: ChrMGroupsTest.c

Tcl file: ChrMGroupsTest.tcl

This example is similar to the Pairs Test example. It builds and runs a test that only
involves multicast groups. It demonstrates how to set script variables.
Use the Print General Test Results example or the IxChariot Console to view the results
from this test.
Print General Test Results
n

C file: ChrTestResults.c

Tcl file: ChrTestResults.tcl

This example prints some results for tests that contain endpoint pairs and/or multicast
groups. It demonstrates how to handle the CHR_NO_SUCH_VALUE return code for results.

- 101 -

IxChariot APIGuide

C Reference
The C Reference describes how to build and execute programs written in C or C++ using
the IxChariot API.
Each function name in the C interface is prefixed with CHR_object. The prefix helps avoid
naming conflicts with other libraries used by the program; here object stands for the term
used to identify which object the function operates on. All function names are organized
alphabetically within the respective objects.
The calls for each test, error, or utility function are explained in separate topics.
The Return Code Summary contains a list and explanation of all the error codes you might
see.
Refer to the Tcl Reference, for information on programming in Tcl for the IxChariot API.
This reference also shows the type definitions and enumerations as defined in the header
file CHRAPI.H. See Typedefs and Enumerations.

- 102 -

IxChariot APIGuide

Getting Started
To use the IxChariot API to write programs in C, you need to make sure your computer is
accessing the correct header file (chrapi.h) from the IxChariot Software Developer's Kit.
The IxChariot SDK is included on the IxChariot DVD-ROM.
Copy the following to your include path:
[ driv e]\ s dk \ inc lude\ c hrapi. h
where [drive] indicates the DVD-ROM drive where the IxChariot DVD-ROM can be
accessed.
You also need to copy the following path to your lib path:
[ driv e]\ s dk \ lib\ c hrapi. lib

- 103 -

IxChariot APIGuide

IxChariot API Objects

The following characteristics apply to IxChariot API objects:
l

Most objects have a CHR_object_new() function to create an instance of the object.

This function returns a handle to the new instance. Some objects are implicitly created when their containing object is created or as the result of running a test.
Objects that have a CHR_object_new() function have a corresponding CHR_object_
delete() function. The delete function is used to deallocate the instance of the object.
The delete function also deallocates any objects that are contained within this object.
Some objects have a CHR_object_copy() function. The copy function creates a copy
of the object. Note that the copy function copies other objects contained within the
object, but does not copy the results contained within the object.
Each object has a set of attributes. Some of the attributes are read/write and others
are read-only. For the read/write attributes, the object contains a CHR_object_set_
attribute() function, where attribute is the name of the attribute. The set function
allows the program to set the value of the attribute. For all attributes, the object contains a CHR_object_get_attribute() function. The get function allows the program to
retrieve the value of the attribute. Most of the attributes of objects are read/write.
Any information generated by running a test is accessible via read-only attributes.

- 104 -

IxChariot APIGuide

String Parameters
Each function requires the object handle as the first parameter, with the exception of the
utility functions and the CHR_*_new() functions. All parameters have specific type definitions contained in the IxChariot API header file. String parameters (CHR_STRING) have
the following characteristics:
l

All strings passed into the API are passed in via two arguments: a pointer to the character buffer, and a length. The length does not include the null terminator.
When strings are returned from the API, three arguments are used: a pointer to the
character buffer where the string should be returned, the length of the buffer, and a
pointer to an integer where the length of the returned string is returned. The API terminates each returned string with the null terminator, but the returned length does
not include the null terminator.

- 105 -

IxChariot APIGuide

Return Codes
Return codes apply to the following situations and may include the following information:
l

Each function provides a return code to indicate its completion status.

A return code of CHR_OK indicates successful completion of the function.

A text message corresponding to a particular return code may be retrieved by invoking CHR_api_get_return_msg().
If a function completes with a return code of CHR_OPERATION_FAILED or CHR_
OBJECT_INVALID, extended error information is available for that object, providing
details of why the operation failed or how the object is invalid. Use CHR_common_
error_get_info to get this extended error information.

- 106 -

IxChariot APIGuide

Error Detail Levels

Some return codes offer extended error information to aid in troubleshooting. When you
are using the extended error information, the information returned is based on the value of
CHR_DETAIL_LEVEL, whose values are as follows:
l
l

NONE - No extended error information provided.

CHR_DETAIL_LEVEL_PRIMARY - The IxChariot component that detected the error, the
time of error, the return code, and a primary error message. This is useful for summarizing error activity.
CHR_DETAIL_LEVEL_ADVANCED - CHR_DETAIL_LEVEL_PRIMARY information, plus
advanced and informational error messages, if they exist. This level is useful for display and logging.
CHR_DETAIL_LEVEL_ALL - CHR_DETAIL_LEVEL_ADVANCED information, plus file
information about where the error occurred.
Extended error information should be logged at detail level ALL to receive error
diagnosis assistance from Ixia.

Use CHR_common_error_get_info to get this extended error information.

- 107 -

IxChariot APIGuide

Compiler Support
Programs written for the IxChariot API can generally be complied and linked by any C or
C++ compiler capable of creating a Windows 32-bit program. We have tested the
IxChariot API with the following compilers:
l

Microsoft Visual C++ .NET 2003, Visual Studio 6.0 SP5 and above.

IBM VisualAge for C++ Version 3.5 and above.

This compiler is no longer available for new purchases.

Watcom C/C++ Version 10.0 and above.

This compiler is no longer available for new purchases.
There is a known issue when you are calling the Chariot API from a Managed (.NET)
program. The Hardware Performance Pair (HPP) initialization code uses CoInitialize
to initialize the Microsoft COM library, which sets the thread's apartment state to
STA (single-threaded). However, if the apartment state has already been set to
MTA (multi-threaded), the CoInitialize call will fail with a Windows error code of
0x80010106 (-2147417850). IxChariot reports error CHR0424 (The Microsoft COM
library could not be initialized).
You can usually work around this problem by setting the [STAThread] attribute on
your main program.
The following blog entry discusses both the general problem and a specific workaround for managed C++ programs under VS.NET 7.1:
http://blogs.msdn.com/adam_nathan/archive/2003/07/18/56727.aspx

- 108 -

IxChariot APIGuide

Compiling and Linking Your Program

The files required to compile and link your program are included on your IxChariot DVDROM. There are two include files required for compiling and one library file required for
static linking.
The include files, CHRAPI.H and VoIP_DEFS.H, are located in the SDK\INCLUDE directory
of the DVD-ROM. These files can either be copied into your source file directory or copied
to a location identified by the INCLUDE environment variable.
The library file, CHRAPI.LIB, is located in the SDK\LIB directory of the DVD-ROM. This file
can either be copied into your source file directory or copied to a location identified by the
LIB environment variable.
If you choose to dynamically link to the IxChariot API DLL at runtime (by using the
LoadLibrary() and GetProcAddress() functions from Win32 API), the filename CHRAPI.DLL
should be used.
The programs using IxChariot API must run on a computer with a licensed version of IxChariot installed and the path to IxChariot must be added to the system path.

- 109 -

IxChariot APIGuide

C Functions

- 110 -

IxChariot APIGuide

API Utility Functions

The API utility functions are used to define and retrieve API information that is independent of specific objects (tests, pairs, etc.).

- 111 -

IxChariot APIGuide

CHR_api_delete_qos_template
DESCRIPTION
The CHR_api_delete_qos_template function deletes the specified QoS template from
the IxChariot library of QoS templates. The template must be present in the servqual.dat
file; otherwise the delete operation will fail.
C H R _API_R C
C H R _api _del et e_qos _t em pl at e(
C H R _STR I N G t emplat eN ame,
C H R _LEN GTH t emplat eLengt h
)

PARAMETERS
templateName [in]
A string containing the QoS template name.

templateLength [in]
The length of the QoS template name, excluding the null terminator. This string is limited
to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
C H R _OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_NO_SUCH_OBJECT

CHR_API_NOT_INITIALIZED

CHR_POINTER_INVALID

CHR_STRING_TOO_LONG

CHR_VALUE_INVALID

CHR_NO_MEMORY

See Return Code Summary for a detailed description of each return code.

- 112 -

IxChariot APIGuide

CHR_api_get_license_expiration_time
DESCRIPTION
The CHR_api_get_license_expiration_time function returns the expiration time for
borrowed licenses (CHR_LICENSE_TYPE_FLOATING_BORROW). It returns 0 for NODELOCKED and FLOATING licenses.
C H R _API_R C
C H R _api _get _l i c ens e_ex pi rat i on_t i m e(
C H R _LON G* ex pirat ionTime
)

PARAMETERS
expirationTime [out]
A pointer to the variable where the license expiration time value will be returned.

RETURN CODES
The following return code indicates that the function call was successful:
C H R _OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 113 -

IxChariot APIGuide

CHR_api_get_license_type
DESCRIPTION
The CHR_api_get_license_type function returns the value of the current Ixia license type.
C H R _API_R C
C H R _api_get _lic ens e_t y pe(
C H R _LI C EN SE_TYPE* lic ens eTy pe,
)

PARAMETERS
licenseType [out]
A pointer to the variable where the license type value (CHR_LICENSE_TYPE) will be
returned.

RETURN CODES
The following return code indicates that the function call was successful:
C H R _OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 114 -

IxChariot APIGuide

CHR_api_get_max_pairs
DESCRIPTION
The CHR_api_get_max_pairs function gets the maximum number of pairs and multicast
pairs allowed in a test for this installation of IxChariot.
C H R _API_R C
C H R _api_get _max _pairs (
C H R _C OU N T* max _pairs
)

PARAMETERS
max_pairs [out]
A pointer to the variable where the maximum number of pairs will be returned. For an
unlimited Console, the maximum number of pairs returned is CHR_INFINITE.

RETURN CODES
The following return code indicates that the function call was successful:
C H R _OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 115 -

IxChariot APIGuide

CHR_api_get_network_ip_list
DESCRIPTION
The CHR_api_get_network_ip_list function retrieves the list of available hardware performance pair network IP addresses that are configured for the given port management IP
address. These are the addresses that are used for the console as E1 and E2 for hardware
performance pairs and endpoints running on the Ixia port CPU.
The user must preallocate an array of strings that will be filled with the available IP
addresses. The user can call this method with a ip_addr_count set to 0. The return will be
CHR_BUFFER_TOO_SMALL and ip_addr_read will be set with the number of available
strings. Each string has a max length of CHR_MAX_ADDR_STRING. This is 16 bytes including
the NULL terminator for each address (E.g. "123.123.123.123\0"). Host names are not
valid.
If there are more available addresses than slots in the output list, the call will return CHR_
BUFFER_TOO_SMALL. ip_addr_read will be set to the number of strings that are available.
Note: This is only the number of actual strings set in ip_list when CHR_OK is returned.
This call is applicable for IxApplifier configurations only. If you load an Ixia network configuration file, the call will return the CHR_NO_APPLIFIER_CONFIGURATION error code.
The user owns the array of strings so no further calls to the API are necessary. Any valid
address returned by this call can be used in a call to CHR_api_get_port_mgmt_ip_list.
C H R _API_R C
C H R _ api _ get _ net w ork _ i p_l i s t (
C H R _ C H A R port _m gm t _ i p[ C H R _M A X _ A D D R _ S T R I N G] ,
C H R _ C OU N T i p_ addr_c ount ,
C H R _AD D R _STR I N G *ip_lis t ,
C H R _ C OU N T * i p_addr_ read
)

PARAMETERS
port_mgmt_ip [in]
The port management address as returned in a previous call to CHR_api_get_port_mgmt_
ip_list. This identifies the port to which the network IP addresses are associated.

ip_addr_count [in]
The count of strings the user is providing space for in ip_list. Zero when the user wants
to know the total count of strings available from the system.

ip_list [out]
An array of address strings. Each index receives a single IP address from the internal network IP list based on the given port management address. The user must preallocate with
the number of strings passed to the call in ip_addr_count. This may be CHR_NULL_HANDLE
when ip_addr_count is 0 when the user is checking for the number of available
addresses.

- 116 -

IxChariot APIGuide

ip_addr_read [out]
The pointer to the count of strings actually read when CHR_OK is returned. When CHR_
BUFFER_TOO_SMALL is returned, this is the total count of addresses available from the system, regardless of what was passed in ip_addr_count.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_OUT_OF_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_BUFFER_TOO_SMALL

CHR_NO_APPLIFIER_CONFIGURATION

See Return Code Summary for a detailed description of each return code.

- 117 -

IxChariot APIGuide

CHR_api_get_pair_type
DESCRIPTION
The CHR_api_get_pair_type function gets the pair type for a pair defined in a test. This
enables you to identify the specific parameters available for that pair. For example, if the
IxChariot test uses only regular pairs, then you can check for Average Throughput, Timing
Records completed, and so forth. If the test uses VoIP pairs, you can check for Average
MOS, Jitter delay variation, and so forth.
C H R _API_R C
C H R _ api _get _pai r_t y pe(
C H R _H AN D LE handle,
C H R _P A I R _T Y P E * t y pe
)

PARAMETERS
handle [in]
A handle returned by CHR_test_new() or CHR_mpair_new().

type [out]
A pointer to the variable where the pair type identifier (CHR_PAIR_TYPE) is returned. The
pair types are defined as:

- 118 -

IxChariot APIGuide

C H R _ P A I R _T Y P E _ R E G U L A R ( P a i r s w i t h n o n - s t r e a m i n g
scripts)

C H R _ P A I R _T Y P E _ S T R E A M I N G

C H R _ P A I R _T Y P E _ V OI P

C H R _ P A I R _T Y P E _ V I D E O

C H R _ P A I R _T Y P E _ H A R D W A R E

C H R _ P A I R _T Y P E _ H A R D W A R E _V OI P

With video multicast groups, the returned pair type for a video pair inside the
multicast group will be CHR_PAIR_TYPE_STREAMING, rather than CHR_PAIR_
TYPE_VIDEO.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_API_NOT_INITIALIZED

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 119 -

IxChariot APIGuide

CHR_api_get_port_mgmt_ip_list
DESCRIPTION
The CHR_api_get_port_mgmt_ip_list function retrieves the list of available hardware
performance pair port management IP addresses. These are the addresses that are used
for the console to know how to reach E1 and for E1 to know how to reach E2 for hardware
performance pairs and endpoints that reside on Ixia port CPUs.
The user must preallocate an array of strings that will be filled with the available IP
addresses. The user can call this method with a ip_addr_count set to 0. The return will be
CHR_BUFFER_TOO_SMALL and ip_addr_read will be set with the number of available
strings. Each string has a max length of CHR_MAX_ADDR_STRING. This is 16 bytes including
the NULL terminator for each address (E.g. "123.123.123.123\0"). Host names are not
valid.
If there are more available addresses than slots in the output list, the call will return CHR_
BUFFER_TOO_SMALL. ip_addr_read will be set to the number of strings that are available. Note: This is only the number of actual strings set in ip_list when CHR_OK is
returned.
This call is applicable for IxApplifier configurations only. If you load an Ixia network configuration file, the call will return the CHR_NO_APPLIFIER_CONFIGURATION error code.
The user owns the array of strings so no further calls to the API are necessary. Any valid
address returned by this call can be used in a call to CHR_api_get_network_ip_list.
C H R _API_R C
C H R _ api _ get _ port _m gm t _ i p_l i s t
C H R _ C OU N T i p_addr_ c ount ,
C H R _A D D R _S T R I N G* i p_ l i s t ,
C H R _ C OU N T * i p_addr_ read
)

PARAMETERS
ip_addr_count [in]
The count of strings the user is providing space for in ip_list. Zero when the user wants
to know the total count of strings available from the system.

ip_list [out]
An array of address strings. Each index receives a single IP address from the internal port
management IP list. The user must preallocate with the number of strings passed to the
call in ip_addr_count. This may be CHR_NULL_HANDLE when ip_addr_count is 0 when the
user is checking for the number of available addresses.

ip_addr_read [out]
The pointer to the count of strings actually read when CHR_OK is returned. When CHR_
BUFFER_TOO_SMALL is returned, this is the total count of addresses available from the system, regardless of what was passed in ip_addr_count.

- 120 -

IxChariot APIGuide

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_OUT_OF_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

l
l

CHR_BUFFER_TOO_SMALL
CHR_NO_APPLIFIER_CONFIGURATION

See Return Code Summary for a detailed description of each return code.

- 121 -

IxChariot APIGuide

CHR_api_get_reporting_port
DESCRIPTION
The CHR_api_get_reporting_port function gets the port number used to report results to
the IxChariot Console for the given network protocol type.
C H R _API_R C
C H R _api_get _report ing_port (
C H R _PR OTOC OL prot o,
C H R _POR T* port
)

PARAMETERS
proto [in]
The protocol type CHR_PROTOCOL_TCP or CHR_PROTOCOL_SPX.

port [out]
A pointer to the variable where the port number should be returned. A value of zero indicates that IxChariot automatically selects the port when a test is run using the protocol for
Console to Endpoint 1 communications.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 122 -

IxChariot APIGuide

CHR_api_get_return_msg
DESCRIPTION
The CHR_api_get_return_msg function gets the text message corresponding to the given
IxChariot API return code.
C H R _API_R C
C H R _api _get _ret urn_m s g (
C H R _API _R C rt nc ode,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
rtncode [in]
A code returned by an IxChariot API function.

buf [out]
A pointer to the buffer where the text message should be returned.

len [in]
The length of the provided buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 123 -

IxChariot APIGuide

CHR_api_get_version
DESCRIPTION
The CHR_api_get_version function gets the version of the IxChariot API.
C H R _API_R C
C H R _ a p i _ g e t _ v e rs i o n(
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
buf [out]
A pointer to the buffer where the version should be returned.

len [in]
The length of the provided buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 124 -

IxChariot APIGuide

CHR_api_initialize
DESCRIPTION
The CHR_api_initialize function initializes the IxChariot API. This function must be called
before any other IxChariot API function.
C H R _API_R C
C H R _api_init ializ e(
C H R _D ETAI L_LEVEL det ail,
C H R _S T R I N G ex t ended_i nf o,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
detail[in]
The detail level for extended error information, if requested. Refer to Error Detail Levels
for available levels. If detail is set to CHR_DETAIL_NONE, the extended_info buffer pointer
is null, or the buffer length is given as zero, no extended error information is returned if
the API could not be initialized. If the buffer is valid but not big enough, truncated extended error information will be returned.

extended_info [out]
A pointer to the buffer where the extended error information should be returned.

len [in]
The length of the given buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_OPERATION_FAILED

CHR_POINTER_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 125 -

IxChariot APIGuide

CHR_api_initialize_with_license_details
DESCRIPTION
The CHR_api_initialize_with_license_details function initializes the IxChariot API with the
specified license details. It must be called before any other IxChariot API function. Calling
this function while IxChariot console is open will fail with CHR_FLOATING_LICENSE_IN_
USE error code. This function can only be used for floating license initialization. This function cannot be used when a node locked license is already installed on the machine and will
fail with CHR_NOT_SUPPORTED if it is called for this case.
C H R _API_R C
C H R _api _i ni t i al i z e_w i t h_ l i c ens e_det ai l s (
C H R _D ETAI L_LEVEL det ail,
C H R _S T R I N G ex t ended_i nf o,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen,
C H R _S T R I N G s erv er_nam e,
C H R _C OU N T pair_c ount ,
C H R _ C OU N T day s _ t o_borrow )
)

PARAMETERS
detail[in]
The detail level for extended error information, if requested. Available levels are the same
as in the case of CHR_api_initialize. If detail is set to CHR_DETAIL_NONE, the extended_
info buffer pointer is null, or the buffer length is given as zero, no extended error information is returned if the API could not be initialized. If the buffer is valid but not big enough,
truncated extended error information will be returned.

extended_info [out]
A pointer to the buffer where the extended error information should be returned.

len [in]
The length of the given buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

server_name [in]
The name of the license server to try checking out pairs from.

pair_count[in]
The number of pairs to check out from the server.

- 126 -

IxChariot APIGuide

days_to_borrow [in]
The number of days to borrow the license for. If set to zero, the pairs will be checked out
as release on exit.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_OPERATION_FAILED

CHR_POINTER_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

CHR_NOT_SUPPORTED

CHR_LICENSE_ALREADY_BORROWED

CHR_FLOATING_LICENSE_IN_USE
A new error code has been added for this function, to indicate the fact that another
borrowed license has already been checked out for the current client and is still
valid. For borrowed licenses, a new check out with specific license details cannot be
performed until the last valid license has been released (by setting borrow days to
zero). If a valid borrowed license is found when trying init with parameters, the
function will fail and we will return CHR_LICENSE_ALREADY_BORROWED (error
code 144). The message corresponding to this code is "A license has already been
borrowed for this machine".
Another new error code, CHR_FLOATING_LICENSE_IN_USE, indicates that two different processes are trying to modigy license characteristics at the same time. The
message corresponding to this code is "The floating license is in use by IxChariot
console or other API program."

See Return Code Summary for a detailed description of each return code.

- 127 -

IxChariot APIGuide

CHR_api_license_change_borrow_time
DESCRIPTION
The CHR_api_license_change_borrow_time function changes the expiration time for all
the current licenses (console, VoIP, video. pairs, and so forth). It will fail if the current
license type is neither FLOATING nor FLOATING_BORROW. Calling this function while
IxChariot console is open will result in an error code being returned (CHR_FLOATING_
LICENSE_IN_USE).
C H R _api _l i c ens e_c hange_borrow _ t i m e(
C H R _C OU N T day s ToBorrow
)
This function will check-in all the current features and then check them out using the new
expiration time. If the check-out fails, there will be no license for any feature.
This function cannot be called while the IxChariot console is open. Calling this
subcommand while IxChariot console is open will result in an error code being
returned (CHR_OPERATION_ FAILED).

PARAMETERS
daysToBorrow [in]
The number of days for which the license is borrowed. If daysToBorrow is zero, floating
licenses will be used.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_OPERATION_FAILED

CHR_FLOATING_LICENSE_IN_USE

See Return Code Summary for a detailed description of each return code.

- 128 -

IxChariot APIGuide

CHR_api_license_change_license_server
DESCRIPTION
The CHR_api_license_change_license_server function changes the license server
used to check out a floating license. It will check in any previously checked out licenses
and try a check out with the same license parameters (pair count and borrow days) from
the new server.
C H R _API_R C
C H R _api _l i c ens e_c hange_l i c ens e_s erv er(
C H R _STR I N G s erv er_name
)
This function will fail if the currently checked out license is not of type FLOATING or
FLOATING_BORROW or if IxChariot console is running at the time of the call. If checking
out the specified number of pairs from the new server fails, the license will be invalidated.
Calling this function while IxChariot console is open will result in an error code being
returned (CHR_FLOATING_LICENSE_IN_USE).

PARAMETERS
server_name [in]
The name of the new server to attempt the new license check out from.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_OPERATION_FAILED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_NOT_SUPPORTED

CHR_FLOATING_LICENSE_IN_USE

See Return Code Summary for a detailed description of each return code.

- 129 -

IxChariot APIGuide

CHR_api_license_checkin_pairs
DESCRIPTION
The CHR_api_license_checkin_pairs function checks in to the license server any pairs
that are presently checked out. This function will fail if the license type is neither
FLOATING nor FLOATING_BORROW. It does nothing if there are no pairs checked-out.
C H R _api _l i c ens e_c hec k out _pai rs (
v oid
)
Calling this function while IxChariot console is open will result in an error code
being returned (CHR_FLOATING_LICENSE_IN_USE).

PARAMETERS
This function takes no parameters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_OPERATION_FAILED

CHR_FLOATING_LICENSE_IN_USE

See Return Code Summary for a detailed description of each return code.

- 130 -

IxChariot APIGuide

CHR_api_license_checkout_pairs
DESCRIPTION
The CHR_api_license_checkout_pairs function checks out the specified number of
pairs from the license server. This function is applicable only if the current license is either
FLOATING or FLOATING_BORROW.
C H R _api _l i c ens e_c hec k out _pai rs (
C H R _C OU N T noPairs
)
If any pairs are already checked-out, they will be checked-in and the number of pairs specified in noPairs will be checked-out. If the check-out fails,there will be no license for the
pairs.
Calling this function while IxChariot console is open will result in an error code
being returned (CHR_FLOATING_LICENSE_IN_USE).

PARAMETERS
noPairs [in]
The number of pairs to check out. The number of pairs specified must be positive. In addition, the actual number of pairs that will be checked-out from the server will be rounded to
the next highest multiple of 10. For example, if you specify 14 as the value for noPairs, 20
pairs will be checked out.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_OPERATION_FAILED

CHR_FLOATING_LICENSE_IN_USE

See Return Code Summary for a detailed description of each return code.

- 131 -

IxChariot APIGuide

CHR_api_license_get_borrow_days_remaining
DESCRIPTION
The CHR_api_license_get_borrow_days_remaining function returns the number of borrow days remaining for the current license check out. This function returns:
l

0, if check out type is release on exit.

Number of days remaining if check out type is borrow.

CHR_NOT_SUPPORTED if check out type is node locked.

CHR_API_RC
CHR_api_license_get_borrow_days_remaining(
CHR_COUNT *days_remaining
)

PARAMETERS
days_remaining [out]
A pointer to the variable where the number of remaining borrow-days is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_NOT_SUPPORTED

See Return Code Summary for a detailed description of each return code.

- 132 -

IxChariot APIGuide

CHR_api_license_get_license_server
DESCRIPTION
The CHR_api_license_get_license_server function gets the name of the license server
currently in use for license check out.
C H R _API_R C
C H R _api_lic ens e_get _lic ens e_s erv er(
C H R _STR I N G *s erv er_name,
C H R _LEN GTH len,
C H R _LEN GTH *rt len
)

PARAMETERS
server_name [out]
A pointer to the buffer where the server name should be returned.

len [in]
The length of the provided buffer.

rtlen[out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator, like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUGGER_TOO_SMALL

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_VALUE_INVALID

CHR_NOT_SUPPORTED

See Return Code Summary for a detailed description of each return code.

- 133 -

IxChariot APIGuide

CHR_api_license_get_test_pair_count
DESCRIPTION
The CHR_api_license_get_test_pair_count function returns a count of the number of
pairs configured for the specified IxChariot test. This function can be called even if there is
no license for the pairs.
C H R _ api _l i c ens e_ get _t es t _pai r_ c ount (
C H R _STR I N G t es t FileN ame,
C H R _LEN GTH t es t FileN ameLengt h,
C H R _C OU N T *pairC ount
)

PARAMETERS
testFileName [in]
A handle returned by CHR_test_new().

testFileNameLength [in]
The length of the test file name.

pairCount [out]
A pointer to the variable where the pair count is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 134 -

IxChariot APIGuide

CHR_api_modify_qos_tos_template
DESCRIPTION
The CHR_api_modify_qos_tos_template function modifies the specified TOS template.
The template must be present in the servqual.dat file; otherwise the modify operation will
fail.
C H R _API_R C
C H R _api _m odi f y _qos _t os _t em pl at e(
C H R _QOS _T E M P LA T E _T Y P E t em pl at eT y pe,
C H R _STR I N G t emplat eN ame,
C H R _LEN GTH t emplat eLengt h,
C H R _BYTE t os Mas k
)
Note that you can receive the CHR_VALUE_INVALID return code for any of these reasons:
to indicate that a template with the specified name does not exist in the servqual.dat file;
to indicate that the template type passed as a parameter is not one of the valid values for
the tosMask parameter; or, for Layer 2, to indicate that the tosMask parameter does not
have a value in the 0-7 interval.

PARAMETERS
templateType [in]
The type of template that will be modified. This must be CHR_QOS_TEMPLATE_TOS_BIT_
MASK, CHR_QOS_TEMPLATE_DIFFSERV, or CHR_QOS_TEMPLATE_L2_PRIORITY.

templateName [in]
A string containing the QoS template name.

templateLength [in]
The length of the QoS template name, excluding the null terminator. This string is limited
to 64 characters.

tosMask [in]
The new TOS mask value to be used by the template, given as a decimal number. For
example, if the desired TOS mask is 0110 0000, you would enter 96 as the mask value. For
Layer 2, must be in the 0-7 interval.

RETURN CODES
The following return code indicates that the function call was successful:
C H R _OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_NO_SUCH_OBJECT

CHR_API_NOT_INITIALIZED

- 135 -

IxChariot APIGuide

CHR_POINTER_INVALID

CHR_STRING_TOO_LONG

CHR_VALUE_INVALID

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 136 -

IxChariot APIGuide

CHR_api_new_qos_tos_template
DESCRIPTION
The CHR_api_new_qos_tos_template function creates a new TOS template in the
IxChariot QoS template library.
C H R _API_R C
C H R _api_new _qos _t os _t emplat e(
C H R _QOS _T E M P LA T E _T Y P E t em pl at eT y pe,
C H R _STR I N G t emplat eN ame,
C H R _LEN GTH t emplat eLengt h,
C H R _BYTE t os Mas k
)
Note that you can receive the CHR_VALUE_INVALID return code for any of these reasons:
to indicate that a template with the specified name already exists in the servqual.dat file;
to indicate that the template type passed as a parameter is not one of the valid values for
the tosMask parameter; or, for Layer 2, to indicate that the tosMask parameter does not
have a value in the 0-7 interval.

PARAMETERS
templateType [in]
The type of template that will be created. This must be CHR_QOS_TEMPLATE_TOS_BIT_
MASK, CHR_QOS_TEMPLATE_DIFFSERV, or CHR_QOS_TEMPLATE_L2_PRIORITY.

templateName [in]
A string containing the QoS template name.

templateLength [in]
The length of the QoS template name, excluding the null terminator. This string is limited
to 64 characters.

tosMask [in]
The TOS mask value to be used by the template, given as a decimal number. For example,
if the desired TOS mask is 0110 0000, you would enter 96 as the mask value. For Layer 2,
must be in the 0-7 interval.

RETURN CODES
The following return code indicates that the function call was successful:
C H R _OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_POINTER_INVALID

- 137 -

IxChariot APIGuide

CHR_STRING_TOO_LONG

CHR_VALUE_INVALID

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 138 -

IxChariot APIGuide

CHR_api_set_reporting_port
DESCRIPTION
The CHR_api_set_reporting_port function sets or changes the port number used to report
results to the Console. The port number can only be changed if the current process has not
run a test. After the current process runs a test, the reporting port is allocated by the API
and attempts to change it will result in a CHR_OBJECT_IN_USE return code.
C H R _API_R C
C H R _api_s et _report ing_port (
C H R _PR OTOC OL prot o,
C H R _POR T port
)

PARAMETERS
proto [in]
The protocol for which the port number is specified. This must be either CHR_PROTOCOL_
TCP or CHR_PROTOCOL_SPX.

port [in]
The port number in the range of 1 - 65535. Specifying a zero causes IxChariot to automatically select the port when a test is run using the given protocol for Console to Endpoint
1 communications.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_TEST_RUNNINGCHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 139 -

IxChariot APIGuide

Application Group Object Functions

The IxChariot API provides a set of functions for working with application groups. Application groups provide the means to synchronize the actions of two or more pairs during a
test. This allows you to simulate the behavior of applications that use more than one simultaneous connection (such as FTP, which uses one connection for control and the other for
data transfer).
You can use the IxChariot application group functions to perform all of the following activities:
l

load one or more application groups from a file with an .iag extension.

save an application group to a file with an .iag extension.

copy one application group to another.

add an application group to a test.

remove an application group from a test.

create an (empty) application group.

edit some application group attributes (name, comment).

validate an application group (on request and when starting the test).

add a pair to an application group.

remove a pair from an application group.

get the handle of a pair from an application group.

add an event to an application group.

remove an event from an application group.

get the number of events from the application group.

get the name and the comment of a specific event.

Refer to the IxChariot Script Development and Editing Guide for a detailed description of
application groups.

- 140 -

IxChariot APIGuide

CHR_app_group_add_event
DESCRIPTION
The CHR_app_group_add_event function adds an event to the designated application
group. Events are objects defined within application groups and passed as parameters to
the WAIT_EVENT and SIGNAL_EVENT script commands. An event is simply a unique name
(a character string) defined within an application group. An event does not specify any
actions. Rather, it acts as a token to trigger the scripts to pause or resume execution at
specific points in the scripts.
C H R _API_R C
C H R _app_group_add_ev ent(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _STR IN G
ev ent N ame,
C H R _LEN GTH
ev ent N ameLengt h,
C H R _STR IN G
ev ent C omment ,
C H R _LEN GTH
ev ent C omment Lengt h
)
The application group must be either unowned or locked.

PARAMETERS
appGroupHandle [in]
A handle for the target application group object, returned by CHR_app_group_new(), CHR_
test_get_app_group_by_name(), or CHR_test_get_app_group_by_index().

eventName [in]
A name for the event. Note that:
l

An event name can be any non-empty string other than "Not Assigned" (otherwise,
CHR_VALUE_INVALID will be returned).
The event name must be unique within that application group (otherwise, CHR_
DUPLICATE_NAME will be returned).

eventNameLength[in]
The length, in bytes, of the event name. Note that eventNameLength must be lower than
CHR_MAX_APP_GROUP_EVENT_NAME.

eventComment [in]
An optional comment for this event.

eventCommentLength [in]
The length, in bytes, of the event name comment. Note that eventCommentLength must be
lower than CHR_MAX_APP_GROUP_EVENT_COMMENT.

RETURN CODES
The following return code indicates that the function call was successful:

- 141 -

IxChariot APIGuide
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_STRING_TOO_LONG

CHR_DUPLICATE_NAME

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 142 -

IxChariot APIGuide

CHR_app_group_add_pair
DESCRIPTION
The CHR_app_group_add_pair function adds an endpoint pair to the designated application group.
C H R _API_R C
C H R _app_group_add_pair(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _P A I R _H A N D LE
pairH andle
)
The application group must be either unowned or locked.

PARAMETERS
appGroupHandle [in]
A handle for the target application group object, returned by CHR_app_group_new(), CHR_
test_get_app_group_by_name(), or CHR_test_get_app_group_by_index().

pairHandle [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID

CHR_PGM_INTERNAL_ERROR

CHR_SCRIPT_TOO_LARGE

See Return Code Summary for a detailed description of each return code.
When CHR_OBJECT_INVALID is returned, extended error information provides details of
the operation failure. Use CHR_common_error_get_info to get this extended error information.

- 143 -

IxChariot APIGuide

CHR_app_group_copy
DESCRIPTION
The CHR_app_group_copy function copies the attributes of the source application group to
the destination application group. This does not include any results information.
C H R _API_R C
C H R _app_group_c opy (
C H R _APP_GR OU P_H AN D LE t oAppGroupH andle,
C H R _APP_GR OU P_H AN D LE f romAppGroupH andle
)
The attributes that are copied are:
l

Application Group name

Application Group comment

Application Group save filename

Console management address

Pair management address

Pair protocol

Pair QoS name

Pair objects
The pairs in the source object are added to the pairs in the destination.

PARAMETERS
toAppGroupHandle [in]
A handle for the destination object, returned by CHR_app_group_new(), CHR_test_get_
app_group_by_name(), or CHR_test_get_app_group_by_index().

fromAppGroupHandle [in]
A handle for the source object, returned by CHR_app_group_new(), CHR_test_get_app_
group_by_name(), or CHR_test_get_app_group_by_index().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_APP_GROUP_DUPLICATE_NAME

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

- 144 -

IxChariot APIGuide

CHR_OPERATION_FAILED

CHR_PAIR_LIMIT_EXCEEDED

CHR_PGM_INTERNAL_ERROR

CHR_SCRIPT_TOO_LARGE

See Return Code Summary for a detailed description of each return code.
When CHR_OBJECT_INVALID is returned, extended error information provides details of
the operation failure. Use CHR_common_error_get_info to get this extended error information.

- 145 -

IxChariot APIGuide

CHR_app_group_delete
DESCRIPTION
The CHR_app_group_delete function frees all memory associated with the given application group.
C H R _API_R C
C H R _app_group_delet e(
C H R _APP_GR OU P_H AN D LE appGroupH andle
)
This function will not delete the application group if it has not been saved since it was
defined or modified (CHR_TEST_NOT_SAVED will be returned). Note that you can use the
CHR_app_group_force_delete function to delete an application group that has not been
saved.

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().
After verifying that the handle refers to a valid application group object, the function
checks to ensure that it is not referenced by a test object known by the API. The application group object is not deleted if it is contained by a test object.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_OPERATION_FAILED

CHR_PGM_INTERNAL_ERROR

CHR_TEST_RUNNING

CHR_TEST_NOT_SAVED

See Return Code Summary for a detailed description of each return code.
When CHR_OBJECT_INVALID is returned, extended error information provides details of
the operation failure. Use CHR_common_error_get_info to get this extended error information.

- 146 -

IxChariot APIGuide

CHR_app_group_disable
DESCRIPTION
The CHR_app_group_disable function disables or enables all of the pairs assigned to the
specified application group. IxChariot ignores any disabled pairs when running a test.
CHR_API_RC
CHR_app_group_disable(
CHR_APP_GROUP_HANDLE
CHR_BOOLEAN
)

appGroupHandle,
disable

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

disable [in]
Specifies the action to perform:
l

CHR_TRUE: Disable all the application group pairs for the test.

CHR_FALSE: Enable all the application group pairs for the test.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 147 -

IxChariot APIGuide

CHR_app_group_force_delete
DESCRIPTION
The CHR_app_group_force_delete function frees all memory associated with the given
application group.
C H R _API_R C
C H R _app_group_f orc e_delet e(
C H R _APP_GR OU P_H AN D LE appGroupH andle
);
This function will delete the application group whether or not it has been saved.

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OPERATION_FAILED

CHR_PGM_INTERNAL_ERROR

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.
When CHR_OBJECT_INVALID is returned, extended error information provides details of
the operation failure. Use CHR_common_error_get_info to get this extended error information.

- 148 -

IxChariot APIGuide

CHR_app_group_get_address
DESCRIPTION
The CHR_app_group_get_address function returns the IP address of the given pair within
the application group.
C H R _API_R C
C H R _app_group_get _addres s(
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _C OU N T addres s I ndex ,
C H R _STR I N G addres s ,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h
)

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

addressIndex [in]
An address index returned by CHR_app_group_get_address_count(). The index identifies a
specific (and unique) network address within the application group.

address [out]
A pointer to the buffer where the management address is returned.

maxLength [in]
The length of the provided buffer.

length [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

- 149 -

IxChariot APIGuide

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 150 -

IxChariot APIGuide

CHR_app_group_get_address_count
DESCRIPTION
The CHR_app_group_get_address_count function gets the number of unique network
addresses used in the given application group.
C H R _API_R C
C H R _app_group_get _addres s _c ount(
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _C OU N T* addres s C ount
)
Other application group functions use CHR_app_group_get_address_count to obtain the
index of a network address in an application group.

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

addressCount [out]
A pointer to the variable where the number of application group pairs is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 151 -

IxChariot APIGuide

CHR_app_group_get_comment
DESCRIPTION
The CHR_app_group_get_comment function gets the comment for the given application
group.
C H R _API_R C
C H R _app_group_get _c omment(
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _STR I N G c omment ,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h
)

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

comment [out]
A pointer to the buffer where the comment is returned.

maxLength [in]
The length of the buffer.

length [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL
CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 152 -

IxChariot APIGuide

CHR_app_group_get_event
DESCRIPTION
The CHR_app_group_get_event function gets information about a specific event defined
in the given application group.
C H R _API_R C
C H R _app_group_get _ev ent(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _C OU N T
index ,
C H R _STR IN G
ev ent N ame,
C H R _LEN GTH
ev ent N ameMax Lengt h,
C H R _LEN GTH *
ev ent N ameLengt h,
C H R _STR IN G
ev ent C omment ,
C H R _LEN GTH
ev ent C omment Max Lengt h,
C H R _LEN GTH *
ev ent C omment Lengt h
)

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

index [in]
A zero-based index that can take values between 0 and CHR_app_group_get_event_count
() 1. The index identifies a specific (and unique) event within the application group. For
example, if there are four events defined in an application group, their index numbers are
0, 1, 2, and 3.

eventName [out]
The name of the buffer to which the event name is returned.

eventNameMaxLength [in]
The length of the buffer provided for eventName.

eventNameLength[out]
A pointer to the variable where the length of the event name is returned.

eventComment [out]
The name of the buffer to which the event comment is returned.

eventCommentMaxLength [in]
The length of the buffer provided for eventComment.

eventCommentLength [out]
A pointer to the variable where the length of the event comment is returned.

- 153 -

IxChariot APIGuide

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_BUFFER_TOO_SMALL

CHR_NO_SUCH_OBJECT

See Return Code Summary for a detailed description of each return code.

- 154 -

IxChariot APIGuide

CHR_app_group_get_event_count
DESCRIPTION
The CHR_app_group_get_event_count function gets the number of events defined in the
given application group.
C H R _API_R C
C H R _app_group_get _ev ent _c ount(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _C OU N T*
ev ent C ount
)
Other application group functions use CHR_app_group_get_event_count to obtain the index
of an event in an application group.

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

eventCount[out]
A pointer to the variable where the number of events is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 155 -

IxChariot APIGuide

CHR_app_group_get_filename
DESCRIPTION
The CHR_app_group_get_filename function gets the name of the file from which this
application group was loaded or to which it will be saved.
C H R _API_R C
C H R _app_group_get _f ilename(
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _STR I N G buf f er,
C H R _LEN GTH buf f erLengt h,
C H R _LEN GTH * ret Lengt h
)

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

buffer [out]
A pointer to the buffer where the filename is returned. The returned filename includes any
specified path information.

bufferLength [in]
The length of the provided buffer.

retLength [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 156 -

IxChariot APIGuide

CHR_app_group_get_lock
DESCRIPTION
The function CHR_app_group_get_lock returns a Boolean value that indicates whether
the application group is locked (CHR_TRUE) or unlocked (CHR_FALSE). An application
group object that is contained by a test object must be locked before any of its attributes
(such as its endpoint address) can be set.
C H R _API_R C
C H R _app_group_get _loc k (
C H R _APP_GR OU P_H AN D LE
C H R _BOOLEAN * loc k
)

appGroupH andle,

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

lock [out]
A pointer to the variable where the Boolean "lock" value is returned.

RETURN CODES
The following return code indicates the function call was successful:
CHR_OK
The following return codes indicate an error occurred:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_INVALID

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 157 -

IxChariot APIGuide

CHR_app_group_get_management_address
DESCRIPTION
The CHR_app_group_get_management_address function gets the management address
for the given endpoint pair in the application group.
C H R _API_R C
C H R _app_group_get _m anagem ent _addres s (
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _C OU N T addres s I ndex ,
C H R _STR I N G addres s ,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h
)

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

addressIndex [in]
An address index returned by CHR_app_group_get_management_address_count(). The
index identifies a specific (and unique) management address within the application group.

address [out]
A pointer to the buffer where the management address is returned.

maxLength [in]
The length of the provided buffer.

length [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

- 158 -

IxChariot APIGuide

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 159 -

IxChariot APIGuide

CHR_app_group_get_management_address_count
DESCRIPTION
The CHR_app_group_get_management_address_count function gets the number of
unique management addresses owned by the given application group. If the management
address is not user-defined (that is, USE_CONSOLE_E1_ADDR and USE_SETUP_E1_E2_ADDR
are false), the address is not counted.
C H R _API_R C
C H R _app_group_get _m anagem ent _addres s _c ount (
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _C OU N T* addres s C ount
)
Other application group functions use CHR_app_group_get_management_address_count to
obtain the index of a management address in an application group.

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

addressCount [out]
A pointer to the variable where the number of management addresses is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 160 -

IxChariot APIGuide

CHR_app_group_get_name
DESCRIPTION
The CHR_app_group_get_name function gets the name of the given application group.
C H R _API_R C
C H R _app_group_get _name(
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _STR I N G name,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h
)

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

name [out]
A pointer to the buffer where the application group name is returned.

maxLength
The length of the buffer.

length [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 161 -

IxChariot APIGuide

CHR_app_group_get_pair
DESCRIPTION
The CHR_app_group_get_pair function gets the handle of a specified pair from the designated application group.
C H R _API_R C
C H R _app_group_get _pair(
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _C OU N T index ,
C H R _P A I R _H A N D LE * pai rH andl e
)

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

index [in]
A zero-based index that can take values between 0 and CHR_app_group_get_pair_count
() 1. The index identifies a specific pair within the application group. For example, if
there are four pairs in an application group, their index numbers are 0, 1, 2, and 3.

pairHandle [out]
A pointer to the variable where the pair handle is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 162 -

IxChariot APIGuide

CHR_app_group_get_pair_count
DESCRIPTION
The CHR_app_group_get_pair_count function gets the number of endpoint pairs owned
by the given application group.
C H R _API_R C
C H R _ app_ group_ get _pai r_c ount (
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _C OU N T* pairC ount
)
Other application group functions use CHR_app_group_get_pair_count to obtain the index
of a pair in an application group.

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

pairCount [out]
A pointer to the variable where the number of pairs is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 163 -

IxChariot APIGuide

CHR_app_group_get_pair_management_protocol
DESCRIPTION
The CHR_app_group_get_pair_management_protocol function gets the Endpoint 1 to
Endpoint 2 management protocol for the given pair within the application group.
C H R _API_R C
C H R _ app_ group_ get _pai r_m anagem ent _ prot oc ol (
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _C OU N T pairI ndex ,
C H R _PR OTOC OL* prot oc ol
)
As of IxChariot 6.70, this function has been deprecated. The function is still available, but the recommended procedure is to get the handle of the pair and use
the pair API functions.

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

pairIndex [in]
An address index returned by CHR_app_group_get_pair_count(). The index identifies the
specific pair within the application group.

protocol [out]
A pointer to the variable where the protocol is returned. See the CHR_pair_set_protocol
function for applicable protocols.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 164 -

IxChariot APIGuide

CHR_app_group_get_pair_protocol
DESCRIPTION
The CHR_app_group_get_pair_protocol function gets the Endpoint 1 to Endpoint 2 network
protocol for the given endpoint pair within the application group.
C H R _API_R C
C H R _ app_ group_ get _pai r_prot oc ol (
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _C OU N T pairI ndex ,
C H R _PR OTOC OL* prot oc ol
)
As of IxChariot 6.70, this function has been deprecated. The function is still available, but the recommend procedure is to get the handle of the pair and use the
pair API functions.

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

pairIndex [in]
An address index returned by CHR_app_group_get_pair_count(). The index identifies the
specific pair within the application group.

protocol [out]
A pointer to the variable where the protocol is returned. See the CHR_pair_set_protocol
function for applicable protocols.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 165 -

IxChariot APIGuide

CHR_app_group_get_pair_qos_name
DESCRIPTION
The CHR_app_group_get_pair_qos_name function gets the service quality name for the
given endpoint pair.
C H R _API_R C
C H R _ app_ group_ get _pai r_qos _ nam e(
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _C OU N T pairI ndex ,
C H R _STR I N G qos N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h
)
This function has been deprecated, as of IxChariot 6.70. The function is still
available, but the recommend procedure is to get the handle of the pair and use
the pair API functions.

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

pairIndex [in]
An address index returned by CHR_app_group_get_pair_count(). The index identifies the
specific pair within the application group.

qosName [out]
A pointer to the buffer where the service quality name is returned.

maxLength [in]
The length of the provided buffer.

length [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

- 166 -

IxChariot APIGuide

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 167 -

IxChariot APIGuide

CHR_app_group_is_disabled
DESCRIPTION
The CHR_app_group_is_disabled function determines whether or not the pairs in the
specified application group are disabled.
CHR_API_RC
CHR_app_group_is_disabled(
CHR_APP_GROUP_HANDLE
CHR_BOOLEAN*
)

appGroupHandle,
disabled

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

disabled [out]
A pointer to the variable where the Boolean value is returned. The returned values can be:
l

CHR_TRUE: All the pairs in the specified application group are disabled.

CHR_FALSE: All the pairs in the specified application group are enabled.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 168 -

IxChariot APIGuide

CHR_app_group_new
DESCRIPTION
The CHR_app_group_new function creates an application group object and initializes it to
object default values. See Application Group Object Default Values for information on the
object default values.
C H R _API_R C
C H R _app_group_new(
C H R _APP_GR OU P_H AN D LE* appGroupH andle
)

PARAMETERS
appGroupHandle [out]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_OUT_OF_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 169 -

IxChariot APIGuide

CHR_app_group_remove_event
DESCRIPTION
The CHR_app_group_remove_event function removes an event from the designated
application group.
C H R _API_R C
C H R _app_group_rem ov e_ev ent (
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _STR IN G
ev ent N ame,
C H R _LEN GTH
ev ent N ameLengt h
)
The application group must be either unowned or locked.
The removed event will be set to "Not Assigned" in all the pairs that use it in the
application group.

PARAMETERS
appGroupHandle [in]
A handle for the target application group object, returned by CHR_app_group_new(), CHR_
test_get_app_group_by_name(), or CHR_test_get_app_group_by_index().

eventName [in]
The name of the event to remove.

eventNameLength[in]
The length, in bytes, of the event name.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 170 -

IxChariot APIGuide

CHR_app_group_remove_pair
DESCRIPTION
The CHR_app_group_remove_pair function removes an endpoint pair from the designated application group.
C H R _API_R C
C H R _app_group_rem ov e_pai r(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _P A I R _H A N D LE
pairH andle
)
The application group must be either unowned or locked.
All the event variables inside the pair script will be set to "Not Assigned".

PARAMETERS
toAppGroupHandle [in]
A handle for the target application group object, returned by CHR_app_group_new(), CHR_
test_get_app_group_by_name(), or CHR_test_get_app_group_by_index().

pairHandle [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.
When CHR_OBJECT_INVALID is returned, extended error information provides details of
the operation failure. Use CHR_common_error_get_info to get this extended error information.

- 171 -

IxChariot APIGuide

CHR_app_group_save
DESCRIPTION
The CHR_app_group_save function saves the given application group to the currently
defined filename.
C H R _API_R C
C H R _app_group_s av e(
C H R _APP_GR OU P_H AN D LE appGroupH andle
)
Note that:
l

The function will save only one application group in the file.

The function will not save application groups without pairs.

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_TEST_FILE

CHR_OBJECT_INVALID

CHR_OPERATION_FAILED

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.
When CHR_OBJECT_INVALID is returned, extended error information provides details of
the operation failure. Use CHR_common_error_get_info to get this extended error information.

- 172 -

IxChariot APIGuide

CHR_app_group_set_address
DESCRIPTION
The CHR_app_group_set_address function sets or changes a network address within the
application group.
C H R _API_R C
C H R _app_group_s et _addres s(
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _C OU N T addres s I ndex ,
C H R _STR I N G addres s ,
C H R _LEN GTH addres s Lengt h
)
When you use this function to change a network address, be aware that your change may
modify the address index numbers. Specifically, if your modification changes the number
of unique network addresses, the index numbers returned by CHR_app_group_get_
address_count will also change. For example, if you have three unique network addresses
in an application group, and you change the first address (index 0) such that it is identical
to the second address, the index values for the second and third addresses will change to 0
and 1 (they are no longer 1 and 2). This occurs because CHR_app_group_get_address_
count counts the number of unique addresses. You can account for this in your applications
by doing one of the following:
l
l

Either call CHR_app_group_get_address_count after any address change;

Or always change the addresses in reverse order (for example: change index2 first,
followed by index 1, followed by index 0).

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

addressIndex [in]
An address index returned by CHR_app_group_get_address_count(). The index identifies a
specific (and unique) network address within the application group.

address [in]
A string containing the address for Endpoint 1 (IPv4 or IPv6).

addressLength [in]
The length of the endpoint address string, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK

- 173 -

IxChariot APIGuide
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 174 -

IxChariot APIGuide

CHR_app_group_set_comment
DESCRIPTION
The CHR_app_group_set_comment function sets or changes the comment for the given
application group.
C H R _API_R C
C H R _app_group_s et _c omment(
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _STR I N G c omment ,
C H R _LEN GTH lengt h
);

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

comment [in]
The string containing the new comment.

length [in]
The length of the comment string, excluding the null terminator. This string is limited to
129 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 175 -

IxChariot APIGuide

CHR_app_group_set_filename
DESCRIPTION
The CHR_app_group_set_filename function sets or changes the name of the file to which
the given test is saved.
C H R _API_R C
C H R _app_group_s et _f ilename(
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _STR I N G f ilename,
C H R _LEN GTH f ilenameLengt h
)

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

filename [in]
A string containing the filename. The filename may be specified using a relative or an absolute pathname. Note that once you've set the filename, you cannot change it back to the
loaded filename. To reset the filename to the name of the loaded test, use a null filename
parameter and a "0" filename length.

filenameLength [in]
The length of the filename string, excluding the null terminator. The maximum length of
the application group filename is 602 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OPERATION_FAILED*

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_STRING_TOO_LONG

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 176 -

IxChariot APIGuide
When CHR_OBJECT_INVALID is returned, extended error information provides details of
the operation failure. Use CHR_common_error_get_info to get this extended error information.

- 177 -

IxChariot APIGuide

CHR_app_group_set_lock
DESCRIPTION
The CHR_app_group_set_lock function takes one of the following actions:
l

locks an unlocked application group object if lock is CHR_TRUE.

unlocks a locked application group object if lock is CHR_FALSE.

An application group object that is contained by a test object must be locked before any of
its attributes (such as endpoint addresses) can be set.
An application group object cannot be locked if it is contained by a test object that has results or is running. If you attempt to lock a pair object that is already locked, the pair object
remains locked.
C H R _API_R C
C H R _app_group_s et _loc k (
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _BOOLEAN * loc k
)

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

lock [in]
A CHR_BOOLEAN, where CHR_TRUE locks the (unlocked) application group object, and
CHR_FALSE unlocks the (locked) object.

RETURN CODES
The following return code indicates the function call was successful:
CHR_OK
The following return codes indicate an error occurred:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_INVALID

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 178 -

IxChariot APIGuide

CHR_app_group_set_management_address
DESCRIPTION
The CHR_app_group_set_management_address function sets or changes a management
address in the application group.
C H R _API_R C
C H R _app_group_s et _m anagem ent _addres s (
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _C OU N T addres s I ndex ,
C H R _STR I N G addres s ,
C H R _LEN GTH addres s Lengt h
)
When you use this function to change a management address, be aware that your change
may modify the management address index numbers. Specifically, if your modification
changes the number of unique management addresses, the index numbers returned by
CHR_app_group_get_management_address_count will also change. For example, if you
have three unique management addresses in an application group, and you change the
first address (index 0) such that it is identical to the second address, the index values for
the second and third addresses will change to 0 and 1 (they are no longer 1 and 2). This
occurs because CHR_app_group_get_management_address_count counts the number of
unique management addresses. You can account for this in your applications by doing one
of the following:
l

Either call CHR_app_group_get_management_address_count after any management

address change;
Or always change the addresses in reverse order (for example: change index2 first,
followed by index 1, followed by index 0).

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

addressIndex [in]
A handle returned by CHR_app_group_get_management_address_count(). The index identifies a specific (and unique) management address within the application group.

address [in]
A string containing the management address (IPv4 or IPv6).

addressLength [in]
The length of the endpoint address string, excluding the null terminator. This string is limited to 64 char.

RETURN CODES
The following return code indicates that the function call was successful:

- 179 -

IxChariot APIGuide
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 180 -

IxChariot APIGuide

CHR_app_group_set_name
DESCRIPTION
The CHR_app_group_set_name function sets or changes the name of the given application
group.
group.
C H R _API_R C
C H R _app_group_s et _name(
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _STR I N G name,
C H R _LEN GTH lengt h
)
The application group name must be unique within a test.

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

name [in]
A string containing the name for the application group.

length [in]
The length of the name string, excluding the null terminator. This string is limited to 25
characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_APP_GROUP_DUPLICATE_NAME

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 181 -

IxChariot APIGuide

- 182 -

IxChariot APIGuide

CHR_app_group_set_pair_management_protocol
DESCRIPTION
The CHR_app_group_set_pair_management_protocol function sets or changes the management protocol for the given pair within the application group.
C H R _API_R C
C H R _ app_ group_ s et _pai r_m anagem ent _ prot oc ol (
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _C OU N T pairI ndex ,
C H R _PR OTOC OL prot oc ol
)
As of IxChariot 6.70, this function has been deprecated. The function is still available, but the recommend procedure is to get the handle of the pair and use the
pair API function.

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

pairIndex [in]
A handle returned by CHR_app_group_get_pair_count(). The index identifies the specific
pair within the application group.

protocol [in]
Specifies the protocol type: CHR_PROTOCOL_UDP, CHR_PROTOCOL_RTP, CHR_PROTCOL_
TCP, CHR_PROTOCOL_IPX, or CHR_PROTOCOL_SPX.
With the separately licensed IPv6 Test Module, also provides CHR_PROTCOL_TCP6, CHR_
PROTOCOL_UDP6, and CHR_PROTOCOL_RTP6.
With the VoIP Test Module, also provides CHR_PROTOCOL_RTP. With both the IPv6 Test
Module and the VoIP Test Module, also provides CHR_PROTOCOL_RTP or CHR_PROTOCOL_
RTP6.
Note that if you change a pair&#39;s protocol to an IPv6 protocol, you must also clear any
QoS settings before you try to add this pair to a test; otherwise, you&#39;ll get CHR_
OBJECT_INVALID.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

- 183 -

IxChariot APIGuide

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 184 -

IxChariot APIGuide

CHR_app_group_set_pair_protocol
DESCRIPTION
The CHR_app_group_set_pair_protocol function sets or changes the Endpoint 1 to Endpoint
2 network protocol for the given endpoint in the application group.
C H R _API_R C
C H R _ app_ group_ s et _pai r_prot oc ol (
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _C OU N T pairI ndex ,
C H R _PR OTOC OL prot oc ol
)
As of IxChariot 6.70, this function has been deprecated. The function is still available, but the recommend procedure is to get the handle of the pair and use the
pair API functions.

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

pairIndex [in]
A handle returned by CHR_app_group_get_pair_count(). The index identifies the specific
pair within the application group.

protocol [in]
Specifies the protocol type: CHR_PROTOCOL_UDP, CHR_PROTOCOL_RTP, CHR_PROTCOL_
TCP, CHR_PROTOCOL_IPX, or CHR_PROTOCOL_SPX.
With the separately licensed IPv6 Test Module, also provides CHR_PROTCOL_TCP6, CHR_
PROTOCOL_UDP6, and CHR_PROTOCOL_RTP6.
With the VoIP Test Module, also provides CHR_PROTOCOL_RTP. With both the IPv6 Test
Module and the VoIP Test Module, also provides CHR_PROTOCOL_RTP or CHR_PROTOCOL_
RTP6.
Note that if you change a pair&#39;s protocol to an IPv6 protocol, you must also clear any
QoS settings before you try to add this pair to a test; otherwise, you&#39;ll get CHR_
OBJECT_INVALID.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:

- 185 -

IxChariot APIGuide

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 186 -

IxChariot APIGuide

CHR_app_group_set_pair_qos_name
DESCRIPTION
The CHR_app_group_set_pair_qos_name function sets or changes the service quality
name for the given endpoint pair within the application group.
C H R _API_R C
C H R _ app_ group_ s et _pai r_qos _ nam e(
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _C OU N T pairI ndex ,
C H R _STR I N G qos N ame,
C H R _LEN GTH qos N ameLengt h
)
As of IxChariot 6.70, this function has been deprecated. The function is still available, but the recommend procedure is to get the handle of the pair and use the
pair API functions.

PARAMETERS
appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

pairIndex [in]
A handle returned by CHR_app_group_get_pair_count(). The index identifies the specific
pair within the application group.

qos [in]
A string containing quality of service name.

len [in]
The length of the quality of service name, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

- 187 -

IxChariot APIGuide

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 188 -

IxChariot APIGuide

CHR_app_group_validate
DESCRIPTION
The CHR_app_group_validate function verifies the validity of the designated application
group.
C H R _API_R C
C H R _app_group_v alidat e(
C H R _APP_GR OU P_H AN D LE
)

appGroupH andle,

Refer to the IxChariot Script Development and Editing Guide for a the requirements for
valid application groups.

PARAMETERS
appGroupHandle [in]
A handle for the target application group object, returned by CHR_app_group_new(), CHR_
test_get_app_group_by_name(), or CHR_test_get_app_group_by_index().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_APP_GROUP_INVALID

See Return Code Summary for a detailed description of each return code.

- 189 -

IxChariot APIGuide

Common Error Functions

Extended error information is available for some function errors after a test has been run.
The Chariot API includes a function to get this information at various levels of detail. Extended error information about test run errors is only available for test objects, for pair
objects contained by a test, for application group objects contained by a test, and for multicast pair objects in a multicast group contained by a test. This information is only meaningful when a test object, pair object, application group, or multicast group object function
call returns CHR_OPERATION_FAILED, CHR_OBJECT_INVALID, or CHR_APP_GROUP_
INVALID. CHR_NO_SUCH_VALUE is returned by this function if there is no extended error
information available for the function error or test run.
A Chariot message number is available for function errors and test run errors that have
extended error information. The Chariot API also offers a common error function to get
this message number for test objects, pair objects, multicast pair objects, and multicast
group objects. The code CHR_NO_SUCH_VALUE is returned if there is no Chariot message
number available for the error.
When logging the error information reported by these functions, use CHR_DETAIL_LEVEL_
ALL to give the maximum possible information about the error. Information at this level of
detail is needed to receive assistance with error diagnosis from Ixia. You should log all
errors, not just those with extended information, so that you can later debug your programs that use the IxChariot API.

- 190 -

IxChariot APIGuide

CHR_common_error_get_info
DESCRIPTION
The CHR_common_error_get_info function retrieves the extended error information for
function calls and test run errors.
The extended error information is only meaningful after function call errors for tests,
pairs, multicast pairs, and multicast groups when the error is CHR_OPERATION_FAILED,
CHR_OBJECT_INVALID, or CHR_APP_GROUP_INVALID.
Extended error information about test run errors is available for tests, for pairs contained
by a test, and for multicast pairs owned by a multicast group contained by a test. See Error
Detail Levels for more information.
The extended error information for function errors is not retained and is cleared each time
a function is called for pairs, multicast pairs, and multicast groups until the object or its
container is owned by a test. The extended error information for test run errors for pairs
and multicast pairs is retained and stored with the test when it is saved. For test objects,
the extended error information from a function or test run error is cleared when the next
function is called for the object, unless the function call fails with one of the following
return codes:
l

CHR_POINTER_INVALID

CHR_STRING_TOO_LONG

CHR_VALUE_INVALID.

These return codes indicate that error information may not have been cleared.
C H R _API_R C
C H R _c om m on_error_get _i nf o(
C H R _H AN D LE handle,
C H R _D ETAI L_LEVEL det ail,
C H R _S T R I N G ex t ended_i nf o,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
handle [in]
l
l

For a test, the handle returned by CHR_test_new.

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair
().
For a multicast group, the handle returned by CHR_mgroup_new() or CHR_test_get_
mgroup().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().

- 191 -

IxChariot APIGuide

detail[in]
The detail level for extended error information. Refer to Error Detail Levels for available
levels.

extended_info [out]
A pointer to the buffer where the extended error information should be returned. If the buffer is valid but not large enough, truncated extended error information is returned.

len [in]
The length of the given buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_SUCH_VALUE*

CHR_POINTER_INVALID

CHR_VALUE_INVALID

CHR_TEST_RUNNING
This return code means that there is no extended error information available
and does not indicate an error.

See Return Code Summary for a detailed description of each return code.

- 192 -

IxChariot APIGuide

CHR_common_error_get_msg_num
DESCRIPTION
The CHR_common_error_get_msg_num function gets the IxChariot error message that
applies to the extended error information for a function or test run error.
C H R _API_R C
C H R _c om m on_error_get _m s g_num (
C H R _H AN D LE handle,
C H R _MESSAGE_N U MBER * ms gnum
)

PARAMETERS
handle [in]
l
l

For a test, the handle returned by CHR_test_new().

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair
().
For a multicast group, the handle returned by CHR_mgroup_new() or CHR_test_get_
mgroup().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().

msgnum [out]
A pointer to the variable where the message number should be returned. See the Message
Reference for more information on messages.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_NO_SUCH_VALUE*

CHR_TEST_RUNNING
This return code means that there is no extended error information available
and does not indicate an error.

See Return Code Summary for a detailed description of each return code.

- 193 -

IxChariot APIGuide

Common Results Extraction Functions

Common Results Extraction functions are used to obtain test results that are common to
endpoint pairs, multicast pairs, and timing records for either pair type (that is, normal pair
or multicast pair).

- 194 -

IxChariot APIGuide

CHR_common_results_get_bytes_recv_e1
DESCRIPTION
The CHR_common_results_get_bytes_recv_e1 function gets the number of bytes received
by Endpoint 1 from the test results in the given endpoint pair or timing record. This value
does not apply for pairs defined with a streaming script.
C H R _API_R C
C H R _c om m on_res ul t s _get _by t es _rec v _ e1(
C H R _H AN D LE handle,
C H R _FLOAT* by t es
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

bytes[out]
A pointer to the variable where the number of bytes received should be returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 195 -

IxChariot APIGuide

CHR_common_results_get_bytes_recv_e2
DESCRIPTION
The CHR_common_results_get_bytes_recv_e2 function gets the number of bytes received
by Endpoint 2 from the test results in the given endpoint pair, multicast pair, or timing
record. This value only applies to pairs defined with a streaming script since the received
value may not be the same as the bytes_sent_e1 value.
C H R _API_R C
C H R _c om m on_res ul t s _get _by t es _rec v _ e2(
C H R _H AN D LE handle,
C H R _FLOAT* by t es
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().
For a timing record, the handle returned by CHR_pair_get_timing_record() or CHR_
mpair_get_timing_record().

bytes[out]
A pointer to the variable where the number of bytes received should be returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 196 -

IxChariot APIGuide

CHR_common_results_get_bytes_sent_e1
DESCRIPTION
The CHR_common_results_get_bytes_sent_e1 function gets the number of bytes sent by
Endpoint 1 from the test results in the given endpoint pair, multicast pair, or timing record.
C H R _API_R C
C H R _c om m on_res ul t s _get _by t es _s ent _ e1(
C H R _H AN D LE handle,
C H R _FLOAT* by t es
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().
For a timing record, the handle returned by CHR_pair_get_timing_record() or CHR_
mpair_get_timing_record().

bytes[out]
A pointer to the variable where the number of bytes sent should be returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_NO_SUCH_VALUE

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 197 -

IxChariot APIGuide

CHR_common_results_get_dg_dup_recv_e1
DESCRIPTION
The CHR_common_results_get_dg_dup_recv_e1 function gets the number of duplicate
datagrams received by Endpoint 1 from the test results in the given endpoint pair or timing
record. This value does not apply for pairs defined with a streaming script.
C H R _API_R C
C H R _ c om m on_res ul t s _ get _dg_ dup_rec v _e1(
C H R _H AN D LE handle,
C H R _FLOAT* dg
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

dg [out]
A pointer to the variable where the number of duplicate datagrams received by Endpoint 1
should be returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
n

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 198 -

IxChariot APIGuide

CHR_common_results_get_dg_dup_recv_e2
DESCRIPTION
The CHR_common_results_get_dg_dup_recv_e2 function gets the number of duplicate
datagrams received by Endpoint 2 from the test results in the given endpoint pair, multicast pair, or timing record.
C H R _API_R C
C H R _ c om m on_res ul t s _ get _dg_ dup_rec v _e2(
C H R _H AN D LE handle,
C H R _FLOAT* dg
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().
For a timing record, the handle returned by CHR_pair_get_timing_record() or CHR_
mpair_get_timing_record().

dg [out]
A pointer to the variable where the number of duplicate datagrams received should be
returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_NO_SUCH_VALUE

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 199 -

IxChariot APIGuide

CHR_common_results_get_dg_dup_sent_e1
DESCRIPTION
The CHR_common_results_get_dg_dup_sent_e1 function gets the total number of duplicate datagrams sent by Endpoint 1 from the test results in the given endpoint pair or timing
record. This value does not apply for pairs defined with a streaming script.
C H R _API_R C
C H R _ c om m on_res ul t s _ get _dg_ dup_s ent _e1(
C H R _H AN D LE handle,
C H R _FLOAT* dg
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

dg [out]
A pointer to the variable where the number of duplicate datagrams sent should be
returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 200 -

IxChariot APIGuide

CHR_common_results_get_dg_dup_sent_e2
DESCRIPTION
The CHR_common_results_get_dg_dup_sent_e2 function gets the number of duplicate datagrams sent by Endpoint 2 from the test results in the given endpoint pair or timing record.
This value does not apply for pairs defined with a streaming script.
C H R _API_R C
C H R _ c om m on_res ul t s _ get _dg_ dup_s ent _e2(
C H R _H AN D LE handle,
C H R _FLOAT* dg
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

dg [out]
A pointer to the variable where the number of duplicate datagrams should be returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 201 -

IxChariot APIGuide

CHR_common_results_get_dg_lost_e1_to_e2
DESCRIPTION
The CHR_common_results_get_dg_lost e1_to_e2 function gets the total number of datagrams lost between Endpoint 1 and Endpoint 2 from the test results in the given endpoint
pair, multicast pair, or timing record.
C H R _API_R C
C H R _ c om m on_res ul t s _ get _ dg_ l os t _e1_ t o_e2(
C H R _H AN D LE handle,
C H R _FLOAT* dg
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().
For a timing record, the handle returned by CHR_pair_get_timing_record() or CHR_
mpair_get_timing_record().

dg [out]
A pointer to the variable where the number of datagrams lost should be returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_NO_SUCH_VALUE

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 202 -

IxChariot APIGuide

CHR_common_results_get_dg_out_of_order
DESCRIPTION
The CHR_common_results_get_dg_out_of_order function gets the number of datagrams
received out of order by Endpoint 2 from the test results in the given endpoint pair, multicast pair, or timing record. This value only applies to pairs defined with a streaming
script.
C H R _API_R C
C H R _ c om m on_res ul t s _ get _ dg_ out _ of _order (
C H R _H AN D LE handle,
C H R _FLOAT* dg
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().
For a timing record, the handle returned by CHR_pair_get_timing_record() or CHR_
mpair_get_timing_record().

dg [out]
A pointer to the variable where the number of datagrams received out of order is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_NO_SUCH_VALUE

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 203 -

IxChariot APIGuide

CHR_common_results_get_dg_recv_e1
DESCRIPTION
The CHR_common_results_get_dg_recv_e1 function gets the number of datagrams
received by Endpoint 1 from the test results in the given endpoint pair or timing record.
This value does not include duplicate datagrams.
C H R _API_R C
C H R _ c om m on_res ul t s _ get _dg_ rec v _e1(
C H R _H AN D LE handle,
C H R _FLOAT* dg
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

dg [out]
A pointer to the variable where the number of datagrams sent is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 204 -

IxChariot APIGuide

CHR_common_results_get_dg_recv_e2
DESCRIPTION
The CHR_common_results_get_dg_recv_e2 function gets the number of datagrams
received by Endpoint 2 from the test results in the given endpoint pair, multicast pair, or
timing record. This value does not include duplicate datagrams.
C H R _API_R C
C H R _ c om m on_res ul t s _ get _ dg_ l os t _e2_ t o_e1(
C H R _H AN D LE handle,
C H R _FLOAT* dg
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().
For a timing record, the handle returned by CHR_pair_get_timing_record() or CHR_
mpair_get_timing_record().

dg [out]
A pointer to the variable where the number of datagrams received by Endpoint 2 is
returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 205 -

IxChariot APIGuide

CHR_common_results_get_dg_sent_e1
DESCRIPTION
The CHR_common_results_get_dg_sent_e1 function gets the number of datagrams sent by
Endpoint 1 from the test results in the given endpoint pair, multicast pair, or timing record.
This value does not include retransmitted datagrams.
C H R _API_R C
C H R _ c om m on_res ul t s _ get _dg_ s ent _e1(
C H R _H AN D LE handle,
C H R _FLOAT* dg
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().
For a timing record, the handle returned by CHR_pair_get_timing_record() or CHR_
mpair_get_timing_record().

dg [out]
A pointer to the variable where the number of datagrams sent.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_NO_SUCH_VALUE

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 206 -

IxChariot APIGuide

CHR_common_results_get_e1_ack_to_fin_rx
DESCRIPTION
The CHR_common_results_get_e1_ack_to_fin_rx function retrieves from the test results in
the given endpoint pair or timing record the number of TCP ACK packets received by Endpoint 1 from Endpoint2 in response to a FIN packet sent by Endpoint1.
C H R _API_R C
C H R _ c om m on_res ul t s _ get _ e1_ ac k _ t o_f i n_ rx (
C H R _H AN D LE_H AN D LE handle,
C H R _LON G* f in_ac k _rx
)
Note that this value is not applicable for pairs that are not running the TCP protocol.

PARAMETERS
handle [in]
One of the following:
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

fin_ack_rx [out]
A pointer to the variable to which the function returns the number of ACK packets received
by Endpoint 1 from Endpoint2 in response to a FIN packet sent by Endpoint1.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 207 -

IxChariot APIGuide

CHR_common_results_get_e1_ack_to_fin_tx
DESCRIPTION
The CHR_common_results_get_e1_ack_to_fin_tx function retrieves from the test results in
the given endpoint pair or timing record the number of TCP ACK packets transmitted by
Endpoint 1 in response to a FIN sent by Endpoint2.
C H R _API_R C
C H R _ c om m on_res ul t s _ get _ e1_ ac k _ t o_f i n_ t x (
C H R _H AN D LE_H AN D LE handle,
C H R _LON G* f in_ac k _t x
)
Note that this value is not applicable for pairs that are not running the TCP protocol.

PARAMETERS
handle [in]
One of the following:
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

fin_ack_tx [out]
A pointer to the variable to which the function returns the number of ACK packets transmitted by Endpoint 1 in response to a FIN sent by Endpoint2.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 208 -

IxChariot APIGuide

CHR_common_results_get_e1_conn_established
DESCRIPTION
The CHR_common_results_get_e1_conn_established function retrieves from the test results in the given endpoint pair or timing record a count of the number of TCP connections
successfully established by Endpoint 1.
C H R _API_R C
C H R _ c om m on_res ul t s _ get _e1_ c onn_es t abl i s hed (
C H R _H AN D LE_H AN D LE handle,
C H R _LON G* c onn_es t ablis hed
)

PARAMETERS
handle [in]
One of the following:
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

conn_established [out]
A pointer to the variable to which the function returns the count of TCP connections successfully established by Endpoint 1.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 209 -

IxChariot APIGuide

CHR_common_results_get_e1_fin_rx
DESCRIPTION
The CHR_common_results_get_e1_fin_rx function retrieves from the test results in the
given endpoint pair or timing record the number of TCP FIN packets received by Endpoint
1.
C H R _API_R C
C H R _c om m on_res ul t s _get _e1_ f i n_rx (
C H R _H AN D LE_H AN D LE handle,
C H R _LON G* f in_rx
)
Note that this value is not applicable for pairs that are not running the TCP protocol.

PARAMETERS
handle [in]
One of the following:
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

fin_rx [out]
A pointer to the variable to which the function returns the number of FINs received by Endpoint 1.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 210 -

IxChariot APIGuide

CHR_common_results_get_e1_fin_tx
DESCRIPTION
The CHR_common_results_get_e1_fin_tx function retrieves from the test results in the
given endpoint pair or timing record the number of TCP FIN packets transmitted by Endpoint 1.
C H R _API_R C
C H R _c om m on_res ul t s _get _e1_ f i n_t x (
C H R _H AN D LE_H AN D LE handle,
C H R _LON G* f in_t x
)
Note that this value is not applicable for pairs that are not running the TCP protocol.

PARAMETERS
handle [in]
One of the following:
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

fin_tx [out]
A pointer to the variable to which the function returns the number of FINs transmitted by
Endpoint 1.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 211 -

IxChariot APIGuide

CHR_common_results_get_e1_rst_rx
DESCRIPTION
The CHR_common_results_get_e1_rst_rx function retrieves from the test results in the
given endpoint pair or timing record the number of TCP RST (Reset) packets received by
Endpoint 1.
C H R _API_R C
C H R _c om m on_res ul t s _get _e1_ rs t _rx (
C H R _H AN D LE_H AN D LE handle,
C H R _LON G* rs t _rx
)
Note that this value is not applicable for pairs that are not running the TCP protocol.

PARAMETERS
handle [in]
One of the following:
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

rst_rx [out]
A pointer to the variable to which the function returns the number of TCP RST (Reset) packets received by Endpoint 1.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 212 -

IxChariot APIGuide

CHR_common_results_get_e1_rst_tx
DESCRIPTION
The CHR_common_results_get_e1_rst_tx function retrieves from the test results in the
given endpoint pair or timing record the number of TCP RST (Reset) packets transmitted
by Endpoint 1.
C H R _API_R C
C H R _c om m on_res ul t s _get _e1_ rs t _t x (
C H R _H AN D LE_H AN D LE handle,
C H R _LON G* rs t _t x
)
Note that this value is not applicable for pairs that are not running the TCP protocol.

PARAMETERS
handle [in]
One of the following:
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

rst_tx [out]
A pointer to the variable to which the function returns the number of TCP RST (Reset) packets transmitted by Endpoint 1.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 213 -

IxChariot APIGuide

CHR_common_results_get_e1_syn_failed
DESCRIPTION
The CHR_common_results_get_e1_syn_failed function retrieves from the test results in
the given endpoint pair or timing record a count of the number of TCP connection attempts
for which Endpoint 1 reset the connection before synchronization was established.
C H R _API_R C
C H R _c om m on_res ul t s _get _e1_ s y n_f ai l ed(
C H R _H AN D LE_H AN D LE handle,
C H R _LON G* s y n_f ailed
)

PARAMETERS
handle [in]
One of the following:
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

syn_failed [out]
A pointer to the variable to which the function returns the count of TCP connection attempts
for which Endpoint 1 reset the connection before synchronization was established.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 214 -

IxChariot APIGuide

CHR_common_results_get_e1_syn_rx
DESCRIPTION
The CHR_common_results_get_e1_syn_rx function retrieves from the test results in the
given endpoint pair or timing record the number of TCP SYN packets received by Endpoint
1.
C H R _API_R C
C H R _c om m on_res ul t s _get _e1_ s y n_rx (
C H R _H AN D LE_H AN D LE handle,
C H R _LON G* s y n_rx
)
Note that this value is not applicable for pairs that are not running the TCP protocol.

PARAMETERS
handle [in]
One of the following:
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

syn_rx [out]
A pointer to the variable to which the function returns the number of SYNs received by
Endpoint1.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 215 -

IxChariot APIGuide

CHR_common_results_get_e1_syn_tx
DESCRIPTION
The CHR_common_results_get_e1_syn_tx function retrieves from the test results in the
given endpoint pair or timing record the number of TCP SYN packets transmitted by Endpoint 1.
C H R _API_R C
C H R _c om m on_res ul t s _get _e1_ s y n_t x (
C H R _H AN D LE_H AN D LE handle,
C H R _LON G* s y n_t x
)
Note that this value is not applicable for pairs that are not running the TCP protocol.

PARAMETERS
handle [in]
One of the following:
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

syn_tx [out]
A pointer to the variable to which the function returns the number of SYNs transmitted by
Endpoint1.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 216 -

IxChariot APIGuide

CHR_common_results_get_e1_tcp_retransmissions
DESCRIPTION
The CHR_common_results_get_e1_tcp_retransmissions function retrieves from the test
results in the given endpoint pair or timing record a count of the number of packets retransmitted by Endpoint 1.
C H R _API_R C
C H R _c om m on_res ul t s _get _e1_ t c p_ret rans m i s s i ons (
C H R _H AN D LE_H AN D LE handle,
C H R _LON G* t c p_ret rans mis s ions
)

PARAMETERS
handle [in]
One of the following:
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

tcp_retransmissions [out]
A pointer to the variable to which the function returns the count of packets retransmitted
by Endpoint 1.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 217 -

IxChariot APIGuide

CHR_common_results_get_e1_tcp_timeouts
DESCRIPTION
The CHR_common_results_get_e1_tcp_timeouts function retrieves from the test results in
the given endpoint pair or timing record a count of the number of TCP connection timeouts
that occurred on Endpoint 1.
C H R _API_R C
C H R _c om m on_res ul t s _get _e1_ t c p_t i m eout s (
C H R _H AN D LE_H AN D LE handle,
C H R _LON G* t c p_t imeout s
)

PARAMETERS
handle [in]
One of the following:
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a timing record, the handle returned by CHR_pair_get_timing_record().

tcp_timeouts [out]
A pointer to the variable to which the function returns the count of the number of TCP
timeouts that occurred on Endpoint 1

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 218 -

IxChariot APIGuide

CHR_common_results_get_est_clock_error
DESCRIPTION
The CHR_common_results_get_est_clock_error function gets the maximum error in clock
synchronization between the endpoints.
C H R _API_R C
C H R _c om m on_res ul t s _get _es t _c l oc k _error (
C H R _H AN D LE handle,
C H R _FLOAT* es t _c loc k _error
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().
For a timing record, the handle returned by CHR_pair_get_timing_record() or CHR_
mpair_get_timing_record().

est_clock_error [out]
A pointer to the variable where the estimated clock error is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 219 -

IxChariot APIGuide

CHR_common_results_get_jitter_buffer_lost
DESCRIPTION
The CHR_common_results_get_jitter_buffer_lost function gets the number of datagrams
that were lost due to the jitter buffer. This value is only available for VoIP pairs and timing
records associated with a VoIP pair.
C H R _API_R C
C H R _c om m on_res ul t s _ get _j i t t er_ buf f er_l os t (
C H R _H AN D LE handle,
C H R _C OU N T* res ult
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_voip_pair_new() or CHR_test_get_

pair().
For a timing record, the handle returned by CHR_pair_get_timing_record().

result [out]
A pointer to the variable where the number of jitter buffer lost datagrams is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 220 -

IxChariot APIGuide

CHR_common_results_get_max_clock_error
DESCRIPTION
The CHR_common_results_get_max_clock_error function gets the maximum error in clock
synchronization between the endpoints.
C H R _API_R C
C H R _c om m on_res ul t s _get _m ax _c l oc k _error (
C H R _H AN D LE handle,
C H R _FLOAT* max _c loc k _error
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().

max_clock_error [out]
A pointer to the variable where the maximum clock error is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 221 -

IxChariot APIGuide

CHR_common_results_get_meas_time
DESCRIPTION
The CHR_common_results_get_meas_time function gets the measured time in seconds
from the test results in the given endpoint pair, multicast pair, or timing record.
C H R _API_R C
C H R _c om m on_res ul t s _get _m eas _ t i m e(
C H R _H AN D LE handle,
C H R _FLOAT* meas t ime
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().
For a timing record, the handle returned by CHR_pair_get_timing_record() or CHR_
mpair_get_timing_record().

meastime [out]
A pointer to the variable where the measured time is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 222 -

IxChariot APIGuide

CHR_common_results_get_rtd
DESCRIPTION
The CHR_common_results_get_rtd function gets the round-trip delay for a voice over IP
(VoIP) pair.
C H R _API_R C
C H R _c om m on_res ul t s _get _rt d (
C H R _H AN D LE handle,
C H R _FLOAT* rt d
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().

rtd [out]
A pointer to the variable where the round-trip delay time is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary on page A-1 for a detailed description of each return code.

- 223 -

IxChariot APIGuide

CHR_common_results_get_rtd_95pct_confidence
DESCRIPTION
The CHR_common_results_get_rtd_95pct_confidence function gets the 95% confidence
interval for the round-trip delay time.
C H R _API_R C
C H R _c om m on_res ul t s _get _rt d_95pc t _c onf i denc e(
C H R _H AN D LE handle,
C H R _FLOAT* c onf idenc e
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().
For a timing record, the handle returned by CHR_pair_get_timing_record() or CHR_
mpair_get_timing_record().

confidence [out]
A pointer to the variable where the 95% confidence interval is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 224 -

IxChariot APIGuide

CHR_common_results_get_trans_count
DESCRIPTION
The CHR_common_results_get_trans_count function gets the transaction count from the
test results in the given endpoint pair, multicast pair, or timing record.
C H R _API_R C
C H R _c om m on_res ul t s _get _t rans _c ount (
C H R _H AN D LE handle,
C H R _FLOAT* c ount
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().
For a timing record, the handle returned by CHR_pair_get_timing_record() or CHR_
mpair_get_timing_record().

count[out]
A pointer to the variable where the transaction count is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 225 -

IxChariot APIGuide

Datagram Options Object Functions

Datagram options object functions are used to define and retrieve the datagram options
for the test that owns them. You cannot set datagram options for a test that has results or
while a test is running.

- 226 -

IxChariot APIGuide

CHR_dgopts_get_data_rate_limit
DESCRIPTION
The CHR_dgopts_get_data_rate_limit function gets the datagram data rate limit that has
been set for all the streaming pairs in the test. The data rate limit is expressed as a percent of the required data rate defined in the script. For example, a value of 100 means that
the limit is equal to 100% of the required data rate.
C H R _API_R C
C H R _ dgopt s _get _dat a_ rat e_l i m i t (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T* dat aR at eLimit
)

PARAMETERS
datagramOptionsHandle [in]
The handle returned by CHR_test_get_dgopts().

dataRateLimit [out]
A pointer to the variable where the datagram data rate limit is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 227 -

IxChariot APIGuide

CHR_dgopts_get_limit_data_rate
DESCRIPTION
The CHR_dgopts_get_limit_data_rate function gets the value of the datagram data rate
limit flag that has been set for all the streaming pairs in the test. This flag is used to enable
a data rate (throughput) limit measured on intervals much smaller than a timing record
interval.
C H R _API_R C
C H R _dgopt s _get _l i m i t _dat a_ rat e (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _BOOLEAN * f lag
)

PARAMETERS
datagramOptionsHandle [in]
The handle returned by CHR_test_get_dgopts().

flag [out]
A pointer to the Boolean variable where the value of the datagram data rate limit flag is
returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 228 -

IxChariot APIGuide

CHR_dgopts_get_low_sender_jitter
DESCRIPTION
The CHR_dgopts_get_low_sender_jitter function gets the value of the datagram low sender
jitter flag that has been set for all the streaming pairs in the test. This flag is used to
enable very precise timers to reduce the jitter on the sender. When the flag is enabled,
datagrams are sent at more precise intervals.
C H R _API_R C
C H R _dgopt s _get _l ow _s ender_ j i t t er (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _BOOLEAN * f lag
)

PARAMETERS
datagramOptionsHandle [in]
The handle returned by CHR_test_get_dgopts().

flag [out]
A pointer to the Boolean variable where the value of the datagram low sender jitter flag is
returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 229 -

IxChariot APIGuide

CHR_dgopts_get_measured_interval
DESCRIPTION
The CHR_dgopts_get_measured_interval function gets the datagram measured interval
that has been set for all the streaming pairs in the test. The measured interval is the interval (in milliseconds) over which IxChariot enforces the data rate limit.
C H R _API_R C
C H R _dgopt s _get _m eas ured_ i nt erv al (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T* meas uredI nt erv al
)

PARAMETERS
datagramOptionsHandle [in]
The handle returned by CHR_test_get_dgopts().

measuredInterval[out]
A pointer to the variable where the datagram measured interval is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 230 -

IxChariot APIGuide

CHR_dgopts_get_recv_timeout
DESCRIPTION
The CHR_dgopts_get_recv_timeout function gets the multicast datagram receive timeout
in milliseconds.
C H R _API_R C
C H R _dgopt s _get _rec v _ t i m eout (
C H R _D GOPTS_H AN D LE dgopt s ,
C H R _C OU N T* t imeout
)

PARAMETERS
dgopts[in]
The handle returned by CHR_test_get_dgopts().

timeout [out]
A pointer to the variable where the datagram receive timeout is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 231 -

IxChariot APIGuide

CHR_dgopts_get_retrans_count
DESCRIPTION
The CHR_dgopts_get_retrans_count function gets the datagram retransmission count.
C H R _API_R C
C H R _dgopt s _get _ret rans _ c ount (
C H R _D GOPTS_H AN D LE dgopt s ,
C H R _C OU N T* c ount
)

PARAMETERS
dgopts[in]
The handle returned by CHR_test_get_dgopts().

count[out]
A pointer to the variable where the datagram retransmission count is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 232 -

IxChariot APIGuide

CHR_dgopts_get_retrans_timeout
DESCRIPTION
The CHR_dgopts_get_retrans_timeout function gets the datagram retransmission timeout
in milliseconds.
C H R _API_R C
C H R _dgopt s _get _ret rans _ t i m eout (
C H R _D GOPTS_H AN D LE dgopt s ,
C H R _C OU N T* t imeout
)Paramet ers

PARAMETERS
dgopts[in]
The handle returned by CHR_test_get_dgopts().

timeout [out]
A pointer to the variable where the datagram retransmission timeout is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 233 -

IxChariot APIGuide

CHR_dgopts_get_RTP_use_extended_headers
DESCRIPTION
The CHR_dgopts_get_RTP_use_extended_headers function gets the useextension
header setting defined for RTP traffic.
C H R _API_R C
C H R _dgopt s _get _R T P _us e_ex t ended_ headers (
C H R _D GOPTS_H AN D LE dat agramOpt ions H andle,
C H R _BOOLEAN * f lag
)

PARAMETERS
datagramOptionsHandle [in]
The handle returned by CHR_test_get_dgopts().

flag [out]
A pointer to the variable where the useextension header Boolean value is returned. The
variable can take either of the following values:
l

CHR_TRUEThe RTP datagram includes an extension header. In this case, the RTP
timestamp field contains a monotonous timestamp value, while the header extension
contains a time value derived from the system clock.
CHR_FALSEThe RTP datagram does not include an extension header. In this case, the
RTP timestamp field contains a time value derived from the system clock.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 234 -

IxChariot APIGuide

CHR_dgopts_get_TTL
DESCRIPTION
The CHR_dgopts_get_TTL function gets the multicast datagram time to live hop count.
C H R _API_R C
C H R _dgopt s _get _T T L (
C H R _D GOPTS_H AN D LE dgopt s ,
C H R _C OU N T* t t l
)

PARAMETERS
dgopts[in]
The handle returned by CHR_test_get_dgopts().

ttl [out]
A pointer to the variable where the time to live is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 235 -

IxChariot APIGuide

CHR_dgopts_get_window_size
DESCRIPTION
The CHR_dgopts_get_window_size function gets the datagram window size in bytes.
C H R _API_R C
C H R _dgopt s _get _w i ndow _ s i z e(
C H R _D GOPTS_H AN D LE dgopt s ,
C H R _C OU N T* s iz e
)

PARAMETERS
dgopts[in]
The handle returned by CHR_test_get_dgopts().

size [out]
A pointer to the variable where the datagram window size is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 236 -

IxChariot APIGuide

CHR_dgopts_set_data_rate_limit
DESCRIPTION
The CHR_dgopts_set_data_rate_limit function sets the datagram data rate limit for all the
streaming pairs in the test.
C H R _API_R C
C H R _ dgopt s _s et _dat a_ rat e_l i m i t (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T dat aR at eLimit
)
This API is only applicable for streaming pairs.
This API is only applicable for the following Performance Endpoints: Windows 32bit, Windows 64-bit, and Linux On PowerPC.
This API requires that Endpoint 1 (the sender) is running a Performance Endpoint
software release of 6.70 or higher.

PARAMETERS
datagramOptionsHandle [in]
The handle returned by CHR_test_get_dgopts().

dataRateLimit [in]
The datagram data rate limit. The data rate limit is expressed as a percent of the required
data rate defined in the script. For example, a value of 100 means that the limit is equal to
100% of the required data rate. The valid range of values is from 100 through 200.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 237 -

IxChariot APIGuide

CHR_dgopts_set_limit_data_rate
DESCRIPTION
The CHR_dgopts_set_limit_data_rate function sets the datagram data rate limit flag for all
the streaming pairs in the test. This flag is used to enable a data rate (throughput) limit
measured on intervals much smaller than a timing record interval.
C H R _API_R C
C H R _dgopt s _s et _l i m i t _dat a_ rat e (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _BOOLEAN f lag
)
This API is only applicable for streaming pairs.
This API is only applicable for the following Performance Endpoints: Windows 32bit, Windows 64-bit, and Linux On PowerPC.
This API requires that Endpoint 1 (the sender) is running a Performance Endpoint
software release of 6.70 or higher.

PARAMETERS
datagramOptionsHandle [in]
The handle returned by CHR_test_get_dgopts().

flag [in]
The value of the datagram data rate limit flag:
l

CHR_TRUEEnable the datagram data rate limit.

CHR_FALSEDisable the datagram data rate limit.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 238 -

IxChariot APIGuide

CHR_dgopts_set_low_sender_jitter
DESCRIPTION
The CHR_dgopts_set_low_sender_jitter function sets the datagram low sender jitter flag
for all the streaming pairs in the test. This flag is used to enable very precise timers to
reduce the jitter on the sender. When the flag is enabled, datagrams are sent at more precise intervals.
C H R _API_R C
C H R _dgopt s _s et _l ow _s ender_ j i t t er (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _BOOLEAN f lag
)
This API is only applicable for streaming pairs.
This API is only applicable for the following Performance Endpoints: Windows 32bit, Windows 64-bit, and Linux On PowerPC.
This API requires that Endpoint 1 (the sender) is running a Performance Endpoint
software release of 6.70 or higher.

PARAMETERS
datagramOptionsHandle [in]
The handle returned by CHR_test_get_dgopts().

flag [in]
The value of the datagram low sender jitter flag:
l

CHR_TRUEEnable low sender jitter for all the streaming pairs in the test.

CHR_FALSEDisable low sender jitter.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 239 -

IxChariot APIGuide

- 240 -

IxChariot APIGuide

CHR_dgopts_set_measured_interval
DESCRIPTION
The CHR_dgopts_set_measured_interval function sets the datagram measured interval for
all the streaming pairs in the test.
C H R _API_R C
C H R _dgopt s _s et _m eas ured_ i nt erv al (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T meas uredI nt erv al
)
This API is only applicable for streaming pairs.
This API is only applicable for the following Performance Endpoints: Windows 32bit, Windows 64-bit, and Linux On PowerPC.
This API requires that Endpoint 1 (the sender) is running a Performance Endpoint
software release of 6.70 or higher.

PARAMETERS
datagramOptionsHandle [in]
The handle returned by CHR_test_get_dgopts().

measuredInterval[in]
The datagram measured interval. This is the interval (in milliseconds) over which
IxChariot enforces the data rate limit. The valid range of values is from 1 through 999,999.
You will typically set this value to match the interval over which network devices check for
throughput spikes.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 241 -

IxChariot APIGuide

CHR_dgopts_set_recv_timeout
DESCRIPTION
The CHR_dgopts_set_recv_timeout function sets or changes the multicast datagram
receive timeout in milliseconds.
C H R _API_R C
C H R _dgopt s _s et _rec v _ t i m eout (
C H R _D GOPTS_H AN D LE dgopt s ,
C H R _C OU N T t imeout
)

PARAMETERS
dgopts[in]
The handle returned by CHR_test_get_dgopts().

timeout [in]
The time in milliseconds. The range of valid values is 1 to 999,999.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 242 -

IxChariot APIGuide

CHR_dgopts_set_retrans_count
DESCRIPTION
The CHR_dgopts_set_retrans_count function sets or changes the datagram retransmission
count.
C H R _API_R C
C H R _dgopt s _s et _ret rans _ c ount (
C H R _D GOPTS_H AN D LE dgopt s ,
C H R _C OU N T c ount
)

PARAMETERS
dgopts[in]
The handle returned by CHR_test_get_dgopts().

count[in]
The number of retransmissions before aborting. The range of valid values is 1 to 999.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 243 -

IxChariot APIGuide

CHR_dgopts_set_retrans_timeout
DESCRIPTION
The CHR_dgopts_set_retrans_timeout function sets or changes datagram retransmission
timeout in milliseconds.
C H R _API_R C
C H R _dgopt s _s et _ret rans _ t i m eout (
C H R _D GOPTS_H AN D LE dgopt s ,
C H R _C OU N T t imeout
)

PARAMETERS
dgopts[in]
The handle returned by CHR_test_get_dgopts().

timeout [in]
Retransmission timeout in milliseconds. The range of valid values is 1 to 99999.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 244 -

IxChariot APIGuide

CHR_dgopts_set_RTP_use_extended_headers
DESCRIPTION
The CHR_dgopts_set_RTP_use_extended_headers function sets the useextension
header option for RTP traffic.
C H R _API_R C
C H R _dgopt s _s et _R T P _us e_ex t ended_ headers (
C H R _D GOPTS_H AN D LE dat agramOpt ions H andle,
C H R _BOOLEAN * f lag
)

PARAMETERS
datagramOptionsHandle [in]
The handle returned by CHR_test_get_dgopts().

flag [in]
A Boolean variable that sets the useextension header option. The variable can take either
of the following values:
l

CHR_TRUEThe RTP datagram will use an extension header. In this case, the RTP
timestamp field contains a monotonous timestamp value, while the header extension
contains a time value derived from the system clock.
CHR_FALSEThe RTP datagram will not use an extension header. In this case, the RTP
timestamp field contains a time value derived from the system clock.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 245 -

IxChariot APIGuide

CHR_dgopts_set_TTL
DESCRIPTION
The CHR_dgopts_set_TTL function sets or changes the multicast datagram time to live hop
count.
C H R _API_R C
C H R _dgopt s _s et _T T L (
C H R _D GOPTS_H AN D LE dgopt s ,
C H R _C OU N T t t l
)

PARAMETERS
dgopts[in]
The handle returned by CHR_test_get_dgopts().

ttl [in]
The time to live hop count. The range of valid values is 0 to 255.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 246 -

IxChariot APIGuide

CHR_dgopts_set_window_size
DESCRIPTION
The CHR_dgopts_set_window_size function sets or changes the datagram window size in
bytes.
C H R _API_R C
C H R _dgopt s _s et _w i ndow _ s i z e(
C H R _D GOPTS_H AN D LE dgopt s ,
C H R _C OU N T s iz e
)

PARAMETERS
dgopts[in]
The handle returned by CHR_test_get_dgopts().

size [in]
The datagram window size in bytes. The range of valid values is 1 to 9999999.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 247 -

IxChariot APIGuide

Hop Record Object Functions

Hop record results extraction is part of the API's traceroute functionality. Hop records can
be extracted from a traceroute pair. Hop record extraction gets a series of hop records,
with a hop count. Individual hop records contain the hop number, the average hop latency,
the hop address, and the resolved hop name.

- 248 -

IxChariot APIGuide

CHR_hoprec_get_hop_address
DESCRIPTION
The CHR_hoprec_get_hop_address function gets the address of a particular hop from a
traceroute.
C H R _API_R C
C H R _hoprec _get _hop_addres s (
C H R _H OPR EC _H AN D LE hoprec ,
C H R _STR I N G hop_addres s ,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h
)

PARAMETERS
hoprec[in]
A handle returned by CHR_tracert_pair_get_hop_record.

hop_address [out]
A pointer to the buffer where the address is returned.

maxLength [in]
The length of the buffer, or the maximum number of bytes that can be returned in the buffer, excluding the null terminator.

length [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 249 -

IxChariot APIGuide

CHR_hoprec_get_hop_latency
DESCRIPTION
The CHR_hoprec_get_hop_latency function gets the number of milliseconds it took to reach
the hop from the Endpoint 1 in a traceroute.
C H R _API_R C
C H R _hoprec _get _hop_l at enc y (
C H R _H OPR EC _H AN D LE hoprec ,
C H R _C OU N T* hop_lat enc y
)

PARAMETERS
hoprec[in]
A handle returned by CHR_tracert_pair_get_hop_record.

hop_latency [out]
A pointer to the buffer where the latency value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 250 -

IxChariot APIGuide

CHR_hoprec_get_hop_name
DESCRIPTION
The CHR_hoprec_get_hop_name function gets the resolved name of a hop in a traceroute.
C H R _API_R C
C H R _hoprec _get _hop_nam e(
C H R _H OPR EC _H AN D LE hoprec H andle,
C H R _STR I N G hop_name,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h
)

PARAMETERS
hoprec[in]
A handle returned by CHR_tracert_pair_get_hop_record.

hop_name [out]
A pointer to the buffer where the hop name is returned.

maxLength [in]
The length of the buffer, or the maximum number of bytes that can be returned in the buffer, excluding the null terminator.

length [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 251 -

IxChariot APIGuide

CHR_hoprec_get_hop_number
DESCRIPTION
The CHR_hoprec_get_hop_number function gets the number of hops before a traceroute
was completed. An index of 0 gets the first hop record, while an index of 1 gets the second
hop record, and so on.
C H R _API_R C
C H R _hoprec _get _hop_num ber(
C H R _H OPR EC _H AN D LE hoprec ,
C H R _C OU N T* hop_number
)

PARAMETERS
hoprec[in]
A handle returned by CHR_tracert_pair_get_hop_record.

hop_number [out]
A pointer to the buffer where the hop number is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 252 -

IxChariot APIGuide

IPTV Channel Object Functions

The IPTV channel object functions are used to define and retrieve information for IPTV
channels. A channel object must be contained by a test object. The testing parameters
available for a channel object include the channel name, test network parameters, management network parameters, and IPTV traffic characteristics.
A related set of functions is provided for IPTV receiver objects and IPTV VPair objects.

- 253 -

IxChariot APIGuide

CHR_channel_delete
DESCRIPTION
The CHR_channel_delete function deletes the specified IPTV channel object.
C H R _API_R C
C H R _c hannel_delet e(
C H R _C H AN N EL_H AN D LE
)

i_c hannelH andle

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 254 -

IxChariot APIGuide

CHR_channel_get_bitrate
DESCRIPTION
The CHR_channel_get_bitrate function gets the bit rate value and unit of measurement
defined for the given IPTV channel object.
C H R _API_R C
C H R _ c h a n n e l _ g e t _ b i t ra t e(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _FLOAT*
o_bit rat e,
C H R _T H R OU GH P U T _U N I T S * o_uni t s
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_bitrate [out]
A pointer to the variable where the transmission bit rate value is returned.

o_units [out]
A pointer to the variable where the unit of measurement is returned. (This is the unit of
measurement in which the transmission rate is expressed.)

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 255 -

IxChariot APIGuide

CHR_channel_get_codec
DESCRIPTION
The CHR_channel_get_codec function returns the codec type defined for the specified
IPTV channel object.
C H R _API_R C
C H R _c hannel_get _c odec(
C H R _C H AN N EL_H AN D LE
C H R _VI D EO_C OD EC *
)

i_c hannelH andle,

o_v ideoC odec

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_videoCodec [out]
A pointer to the variable where the video codec type (MPEG2 or CUSTOM) is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 256 -

IxChariot APIGuide

CHR_channel_get_comment
DESCRIPTION
The CHR_channel_get_comment function returns the comment string for the specified
IPTV channel object.
C H R _API_R C
C H R _c hannel_get _c omment(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _STR IN G
o_c omment ,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_comment [out]
Character buffer to receive the comment. The symbol CHR_MAX_CHANNEL_COMMENT
may be used to define a character buffer large enough to hold the largest comment string
supported.

i_maxLength [in]
Size of the return buffer.

o_length [out]
A pointer to the variable where the actual number of bytes is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_BUFFER_TOO_SMALL

CHR_PGM_INTERNAL_ERROR

- 257 -

IxChariot APIGuide
* Use CHR_common_error_get_info to get the extended error information available for
this return code.

- 258 -

IxChariot APIGuide

CHR_channel_get_conn_send_buff_size
DESCRIPTION
The CHR_channel_get_conn_send_buff_size function returns the size of the socket connection buffer that this channel uses for send operations.
C H R _API_R C
C H R _ c hannel _ get _c onn_s end_ buf f _s i z e(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C OU N T*
o_buf f erSiz e
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_bufferSize [out]
The buffer size that this channel connection uses for send operations.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_BUFFER_TOO_SMALL

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 259 -

IxChariot APIGuide

CHR_channel_get_console_e1_addr
DESCRIPTION
The CHR_channel_get_console_e1_addr function returns the IP address of Endpoint1 on
the management network. This is the address the console will use to perform IPTV pair
setup.
C H R _API_R C
C H R _ c hannel _ get _ c ons ol e_ e1_addr(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _STR IN G
o_mgmt Addr,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h
)
This parameter is used only if the use_e1_e2_values attribute is False.

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_mgmtAddr [out]
Character buffer to receive the address.

i_maxLength [in]
Size of the return IP address buffer.

o_length [out]
A pointer to the variable where the actual number of bytes is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_BUFFER_TOO_SMALL

CHR_PGM_INTERNAL_ERROR

- 260 -

IxChariot APIGuide
* Use CHR_common_error_get_info to get the extended error information available for
this return code.

- 261 -

IxChariot APIGuide

CHR_channel_get_console_e1_protocol
DESCRIPTION
The CHR_channel_get_console_e1_protocol function returns the network protocol that
the console will use when connecting to Endpoint1 to perform IPTV pair setup.
C H R _API_R C
C H R _ c hannel _ get _ c ons ol e_ e1_prot oc ol (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _PR OTOC OL*
o_prot oc ol
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_protocol [out]
A pointer to the variable where the protocol designation (CHR_PROTOCOL_TCP or CHR_
PROTOCOL_TCP6) is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 262 -

IxChariot APIGuide

CHR_channel_get_e1_addr
DESCRIPTION
The CHR_channel_get_e1_addr function returns the IP address of Endpoint1 on the test
network. The channel will use this as the source IP address of the multicast.
C H R _API_R C
C H R _ c hannel _ get _ e1_addr(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _STR IN G
o_addres s ,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_address [out]
Character buffer to receive the IP address.

i_maxLength [in]
Maximum size of the return buffer.

o_length [out]
A pointer to the variable where the actual number of bytes is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_BUFFER_TOO_SMALL

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 263 -

IxChariot APIGuide

CHR_channel_get_frames_per_datagram
DESCRIPTION
The CHR_channel_get_frames_per_datagram function returns the number of media
frames per datagram defined for the specified IPTV channel.
C H R _API_R C
C H R _c hannel _ get _f ram es _per_dat agram (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C OU N T*
o_f rames
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_frames [out]
A pointer to the variable where the number of media frames per datagram is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 264 -

IxChariot APIGuide

CHR_channel_get_lock
DESCRIPTION
The CHR_channel_get_lock function returns a Boolean value that specifies whether or
not the channel object is locked.
C H R _API_R C
C H R _c hannel_get _loc k (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _BOOLEAN *
o_us eValues
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_useValues [out]
A pointer to the variable where the Boolean value is returned. The returned values are:
l

CHR_TRUE: The channel object is locked.

CHR_FALSE: The channel object is unlocked.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 265 -

IxChariot APIGuide

CHR_channel_get_media_frame_size
DESCRIPTION
The CHR_channel_get_media_frame_size function returns the media frame size defined
for the given IPTV channel.
C H R _API_R C
C H R _c hannel_get _media_f rame_s iz e(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C OU N T*
o_f rameSiz e
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_frameSize [out]
A pointer to the variable where the media frame size value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 266 -

IxChariot APIGuide

CHR_channel_get_multicast_addr
DESCRIPTION
The CHR_channel_get_multicast_addr function returns the multicast IP address of the
given IPTV channel.
C H R _API_R C
C H R _c hannel_get _mult ic as t _addr(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _STR IN G
o_mult ic as t Addr,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_multicastAddr [out]
Character buffer to receive the multicast IP address.

i_maxLength [in]
Maximum size of the return buffer.

o_length [out]
A pointer to the variable where the actual number of bytes is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_BUFFER_TOO_SMALL

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 267 -

IxChariot APIGuide

CHR_channel_get_multicast_port
DESCRIPTION
The CHR_channel_get_multicast_port function returns the multicast port number of
the given IPTV channel.
C H R _API_R C
C H R _c hannel_get _mult ic as t _port (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _POR T*
o_mult ic as t Port
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_multicastPort [out]
A pointer to the variable where the multicast port number is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 268 -

IxChariot APIGuide

CHR_channel_get_name
DESCRIPTION
The CHR_channel_get_name function returns the name assigned to the specified IPTV
channel.
C H R _API_R C
C H R _c hannel_get _name(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _STR IN G
o_name,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_name [out]
Character buffer to receive the channel name.

i_maxLength [in]
Maximum size of the return buffer.

o_length [out]
A pointer to the variable where the actual number of bytes is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_BUFFER_TOO_SMALL

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 269 -

IxChariot APIGuide

CHR_channel_get_protocol
DESCRIPTION
The CHR_channel_get_protocol function returns the test protocol of the specified IPTV
channel.
C H R _API_R C
C H R _c hannel_get _prot oc ol(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _PR OTOC OL*
o_prot oc ol
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_protocol [out]
A pointer to the variable where the test protocol designation is returned. Refer to Typedefs
and Enumerations for the list of valid CHR_PROTOCOL values.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 270 -

IxChariot APIGuide

CHR_channel_get_qos_name
DESCRIPTION
The CHR_channel_get_qos_name function returns the quality-of-service template name
for the specified IPTV channel.
C H R _API_R C
C H R _c hannel_get _qos _name(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _STR IN G
o_qos N ame,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_qosName [out]
Character buffer to receive the QoS template name.

i_maxLength [in]
maximum size of the return buffer.

o_length [out]
A pointer to the variable where the actual number of bytes is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_BUFFER_TOO_SMALL

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 271 -

IxChariot APIGuide

CHR_channel_get_rtp_payload_type
DESCRIPTION
The CHR_channel_get_rtp_payload_type function returns the RTP payload type defined
for the given IPTV channel.
C H R _API_R C
C H R _c hannel_get _rt p_pay load_t y pe(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _BYTE*
o_pay loadTy pe
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_payloadType [out]
A pointer to the variable where the RTP payload type designation is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 272 -

IxChariot APIGuide

CHR_channel_get_source_port_num
DESCRIPTION
The CHR_channel_get_source_port_num function returns the UDP source port number
for the specified IPTV channel.
C H R _API_R C
C H R _c hannel _ get _s ourc e_port _ num(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _POR T*
o_s ourc ePort
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_sourcePort [out]
A pointer to the variable where the UDP source port number is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 273 -

IxChariot APIGuide

CHR_channel_get_use_console_e1_values
DESCRIPTION
The CHR_channel_get_use_console_e1_values function indicates whether the console
will use the management network or the test network to perform pair setup.
C H R _API_R C
C H R _ c hannel _ get _ us e_ c ons ol e_ e1_v al ues (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _BOOLEAN *
o_us eValues
);

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

o_useValues [out]
A pointer to the variable where the Boolean value is returned. The values are:
l

CHR_TRUE if the console will use the management network.

CHR_FALSE if the console will use the test network.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 274 -

IxChariot APIGuide

CHR_channel_new
DESCRIPTION
The CHR_channel_new function creates a new IPTV channel object and initializes it to the
default values.
C H R _API_R C
C H R _c hannel_new(
C H R _C H AN N EL_H AN D LE*
)

o_c hannelH andle

PARAMETERS
o_channelHandle [out]
A handle to the new channel object.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_POINTER_INVALID

CHR_NO_MEMORY

CHR_NOT_LICENSED

CHR_LICENSE_HAS_EXPIRED

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 275 -

IxChariot APIGuide

CHR_channel_set_bitrate
DESCRIPTION
The CHR_channel_set_bitrate function specifies the bit rate value and unit of measurement defined for the given IPTV channel object.
C H R _API_R C
C H R _ c h a n n e l _ s e t _ b i t ra t e(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _FLOAT
i_bit rat e,
C H R _T H R OU GH P U T _U N I T S
i_unit s
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_bitrate [in]
The transmission bit rate for the given IPTV channel object.

i_units [in]
The unit of measurement in which transmission rate is specified. Refer to Typedefs and
Enumerations for the list of valid CHR_THROUGHPUT_UNITS values.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 276 -

IxChariot APIGuide

CHR_channel_set_codec
DESCRIPTION
The CHR_channel_set_codec function specifies the type of codec for the IPTV channel
object.
C H R _API_R C
C H R _c hannel_s et _c odec(
C H R _C H AN N EL_H AN D LE
C H R _VI D EO_C OD EC
)

i_c hannelH andle,

i_v ideoC odec

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_videoCodec [in]
The video codec type that the IPTV channel object will use. Refer to Typedefs and Enumerations for the list of valid CHR_VIDEO_CODEC values.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 277 -

IxChariot APIGuide

CHR_channel_set_comment
DESCRIPTION
The CHR_channel_set_comment function specifies the comment string for the given IPTV
channel object.
C H R _API_R C
C H R _c hannel_s et _c omment(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C ON ST_STR I N G
i_c omment ,
C H R _LEN GTH
i_lengt h
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_comment [in]
Comment string to be assigned to the IPTV channel object.

i_length [in]
The length of comment string (maximum 64 bytes).

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 278 -

IxChariot APIGuide

CHR_channel_set_conn_send_buff_size
DESCRIPTION
The CHR_channel_set_conn_send_buff_size function specifies the desired size of the
socket connection buffer that this channel should use for sending IPTV data streams. Note
that the maximum value is determined by the operating system on which the Performance
Endpoint is running
C H R _API_R C
C H R _ c hannel _ s et _c onn_s end_ buf f _s i z e(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C OU N T
i_buf f erSiz e
)
If the endpoint.ini file specifies the send buffer size (using the SOCKET_SEND_
BUFFER_SIZE keyword), that value overrides the value specified by this API
function.

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_bufferSize [in]
The desired buffer size that this channel should use for send operations. You can specify a
buffer size in the 02,147,483,646 bytes range or as CHR_SOCKET_BUFFER_DEFAULT.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NOT_SUPPORTED

CHR_OBJECT_IN_USE

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_PGM_INTERNAL_ERROR

- 279 -

IxChariot APIGuide

CHR_channel_set_console_e1_addr
DESCRIPTION
The CHR_channel_set_console_e1_addr function specifies the IP address on the management network that the console uses to connect to Endpoint1 during test setup.
C H R _API_R C
C H R _ c hannel _ s et _ c ons ol e_ e1_addr(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C ON ST_STR I N G
i_mgmt Addr,
C H R _LEN GTH
i_lengt h
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_mgmtAddr [in]
Management address of Endpoint 1.

i_length [in]
Length of the management address.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 280 -

IxChariot APIGuide

CHR_channel_set_console_e1_protocol
DESCRIPTION
The CHR_channel_set_console_e1_protocol function specifies the network protocol the
console will use when connecting to Endpoint 1 to perform pair setup.
C H R _API_R C
C H R _ c hannel _ s et _ c ons ol e_ e1_prot oc ol (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _PR OTOC OL
i_prot oc ol
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_protocol [in]
The management network protocol. Refer to Typedefs and Enumerations for the list of
valid CHR_PROTOCOL values.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 281 -

IxChariot APIGuide

CHR_channel_set_e1_addr
DESCRIPTION
The CHR_channel_set_e1_addr function specifies the IP address of Endpoint1 on the test
network. The channel will use this as the source IP address for the multicast.
C H R _API_R C
C H R _ c hannel _ s et _ e1_addr(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C ON ST_STR I N G
i_addres s ,
C H R _LEN GTH
i_lengt h
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_address [in]
Source IP address of channel.

i_length [in]
Length of IP address.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 282 -

IxChariot APIGuide

CHR_channel_set_frames_per_datagram
DESCRIPTION
The CHR_channel_set_frames_per_datagram function specifies the number of media
frames per datagram for the specified IPTV channel.
C H R _API_R C
C H R _c hannel _ s et _f ram es _per_dat agram (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C OU N T
i_f rames
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_frames [in]
The number of media frames per datagram.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 283 -

IxChariot APIGuide

CHR_channel_set_lock
DESCRIPTION
The CHR_channel_set_lock function locks or unlocks the channel object. Locking allows
a channel that is owned by a test to be edited.
C H R _API_R C
C H R _c hannel_s et _loc k (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _BOOLEAN
i_us eValues
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_useValues [in]
Indicates the action to take on the channel object:
l
l

CHR_TRUE: Lock the channel object.

CHR_FALSE: Unlock the channel object. When you unlock the object, it is automatically validated.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_RESULTS_NOT_CLEARED

CHR_OBJECT_INVALID*

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_CHANNEL_DUPLICATE_NAME

* Use CHR_common_error_get_info to get the extended error information available for

this return code.
See Return Code Summary for a detailed description of each return code.

- 284 -

IxChariot APIGuide

CHR_channel_set_media_frame_size
DESCRIPTION
The CHR_channel_set_media_frame_size function specifies the media frame size used
for the IPTV channel.
C H R _API_R C
C H R _c hannel_s et _media_f rame_s iz e(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C OU N T
i_f rameSiz e
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_frameSize [in]
The media frame size to use for the IPTV channel.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 285 -

IxChariot APIGuide

CHR_channel_set_multicast_addr
DESCRIPTION
The CHR_channel_set_multicast_addr function specifies the multicast IP address on
which traffic will be transmitted for the given IPTV channel.
C H R _API_R C
C H R _c hannel_s et _mult ic as t _addr(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C ON ST_STR I N G
i_mult ic as t Addr,
C H R _LEN GTH
i_lengt h
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_multicastAddr [in]
The multicast IP address on which traffic will be transmitted.

i_length [in]
The length of multicast address.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 286 -

IxChariot APIGuide

CHR_channel_set_multicast_port
DESCRIPTION
The CHR_channel_set_multicast_port function specifies the source port number on
which multicast traffic will be transmitted.
C H R _API_R C
C H R _c hannel_s et _mult ic as t _port (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _POR T
i_mult ic as t Port
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_multicastPort [in]
The source port number on which multicast traffic will be transmitted.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 287 -

IxChariot APIGuide

CHR_channel_set_name
DESCRIPTION
The CHR_channel_set_name function specifies a name of the IPTV channel. The name is a
characters string, such as "BBC".
C H R _API_R C
C H R _c hannel_s et _name(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C ON ST_STR I N G
i_name,
C H R _LEN GTH
i_lengt h
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_name [in]
The name to be assigned to IPTV channel object.

i_length [in]
The length of channel name.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 288 -

IxChariot APIGuide

CHR_channel_set_protocol
DESCRIPTION
The CHR_channel_set_protocol function specifies the test protocol of the IPTV channel.
C H R _API_R C
C H R _c hannel_s et _prot oc ol(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _PR OTOC OL
i_prot oc ol
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_protocol [in]
The test protocol of the IPTV channel. Refer to Typedefs and Enumerations on page 4-616
for the list of valid CHR_PROTOCOL values.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 289 -

IxChariot APIGuide

CHR_channel_set_qos_name
DESCRIPTION
The CHR_channel_set_qos_name function specifies the quality-of-service template name
for the IPTV channel.
C H R _API_R C
C H R _c hannel_s et _qos _name(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C ON ST_STR I N G
i_qos N ame,
C H R _LEN GTH
i_lengt h
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_qosName [in]
The QoS template name.

i_length [in]
The length of the QoS template name.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 290 -

IxChariot APIGuide

CHR_channel_set_rtp_payload_type
DESCRIPTION
The CHR_channel_set_rtp_payload_type function specifies the RTP payload type for the
given IPTV channel.
C H R _API_R C
C H R _c hannel_s et _rt p_pay load_t y pe(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _BYTE
i_pay loadTy pe
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_payloadType [in]
The RTP payload type.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 291 -

IxChariot APIGuide

CHR_channel_set_source_port_num
DESCRIPTION
The CHR_channel_set_source_port_num function specifies the UDP source port number
for the IPTV channel.
C H R _API_R C
C H R _c hannel _ s et _s ourc e_port _ num(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _POR T
i_s ourc ePort
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_sourcePort [in]
The UDP source port number.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 292 -

IxChariot APIGuide

CHR_channel_set_use_console_e1_values
DESCRIPTION
The CHR_channel_set_use_console_e1_values function specifies whether the console
will use the management network or the test network to perform IPTV pair setup.
C H R _API_R C
C H R _ c hannel _ s et _ us e_ c ons ol e_ e1_v al ues (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _BOOLEAN
i_us eValues
)

PARAMETERS
i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

i_useValues [in]
Specifies whether the console will use the test network or the management network to perform IPTV pair setup:
l

CHR_TRUE: The console will use the management network.

CHR_FALSE: The console will use the test network.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NOT_SUPPORTED

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 293 -

IxChariot APIGuide

IPTV Pair Object Functions

The IPTV pair object functions are used to define IPTV pairs (vpairs) for a test and retrieve
information about an endpoint vpair..
A related set of commands is provided for IPTV channel objects and IPTV receiver objects.

- 294 -

IxChariot APIGuide

CHR_vpair_delete
DESCRIPTION
The

CHR_vpair_delete

function deletes the specified IPTV pair object.

C H R _API_R C
C H R _v pair_delet e(
C H R _VPAI R _H AN D LE
)

i_pairH andle

PARAMETERS
i_pairHandle [in]
An IPTV pair object handle returned by CHR_vpair_new() or CHR_receiver_get_vpair().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 295 -

IxChariot APIGuide

CHR_vpair_get_channel
DESCRIPTION
The CHR_vpair_get_channel function returns the IPTV channel with which this IPTV pair is
associated.
C H R _API_R C
C H R _v pair_get _c hannel(
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C H AN N EL_H AN D LE*
o_c hannel
)

PARAMETERS
i_pairHandle [in]
An IPTV pair object handle returned by CHR_vpair_new() or CHR_receiver_get_vpair().

o_channel [out]
A pointer to the variable to which the function returns the IPTV channel handle.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 296 -

IxChariot APIGuide

CHR_vpair_get_lock
DESCRIPTION
The CHR_vpair_get_lock function returns a Boolean value that specifies whether or not
the IPTV pair object is locked.
C H R _API_R C
C H R _v pair_get _loc k (
C H R _VPAI R _H AN D LE
C H R _BOOLEAN *
)

i_pairH andle,
o_us eValues

PARAMETERS
i_pairHandle [in]
An IPTV pair object handle returned by CHR_vpair_new() or CHR_receiver_get_vpair().

o_useValues [out]
A pointer to the variable where the Boolean value is returned. The returned values are:
l

CHR_TRUE: The IPTV pair object is locked.

CHR_FALSE: The IPTV pair object is unlocked.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 297 -

IxChariot APIGuide

CHR_vpair_get_no_of_timing_records
DESCRIPTION
The CHR_vpair_get_no_of_timing_records function returns the number of timing
records that the pair has been configured to create during the execution of a test.
C H R _API_R C
C H R _ v pai r_ get _ no_of _ t i m i ng_rec ords (
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C OU N T*
o_c ount
)

PARAMETERS
i_pairHandle [in]
An IPTV pair object handle returned by CHR_vpair_new() or CHR_receiver_get_vpair().

o_count [out]
A pointer to the variable to which the function returns the number of timing records that
the IPTV pair has been configured to generate.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 298 -

IxChariot APIGuide

CHR_vpair_get_report
DESCRIPTION
The CHR_vpair_get_report function returns the specified report for this IPTV pair.
C H R _API_R C
C H R _v pair_get _report (
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C OU N T
i_report I ndex ,
C H R _R E P OR T _H A N D LE *
o_report H andle
)

PARAMETERS
i_pairHandle [in]
An IPTV pair object handle returned by CHR_vpair_new() or CHR_receiver_get_vpair().

i_reportIndex [in]
Zero-based index of the requested report. Must be less than the value returned by CHR_
vpair_get_report_count().

o_reportHandle [out]
A pointer to the variable where the handle of the requested report is returned. Refer to
Report Object Functions for a description of the report object APIs.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 299 -

IxChariot APIGuide

CHR_vpair_get_report_count
DESCRIPTION
The CHR_vpair_get_report_count function returns the number of reports collected for
this IPTV pair.
C H R _API_R C
C H R _v pai r_get _report _c ount (
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C OU N T*
o_report C ount
)

PARAMETERS
i_pairHandle [in]
An IPTV pair object handle returned by CHR_vpair_new() or CHR_receiver_get_vpair().

o_reportCount [out]
A pointer to the variable where the report count is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 300 -

IxChariot APIGuide

CHR_vpair_get_runStatus
DESCRIPTION
The

CHR_vpair_get_runStatus function returns the run status for this IPTV pair.

C H R _API_R C
C H R _v pair_get _runSt at us(
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _PAI R _R U N STATU S_TYPE *runSt at us
)

PARAMETERS
i_pairHandle [in]
An IPTV pair object handle returned by CHR_vpair_new() or CHR_receiver_get_vpair().

runStatus [out]
A pointer to the variable where the run status value is returned. The following status types
are applicable:
l

CHR_PAIR_RUNSTATUS_UNINITIALIZED

CHR_PAIR_RUNSTATUS_INITIALIZING_1

CHR_PAIR_RUNSTATUS_INITIALIZING_2

CHR_PAIR_RUNSTATUS_INITIALIZING_3

CHR_PAIR_RUNSTATUS_INITIALIZED

CHR_PAIR_RUNSTATUS_RUNNING

CHR_PAIR_RUNSTATUS_STOPPING

CHR_PAIR_RUNSTATUS_REQUESTED_STOP

CHR_PAIR_RUNSTATUS_ERROR

CHR_PAIR_RUNSTATUS_RESOLVING_NAMES

CHR_PAIR_RUNSTATUS_POLLING

CHR_PAIR_RUNSTATUS_FINISHED

CHR_PAIR_RUNSTATUS_REQUESTING_STOP

CHR_PAIR_RUNSTATUS_FINISHED_WARNINGS

CHR_PAIR_RUNSTATUS_TRANSFERRING_PAYLOAD

CHR_PAIR_RUNSTATUS_APPLYING_IXIA_CONFIG

CHR_PAIR_RUNSTATUS_WAITING_FOR_REINIT

CHR_PAIR_RUNSTATUS_ABANDONED

See also typedef char CHR_PAIR_RUNSTATUS_TYPE, listed in Typedefs and Enumerations.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK

- 301 -

IxChariot APIGuide
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 302 -

IxChariot APIGuide

CHR_vpair_get_timing_record
DESCRIPTION
The CHR_vpair_get_timing_record function returns the specified timing record for this
IPTV pair.
C H R _API_R C
C H R _v pai r_get _t i m i ng_rec ord(
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C OU N T
i_rec ordI ndex ,
C H R _TI MI N GR EC _H AN D LE* o_rec ordH andle
)

PARAMETERS
i_pairHandle [in]
An IPTV pair object handle returned by CHR_vpair_new() or CHR_receiver_get_vpair().

i_recordIndex [in]
Zero-based index of the requested timing record. Must be less than the value returned by
CHR_vpair_get_timing_record_count().

o_recordHandle [out]
A pointer to the variable where the timing record handle is returned. Refer to Timing
Record Object Functions for a description of the timing record object APIs.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 303 -

IxChariot APIGuide

CHR_vpair_get_timing_record_count
DESCRIPTION
The CHR_vpair_get_timing_record_count function returns the number of timing records
collected for this IPTV pair.
C H R _API_R C
C H R _v pai r_get _t i m i ng_rec ord_ c ount (
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C OU N T*
o_rec ordC ount
)

PARAMETERS
i_pairHandle [in]
An IPTV pair object handle returned by CHR_vpair_new() or CHR_receiver_get_vpair().

o_reportCount [out]
A pointer to the variable where the timing record count is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 304 -

IxChariot APIGuide

CHR_vpair_get_tr_duration
DESCRIPTION
The CHR_vpair_get_tr_duration function returns the timing record duration, in
seconds.
C H R _API_R C
C H R _ v pai r_ get _ t r_durat i on(
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C OU N T*
o_durat ion
)

PARAMETERS
i_pairHandle [in]
An IPTV pair object handle returned by CHR_vpair_new() or CHR_receiver_get_vpair().

o_duration [out]
A pointer to the variable where the timing record duration is returned. (The timing record
duration is measured in seconds.)

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 305 -

IxChariot APIGuide

CHR_vpair_new
DESCRIPTION
The

CHR_vpair_new function creates a new IPTV pair object.

C H R _API_R C
C H R _v pair_new(
C H R _VPAI R _H AN D LE*
)

o_pairH andle

PARAMETERS
o_pairHandle [out]
The handle for the new IPTV pair object.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_NOT_LICENSED

CHR_LICENSE_HAS_EXPIRED

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 306 -

IxChariot APIGuide

CHR_vpair_set_lock
DESCRIPTION
The CHR_vpair_set_lock function locks or unlocks the IPTV pair object. Locking allows a
pair that is owned by a receiver to be edited.
C H R _API_R C
C H R _v pair_s et _loc k (
C H R _VPAI R _H AN D LE
C H R _BOOLEAN
)

i_pairH andle,
i_us eValues

PARAMETERS
i_pairHandle [in]
An IPTV pair object handle returned by CHR_vpair_new() or
CHR_receiver_get_vpair().

i_useValues [in]
Indicates the action to take on the IPTV pair object:
l
l

CHR_TRUE: Lock the IPTV pair object.

CHR_FALSE: Unlock the IPTV pair object. When you unlock the object, it is automatically validated.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_RESULTS_NOT_CLEARED

CHR_OBJECT_INVALID*

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.
See Return Code Summary for a detailed description of each return code.

- 307 -

IxChariot APIGuide

CHR_vpair_set_no_of_timing_records
DESCRIPTION
The CHR_vpair_set_no_of_timing_records
records the IPTV pair should generate.

function specifies the number of timing

C H R _API_R C
C H R _ v pai r_ s et _ no_of _ t i m i ng_rec ords (
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C OU N T
i_c ount
)

PARAMETERS
i_pairHandle [in]
An IPTV pair object handle returned by CHR_vpair_new() or CHR_receiver_get_vpair().

i_count [in]
The number of timing records the IPTV pair should generate.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 308 -

IxChariot APIGuide

CHR_vpair_set_channel
DESCRIPTION
The CHR_vpair_set_channel function specifies the channel with which this IPTV pair is
associated.
C H R _API_R C
C H R _v pair_s et _c hannel(
C H R _VPAI R _H AN D LE
C H R _C H AN N EL_H AN D LE
)

i_pairH andle,
i_c hannel

PARAMETERS
i_pairHandle [in]
An IPTV pair object handle returned by CHR_vpair_new() or CHR_receiver_get_vpair().

i_channel [in]
The channel handle returned by CHR_channel_new(), CHR_test_get_channel(), or CHR_
test_get_channel_by_name().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 309 -

IxChariot APIGuide

CHR_vpair_set_tr_duration
DESCRIPTION
The CHR_vpair_set_tr_duration function specifies the timing record duration, in
seconds.
C H R _API_R C
C H R _ v pai r_ s et _ t r_durat i on(
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C OU N T
i_durat ion
)

PARAMETERS
i_pairHandle [in]
An IPTV pair object handle returned by CHR_vpair_new() or CHR_receiver_get_vpair().

i_duration [in]
The timing record duration, in seconds.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 310 -

IxChariot APIGuide

IPTV Receiver Object Functions

The IPTV receiver object functions are used to configure receiver group objects. Receiver
groups are the subscribers of the IPTV channels. Each channel is represented by a VPair
within a receiver group.
A related set of commands is provided for IPTV channel objects and IPTV VPair objects.

- 311 -

IxChariot APIGuide

CHR_receiver_add_vpair
DESCRIPTION
The CHR_receiver_add_vpair
receiver.

function adds an IPTV pair to the list for the designated

C H R _API_R C
C H R _rec ei v er_add_v pai r (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _VPAI R _H AN D LE
i_pairH andle
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

i_pairHandle [in]
The handle of the IPTV pair to be added to the receiver list. The vpair object handle is
returned by CHR_vpair_new().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 312 -

IxChariot APIGuide

CHR_receiver_delete
DESCRIPTION
The

CHR_receiver_delete function deletes the specified IPTV receiver object.

C H R _API_R C
C H R _rec ei v er_del et e(
C H R _R E C E I V E R _H A N D LE
)

i_rec eiv erH andle

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 313 -

IxChariot APIGuide

CHR_receiver_disable
DESCRIPTION
The CHR_receiver_disable function disables or enables all of the pairs assigned to the
specified IPTV receiver. IxChariot ignores any disabled pairs when running a test.
CHR_API_RC
CHR_receiver_disable (
CHR_RECEIVER_HANDLE
CHR_BOOLEAN
)

i_receiverHandle,
i_disable

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

i_disable [in]
Specifies the action to perform:
l

CHR_TRUE: Disable all the IPTV receiver pairs for the test.

CHR_FALSE: Enable all the IPTV receiver pairs for the test.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_API_NOT_INITIALIZED

CHR_VALUE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 314 -

IxChariot APIGuide

CHR_receiver_get_comment
DESCRIPTION
The CHR_receiver_get_comment function returns the comment string for the specified
IPTV receiver object.
C H R _API_R C
C H R _rec ei v er_get _c om m ent (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _STR IN G
o_c omment ,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

o_comment [out]
Character buffer to receive the comment.

i_maxLength [in]
Maximum size of the return buffer.

o_length [out]
A pointer to the variable where the actual number of bytes is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_BUFFER_TOO_SMALL

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 315 -

IxChariot APIGuide

- 316 -

IxChariot APIGuide

CHR_receiver_get_conn_recv_buff_size
DESCRIPTION
The CHR_receiver_get_conn_recv_buff_size function returns the size of the socket
connection buffer that this receiver uses for receiving IPTV data streams.
C H R _API_R C
C H R _ rec ei v er_get _c onn_ rec v _buf f _ s i z e(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C OU N T*
o_buf f erSiz e
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

o_bufferSize [out]
The buffer size that this receiver uses for receiving IPTV data streams.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_BUFFER_TOO_SMALL

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 317 -

IxChariot APIGuide

CHR_receiver_get_e2_addr
DESCRIPTION
The CHR_receiver_get_e2_addr function returns the IP address of an Endpoint2
receiver on the test network.
C H R _API_R C
C H R _rec ei v er_get _e2_ addr(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _STR IN G
o_addres s ,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

o_address [out]
Character buffer to receive the IP address.

i_maxLength [in]
Maximum size of the return buffer.

o_length [out]
A pointer to the variable where the actual number of bytes is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_BUFFER_TOO_SMALL

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 318 -

IxChariot APIGuide

- 319 -

IxChariot APIGuide

CHR_receiver_get_lock
DESCRIPTION
The CHR_receiver_get_lock function returns a Boolean value that specifies whether or
not the receiver object is locked.
C H R _API_R C
C H R _rec ei v er_get _l oc k (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _BOOLEAN *
o_us eValues
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

o_useValues [out]
A pointer to the variable where the Boolean value is returned. The returned values are:
l

CHR_TRUE: The receiver object is locked.

CHR_FALSE: The receiver object is unlocked.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 320 -

IxChariot APIGuide

CHR_receiver_get_name
DESCRIPTION
The CHR_receiver_get_name function returns the name assigned to the specified IPTV
receiver.
C H R _API_R C
C H R _rec ei v er_get _nam e(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _STR IN G
o_name,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

o_name [out]
Character buffer to receive the receiver name.

i_maxLength [in]
Maximum size of the return buffer.

o_length [out]
A pointer to the variable where the actual number of bytes is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_BUFFER_TOO_SMALL

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 321 -

IxChariot APIGuide

- 322 -

IxChariot APIGuide

CHR_receiver_get_no_of_iterations
DESCRIPTION
The CHR_receiver_get_no_of_iterations function returns the number of times the
JOIN/LEAVE loop will be repeated in the test.
C H R _API_R C
C H R _ rec ei v er_get _ no_ of _i t erat i ons (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C OU N T*
o_it erat ions
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

o_iterations [out]
A pointer to the variable where the JOIN/LEAVE repeat count is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 323 -

IxChariot APIGuide

CHR_receiver_get_vpair
DESCRIPTION
The CHR_receiver_get_vpair function returns the IPTV pair object with the specified
index from the list of pairs assigned to this receiver.
C H R _API_R C
C H R _rec ei v er_get _v pai r (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C OU N T
i_pairI ndex ,
C H R _VPAI R _H AN D LE*
o_pairH andle
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

i_pairIndex [in]
Zero-based index of the desired entry in the pair list. Must be less than the value returned
by CHR_receiver_get_pair_count().

o_pairHandle [out]
A pointer to the variable where the handle of the IPTV pair object is returned. Refer to
IPTV Pair Object Functions on page 4-178 for a description of the IPTV pair object APIs.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 324 -

IxChariot APIGuide

CHR_receiver_get_vpair_count
DESCRIPTION
The CHR_receiver_get_vpair_count function returns the number of pairs that have
been assigned to this receiver.
C H R _API_R C
C H R _rec ei v er_get _v pai r_c ount (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C OU N T*
o_pairC ount
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

o_pairCount [out]
A pointer to the variable where the number of entries in the pair list is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 325 -

IxChariot APIGuide

CHR_receiver_get_setup_e1_e2_addr
DESCRIPTION
The CHR_receiver_get_setup_e1_e2_addr function returns the management IP address
of the receiver.
C H R _API_R C
C H R _ rec ei v er_get _ s et up_ e1_ e2_addr(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _STR IN G
o_addres s ,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

o_address [out]
Character buffer to receive the IP address.

i_maxLength [in]
Maximum size of the return buffer.

o_length [out]
A pointer to the variable where the actual number of bytes is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_BUFFER_TOO_SMALL

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 326 -

IxChariot APIGuide

- 327 -

IxChariot APIGuide

CHR_receiver_get_switch_delay
DESCRIPTION
The CHR_receiver_get_switch_delay function returns the channel switch delay (measured as the interval between a LEAVE and the next JOIN).
C H R _API_R C
C H R _rec ei v er_get _s w i t c h_ del ay (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C OU N T*
o_s w it c hD elay
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

o_switchDelay [out]
A pointer to the variable where the switch delay value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 328 -

IxChariot APIGuide

CHR_receiver_get_use_e1_e2_values
DESCRIPTION
The CHR_receiver_get_use_e1_e2_values function indicates whether IxChariot will use
the management network or the test network when setting up the test.
C H R _API_R C
C H R _ rec ei v er_get _ us e_ e1_ e2_v al ues (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _BOOLEAN *
o_us eValues
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

o_useValues [out]
A pointer to the variable where the Boolean value is returned. The values are:
l

CHR_TRUE if IxChariot will perform pair setup over the management network.

CHR_FALSE if IxChariot will perform pair setup over the test network.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 329 -

IxChariot APIGuide

CHR_receiver_is_disabled
DESCRIPTION
The CHR_receiver_is_disabled function determines whether or not the pairs in the specified IPTV receiver group are disabled.
CHR_API_RC
CHR_receiver_is_ disabled(
CHR_RECEIVER_HANDLE
CHR_BOOLEAN*
)

i_receiverHandle,
o_disabled

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

o_disabled [out]
A pointer to the variable where the Boolean value is returned. The returned values can be:
l

CHR_TRUE: All the pairs in the specified IPTV receiver group are disabled.

CHR_FALSE: All the pairs in the specified IPTV receiver group are enabled.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 330 -

IxChariot APIGuide

CHR_receiver_new
DESCRIPTION
The CHR_receiver_new function creates a new IPTV receiver object and initializes it to
the default values.
C H R _API_R C
C H R _rec ei v er_new (
C H R _R E C E I V E R _H A N D LE *
)

o_rec eiv erH andle

PARAMETERS
o_receiverHandle [out]
A handle to the new receiver object.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_POINTER_INVALID

CHR_NO_MEMORY

CHR_NOT_LICENSED

CHR_LICENSE_HAS_EXPIRED

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 331 -

IxChariot APIGuide

CHR_receiver_remove_vpair
DESCRIPTION
The CHR_receiver_remove_vpair function removes an IPTV pair from the list for this
receiver.
C H R _API_R C
C H R _ r e c e i v e r _r e m o v e _ v p a i r(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _VPAI R _H AN D LE
i_pairH andle
)
To use this function, the receiver object must be either unowned or locked.

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

i_pairHandle [in]
An IPTV pair object handle returned by CHR_vpair_new() or
CHR_receiver_get_vpair().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_SUCH_OBJECT

CHR_OBJECT_IN_USE

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 332 -

IxChariot APIGuide

CHR_receiver_set_comment
DESCRIPTION
The CHR_receiver_set_comment function specifies a comment string for the specified
IPTV receiver object.
C H R _API_R C
C H R _rec ei v er_s et _c om m ent (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C ON ST_STR I N G
i_c omment ,
C H R _LEN GTH
i_lengt h
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

i_comment [in]
The comment string to be assigned to the receiver.

i_length [in]
The length of the comment string.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 333 -

IxChariot APIGuide

CHR_receiver_set_conn_recv_buff_size
DESCRIPTION
The CHR_receiver_set_conn_recv_buff_size function specifies the desired size of the
socket connection buffer that this receiver should use for receiving IPTV data streams.
Note that the maximum value is determined by the operating system on which the Performance Endpoint is running.
C H R _API_R C
C H R _ rec ei v er_s et _c onn_ rec v _buf f _ s i z e(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C OU N T
i_buf f erSiz e
)
If the endpoint.ini file specifies the receive buffer size (using the SOCKET_
RECEIVE_BUFFER_SIZE keyword), that value overrides the value specified by
this API function.

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

i_bufferSize [in]
The desired buffer size that this receiver should use for receiving IPTV data streams. You
can specify a buffer size in the 02147483646 bytes range or as CHR_SOCKET_BUFFER_
DEFAULT.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_BUFFER_TOO_SMALL

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 334 -

IxChariot APIGuide

CHR_receiver_set_e2_addr
DESCRIPTION
The CHR_receiver_set_e2_addr function specifies the IP address of an Endpoint2
receiver on the test network.
C H R _API_R C
C H R _rec ei v er_s et _e2_ addr(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C ON ST_STR I N G
i_addres s ,
C H R _LEN GTH
i_lengt h
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

i_address [in]
IP address to be assigned to the receiver.

i_length [in]
The length of the IP address.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 335 -

IxChariot APIGuide

CHR_receiver_set_lock
DESCRIPTION
The CHR_receiver_set_lock function locks or unlocks the receiver object. Locking
allows a receiver that is owned by a test to be edited.
C H R _API_R C
C H R _rec ei v er_s et _l oc k (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _BOOLEAN
i_us eValues
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

i_useValues [in]
Indicates the action to take on the receiver object:
l
l

CHR_TRUE: Lock the receiver object.

CHR_FALSE: Unlock the receiver object. When you unlock the object, it is automatically validated.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_RESULTS_NOT_CLEARED

CHR_OBJECT_INVALID*
CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RECEIVER_DUPLICATE_NAME

* Use CHR_common_error_get_info to get the extended error information available for

this return code.
See Return Code Summary for a detailed description of each return code.

- 336 -

IxChariot APIGuide

CHR_receiver_set_name
DESCRIPTION
The CHR_receiver_set_name function specifies the name of the IPTV receiver object.
C H R _API_R C
C H R _rec ei v er_s et _nam e(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C ON ST_STR I N G
i_name,
C H R _LEN GTH
i_lengt h
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

i_name [in]
The name to assign to the receiver object.

i_length [in]
The length of the name string.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 337 -

IxChariot APIGuide

CHR_receiver_set_no_of_iterations
DESCRIPTION
The CHR_receiver_set_no_of_iterations function specifies the number of times the
JOIN/LEAVE loop is to be repeated in the test.
C H R _API_R C
C H R _ rec ei v er_s et _ no_ of _i t erat i ons (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C OU N T
i_it erat ions
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

i_iterations [in]
The number of times the JOIN/LEAVE loop is to be repeated.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 338 -

IxChariot APIGuide

CHR_receiver_set_setup_e1_e2_addr
DESCRIPTION
The CHR_receiver_set_setup_e1_e2_addr function specifies the IP address of the
receiver on the management network.
C H R _API_R C
C H R _ rec ei v er_s et _ s et up_ e1_ e2_addr(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C ON ST_STR I N G
i_addres s ,
C H R _LEN GTH
i_lengt h
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

i_address [in]
The management IP address.

i_length [in]
The length of the management IP address.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 339 -

IxChariot APIGuide

CHR_receiver_set_switch_delay
DESCRIPTION
The CHR_receiver_set_switch_delay function specifies the channel switch delay (the
interval between a LEAVE and the next JOIN).
C H R _API_R C
C H R _rec ei v er_s et _s w i t c h_ del ay (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C OU N T
i_s w it c hD elay
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

i_switchDelay [in]
The channel switch delay, in milliseconds.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 340 -

IxChariot APIGuide

CHR_receiver_set_use_e1_e2_values
DESCRIPTION
The CHR_receiver_set_use_e1_e2_values function specifies whether IxChariot will use
the management network or the test network when setting up the test.
C H R _API_R C
C H R _ rec ei v er_s et _ us e_ e1_ e2_v al ues (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _BOOLEAN
i_us eValues
)

PARAMETERS
i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

o_useValues [out]
Specifies whether the receiver will use the test network or the management network when
setting up the test:
l

CHR_TRUE: IxChariot will perform pair setup over the management network.

CHR_FALSE: IxChariot will perform pair setup over the test network.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 341 -

IxChariot APIGuide

Multicast Group Object Functions

The multicast group object functions are used to define and retrieve information about a
multicast group. A separate set of functions is provided to define and retrieve information
about multicast group members, called multicast pairs (mpairs). You cannot add members
to or set the attributes of a multicast group object that is contained by a test object.

- 342 -

IxChariot APIGuide

CHR_mgroup_add_mpair
DESCRIPTION
The CHR_mgroup_add_mpair function adds the given multicast pair to the given multicast
group. A multicast pair handle can only be added to one multicast group and can only be
added once to that group.
C H R _API_R C
C H R _m group_add_m pai r (
C H R _MGR OU P_H AN D LE mgroup,
C H R _MPAI R _H AN D LE mpair
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

mpair [in]
A handle returned by CHR_mpair_new(). The multicast pair handle is checked to ensure
that it refers to a properly defined multicast pair before the mpair is added to the multicast
group. If not properly defined, CHR_OBJECT_INVALID is returned. This mpair must not be
owned by any other mgroup.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PAIR_LIMIT_EXCEEDED

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_VALUE_INVALID

* Use CHR_common_error_get_info to get the extended error information available for

this return code.
See Return Code Summary for a detailed description of each return code.

- 343 -

IxChariot APIGuide

CHR_mgroup_copy
DESCRIPTION
The CHR_mgroup_copy function copies the attributes of the source multicast group to the
destination multicast group. This does not include any results information.
C H R _API_R C
C H R _m group_c opy (
C H R _MGR OU P_H AN D LE des t ,
C H R _MGR OU P_H AN D LE s rc
)
The attributes that are copied are:
l

appl_script_name

comment

console_e1_addr

console_e1_protocol

console_e1_qos_name

e1_addr

multicast_addr

multicast_port

name

protocol

qos_name

script_filename (and script values)

use_console_e1_values

mpair objects*
The multicast pairs in the source object are added to the multicast pairs in the
destination.

PARAMETERS
dest [in]
A handle for the destination, returned by CHR_mgroup_new() or CHR_test_get_mgroup().

src [in]
A handle for the source, returned by CHR_mgroup_new() or CHR_test_get_mgroup().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:

- 344 -

IxChariot APIGuide

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR
Use CHR_common_error_get_info to get the extended error information available for this return code.

See Return Code Summary for a detailed description of each return code.

- 345 -

IxChariot APIGuide

CHR_mgroup_delete
DESCRIPTION
The CHR_mgroup_delete function frees all memory associated with the given multicast
group.<META NAME="Keywords" CONTENT="Multicast Group Object Functions:CHR_
mgroup_delete, Return Codes">
C H R _API_R C
C H R _m group_del et e(
C H R _MGR OU P_H AN D LE mgroup
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup(). After verifying that
the handle refers to a valid multicast group object, it is checked to ensure that it is not referenced by a test object known by the API. The multicast group object is not deleted if it is
contained by a test object.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 346 -

IxChariot APIGuide

CHR_mgroup_disable
DESCRIPTION
The CHR_mgroup_disable function disables or enables all of the pairs assigned to the specified multicast group or video multicast group. IxChariot ignores any disabled pairs when
running a test.
CHR_API_RC
CHR_mgroup_disable (
CHR_MGROUP_HANDLE mgroupHandle,
CHR_BOOLEAN disable
)

PARAMETERS
mgroupHandle [in]
A handle returned by any of the following functions: CHR_mgroup_new(),
CHR_video_mgroup_new(), or CHR_test_get_mgroup().

disable [in]
Specifies the action to perform:
l

CHR_TRUE: Disable all the multicast group pairs or video multicast group pairs for
the test.
CHR_FALSE: Enable all the multicast group pairs or video multicast group pairs for
the test.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_API_NOT_INITIALIZED

CHR_VALUE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 347 -

IxChariot APIGuide

CHR_mgroup_get_appl_script_name
DESCRIPTION
The CHR_mgroup_get_appl_script_name function gets the application script name for the
given multicast group.
C H R _API_R C
C H R _m group_get _appl _ s c ri pt _nam e(
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
mgroup [in]
l

A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

buf [out]
l

A pointer to the buffer where the script name is returned.

len [in]
l

The length of the buffer.

rtnlen [out]
l

A pointer to the variable where the number of bytes in the buffer is returned, excluding the null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 348 -

IxChariot APIGuide

CHR_mgroup_get_comment
DESCRIPTION
The CHR_mgroup_get_comment function gets the comment for the given multicast group.
C H R _API_R C
C H R _m group_get _c om m ent (
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

buf [out]
A pointer to the buffer where the comment is returned.

len [in]
The length of the buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 349 -

IxChariot APIGuide

CHR_mgroup_get_console_e1_addr
DESCRIPTION
The CHR_mgroup_get_console_e1_addr function gets the address by which the Console
knows Endpoint 1 for the given multicast group. This attribute applies only when the CHR_
mgroup_set_use_console_e1_values function sets the "use" attribute to CHR_TRUE.
C H R _API_R C
C H R _m group_get _c ons ol e_ e1_ addr(
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

buf [out]
A pointer to the buffer where the address is returned.

len [in]
The length of the buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 350 -

IxChariot APIGuide

CHR_mgroup_get_console_e1_protocol
DESCRIPTION
The CHR_mgroup_get_console_e1_protocol function gets the Console to Endpoint 1 network protocol for the given multicast group. This attribute applies only when the CHR_
mgroup_set_use_console_e1_values function sets the "use" attribute to CHR_TRUE.
C H R _API_R C
C H R _m group_get _c ons ol e_ e1_ prot oc ol (
C H R _MGR OU P_H AN D LE mgroup,
C H R _PR OTOC OL* prot oc ol
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

protocol [out]
A pointer to the variable where the protocol is returned. See the CHR_mgroup_set_console_e1_protocol function for applicable protocols.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 351 -

IxChariot APIGuide

CHR_mgroup_get_console_e1_qos_name
DESCRIPTION
The CHR_mgroup_get_console_e1_qos_name function gets the quality of service name for
Console to Endpoint 1 for the given multicast group. This attribute applies only when the
CHR_mgroup_set_use_console_e1_values function sets the "use" attribute to CHR_TRUE.
C H R _API_R C
C H R _m group_get _c ons ol e_ e1_ qos _nam e(
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)
This function is applicable only to APPC. IxChariot 6.20 and higher no longer support APPC.

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

buf [out]
A pointer to the buffer where the quality of service name is returned.

len [in]
The length of the buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 352 -

IxChariot APIGuide

- 353 -

IxChariot APIGuide

CHR_mgroup_get_e1_addr
DESCRIPTION
The CHR_mgroup_get_e1_addr function gets the Endpoint 1 address for the given multicast
group.
C H R _API_R C
C H R _m group_get _e1_ addr(
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

buf [out]
A pointer to the buffer where the Endpoint 1 address is returned.

len [in]
The length of the buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 354 -

IxChariot APIGuide

CHR_mgroup_get_e1_config_value
DESCRIPTION
The CHR_mgroup_get_e1_config_value function gets an Endpoint 1 configuration value
from the multicast group. The configuration information is returned from the endpoint during test execution.
C H R _API_R C
C H R _m group_get _e1_ c onf i g_v al ue (
C H R _MGR OU P_H AN D LE mpair ,
CHR_CFG_PARM v alue,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

value [in]
One of the CHR_CFG_PARM values. See "Typedefs and Enumerations" for CHR_CFG_PARM
values.

buf [out]
A pointer to the buffer where the endpoint configuration value is returned.

len [in]
The length of the buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

- 355 -

IxChariot APIGuide

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 356 -

IxChariot APIGuide

CHR_mgroup_get_mpair
DESCRIPTION
The CHR_mgroup_get_mpair function gets the handle for the multicast pair that corresponds to the given index number in the given multicast group. The handle returned by
this function is needed for other function calls to operate on this object.
C H R _API_R C
C H R _m group_get _m pai r (
C H R _MGR OU P_H AN D LE mgroup,
C H R _C OU N T index ,
C H R _MPAI R _H AN D LE* mpair
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

index [in]
An index into the array of multicast pairs. The index parameter is determined by the order
in which mpairs were added to this multicast group.

mpair [out]
A pointer to the variable where the multicast pair handle is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 357 -

IxChariot APIGuide

CHR_mgroup_get_mpair_count
DESCRIPTION
The CHR_mgroup_get_mpair_count function gets the number of multicast pairs owned by
the given multicast group.
C H R _API_R C
C H R _m group_get _m pai r_c ount (
C H R _MGR OU P_H AN D LE mgroup,
C H R _C OU N T* c ount
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

count[out]
A pointer to the variable where the number of multicast pairs is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 358 -

IxChariot APIGuide

CHR_mgroup_get_multicast_addr
DESCRIPTION
The CHR_mgroup_get_multicast_addr function gets the multicast IP address for the given
multicast group.
C H R _API_R C
C H R _m group_get _m ul t i c as t _ addr(
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

buf [out]
A pointer to the buffer where the multicast IP address is returned.

len [in]
The length of the buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 359 -

IxChariot APIGuide

CHR_mgroup_get_multicast_port
DESCRIPTION
The CHR_mgroup_get_multicast_port function gets the multicast port number for the given
multicast group.
C H R _API_R C
C H R _m group_get _m ul t i c as t _ port (
C H R _MGR OU P_H AN D LE mgroup,
C H R _POR T* port
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

port [out]
A pointer to the variable where the multicast port number is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 360 -

IxChariot APIGuide

CHR_mgroup_get_name
DESCRIPTION
The CHR_mgroup_get_name function gets the name for the given multicast group.
C H R _API_R C
C H R _m group_get _nam e(
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

buf [out]
A pointer to the buffer where the multicast group name is returned.

len
The length of the buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary on page A-1 for a detailed description of each return code.

- 361 -

IxChariot APIGuide

CHR_mgroup_get_payload_file
DESCRIPTION
The CHR_mgroup_get_payload_file function gets the name of the payload file that is
defined for the script used by the given multicast group, as well as the embedded flag
(indicating whether the payload is embedded or referenced). This function requires that
the variable is of type send_datatype, and that send_datatype is set to "Payload file",
rather than "Embedded payload".
C H R _API_R C
C H R _m group_get _pay l oad_ f i l e (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G v ariableN ame,
C H R _LEN GTH v ariableN ameLengt h,
C H R _STR I N G f ilename,
C H R _LEN GTH f ilenameMax Lengt h,
C H R _LEN GTH * f ilenameLengt h,
C H R _BOOLEAN * embedded
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

variableName [in]
A string containing the name of the send_datatype script variable that is used by the given
multicast group.

variableNameLength [in]
The length of the variable name, excluding the null terminator. This string is limited to 24
characters.

filename [out]
The buffer where the name of the payload file will be returned.

filenameMaxLength [in]
The length of the provided buffer.

filenameLength [out]
A pointer to the variable where the length of the payload file name is returned, expressed
in bytes.

embedded [out]
A pointer to the Boolean variable where the embedded payload flag is returned. The values
for the flag are:

- 362 -

IxChariot APIGuide

CHR_TRUE: The payload file is embedded within the script.

CHR_FALSE: The script contains a reference to the external file.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NO_SCRIPT_IN_USE

CHR_BUFFER_TOO_SMALL

CHR_STRING_TOO_LONG

See Return Code Summar for a detailed description of each return code.

- 363 -

IxChariot APIGuide

CHR_mgroup_get_protocol
DESCRIPTION
The CHR_mgroup_get_protocol function gets the Endpoint 1 to Endpoint 2 protocol for the
given multicast group.
C H R _API_R C
C H R _m group_get _prot oc ol (
C H R _MGR OU P_H AN D LE mgroup,
C H R _PR OTOC OL* prot oc ol
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

protocol [out]
A pointer to the variable where the protocol is returned. See the CHR_mgroup_set_protocol function for applicable protocols.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 364 -

IxChariot APIGuide

CHR_mgroup_get_qos_name
DESCRIPTION
The CHR_mgroup_get_qos_name function gets the quality of service name for the given
multicast group.
C H R _API_R C
C H R _m group_get _qos _nam e(
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

buf [out]
A pointer to the buffer where the quality of service name is returned.

len [in]
The length of the buffer, the maximum number of bytes that can be returned in the buffer,
excluding the null terminator.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 365 -

IxChariot APIGuide

CHR_mgroup_get_script_embedded_payload
DESCRIPTION
The CHR_mgroup_get_script_embedded_payload function gets the value of the embedded
payload data from the script used by this multicast group. This function requires that the
variable is of type send_datatype.
C H R _API_R C
C H R _m group_get _s c ri pt _ em bedded_pay l oad (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G v ariableN ame,
C H R _LEN GTH v ariableN ameLengt h,
C H R _STR I N G pay load,
C H R _LEN GTH pay loadMax Lengt h,
C H R _LEN GTH * pay loadLengt h
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

variableName [in]
A string containing the name of the send_datatype script variable that is used by the given
multicast group.

variableNameLength [in]
The length of the variable name, excluding the null terminator. This string is limited to 24
characters.

payload [out]
The buffer to which the embedded script payload is returned.

payloadMaxLength [in]
The length of the provided buffer.

payloadLength [out]
A pointer to the variable where the length of the payload is returned. The length of the payload is expressed in number of bytes.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:

- 366 -

IxChariot APIGuide

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NO_SCRIPT_IN_USE

CHR_BUFFER_TOO_SMALL

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 367 -

IxChariot APIGuide

CHR_mgroup_get_script_filename
DESCRIPTION
The CHR_mgroup_get_script_filename function gets the script filename for the given multicast group. The script filename is returned without path information.
C H R _API_R C
C H R _m group_get _s c ri pt _ f i l enam e(
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

buf [out]
A pointer to the buffer where the script filename is returned.

len[in]
The length of the buffer.

rtnlen[out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 368 -

IxChariot APIGuide

CHR_mgroup_get_script_variable
DESCRIPTION
The CHR_mgroup_get_script_variable function gets the value of a specified variable from
the script defined for use by the given multicast group.
C H R _API_R C
C H R _m group_get _s c ri pt _ v ari abl e (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G name,
C H R _LEN GTH nameLengt h,
C H R _STR I N G v alue,
C H R _LEN GTH v alueMax Lengt h,
C H R _LEN GTH * v alueLengt h
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

name [in]
A string containing the name of the script variable.

nameLength[in]
The length of the variable name, excluding the null terminator. This string is limited to 24
characters.

value [out]
The buffer to which the value of the script variable is returned.
The value is returned in the same format as for the set function (CHR_mgroup_set_script_
variable).

valueMaxLength [in]
The length of the provided buffer.

valueLength [out]
A pointer to the variable where the length of the variable value is returned. (The length
value excludes the null terminator.)

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:

- 369 -

IxChariot APIGuide

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NO_SCRIPT_IN_USE

CHR_BUFFER_TOO_SMALL

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 370 -

IxChariot APIGuide

CHR_mgroup_get_use_console_e1_values
DESCRIPTION
The CHR_mgroup_get_use_console_e1_values function gets whether the Console-to-Endpoint 1 values are to be used.
C H R _API_R C
C H R _m group_get _us e_c ons ol e_ e1_ v al ues (
C H R _MGR OU P_H AN D LE mgroup,
C H R _BOOLEAN * us e
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

use [out]
A pointer to the variable where the Boolean value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 371 -

IxChariot APIGuide

CHR_mgroup_is_disabled
DESCRIPTION
The CHR_mgroup_is_disabled function determines whether or not the pairs in the specified multicast group or video multicast group are disabled.
CHR_API_RC
CHR_mgroup_is_ disabled(
CHR_MGROUP_HANDLE mgroupHandle,
CHR_BOOLEAN* disabled
)

PARAMETERS
mgroupHandle [in]
A handle returned by any of the following functions: CHR_mgroup_new(),
CHR_video_mgroup_new(), or CHR_test_get_mgroup().

disabled [out]
A pointer to the variable where the Boolean value is returned. The returned values can be:
l

CHR_TRUE: All the pairs in the specified multicast group or video multicast group are
disabled.
CHR_FALSE: All the pairs in the specified multicast group or video multicast group
are enabled.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 372 -

IxChariot APIGuide

CHR_mgroup_is_udp_RFC768_streaming
DESCRIPTION
The CHR_ mgroup_is_udp_RFC768_streaming function determines whether or not the
RFC768 option is enabled in the script for the specified multicast group. If the option is
present in the script, and it is enabled, the function returns TRUE. In all other cases, it
returns FALSE.
This function should be called only for streaming scripts that use the UDP or UDPv6 protocol; otherwise it will return CHR_NO_SUCH_VALUE.
CHR_API_RC
CHR_mgroup_is_ udp_RFC768_streaming (
CHR_MGROUP_HANDLE mgroupHandle,
CHR_BOOLEAN* used
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_mpair_new() or CHR_mgroup_get_mpair().

used [out]
A pointer to the variable where the Boolean value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_API_NOT_INITIALIZED

CHR_NO_SUCH_VALUE

CHR_BUFFER_TOO_SMALL

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 373 -

IxChariot APIGuide

CHR_mgroup_new
DESCRIPTION
The CHR_mgroup_new function creates a new multicast group object and initializes it to
object default values. Note that the object default values do not use the default values specified in the Chariot Options Menu. See Multicast Group Object Default Values for the
object default values.
C H R _API_R C
C H R _m group_new (
C H R _MGR OU P_H AN D LE* mgroup
)

PARAMETERS
mgroup [out]
A pointer to the variable where the handle for the new multicast group is returned. The
handle returned by this function is needed for other function calls to operate on this object.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_OUT_OF_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 374 -

IxChariot APIGuide

CHR_mgroup_remove_mpair
DESCRIPTION
The function CHR_mgroup_remove_mpair removes a multicast pair from a multicast
group. The multicast group must be unowned or locked.
C H R _API_R C
C H R _ m g r o u p _r e m o v e _ m p a i r(
C H R _MGR OU P_H AN D LE mgroup,
C H R _MPAI R _H AN D LE mpair
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

mpair [in]
A handle returned by CHR_mpair_new().

RETURN CODES
The following return code indicates the function call was successful:
CHR_OK
The following return codes indicate an error occurred:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 375 -

IxChariot APIGuide

CHR_mgroup_set_comment
DESCRIPTION
The CHR_mgroup_set_comment function sets or changes the comment for the given multicast group.
C H R _API_R C
C H R _m group_s et _c om m ent (
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G c omment ,
C H R _LEN GTH len
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

comment [in]
A string containing the multicast group comment.

len [in]
The length of the comment string, excluding the null terminator. This string is limited to 64
characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 376 -

IxChariot APIGuide

CHR_mgroup_set_console_e1_addr
DESCRIPTION
The CHR_mgroup_set_console_e1_addr function sets or changes the address by which the
Console knows Endpoint 1 for the given multicast group. This attribute applies only when
the CHR_mgroup_set_use_console_e1_values function sets the "use" attribute to CHR_
TRUE.
C H R _API_R C
C H R _m group_s et _c ons ol e_ e1_ addr(
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G addr,
C H R _LEN GTH len
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

addr [in]
A string containing the endpoint address.

len [in]
The length of the address, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 377 -

IxChariot APIGuide

CHR_mgroup_set_console_e1_protocol
DESCRIPTION
The CHR_mgroup_set_console_e1_protocol function sets or changes the Console to Endpoint 1 network protocol for the given multicast group. This attribute applies only when the
CHR_mgroup_set_use_console_e1_values function sets the "use" attribute to CHR_TRUE.
C H R _API_R C
C H R _m group_s et _c ons ol e_ e1_ prot oc ol (
C H R _MGR OU P_H AN D LE mgroup,
C H R _PR OTOC OL prot oc ol
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

protocol [in]
A protocol type: CHR_PROTOCOL_TCP, CHR_PROTOCOL_TCP6, or CHR_PROTOCOL_SPX.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 378 -

IxChariot APIGuide

CHR_mgroup_set_console_e1_qos_name
DESCRIPTION
The CHR_mgroup_set_console_e1_qos_name function sets or changes the quality of service name for Console to Endpoint 1 for the given multicast group. This attribute applies
only when the CHR_mgroup_set_use_console_e1_values function sets the "use" attribute
to CHR_TRUE.
C H R _API_R C
C H R _m group_s et _c ons ol e_ e1_ qos _nam e(
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G qos ,
C H R _LEN GTH len
)
This function is applicable only to APPC. IxChariot 6.20 and higher no longer support APPC.

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

qos [in]
A string containing the quality of service name.

len [in]
The length of the quality of service name, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 379 -

IxChariot APIGuide

CHR_mgroup_set_e1_addr
DESCRIPTION
The CHR_mgroup_set_e1_addr function sets or changes the Endpoint 1 address for the
given multicast group.
C H R _API_R C
C H R _m group_s et _e1_ addr(
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G addr,
C H R _LEN GTH len
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

addr [in]
A string containing the Endpoint 1 address (IPv4 or IPv6).

len [in]
The length of the endpoint address string, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary on page A-1 for a detailed description of each return code.

- 380 -

IxChariot APIGuide

CHR_mgroup_set_script_embedded_payload
DESCRIPTION
The CHR_mgroup_set_script_embedded_payload function modifies the value of a send_
datatype variable in the script defined for use by the given multicast group. The type of
the variable is automatically set to "Embedded payload".
C H R _API_R C
C H R _m group_s et _s c ri pt _ v ari abl e(
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G v arname,
C H R _LEN GTH namelen,
C H R _STR I N G pay load,
C H R _LEN GTH pay loadLengt h
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

varname [in]
A string containing the name of the script variable.

namelen [in]
The length of the variable name, excluding the null terminator. This string is limited to 24
characters.

payload [in]
A pointer to the buffer that holds the payload.

payloadLength [in]
The length of the payload, in bytes.
Note that CHR_MAX_EMBEDDED_PAYLOAD_SIZE defines the maximum size permitted for
embedded payload.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

- 381 -

IxChariot APIGuide

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NO_SCRIPT_IN_USE

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

CHR_VALUE_INVALID

See Return Code Summary for a description of each return code.

- 382 -

IxChariot APIGuide

CHR_mgroup_set_lock
DESCRIPTION
The function CHR_mgroup_set_lock locks an unlocked multicast group object if lock is
CHR_TRUE, or unlocks a locked multicast group object if lock is CHR_FALSE. An owned
object must be locked--disabled for validation before any of its attributes can be modified
(using the set subcommand). To enable validation, all objects owned by a test (including
multicast pairs owned by the test's multicast groups) must be unlocked before the test can
be run or saved.
When an attempt is made to unlock a locked multicast group object, the object is validated. If the object is found to be invalid, an error is returned and the object remains
locked.
When an attempt is made to unlock an invalid multicast group object, CHR_OBJECT_
INVALID is returned. In addition, extended error information is always returned, providing
details of why the operation failed or how the object is invalid. Use CHR_common_error_
get_info to get this extended error information, and refer to Common Error Functions for
more information.
A multicast group object can't be locked if it's contained by a test object that has results or
is running. If you attempt to lock a multicast group object that is already locked, the multicast group object remains locked.
A multicast group object that is contained by a test object must be locked before any of its
attributes (such as its endpoint address) can be set.
C H R _API_R C
C H R _m group_s et _l oc k (
C H R _MGR OU P_H AN D LE mgroup,
C H R _BOOLEAN loc k
)

PARAMETERS
mgroup [in]
A handle returned by CHR_pair_mgroup() or CHR_test_get_mgroup.

lock [in]
A CHR_BOOLEAN, where CHR_TRUE locks the (unlocked) multicast group object, and CHR_
FALSE unlocks the (locked) object.

RETURN CODES
The following return code indicates the function call was successful:
CHR_OK
The following return codes indicate an error occurred:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

- 383 -

IxChariot APIGuide

CHR_NO_MEMORY

CHR_OBJECT_INVALID

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 384 -

IxChariot APIGuide

CHR_mgroup_set_multicast_addr
DESCRIPTION
The CHR_mgroup_set_multicast_addr function sets or changes the multicast IP address for
the given multicast group.
C H R _API_R C
C H R _m group_s et _m ul t i c as t _ addr(
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G addr,
C H R _LEN GTH len
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

addr [in]
A string containing the multicast IP address.
For IPv4, the range of valid addresses is 224.0.0.0 to 239.255.255.255.
For IPv6, multicast addresses have a prefix of FF00::/8 (address range of FF00:: to
FF0F::). The addresses listed in the following table are assigned to specific functions:
Ran ge

U sage

FF01::1

Al l nodes wi thi n the node- l ocal scope.

FF02::1

Al l nodes on the l ocal l i nk.

FF01::2

Al l r outer s wi thi n the node- l ocal scope.

FF02::2

Al l r outer s on the l i nk- l ocal scope.

FF05::2

Al l r outer s i n the si te.

FF02::1:FFXX:XXXX

Sol i ci ted-node mul ti cast addr ess, wher e

XX:XXXX r epr esents the l ast 24 bi ts of the
I Pv6 addr ess of the node

len [in]
The length of the endpoint address string, excluding the null terminator. This string is limited to 15 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

- 385 -

IxChariot APIGuide

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_STRING_TOO_LONG

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 386 -

IxChariot APIGuide

CHR_mgroup_set_multicast_port
DESCRIPTION
The CHR_mgroup_set_multicast_port function sets or changes the multicast port number
for the given multicast group.
C H R _API_R C
C H R _m group_s et _m ul t i c as t _ port (
C H R _MGR OU P_H AN D LE mgroup,
C H R _POR T port
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

port [in]
A multicast port number. The range of valid port numbers is 1 to 65535.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 387 -

IxChariot APIGuide

CHR_mgroup_set_name
DESCRIPTION
The CHR_mgroup_set_name function sets or changes the name of the given multicast
group.
C H R _API_R C
C H R _m group_s et _nam e(
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G name,
C H R _LEN GTH len
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

name [in]
A string containing the name for the multicast group.

len [in]
The length of the name string, excluding the null terminator. This string is limited to 64
characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 388 -

IxChariot APIGuide

CHR_mgroup_set_payload_file
DESCRIPTION
The CHR_mgroup_set_payload_file function modifies the value of a send_datatype variable in the script defined for use by the given multicast group. It allows a user to specify a
file whose content will be used as payload when running the script. This function sets the
variable type to "Embedded payload" as well.
C H R _API_R C
C H R _m group_s et _pay l oad_ f i l e(
C H R _MGR OU P_H AN D LE mgroupH andle,
C H R _STR I N G v arN ame,
C H R _LEN GTH v arN ameLengt h,
C H R _STR I N G f ilename,
C H R _LEN GTH f ilenameLengt h,
C H R _BOOLEAN embedded,
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

varName [in]
A string containing the name of a send_datatype script variable.
A script must be defined for use by the given multicast group. The script variable name is
checked to ensure that it exists and is of type send_datatype. CHR_NO_SUCH_OBJECT is
returned if the variable does not exist in the script, and CHR_VALUE_INVALID will be
returned if the variable is not of type send_datatype.

varNameLength [in]
The length of the variable name, excluding the null terminator. This string is limited to 24
characters.

filename [in]
The name of the file containing the payload data.

filenameLength [in]
The length of the filename parameter.
The filenameLength parameter needs to be between 1 and 24, inclusive; otherwise, CHR_
VALUE_INVALID will be returned. If the specified file does not exit, CHR_OPERATION_
FAILED will be returned. If the file size is greater than 1 billion bytes (953MB), CHR_
PAYLOAD_FILE_TOO_LARGE will be returned.

embedded [in]
If set to CHR_TRUE, the payload file will be embedded within the script. If set to CHR_
FALSE, the script will contain a reference to the external file. The recommended option is

- 389 -

IxChariot APIGuide
CHR_TRUE.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NO_SCRIPT_IN_USE

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 390 -

IxChariot APIGuide

CHR_mgroup_set_protocol
DESCRIPTION
The CHR_mgroup_set_protocol function sets or changes the Endpoint 1 to Endpoint 2 protocol for the given multicast group.
C H R _API_R C
C H R _mgoup_s et _prot oc ol(
C H R _MGR OU P_H AN D LE mgroup,
C H R _PR OTOC OL prot oc ol
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

protocol [in]
A protocol type: CHR_PROTOCOL_UDP,CHR_PROTOCOL_UDP6, CHR_PROTOCOL_RTP, or
CHR_PROTOCOL_RTP6.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 391 -

IxChariot APIGuide

CHR_mgroup_set_qos_name
DESCRIPTION
The CHR_mgroup_set_qos_name function sets or changes the quality of service name for
the given multicast group.
C H R _API_R C
C H R _m group_s et _qos _nam e(
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G qos ,
C H R _LEN GTH len
)Paramet ers

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

qos [in]
A string containing quality of service name.

len [in]
The length of the quality of service name, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 392 -

IxChariot APIGuide

CHR_mgroup_set_script_variable
DESCRIPTION
The CHR_mgroup_set_script_variable function modifies the value of a variable in the script
defined for use by the given multicast group. The script variable name is checked to
ensure that it exists in the defined script. CHR_NO_SUCH_OBJECT is returned if the variable does not exist in the script. The variable value is checked to ensure that it is valid for
that variable in that script.
C H R _API_R C
C H R _m group_s et _s c ri pt _ v ari abl e(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G name,
C H R _LEN GTH nameLengt h,
C H R _STR I N G v alue,
C H R _LEN GTH v alueLengt h
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

name [in]
A string containing the name of the script variable.

nameLength[in]
The length of the variable name, excluding the null terminator. This string is limited to 24
characters.

value [in]
A string containing the value for the script variable. Use the following table to determine
the valid string entries:
Ty pe of
v ariable

close_type

Allowed valu es

"Reset" (default)
"Normal"
"0" - "2147483647"

Integer

Option:
nagle_
algorithm_e1
nagle_

For send or receive buffer sizes, "default" instructs IxChariot to automatically select the default buffer size for the protocol and platform on
which it is running.
Enabled by default.
"enabled"
"disabled"

- 393 -

IxChariot APIGuide

Ty pe of
v ariable

Allowed valu es

algorithm_e2
udp_checksum_e1
udp_checksum_e2
Port Number:
source_port
destination_
port

"0" - "65535" or " auto." Specifying a port number of zero instructs

IxChariot to automatically select the port.

An integer (constant). This variable specifies the number pf bytes to send

Send Data
with each SEND command.
Size: file_size
SEND/RECEIVE
Buffer Size:
An integer (constant) between 1 and 2147483647, or a Random value
expressed as "d[x,y]", where:
send_buffer_
size
d=u (uniform), n (normal), p (poisson), or e (exponential) and
receive_buffer_size
Transaction
Count:
transactions_
per_record
Timing
records:

x,y = integers between "0" and "2147483647", where x<y

An integer (constant) minimum value is 1. This variable controls the number of transactions that will be run for each timing record. Setting it to 1
causes each transaction to have its own timing record.

An integer (constant).

number-of_tim-An endpoint creates a timing record each time it goes through a loop.
ing_records
The word unlimited or a data rate expressed as: xxxxxx[.yyy] units
There must not be more than six x's to the left of the decimal and no more
than three y's to the right of the decimal point.
Data rate:
send_data_
rate

Units should be one of:

KB, Kb, kB, kb - 1024 bytes per second
Mb 1,000,000 bytes per second
Gb 1,000,000,000 bytes per second
The data rate may not be 0.0.
Def aul t Data:

Data Type:
s e n d _d a t a type
Opti onal Data:

ZEROS, NOCOMPRESS, news.cmp, lena cmp,

trans.cmp
bib.cmp, book1.cmp, book2.cmp, geo.cmp,
paper1.cmp, paper2.cmp, pic.cmp, progc.cmp, progl.cmp, progp.cmp, userxx.cmp
(where xx is between 01 and 10)

- 394 -

IxChariot APIGuide

Ty pe of
v ariable

Allowed valu es

Embedded Payl oad:

Embedded payload. The value of the embedded payload must be set using the CHR_
mgroup_set_script_embedded_payload function.

Ref er enced or
Embedded Payl oad
File:

A large payload file either referenced or

embedded. The value of the payload file
must be set using the CHR_mgroup_set_payload_file function.

valueLength [in]
The length of the variable value, excluding the null terminator.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NO_SCRIPT_IN_USE

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 395 -

IxChariot APIGuide

CHR_mgroup_set_use_console_e1_values
DESCRIPTION
The CHR_mgroup_set_use_console_e1_values function sets or changes whether the Console-to-Endpoint 1 values are to be used. If the value is set to CHR_TRUE, the Console to
Endpoint 1 address and Console to Endpoint 1 Quality Of Service name must be properly
defined before the test is run. The Console to Endpoint 1 protocol defaults to TCP and may
be changed if needed.
C H R _API_R C
C H R _ m group_ s et _ us e_ c ons ol e_ e1_v al ues (
C H R _MGR OU P_H AN D LE mgroup,
C H R _BOOLEAN us e
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

use [in]
Specifies CHR_TRUE or CHR_FALSE to indicate whether the Console-to-Endpoint 1 values
are to be used.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 396 -

IxChariot APIGuide

CHR_mgroup_use_script_filename
DESCRIPTION
The CHR_mgroup_use_script_filename function sets or changes the script file to be used
by the given multicast group.
C H R _API_R C
C H R _m group_us e_s c ri pt _ f i l enam e(
C H R _MGR OU P_H AN D LE mgroup,
C H R _STR I N G s c ript ,
C H R _C OU N T s c ript len
)

PARAMETERS
mgroup [in]
A handle returned by CHR_mgroup_new() or CHR_test_get_mgroup().

script [in]
A string containing the new script filename. The script filename may be specified with a
full or relative pathname.

scriptlen [in]
The length of the script filename string, excluding the null terminator. The maximum
length of the script filename is 1023.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OPERATION_FAILED*

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_VALUE_INVALID

CHR_OBJECT_IN_USE
Use CHR_common_error_get_info to get the extended error information available for this return code.

See Return Code Summary for a detailed description of each return code.

- 397 -

IxChariot APIGuide

Multicast Pair Object Functions

The multicast pair object functions are used to define multicast group members and
retrieve information about a multicast pair. You cannot set any multicast pair information
for a multicast pair that is owned by multicast group.

- 398 -

IxChariot APIGuide

CHR_mpair_delete
DESCRIPTION
The CHR_mpair_delete function frees all memory associated with the given multicast pair.
C H R _API_R C
C H R _mpair_delet e(
C H R _MPAI R _H AN D LE mpair
)

PARAMETERS
mpair [in]
A handle returned by CHR_mpair_new() or CHR_mgroup_get_mpair(). After verifying that
the handle refers to a multicast pair object, it is checked to ensure that it is not referenced
by a multicast object known by the API. The multicast pair object cannot be deleted if it is
referenced.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 399 -

IxChariot APIGuide

CHR_mpair_get_e2_addr
DESCRIPTION
The CHR_mpair_get_e2_addr function gets the Endpoint 2 address for the given multicast
pair.
C H R _API_R C
C H R _ m pai r_ get _ e2_addr(
C H R _MPAI R _H AN D LE mpair ,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
mpair [in]
A handle returned by CHR_mpair_new() or CHR_mgroup_get_mpair().

buf [out]
A pointer to the buffer where the Endpoint 2 address is returned.

len [in]
The length of the buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 400 -

IxChariot APIGuide

CHR_mpair_get_e2_config_value
DESCRIPTION
The CHR_mpair_get_e2_config_value function gets an Endpoint 2 configuration value from
the multicast pair. The configuration information is returned from the endpoint during test
execution.
C H R _API_R C
C H R _ m p a i r_ g e t _ e 2 _c o n f i g _ v a l u e(
C H R _MPAI R _H AN D LE mpair ,
CHR_CFG_PARM v alue,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
mpair [in]
A handle returned by CHR_mpair_new() or CHR_mgroup_get_mpair().

value [in]
One of the CHR_CFG_PARM values. See Typedefs and Enumerations on page 4-616 for
CHR_CFG_PARM values.

buf [out]
A pointer to the buffer where the endpoint configuration value is returned.

len [in]
The length of the buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

- 401 -

IxChariot APIGuide

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 402 -

IxChariot APIGuide

CHR_mpair_get_runStatus
DESCRIPTION
The CHR_mpair_get_runStatus function returns the run status for this multicast pair.
C H R _API_R C
C H R _mpair_get _runSt at us(
C H R _MPAI R _H AN D LE mpairH andle,
C H R _PAI R _R U N STATU S_TYPE *runSt at us
)

PARAMETERS
mpairHandle [in]
A multicast pair object handle returned by CHR_mpair_new() or CHR_mgroup_get_mpair
().

runStatus [out]
A pointer to the variable where the run status value is returned. The following status types
are applicable:
l

CHR_PAIR_RUNSTATUS_UNINITIALIZED

CHR_PAIR_RUNSTATUS_INITIALIZING_1

CHR_PAIR_RUNSTATUS_INITIALIZING_2

CHR_PAIR_RUNSTATUS_INITIALIZING_3

CHR_PAIR_RUNSTATUS_INITIALIZED

CHR_PAIR_RUNSTATUS_RUNNING

CHR_PAIR_RUNSTATUS_STOPPING

CHR_PAIR_RUNSTATUS_REQUESTED_STOP

CHR_PAIR_RUNSTATUS_ERROR

CHR_PAIR_RUNSTATUS_RESOLVING_NAMES

CHR_PAIR_RUNSTATUS_POLLING

CHR_PAIR_RUNSTATUS_FINISHED

CHR_PAIR_RUNSTATUS_REQUESTING_STOP

CHR_PAIR_RUNSTATUS_FINISHED_WARNINGS

CHR_PAIR_RUNSTATUS_TRANSFERRING_PAYLOAD

CHR_PAIR_RUNSTATUS_APPLYING_IXIA_CONFIG

CHR_PAIR_RUNSTATUS_WAITING_FOR_REINIT

CHR_PAIR_RUNSTATUS_ABANDONED

See also typedef char CHR_PAIR_RUNSTATUS_TYPE, listed in Typedefs and Enumerations.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK

- 403 -

IxChariot APIGuide
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

* Use CHR_common_error_get_info to get the extended error information available for

this return code.

- 404 -

IxChariot APIGuide

CHR_mpair_get_setup_e1_e2_addr
DESCRIPTION
The CHR_mpair_get_setup_e1_e2_addr function gets the address by which Endpoint 1
knows Endpoint 2 for purposes of test setup. This attribute applies only when the CHR_
mpair_set_use_setup_e1_e2_values function sets the "use" attribute to CHR_TRUE.
CHR_API_RC
CHR_mpair_get_setup_e1_e2_ addr(
CHR_MPAIR_HANDLE mpair,
CHR_STRING buf,
CHR_LENGTH len,
CHR_LENGTH* rtnlen
)

PARAMETERS
mpair [in]
A handle returned by CHR_mpair_new() or CHR_mgroup_get_mpair().

buf [out]
A pointer to the buffer where the address is returned.

len [in]
The length of the given buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminatorlike strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 405 -

IxChariot APIGuide

CHR_mpair_get_timing_record
DESCRIPTION
The CHR_mpair_get_timing_record function gets the handle for the specified timing record
from the results for the given multicast pair. The handle returned by this function is
needed for other function calls to operate on this object.
C H R _API_R C
C H R _m pai r_get _t i m i ng_rec ord(
C H R _MPAI R _H AN D LE mpair,
C H R _C OU N T num,
C H R _TI MI N GR EC _H AN D LE* t imingrec
)

PARAMETERS
mpair [in]
A handle returned by CHR_mpair_new() or CHR_mgroup_get_mpair().

num [in]
The number indicating a specific timing record. The number is determined by the order in
which timing records were received from the endpoints.

timingrec [out]
A pointer to the variable where the handle of the timing record is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 406 -

IxChariot APIGuide

CHR_mpair_get_timing_record_count
DESCRIPTION
The CHR_mpair_get_timing_record_count function gets the number of timing records in
the results for the given multicast pair.
C H R _API_R C
C H R _m pai r_get _t i m i ng_rec ord_ c ount (
C H R _MPAI R _H AN D LE mpair,
C H R _C OU N T* num
)

PARAMETERS
mpair [in]
A handle returned by CHR_mpair_new() or CHR_mgroup_get_mpair().

num [out]
A pointer to the variable where the number of timing records is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 407 -

IxChariot APIGuide

CHR_mpair_get_use_setup_e1_e2_values
DESCRIPTION
The CHR_mpair_get_use_setup_e1_e2_values function gets whether to use the values by
which Endpoint 1 knows Endpoint 2 for purposes of test setup.
CHR_API_RC
CHR_mpair_get_use_setup_e1_e2_ values(
CHR_MPAIR_HANDLE mpair,
CHR_BOOLEAN* use
)

PARAMETERS
mpair [in]
A handle returned by CHR_mpair_new() or CHR_mgroup_get_mpair().

use [out]
A pointer to the variable where the Boolean value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 408 -

IxChariot APIGuide

CHR_mpair_new
DESCRIPTION
The CHR_mpair_new function creates a multicast pair. See the Multicast Pair Object Functionsfor more information.
The handle returned by this function is needed for other function calls to operate on this
object.
C H R _API_R C
C H R _mpair_new(
C H R _MPAI R _H AN D LE* mpair
)

PARAMETERS
mpair [out]
A pointer to the variable where the handle for the new pair is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_OUT_OF_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 409 -

IxChariot APIGuide

CHR_mpair_set_e2_addr
DESCRIPTION
The CHR_mpair_set_e2_addr function sets or changes the address for Endpoint 2 in the
given multicast pair.
C H R _API_R C
C H R _ m pai r_ s et _ e2_addr(
C H R _MPAI R _H AN D LE mpair,
C H R _STR I N G addr,
C H R _LEN GTH len
)

PARAMETERS
mpair [in]
A handle returned by CHR_mpair_new() or CHR_mgroup_get_mpair().

addr [in]
A string containing the address for Endpoint 2.

len [in]
The length of the endpoint address string, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 410 -

IxChariot APIGuide

CHR_mpair_set_lock
DESCRIPTION
The function CHR_mpair_set_lock locks an unlocked multicast pair object if lock is CHR_
TRUE, or unlocks a locked multicast pair object if lock is CHR_FALSE. An owned object
must be locked--disabled for validation--before any of its attributes can be modified (using
the set subcommand). To enable validation, all objects owned by a test (including multicast pairs owned by the test's multicast groups) must be unlocked before the test can be
run or saved.
When an attempt is made to unlock a locked multicast group object, the object is validated. If the object is found to be invalid, an error is returned and the object remains
locked.
When an attempt is made to unlock an invalid multicast group object, CHR_OBJECT_
INVALID is returned. In addition, extended error information is always returned, providing
details of why the operation failed or how the object is invalid. Use CHR_common_error_
get_info to get this extended error information, and refer to Common Error Functions for
more information.
A multicast pair object can't be locked if it's contained by a multicast group object that is in
turn contained by a test object that has results or is running. If you attempt to lock a multicast pair object that is already locked, the multicast pair object remains locked.
A multicast pair object that is contained by a multicast group object must be locked before
any of its attributes (such as its endpoint address) can be set.
CHR_API_RC
CHR_mpair_set_lock(
CHR_MPAIR_HANDLE mpair,
CHR_BOOLEAN lock
)

PARAMETERS
mpair [in]
A handle returned by CHR_mpair_new() or CHR_mgroup_get_mpair.

lock [in]
A CHR_BOOLEAN, where CHR_TRUE locks the (unlocked) multicast pair object, and CHR_
FALSE unlocks the (locked) object.

RETURN CODES
The following return code indicates the function call was successful:
CHR_OK
The following return codes indicate an error occurred:
l

CHR_API_NOT_INITIALIZED

- 411 -

IxChariot APIGuide

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_INVALID

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 412 -

IxChariot APIGuide

CHR_mpair_set_setup_e1_e2_addr
DESCRIPTION
The CHR_mpair_set_setup_e1_e2_addr function sets the address by which Endpoint 1
knows Endpoint 2 for purposes of test setup. This attribute applies only when the CHR_
mpair_set_use_setup_e1_e2_values function sets the "use" attribute to CHR_TRUE.
CHR_API_RC
CHR_mpair_set_setup_e1_e2_ addr(
CHR_MPAIR_HANDLE mpair,
CHR_STRING addr,
CHR_LENGTH len
)

PARAMETERS
mpair [in]
A handle returned by CHR_mpair_new() or CHR_mgroup_get_mpair().

addr [in]
A string containing the address.

len [in]
The length of the address, excluding the null terminator. The string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALIDCHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 413 -

IxChariot APIGuide

CHR_mpair_set_use_setup_e1_e2_values
DESCRIPTION
The CHR_mpair_set_use_setup_e1_e2_values function sets or changes whether the values
by which Endpoint 1 knows Endpoint 2 for purposes of test setup should be used. If this
value is set to CHR_TRUE, the Pair Setup Endpoint 1 to Endpoint 2 address must be properly defined before the test is run. The Pair Setup Endpoint 1 to Endpoint 2 protocol is automatically set to TCP and cannot be changed.
CHR_API_RC
CHR_mpair_set_use_setup_e1_e2_ values(
CHR_MPAIR_HANDLE mpair,
CHR_BOOLEAN use
)

PARAMETERS
mpair [in]
A handle returned by CHR_mpair_new() or CHR_mgroup_get_mpair().

use [in]
Specifies CHR_TRUE or CHR_FALSE to indicate whether to use the Endpoint 1 to Endpoint 2
test setup values.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_OBJECT_IN_USE

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 414 -

IxChariot APIGuide

Pair Object Functions

Pair object functions are used to define pairs for a test and retrieve information about an
endpoint pair. You are not allowed to set any pair information for a pair that is owned by a
test.
Some functions apply to VoIP pairs; see VoIP Pair Object for more information.

- 415 -

IxChariot APIGuide

CHR_pair_copy
DESCRIPTION
The CHR_pair_copy function copies the attributes of the source endpoint pair or hardware
performance pair to the destination endpoint pair. The destination endpoint pair must not
yet be owned by a test. Only the attributes of the endpoint pair are copied from the source
to the destination. This does not include any results information.
C H R _API_R C
C H R _ pai r_c opy (
C H R _PAI R _H AN D LE des t ,
C H R _PAI R _H AN D LE s rc
)
For an endpoint pair, the attributes that are copied are the following:
l

appl_script_name

comment

console_e1_addr

console_e1_protocol

console_e1_qos_name

e1_addr

e2_addr

protocol

qos_name

script_filename (and script values)

use_console_e1_values

For a hardware performance pair, the attributes that are copied are the following:
l

appl_script_name

comment

console_e1_addr

e1_addr

e2_addr

script_filename

line_rate

measure_statistics

PARAMETERS
dest [in]
A handle of the destination pair object, returned by CHR_pair_new().

src [in]
A handle of the source pair object, returned by CHR_pair_new() or CHR_test_get_pair().

- 416 -

IxChariot APIGuide

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 417 -

IxChariot APIGuide

CHR_pair_delete
DESCRIPTION
The CHR_pair_delete function frees all memory associated with the given endpoint pair or
hardware performance pair.
C H R _API_R C
C H R _ pai r_del et e(
C H R _PAI R _H AN D LE pair
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair(). After verifying that the
handle refers to an endpoint pair object, it is checked to ensure that it is not referenced by
a test object known by the API. The endpoint pair object cannot be deleted if it is contained
by a test object.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 418 -

IxChariot APIGuide

CHR_pair_disable
DESCRIPTION
The CHR_pair_disable function disables or enables the specified pair for the test.
IxChariot ignores any disabled pairs when running a test. You can use this function for any
of the following pair types: regular pairs, Hardware Performance Pairs, VoIP pairs, VoIP
Hardware Performance Pairs, and video pairs. However, this function is not valid for pairs
within application groups.
CHR_API_RC
CHR_pair_disable (
CHR_PAIR_HANDLE pairHandle,
CHR_BOOLEAN
disable
)

PARAMETERS
pairHandle [in]
A handle returned by any of the following functions:
l

CHR_test_get_pair()

CHR_pair_new()

CHR_hardware_pair_new()

CHR_voip_pair_new()

CHR_video_pair_new()

disable [in]
Specifies the action to perform:
l

CHR_TRUE: Disable the pair for the test.

CHR_FALSE: Enable the pair for the test.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_API_NOT_INITIALIZED

CHR_VALUE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 419 -

IxChariot APIGuide

CHR_pair_get_appl_script_name
DESCRIPTION
The CHR_pair_get_appl_script_name function gets the application script name for the
given endpoint pair. This function is not available for a voice over IP (VoIP) pair.
C H R _API_R C
C H R _ pai r_get _appl _ s c ri pt _nam e(
C H R _PAI R _H AN D LE pair,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

buf [out]
A pointer to the buffer where the script name is returned.

len [in]
The length of the provided buffer.

rtnlen[out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 420 -

IxChariot APIGuide

CHR_pair_get_comment
DESCRIPTION
The CHR_pair_get_comment function gets the comment for the given endpoint pair or hardware performance pair.
C H R _API_R C
C H R _ pai r_get _c om m ent (
C H R _PAI R _H AN D LE pair,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

buf [out]
A pointer to the buffer where the comment is returned.

len [in]
The length of the given buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 421 -

IxChariot APIGuide

CHR_pair_get_console_e1_addr
DESCRIPTION
The CHR_pair_get_console_e1_addr function gets the address by which the Console knows
Endpoint 1 for the given endpoint pair or hardware performance pair. This attribute applies
only when the CHR_pair_set_use_console_e1_values function sets the "use" attribute to
CHR_TRUE.
C H R _API_R C
C H R _ pai r_get _c ons ol e_ e1_ addr(
C H R _PAI R _H AN D LE pair,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

buf [out]
A pointer to the buffer where the address is returned.

len [in]
The length of the given buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 422 -

IxChariot APIGuide

CHR_pair_get_console_e1_protocol
DESCRIPTION
The CHR_pair_get_console_e1_protocol function gets the Console to Endpoint 1 network
protocol for the given endpoint pair. This attribute applies only when the CHR_pair_set_
use_console_e1_values function sets the "use" attribute to CHR_TRUE.
C H R _API_R C
C H R _ pai r_get _c ons ol e_ e1_ prot oc ol (
C H R _PAI R _H AN D LE pair,
C H R _PR OTOC OL* prot o
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

proto [out]
A pointer to the variable where the protocol is returned. See CHR_mgroup_set_console_
e1_protocol for information on applicable protocols.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 423 -

IxChariot APIGuide

CHR_pair_get_console_e1_qos_name
DESCRIPTION
The CHR_pair_get_console_e1_qos_name function gets the service quality name for Console to Endpoint 1 for the given endpoint pair. This attribute applies only when the CHR_
pair_set_use_console_e1_values function sets the "use" attribute to CHR_TRUE.
C H R _API_R C
C H R _ pai r_get _c ons ol e_ e1_ qos _ nam e(
C H R _PAI R _H AN D LE pair,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)
This function is applicable only to APPC. IxChariot 6.20 and higher no longer support APPC.

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

buf [out]
A pointer to the buffer where the service quality name is returned.

len [in]
The length of the provided buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 424 -

IxChariot APIGuide

- 425 -

IxChariot APIGuide

CHR_pair_get_e1_addr
DESCRIPTION
The CHR_pair_get_e1_addr function gets the Endpoint 1 address for the given endpoint
pair or hardware performance pair.
C H R _API_R C
C H R _ pai r_get _e1_ addr(
C H R _PAI R _H AN D LE pair,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

buf [out]
A pointer to the buffer where the Endpoint 1 address is returned.

len [in]
The length of the provided buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 426 -

IxChariot APIGuide

CHR_pair_get_e1_config_value
DESCRIPTION
The CHR_pair_get_e1_config_value function gets an Endpoint 1 configuration value from
the pair. The configuration information is returned from the endpoint during test execution.
C H R _API_R C
C H R _ pai r_get _e1_ c onf i g_v al ue (
C H R _PAI R _H AN D LE mpair ,
CHR_CFG_PARM v alue,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

value [in]
One of the CHR_CFG_PARM values. See Typedefs and Enumerations on page 4-616 or
CHR_CFG_PARM values.

buf [out]
A pointer to the buffer where the endpoint configuration value is returned.

len [in]
The length of the buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_VALUE

- 427 -

IxChariot APIGuide

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 428 -

IxChariot APIGuide

CHR_pair_get_e2_addr
DESCRIPTION
The CHR_pair_get_e2_addr function gets the Endpoint 2 address for the given endpoint
pair or hardware performance pair.
C H R _API_R C
C H R _ pai r_get _e2_ addr(
C H R _PAI R _H AN D LE pair,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

buf [out]
A pointer to the buffer where the Endpoint 2 address is returned.

len [in]
The length of the provided buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 429 -

IxChariot APIGuide

CHR_pair_get_e2_config_value
DESCRIPTION
The CHR_pair_get_e2_config_value function gets an Endpoint 2 configuration value from
the pair. The configuration information is returned from the endpoint during test execution.
C H R _API_R C
C H R _ pai r_get _e2_ c onf i g_v al ue (
C H R _PAI R _H AN D LE mpair ,
CHR_CFG_PARM v alue,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

value [in]
One of the CHR_CFG_PARM values. See Typedefs and Enumerations on page 4-616 for
CHR_CFG_PARM values.

buf [out]
A pointer to the buffer where the endpoint configuration value is returned.

len [in]
The length of the buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_VALUE

- 430 -

IxChariot APIGuide

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 431 -

IxChariot APIGuide

CHR_pair_get_payload_file
DESCRIPTION
The CHR_pair_get_payload_file function gets the name of the payload file that is defined
for the script used by the given endpoint pair, as well as the embedded flag (indicating
whether the payload is embedded or referenced). This function requires that the variable
is of type send_datatype, and that send_datatype is set to "Payload file", rather than
"Embedded payload".
C H R _API_R C
C H R _ pai r_get _pay l oad_ f i l e (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G v ariableN ame,
C H R _LEN GTH v ariableN ameLengt h,
C H R _STR I N G f ilename,
C H R _LEN GTH f ilenameMax Lengt h,
C H R _LEN GTH * f ilenameLengt h,
C H R _BOOLEAN * embedded
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

variableName [in]
A string containing the name of the send_datatype script variable that is used by the given
endpoint pair.

variableNameLength [in]
The length of the variable name, excluding the null terminator. This string is limited to 24
characters.

filename [out]
The buffer containing the name of the payload file.

filenameMaxLength [in]
The length of the provided buffer.

filenameLength [out]
A pointer to the variable where the length of the payload file name is returned, expressed
in number of bytes.

embedded [out]
A pointer to the Boolean variable where the embedded payload flag is returned. The values
for the flag are:

- 432 -

IxChariot APIGuide

CHR_TRUE: The payload file is embedded within the script.

CHR_FALSE: The script contains a reference to the external file.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NO_SCRIPT_IN_USE

CHR_BUFFER_TOO_SMALL

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 433 -

IxChariot APIGuide

CHR_pair_get_protocol
DESCRIPTION
The CHR_pair_get_protocol function gets the Endpoint 1 to Endpoint 2 network protocol for
the given endpoint pair.
C H R _API_R C
C H R _pair_get _prot oc ol(
C H R _PAI R _H AN D LE pair,
C H R _PR OTOC OL* prot oc ol
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

protocol [out]
A pointer to the variable where the protocol is returned. See the CHR_pair_set_protocol
function for applicable protocols.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 434 -

IxChariot APIGuide

CHR_pair_get_qos_name
DESCRIPTION
The CHR_pair_get_qos_name function returns the endpoint 1 service quality template.
This function is equivalent to CHR_pair_get_e1_qos_name and is kept for compatibility reasons.
C H R _API_R C
C H R _ pai r_get _qos _ nam e(
C H R _PAI R _H AN D LE pair,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

buf [out]
A pointer to the buffer where the service quality name is returned.

len [in]
The length of the provided buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 435 -

IxChariot APIGuide

CHR_pair_get_e1_qos_name
DESCRIPTION
The CHR_pair_get_e1_qos_name function gets the service quality name for Endpoint 1 in
the pair.
C H R _API_R C
C H R _ pai r_get _e1_ qos _ nam e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G qos N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h

PARAMETERS
pairHandle [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

qosName [out]
A pointer to the buffer where the service quality of name is returned.

maxLength [in]
The length of the provided buffer.

length[out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 436 -

IxChariot APIGuide

CHR_pair_get_e2_qos_name
DESCRIPTION
The CHR_pair_get_e2_qos_name function gets the service quality name for Endpoint 2 in
the pair, where it exists.
C H R _API_R C
C H R _ pai r_get _e2_ qos _ nam e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G qos N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h)

PARAMETERS
pairHandle [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

qosName [out]
A pointer to the buffer where the service quality of name is returned.

maxLength [in]
The length of the provided buffer.

length[out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 437 -

IxChariot APIGuide

CHR_pair_get_runStatus
DESCRIPTION
The CHR_pair_get_runStatus function gets the status of an endpoint pair or hardware performance pair during a test run.
C H R _API_R C
C H R _ pai r_get _runS t at us (
C H R _PAI R _H AN D LE pair,
C H R _PAI R _R U N STATU S_TYPE * runSt at us
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

runStatus [out]
A pointer to the variable where the run status is returned. The following status types are
applicable:
l

CHR_PAIR_RUNSTATUS_UNINITIALIZED

CHR_PAIR_RUNSTATUS_INITIALIZING_1

CHR_PAIR_RUNSTATUS_INITIALIZING_2

CHR_PAIR_RUNSTATUS_INITIALIZING_3

CHR_PAIR_RUNSTATUS_INITIALIZED

CHR_PAIR_RUNSTATUS_RUNNING

CHR_PAIR_RUNSTATUS_STOPPING

CHR_PAIR_RUNSTATUS_REQUESTED_STOP

CHR_PAIR_RUNSTATUS_ERROR

CHR_PAIR_RUNSTATUS_RESOLVING_NAMES

CHR_PAIR_RUNSTATUS_POLLING

CHR_PAIR_RUNSTATUS_FINISHED

CHR_PAIR_RUNSTATUS_REQUESTING_STOP

CHR_PAIR_RUNSTATUS_FINISHED_WARNINGS

CHR_PAIR_RUNSTATUS_TRANSFERRING_PAYLOAD

CHR_PAIR_RUNSTATUS_APPLYING_IXIA_CONFIG

CHR_PAIR_RUNSTATUS_WAITING_FOR_REINIT

CHR_PAIR_RUNSTATUS_ABANDONED

See also typedef char CHR_PAIR_RUNSTATUS_TYPE, listed in Typedefs and Enumerations.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK

- 438 -

IxChariot APIGuide
The following return code indicates that an error occurred and any returned values should
be ignored:
l

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 439 -

IxChariot APIGuide

CHR_pair_get_script_embedded_payload
DESCRIPTION
The CHR_pair_get_script_embedded_payload function gets the value of the embedded payload data from the script used by this endpoint pair. This function requires that the variable
is of type send_datatype.
C H R _API_R C
C H R _ pai r_get _s c ri pt _ em bedded_pay l oad (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G v ariableN ame,
C H R _LEN GTH v ariableN ameLengt h,
C H R _STR I N G pay load,
C H R _LEN GTH pay loadMax Lengt h,
C H R _LEN GTH * pay loadLengt h
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

variableName [in]
A string containing the name of the script variable.

variableNameLength [in]
The length of the variable name, excluding the null terminator. This string is limited to 24
characters.

payload [out]
The buffer to which the embedded script payload is returned.

valueMaxLength [in]
The length of the provided buffer.

valueLength [out]
A pointer to the variable to which the length of the payload (in bytes) is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

- 440 -

IxChariot APIGuide

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NO_SCRIPT_IN_USE

CHR_BUFFER_TOO_SMALL

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 441 -

IxChariot APIGuide

CHR_pair_get_script_filename
DESCRIPTION
The CHR_pair_get_script_filename function gets the script filename for the given endpoint
pair or hardware performance pair. The script filename is returned without path information.
C H R _API_R C
C H R _ pai r_get _s c ri pt _ f i l enam e(
C H R _PAI R _H AN D LE pair,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

buf [out]
A pointer to the buffer where the script filename is returned.

len [in]
The length of the provided buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 442 -

IxChariot APIGuide

CHR_pair_get_script_variable
DESCRIPTION
The CHR_pair_get_script_variable function gets the value of a specified variable from the
script used by this endpoint pair.
C H R _API_R C
C H R _ pai r_get _s c ri pt _ v ari abl e (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G name,
C H R _LEN GTH nameLengt h,
C H R _STR I N G v alue,
C H R _LEN GTH v alueMax Lengt h,
C H R _LEN GTH * v alueLengt h
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

name [in]
A string containing the name of the script variable.

nameLength[in]
The length of the variable name, excluding the null terminator. This string is limited to 24
characters.

value [out]
The name of the buffer to which the value of the script variable is returned.
The value will be returned in the same format used by the set function.

valueMaxLength [in]
The length of the provided buffer.

valueLength [out]
A pointer to the variable to which the length of the variable value is returned. (The length
of the variable value excludes the null terminator.)

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

- 443 -

IxChariot APIGuide

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NO_SCRIPT_IN_USE

CHR_BUFFER_TOO_SMALL

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 444 -

IxChariot APIGuide

CHR_pair_get_setup_e1_e2_addr
DESCRIPTION
The CHR_pair_get_setup_e1_e2_addr function gets the address at which Endpoint 1 knows
Endpoint 2 for purposes of test setup for the given endpoint pair or hardware performance
pair. This attribute applies only when the CHR_pair_set_use_setup_e1_e2_values function
sets the "use" attribute to CHR_TRUE.
C H R _API_R C
C H R _ pai r_get _ s et up_ e1_ e2_addr(
C H R _PAI R _H AN D LE pair,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

buf [out]
A pointer to the buffer where the address is returned.

len [in]
The length of the given buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminatorlike strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 445 -

IxChariot APIGuide

CHR_pair_get_timing_record
DESCRIPTION
The CHR_pair_get_timing_record function gets the specified timing record from the given
endpoint pair or hardware performance pair. The handle returned by this function is
needed for other function calls to operate on this object.
C H R _API_R C
C H R _ pai r_get _t i m i ng_ rec ord(
C H R _PAI R _H AN D LE pair,
C H R _C OU N T num,
C H R _TI MI N GR EC _H AN D LE* t imingrec
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

num [in]
The number indicating which timing record. The number is determined by the order in
which timing records were received.

timingrec [out]
A pointer to the variable where the handle of the timing record is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 446 -

IxChariot APIGuide

CHR_pair_get_timing_record_count
DESCRIPTION
The CHR_pair_get_timing_record_count function gets the number of timing records in the
results for the given endpoint pair or hardware performance pair.
C H R _API_R C
C H R _ pai r_get _t i m i ng_ rec ord_c ount (
C H R _PAI R _H AN D LE pair,
C H R _C OU N T* num
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

num [out]
A pointer to the variable where the number of timing records is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 447 -

IxChariot APIGuide

CHR_pair_get_use_console_e1_values
DESCRIPTION
The CHR_pair_get_use_console_e1_values function gets whether to use the Console-toEndpoint 1 values.
C H R _API_R C
C H R _ pai r_get _us e_ c ons ol e_ e1_ v al ues (
C H R _PAI R _H AN D LE pair,
C H R _BOOLEAN * us e
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new or CHR_test_get_pair.

use [out]
A pointer to the variable where the Boolean value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 448 -

IxChariot APIGuide

CHR_pair_get_use_setup_e1_e2_values
DESCRIPTION
The CHR_pair_get_use_setup_e1_e2_values function gets whether to use the values by
which Endpoint 1 knows Endpoint 2 for purposes of test setup.
CHR_API_RC
CHR_pair_get_use_setup_e1_ e2_values(
CHR_PAIR_HANDLE pair,
CHR_BOOLEAN* use
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

use [out]
A pointer to the variable where the Boolean value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 449 -

IxChariot APIGuide

CHR_pair_is_disabled
DESCRIPTION
The CHR_pair_is_disabled function determines whether or not the specified pair is disabled in the test. You can use this function for any of the following pair types: regular
pairs, Hardware Performance Pairs, VoIP pairs, VoIP Hardware Performance Pairs, and
video pairs. However, this function is not valid for pairs within application groups.
CHR_API_RC
CHR_pair_is_ disabled(
CHR_PAIR_HANDLE pairHandle,
CHR_BOOLEAN* disabled
)

PARAMETERS
pairHandle [in]
A handle returned by any of the following functions:
l

CHR_test_get_pair()

CHR_pair_new()

CHR_hardware_pair_new()

CHR_voip_pair_new()

CHR_video_pair_new()

disabled [out]
A pointer to the variable where the Boolean value is returned. The returned values can be:
l

CHR_TRUE: The pair is disabled in the test.

CHR_FALSE: The pair is enabled in the test.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_API_NOT_INITIALIZED

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 450 -

IxChariot APIGuide

CHR_pair_is_udp_RFC768_streaming
DESCRIPTION
The CHR_ pair_is_udp_RFC768_streaming function determines whether or not the
RFC768 option is enabled in the script for the specified pair. If the option is present in the
script, and it is enabled, the function returns TRUE. In all other cases, it returns FALSE.
This function should be called only for streaming pairs that use the UDP or UDPv6 protocol;
otherwise it will return CHR_NO_SUCH_VALUE.
CHR_API_RC
CHR_ pair_ is_udp_RFC768_ streaming(
CHR_PAIR_HANDLE pairHandle,
CHR_BOOLEAN* used
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

used [out]
A pointer to the variable where the Boolean value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_API_NOT_INITIALIZED

CHR_NO_SUCH_VALUE

CHR_BUFFER_TOO_SMALL

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 451 -

IxChariot APIGuide

CHR_pair_new
DESCRIPTION
The CHR_pair_new function creates an endpoint pair object and initializes it to object
default values. Note that the object default values do not use the default values specified
in the Chariot Options Menu. See Pair Object Default Values for information on the object
default values.
The handle returned by this function is needed for other function calls to operate on this
object.
For voice over IP (VoIP) pairs, use CHR_voip_pair_new (VoIP Test Module only).
C H R _API_R C
C H R _ pai r_new (
C H R _PAI R _H AN D LE* pair
)

PARAMETERS
pair [out]
A pointer to the variable where the handle for the new endpoint pair is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_OUT_OF_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 452 -

IxChariot APIGuide

CHR_pair_set_comment
DESCRIPTION
The CHR_pair_set_comment function sets or changes the comment for the given endpoint
pair or hardware performance pair.
C H R _API_R C
C H R _ pai r_s et _c om m ent (
C H R _PAI R _H AN D LE pair,
C H R _STR I N G c omment ,
C H R _LEN GTH len
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

comment [in]
The string containing the new comment.

len [in]
The length of the comment string, excluding the null terminator. This string is limited to 64
characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 453 -

IxChariot APIGuide

CHR_pair_set_console_e1_addr
DESCRIPTION
The CHR_pair_set_console_e1_addr function sets or changes the address by which the Console knows Endpoint 1 for the given endpoint pair or hardware performance pair. This
attribute applies only when the CHR_pair_set_use_console_e1_values function sets the
"use" attribute to CHR_TRUE.
C H R _API_R C
C H R _ pai r_s et _c ons ol e_ e1_ addr(
C H R _PAI R _H AN D LE pair,
C H R _STR I N G addr,
C H R _LEN GTH len
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

addr [in]
A string containing the address.

len [in]
The length of the address, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 454 -

IxChariot APIGuide

CHR_pair_set_console_e1_protocol
DESCRIPTION
The CHR_pair_set_console_e1_protocol function sets or changes the Console to Endpoint 1
network protocol for the given endpoint pair. This attribute applies only when the CHR_
pair_set_use_console_e1_values function sets the "use" attribute to CHR_TRUE.
C H R _API_R C
C H R _ pai r_s et _c ons ol e_ e1_ prot oc ol (
C H R _PAI R _H AN D LE pair,
C H R _PR OTOC OL prot oc ol
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

protocol [in]
The protocol type: CHR_PROTOCOL_TCP, CHR_PROTOCOL_TCP6, or CHR_PROTOCOL_SPX.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 455 -

IxChariot APIGuide

CHR_pair_set_console_e1_qos_name
DESCRIPTION
The CHR_pair_set_console_e1_qos_name function sets or changes the quality of service
name for Console to Endpoint 1 for the given endpoint pair. This attribute applies only
when the CHR_pair_set_use_console_e1_values function sets the "use" attribute to CHR_
TRUE.
C H R _API_R C
C H R _ pai r_s et _c ons ol e_ e1_ qos _ nam e(
C H R _PAI R _H AN D LE pair,
C H R _STR I N G qos ,
C H R _LEN GTH len
)
This function is applicable only to APPC. IxChariot 6.20 and higher no longer support APPC.

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

qos [in]
A string containing the quality of service name.

len [in]
The length of the quality of service name, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 456 -

IxChariot APIGuide

CHR_pair_set_e1_addr
DESCRIPTION
The CHR_pair_set_e1_addr function sets or changes the address for Endpoint 1 in the given
endpoint pair or hardware performance pair.
C H R _API_R C
C H R _ pai r_s et _e1_ addr(
C H R _PAI R _H AN D LE pair,
C H R _STR I N G addr,
C H R _LEN GTH len
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

addr [in]
A string containing the address for Endpoint 1 (IPv4 or IPv6).

len [in]
The length of the endpoint address string, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 457 -

IxChariot APIGuide

CHR_pair_set_e2_addr
DESCRIPTION
The CHR_pair_set_e2_addr function adds or changes the address for Endpoint 2 in the
given endpoint pair or hardware performance pair.
C H R _API_R C
C H R _ pai r_s et _e2_ addr(
C H R _PAI R _H AN D LE pair,
C H R _STR I N G addr,
C H R _LEN GTH len
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

addr [in]
A string containing the address for Endpoint 2.

len [in]
The length of the endpoint address string, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 458 -

IxChariot APIGuide

CHR_pair_set_lock
DESCRIPTION
The function CHR_pair_set_lock locks an unlocked pair object if lock is CHR_TRUE, or
unlocks a locked pair object if lock is CHR_FALSE. An owned object must be locked--disabled for validation--before any of its attributes can be modified (using the set subcommand). To enable validation, all objects owned by a test must be unlocked before the
test can be run or saved.<META NAME="Keywords" CONTENT="Pair Object Functions:CHR_pair_set_lock, LOCK">
When an attempt is made to unlock a locked pair object, the object is validated. If the
object is found to be invalid, an error is returned and the object remains locked.
When an attempt is made to unlock an invalid pair object, CHR_OBJECT_INVALID is
returned. In addition, extended error information is always returned, providing details of
why the operation failed or how the object is invalid. Use CHR_common_error_get_info to
get this extended error information, and refer to Common Error Functions for more information.
A pair object can't be locked if it's contained by a test object that has results or is running.
If you attempt to lock a pair object that is already locked, the pair object remains locked.
A pair object that is contained by a test object must be locked before any of its attributes
(such as its endpoint addresses) can be set.
C H R _API_R C
C H R _ pai r_s et _l oc k (
C H R _PAI R _H AN D LE pair,
C H R _BOOLEAN loc k
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair.

lock [in]
A CHR_BOOLEAN, where CHR_TRUE locks the (unlocked) pair object, and CHR_FALSE
unlocks the (locked) object.

RETURN CODES
The following return code indicates the function call was successful:
CHR_OK
l

The following return codes indicate an error occurred:

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

- 459 -

IxChariot APIGuide

CHR_OBJECT_INVALID

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 460 -

IxChariot APIGuide

CHR_pair_set_payload_file
DESCRIPTION
The CHR_pair_set_payload_file function specifies the payload of a particular SEND
command. It allows the user to specify a file whose content will be used as payload when
running the script. In addition to specifying the payload, this function will also set the
send_datatype to "Payload File".
C H R _API_R C
C H R _ pai r_s et _pay l oad_ f i l e(
C H R _PAI R _H AN D LE pair,
C H R _STR I N G v arname,
C H R _LEN GTH v arnameLengt h,
C H R _STR I N G f ilename,
C H R _LEN GTH f ilenameLengt h,
C H R _BOOLEAN embedded
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new().

varname [in]
A string containing the name of a send_datatype script variable.
A script must be defined for use by the given endpoint pair. The script variable name is
checked to ensure that it exists and is of type send_datatype. CHR_NO_SUCH_OBJECT is
returned if the variable does not exist in the script, and CHR_VALUE_INVALID will be
returned if the variable is not of type send_datatype.

varnameLength [in]
The length of the variable name, excluding the null terminator. This string is limited to 24
characters.

filename [in]
The name of the file containing the payload data.
If the specified file does not exit, CHR_OPERATION_FAILED will be returned. If the file size
is greater than 1 billion bytes (953MB), CHR_PAYLOAD_FILE_TOO_LARGE will be returned.

filenameLength [in]
The length of the filename parameter.
The filenameLength parameter needs to be between 1 and 24, inclusive; otherwise, CHR_
VALUE_INVALID will be returned.

- 461 -

IxChariot APIGuide

embedded [in]
If set to CHR_TRUE, the payload file will be embedded within the script. If set to CHR_
FALSE, the script will contain a reference to the external file. The recommended option is
CHR_TRUE.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NO_SCRIPT_IN_USE

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

CHR_VALUE_INVALID

CHR_OPERATION_FAILED

CHR_PAYLOAD_FILE_TOO_LARGE

See Return Code Summary for a detailed description of each return code.

- 462 -

IxChariot APIGuide

CHR_pair_set_protocol
DESCRIPTION
The CHR_pair_set_protocol function sets or changes the Endpoint 1 to Endpoint 2 network
protocol for the given endpoint or VoIP pair.
C H R _API_R C
C H R _ pai r_s et _prot oc ol (
C H R _PAI R _H AN D LE pair,
C H R _PR OTOC OL prot oc ol
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair.

protocol [in]
Provides the following protocol types: CHR_PROTOCOL_UDP, CHR_PROTOCOL_RTP, CHR_
PROTCOL_TCP, CHR_PROTOCOL_IPX, and CHR_PROTOCOL_SPX. With the separately
licensed IPv6 Test Module, also provides CHR_PROTCOL_TCP6, CHR_PROTOCOL_UDP6,
and CHR_PROTOCOL_RTP6.With the VoIP Test Module, also provides CHR_PROTOCOL_RTP.
With both the IPv6 Test Module and the VoIP Test Module, also provides CHR_PROTOCOL_
RTP or CHR_PROTOCOL_RTP6.
If you change a pair's protocol to an IPv6 protocol, you must also clear any QoS settings before you try to add this pair to a test; otherwise, you'll get CHR_OBJECT_
INVALID. Note that IxChariot supports IPv6 QoS on Linux and Ixia, but not on Windows.
Before you can add this pair to a test, you must also set the following functions:
CHR_pair_set_console_e1_addr and CHR_pair_set_console_e1_protocol. In addition, CHR_pair_set_use_console_e1_values must be set to "True".

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 463 -

IxChariot APIGuide

- 464 -

IxChariot APIGuide

CHR_pair_set_qos_name
DESCRIPTION
The CHR_pair_set_qos_name function sets or changes the service quality template for
both endpoint 1 and endpoint 2.
C H R _API_R C
C H R _ pai r_s et _qos _ nam e(
C H R _PAI R _H AN D LE pair,
C H R _STR I N G qos ,
C H R _LEN GTH len
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new().

qos [in]
A string containing quality of service name.

len [in]
The length of the quality of service name, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 465 -

IxChariot APIGuide

CHR_pair_set_e1_qos_name
DESCRIPTION
The CHR_pair_set_e1_qos_name function sets or changes the service quality name for endpoint 1 in the given pair.
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _e1_ qos _ nam e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G qos N ame,
C H R _LEN GTH lengt h)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new().

qos [in]
A string containing quality of service name.

length [in]
The length of the quality of service name, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 466 -

IxChariot APIGuide

CHR_pair_set_e2_qos_name
DESCRIPTION
The CHR_pair_set_e2_qos_name function sets or changes the service quality name for endpoint 2 in the given pair.
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _e2_ qos _ nam e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G qos N ame,
C H R _LEN GTH lengt h)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new().

qos [in]
A string containing quality of service name.

length [in]
The length of the quality of service name, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG
When calling CHR_pair_set_e2_qos_name for a VoIP, Video, or VoIP HPP pair,
the function returns no error code, but the QoS is not set, as these pair types
send traffic only from Endpoint 1 to Endpoint 2.

See Return Code Summary for a detailed description of each return code.

- 467 -

IxChariot APIGuide

CHR_pair_set_script_embedded_payload
DESCRIPTION
The CHR_pair_set_script_embedded_payload function modifies the value of an embedded
payload within a script. The send_datatype for the variable will automatically be set to
"Embedded payload". There must be a script defined for use by the given endpoint pair.
C H R _API_R C
C H R _ pai r_s et _s c ri pt _ em bedded_pay l oad (
C H R _PAI R _H AN D LE pair,
C H R _STR I N G v arname,
C H R _LEN GTH namelen,
C H R _STR I N G pay load,
C H R _LEN GTH pay loadLengt h
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new().

varname [in]
A string containing the name of the script variable.

namelen [in]
The length of the variable name, excluding the null terminator. This string is limited to 24
characters.

payload [in]
A pointer to a buffer that contains the payload.

payloadLength [in]
The length of the payload, in bytes.
Note that CHR_MAX_EMBEDDED_PAYLOAD_SIZE defines the maximum size permitted for
embedded payload.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

- 468 -

IxChariot APIGuide

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NO_SCRIPT_IN_USE

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

CHR_VALUE_INVALID

See Return Code Summary for a description of each return code.

- 469 -

IxChariot APIGuide

CHR_pair_set_script_variable
DESCRIPTION
The CHR_pair_set_script_variable function modifies the value of a variable in the script
defined for use by the given endpoint pair. There must be a script defined for use by the
given endpoint pair. The script variable name is checked to ensure that it exists in the
defined script. CHR_NO_SUCH_OBJECT is returned if the variable does not exist in the
script. Note that the options related to Nagle, UDP checksum and MSS must have previously been created using the IxChariot editor before being set with this command. The
variable value is checked to ensure that it is valid for that variable in that script.
C H R _API_R C
C H R _ pai r_s et _s c ri pt _ v ari abl e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G name,
C H R _LEN GTH nameLengt h,
C H R _STR I N G v alue,
C H R _LEN GTH v alueLengt h
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_pair_new().

name [in]
A string containing the name of the script variable.

nameLength[in]
The length of the variable name, excluding the null terminator. This string is limited to 24
characters.

value [in]
A string containing the value for the script variable. Use the following table to determine
the valid string values.
Ty pe of Variable

Allowed Valu es

"Reset" (default)
cl ose_type
"Normal"
"0" - "2147483647."
I nteger

Option:
nagle_algorithm_e1
nagle_algorithm_e2

For send or receive buffer sizes, "default"

instructs Chariot to automatically select the
default buffer size for the protocol and platform
on which it is running
Enabled by default. But for all VoIP pairs, udp_
checksum is disabled by default on operating systems that support it.

- 470 -

IxChariot APIGuide

Ty pe of Variable

Allowed Valu es

udp_checksum_e1
udp_checksum_e2

"enabled"

Option:

Disabled by default.

max_segment_size_e1
max_segment_size_e2

The transmit MSS associated with either endpoint 1 or 2. This must be an integer value.

Port Number:

"0" - "65535" or "auto."

source_port
destination_port

Specifying a port number of zero instructs

IxChariot to automatically select the port.

Send Data Size:

file_size

"disabled"

An integer (constant).
This variable specifies the number of bytes to
send with each SEND command.
An integer (constant) between 1 and 2147483647
or a Random value expressed as "d[x,y]" where:

SEND/RECEIVE Buffer Size:

send_buffer_size
receive_buffer_size

Connection Buffer Size:

d = u(uniform), n(normal), p(poisson), or e

(exponential) and x,y = integers between "1"
and "2147483647" where x < y , or "default." For
send or receive buffer sizes, "default" instructs
Chariot to automatically select the default buffer
size for the protocol and platform on which it is
running.
An integer (constant) between 0 and
2147483646.

send_buffer
receive_buffer

CONNECT_INITIATE and CONNECT_ACCEPT each

define both buffers (send_buffer and receive_buffer).

Sleep Time:

An integer (constant) between 1 and

2147483647, or a Random value expressed as "d
[x,y]" where: d = u(uniform), n(normal), p(poisson), or e(exponential) and x,y = integers
between "0" and "2147483647" where x < y.

initial_delay
user_delay
transaction_delay

An integer (constant) - minimum value is 1.

Transaction Count:
transactions_per_record

TimingRecords:
number_of_timing_records
Data Rate:
send_data_rate
Data Type:
send_datatype

This variable controls the number of transactions

that will be run for each timing record. Setting it
to 1 causes each transaction to have its own timing record.
An integer (constant).
An endpoint creates a timing record each time it
goes through a loop.
The word unlimited or a data rate expressed as:
xxxxxx[.yyy] units
There must not be more than six x's to the left of
the decimal and no more than three y's to the

- 471 -

IxChariot APIGuide

Ty pe of Variable

Allowed Valu es

right of the decimal point.

Units should be one of:
KB, Kb, kB, kb - 1024 bytes per second
Mb 1,000,000 bytes per second
Gb 1,000,000,000 bytes per second
The data rate may not be 0.0.
Default
Files

ZEROS, NOCOMPRESS, lena.cmp,

news.cmp, trans.cmp

bib.cmp, book1.cmp, book2.cmp,

geo.cmp, paper1.cmp, paper2.cmp,
Optional
pic.cmp, progc.cmp, progl.cmp, proFiles
gp.cmp, userxx.cmp (where xx is
between 01 and 10)
Embedded Embedded payload. The value of
the embedded payload must be set
Payload
using the CHR_pair_set_script_
embedded_payload function.
A large payload file - either refReferenced
erenced or embedded. The value
or Embedof the payload file must be set
ded Payusing the CHR_pair_set_payload_
load File:
file function.
Specify the variable name (such as sync_event)
as the name parameter, and an application group
event name as the value parameter.
For example, if your script contains:
SIGNAL_EVENT
Event = sync_event (start_streaming)
Data Type:
SIGNAL_EVENT or WAIT_EVEN

Then, name = sync_event, and value = start_

streaming.
To unassign an event, use the string "Not
Assigned" as the event name.
l

The pair must be part of an application

group.
The event name must already be included in
that application group.

valueLength [in]
The length of the variable value, excluding the null terminator.

- 472 -

IxChariot APIGuide

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NO_SCRIPT_IN_USE

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 473 -

IxChariot APIGuide

CHR_pair_set_setup_e1_e2_addr
DESCRIPTION
The CHR_pair_set_setup_e1_e2_addr function sets the address by which Endpoint 1 knows
Endpoint 2 for purposes of test setup for the given endpoint pair or hardware performance
pair. This attribute applies only when the CHR_pair_set_use_setup_e1_e2_values function
sets the "use" attribute to CHR_TRUE.
CHR_API_RC
CHR_pair_set_setup_e1_ e2_addr(
CHR_PAIR_HANDLE pair,
CHR_STRING addr,
CHR_LENGTH len
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

addr [in]
A string containing the address.

len [in]
The length of the address, excluding the null terminator. The string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 474 -

IxChariot APIGuide

CHR_pair_set_use_console_e1_values
DESCRIPTION
The CHR_pair_set_use_console_e1_values function sets or changes whether the Consoleto-Endpoint 1 values are to be used. If the value is set to CHR_TRUE, the Console to Endpoint 1 address and Console to Endpoint 1 QOS name must be properly defined before the
test is run. The Console to Endpoint 1 protocol defaults to TCP and may be changed if
needed.
C H R _API_R C
C H R _ pai r_s et _us e_ c ons ol e_ e1_ v al ues (
C H R _PAI R _H AN D LE pair,
C H R _BOOLEAN us e
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new().

use [in]
Specifies CHR_TRUE or CHR_FALSE to indicate whether to use the Console to Endpoint 1
values.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 475 -

IxChariot APIGuide

CHR_pair_use_script_filename
DESCRIPTION
The CHR_pair_use_script_filename function defines or changes the script file to be used by
the given endpoint pair or hardware performance pair. The script filename may be specified by relative or absolute path.
C H R _API_R C
C H R _ pai r_us e_ s c ri pt _ f i l enam e(
C H R _PAI R _H AN D LE pair,
C H R _STR I N G s c ript ,
C H R _LEN GTH s c ript len
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new().

script [in]
A string containing the script filename.

scriptlen [in]
The length of the script filename string, excluding the null terminator. The maximum
length of the script filename is 1023.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OPERATION_FAILED*

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

CHR_VALUE_INVALID
Use CHR_common_error_get_info to get the extended error information available for this return code.

See Return Code Summary for a detailed description of each return code.

- 476 -

IxChariot APIGuide

- 477 -

IxChariot APIGuide

CHR_pair_set_use_setup_e1_e2_values
DESCRIPTION
The CHR_pair_set_use_setup_e1_e2_values function sets or changes whether the values
by which Endpoint 1 knows Endpoint 2 for purposes of test setup should be used. If this
value is set to CHR_TRUE, the Pair Setup Endpoint 1 to Endpoint 2 address must be properly defined before the test is run. The Pair Setup Endpoint 1 to Endpoint 2 protocol is automatically set to TCP and cannot be changed.
CHR_API_RC
CHR_pair_set_use_setup_e1_ e2_values(
CHR_PAIR_HANDLE pair,
CHR_BOOLEAN use
)

PARAMETERS
pair [in]
A handle returned by CHR_pair_new() or CHR_test_get_pair().

use [in]
Specifies CHR_TRUE or CHR_FALSE to indicate whether to use the Endpoint 1 to Endpoint 2
test setup values.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_OBJECT_IN_USE

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 478 -

IxChariot APIGuide

CHR_pair_swap_endpoints
DESCRIPTION
The CHR_pair_swap_endpoints function swaps (exchanges) endpoints (test and management addresses between E1 and E2). It is supported for regular pairs, VoIP, unicast
video, HPP, and vHPP.
CHR_API_RC
CHR_pair_swap_ endpoints(
CHR_PAIR_HANDLE pairHandle
)

PARAMETERS
pairHandle [in]
A handle returned by many functions, since CHR_pair_swap_endpoint is supported for regular pairs, VoIP, unicast video, HPP, and vHPP (e.g., CHR_pair_new, CHR_voip_pair_
new, etc.).

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

See Return Code Summary for a detailed description of each return code.

- 479 -

IxChariot APIGuide

Hardware Performance Pair Object Functions

Hardware Performance Pair object functions are used to define pairs for a test and retrieve
information about a hardware performance pair, either VoIP or not. You are not allowed to
set any pair information for a pair that is owned by a test. The following Pair Object Functions are used to get/set values in the Hardware Performance Pair Object as well:
l

CHR_hardware_pair_get_line_rate

CHR_hardware_pair_get_override_line_rat

CHR_hardware_pair_get_measure_statistics

CHR_hardware_pair_new

CHR_hardware_pair_set_line_rate

CHR_hardware_pair_set_override_line_rate

CHR_hardware_pair_set_measure_statistics

- 480 -

IxChariot APIGuide

CHR_hardware_pair_get_line_rate
DESCRIPTION
The CHR_hardware_pair_get_line_rate function gets the line rate for the given hardware
pair.
C H R _API_R C
C H R _ hardw are_pai r_ get _ l i ne_rat e(
C H R _H A R D W A R E _P A I R _ H A N D LE pai r,
C H R _FLOAT* line_rat e
)

PARAMETERS
pair [in]
A handled returned by CHR_hardware_pair_new () or CHR_test_get_pair ().

line_rate [out]
A pointer to the variable where the line rate is returned. See the CHR_hardware_pair_set_
line_rate function for applicable line rate values.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OUT_OF_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 481 -

IxChariot APIGuide

CHR_hardware_pair_get_override_line_rate
DESCRIPTION
The CHR_hardware_pair_get_override_line_rate function gets the setting for the override
line rate flag for the given hardware pair.
C H R _API_R C
C H R _ hardw are_pai r_ get _ l i ne_rat e(
C H R _H A R D W A R E _P A I R _ H A N D LE pai r,
C H R _ B OOLE A N * ov erri de_ l i ne_rat e
)

PARAMETERS
pair [in]
A handled returned by CHR_hardware_pair_new () or CHR_test_get_pair ().

override_line_rate [out]
A pointer to the Boolean variable where the override line rate condition is returned. See
the CHR_hardware_pair_set_override_line_rate function for applicable override line rate
values.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OUT_OF_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 482 -

IxChariot APIGuide

CHR_hardware_pair_get_measure_statistics
DESCRIPTION
The CHR_hardware_pair_get_measure_statistics function gets the flag that indicates
whether background statistics should be collected for the given hardware pair.
C H R _API_R C
C H R _hardw are_pai r_ get _m eas ure_s t at i s t i c s (
C H R _H A R D W A R E _P A I R _ H A N D LE pai r,
C H R _BOOLEAN * meas ure_s t at is t ic s
)

PARAMETERS
pair [in]
A handled returned by CHR_hardware_pair_new () or CHR_test_get_pair ().

measure_statistics [out]
A pointer to the variable where the collect statistics flag is returned. See the CHR_hardware_pair_set_measure_statistics on page 4-358.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OUT_OF_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 483 -

IxChariot APIGuide

CHR_hardware_pair_new
DESCRIPTION
The CHR_hardware_pair_new function creates a hardware pair object and initializes it to
object default values. Note that the object default values do not use the default values specified in the Chariot Options Menu. See Hardware Performance Pair Object Default Values
for information on the object default values.
The handle returned by this function is needed for other function calls to operate on this
object.
CHR_API_RC
CHR_hardware_pair_ new(
CHR_HARDWARE_PAIR_ HANDLE* pair
)

PARAMETERS
pair [out]
A pointer to the variable where the handle for the new hardware pair is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_OUT_OF_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 484 -

IxChariot APIGuide

CHR_hardware_voip_pair_new
DESCRIPTION
The CHR_hardware_voip_pair_new function creates a new hardware pair object specialized for Voice over IP testing and initializes it to object default values. Note that the
object default values do not use the default values specified in the Chariot Options Menu.
See VoIP Hardware Performance Pair Object Default Values for information on the object
default values.
The handle returned by this function is needed for other function calls to operate on this
object.
CHR_API_RC
CHR_hardware_voip_ pair_new (
CHR_HARDWARE_PAIR_ HANDLE* pair
)

PARAMETERS
pair [out]
A pointer to the variable where the handle for the new hardware pair is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_OUT_OF_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 485 -

IxChariot APIGuide

CHR_hardware_pair_set_line_rate
DESCRIPTION
The CHR_hardware_pair_set_line_rate function sets or changes the line rate percentage
for the given hardware pair.
C H R _API_R C
C H R _ hardw are_pai r_ s et _ l i ne_rat e(
C H R _H A R D W A R E _P A I R _ H A N D LE pai r,
C H R _ F LOA T l i ne_rat e
)

PARAMETERS
pair [in]
A handled returned by CHR_hardware_pair_new () or CHR_test_get_pair ().

line_rate [in]
The line rate to send traffic for this pair. Applicable values are greater than 0 and less than
or equal 100.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OUT_OF_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 486 -

IxChariot APIGuide

CHR_hardware_pair_set_override_line_rate
DESCRIPTION
The CHR_hardware_pair_set_override_line_rate function sets or changes the line rate
override condition for the given hardware pair.
C H R _API_R C
C H R _ hardw are_pai r_ s et _ l i ne_rat e(
C H R _H A R D W A R E _P A I R _ H A N D LE pai r,
C H R _B OOLE A N ov erri de_l i ne_ rat e
)

PARAMETERS
pair [in]
A handled returned by CHR_hardware_pair_new () or CHR_test_get_pair ().

override_line_rate [in]
Indicates whether to override the line rate programmed in the stream associated with the
hardware performance pair or not.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OUT_OF_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 487 -

IxChariot APIGuide

CHR_hardware_pair_set_measure_statistics
DESCRIPTION
The CHR_Hardware_pair_set_measure_statistics function sets a flag to tell the hardware pair whether or not to collect background statistics.
C H R _API_R C
C H R _hardw are_pai r_ s et _m eas ure_s t at i s t i c s (
C H R _H A R D W A R E _P A I R _ H A N D LE pai r,
C H R _BOOLEAN meas ure_s t at is t ic s
)

PARAMETERS
pair [in]
A handled returned by CHR_hardware_pair_new () or CHR_test_get_pair ().

measure_statistics [in]
A flag to indicate whether or not to collect background statistics. If this value is set to CHR_
TRUE then the applicable statistics will be collected for this hardware pair.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OUT_OF_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 488 -

IxChariot APIGuide

Ixia Network Configuration Functions

The Ixia network configuration functions are used to import Ixia network configurations
into a test object and export Ixia network configurations that are part of a test object.

- 489 -

IxChariot APIGuide

CHR_test_clear_ixia_network_configuration
DESCRIPTION
The CHR_test_clear_ixia_network_configuration function clears the Ixia port configuration that is presently associated with test identified by testHandle.
C H R _API_R C
C H R _ t es t _c l ear_ i x i a_ net w ork _ c onf i gurat i on(
C H R _T E S T _H A N D LE t es t H andl e
)

PARAMETERS
testHandle [in]
A handle returned by CHR_test_new().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 490 -

IxChariot APIGuide

CHR_test_get_ixia_network_configuration
DESCRIPTION
The CHR_test_get_ixia_network_configuration function gets the Ixia port configuration
that is presently associated with the test identified by testHandle.
C H R _API_R C
C H R _ t es t _get _ i x i a_ net w ork _ c onf i gurat i on(
C H R _TEST_H AN D LE t es t H andle,
C H R _BYTE * dat aPt r,
C H R _LEN GTH max imumSiz e,
C H R _LEN GTH * dat aSiz e
)

PARAMETERS
testHandle [in]
A handle returned by CHR_test_new().

dataPtr [out]
A pointer to the variable where the Ixia network configuration is returned.

maximumSize [in]
The maximum length of the dataPtr buffer.

dataSize [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_NO_NETWORK_CONFIGURATION

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 491 -

IxChariot APIGuide

CHR_test_load_ixia_network_configuration
DESCRIPTION
The CHR_test_load_ixia_network_configuration function loads the Ixia port configuration
into the test object identified by testHandle.
C H R _API_R C
C H R _ t es t _l oad_ i x i a_net w ork _ c onf i gurat i on (
C H R _TEST_H AN D LE t es t H andle,
C H R _STR I N G f ileN ame,
C H R _LEN GTH f ileN ameLengt h
)

PARAMETERS
testHandle [in]
A handle returned by CHR_test_new().

fileName [in]
The filename associated with the Ixia network configuration.

fileNameLength [in]
The length of the buffer that holds the filename.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_NO_NETWORK_CONFIGURATION

CHR_INVALID_NETWORK_CONFIGURATION

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 492 -

IxChariot APIGuide

CHR_test_save_ixia_network_configuration
DESCRIPTION
The CHR_test_save_ixia_network_configuration function saves the Ixia port configuration
from the test object identified by testHandle to the file identified by fileName.
C H R _API_R C
C H R _ t es t _s av e_ i x i a_net w ork _ c onf i gurat i on (
C H R _TEST_H AN D LE t es t H andle,
C H R _STR I N G f ileN ame,
C H R _LEN GTH f ileMax imumLengt h
)

PARAMETERS
testHandle [in]
A handle returned by CHR_test_new().

fileName [in]
The filename associated with the Ixia network configuration.

fileMaximumLength [in]
The maximum length of the buffer that will hold the filename.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_NO_NETWORK_CONFIGURATION

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 493 -

IxChariot APIGuide

CHR_test_set_ixia_network_configuration
DESCRIPTION
The CHR_test_set_ixia_network_configuration function applies the Ixia port configuration
to the test identified by testHandle.
C H R _API_R C
C H R _ t es t _s et _ i x i a_ net w ork _ c onf i gurat i on(
C H R _TEST_H AN D LE t es t H andle,
C H R _BYTE * dat aPt r,
C H R _LEN GTH dat aSiz e
)

PARAMETERS
testHandle [in]
A handle returned by CHR_test_new().

dataPtr [out]
A pointer to the buffer containing the Ixia port configuration.

dataSize [in]
The size of the configuration buffer pointed to by dataPtr.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_PGM_INTERNAL_ERROR

CHR_NO_NETWORK_CONFIGURATION

CHR_INVALID_NETWORK_CONFIGURATION

CHR_ERROR_ACCESSING_TESTSERVER_SESSION

See Return Code Summary for a detailed description of each return code.

- 494 -

IxChariot APIGuide

Pair/MPair Results Extraction Functions

The pair/mpair extraction functions are used to obtain test results that are common to endpoint pairs and multicast pairs.

- 495 -

IxChariot APIGuide

CHR_pair_results_get_95pct_confidence
DESCRIPTION
The CHR_pair_results_get_95pct_confidence function gets the 95 percent confidence
interval for the given endpoint pair or multicast pair.
C H R _ pai r_res ul t s _ get _95pc t _ c onf i denc e(
C H R _H AN D LE handle,
C H R _R ESU LTS res ult Ty pe,
C H R _FLOAT* res ult
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().

resultType [in]
Provides one of the following CHR_RESULTS values:
l

CHR_RESULTS_THROUGHPUT,

CHR_RESULTS_TRANSACTION_RATE,

CHR_RESULTS_RESPONSE_TIME,

CHR_RESULTS_DF or CHR_RESULTS_MLR.

CHR_RESULTS_TRANSACTION_RATE and CHR_RESULTS_RESPONSE_TIME are not valid for

streaming pairs.
CHR_RESULTS_DF and CHR_RESULTS_MLR are only valid for video pairs (or video multicast pairs).
See Typedefs and Enumerations for CHR_RESULTS values.

result [out]
A pointer to the variable where the confidence interval value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

- 496 -

IxChariot APIGuide

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 497 -

IxChariot APIGuide

CHR_pair_results_get_average
DESCRIPTION
The CHR_pair_results_get_average function gets the average for the given type from the
test results in the given endpoint pair or multicast pair.
C H R _API_R C
C H R _ pai r_res ul t s _ get _av erage (
C H R _H AN D LE handle,
CHR_RESULTS t y pe,
C H R _FLOAT* av g
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().

type [in]
Provides one of the CHR_RESULTS values. See Typedefs and Enumerations for CHR_
RESULTS values.
The units for this value depend on the type of results:
l

For throughput, the units are specified in the test.

Transaction rate has no units. CHR_NO_SUCH_VALUE is returned for streaming pairs.

For response time, the units are seconds. CHR_NO_SUCH_VALUE is returned for
streaming pairs.
For jitter, the units are milliseconds. CHR_NO_SUCH_VALUE is returned for protocols
other than RTP.
The following two result types only have average values: CHR_RESULTS_R_VALUE;
CHR_RESULTS_END_TO_END_DELAY
The following two result types do not have average values: CHR_RESULTS_DELAY_
VARIATION; CHR_RESULTS_CONSECUTIVE_LOST.
For both endpoint 1 and endpoint 2 RSSI, the units are in dBm. Values for E1 are
returned when using non-streaming scripts and for E2 when using streaming scripts.

For DF (Delay Factor), the units are milliseconds.

For MLR (media loss rate), the units are media packets per second.

avg [out]
A pointer to the variable where the average value is returned.

RETURN CODES
The following return code indicates that the function call was successful:

- 498 -

IxChariot APIGuide
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 499 -

IxChariot APIGuide

CHR_pair_results_get_CPU_util_e1
DESCRIPTION
The CHR_pair_results_get_CPU_util_e1 function gets the CPU utilization for Endpoint 1
from the test results in the given endpoint pair or multicast pair.
C H R _API_R C
C H R _ pai r_res ul t s _ get _C P U _ ut i l _ e1(
C H R _H AN D LE handle,
C H R _FLOAT* c pu_ut il
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().

cpu_util [out]
A pointer to the variable where the CPU utilization is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_VALUE

CHR_NO_RESULTS

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 500 -

IxChariot APIGuide

CHR_pair_results_get_CPU_util_e2
DESCRIPTION
The CHR_pair_results_get_CPU_util_e2 function gets the CPU utilization for Endpoint 2
from the test results in the given endpoint pair or multicast pair.
C H R _API_R C
C H R _ pai r_res ul t s _ get _C P U _ ut i l _ e2(
C H R _H AN D LE handle,
C H R _FLOAT* c pu_ut il
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().

cpu_util [out]
A pointer to the variable where the CPU utilization is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 501 -

IxChariot APIGuide

CHR_pair_results_get_maximum
DESCRIPTION
The CHR_pair_results_get_maximum function gets the maximum for the given type from
the test results in the given endpoint pair or multicast pair.
C H R _API_R C
C H R _ pai r_res ul t s _ get _m ax i m um (
C H R _H AN D LE handle,
CHR_RESULTS t y pe,
C H R _FLOAT* max
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().

type [in]
Provides one of the CHR_RESULTS values. See Typedefs and Enumerations for CHR_
RESULTS values.
The units for this value depend on the type of results:
l

For throughput, the units are specified in the test.

Transaction rate has no units. CHR_NO_SUCH_VALUE is returned for streaming pairs.

For response time, the units are seconds. CHR_NO_SUCH_VALUE is returned for
streaming pairs.
For jitter, the units are milliseconds. CHR_NO_SUCH_VALUE is returned for protocols
other than RTP.
The following two result types do not have maximum values: CHR_RESULTS_R_
VALUE; CHR_RESULTS_END_TO_END_DELAY.
The following two result types only have maximum values: CHR_RESULTS_DELAY_
VARIATION; CHR_RESULTS_CONSECUTIVE_LOST.
For both endpoint 1 and endpoint 2 RSSI, the units are in dBm. Values for E1 are
returned when using non-streaming scripts and for E2 when using streaming scripts.

For DF (Delay Factor), the units are milliseconds.

For MLR (media loss rate), the units are media packets per second.

max [out]
A pointer to the variable where the maximum value is returned.

RETURN CODES
The following return code indicates that the function call was successful:

- 502 -

IxChariot APIGuide
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 503 -

IxChariot APIGuide

CHR_pair_results_get_minimum
DESCRIPTION
The CHR_pair_results_get_minimum function gets the minimum for the given type from
the test results in the given endpoint pair or multicast pair.
CHR_API_RC
CHR_pair_results_get_minimum (
CHR_HANDLE handle,
CHR_RESULTS type,
CHR_FLOAT* min
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().

type [in]
Provides one of the CHR_RESULTS values. See Typedefs and Enumerations for CHR_
RESULTS values.
The units for this value depend on the type of results:
l

For throughput, the units are specified in the test.

Transaction rate has no units. CHR_NO_SUCH_VALUE is returned for streaming pairs.

For response time, the units are seconds. CHR_NO_SUCH_VALUE is returned for
streaming pairs.
For jitter, the units are milliseconds. CHR_NO_SUCH_VALUE is returned for protocols
other than RTP.
The following four result types do not have minimum values: CHR_RESULTS_DELAY_
VARIATION; CHR_RESULTS_CONSECUTIVE_LOST; CHR_RESULTS_R_VALUE; CHR_
RESULTS_END_TO_END_DELAY.
For both endpoint 1 and endpoint 2 RSSI, the units are in dBm. Values for E1 are
returned when using non-streaming scripts and for E2 when using streaming scripts.

For DF (Delay Factor), the units are milliseconds.

For MLR (media loss rate), the units are media packets per second.

min [out]
A pointer to the variable where the minimum value is returned.

RETURN CODES
The following return code indicates that the function call was successful:

- 504 -

IxChariot APIGuide
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 505 -

IxChariot APIGuide

CHR_pair_results_get_rel_precision
DESCRIPTION
The CHR_pair_results_get_rel_precision function gets the relative precision from the test
results in the given endpoint pair or multicast pair.
C H R _API_R C
C H R _ pai r_res ul t s _ get _rel _prec i s i on (
C H R _H AN D LE handle,
C H R _FLOAT* prec is ion
)

PARAMETERS
handle [in]
l

For an endpoint pair, the handle returned by CHR_pair_new() or CHR_test_get_pair

().
For a multicast pair, the handle returned by CHR_mpair_new() or CHR_mgroup_get_
mpair().

precision [out]
A pointer to the variable where the relative precision value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_RESULTS

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 506 -

IxChariot APIGuide

Report Object Functions

Report object functions handle information reported back by the endpoint that does not fit
into a timing record. There can be many types of reports, hence the ITEM_TYPE field.
The Join Latency and Leave Latency reports are used by the IPTV functions. These reports
are issued once per test iteration; many timing records may be generated during each iteration.
The REPORT_GROUP_ID field helps associate timing records with reports.

- 507 -

IxChariot APIGuide

CHR_report_get_item_type
DESCRIPTION
The CHR_report_get_item_type function returns the type of the specified report item.
C H R _API_R C
C H R _report _get _i t em _ t y pe(
C H R _R E P OR T _H A N D LE
C H R _R E P OR T _I T E M *
)

i_report H andle,
o_report I t em

PARAMETERS
i_reportHandle [in]
A handle returned by CHR_vpair_get_report().

i_reportItem [out]
A pointer to the variable to which the function returns the report type designation.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 508 -

IxChariot APIGuide

CHR_report_get_join_latency
DESCRIPTION
The CHR_report_get_join_latency
cified report.

function returns the join latency field from the spe-

C H R _API_R C
C H R _report _get _j oi n_ l at enc y (
C H R _R E P OR T _H A N D LE
i_report H andle,
C H R _FLOAT*
o_joinLat enc y
)

PARAMETERS
i_reportHandle [in]
A handle returned by CHR_vpair_get_report().

o_joinLatency [out]
A pointer to the variable to which the function returns the join latency value, in milliseconds.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 509 -

IxChariot APIGuide

CHR_report_get_leave_latency
DESCRIPTION
The CHR_report_get_item_type
cified report.

function returns the leave latency field from the spe-

C H R _API_R C
C H R _report _get _l eav e_l at enc y (
C H R _R E P OR T _H A N D LE
i_report H andle,
C H R _FLOAT*
o_leav eLat enc y
)

PARAMETERS
i_reportHandle [in]
A handle returned by CHR_vpair_get_report().

o_joinLatency [out]
A pointer to the variable to which the function returns the leave latency value, in milliseconds.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 510 -

IxChariot APIGuide

CHR_report_get_report_group_id
DESCRIPTION
The CHR_report_get_report_group_id function returns the report group identifier from
the specified report. The group identifier helps associate timing records with reports.
C H R _API_R C
C H R _report _get _report _ group_i d(
C H R _R E P OR T _H A N D LE
i_report H andle,
C H R _C OU N T*
o_report GroupI d
)

PARAMETERS
i_reportHandle [in]
A handle returned by CHR_vpair_get_report().

o_reportGroupId [out]
A pointer to the variable to which the function returns the report group identifier.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 511 -

IxChariot APIGuide

Run Options Object Functions

Run options object functions are used to define and retrieve the run options that are set for
a specified test. You are not allowed to set run options for a test that has results or while a
test is running.

- 512 -

IxChariot APIGuide

CHR_runopts_get_allow_pair_reinit
DESCRIPTION
The CHR_runopts_get_allow_pair_reinit function returns a pointer that indicates
whether pair reinitialization is allowed as part of the IxChariot test.
C H R _API_R C
C H R _ runopt s _ get _al l ow _ pai r_rei ni t (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * allow PairR einit
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

allowPairReinit[out]
A pointer to the Boolean variable to which the function returns one of the following:
l

CHR_TRUEif pair reinitialization is allowed in the test.

CHR_FALSEif pair reinitialization is not allowed in the test.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 513 -

IxChariot APIGuide

CHR_runopts_get_allow_pair_reinit_run
DESCRIPTION
The CHR_runopts_get_allow_pair_reinit_run function returns a pointer that indicates
whether pair reinitialization is allowed once the IxChariot test has commenced running.
C H R _API_R C
C H R _ ru n o p t s _ g e t _ a l l o w _ p a i r_re i n i t _ ru n(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * allow PairR einit
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

allowPairReinit[out]
A pointer to the Boolean variable to which the function returns one of the following:
l

CHR_TRUEif pair reinitialization is allowed once the IxChariot test has commenced
running.
CHR_FALSEif pair reinitialization is not allowed once the IxChariot test has commenced running.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 514 -

IxChariot APIGuide

CHR_runopts_get_apply_dod_only
DESCRIPTION
The CHR_runopts_get_apply_dod_only function returns a pointer that indicates whether
the "Apply only Endpoint DoD package" run option is set.
C H R _API_R C
C H R _runopt s _get _apply _dod_only (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * iep_dod_only
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

iep_dod_only [out]
A pointer to the Boolean variable to which the function returns one of the following:
l

CHR_TRUEif the "Apply only Endpoint DoD package" run option is enabled.

CHR_FALSEif the "Apply only Endpoint DoD package" run option is disabled.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 515 -

IxChariot APIGuide

CHR_runopts_get_clksync_external
DESCRIPTION
The CHR_runopts_get_clksync_external function returns a pointer that indicates
whether the endpoints in the test are using an external clocking source (such as NTP servers synchronized to the Global Positioning System).
C H R _API_R C
C H R _runopt s _get _c lk s y nc _ex t ernal(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * c lk s y nc _ex t ernal
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

clksync_external [out]
A pointer to the Boolean variable to which the function returns one of the following:
l

CHR_TRUEthe endpoints in the test are using an external clocking source.

CHR_FALSEthe endpoints in the test are not using an external clocking source.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 516 -

IxChariot APIGuide

CHR_runopts_get_clksync_hardware_ts
DESCRIPTION
The CHR_runopts_get_clksync_hardware_ts function returns a pointer that indicates
whether the endpoints in the test will attempt to use hardware timestamps as the timing
source on the Ixia ports. Where this option is not supported, the endpoint internal clock is
used.
C H R _API_R C
C H R _runopt s _get _c l k s y nc _hardw are_t s (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * c lc k s y nc H ardw areTs
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

clcksyncHardwareTs [out]
A pointer to the Boolean variable to which the function returns one of the following:
l

CHR_TRUEif the endpoints in the test will attempt to use hardware time-stamps as
the timing source on the ixia ports.
CHR_FALSEif the endpoints in the test will not use hardware timestamps as the timing source on the ixia ports. In this case, the endpoint internal clock is used.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 517 -

IxChariot APIGuide

CHR_runopts_get_collect_tcp_statistics
DESCRIPTION
The CHR_runopts_get_collect_tcp_statistics function returns a pointer that indicates
whether TCP statistics will be collected as part of the IxChariot test.
C H R _API_R C
C H R _runopt s _get _c ollec t _t c p_s t at is t ic s (
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _B OOLE A N * enabl e_t c p_s t at s
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

enable_tcp_stats [out]
A pointer to the Boolean variable to which the function returns one of the following:
l

CHR_TRUEif TCP statistics are collected.

CHR_FALSEif TCP statistics are not collected.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 518 -

IxChariot APIGuide

CHR_runopts_get_connect_timeout
DESCRIPTION
The CHR_runopts_get_connect_timeout function gets the time in minutes for which connection attempts are retried. A value of zero minutes means no retries are attempted.
C H R _API_R C
C H R _runopt s _get _c onnec t _t imeout(
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _C OU N T* t imeout
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

timeout [out]
A pointer to the variable where the connection timeout is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 519 -

IxChariot APIGuide

CHR_runopts_get_CPU_util
DESCRIPTION
The CHR_runopts_get_CPU_util function gets the option value indicating that endpoints are
collecting CPU utilization (CHR_TRUE) or not collecting (CHR_FALSE).
C H R _API_R C
C H R _runopt s _get _C PU _ut il(
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _BOOLEAN * c pu
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

cpu [out]
A pointer to the true or false Boolean variable that tells whether CPU utilization can be collected.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 520 -

IxChariot APIGuide

CHR_runopts_get_deconfigure_ports
DESCRIPTION
The CHR_runopts_get_deconfigure_ports function gets the option value indicating that the
Ixia ports are deconfigured (CHR_TRUE) or not (CHR_FALSE).
C H R _API_R C
C H R _runopt s _get _dec onf igure_port s(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * f lag)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

flag [out]
A pointer to the true or false Boolean variable that tells whether to deconfigure the Ixia
ports.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 521 -

IxChariot APIGuide

CHR_runopts_get_fewer_setup_connections
DESCRIPTION
The CHR_runopts_get_fewer_setup_connections function gets whether the option to use
fewer setup connections during test initialization is set. If a test has more than 500 pairs,
this option defaults to true. For tests with more than 1250 pairs, this option is set to "true"
and cannot be disabled.
C H R _API_R C
C H R _runopt s _get _f ew er_s et up_c onnec t ions(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * f ew erC onnec t ions
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

fewerConnections[out]
A pointer to the true or false Boolean variable that tells whether the option to use fewer
connections during test setup is set.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NOT_SUPPORTED

See Return Code Summary for a detailed description of each return code.

- 522 -

IxChariot APIGuide

CHR_runopts_get_force_reporting_ack
DESCRIPTION
The CHR_runopts_get_force_reporting_ack function gets whether the option to force an
acknowledgement after each report is set.
C H R _API_R C
C H R _runopt s _get _f orc e_report ing_ac k(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * f lag
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

flag [out]
A pointer to the Boolean variable to which the function returns whether the option to force
an acknowledgement after each report is set.

RETURN CODES
The following return code indicates that the function call was successful:
C H R _OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NOT_SUPPORTED

See Return Code Summary for a detailed description of each return code.

- 523 -

IxChariot APIGuide

CHR_runopts_get_HW_timestamps
DESCRIPTION
The CHR_runopts_get_HW_timestamps function gets a variable that specifies whether the
option to use hardware timestamps during test initialization is set. Hardware timestamps
are used to determine the video test source jitter and account for it in video test DF calculations.
C H R _API_R C
C H R _ runopt s _ get _ H W _t i m es t am ps (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * hw Times t amps
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

hwTimestamps [out]
A pointer to the true or false Boolean variable that tells whether the option to use hardware timestamps during test setup is set.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NOT_SUPPORTED

See Return Code Summary for a detailed description of each return code.

- 524 -

IxChariot APIGuide

CHR_runopts_get_init_recv_timeout
DESCRIPTION
The CHR_runopts_get_init_recv_timeout function gets a variable that returns the value of
the receive timeout for the initialization phase.
C H R _API_R C
C H R _ runopt s _ get _ i ni t _rec v _ t i m eout (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T* v alue
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

value [out]
The value of the initialization receive timeout. Please see CHR_runopts_set_init_recv_
timeout on page 4-428 for the valid range.

RETURN CODES
The following return code indicates that the function call was successful:
C H R _OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NOT_SUPPORTED

See Return Code Summary for a detailed description of each return code.

- 525 -

IxChariot APIGuide

CHR_runopts_get_management_qos_console_name
DESCRIPTION
The CHR_runopts_get_management_qos_console_name function returns the quality of
service template name that the IxChariot test uses for management traffic sent from the
console to Endpoint1.
C H R _API_R C
C H R _runopt s _get _m anagem ent _qos _c ons ol e_nam e(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _STR I N G qos N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

qosName [out]
A pointer to the buffer where the service quality name is returned.

maxLength [in]
The length of the provided buffer.

length [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_BUFFER_TOO_SMALL

See Return Code Summary for a detailed description of each return code.

- 526 -

IxChariot APIGuide

CHR_runopts_get_management_qos_endpoint_name
DESCRIPTION
The CHR_runopts_get_management_qos_endpoint_name function returns the quality of
service template name that the IxChariot test uses for (1) management traffic sent from
Endpoint1 to the console, and (2) management traffic exchanged by Endpoint1 and
Endpoint2.
C H R _API_R C
C H R _runopt s _get _m anagem ent _qos _endpoi nt _ nam e(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _STR I N G qos N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

qosName [out]
A pointer to the buffer where the service quality name is returned.

maxLength [in]
The length of the provided buffer.

length [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_BUFFER_TOO_SMALL

See Return Code Summary for a detailed description of each return code.

- 527 -

IxChariot APIGuide

CHR_runopts_get_num_result_ranges
DESCRIPTION
The CHR_runopts_get_num_result_ranges function gets the number of configurable ranges
for different statistics.
C H R _API_R C
C H R _runopt s _ get _num _res ul t _ranges (
C H R _R U N OPTS_H AN D LE handle,
CHR_RESULTS res ult Ty pe,
C H R _C OU N T *number,
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

resultType [in]
The desired result type. One of the following:
l

CHR_RESULTS_DELAY_VARIATION

CHR_RESULTS_CONSECUTIVE_LOST

If other CHR_RESULTS values are specified, the call returns CHR_VALUE_INVALID.

number [out]
The number of configurable ranges.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 528 -

IxChariot APIGuide

CHR_runopts_get_overlapped_sends_count
DESCRIPTION
The CHR_runopts_get_overlapped_sends_count function gets the number of multiple buffers sent in parallel.
C H R _API_R C
C H R _runopt s _get _ov erl apped_s ends _c ount (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T* v alue)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

value [out]
The number of multiple buffers to send.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 529 -

IxChariot APIGuide

CHR_runopts_get_pair_reinit_max
DESCRIPTION
The CHR_runopts_get_pair_reinit_max function returns a pointer to the variable that
specifies the maximum number of reinitialization attempts that IxChariot will make for a
pair that fails during test initialization.
C H R _API_R C
C H R _ runopt s _ get _pai r_rei ni t _ m ax (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T* pairR einit Max
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

pairReinitMax [out]
A pointer to the variable that specifies the maximum number of reinitialization attempts
that IxChariot will make for a pair that fails during test initialization.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 530 -

IxChariot APIGuide

CHR_runopts_get_pair_reinit_max_run
DESCRIPTION
The CHR_runopts_get_pair_reinit_max_run function returns a pointer to the variable
that specifies the maximum number of reinitialization attempts that IxChariot will make
for a pair that fails while the test is running.
C H R _API_R C
C H R _ ru n o p t s _ g e t _ p a i r_re i n i t _ m a x _ ru n(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T* pairR einit Max
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

pairReinitMax [out]
A pointer to the variable that specifies the maximum number of reinitialization attempts
that IxChariot will make for a pair that fails while the test is running.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 531 -

IxChariot APIGuide

CHR_runopts_get_pair_reinit_retry_interval
DESCRIPTION
The CHR_runopts_get_pair_reinit_retry_interval function returns a pointer to the
variable that specifies the time interval between the reinitialization attempts that
IxChariot will make for a pair that fails during test initialization.
C H R _API_R C
C H R _ runopt s _ get _pai r_rei ni t _ ret ry _ i nt erv al (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T* pairR einit R et ry I nt erv al
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

pairReinitRetryInterval [out]
A pointer to the variable that specifies the time interval between the reinitialization
attempts that IxChariot will make for a pair that fails during test initialization. The interval
is specified in seconds.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 532 -

IxChariot APIGuide

CHR_runopts_get_pair_reinit_retry_interval_run
DESCRIPTION
The CHR_runopts_get_pair_reinit_retry_interval_run function returns a pointer
to the variable that specifies the time interval between the reinitialization attempts that
IxChariot will make for a pair that fails while the test is running.
C H R _API_R C
C H R _ runopt s _ get _pai r_rei ni t _ ret ry _ i nt erv al _run (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T* pairR einit R et ry I nt erv al
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

pairReinitRetryInterval [out]
A pointer to the variable that specifies the time interval between the reinitialization
attempts that IxChariot will make for a pair that fails while the test is running. The interval
is specified in seconds.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 533 -

IxChariot APIGuide

CHR_runopts_get_poll_endpoints
DESCRIPTION
The CHR_runopts_get_poll_endpoints function gets whether the endpoints will be polled
during a test.
C H R _API_R C
C H R _ runopt s _ get _ pol l _endpoi nt s (
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _BOOLEAN * poll
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

poll [out]
A pointer to the true or false Boolean variable that determines whether to poll the endpoints.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 534 -

IxChariot APIGuide

CHR_runopts_get_poll_interval
DESCRIPTION
The CHR_runopts_get_poll_interval function gets the interval in minutes used when endpoints are to be polled.
C H R _API_R C
C H R _ runopt s _ get _ pol l _i nt erv al (
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _C OU N T* int erv al
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

interval [out]
A pointer to the variable where the polling interval is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 535 -

IxChariot APIGuide

CHR_runopts_get_poll_retrieving_type
DESCRIPTION
The CHR_runopts_get_poll_retrieving_type function gets the value of the reporting
type that is in effect for polling.
C H R _API_R C
C H R _ runopt s _ get _ pol l _ret ri ev i ng_ t y pe(
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _ T E S T _ P OLL_T I M I N G_ R E C OR D * pol l _ret ri ev i ng_ t y pe
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

poll_retrieving_type [out]
A pointer to the variable where the retrieving type value is returned. The retrieving type is
one of the following:
l

CHR_TEST_RETRIEVE_NUMBER (Polling retrieves a count of the timing records).

CHR_TEST_RETRIEVE_TIMING_RECORD (Polling retrieves the actual timing records).

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_API_DISABLED

See Return Code Summary for a detailed description of each return code.

- 536 -

IxChariot APIGuide

CHR_runopts_get_random_new_seed
DESCRIPTION
The CHR_runopts_get_random_new_seed function gets whether to reseed the random number generator.
C H R _API_R C
C H R _runopt s _get _random _new _s eed(
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _BOOLEAN * res eed
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

reseed [out]
A pointer to the true or false Boolean variable that tells whether to reseed the random number generator.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 537 -

IxChariot APIGuide

CHR_runopts_get_reporting_firewall
DESCRIPTION
The CHR_runopts_get_reporting_firewall function gets the value that indicates
whether or not there is a firewall between the IxChariot Console and endpoint1.
C H R _API_R C
C H R _runopt s _get _report ing_f irew all(
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _T E S T _ P OLL_F I R E W A LL* report i ng_ f i rew al l
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

reporting_firewall [out]
A pointer to the variable where the value is returned. The reporting_firewall variable takes
one of the following values:
l

CHR_TEST_REPORTING_USE_FIREWALL

CHR_TEST_REPORTING_NO_FIREWALL.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 538 -

IxChariot APIGuide

CHR_runopts_get_reporting_type
DESCRIPTION
The CHR_runopts_get_reporting_type function gets how to report the timing records.
C H R _API_R C
C H R _runopt s _get _report ing_t y pe(
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _TEST_R EPOR TI N G* report ing_t y pe
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

reporting_type [out]
A pointer to variable where the reporting type value is returned. See the "CHR_runopts_
set_reporting_type" function for CHR_TEST_REPORTING values.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 539 -

IxChariot APIGuide

CHR_runopts_get_result_range
DESCRIPTION
The CHR_runopts_get_result_range function gets the values for a specified statistics
bucket ranges.
C H R _API_R C
C H R _runopt s _ get _res ul t _range (
C H R _R U N OPTS_H AN D LE runopt s ,
CHR_RESULTS res ult Ty pe,
C H R _C OU N T index ,
C H R _C OU N T *minValue,
C H R _C OU N T *max Value
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

resultType [in]
The desired statistic type. One of the following:
l

CHR_RESULTS_DELAY_VARIATION

CHR_RESULTS_CONSECUTIVE_LOST

index [in]
The index of the range value to set. The index value can be a value from 0 to the number
of configured ranges1, for a specified result type.
The number of configured ranges can be determined using CHR_runopts_get_num_result_
ranges.

min [out]
The minimum value for this particular range.

max [out]
The maximum value for this particular range.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

- 540 -

IxChariot APIGuide

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_VALUE_INVALID

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 541 -

IxChariot APIGuide

CHR_runopts_get_stop_after_num_pairs_fail
DESCRIPTION
The CHR_runopts_get_stop_after_num_pairs_fail function gets the number of pairs that
must fail to force the test to stop with an error.
C H R _API_R C
C H R _ runopt s _ get _s t op_af t er_ num _ pai rs _ f ai l (
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _C OU N T* num
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

num [out]
A pointer to the variable where the number of pair failures necessary to force stoppage is
returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 542 -

IxChariot APIGuide

CHR_runopts_get_stop_on_init_failure
DESCRIPTION
The CHR_runopts_get_stop_on_init_failure function gets whether the test is to stop on initialization errors.
C H R _API_R C
C H R _ runopt s _ get _ s t op_on_ i ni t _f ai l ure (
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _BOOLEAN * s t op
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

stop [out]
A pointer to the true or false Boolean variable that tells whether to stop on initialization
errors.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 543 -

IxChariot APIGuide

CHR_runopts_get_test_duration
DESCRIPTION
The CHR_runopts_get_test_duration function gets the time in seconds the test is to run.
C H R _API_R C
C H R _ runopt s _ get _t es t _durat i on(
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _C OU N T* durat ion
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

duration [out]
A pointer to the variable where the test duration is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 544 -

IxChariot APIGuide

CHR_runopts_get_test_end
DESCRIPTION
The CHR_runopts_get_test_end function gets the option indicating when the test is to end.
C H R _API_R C
C H R _ runopt s _ get _t es t _end (
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _TEST_EN D * t es t end
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

testend [out]
A pointer to the variable where the test end value is returned. See the CHR_runopts_set_
test_end on page 4-448 function for CHR_TEST_END values.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 545 -

IxChariot APIGuide

CHR_runopts_get_validate_on_recv
DESCRIPTION
The CHR_runopts_get_validate_on_recv function gets whether to validate the data when it
is received.
C H R _API_R C
C H R _runopt s _get _v al i dat e_on_ rec v (
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _BOOLEAN * v alidat e
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

validate [out]
A pointer to the true or false Boolean variable that tells whether to validate the data when
it is received.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 546 -

IxChariot APIGuide

CHR_runopts_set_allow_pair_reinit
DESCRIPTION
The CHR_runopts_set_allow_pair_reinit function sets or changes the option that
determines whether or not pair reinitialization is allowed as part of the IxChariot test.
C H R _API_R C
C H R _ runopt s _ s et _al l ow _ pai r_rei ni t (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN allow PairR einit
)

Refer to "How to Handle Failures" in the IxChariot User Guide for more information about
pair reinitialization.

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

allowPairReinit[in]
Sets one of the following to specify whether or not pair reinitialization is allowed as part of
the IxChariot test:
l

CHR_TRUEThe test will allow pair reinitialization.

CHR_FALSEThe test will not allow pair reinitialization.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 547 -

IxChariot APIGuide

CHR_runopts_set_allow_pair_reinit_run
DESCRIPTION
The CHR_runopts_set_allow_pair_reinit_run function sets or changes the option that
determines whether or not pair reinitialization is allowed once the IxChariot test starts running.
C H R _API_R C
C H R _ ru n o p t s _ s e t _ a l l o w _ p a i r_re i n i t _ ru n(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN allow PairR einit
)

Refer to "How to Handle Failures" in the IxChariot User Guide for more information about
pair reinitialization.

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

allowPairReinit[in]
Sets one of the following to specify whether or not pair reinitialization is allowed as part of
the IxChariot test:
l

CHR_TRUEThe test will allow pair reinitialization once the IxChariot test has commenced running.
CHR_FALSEThe test will not allow pair reinitialization once the IxChariot test has
commenced running.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 548 -

IxChariot APIGuide

CHR_runopts_set_apply_dod_only
DESCRIPTION
The CHR_runopts_set_apply_dod_only function enables or disables the "Apply only Endpoint DoD package" run option. This option applies the endpoint DoD package only, without
applying the configuration.
C H R _API_R C
C H R _runopt s _s et _apply _dod_only (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN ep_dod_only
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

ep_dod_only [in]
Sets the "Apply only Endpoint DoD package" run option to one of the following values:
l

CHR_TRUEenables the "Apply only Endpoint DoD package" run option.

CHR_FALSEdisables the "Apply only Endpoint DoD package" run option.

Setting the function to CHR_TRUE automatically sets CHR_runopts_set_deconfigure_ports

to CHR_FALSE.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 549 -

IxChariot APIGuide

CHR_runopts_set_clksync_external
DESCRIPTION
The CHR_runopts_set_clksync_external function sets an option that specifies whether
the endpoints in the test will use external clocking as the timing source on the Ixia ports.
Note that IxChariot validates neither the presence nor the reliability of the external timing
source.
C H R _API_R C
C H R _runopt s _s et _c lk s y nc _ex t ernal(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN c lk s y nc _ex t ernal
)
When both hardware timestamps and external clocking are set as the timing source on the
Ixia ports, IxChariot first attempts to use hardware timestamps. If the Ixia port hardware
timestamp is not available to a specific endpoint pair, that pair will use the external clock
source. When only external clocking is set, all pairs obtain their timing values from the
external timing source.

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

clksync_external [in]
Sets the Boolean variable to one of the following:
l

CHR_TRUEthe endpoints in the test will use external clocking as the timing source on
the Ixia ports.
CHR_FALSEthe endpoints in the test will not use external clocking as the timing
source on the Ixia ports.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 550 -

IxChariot APIGuide

CHR_runopts_set_clksync_hardware_ts
DESCRIPTION
The CHR_runopts_set_clksync_hardware_ts function sets an option that specifies
whether the endpoints in the test will attempt to use hardware timestamps as the timing
source on the Ixia ports.
C H R _API_R C
C H R _runopt s _s et _c l k s y nc _hardw are_t s (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN c lc k s y nc H ardw areTs
)
When hardware timestamps and external clocking are both set as the timing source on the
Ixia ports, IxChariot first attempts to use hardware timestamps. If the Ixia port hardware
timestamp is not available to a specific endpoint pair, that pair will use the external clock
source.
When only hardware timestamps is set, IxChariot first attempts to use hardware
timestamps. If the Ixia port hardware timestamp is not available to a specific endpoint
pair, that pair will use the endpoint internal clocking.

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

clcksyncHardwareTs [in]
Sets the Boolean variable to one of the following:
l

CHR_TRUEthe endpoints in the test will attempt to use hardware time-stamps as the
timing source on the Ixia ports.
CHR_FALSEthe endpoints in the test will not use hardware timestamps as the timing
source on the Ixia ports.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

- 551 -

IxChariot APIGuide

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 552 -

IxChariot APIGuide

CHR_runopts_set_collect_tcp_statistics
DESCRIPTION
The CHR_runopts_set_collect_tcp_statistics function sets or changes the option that
determines whether TCP statistics will be collected as part of the IxChariot test.
C H R _API_R C
C H R _runopt s _s et _c ollec t _t c p_s t at is t ic s (
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _BOOLEAN enable_t c p_s t at s
)
Collecting TCP statistics requires the following:
l
l

An Ixia chassis running IxOS 3.80 or later,

One of the following load modules: TXS8, TXS4, STXS4, SFPS4, ALM-T8, ELM-ST2,
TXS2, LM10GE700F1B-P, LM622MR, OLM1000STXS24,
TCP traffic running over IPv4.

Refer to "Miscellaneous Run Options" in the IxChariot User Guide for more information
about collecting TCP statistics.

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

enable_tcp_stats [in]
Specifies one of the following to indicate whether the test will collect TCP statistics:
l

CHR_TRUEThe test will collect TCP statistics.

CHR_FALSEThe test will not collect TCP statistics.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 553 -

IxChariot APIGuide

- 554 -

IxChariot APIGuide

CHR_runopts_set_connect_timeout
DESCRIPTION
The CHR_runopts_set_connect_timeout function sets or changes the time in minutes
waited for a connection before it is considered an error.
C H R _API_R C
C H R _runopt s _s et _c onnec t _t imeout(
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _C OU N T t imeout
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

timeout [in]
The time in minutes. The valid range is 1 to 999.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 555 -

IxChariot APIGuide

CHR_runopts_set_CPU_util
DESCRIPTION
The CHR_runopts_set_CPU_util function sets or changes the option that determines
whether endpoints collect CPU utilization data.
C H R _API_R C
C H R _runopt s _s et _C PU _ut il(
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _BOOLEAN c pu
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

cpu [in]
Specifies CHR_TRUE or CHR_FALSE to indicate whether to collect CPU utilization.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 556 -

IxChariot APIGuide

CHR_runopts_set_deconfigure_ports
DESCRIPTION
The CHR_runopts_set_deconfigure_ports function sets or changes the option that determines whether to deconfigure Ixia ports as soon as the test ends.
C H R _API_R C
C H R _runopt s _s et _dec onf igure_port s(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN f lag)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

flag [in]
Specifies CHR_TRUE or CHR_FALSE to indicate whether to deconfigure Ixia ports when test
ends.
The function fails when attempting to set it to CHR_TRUE, if CHR_runopts_set_apply_dod_
only is already set to CHR_TRUE.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 557 -

IxChariot APIGuide

CHR_runopts_set_force_reporting_ack
DESCRIPTION
The CHR_runopts_set_force_reporting_ack function sets whether to force an acknowledgement after each report.
C H R _API_R C
C H R _runopt s _s et _f orc e_report ing_ac k(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN f lag
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

flag [in]
Specifies whether an acknowledgement is sent after each report.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NOT_SUPPORTED

See Return Code Summary for a detailed description of each return code.

- 558 -

IxChariot APIGuide

CHR_runopts_set_fewer_setup_connections
DESCRIPTION
The CHR_runopts_set_fewer_setup_connections function sets whether to use fewer setup
connections during test initialization. If a test contains more than 500 pairs, this option is
automatically set to true, but it can still be changed to false. For tests with more than 1250
pairs, this option is set to "true" and cannot be disabled.
C H R _API_R C
C H R _runopt s _s et _f ew er_s et up_c onnec t ions(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN f ew erC onnec t ions
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

fewerConnections[in]
Specifies CHR_TRUE or CHR_FALSE to indicate whether to use fewer connections during
test setup.

RETURN CODES
The following return code indicates that the function call was successful:
C H R _OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NOT_SUPPORTED

See Return Code Summary for a detailed description of each return code.

- 559 -

IxChariot APIGuide

CHR_runopts_set_HW_timestamps
DESCRIPTION
The CHR_runopts_set_HW_timestamps function specifies whether or not hardware
timestamps will be used during video testing. Hardware timestamps are used to determine
the video test source jitter and account for it in video test DF calculations.
C H R _API_R C
C H R _ runopt s _ s et _ H W _t i m es t am ps (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * hw Times t amps
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_set_runopts().

hwTimestamps [out]
Specifies CHR_TRUE or CHR_FALSE to indicate whether to use hardware time-stamps.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NOT_SUPPORTED

See Return Code Summary for a detailed description of each return code.

- 560 -

IxChariot APIGuide

CHR_runopts_set_init_recv_timeout
DESCRIPTION
The CHR_runopts_set_init_recv_timeout function specifies a receive timeout for the initialization phase.
C H R _API_R C
C H R _ runopt s _ s et _ i ni t _rec v _ t i m eout (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T v alue
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

value [in]
The value of the initialization receive timeout, in seconds. Valid values are in the 1-999
range.

RETURN CODES
The following return code indicates that the function call was successful:
C H R _OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NOT_SUPPORTED

See Return Code Summary for a detailed description of each return code.

- 561 -

IxChariot APIGuide

CHR_runopts_set_management_qos_console_name
DESCRIPTION
The CHR_runopts_set_management_qos_console_name function specifies the quality of
service template name that the IxChariot test will use for the management traffic sent
from the console to Endpoint1.
C H R _API_R C
C H R _runopt s _s et _m anagem ent _qos _c ons ol e_nam e(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _STR I N G qos N ame,
C H R _LEN GTH lengt h
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

qosName [in]
A string containing the quality of service template name.

length [in]
The length of the quality of service name, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_NO_SUCH_OBJECT

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_STRING_TOO_LONG

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 562 -

IxChariot APIGuide

CHR_runopts_set_management_qos_endpoint_name
DESCRIPTION
The CHR_runopts_set_management_qos_endpoint_name function specifies the quality of
service template name that the IxChariot test will use for (1) management traffic sent
from Endpoint1 to the console, and (2) management traffic exchanged by Endpoint1 and
Endpoint2.
C H R _API_R C
C H R _runopt s _s et _m anagem ent _qos _endpoi nt _ nam e(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _STR I N G qos N ame,
C H R _LEN GTH lengt h
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

qosName [in]
A string containing the quality of service template name.

length [in]
The length of the quality of service name, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_NO_SUCH_OBJECT

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_STRING_TOO_LONG

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 563 -

IxChariot APIGuide

CHR_runopts_set_num_result_ranges
DESCRIPTION
The CHR_runopts_set_num_result_ranges function sets the number of ranges into which
different statistics are placed in VoIP test results.
C H R _API_R C
C H R _runopt s _ s et _num _res ul t _ranges (
C H R _R U N OPTS_H AN D LE runopt s ,
CHR_RESULTS res ult Ty pe,
C H R _C OU N T number,
)Paramet ers

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

resultType [in]
The desired result type. One of the following:
l

CHR_RESULTS_DELAY_VARIATION

CHR_RESULTS_CONSECUTIVE_LOST

If other CHR_RESULTS values are specified, the call returns CHR_VALUE_INVALID.

number [in]
The number of configurable ranges. The maximum number of configurable ranges is 5 for
CHR_RESULTS_DELAY_VARIATION and CHR_RESULTS_CONSECUTIVE_LOST. Ranges must
be contiguous. If a number of ranges is set that interferes with the contiguity of configured
ranges, ranges are adjusted to be contiguous.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_VALUE_INVALID

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 564 -

IxChariot APIGuide

- 565 -

IxChariot APIGuide

CHR_runopts_set_overlapped_sends_count
DESCRIPTION
The CHR_runopts_set_overlapped_sends_count function sets the number of multiple buffers sent in parallel.
C H R _API_R C
C H R _runopt s _s et _ov erl apped_s ends _c ount (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T v alue)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

value [in]
The number of multiple buffers to send. Valid values are in the 2-999999 range.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 566 -

IxChariot APIGuide

CHR_runopts_set_pair_reinit_max
DESCRIPTION
The CHR_runopts_set_pair_reinit_max function sets or changes the maximum number
of reinitialization attempts that IxChariot will make for a pair that fails during test initialization.
C H R _API_R C
C H R _ runopt s _ s et _pai r_rei ni t _ m ax (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T pairR einit Max
)
See also CHR_runopts_set_pair_reinit_max_run on page 4-434.

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

pairReinitMax [in]
The maximum number of reinitialization attempts that IxChariot will make for a pair that
fails during test initialization. Accepted values are in the 1-99999 range.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 567 -

IxChariot APIGuide

CHR_runopts_set_pair_reinit_max_run
DESCRIPTION
The CHR_runopts_set_pair_reinit_max_run function sets or changes the maximum
number of reinitialization attempts that IxChariot will make for a pair that fails while the
test is running.
C H R _API_R C
C H R _ ru n o p t s _ s e t _ p a i r_re i n i t _ m a x _ ru n(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T pairR einit Max
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

pairReinitMax [in]
The maximum number of reinitialization attempts that IxChariot will make for a pair that
fails while the test is running. Accepted values are in the 1-99999 range.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 568 -

IxChariot APIGuide

CHR_runopts_set_pair_reinit_retry_interval
DESCRIPTION
The CHR_runopts_set_pair_reinit_retry_interval function sets or changes the time
interval between the reinitialization attempts that IxChariot will make for a pair that fails
during test initialization.
C H R _API_R C
C H R _ runopt s _ s et _pai r_rei ni t _ ret ry _ i nt erv al (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T pairR einit R et ry I nt erv al
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

pairReinitRetryInterval [in]
The time interval between the reinitialization attempts that IxChariot will make for a pair
that fails during test initialization. The interval is specified in seconds. The accepted values
are in the 1-99999 range.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 569 -

IxChariot APIGuide

CHR_runopts_set_pair_reinit_retry_interval_run
DESCRIPTION
The CHR_runopts_set_pair_reinit_retry_interval_run function sets or changes the
time interval between the reinitialization attempts that IxChariot will make for a pair that
fails while the test is running.
C H R _API_R C
C H R _ runopt s _ s et _pai r_rei ni t _ ret ry _ i nt erv al _run (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T pairR einit R et ry I nt erv al
)

PARAMETERS
runOptionsHandle [in]
A handle returned by CHR_test_get_runopts().

pairReinitRetryInterval [in]
The time interval between the reinitialization attempts that IxChariot will make for a pair
that fails while the test is running. The interval is specified in seconds. Accepted values are
in the 1-99999 range.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 570 -

IxChariot APIGuide

CHR_runopts_set_poll_endpoints
DESCRIPTION
The CHR_runopts_set_poll_endpoints function sets or changes whether to poll the endpoints.
C H R _API_R C
C H R _ runopt s _ s et _ pol l _endpoi nt s (
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _BOOLEAN poll
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

poll [in]
Specifies CHR_TRUE or CHR_FALSE to indicate whether to poll the endpoints.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 571 -

IxChariot APIGuide

CHR_runopts_set_poll_interval
DESCRIPTION
The CHR_runopts_set_poll_interval function sets or changes the interval in minutes used
when endpoints are to be polled. This attribute applies only when the poll endpoints option
is set to CHR_TRUE.
C H R _API_R C
C H R _ runopt s _ s et _ pol l _i nt erv al (
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _C OU N T int erv al
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

interval [in]
The polling interval in minutes. The valid range is 1 to 9999.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_VALUE_INVALID

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 572 -

IxChariot APIGuide

CHR_runopts_set_poll_retrieving_type
DESCRIPTION
The CHR_runopts_set_poll_retrieving_type function sets the value of the reporting
type that IxChariot will use when polling the endpoints during a test.
C H R _API_R C
C H R _ runopt s _ s et _ pol l _ret ri ev i ng_ t y pe(
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _T E S T _ R E T R I E V I N G pol l _ ret ri ev i ng_t y pe
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

poll_retrieving_type [in]
One of the CHR_POLL_RETRIEVING values:
l

CHR_TEST_RETRIEVE_NUMBER (Polling retrieves a count of the timing records).

CHR_TEST_RETRIEVE_TIMING_RECORD (Polling retrieves the actual timing records).

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_API_DISABLED

See Return Code Summary for a detailed description of each return code.

- 573 -

IxChariot APIGuide

CHR_runopts_set_random_new_seed
DESCRIPTION
The CHR_runopts_set_random_new_seed function sets or changes whether to reseed the
random number generator.
C H R _API_R C
C H R _runopt s _s et _random _new _s eed(
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _BOOLEAN res eed
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

reseed [in]
Specifies CHR_TRUE or CHR_FALSE to indicate whether to reseed the random number generator.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_VALUE_INVALID

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 574 -

IxChariot APIGuide

CHR_runopts_set_reporting_firewall
DESCRIPTION
The CHR_runopts_set_reporting_firewall function sets the value that indicates
whether or not there is a firewall between the IxChariot Console and endpoint1.
C H R _API_R C
C H R _runopt s _s et _report ing_f irew all(
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _TEST_R EPOR TI N G_FI R EW ALL report ing_f irew all
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

reporting_firewall [in]
The reporting_firewall variable takes one of the following values:
l

CHR_TEST_REPORTING_USE_FIREWALL

CHR_TEST_REPORTING_NO_FIREWALL.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_OBJECT_IN_USE

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 575 -

IxChariot APIGuide

CHR_runopts_set_reporting_type
DESCRIPTION
The CHR_runopts_set_reporting_type function sets how to report the timing records.
C H R _API_R C
C H R _runopt s _s et _report ing_t y pe(
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _TEST_R EPOR TI N G report ing_t y pe
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

reporting_type [in]
One of the CHR_REPORTING values:
l

CHR_TEST_REPORTING_BATCH or

CHR_TEST_REPORTING_REALTIME.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_VALUE_INVALID

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 576 -

IxChariot APIGuide

CHR_runopts_set_result_range
DESCRIPTION
The CHR_runopts_set_result_range function sets the range of values for a given statistic.
C H R _API_R C
C H R _runopt s _ s et _res ul t _range (
C H R _R U N OPTS_H AN D LE runopt s ,
CHR_RESULTS res ult Ty pe,
C H R _C OU N T index ,
C H R _C OU N T minValue,
C H R _C OU N T max Value,
)
The maximum value for a range must be greater than the minimum value. The maximum
value is infinite -CHR_INFINITE. This value indicates a range of everything above a certain
value.
The minimums for the index 0 ranges are as follows:
l

CHR_RESULTS_DELAY_VARIATION -min=0

CHR_CONSECUTIVE_LOST -min=1

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

resultType [in]
The desired statistic type. One of the following:
l

CHR_RESULTS_DELAY_VARIATION

CHR_RESULTS_CONSECUTIVE_LOST

index [in]
The index of the range value to set. The index value can be a value from 0 to the number
of configured ranges1, for a specified result type.
The number of configured ranges can be determined using CHR_runopts_get_num_result_
ranges.

min [in]
The minimum value for this particular range. All ranges must be increasing and contiguous. This value is currently ignored and is set to the previous range's maximum value
+ 1.

max [in]
The maximum value for this particular range. Ranges must be contiguous. If a change is
made to the maximum range that ends the contiguity of the lower ranges, the lower
ranges are adjusted to be contiguous.

- 577 -

IxChariot APIGuide

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_VALUE_INVALID

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 578 -

IxChariot APIGuide

CHR_runopts_set_stop_after_num_pairs_fail
DESCRIPTION
The CHR_runopts_set_stop_after_num_pairs_fail function sets or changes the number of
pairs that must fail to force the test to stop with an error.
C H R _API_R C
C H R _ runopt s _ s et _s t op_af t er_ num _ pai rs _ f ai l (
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _C OU N T num
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

num [in]
The number of pair failures necessary to force a stop. The valid range is 1 to 9999.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_VALUE_INVALID

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 579 -

IxChariot APIGuide

CHR_runopts_set_stop_on_init_failure
DESCRIPTION
The CHR_runopts_set_stop_on_init_failure function sets or changes whether the test is to
stop on initialization errors.
C H R _API_R C
C H R _ runopt s _ s et _ s t op_on_ i ni t _f ai l ure (
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _BOOLEAN s t op
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

stop [in]
Provides a CHR_TRUE or CHR_FALSE.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_VALUE_INVALID

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 580 -

IxChariot APIGuide

CHR_runopts_set_test_duration
DESCRIPTION
The CHR_runopts_set_test_duration function sets or changes the test duration in seconds.
This attribute applies only when the CHR_RUNOPTS_SET_TEST_END is set to CHR_END_
AFTER_FIXED_DURATION.
C H R _API_R C
C H R _ runopt s _ s et _t es t _durat i on(
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _C OU N T durat ion
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

duration [in]
The time in seconds to run the test. The valid range is 1 to 359,999.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_VALUE_INVALID

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 581 -

IxChariot APIGuide

CHR_runopts_set_test_end
DESCRIPTION
The CHR_runopts_set_test_end function sets or changes how the test is to end.
C H R _API_R C
C H R _ runopt s _ s et _t es t _end (
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _TEST_EN D t es t end
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

testend [in]
Provides one of the CHR_TEST_END values:
l

CHR_TEST_END_WHEN_FIRST_COMPLETES

CHR_TEST_END_WHEN_ALL_COMPLETE

CHR_TEST_END_AFTER_FIXED_DURATION

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_VALUE_INVALID

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 582 -

IxChariot APIGuide

CHR_runopts_set_validate_on_recv
DESCRIPTION
The CHR_runopts_set_validate_on_recv function sets or changes whether data is to be validated at the endpoint as it is received.
C H R _API_R C
C H R _runopt s _s et _v al i dat e_on_ rec v (
C H R _R U N OPTS_H AN D LE runopt s ,
C H R _BOOLEAN v alidat e
)

PARAMETERS
runopts [in]
A handle returned by CHR_test_get_runopts().

validate [in]
Specifies CHR_TRUE or CHR_FALSE.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_VALUE_INVALID

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 583 -

IxChariot APIGuide

Test Object Functions

The test object functions are used to define and retrieve information about a test and to
control the running of tests. You cannot add pairs or multicast groups to a test that has results. A test must have at least one pair or multicast group before it can be saved or run.

- 584 -

IxChariot APIGuide

CHR_test_abandon
DESCRIPTION
The CHR_test_abandon function abandons running the given test. This call returns immediately, perhaps before the test has stopped. Use CHR_test_query_stop() to determine
when the test has stopped.
This function should be used as a last resort to stop a test, as it can prevent some test
resources from being relinquished. Always try CHR_test_stop() first to stop a test.
C H R _API_R C
C H R _ t es t _abandon (
C H R _TEST_H AN D LE t es t
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OPERATION_FAILED*

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 585 -

IxChariot APIGuide

CHR_test_add_app_group
DESCRIPTION
The CHR_test_add_app_group function adds the given application group to the given
test.
C H R _API_R C
C H R _ t es t _add_ app_ group (
C H R _TEST_H AN D LE t es t H andle,
C H R _APP_GR OU P_H AN D LE appGroupH andle
)

PARAMETERS
testHandle [in]
A handle returned by CHR_test_new().

appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().
The application group handle is checked to ensure that it refers to a properly defined application group before it is added to the test. An application group handle can be added to only
one test, and can be added only once to that test.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_APP_GROUP_DUPLICATE_NAME

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PAIR_LIMIT_EXCEEDED

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

CHR_SCRIPT_TOO_LARGE

See Return Code Summary for a detailed description of each return code.

- 586 -

IxChariot APIGuide
When CHR_OBJECT_INVALID is returned, extended error information provides details of
the operation failure. Use CHR_common_error_get_info to get this extended error information.

- 587 -

IxChariot APIGuide

CHR_test_add_channel
DESCRIPTION
The CHR_test_add_channel function adds an IPTV channel object to the specified test.
C H R _API_R C
C H R _ t es t _add_ c hannel (
C H R _T E S T _H A N D LE
C H R _C H AN N EL_H AN D LE
)

i_t es t H andle,
i_c hannelH andle

PARAMETERS
i_testHandle [in]
A handle returned by CHR_test_new().

i_channelHandle [in]
A handle returned by CHR_channel_new().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PAIR_LIMIT_EXCEEDED

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

CHR_SCRIPT_TOO_LARGE

CHR_CHANNEL_DUPLICATE_NAME

See Return Code Summary for a detailed description of each return code.

- 588 -

IxChariot APIGuide

CHR_test_add_mgroup
DESCRIPTION
The CHR_test_add_mgroup function adds the given multicast group to the given test.
C H R _API_R C
C H R _ t es t _add_ m group(
C H R _TEST_H AN D LE t es t ,
C H R _MGR OU P_H AN D LE mgroup
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

mgroup [in]
A handle returned by CHR_mgroup_new(). The multicast group handle is checked to
ensure that it refers to a properly defined multicast group before the group is added to the
test, including a valid multicast address and port, and a valid script filename. A multicast
group handle can only be added to one test, and can only be added once to that test.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PAIR_LIMIT_EXCEEDED

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

CHR_SCRIPT_TOO_LARGE
Use CHR_common_error_get_info to get the extended error information available for this return code.

See Return Code Summary for a detailed description of each return code.

- 589 -

IxChariot APIGuide

CHR_test_add_pair
DESCRIPTION
The CHR_test_add_pair function adds the given pair to the given test.
C H R _API_R C
C H R _ t es t _add_ pai r(
C H R _TEST_H AN D LE t es t ,
C H R _PAI R _H AN D LE pair
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

pair [in]
A handle returned by CHR_pair_new(). The endpoint pair handle is checked to ensure that
it refers to a properly defined endpoint pair before the pair is added to the test, including
defined endpoint addresses and a valid script filename. A pair handle can only be added to
one test, and can only be added once to that test.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID

CHR_PAIR_LIMIT_EXCEEDED

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

CHR_SCRIPT_TOO_LARGE
Use CHR_common_error_get_info to get the extended error information available for this return code.

See Return Code Summary for a description of each return code.

- 590 -

IxChariot APIGuide

CHR_test_add_receiver
DESCRIPTION
The CHR_test_add_receiver function adds an IPTV receiver object to the specified test.
C H R _API_R C
C H R _ t es t _add_ rec ei v er(
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle
)

PARAMETERS
i_testHandle [in]
A handle returned by CHR_test_new().

i_receiverHandle [in]
A handle returned by CHR_receiver_new().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PAIR_LIMIT_EXCEEDED

CHR_PGM_INTERNAL_ERROR

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

CHR_SCRIPT_TOO_LARGE

CHR_RECEIVER_DUPLICATE_NAME

See Return Code Summary for a detailed description of each return code.

- 591 -

IxChariot APIGuide

CHR_test_clear_results
DESCRIPTION
The CHR_test_clear_results function clears all the results from the test, the multicast pairs
in its multicast groups, and its pairs. If the test contains results, a test object cannot be
deleted, pairs and multicast groups cannot be added to the test, and the associated run
options and datagram options cannot be changed.
C H R _API_R C
C H R _ t es t _c l ear_ res ul t s (
C H R _TEST_H AN D LE t es t
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 592 -

IxChariot APIGuide

CHR_test_delete
DESCRIPTION
The CHR_test_delete function frees all memory associated with the given test. This
includes all objects associated with the test including endpoint pairs and multicast groups.
If the test has not been saved since it was defined, modified or was run, it cannot be
deleted.
C H R _API_R C
C H R _ t es t _del et e(
C H R _TEST_H AN D LE t es t
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_OPERATION_FAILED*

CHR_PGM_INTERNAL_ERROR

CHR_TEST_RUNNING

CHR_TEST_NOT_SAVED

Use CHR_common_error_get_info to get the extended error information available for this
return code.
See Return Code Summary for a detailed description of each return code.

- 593 -

IxChariot APIGuide

CHR_test_force_delete
DESCRIPTION
The CHR_test_force_delete function frees all memory associated with the given test. This
includes all objects associated with this test including endpoint pairs and multicast groups.
This function will delete the test object whether or not it has been saved.
C H R _API_R C
C H R _ t es t _f orc e_ del et e(
C H R _TEST_H AN D LE t es t
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OPERATION_FAILED*

CHR_PGM_INTERNAL_ERROR

CHR_TEST_RUNNING

Use CHR_common_error_get_info to get the extended error information available for this
return code.
See Return Code Summary for a detailed description of each return code.

- 594 -

IxChariot APIGuide

CHR_test_get_app_group_by_index
DESCRIPTION
The CHR_test_get_app_group_by_index function gets the handle to a specific application group in the given test. The handle returned by this function is needed for other function calls to operate on this object.
C H R _API_R C
C H R _ t es t _get _app_ group_ by _ i ndex (
C H R _TEST_H AN D LE t es t H andle,
C H R _C OU N T index ,
C H R _APP_GR OU P_H AN D LE* appGroupH andle
)

PARAMETERS
testHandle [in]
A handle returned by CHR_test_new().

index [in]
An index into the application group list. The index is determined by the order in which
application groups were added to this test.

appGroupHandle [out]
A pointer to the variable where the handle for the application group is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 595 -

IxChariot APIGuide

CHR_test_get_app_group_by_name
DESCRIPTION
The CHR_test_get_app_group_by_name function gets the handle to a specific application
group in the given test. The handle returned by this function is needed for other function
calls to operate on this object.
C H R _API_R C
C H R _ t es t _get _app_ group_ by _ nam e(
C H R _TEST_H AN D LE t es t H andle,
C H R _STR I N G name,
C H R _LEN GTH nameLengt h,
C H R _APP_GR OU P_H AN D LE* appGroupH andle
)

PARAMETERS
testHandle [in]
A handle returned by CHR_test_new().

name [in]
A string containing the name of the application group.

varNameLength [in]
The length of the string that contains the application group name, excluding the null terminator.

appGroupHandle [out]
A pointer to the variable where the handle for the application group is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 596 -

IxChariot APIGuide

CHR_test_get_app_group_count
DESCRIPTION
The CHR_test_get_app_group_count function gets the number of endpoint pairs owned
by the given test.
C H R _API_R C
C H R _ t es t _get _app_ group_ c ount (
C H R _TEST_H AN D LE t es t H andle,
C H R _C OU N T* appGroupC ount
)

PARAMETERS
testHandle [in]
A handle returned by CHR_test_new().

appGroupCount [out]
A pointer to the variable where the number of pairs is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 597 -

IxChariot APIGuide

CHR_test_get_channel
DESCRIPTION
The CHR_test_get_channel function gets the specified IPTV channel object from the
test. The handle returned by this function is needed for other function calls to operate on
this object.
C H R _API_R C
C H R _ t es t _get _c hannel (
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _C OU N T
i_lis t I ndex ,
C H R _C H AN N EL_H AN D LE*
o_c hannelH andle
)

PARAMETERS
i_testHandle [in]
A handle returned by CHR_test_new().

i_listIndex [in]
Index of the item in the list of channel objects, in the following range:
0..channel_count-1.

o_channelHandle [out]
A pointer to the variable where the handle of the requested channel object is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 598 -

IxChariot APIGuide

CHR_test_get_channel_by_name
DESCRIPTION
The CHR_test_get_channel_by_name function gets the IPTV channel object with the specified name from the test. The handle returned by this function is needed for other function
calls to operate on this object.
C H R _API_R C
C H R _ t es t _get _c hannel _ by _ nam e(
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _C ON ST_STR I N G
i_c hannelN ame,
C H R _LEN GTH
i_nameLengt h,
C H R _C H AN N EL_H AN D LE*
o_c hannelH andle
)

PARAMETERS
i_testHandle [in]
A handle returned by CHR_test_new().

i_channelName [in]
String specifying the name of the channel.

i_nameLength [in]
Length of the channel name string.

o_channelHandle [out]
A pointer to the variable where the handle of the requested channel object is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 599 -

IxChariot APIGuide

CHR_test_get_channel_count
DESCRIPTION
The CHR_test_get_channel_count function returns a count of the IPTV channel objects
in the specified test.
C H R _API_R C
C H R _ t es t _get _c hannel _ c ount (
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _C OU N T*
o_c hannelC ount
)

PARAMETERS
i_testHandle [in]
A handle returned by CHR_test_new().

o_channelCount [out]
A pointer to the variable where the count of the channel objects is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 600 -

IxChariot APIGuide

CHR_test_get_dgopts
DESCRIPTION
The CHR_test_get_dgopts function gets the handle to the datagram options for the given
test. The handle returned by this function is needed for other function calls to operate on
this object.
C H R _API_R C
C H R _ t es t _get _dgopt s (
C H R _TEST_H AN D LE t es t ,
C H R _D GOPTS_H AN D LE *dgopt s
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

dgopts[out]
A pointer to the variable where the handle to the datagram options is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 601 -

IxChariot APIGuide

CHR_test_get_filename
DESCRIPTION
The CHR_test_get_filename function gets the name of the file from which this test was
loaded or to which it is to be saved.
C H R _API_R C
C H R _ t es t _get _f i l enam e(
C H R _TEST_H AN D LE t es t ,
C H R _STR I N G *buf ,
C H R _LEN GTH len,
C H R _LEN GTH *rt nlen
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

buf [out]
A pointer to the buffer where the filename is returned. The returned filename includes any
specified path information.

len [in]
The length of the provided buffer.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_BUFFER_TOO_SMALL

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 602 -

IxChariot APIGuide

CHR_test_get_grouping
DESCRIPTION
The CHR_test_get_grouping function gets the grouping order and grouping type, for grouping endpoints in the test. See also CHR_test_set_grouping_order and CHR_test_set_grouping_type.
C H R _API_R C
C H R _ t es t _get _groupi ng(
C H R _TEST_H AN D LE t es t H andle,
C H R _GR OU PI N G_ TYPE *groupingTy pe,
C H R _SOR T_OR D ER *groupingOrder
)

PARAMETERS
testHandle [in]
A handle returned by CHR_test_new().

groupingOrder [out]
sortOrder can have one of the following values:
l

CHR_SORT_ORDER_ASCENDING

CHR_SORT_ORDER_DESCENDING

groupingType [out]
See values listed under CHR_test_set_grouping_type.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_OPERATION_FAILED*

CHR_PGM_INTERNAL_ERROR
Use CHR_common_error_get_info to get the extended error information available for this return code.

See Return Code Summary for a detailed description of each return code.

- 603 -

IxChariot APIGuide

CHR_test_get_how_ended
DESCRIPTION
The CHR_test_get_how_ended function gets the value indicating how the test ended.
C H R _API_R C
C H R _ t es t _get _how _ ended (
C H R _TEST_H AN D LE t es t ,
C H R _TEST_H OW _EN D ED *ended
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

ended [out]
A pointer to the variable where the test ended value is returned. See Typedefs and Enumerations for CHR_TEST_HOW_ENDED values.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 604 -

IxChariot APIGuide

CHR_test_get_local_start_time
DESCRIPTION
The CHR_test_get_local_start_time function gets the time the test started.
C H R _API_R C
C H R _ t es t _get _l oc al _ s t art _ t i m e(
C H R _TEST_H AN D LE t es t ,
s t ruc t t m* loc al_s t art _t ime
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

local_start_time [out]
A pointer to the structure of type tm where the test start time is returned. This structure
can be used as a parameter to the asctime() C function that converts time to a character
string.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 605 -

IxChariot APIGuide

CHR_test_get_local_stop_time
DESCRIPTION
The CHR_test_get_local_stop_time function gets the time the test stopped.
C H R _API_R C
C H R _ t es t _get _l oc al _ s t op_ t i m e(
C H R _TEST_H AN D LE t es t ,
s t ruc t t m * l oc al _ s t op_t i m e
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

local_stop_time [out]
A pointer to the structure of type tm where the test stop time is returned. This structure
can be used as a parameter to the asctime() C function that converts time to a character
string.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 606 -

IxChariot APIGuide

CHR_test_get_mgroup
DESCRIPTION
The CHR_test_get_mgroup function gets the handle to a specific multicast group in the
given test. The handle returned by this function is needed for other function calls to operate on this object.
C H R _API_R C
CHR_test_get_mgroup(
C H R _TEST_H AN D LE t es t ,
C H R _C OU N T index ,
C H R _MGR OU P_H AN D LE* mgroup
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

index [in]
An index into the array of multicast groups. The index is determined by the order in which
mgroups were added to this test.

mgroup [out]
A pointer to the variable where the handle for the multicast group is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 607 -

IxChariot APIGuide

CHR_test_get_mgroup_count
DESCRIPTION
The CHR_test_get_mgroup_count function gets the number of multicast groups owned by
the given test.
C H R _API_R C
CHR_test_get_mgroup_ c ount(
C H R _TEST_H AN D LE t es t ,
C H R _C OU N T* num
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

num [out]
A pointer to the variable where the number of multicast groups is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 608 -

IxChariot APIGuide

CHR_test_get_pair
DESCRIPTION
The CHR_test_get_pair function gets the handle to a specific endpoint pair in the given
test. The handle returned by this function is needed for other function calls to operate on
this object.
C H R _API_R C
C H R _ t es t _get _pai r(
C H R _TEST_H AN D LE t es t ,
C H R _C OU N T index ,
C H R _PAI R _H AN D LE* pair
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

index [in]
An index into the endpoint pairs list. The index is determined by the order in which pairs
were added to this test.

pair [out]
A pointer to the variable where the handle for the endpoint pair is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 609 -

IxChariot APIGuide

CHR_test_get_pair_count
DESCRIPTION
The CHR_test_get_pair_count function gets the number of endpoint pairs owned by the
given test.
C H R _API_R C
C H R _ t es t _get _pai r_ c ount (
C H R _TEST_H AN D LE t es t ,
C H R _C OU N T* num
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

num [out]
A pointer to the variable where the number of pairs is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 610 -

IxChariot APIGuide

CHR_test_get_receiver
DESCRIPTION
The CHR_test_get_receiver function returns the specified IPTV receiver from the specified test.
C H R _API_R C
C H R _ t es t _get _rec ei v er(
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _C OU N T
i_lis t I ndex ,
C H R _R E C E I V E R _H A N D LE *
o_rec eiv erH andle
)

PARAMETERS
i_testHandle [in]
A handle returned by CHR_test_new().

i_listIndex [in]
Index of the item in the list of receiver objects, in the following range:
0..receiver_count-1.

o_receiverHandle [out]
A pointer to the variable where the handle of the requested receiver object is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 611 -

IxChariot APIGuide

CHR_test_get_receiver_by_name
DESCRIPTION
The CHR_test_get_receiver_by_name function returns the IPTV receiver object with the
specified name from the specified test.
C H R _API_R C
C H R _ t es t _get _ rec ei v er_ by _nam e(
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _C ON ST_STR I N G
i_rec eiv erN ame,
C H R _LEN GTH
i_nameLengt h,
C H R _R E C E I V E R _H A N D LE *
o_rec eiv erH andle
)

PARAMETERS
i_testHandle [in]
A handle returned by CHR_test_new().

i_receiverName [in]
String specifying the name of the receiver.

i_nameLength [in]
Length of the receiver name string.

o_receiverHandle [out]
A pointer to the variable where the handle of the requested receiver object is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 612 -

IxChariot APIGuide

CHR_test_get_receiver_count
DESCRIPTION
The CHR_test_get_receiver_count function returns a count of the IPTV receiver objects
in the specified test.
C H R _API_R C
C H R _ t es t _get _rec ei v er_ c ount (
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _C OU N T*
o_rec eiv erC ount
)

PARAMETERS
i_testHandle [in]
A handle returned by CHR_test_new().

o_receiverCount [out]
A pointer to the variable where the count of the receiver objects is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 613 -

IxChariot APIGuide

CHR_test_get_runopts
DESCRIPTION
The CHR_test_get_runopts function gets the handle to the run options for the given test.
The handle returned by this function is needed for other function calls to operate on this
object.
C H R _API_R C
C H R _ t es t _get _runopt s (
C H R _TEST_H AN D LE t es t ,
C H R _R U N OPTS_H AN D LE* runopt s
)

PARAMETERS
RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 614 -

IxChariot APIGuide

CHR_test_get_start_time
DESCRIPTION
The CHR_test_get_start_time function gets the time the test started.
C H R _API_R C
C H R _ t es t _get _s t art _ t i m e(
C H R _TEST_H AN D LE t es t ,
t ime_t * s t art _t ime
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

start_time [out]
A pointer to the variable where the start time is returned. Time is returned as the number
of seconds since midnight, January 1, 1970 (that is, a "ctime" value).
The "ctime" value can vary depending on the compiler you use. If you are using
a compiler other than the IBM VisualAge for C++ compiler, we recommend you
use CHR_test_get_local_start_time() to obtain the correct local time.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 615 -

IxChariot APIGuide

CHR_test_get_stop_time
DESCRIPTION
The CHR_test_get_stop_time function gets the time the test stopped.
C H R _API_R C
C H R _ t es t _get _s t op_ t i m e(
C H R _TEST_H AN D LE t es t ,
t ime_t * s t op_t ime
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

stop_time [out]
A pointer to the variable where the stop time is returned. Time is returned as the number
of seconds since midnight, January 1, 1970 (that is, a "ctime" value).
The "ctime" value can vary depending upon the compiler you use. If you are
using a compiler other than the IBM VisualAge for C++ compiler, we recommend you use CHR_test_get_local_stop_time() to obtain the correct local time.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 616 -

IxChariot APIGuide

CHR_test_get_test_server_session
DESCRIPTION
The CHR_test_get_test_server_session function gets the TestServer address, port,
and Object ID for the Aptixia session that is currently active in the test.
C H R _API_R C
C H R _ t es t _get _t es t _ s erv er_s es s i on (
C H R _TEST_H AN D LE t es t H andle,
C H R _STR I N G t es t Serv erAddres s ,
C H R _C OU N T t es t Serv erAddres s Max Siz e,
C H R _C OU N T * t es t Serv erAddres s Siz e,
C H R _C OU N T * t es t Serv erPort
C H R _W LON G * s es s ionObjec t I d
)

PARAMETERS
testHandle [in]
A handle returned by CHR_test_new().

testServerAddress [out]
The returned test server address.

testServerAddressMaxSize [in]
The size of the testServerAddress buffer.

testServerAddressSize [out]
The length of the returned string.

testServerPort [out]
The returned TCP port.

sessionObjectId [out]
The returned 64-bit Object ID of the session.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_ERROR_ACCESSING_TESTSERVER_SESSION

- 617 -

IxChariot APIGuide

CHR_NO_NETWORK_CONFIGURATION

CHR_ERROR_ACCESSING_TESTSERVER_SESSION is returned if there is a problem locating the

session object on the TestServer.
See Return Code Summary for a detailed description of each return code.

- 618 -

IxChariot APIGuide

CHR_test_get_throughput_units
DESCRIPTION
The function CHR_test_get_throughput_units gets the throughput units defined for the
given test.
C H R _API_R C
C H R _ t es t _get _t hroughput _ uni t s (
C H R _TEST_H AN D LE t es t ,
C H R _TH R OU GH PU T_U N I TS* unit s
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

units[out]
A pointer to the variable where the throughput unit value is returned. See the "CHR_test_
set_throughput_units" function for information on valid throughput unit values.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 619 -

IxChariot APIGuide

CHR_test_load
DESCRIPTION
The CHR_test_load function loads a test from the given file. This function uses the run
options that have been defined for the test.
C H R _API_R C
C H R _ t es t _l oad(
C H R _TEST_H AN D LE t es t ,
C H R _STR I N G f ilename,
C H R _LE N GT H f i l enam e_l en
)

PARAMETERS
test [in]
A handle returned by CHR_test_new(). A test cannot be loaded using an existing test
handle unless the test to which the handle refers has been saved or has not been modified
since it was loaded.

filename [in]
A string containing the name of the file from which to load the test.

filename_len [in]
The length of the file from which to load the test. The maximum length of the test filename
is 602 with a null terminator.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_OPERATION_FAILED*

CHR_PAIR_LIMIT_EXCEEDED

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_STRING_TOO_LONG

CHR_VALUE_INVALID

CHR_TEST_RUNNING

- 620 -

IxChariot APIGuide
Use CHR_common_error_get_info to get the extended error information available for this
return code.
See Return Code Summary for a detailed description of each return code.

- 621 -

IxChariot APIGuide

CHR_test_load_app_groups
DESCRIPTION
The CHR_test_load_app_groups function loads a test from the given file.
C H R _API_R C
C H R _ t es t _l oad_ app_ groups (
C H R _TEST_H AN D LE t es t H andle,
C H R _STR I N G f ilename,
C H R _LEN GTH f ilenameLengt h
)

PARAMETERS
testHandle [in]
A handle returned by CHR_test_new(). A test cannot be loaded using an existing test
handle unless the test to which the handle refers has been saved or has not been modified
since it was loaded.

filename [in]
A string containing the name of the file from which to load the test.

filenameLength [in]
The length of the file from which to load the test. The maximum length of the test filename
is 602 with a null terminator.

RETURN CODES
The following return code indicates that the function call was successful:
C H R _OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_APP_GROUP_DUPLICATE_NAME

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_OPERATION_FAILED*

CHR_PGM_INTERNAL_ERROR

CHR_PAIR_LIMIT_EXCEEDED

CHR_POINTER_INVALID

CHR_STRING_TOO_LONG

CHR_VALUE_INVALID

CHR_TEST_RUNNING

See Return Code Summary for a detailed description of each return code.

- 622 -

IxChariot APIGuide
When CHR_OBJECT_INVALID is returned, extended error information provides details of
the operation failure. Use CHR_common_error_get_info to get this extended error information.

- 623 -

IxChariot APIGuide

CHR_test_new
DESCRIPTION
The CHR_test_new function creates a test object and its associated run options and datagram options objects, and initializes them to object default values. Note that the object
defaults do not use the default values specified in the Chariot Options Menu. See Test
Object on page 2-7 for information on the object default values.
C H R _API_R C
CHR_test_new (
C H R _TEST_H AN D LE* t es t
)

PARAMETERS
test [out]
A pointer to the variable where the handle for the new test is returned. This handle is
needed for other function calls to operate on this object.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_OUT_OF_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 624 -

IxChariot APIGuide

CHR_test_query_stop
DESCRIPTION
The CHR_test_query_stop function waits the given time for the test to stop.
C H R _API_R C
C H R _ t es t _query _ s t op(
C H R _TEST_H AN D LE t es t ,
C H R _C OU N T t imeout
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

timeout [in]
The time in seconds to wait for the test to stop or CHR_INFINITE. This call blocks until the
test stops or the timeout is reached.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TIMED_OUT

CHR_TEST_NOT_RUN

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 625 -

IxChariot APIGuide

CHR_test_remove_app_group
DESCRIPTION
The CHR_test_remove_app_group function removes the specified application group from
the specified test.
C H R _API_R C
C H R _ t e s t _re m o v e _ a p p _ g ro u p(
C H R _TEST_H AN D LE t es t H andle,
C H R _APP_GR OU P_H AN D LE appGroupH andle
)

PARAMETERS
testHandle [in]
A handle returned by CHR_test_new().

appGroupHandle [in]
A handle returned by CHR_app_group_new(), CHR_test_get_app_group_by_name(), or
CHR_test_get_app_group_by_index().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_OBJECT_INVALID*

CHR_PAIR_LIMIT_EXCEEDED

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_RESULTS_NOT_CLEARED

CHR_TEST_RUNNING

CHR_VALUE_INVALID

CHR_SCRIPT_TOO_LARGE

See Return Code Summary for a detailed description of each return code.
When CHR_OBJECT_INVALID is returned, extended error information provides details of
the operation failure. Use CHR_common_error_get_info to get this extended error information.

- 626 -

IxChariot APIGuide

CHR_test_remove_channel
DESCRIPTION
The CHR_test_remove_channel function removes a channel object from the specified
test.
C H R _API_R C
C H R _ t es t _rem ov e_ c hannel(
C H R _T E S T _H A N D LE
C H R _C H AN N EL_H AN D LE
)

i_t es t H andle,
i_c hannelH andle

PARAMETERS
i_testHandle [in]
A handle returned by CHR_test_new().

i_channelHandle [in]
A channel object handle returned by CHR_channel_new(), CHR_vpair_get_channel(), CHR_
test_get_channel(), or CHR_test_get_channel_by_name().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 627 -

IxChariot APIGuide

CHR_test_remove_receiver
DESCRIPTION
The CHR_test_remove_receiver function removes a receiver object from the specified
test.
C H R _API_R C
C H R _ t es t _rem ov e_ rec ei v er(
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle
)

PARAMETERS
i_testHandle [in]
A handle returned by CHR_test_new().

i_receiverHandle [in]
A receiver object handle returned by CHR_receiver_new(), CHR_test_get_receiver(), or
CHR_test_get_receiver_by_name().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 628 -

IxChariot APIGuide

CHR_test_save
DESCRIPTION
The CHR_test_save function saves the given test to the currently defined filename. Before
it can be saved, the test must not be running and it must have at least one pair, multicast
group, or application group.
C H R _API_R C
C H R _ t es t _s av e(
C H R _TEST_H AN D LE t es t
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_TEST_FILE

CHR_OBJECT_INVALID

CHR_OPERATION_FAILED*

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_RUNNING

CHR_VALUE_INVALID

CHR_IPTV_INVALID

Use CHR_common_error_get_info to get the extended error information available for this
return code
See Return Code Summary for a detailed description of each return code.

- 629 -

IxChariot APIGuide

CHR_test_set_filename
DESCRIPTION
The CHR_test_set_filename function sets or changes the name of the file to which the
given test is saved.
C H R _API_R C
C H R _ t es t _s et _f i l enam e(
C H R _TEST_H AN D LE t es t ,
C H R _STR I N G f ilename,
C H R _LEN GTH len
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

filename [in]
A string containing the filename. The filename may be specified using a relative or an absolute pathname. Note that once you've set the filename, you can't change it back to the
loaded filename. To reset the filename to the name of the loaded test, use a null filename
parameter and a "0" filename length.

len [in]
The length of the filename string, excluding the null terminator. The maximum length of
the test filename is 602.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OPERATION_FAILED*

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_STRING_TOO_LONG

CHR_TEST_RUNNING

CHR_VALUE_INVALID

- 630 -

IxChariot APIGuide

Use CHR_common_error_get_info to get the extended error information available for this return code.
See Return Code Summary for a detailed description of each return code.

- 631 -

IxChariot APIGuide

CHR_test_set_grouping_order
DESCRIPTION
The CHR_test_set_grouping_order function sets the grouping order, for grouping endpoints
in the test. See also CHR_test_set_grouping_type.
C H R _API_R C
C H R _ t e s t _s e t _ g r o u p i n g _ o r d e r(
C H R _TEST_H AN D LE t es t H andle,
C H R _SOR T_OR D ER s ort Order
)

PARAMETERS
testHandle [in]
A handle returned by CHR_test_new().

sortOrder [in]
sortOrder can have one of the following values:
l

CHR_SORT_ORDER_ASCENDING

CHR_SORT_ORDER_DESCENDING

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_VALUE_INVALID

CHR_OPERATION_FAILED*

CHR_TEST_RUNNING
Use CHR_common_error_get_info to get the extended error information available for this return code.

See Return Code Summary for a detailed description of each return code.

- 632 -

IxChariot APIGuide

CHR_test_set_grouping_type
DESCRIPTION
The CHR_test_set_grouping_type function sets the grouping type, for grouping endpoints in
the test. See also CHR_test_set_grouping_order.
C H R _API_R C
C H R _ t es t _s et _groupi ng_ t y pe(
C H R _TEST_H AN D LE t es t H andle,
C H R _GR OU PI N G_ TYPE groupingTy pe
)

PARAMETERS
testHandle [in]
A handle returned by CHR_test_new().

groupingType [in]
groupingType can have one of the following values:
l

CHR_GROUPING_TYPE_NO_GROUPING

CHR_GROUPING_TYPE_ENDPOINT1

CHR_GROUPING_TYPE_ENDPOINT2

CHR_GROUPING_TYPE_PROTOCOL

CHR_GROUPING_TYPE_SCRIPT

CHR_GROUPING_TYPE_E1_SERVICE_QUALITY

CHR_GROUPING_TYPE_E2_SERVICE_QUALITY

CHR_GROUPING_TYPE_USER_GROUP

CHR_GROUPING_TYPE_PAIR_COMMENT

CHR_GROUPING_TYPE_CONSOLE_E1_ADDR

CHR_GROUPING_TYPE_E1_E2_ADDR

CHR_GROUPING_TYPE_RUN_STATUS

CHR_GROUPING_TYPE_DYNAMIC_E1_MGMT

CHR_GROUPING_TYPE_DYNAMIC_E2_MGMT

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_VALUE_INVALID

- 633 -

IxChariot APIGuide

CHR_OPERATION_FAILED*

CHR_TEST_RUNNING
Use CHR_common_error_get_info to get the extended error information available for this return code.

See Return Code Summary for a detailed description of each return code.

- 634 -

IxChariot APIGuide

CHR_test_set_test_server_session
DESCRIPTION
The CHR_test_set_test_server_session function associates the test with an active
Aptixia session.
C H R _API_R C
C H R _ t es t _s et _t es t _ s erv er_s es s i on (
C H R _TEST_H AN D LE t es t H andle,
C H R _STR I N G t es t Serv erAddres s ,
C H R _C OU N T t es t Serv erSiz e,
C H R _C OU N T t es t Serv erPort
C H R _W LON G s es s ionObjec t I d
)

PARAMETERS
testHandle [in]
A handle returned by CHR_test_new().

testServerAddress [in]
The IP address of the TestServer.

testServerSize [in]
The size of the testServerAddress buffer.

testServerPort [in]
The TCP port of the TestServer. (Note that 0 indicates the default of 5568.)

sessionObjectId [out]
The 64-bit Object ID associated with the session to connect to.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_ERROR_ACCESSING_TESTSERVER_SESSION

CHR_NO_MEMORY

CHR_ERROR_ACCESSING_TESTSERVER_SESSION is returned if there is a problem locating the

session object on the TestServer.
See Return Code Summary for a detailed description of each return code.

- 635 -

IxChariot APIGuide

- 636 -

IxChariot APIGuide

CHR_test_set_throughput_units
DESCRIPTION
The CHR_test_set_throughput_units function sets or changes the throughput units value for
the given test.
C H R _API_R C
C H R _ t es t _s et _t hroughput _ uni t s (
C H R _TEST_H AN D LE t es t ,
C H R _TH R OU GH PU T_U N I TS unit s
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

units[in]
Provides one of the CHR_THROUGHPUT_UNITS values:
l

CHR_THROUGHPUT_UNITS_KB

CHR_THROUGHPUT_UNITS_kB

CHR_THROUGHPUT_UNITS_Kb

CHR_THROUGHPUT_UNITS_kb

CHR_THROUGHPUT_UNITS_Mb

CHR_THROUGHPUT_UNITS_Gb

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 637 -

IxChariot APIGuide

CHR_test_start
DESCRIPTION
The CHR_test_start function starts running the given test.
C H R _API_R C
C H R _ t es t _s t art (
C H R _TEST_H AN D LE t es t
)

Usage Notes:
l

Only one test may be running at a time on a computer.

All results from a previous run of this test are cleared when the test is started.

Before it can be started, the test must have at least one pair or multicast group.

If the test includes an application group, this function will validate the application
group before starting the test. The function will return CHR_APP_GROUP_INVALID if
the validation fails.

PARAMETERS
test [in]
A handle returned by CHR_test_new().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_OBJECT_INVALID

CHR_OPERATION_FAILED*

CHR_OUT_OF_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_TEST_RUNNING

CHR_NOT_LICENSED

CHR_IPTV_INVALID

CHR_APP_GROUP_INVALID

Use CHR_common_error_get_info to get the extended error information available for this return code.
See Return Code Summary for a detailed description of each return code.

- 638 -

IxChariot APIGuide

- 639 -

IxChariot APIGuide

CHR_test_stop
DESCRIPTION
The CHR_test_stop function requests that the given running test be stopped. This call can
and usually does return before the test has stopped. Use the CHR_test_query_stop function
to determine when the test has actually stopped. If the test doesn't stop within a reasonable amount of time, use CHR_test_abandon function to stop the test.
C H R _API_R C
C H R _ t es t _s t op(
C H R _TEST_H AN D LE t es t
)

PARAMETERS
test [in]
A handle returned by CHR_test_new().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OPERATION_FAILED*

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TEST_NOT_RUN

CHR_VALUE_INVALID

Use CHR_common_error_get_info to get the extended error information available for this
return code.
See Return Code Summary for a detailed description of each return code.

- 640 -

IxChariot APIGuide

Timing Record Object Functions

Timing record extraction functions are used to obtain test results that are unique to pair
and multicast pair timing records. Other values typically stored in timing records can be
obtained using common results extraction functions.

- 641 -

IxChariot APIGuide

CHR_timingrec_get_df
DESCRIPTION
The CHR_timingrec_get_df function gets the DF (delay factor) value generated from a
video pair or video multicast group test.
C H R _API_R C
C H R _t imingrec _get _df (
C H R _TI MI N GR EC _H AN D LE t rec ord,
C H R _C OU N T* df
)

PARAMETERS
trecord [in]
A handle returned by CHR_pair_get_timing_record() or CHR_mpair_get_timing_record().

df [out]
A pointer to the variable where the DF (delay factor) value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 642 -

IxChariot APIGuide

CHR_timingrec_get_e1_BSSID
DESCRIPTION
The CHR_timingrec_get_e1_BSSID function gets the Base Service Station ID for Endpoint
1. This is only valid when using non-streaming scripts.
C H R _API_R C
C H R _ t i m i ngrec _ get _ e1_B S S I D (
C H R _TI MI N GR EC _H AN D LE t rec ord,
C H R _STR I N G* Bs s id,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH *lengt h
)

PARAMETERS
trecord [in]
A handle returned by CHR_pair_get_timing_record() or CHR_mpair_get_timing_record().

Bssid [out]
A pointer to the variable where the base station ID is returned. The result is in the form of
a standard MAC address: "01:02:03:04:05:06".

maxLength [in]
The length of the buffer, which must be CHR_BSSID_SIZE bytes in size.

length [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY
CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 643 -

IxChariot APIGuide

CHR_timingrec_get_e1_RSSI
DESCRIPTION
The CHR_timingrec_get_e1_RSSI function gets the Receive Signal Strength Indicator for
Endpoint 1. This may only be used for non-streaming scripts.
C H R _API_R C
C H R _ t i m i ngrec _ get _ e1_R S S I (
C H R _TI MI N GR EC _H AN D LE t rec ord,
C H R _LON G* rs s i
)

PARAMETERS
trecord [in]
A handle returned by CHR_pair_get_timing_record() or CHR_mpair_get_timing_record().

rssi [out]
A pointer to the variable where the receive signal strength indicator is returned. A range of
-10 (strong) to -100 (weak) is used.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 644 -

IxChariot APIGuide

CHR_timingrec_get_e2_BSSID
DESCRIPTION
The CHR_timingrec_get_e1_BSSID function gets the Base Service Station ID for Endpoint
2. This is only valid for streaming scripts.
C H R _API_R C
C H R _ t i m i ngrec _ get _ e2_B S S I D (
C H R _TI MI N GR EC _H AN D LE t rec ord,
C H R _STR I N G* Bs s id,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH *lengt h
)

PARAMETERS
trecord [in]
A handle returned by CHR_pair_get_timing_record() or CHR_mpair_get_timing_record().

Bssid [out]
A pointer to the variable where the base station ID is returned. The result is in the form of
a standard MAC address: "01:02:03:04:05:06".

maxLength [in]
The length of the buffer, which must be CHR_BSSID_SIZE bytes in size.

length [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 645 -

IxChariot APIGuide

CHR_timingrec_get_e2_RSSI
DESCRIPTION
The CHR_timingrec_get_e1_RSSI function gets the Receive Signal Strength Indicator for
endpoint 1. This may only be used for streaming scripts.
C H R _API_R C
C H R _ t i m i ngrec _ get _ e2_R S S I (
C H R _TI MI N GR EC _H AN D LE t rec ord,
C H R _LON G* rs s i
)

PARAMETERS
trecord [in]
A handle returned by CHR_pair_get_timing_record() or CHR_mpair_get_timing_record().

rssi [out]
A pointer to the variable where the receive signal strength indicator is returned. A range of
-10 (strong) to -100 (weak) is used.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 646 -

IxChariot APIGuide

CHR_timingrec_get_elapsed
DESCRIPTION
The CHR_timingrec_get_elapsed function gets the elapsed time in seconds from the given
timing record.
C H R _API_R C
C H R _ t i m i n g re c _ g e t _ e l a p s e d(
C H R _TI MI N GR EC _H AN D LE t rec ord,
C H R _FLOAT* elaps ed
)

PARAMETERS
trecord [in]
A handle returned by CHR_pair_get_timing_record() or CHR_mpair_get_timing_record().

elapsed [out]
A pointer to the variable where the elapsed time is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 647 -

IxChariot APIGuide

CHR_timingrec_get_end_to_end_delay
DESCRIPTION
The CHR_timingrec_get_end_to_end_delay function gets the end-to-end delay in milliseconds from the given timing record.
CHR_API_RC
CHR_timingrec_get_end_to_end_delay (
CHR_TIMINGREC_HANDLE trecord,
CHR_FLOAT* delay)

PARAMETERS
trecord [in]
A handle returned by CHR_pair_get_timing_record() or CHR_mpair_get_timing_record().

delay[out]
A pointer to the variable where the end-to-end delay is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID
CHR_NO_SUCH_VALUE is returned when the pair is not a VoIP pair. There must
also be a valid VoIP license for the Console to get the end-to-end delay.

See Return Code Summary for a detailed description of each return code.

- 648 -

IxChariot APIGuide

CHR_timingrec_get_inactive
DESCRIPTION
The CHR_timingrec_get_inactive function gets the inactive time in seconds from the given
timing record.
C H R _API_R C
C H R _t imingrec _get _inac t iv e(
C H R _TI MI N GR EC _H AN D LE t rec ord,
C H R _FLOAT* inac t iv e
)

PARAMETERS
trecord [in]
A handle returned by CHR_pair_get_timing_record() or CHR_mpair_get_timing_record().

inactive [out]
A pointer to the variable where the inactive time is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 649 -

IxChariot APIGuide

CHR_timingrec_get_jitter
DESCRIPTION
The CHR_timingrec_get_jitter function gets the jitter time in seconds from the given timing
record.
C H R _API_R C
C H R _t imingrec _get _jit t er(
C H R _TI MI N GR EC _H AN D LE t rec ord,
C H R _FLOAT* jit t er
)

PARAMETERS
trecord [in]
A handle returned by CHR_pair_get_timing_record() or CHR_mpair_get_timing_record().

jitter [out]
A pointer to the variable where the jitter time is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

Note that CHR_NO_SUCH_VALUE is returned when the protocol used for the pair or mpair's
multicast group is not CHR_PROTOCOL_RTP.
See Return Code Summary for a detailed description of each return code.

- 650 -

IxChariot APIGuide

CHR_timingrec_get_max_consecutive_lost
DESCRIPTION
The CHR_timingrec_get_max_consecutive_lost function gets the maximum consecutive
lost datagrams from the given timing record. VoIP Test Module only.
C H R _API_R C
C H R _t imingrec _get _max _c ons ec ut iv e_los t (
C H R _TI MI N GR EC _H AN D LE t rec ord,
C H R _C OU N T* los t
)

PARAMETERS
trecord [in]
A handle returned by CHR_pair_get_timing_record() or CHR_mpair_get_timing_record().

count[out]
A pointer to the variable where the maximum consecutive lost datagrams is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID
CHR_NO_SUCH_VALUE is returned when the pair was not set to CHR_
PROTOCOL_RTP, CHR_PROTOCOL_IPX, or CHR_PROTOCOL_UDP. There must
also be a valid VoIP license for the Console.

See Return Code Summary for a detailed description of each return code.

- 651 -

IxChariot APIGuide

CHR_timingrec_get_max_delay_variation
DESCRIPTION
The CHR_timingrec_get_max_delay_variation function gets the jitter (delay variation)
maximum in milliseconds from the given timing record.
C H R _API_R C
C H R _ t i m i n g re c _ g e t _ m a x _ d e l a y _ v a ri a t i o n(
C H R _TI MI N GR EC _H AN D LE t rec ord,
C H R _C OU N T* v ariat ion
)

PARAMETERS
trecord [in]
A handle returned by CHR_pair_get_timing_record() or CHR_mpair_get_timing_record().

variation [out]
A pointer to the variable where the jitter (delay variation) maximum is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID
CHR_NO_SUCH_VALUE is returned when the pair was not set to CHR_
PROTOCOL_RTP. There must also be a valid VoIP license for the Console to get
the jitter (delay variation) maximum.

See Return Code Summary for a detailed description of each return code.

- 652 -

IxChariot APIGuide

CHR_timingrec_get_mlr
DESCRIPTION
The CHR_timingrec_get_mlr function gets the MLR (media loss rate) value generated from
a video pair or video multicast group test. MLR is the number of media packets lost per
second.
C H R _API_R C
C H R _ t i m i n g r e c _ g e t _ m l r(
C H R _TI MI N GR EC _H AN D LE t rec ord,
C H R _FLOAT* mlr
)

PARAMETERS
trecord [in]
A handle returned by CHR_pair_get_timing_record() or CHR_mpair_get_timing_record().

mlr [out]
A pointer to the variable where the MLR value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY
CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 653 -

IxChariot APIGuide

CHR_timingrec_get_MOS_estimate
DESCRIPTION
The CHR_timingrec_get_MOS_estimate function gets the Mean Opinion Score (MOS) estimate from the given timing record.
C H R _API_R C
C H R _t imingrec _get _MOS_es t imat e(
C H R _TI MI N GR EC _H AN D LE t rec ord,
C H R _FLOAT* es t imat e
)

PARAMETERS
trecord [in]
A handle returned by CHR_pair_get_timing_record().

estimate [out]
A pointer to the variable where the MOS estimate is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID
CHR_NO_SUCH_VALUE is returned when the pair is not able to calculate oneway delay (see CHR_timingrec_get_one_way_delay).

See Return Code Summary for a detailed description of each return code.

- 654 -

IxChariot APIGuide

CHR_timingrec_get_one_way_delay
DESCRIPTION
The CHR_timingrec_get_one_way_delay function gets the one-way delay in milliseconds
from the given timing record.
C H R _API_R C
C H R _t imingrec _get _one_w ay _delay(
C H R _TI MI N GR EC _H AN D LE t rec ord,
C H R _C OU N T* delay
)

PARAMETERS
trecord [in]
A handle returned by CHR_pair_get_timing_record() or CHR_mpair_get_timing_record().

delay[out]
A pointer to the variable where the one-way delay is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID
CHR_NO_SUCH_VALUE is returned:
l

when the pair was not a VoIP pair, or

the protocol was not CHR_PROTOCOL_RTP, or

the endpoint clocks were not able to synchronize.

There must also be a valid VoIP Test Module license for the Console to get the one-way
delay.
See Return Code Summary for a detailed description of each return code.

- 655 -

IxChariot APIGuide

CHR_timingrec_get_R_value
DESCRIPTION
The CHR_timingrec_get_R_value function gets the R-value calculated for the given timing
record.
CHR_API_RC
CHR_timingrec_get_R_value(
CHR_TIMINGREC_HANDLE trecord,
CHR_FLOAT* Rvalue
)

PARAMETERS
trecord [in]
A handle returned by CHR_pair_get_timingrecord().

Rvalue [out]
A pointer to the variable where the R-value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_VALUE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 656 -

IxChariot APIGuide

CHR_timingrec_get_report_group_id
DESCRIPTION
The CHR_timingrec_get_report_group_id function returns the report group identifier field
from the specified timing record.
C H R _API_R C
C H R _t i m i ngrec _ get _report _group_i d(
C H R _TI MI N GR EC _H AN D LE
i_rec ordH andle,
C H R _C OU N T*
o_report GroupI d
)

PARAMETERS
i_recordHandle [in]
A timing record handle returned by CHR_vpair_get_timing_record(), CHR_pair_get_timing_record(), or CHR_mpair_get_timing_record().

o_reportGroupId [out]
A pointer to the variable where the report group identifier is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_VALUE_INVALID

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 657 -

IxChariot APIGuide

CHR_timingrec_get_result_frequency
DESCRIPTION
The CHR_timingrec_get_result_frequency function gets the number of occurrences in a specified range for the specified result from the given timing record.
C H R _API_R C
C H R _t i m i ngrec _ get _res ul t _f requenc y (
C H R _TI MI N GR EC _H AN D LE t rec ord,
CHR_RESULTS res ult Ty pe,
C H R _C OU N T index ,
C H R _C OU N T* f requenc y
)

PARAMETERS
trecord [in]
A handle returned by CHR_pair_get_timing_record() or CHR_mpair_get_timing_record().

resultType [in]
A result type to query. One of the following:
l

CHR_RESULTS_DELAY_VARIATION

CHR_RESULTS_CONSECUTIVE_LOST

index [in]
The index of the range where the frequency will be retrieved. Range indices run from 0 to
the number of configured ranges - 1.

frequency [out]
A pointer to the variable where the frequency is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_VALUE_INVALID

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 658 -

IxChariot APIGuide

Traceroute Pair Object Functions

Traceroute pair object functions are used to run traceroutes on selected pairs of endpoints.
You can specify the maximum hop count and maximum timeout value. You can also extract
the runstatus while the traceroute is running.

- 659 -

IxChariot APIGuide

CHR_tracert_pair_delete
DESCRIPTION
The CHR_tracert_pair_delete function deletes a traceroute pair.
C H R _API_R C
C H R _ t rac ert _ pai r_del et e(
C H R _TR AC ER T_PAI R _H AN D LE pair
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_TRACERT_RUNNING

See Return Code Summary for a detailed description of each return code.

- 660 -

IxChariot APIGuide

CHR_tracert_pair_get_e1_addr
DESCRIPTION
The CHR_tracert_pair_get_e1_addr function gets the address for Endpoint 1 in a given
traceroute.
C H R _API_R C
C H R _ t rac ert _ pai r_get _e1_ addr(
C H R _TR AC ER T_PAI R _H AN D LE pair,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

buf [out]
A pointer to the buffer where the Endpoint 1 address is returned.

len [in]
The length of the buffer, or the maximum number of bytes that can be returned in the buffer, excluding the null terminator.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 661 -

IxChariot APIGuide

CHR_tracert_pair_get_e2_addr
DESCRIPTION
The CHR_tracert_pair_get_e2_addr function gets the address for Endpoint 2 in a given
traceroute.
C H R _API_R C
C H R _ t rac ert _ pai r_get _e2_ addr(
C H R _TR AC ER T_PAI R _H AN D LE pair,
C H R _STR I N G buf ,
C H R _LEN GTH len,
C H R _LEN GTH * rt nlen
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

buf [out]
A pointer to the buffer where the Endpoint 2 address is returned.

len [in]
The length of the buffer, or the maximum number of bytes that can be returned in the buffer, excluding the null terminator.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 662 -

IxChariot APIGuide

CHR_tracert_pair_get_hop_record
DESCRIPTION
The CHR_tracert_pair_get_hop_record function gets the record number for a particular hop
of a traceroute.
C H R _API_R C
CHR_tracert_pair_get_hop_record(
C H R _TR AC ER T_PAI R _H AN D LE pair,
C H R _C OU N T num,
C H R _H OPR EC _H AN D LE* hoprec
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

num [in]
The number indicating which hop. The number is determined by the order in which
traceroute data reached the hop.

hoprec[out]
A handle returned by CHR_tracert_pair_get_hop_record.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID (for traceroute pair)

CHR_POINTER_INVALID (for hop record handle)

CHR_TRACERT_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 663 -

IxChariot APIGuide

CHR_tracert_pair_get_max_hops
DESCRIPTION
The CHR_tracert_pair_get_max_hops function gets the maximum hop count before a
traceroute is abandoned.
C H R _API_R C
C H R _ t rac ert _ pai r_get _m ax _ hops (
C H R _TR AC ER T_PAI R _H AN D LE pair,
C H R _C OU N T* max _hops
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

max hops [out]

A pointer to the variable where the maximum number of hops for a traceroute is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 664 -

IxChariot APIGuide

CHR_tracert_pair_get_max_timeout
DESCRIPTION
The CHR_tracert_pair_get_max_timeout function gets the maximum timeout value before
a traceroute is abandoned.
C H R _API_R C
C H R _ t rac ert _ pai r_get _m ax _ t i m eout (
C H R _TR AC ER T_PAI R _H AN D LE pair,
C H R _C OU N T* max _t imeout
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

max_timeout [out]
A pointer to the variable where the maximum time to wait for a reply from a particular hop
is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 665 -

IxChariot APIGuide

CHR_tracert_pair_get_resolve_hop_name
DESCRIPTION
The CHR_tracert_pair_get_resolve_hop_name function determines whether hop names for
a particular hop in a traceroute will be resolved.
C H R _API_R C
C H R _ t rac ert _ pai r_get _res ol v e_ hop_ nam e(
C H R _TR AC ER T_PAI R _H AN D LE pair,
C H R _BOOLEAN * res olv e_name
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

resolve_name [out]
Specifies CHR_TRUE or CHR_FALSE to indicate whether hop names will be resolved.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 666 -

IxChariot APIGuide

CHR_tracert_pair_get_runStatus
DESCRIPTION
The CHR_tracert_pair_get_runStatus function gets the status of a traceroute.
C H R _API_R C
C H R _ t rac ert _ pai r_get _runS t at us (
C H R _TR AC ER T_PAI R _H AN D LE pair,
C H R _TR AC ER T_R U N STATU S_TYPE* s t at us
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

status[out]
A pointer to the variable where the runstatus is returned. The following status types are
applicable:
l

CHR_TRACERT_RUNSTATUS_UNINITIALIZED

CHR_TRACERT_RUNSTATUS_INITIALIZING

CHR_TRACERT_RUNSTATUS_RUNNING

CHR_TRACERT_RUNSTATUS_ERROR

CHR_TRACERT_RUNSTATUS_FINISHED

CHR_TRACERT_RUNSTATUS_STOPPING

CHR_TRACERT_RUNSTATUS_USER_STOPPED

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 667 -

IxChariot APIGuide

CHR_tracert_pair_new
DESCRIPTION
The CHR_tracert_pair_new function selects an endpoint pair on which a traceroute will be
run.
C H R _API_R C
C H R _ t rac ert _ pai r_new (
C H R _TR AC ER T_PAI R _H AN D LE* pair
)

PARAMETERS
pair [out]
A pointer to the variable where the handle for the new traceroute pair is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return code indicates that an error occurred and any returned values should
be ignored:
CHR_NO_MEMORY
See Return Code Summary for a detailed description of each return code.

- 668 -

IxChariot APIGuide

CHR_tracert_pair_query_stop
DESCRIPTION
The CHR_tracert_pair_query_stop function waits the given time for the test to stop.
C H R _API_R C
C H R _ t rac ert _ pai r_query _ s t op(
C H R _TR AC ER T_PAI R _H AN D LE pair,
C H R _C OU N T t imeout
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

timeout [in]
The time in seconds to wait for the test to stop or CHR_INFINITE. This call blocks until the
test stops or the timeout is reached. This should be the same value as the maximum number of hops in the traceroute.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TIMED_OUT

CHR_TEST_NOT_RUN

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 669 -

IxChariot APIGuide

CHR_tracert_pair_results_get_hop_count
DESCRIPTION
The CHR_tracert_pair_results_get_hop_count function gets the number of hops in a
traceroute.
C H R _API_R C
C H R _ t rac ert _ pai r_res ul t s _ get _hop_ c ount (
C H R _TR AC ER T_PAI R _H AN D LE pair,
C H R _C OU N T* c ount
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

count[out]
A pointer to the variable where the number of hops in a traceroute is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_TRACERT_NOT_RUN

See Return Code Summary for a detailed description of each return code.

- 670 -

IxChariot APIGuide

CHR_tracert_pair_run
DESCRIPTION
The CHR_tracert_pair_run starts a traceroute.
C H R _API_R C
C H R _ t rac ert _ pai r_run (
C H R _TR AC ER T_PAI R _H AN D LE pair
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_INVALID (E1 and/or E2 not set)

CHR_TRACERT_RUNNING (already running)

See Return Code Summary for a detailed description of each return code.

- 671 -

IxChariot APIGuide

CHR_tracert_pair_set_e1_addr
DESCRIPTION
The CHR_tracert_pair_set_e1_addr function sets or changes the address for Endpoint 1 in a
given traceroute.
C H R _API_R C
C H R _ t rac ert _ pai r_s et _e1_ addr(
C H R _TR AC ER T_PAI R _H AN D LE pair,
C H R _STR I N G buf ,
C H R _LEN GTH len
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

buf [in]
A pointer to the buffer where the Endpoint 1 address is stored.

len [in]
The length of the endpoint address string, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 672 -

IxChariot APIGuide

CHR_tracert_pair_set_e2_addr
DESCRIPTION
The CHR_tracert_pair_set_e2_addr function sets or changes the address for Endpoint 2 in a
given traceroute.<META NAME="Keywords" CONTENT="Traceroute Pair Object Functions:CHR_tracert_pair_set_e2_addr">
C H R _API_R C
C H R _ t rac ert _ pai r_s et _e2_ addr(
C H R _TR AC ER T_PAI R _H AN D LE pair,
C H R _STR I N G buf ,
C H R _LEN GTH len
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

buf [out]
A pointer to the buffer where the Endpoint 2 address is stored.

len [in]
The length of the endpoint address string, excluding the null terminator. This string is limited to 64 characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 673 -

IxChariot APIGuide

CHR_tracert_pair_set_max_hops
DESCRIPTION
The CHR_tracert_pair_set_max_hops function sets or changes the maximum hop count
before a traceroute is abandoned.
C H R _API_R C
C H R _ t rac ert _ pai r_s et _m ax _ hops (
C H R _TR AC ER T_PAI R _H AN D LE pair,
C H R _C OU N T max _hops
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

max_hops [out]
The value that specifies the maximum number of hops for a traceroute before it is abandoned. This value must be between 2 and 40.The default value for maximum hops is 30.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 674 -

IxChariot APIGuide

CHR_tracert_pair_set_max_timeout
DESCRIPTION
The CHR_tracert_pair_set_max_timeout function sets or changes the maximum timeout
value before a traceroute is abandoned.
C H R _API_R C
C H R _ t rac ert _ pai r_s et _m ax _ t i m eout (
C H R _TR AC ER T_PAI R _H AN D LE pair,
C H R _C OU N T max _t imeout
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

max_timeout [in]
The maximum time to wait for the traceroute to complete (in milliseconds). This value
must be between 1 and 10,000.The default value for maximum timeout is 3000 milliseconds.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 675 -

IxChariot APIGuide

CHR_tracert_pair_set_resolve_hop_name
DESCRIPTION
The CHR_tracert_pair_set_resolve_hop_name function sets or changes the resolution of
hop addresses in a traceroute to hop names.
C H R _API_R C
C H R _ t rac ert _ pai r_s et _res ol v e_ hop_ nam e(
C H R _TR AC ER T_PAI R _H AN D LE pair,
C H R _BOOLEAN res olv e_name
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

resolve_name [in]
Specifies CHR_TRUE or CHR_FALSE to indicate whether to use resolved hop names.
The default setting for resolve hop names is CHR_TRUE.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return code indicates that an error occurred and any returned values should
be ignored:
CHR_HANDLE_INVALID
See Return Code Summary for a detailed description of each return code.

- 676 -

IxChariot APIGuide

CHR_tracert_pair_stop
DESCRIPTION
The CHR_tracert_pair_stop function stops a running traceroute.
C H R _API_R C
C H R _ t rac ert _ pai r_s t op(
C H R _TR AC ER T_PAI R _H AN D LE pair
)

PARAMETERS
pair [in]
A handle returned by CHR_tracert_pair_new().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_TIMED_OUT

CHR_TEST_NOT_RUN

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 677 -

IxChariot APIGuide

Video Multicast Group Object Functions

The video multicast group object functions are used to define and retrieve information
about a video multicast group. A video multicast group object must be contained by a test
object. The testing parameters available for the video multicast group object include the
source port number, the length of the timing records generated, type of codec, the bitrate
of the video transmission, the frames per datagram, the initial delay, the RTP payload
type, and the media frame size. You cannot add members to or set the attributes of a multicast group object that is contained by a test object.
A separate set of functions is provided to define and retrieve information about video pairs
(unicast video).

- 678 -

IxChariot APIGuide

CHR_video_mgroup_get_bitrate
DESCRIPTION
The CHR_video_mgroup_get_bitrate function gets the bitrate value and unit measurement defined for the given video multicast group.
C H R _API_R C
C H R _v i deo_m group_get _bi t rat e (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _FLOAT* bit rat e,
C H R _ T H R OU GH P U T _U N I T S * rat e_um
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

bitrate [out]
A pointer to the variable where the bitrate value is returned.

rate_um [out]
A pointer to the variable where the throughput units measurement setting is returned. See
CHR_video_mgroup_set_bitrate on page 4-552 for applicable values.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 679 -

IxChariot APIGuide

CHR_video_mgroup_get_codec
DESCRIPTION
The CHR_video_mgroup_get_codec function gets the codec defined for the given video multicast group.
C H R _API_R C
C H R _v i deo_m group_get _c odec (
C H R _V I D E O_M GR OU P _H A N D LE
C H R _VI D EO_C OD EC * c odec
)

mgroupH andle,

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

codec[out]
A pointer to the variable where the codec is returned. See CHR_video_mgroup_set_codec
for applicable codecs.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 680 -

IxChariot APIGuide

CHR_video_mgroup_get_frames_per_datagram
DESCRIPTION
The CHR_video_mgroup_get_frames_per_datagram function gets the number of media
frames per datagram defined for the given video multicast group.
C H R _API_R C
C H R _v i deo_m group_get _f ram es _ per_dat agram (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _C OU N T* f rames
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

frames[out]
A pointer to the variable where the frames-per-datagram value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 681 -

IxChariot APIGuide

CHR_video_mgroup_pair_get_initial_delay
DESCRIPTION
The CHR_video_mgroup_pair_get_initial_delay function gets the value of the delay
that occurs before the first video data traffic is transmitted in the multicast video test.
C H R _API_R C
C H R _v i deo_m group_pai r_ get _i ni t i al _del ay (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G delay ,
C H R _LEN GTH lengt h,
C H R _LEN GTH *ret urnedLengt h
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

delay[out]
A pointer to a string that will contain the initial delay in the same format as the one used
for set.

length [in]
Specifies how much space was allocated for the "delay" string, including the null terminator. If "length" is not enough to hold the string that will be returned, an error will be
returned.

returnedLength [out]
A pointer to the variable where the length of the "delay" string, excluding the null terminator, is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 682 -

IxChariot APIGuide

CHR_video_mgroup_get_media_frame_size
DESCRIPTION
The CHR_video_mgroup_get_media_frame_size function gets the media frame size used
in the multicast video test.
C H R _API_R C
C H R _v i deo_m group_get _m edi a_f ram e_s i z e(
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _C OU N T * m edi a_f ram e_s i z e
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

media_frame_size [out]
A pointer to the variable where the frame size value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 683 -

IxChariot APIGuide

CHR_video_mgroup_get_no_of_timing_records
DESCRIPTION
The CHR_video_mgroup_get_no_of_timing_records function gets the number of timing
records that were created for the given video multicast group.
C H R _API_R C
C H R _ v i deo_ m group_get _ no_ of _t i m i ng_ rec ords (
C H R _VI D EO_MGR OU P_H AN D LE mgroupH andle,
C H R _C OU N T *no_of _t r
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

no_of_tr [out]
A pointer to the variable where the count of timing records is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 684 -

IxChariot APIGuide

CHR_video_mgroup_get_rtp_payload_type
DESCRIPTION
The CHR_video_mgroup_get_rtp_payload_type function gets the RTP payload type
defined for the given video multicast group. This function will only be successful if codec is
set to "custom" and protocol is set to RTP or RTP6. Otherwise, the function returns CHR_
NO_SUCH_VALUE.
C H R _API_R C
C H R _v i deo_m group_get _rt p_pay l oad_ t y pe(
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _BYTE *rt p_pay load_t y pe
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

rtp_payload_type [out]
A pointer to the variable where the RTP payload type value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 685 -

IxChariot APIGuide

CHR_video_mgroup_get_source_port_num
DESCRIPTION
The CHR_video_mgroup_get_source_port_num function gets the UDP source port number for the given video multicast group.
C H R _API_R C
C H R _ v i deo_ m group_get _s ourc e_ port _num (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _POR T* port
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

port [out]
A pointer to the variable where the UDP source port number is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 686 -

IxChariot APIGuide

CHR_video_mgroup_get_tr_duration
DESCRIPTION
The CHR_video_mgroup_get_tr_duration function gets the timing record duration
defined for the given video multicast group.
C H R _API_R C
C H R _v i deo_m group_get _t r_ durat i on(
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _C OU N T* s ec onds
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

seconds [out]
A pointer to the variable where the timing record duration value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 687 -

IxChariot APIGuide

CHR_video_mgroup_new
DESCRIPTION
The CHR_video_mgroup_new function creates a new video multicast group object for multicast video testing, and initializes it to object default values. See Video Multicast Group
Object Default Values for information on the object default values.
The handle returned by this function is needed for other function calls to operate on the
video multicast group object.
C H R _API_R C
C H R _v i deo_m group_new (
C H R _V I D E O_M GR OU P _H A N D LE * m groupH andl e
)

PARAMETERS
mgroupHandle [out]
A pointer to the variable where the handle for the new video multicast group is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_OUT_OF_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 688 -

IxChariot APIGuide

CHR_video_mgroup_set_bitrate
DESCRIPTION
The CHR_video_mgroup_set_bitrate function sets the bitrate value and unit measurement for the given video multicast group.
C H R _API_R C
C H R _v i deo_m group_get _bi t rat e (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _FLOAT bit rat e,
C H R _T H R OU GH P U T _U N I T S rat e_ um
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

bitrate [in]
The media data rate of the video stream. Typical values for MPEG2 are between 3 and 15
megabits. The default is 3.75 megabits.

rate_um [in]
The unit measurement setting for the media data rate. The unit measurement can be any
of the following:
CHR_THROUGHPUT_UNITS_KB
CHR_THROUGHPUT_UNITS_kB
CHR_THROUGHPUT_UNITS_Kb
CHR_THROUGHPUT_UNITS_kb
CHR_THROUGHPUT_UNITS_Mb
CHR_THROUGHPUT_UNITS_Gb

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

- 689 -

IxChariot APIGuide

CHR_POINTER_INVALID

CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 690 -

IxChariot APIGuide

CHR_video_mgroup_set_codec
DESCRIPTION
The CHR_video_mgroup_set_codec function sets or changes the codec for the given video
multicast group.
C H R _API_R C
C H R _v i deo_m group_s et _c odec (
C H R _V I D E O_M GR OU P _H A N D LE
C H R _VI D EO_C OD EC c odec
)

mgroupH andle,

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

codec[in]
Provides one of the following codecs:
CHR_VIDEO_CODEC_NONE
CHR_VIDEO_CODEC_MPEG2
CHR_VIDEO_CODEC_CUSTOM

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

l
l

CHR_STRING_TOO_LONG
CHR_NO_SUCH_VALUE

See Return Code Summary for a detailed description of each return code.

- 691 -

IxChariot APIGuide

CHR_video_mgroup_set_frames_per_datagram
DESCRIPTION
The CHR_video_mgroup_set_frames_per_datagram function sets or changes the number
of media frames per datagram for the given video multicast group.
C H R _API_R C
C H R _v i deo_m group_s et _f ram es _ per_dat agram (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _C OU N T f rames
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

frames[in]
Sets the number of media frames that will be contained in a datagram. For Ethernet, there
are typically seven frames per datagram. All integer values greater than zero are valid.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 692 -

IxChariot APIGuide

CHR_video_mgroup_pair_set_initial_delay
DESCRIPTION
The CHR_video_mgroup_pair_set_initial_delay function sets or changes the delay
before the first video data traffic is transmitted in the multicast video test. By default, the
initial delay is set to 0.
C H R _API_R C
C H R _v i deo_m group_pai r_ s et _i ni t i al _del ay (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G delay ,
C H R _LEN GTH lengt h
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

delay[in]
Specifies the initial delay distribution. Valid values are in the form of "d[x,y]", where:
l

d = u (uniform), n (normal), p (poisson), or e (exponential) and

x,y = integers between "0" and "2147483647" where x < y

or an integer (constant) between 1 and 2147483647

length [in]
The length of the delay string, excluding the null terminator. The string is limited to 24
characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

l
l

CHR_POINTER_INVALID
CHR_STRING_TOO_LONG

See Return Code Summary for a detailed description of each return code.

- 693 -

IxChariot APIGuide

CHR_video_mgroup_set_media_frame_size
DESCRIPTION
The CHR_video_mgroup_set_media_frame_size function sets or changes the media frame
size used in the multicast video test.
C H R _API_R C
C H R _v i deo_m group_s et _m edi a_f ram e_s i z e(
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _C OU N T media_f rame_s iz e
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

media_frame_size [in]
Specifies the media frame size. For Video over IP packets, the Ethernet frame size is typically 1362 bytes (assuming 1316 bytes of MPEG2 TS payload).

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 694 -

IxChariot APIGuide

CHR_video_mgroup_set_no_of_timing_record
DESCRIPTION
The CHR_video_mgroup_set_no_of_timing_record function allows you to set the number of timing records for a video multicast group.
C H R _API_R C
C H R _ v i deo_ m group_s et _ no_ of _t i m i ng_ rec ords (
C H R _VI D EO_MGR OU P_H AN D LE mgroupH andle,
C H R _ C OU N T no_ of _t r
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

no_of_tr [in]
Specifies the number of timing records that the endpoint will create during the execution of
a test. The valid range is from 1 to 2147483647, inclusive. The default value is 50.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 695 -

IxChariot APIGuide

CHR_video_mgroup_set_rtp_payload_type
DESCRIPTION
The CHR_video_mgroup_set_rtp_payload_type function sets or changes the RTP payload
type for the given video multicast group. This function will only be successful if codec is set
to "custom" and protocol is set to RTP or RTP6. Otherwise, the function returns CHR_
VALUE_INVALID.
C H R _API_R C
C H R _v i deo_m group_s et _rt p_pay l oad_ t y pe(
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _BYTE rt p_pay load_t y pe
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

rtp_payload_type [in]
Sets the RTP payload type. Any value from 0 to 127 is valid.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 696 -

IxChariot APIGuide

CHR_video_mgroup_set_source_port_num
DESCRIPTION
The CHR_video_mgroup_set_source_port_num function sets or changes the UDP source
multicast port number for the given video multicast group.
C H R _API_R C
C H R _ v i deo_ m group_s et _s ourc e_ port _num (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _POR T port
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

port [in]
Sets the UDP source multicast port number for the test traffic.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 697 -

IxChariot APIGuide

CHR_video_mgroup_set_tr_duration
DESCRIPTION
The CHR_video_mgroup_set_tr_duration function sets or changes the timing record duration for the given video multicast group. This function returns CHR_VALUE_INVALID if the
value set is less than 1 or greater than 3600.
C H R _API_R C
C H R _v i deo_m group_s et _t r_ durat i on(
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _C OU N T s ec onds
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_mgroup_new() or CHR_test_get_mgroup().

seconds [in]
Sets the timing record duration, in seconds. The valid range of values is from 1 to 3600
(inclusive).

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 698 -

IxChariot APIGuide

Video Pair Object Functions

The video pair object functions are used to define and retrieve information about a video
pair. A video pair object must be contained by a test object. The testing parameters available for the video pair object include the source and destination port numbers, the length
of the timing records generated, type of codec, the bitrate of the video transmission, the
frames per datagram, the initial delay, the RTP payload type, and the media frame size.
You cannot add members to or set the attributes of a video pair object that is contained by
a test object.
A separate set of functions is provided to define and retrieve information about video multicast groups.

- 699 -

IxChariot APIGuide

CHR_video_pair_get_bitrate
DESCRIPTION
The CHR_video_pair_get_bitrate function gets the bitrate value and unit measurement
defined for the given video pair.
C H R _API_R C
C H R _ v i deo_ pai r_get _bi t rat e (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _FLOAT* bit rat e,
C H R _ T H R OU GH P U T _U N I T S * rat e_um
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

bitrate [out]
A pointer to the variable where the bitrate value is returned.

rate_um [out]
A pointer to the variable where the throughput units measurement setting is returned. See
CHR_video_pair_set_bitrate for applicable values.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 700 -

IxChariot APIGuide

CHR_video_pair_get_codec
DESCRIPTION
The CHR_video_pair_get_codec function gets the codec defined for the given video pair.
C H R _API_R C
C H R _ v i deo_ pai r_get _c odec (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _VI D EO_C OD EC * c odec
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

codec[out]
A pointer to the variable where the codec is returned. See CHR_video_pair_set_codec for
applicable codecs.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 701 -

IxChariot APIGuide

CHR_video_pair_get_dest_port_num
DESCRIPTION
The CHR_video_pair_get_dest_port_num function gets the UDP destination port number
defined for the given video pair.
C H R _API_R C
C H R _ v i deo_ pai r_get _des t _ port _num (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _POR T* port
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

port [out]
A pointer to the variable where the UDP destination port number is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 702 -

IxChariot APIGuide

CHR_video_pair_get_frames_per_datagram
DESCRIPTION
The CHR_video_pair_get_frames_per_datagram function gets the number of media
frames per datagram defined for the given video pair.
C H R _API_R C
C H R _ v i deo_ pai r_get _f ram es _ per_dat agram (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T* f rames
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

frames[out]
A pointer to the variable where the frames-per-datagram value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 703 -

IxChariot APIGuide

CHR_video_pair_get_initial_delay
DESCRIPTION
The CHR_video_pair_get_initial_delay function gets the value of the delay that
occurs before the first video data traffic is transmitted in the unicast video test.
C H R _API_R C
C H R _ v i deo_ pai r_get _i ni t i al _ del ay (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _STR I N G delay ,
C H R _LEN GTH lengt h,
C H R _LEN GTH *ret urnedLengt h
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

delay[out]
A pointer to a string that will contain the initial delay in the same format as the one used
for set.

length [in]
Specifies how much space was allocated for the "delay" string, including the null terminator. If "length" is not enough to hold the string that will be returned, an error will be
returned.

returnedLength [out]
A pointer to the variable where the length of the "delay" string, excluding the null terminator, is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_BUFFER_TOO_SMALL

See Return Code Summary for a detailed description of each return code.

- 704 -

IxChariot APIGuide

CHR_video_pair_get_media_frame_size
DESCRIPTION
The CHR_video_pair_get_media_frame_size function gets the media frame size used in
the unicast video test.
C H R _API_R C
C H R _ v i deo_ pai r_get _m edi a_ f ram e_ s i z e(
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T * m edi a_f ram e_s i z e
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

media_frame_size [out]
A pointer to the variable where the frame size value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 705 -

IxChariot APIGuide

CHR_video_pair_get_no_of_timing_records
DESCRIPTION
The CHR_video_pair_get_no_of_timing_records function gets the number of timing
records that were created for the given video pair.
C H R _API_R C
C H R _ v i deo_ pai r_get _ no_ of _t i m i ng_ rec ords (
C H R _VI D EO_PAI R _H AN D LE pairH andle,
C H R _C OU N T *no_of _t r
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

no_of_tr [out]
A pointer to the variable where the count of timing records is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 706 -

IxChariot APIGuide

CHR_video_pair_get_rtp_payload_type
DESCRIPTION
The CHR_video_pair_get_rtp_payload_type function gets the RTP payload type defined
for the given video pair. This function will only be successful if codec is set to "custom" and
protocol is set to RTP or RTP6. Otherwise, the function returns CHR_NO_SUCH_VALUE.
C H R _API_R C
C H R _ v i deo_ pai r_get _rt p_pay l oad_ t y pe(
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _BYTE *rt p_pay load_t y pe
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

rtp_payload_type [out]
A pointer to the variable where the RTP payload type value is returned. Any value from 0
to 127 is valid.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NO_SUCH_VALUE

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 707 -

IxChariot APIGuide

CHR_video_pair_get_source_port_num
DESCRIPTION
The CHR_video_pair_get_source_port_num
for the given video pair.

function gets the UDP source port number

C H R _API_R C
C H R _ v i deo_ pai r_get _s ourc e_ port _num (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _POR T* port
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

port [out]
A pointer to the variable where the UDP source port number is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 708 -

IxChariot APIGuide

CHR_video_pair_get_tr_duration
DESCRIPTION
The CHR_video_pair_get_tr_duration function gets the timing record duration defined for
the given video pair.
C H R _API_R C
C H R _ v i deo_ pai r_get _t r_ durat i on(
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T* s ec onds
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

seconds [out]
A pointer to the variable where the timing record duration value is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 709 -

IxChariot APIGuide

CHR_video_pair_new
DESCRIPTION
The CHR_video_pair_new function creates a new video pair object for unicast video testing, and initializes it to object default values. See Video Pair Object Default Values for
information on the object default values.
The handle returned by this function is needed for other function calls to operate on the
video pair object.
C H R _API_R C
C H R _ v i deo_ pai r_new (
C H R _V I D E O_ P A I R _H A N D LE * pai rH andl e
)

PARAMETERS
pairHandle [out]
A pointer to the variable where the handle for the new video pair is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_API_NOT_INITIALIZED

CHR_OUT_OF_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NOT_LICENSED

See Return Code Summary for a detailed description of each return code.

- 710 -

IxChariot APIGuide

CHR_video_pair_set_bitrate
DESCRIPTION
The CHR_video_pair_set_bitrate function sets the bitrate value and unit measurement
for the given video pair.
C H R _API_R C
C H R _ v i deo_ pai r_s et _bi t rat e (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _FLOAT bit rat e,
C H R _T H R OU GH P U T _U N I T S rat e_ um
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

bitrate [in]
The media data rate of the video stream. Typical values for MPEG2 are between 3 and 15
megabits. The default is 3.75 megabits.

rate_um [in]
The unit measurement setting for the media data rate. The unit measurement can be any
of the following:
CHR_THROUGHPUT_UNITS_KB
CHR_THROUGHPUT_UNITS_kB
CHR_THROUGHPUT_UNITS_Kb
CHR_THROUGHPUT_UNITS_kb
CHR_THROUGHPUT_UNITS_Mb
CHR_THROUGHPUT_UNITS_Gb

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

- 711 -

IxChariot APIGuide

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 712 -

IxChariot APIGuide

CHR_video_pair_set_codec
DESCRIPTION
The CHR_video_pair_set_codec function sets or changes the codec for the given video
pair.
C H R _API_R C
C H R _ v i deo_ pai r_s et _c odec (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _VI D EO_C OD EC c odec
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

codec[in]
Provides one of the following codecs:
CHR_VIDEO_CODEC_MPEG2
CHR_VIDEO_CODEC_CUSTOM

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

l
l

CHR_VALUE_INVALID
CHR_NO_SUCH_VALUE

See Return Code Summary for a detailed description of each return code.

- 713 -

IxChariot APIGuide

CHR_video_pair_set_dest_port_num
DESCRIPTION
The CHR_video_pair_set_dest_port_num function sets or changes the UDP destination
port number defined for the given video pair.
C H R _API_R C
C H R _ v i deo_ pai r_s et _des t _ port _num (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _POR T port
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

port [in]
The UDP destination port number for the test traffic.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 714 -

IxChariot APIGuide

CHR_video_pair_set_frames_per_datagram
DESCRIPTION
The CHR_video_pair_set_frames_per_datagram function sets or changes the number of
media frames per datagram for the given video pair.
C H R _API_R C
C H R _ v i deo_ pai r_s et _f ram es _ per_dat agram (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T f rames
)

PARAMETERS
mgroupHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

frames[in]
Sets the number of media frames that will be contained in a datagram. For Ethernet, there
are typically seven frames per datagram. All integer values greater than zero are valid.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 715 -

IxChariot APIGuide

CHR_video_pair_set_initial_delay
DESCRIPTION
The CHR_video_pair_set_initial_delay function sets or changes the delay before the
first video data traffic is transmitted in the unicast video test. By default, the initial delay
is set to 0.
C H R _API_R C
C H R _ v i deo_ pai r_s et _i ni t i al _ del ay (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _STR I N G delay ,
C H R _LEN GTH lengt h
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

delay[in]
Specifies the initial delay distribution. Valid values are in the form of "d[x,y]", where:
l

d = u (uniform), n (normal), p (poisson), or e (exponential) and

x,y = integers between "0" and "2147483647" where x < y

or an integer (constant) between 1 and 2147483647

length [in]
The length of the delay string, excluding the null terminator. The string is limited to 24
characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 716 -

IxChariot APIGuide

CHR_video_pair_set_media_frame_size
DESCRIPTION
The CHR_video_pair_set_media_frame_size function sets or changes the media frame
size used in the unicast video test.
C H R _API_R C
C H R _ v i deo_ pai r_s et _m edi a_ f ram e_ s i z e(
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T media_f rame_s iz e
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

media_frame_size [in]

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 717 -

IxChariot APIGuide

CHR_video_pair_set_no_of_timing_record
DESCRIPTION
The CHR_video_pair_set_no_of_timing_record function allows you to set the number
of timing records for a video pair.
C H R _API_R C
C H R _ v i deo_ pai r_s et _ no_ of _t i m i ng_ rec ords (
C H R _VI D EO_PAI R _H AN D LE pairH andle,
C H R _ C OU N T no_ of _t r
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

no_of_tr [in]
Specifies the number of timing records that the endpoint will create during the execution of
a test. The valid range is from 1 to 2147483647, inclusive. The default value is 50.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 718 -

IxChariot APIGuide

CHR_video_pair_set_rtp_payload_type
DESCRIPTION
The CHR_video_pair_set_rtp_payload_type function sets or changes the RTP payload
type for the given video pair. This function will only be successful if codec is set to "custom" and protocol is set to RTP or RTP6. Otherwise, the function returns CHR_ VALUE_
INVALID.
C H R _API_R C
C H R _ v i deo_ pai r_s et _rt p_pay l oad_ t y pe(
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _BYTE rt p_pay load_t y pe
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

rtp_payload_type [in]
Sets the RTP payload type. Any value from 0 to 127 is valid.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 719 -

IxChariot APIGuide

CHR_video_pair_set_source_port_num
DESCRIPTION
The CHR_video_pair_set_source_port_num function sets or changes the UDP source unicast port number for the given video pair.
C H R _API_R C
C H R _ v i deo_ pai r_s et _s ourc e_ port _num (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _POR T port
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

port [in]
Sets the UDP source port number for the test traffic.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 720 -

IxChariot APIGuide

CHR_video_pair_set_tr_duration
DESCRIPTION
The CHR_video_pair_set_tr_duration function sets or changes the timing record duration
for the given video pair. This function returns CHR_VALUE_INVALID if the value set is less
than 1 or greater than 3600.
C H R _API_R C
C H R _ v i deo_ pai r_s et _t r_ durat i on(
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T s ec onds
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_video_pair_new() or CHR_test_get_pair().

seconds [in]
Sets the timing record duration, in seconds. The valid range of values is from 1 to 3600
(inclusive).

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 721 -

IxChariot APIGuide

VoIP Pair Object Functions

VoIP pair object functions are used in voice over IP tests. A VoIP pair or VoIP hardware
performance pair object must be contained by a test object. The testing parameters available for the VoIP pair object include the type of codec, the source and destination port numbers, whether to use silence suppression and its corresponding activity rate, the length of
the timing records generated, the initial delay, and the delay between packets.
You can also get results for a VoIP test using CHR_timingrec_get_MOS_estimate or one of
the CHR_pair_results functions.

- 722 -

IxChariot APIGuide

CHR_voip_pair_get_additional_delay
DESCRIPTION
The CHR_voip_pair_get_additional_delay function gets the delay value for the given endpoint pair. See also CHR_voip_pair_set_additional_delay.
C H R _API_R C
C H R _ v oi p_pai r_ get _addi t i onal _del ay (
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T* s iz e
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

size [out]
Specifies the size, in milliseconds, for the additional delay. Valid values are in the following ranges:
l

0(if you do not want IxChariot to emulate jitter buffering in your test).

101600, inclusive.

The recommended minimum must be at least 1 x speech frame size (delay between voice
datagrams).

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 723 -

IxChariot APIGuide

CHR_voip_pair_get_codec
DESCRIPTION
The CHR_voip_pair_get_codec function gets the codec type for the given endpoint pair.
C H R _API_R C
C H R _ v oi p_pai r_ get _c odec (
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _VOI P_C OD EC * c odec
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

codec[out]
A pointer to the variable where the codec is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 724 -

IxChariot APIGuide

CHR_voip_pair_get_concurrent_voice_streams
DESCRIPTION
The CHR_voip_pair_get_concurrent_voice_streams function sets the number of simulated voice streams for the given endpoint pair.
C H R _API_R C
C H R _ v oi p_pai r_ get _c onc urrent _v oi c e_ s t ream s (
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T* numSt reams
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

numStreams[out]
A pointer to the variable where the number of simulated streams is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 725 -

IxChariot APIGuide

CHR_voip_pair_get_datagram_delay
DESCRIPTION
The CHR_voip_pair_get_datagram_delay function gets the delay between voice datagrams
for one voice over IP pair. See also CHR_voip_pair_set_datagram_delay.
C H R _API_R C
C H R _ v oi p_pai r_ get _dat agram _del ay (
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T* delay
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

delay[out]
Specifies the delay in milliseconds (ms) that the user wishes to account for.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_NO_CODEC_IN_USE

CHR_PGM_INTERNAL_ERROR

See Return Code Summary for a detailed description of each return code.

- 726 -

IxChariot APIGuide

CHR_voip_pair_get_dest_port_num
DESCRIPTION
The CHR_voip_pair_get_dest_port_num function gets the destination port number for a
single voice over IP pair. See also CHR_voip_pair_set_dest_port_num on page 4-604.
C H R _API_R C
C H R _ v oi p_pai r_ get _des t _port _ num(
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _POR T* port
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

port [out]
Specifies the port number to be used. The value 0 (or the macro CHR_PORT_AUTO)
instructs Chariot to automatically select the port.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 727 -

IxChariot APIGuide

CHR_voip_pair_get_initial_delay
DESCRIPTION
The CHR_voip_pair_get_initial_delay function gets the delay before the first voice data
traffic is transmitted in the voice over IP test. See also CHR_voip_pair_set_initial_delay.
C H R _API_R C
C H R _ v oi p_pai r_ get _i ni t i al _ del ay (
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _STR I N G delay ,
C H R _LEN GTH len,
C H R _LEN GTH *rt nlen
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

delay[out]
A pointer to a string that will contain the initial delay in the same format as the one used
for set.

len [in]
The length of the delay string, excluding the null terminator. The string is limited to 24
characters.

rtnlen [out]
A pointer to the variable where the number of bytes in the buffer is returned, excluding the
null terminator--like strlen().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_BUFFER_TOO_SMALL

See Return Code Summary for a detailed description of each return code.

- 728 -

IxChariot APIGuide

CHR_voip_pair_get_jitter_buffer_size
DESCRIPTION
The CHR_voip_pair_get_jitter_buffer_size function gets the size of the jitter buffer. See
also CHR_voip_pair_set_jitter_buffer_size.
C H R _API_R C
C H R _ v oi p_pai r_ get _j i t t er_buf f er_ s i z e(
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T* s iz e
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

size [out]
Specifies the size, in milliseconds, for the jitter buffer.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

CHR_NO_CODEC_IN_USE

See Return Code Summary for a detailed description of each return code.

- 729 -

IxChariot APIGuide

CHR_voip_pair_get_source_port_num
DESCRIPTION
The CHR_voip_pair_get_source_port_num function gets the source port number for a voice
over IP pair. See also CHR_voip_pair_set_source_port_num.
C H R _API_R C
C H R _ v oi p_pai r_ get _s ourc e_port _ num(
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _POR T* port
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

port [out]
Specifies the port number to be used. The value 0 (or the macro CHR_PORT_AUTO)
instructs Chariot to automatically select the port.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 730 -

IxChariot APIGuide

CHR_voip_pair_get_tr_duration
DESCRIPTION
The CHR_voip_pair_get_tr_duration function gets the duration of a single timing record
generated by a single voice over IP pair. See also CHR_voip_pair_set_tr_duration.
C H R _API_R C
C H R _ v oi p_pai r_ get _ t r_durat i on(
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T* s ec onds
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

seconds [out]
Specifies the approximate time, in seconds, for one timing record to complete.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 731 -

IxChariot APIGuide

CHR_voip_pair_get_no_of_timing_records
DESCRIPTION
The CHR_voip_pair_get_no_of_timing_records function gets the number of timing records
for a VoIP pair. See also CHR_voip_pair_set_no_of_timing_records.
C H R _API_R C
C H R _ v oi p_pai r_ get _ no_of _ t i m i ng_rec ords (
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T *no_of _t r
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

no_of_tr [out]
Specifies the number of timing records that the endpoint will create during the execution of
a test.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 732 -

IxChariot APIGuide

CHR_voip_pair_get_use_PLC
DESCRIPTION
The CHR_voip_pair_get_use_PLC function gets the value of the use_PLC setting. See also
CHR_voip_pair_set_use_PLC.
C H R _API_R C
C H R _ v oi p_pai r_ get _us e_P LC (
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _BOOLEAN * us e
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

use [out]
Specifies CHR_TRUE or CHR_FALSE to indicate whether to use PLC.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 733 -

IxChariot APIGuide

CHR_voip_pair_get_use_silence_sup
DESCRIPTION
The CHR_voip_pair_get_use_silence_sup function gets the value of the silence suppression
setting. See also CHR_voip_pair_set_use_silence_sup.
C H R _API_R C
C H R _ v o i p _p a i r_ g e t _ u s e _ s i l e n c e _ s u p(
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _BOOLEAN * us e
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

use [out]
Specifies CHR_TRUE or CHR_FALSE to indicate whether to use silence suppression.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 734 -

IxChariot APIGuide

CHR_voip_pair_get_voice_activ_rate
DESCRIPTION
The CHR_voip_pair_get_voice_activ_rate function gets the voice activity rate for a voice
over IP pair. See also CHR_voip_pair_set_voice_activ_rate.
C H R _API_R C
C H R _ v oi p_pai r_ get _v oi c e_ ac t i v _ rat e(
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T* rat e
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

rate [out]
Specifies a voice activity rate percentage.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_POINTER_INVALID

See Return Code Summary for a detailed description of each return code.

- 735 -

IxChariot APIGuide

CHR_voip_pair_get_payload_file
DESCRIPTION
The CHR_voip_pair_get_payload_file function gets a file whose content will be used as payload when running the VoIP pair. See also CHR_voip_pair_set_payload_file.
C H R _API_R C
C H R _ v oi p_pai r_ get _pay l oad_ f i l e(
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _STR I N G f ilename
C H R _LEN GTH f ilenameLengt h
C H R _LEN GTH * rt nlen
C H R _BOOLEAN * embedded
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

filename [in]
The buffer that will hold the filename (as returned by this function).

filenameLength [in]
The size of the buffer.

rtnlen [out]
rtnlen = 0 means random payload is selected, while rtnlen > 0 means payload file is selected (and the file was set to "filename" buffer).

embedded [out]
Specifies whether the payload file will be embedded within the script or referenced as an
external file.
l
l

CHR_TRUEThe payload file is embedded within the script.

CHR_FALSEThe payload data is contained in an external file that is referenced from
within the script.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

- 736 -

IxChariot APIGuide

CHR_POINTER_INVALID

CHR_BUFFER_TOO_SMALL

See Return Code Summary for a detailed description of each return code.

- 737 -

IxChariot APIGuide

CHR_voip_pair_new
DESCRIPTION
The CHR_voip_pair_new function creates an endpoint pair object for voice over IP testing
and initializes it to object default values. See VoIP Pair Object for information on the
object default values.
The handle returned by this function is needed for other function calls to operate on the
voice over IP pair object. Many pair function calls will accept a VoIP pair object.
C H R _API_R C
C H R _ v oi p_pai r_ new (
C H R _V OI P _ P A I R _H A N D LE * pai rH andl e
)

PARAMETERS
pairHandle [out]
A pointer to the variable where the handle for the new endpoint pair is returned.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_OUT_OF_MEMORY

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NOT_LICENSED

See Return Code Summary for a detailed description of each return code.

- 738 -

IxChariot APIGuide

CHR_voip_pair_set_additional_delay
DESCRIPTION
The CHR_voip_pair_set_additional_delay function allows the user to set a delay value to
account for known delays (such as device delays) that are not otherwise measured by a
Chariot voice over IP test. This delay is included when calculating the MOS estimate and Rvalue.
CHR_API_RC
CHR_voip_pair_ set_additional_delay (
CHR_VOIP_ PAIR_HANDLE pairHandle,
CHR_COUNT delay
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

delay[out]
Specifies the delay in milliseconds (ms) that the user wishes to account for. Range is 0 to
300 ms.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 739 -

IxChariot APIGuide

CHR_voip_pair_set_codec
DESCRIPTION
The CHR_voip_pair_set_codec function sets or changes the codec for the given endpoint
pair.
C H R _API_R C
C H R _ v oi p_pai r_ s et _c odec (
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _VOI P_C OD EC c odec
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

codec[in]
Provides one of the following codecs:
CHR_VOIP_CODEC_G711u, CHR_VOIP_CODEC_G711a, CHR_VOIP_CODEC_G723_1A, CHR_
VOIP_CODEC_G723_1M, CHR_VOIP_CODEC_G726, CHR_VOIP_CODEC_G729, CHR_VOIP_
CODEC_AMR_NB_4_75, CHR_VOIP_CODEC_AMR_NB_5_15, CHR_VOIP_CODEC_AMR_NB_
5_9, CHR_VOIP_CODEC_AMR_NB_6_7, CHR_VOIP_CODEC_AMR_NB_7_4, CHR_VOIP_
CODEC_AMR_NB_7_95, CHR_VOIP_CODEC_AMR_NB_10_2, CHR_VOIP_CODEC_AMR_NB_
12_2, CHR_VOIP_CODEC_AMR_WB_6_6, CHR_VOIP_CODEC_AMR_WB_8_85, CHR_VOIP_
CODEC_AMR_WB_12_65, CHR_VOIP_CODEC_AMR_WB_14_25, CHR_VOIP_CODEC_AMR_
WB_15_85, CHR_VOIP_CODEC_AMR_WB_18_25, CHR_VOIP_CODEC_AMR_WB_19_85,
CHR_VOIP_CODEC_AMR_WB_23_05, CHR_VOIP_CODEC_AMR_WB_23_85.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

CHR_NO_SUCH_VALUE

See Return Code Summary for a detailed description of each return code.

- 740 -

IxChariot APIGuide

CHR_voip_pair_set_concurrent_voice_streams
DESCRIPTION
The CHR_voip_pair_set_concurrent_voice_streams function sets the number of simulated voice streams for the given endpoint pair.
C H R _API_R C
C H R _ v oi p_pai r_ s et _c onc urrent _v oi c e_ s t ream s (
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _C OU N T numSt reams
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

numStreams[in]
The number of streams to simulate.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 741 -

IxChariot APIGuide

CHR_voip_pair_set_datagram_delay
DESCRIPTION
The CHR_voip_pair_set_datagram_delay function sets or changes the delay between voice
datagrams for one voice over IP pair. By default, the delay is set to 20 ms (G711u, G711a,
G729, G.726) or 30 ms (G723.1A, G723.1M). The delay between datagrams is equivalent to
the datagram size. The timing record duration may be adjusted slightly so that only full buffers are sent.
C H R _API_R C
C H R _ v oi p_pai r_ s et _dat agram _del ay (
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T delay
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

delay[in]
Specifies the delay between voice datagrams in milliseconds (ms). Valid values are in the
range of 20 ms200 ms inclusive for G711u, G711a, G729, and G.726 codecs and 30 ms200
ms inclusive for G723.1A and G723.1M codecs.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 742 -

IxChariot APIGuide

CHR_voip_pair_set_dest_port_num
DESCRIPTION
The CHR_voip_pair_set_dest_port_num function sets or changes the destination port number for a single voice over IP pair. By default, the port number is set to CHR_PORT_AUTO.
C H R _API_R C
C H R _ v oi p_pai r_ s et _des t _port _ num(
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _POR T port
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

port [in]
Specifies the port number to be used. Valid values are in the range 065535 inclusive,
where 0 (or the macro CHR_PORT_AUTO) instructs Chariot to automatically select the port.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 743 -

IxChariot APIGuide

CHR_voip_pair_set_initial_delay
DESCRIPTION
The CHR_voip_pair_set_initial_delay function sets or changes the delay before the first
voice data traffic is transmitted in the voice over IP test. By default, the initial delay is set
to 0.
C H R _API_R C
C H R _ v oi p_pai r_ s et _i ni t i al _ del ay (
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _STR I N G delay ,
C H R _LEN GTH len
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

delay[in]
Specifies the initial delay distribution. Valid values are in the form of "d[x,y]", where:
l

d = u (uniform), n (normal), p (Poisson), or e (exponential) and

x,y = integers between "0" and "2147483647" where x < y

or an integer (constant) between 1 and 2147483647

len [in]
The length of the delay string, excluding the null terminator. The string is limited to 24
characters.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 744 -

IxChariot APIGuide

CHR_voip_pair_set_jitter_buffer_size
DESCRIPTION
The CHR_voip_pair_set_jitter_buffer_size function sets or changes the size of the jitter buffer. You can set the size of the jitter buffer to zero if you do not want IxChariot to emulate
jitter buffering in your test. By default, the jitter buffer is two times the delay between
packets.
C H R _API_R C
C H R _ v oi p_pai r_ s et _j i t t er_buf f er_ s i z e(
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T s iz e
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

size [in]
Specifies the size, in milliseconds, for the jitter buffer. Valid values are in the following
ranges:
l

0(if you do not want IxChariot to emulate jitter buffering in your test).

101600, inclusive.

The recommended minimum must be at least 1 x speech frame size (delay between voice
datagrams).

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 745 -

IxChariot APIGuide

CHR_voip_pair_set_no_of_timing_records
DESCRIPTION
The CHR_voip_pair_set_no_of_timing_records function allows you to set the number
of timing records for a VoIP pair.
C H R _API_R C
C H R _ v oi p_pai r_ s et _ no_of _ t i m i ng_rec ords (
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _ C OU N T no_ of _t r
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

no_of_tr [in]
Specifies the number of timing records that the endpoint will create during the execution of
a test. The valid range is from 1 to 2147483647, inclusive. The default value is 50.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 746 -

IxChariot APIGuide

CHR_voip_pair_set_payload_file
DESCRIPTION
The CHR_voip_pair_set_payload_file function allows a user to specify a file whose content
will be used as payload when running the VoIP pair.
C H R _API_R C
C H R _ v oi p_pai r_ s et _pay l oad_ f i l e(
C H R _V OI P _ P A I R _H A N D LE pai r,
C H R _STR I N G f ilename,
C H R _LEN GTH f ilenameLengt h,
C H R _BOOLEAN embedded
)
You cannot set the timing record duration if payload files are used. If you attempt to do so,
CHR_voip_pair_set_tr_duration will return CHR_NOT_SUPPORTED.
For AMR codecs, if silence suppression is enabled, this command will return CHR_NOT_
SUPPORTED.

PARAMETERS
pair [in]
A handle returned by CHR_voip_pair_new().

filename [in]
The name of the file containing the payload data.

filenameLength [in]
The length of the filename string.

embedded [in]
Specifies whether the payload file will be embedded within the script or referenced as an
external file:
l
l

CHR_TRUEThe payload file is embedded within the script.

CHR_FALSEThe payload data is contained in an external file that is referenced from
within the script.

The recommended option is CHR_TRUE - embedded.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

- 747 -

IxChariot APIGuide

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_PGM_INTERNAL_ERROR

CHR_POINTER_INVALID

CHR_NO_SCRIPT_IN_USE

CHR_OBJECT_IN_USE

CHR_STRING_TOO_LONG

CHR_VALUE_INVALID

CHR_OPERATION_FAILED

CHR_PAYLOAD_FILE_TOO_LARGE

If the specified file does not exit, CHR_OPERATION_FAILED will be returned. If filenameLength is 0, CHR_VALUE_INVALID will be returned. If file length is greater than 1 billion bytes (953MB), CHR_PAYLOAD_FILE_TOO_LARGE will be returned.
See Return Code Summary for a detailed description of each return code.

- 748 -

IxChariot APIGuide

CHR_voip_pair_set_payload_random
DESCRIPTION
The CHR_voip_pair_set_payload_random function sets the payload for a VoIP test to random data.
C H R _API_R C
C H R _ v oi p_pai r_ s et _pay l oad_ random (
C H R _V OI P _ P A I R _H A N D LE pai r
)
You cannot set the timing record duration if payload files are used. If you attempt to do so,
CHR_voip_pair_set_tr_duration will return CHR_NOT_SUPPORTED.

PARAMETERS
pair [in]
A handle returned by CHR_voip_pair_new().

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_NO_SUCH_OBJECT

CHR_NO_SCRIPT_IN_USE

CHR_OBJECT_IN_USE

See Return Code Summary for a detailed description of each return code.

- 749 -

IxChariot APIGuide

CHR_voip_pair_set_source_port_num
DESCRIPTION
The CHR_voip_pair_set_source_port_num function sets or changes the source port number
for a voice over IP pair. By default, the port number is set to CHR_PORT_AUTO.
C H R _API_R C
C H R _ v oi p_pai r_ s et _s ourc e_port _ num(
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _POR T port
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

port [in]
Specifies the port number to be used. Valid values are in the range 065535 inclusive,
where 0 (or the macro CHR_PORT_AUTO) instructs Chariot to automatically select the port.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 750 -

IxChariot APIGuide

CHR_voip_pair_set_tr_duration
DESCRIPTION
The CHR_voip_pair_set_tr_duration function sets or changes the duration of a single timing
record generated by a single voice over IP pair. By default, the duration is set to 3
seconds. The duration may be adjusted slightly so that only full buffers are sent.
C H R _API_R C
C H R _ v oi p_pai r_ s et _ t r_durat i on(
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T s ec onds
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

seconds [in]
Specifies the approximate time, in seconds, for one timing record to complete. Valid values are in the range of 13600 inclusive.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 751 -

IxChariot APIGuide

CHR_voip_pair_set_use_PLC
DESCRIPTION
The CHR_voip_pair_set_use_PLC function allows you to emulate packet loss concealment
(PLC). PLC is supported by the G.711 codecs only. The default setting is not to use PLC
(CHR_FALSE).
CHR_API_RC
CHR_voip_pair_ set_use_PLC(
CHR_VOIP_ PAIR_HANDLE pairHandle,
CHR_BOOLEAN use
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

use [in]
Specifies CHR_TRUE or CHR_FALSE to indicate whether to use PLC.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 752 -

IxChariot APIGuide

CHR_voip_pair_set_use_silence_sup
DESCRIPTION
The CHR_voip_pair_set_use_silence_sup function sets or changes whether silence suppression is enabled. If the value is set to CHR_TRUE, silence suppression is enabled. The
voice activity rate (set by CHR_voip_pair_set_voice_activ_rate) is ignored when this value
is set to CHR_FALSE.
C H R _API_R C
C H R _ v o i p _p a i r_ s e t _ u s e _ s i l e n c e _ s u p(
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _BOOLEAN us e
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

use [in]
Specifies CHR_TRUE or CHR_FALSE to indicate whether to use silence suppression.

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 753 -

IxChariot APIGuide

CHR_voip_pair_set_voice_activ_rate
DESCRIPTION
The CHR_voip_pair_set_voice_activ_rate function sets or changes the voice activity rate
for silence suppression in the voice over IP test. This value is ignored unless silence suppression has been enabled (see CHR_voip_pair_set_use_silence_sup). By default, the activity rate is set to 50 percent.
C H R _API_R C
C H R _ v oi p_pai r_ s et _v oi c e_ ac t i v _ rat e(
C H R _V OI P _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T rat e
)

PARAMETERS
pairHandle [in]
A handle returned by CHR_voip_pair_new() or CHR_test_get_pair().

rate [in]
Specifies a voice activity rate percentage (1-100).

RETURN CODES
The following return code indicates that the function call was successful:
CHR_OK
The following return codes indicate that an error occurred and any returned values should
be ignored:
l

CHR_API_NOT_INITIALIZED

CHR_HANDLE_INVALID

CHR_NO_MEMORY

CHR_OBJECT_IN_USE

CHR_PGM_INTERNAL_ERROR

CHR_VALUE_INVALID

See Return Code Summary for a detailed description of each return code.

- 754 -

IxChariot APIGuide

Typedefs and Enumerations

c hrapi. h, 7. 10. 36. 171
/*
* C hariot API ret urn c odes
*/
#def i ne C H R _ R C _B A S E
100
#def ine C H R _OK
0
#def i ne C H R _H A N D LE _I N V A LI D
(C H R _R C _ B A S E + 1)
#def i ne C H R _S T R I N G_T OO_LON G
(C H R _R C _ B A S E + 2)
#def ine C H R _POI N TER _I N VALI D
(C H R _R C _ B A S E + 3)
#def i ne C H R _ N O_S U C H _ OB J E C T
(C H R _R C _ B A S E + 4)
#def i ne C H R _T E S T _N OT _R U N
(C H R _R C _ B A S E + 5)
#def i ne C H R _T E S T _R U N N I N G
(C H R _R C _ B A S E + 6)
#def i ne C H R _OB J E C T _I N _ U S E
(C H R _R C _ B A S E + 7)
#def ine C H R _OPER ATI ON _FAI LED
(C H R _R C _ B A S E + 8)
#def i ne C H R _ N O_T E S T _ F I LE
(C H R _R C _ B A S E + 9)
#def ine C H R _R ESU LTS_N OT_C LEAR ED
(C H R _R C _ B A S E + 10)
#def i ne C H R _P A I R _LI M I T _ E X C E E D E D
(C H R _R C _ B A S E + 11)
#def i ne C H R _OB J E C T _I N V A LI D
(C H R _R C _ B A S E + 12)
#def ine C H R _API _N OT_I N I TI ALI ZED
(C H R _R C _ B A S E + 13)
#def i ne C H R _ N O_R E S U LT S
(C H R _R C _ B A S E + 14)
#def ine C H R _VALU E_I N VALI D
(C H R _R C _ B A S E + 15)
#def i ne C H R _ N O_S U C H _ V A LU E
(C H R _R C _ B A S E + 16)
#def i ne C H R _ N O_S C R I P T _ I N _U S E
(C H R _R C _ B A S E + 17)
#def ine C H R _TI MED _OU T
(C H R _R C _ B A S E + 18)
#def i ne C H R _B U F F E R _T OO_S M A LL
(C H R _R C _ B A S E + 19)
#def i ne C H R _ N O_M E M OR Y
(C H R _R C _ B A S E + 20)
#def i ne C H R _P GM _I N T E R N A L_E R R OR
(C H R _R C _ B A S E + 21)
#def ine C H R _TR AC ER T_N OT_R U N
(C H R _R C _ B A S E + 22)
#def ine C H R _TR AC ER T_R U N N I N G
(C H R _R C _ B A S E + 23)
#def ine C H R _N OT_SU PPOR TED
(C H R _R C _ B A S E + 24)
#def i ne C H R _ N O_C OD E C _ I N _ U S E
(C H R _R C _ B A S E + 25)
#def ine C H R _N OT_LI C EN SED
(C H R _R C _ B A S E + 26)
#def i ne C H R _S C R I P T _T OO_LA R GE
(C H R _R C _ B A S E + 27)
#def ine C H R _LI C EN SE_H AS_EXPI R ED
(C H R _R C _ B A S E + 28)
#def i ne C H R _ N O_N E T W OR K _ C ON F I GU R A T I ON
(C H R _R C _ B A S E + 29)
#def i ne C H R _I N V A LI D _ N E T W OR K _ C ON F I GU R A T I ON (C H R _R C _ B A S E +
30)
#def i ne C H R _E R R OR _A C C E S S I N G_T E S T S E R V E R _S E S S I ON (C H R _ R C _
BASE + 31)
#def i ne C H R _F U N C T I ON _N OT _S U P P OR T E D
(C H R _R C _ B A S E + 32)
#def i ne C H R _T E S T _N OT _S A V E D
(C H R _R C _ B A S E + 33)
#def i ne C H R _LI C E N S E _ W I LL_E X P I R E
(C H R _R C _ B A S E + 34)
#def ine C H R _APP_GR OU P_N OT_VALI D ATED
(C H R _R C _ B A S E + 35)
#def ine C H R _APP_GR OU P_I N VALI D
(C H R _R C _ B A S E + 36)
#def ine C H R _APP_GR OU P_D U PLI C ATE_N AME
(C H R _R C _ B A S E + 37)
#def i ne C H R _ P A Y LOA D _ F I LE _T OO_LA R GE
(C H R _R C _ B A S E + 38)
#def i ne C H R _ N O_A P P LI F I E R _ C ON F I GU R A T I ON
(C H R _R C _ B A S E + 39)
#def ine C H R _C H AN N EL_D U PLI C ATE_N AME
(C H R _R C _ B A S E + 40)
#def i ne C H R _R E C E I V E R _D U P LI C A T E _N A M E
(C H R _R C _ B A S E + 41)

- 755 -

IxChariot APIGuide
#def i ne C H R _I P T V _I N V A LI D
(C H R _R C _ B A S E + 42)
#def ine C H R _D U PLI C ATE_N AME
(C H R _R C _ B A S E + 43)
#def ine C H R _LI C EN SE_ALR EAD Y_BOR R OW ED
(C H R _R C _ B A S E + 44)
#def i ne C H R _F LOA T I N G_LI C E N S E _I N _ U S E
(C H R _R C _ B A S E + 45)
#def i ne C H R _ N O_M U LT I S E S S I ON _ LI C E N S E
(C H R _R C _ B A S E + 46)
#def i ne C H R _R A V E _S I N GLE _ R U N N I N G
(C H R _R C _ B A S E + 47)
#def i ne C H R _R A V E _M U LT I _ R U N N I N G
(C H R _R C _ B A S E + 48)
/*
* St ring buf f er max imum s iz es (inc luding a t erminat ing &#39; \ 0&#39; )
*/
#def ine C H R _MAX_D I R _PATH
301
#def ine C H R _MAX_FI LEN AME
301
#def i ne C H R _ M A X _ F I LE _P A T H
(C H R _M A X _D I R _P A T H + C H R _
MAX_FI LEN AME)
#def i ne C H R _M A X _E M B E D D E D _P A Y LOA D _S I Z E 27904
#def ine C H R _MAX_ER R OR _I N FO
4096
#def i ne C H R _M A X _P A I R _C OM M E N T
65
#def ine C H R _MAX_AD D R
65
#def ine C H R _MAX_MU LTI C AST_AD D R
16
#def ine C H R _MAX_QOS_N AME
65
#def i ne C H R _M A X _A P P L_S C R I P T _ N A M E
65
#def ine C H R _MAX_GR OU P_N AME
65
#def ine C H R _MAX_VER SI ON
32
#def i ne C H R _M A X _R E T U R N _M S G
256
#def i ne C H R _M A X _S C R I P T _V A R I A B LE _ N A M E 25
#def i ne C H R _M A X _S C R I P T _V A R I A B LE _ V A LU E 65
#def ine C H R _MAX_C FG_PAR M
512
#def i ne C H R _M A X _A D D R _S T R I N G
C H R _MAX_AD D R
#def ine C H R _BSSI D _SI ZE
18
#def ine C H R _MAX_APP_GR OU P_N AME
25
#def ine C H R _MAX_APP_GR OU P_C OMMEN T
129
#def ine C H R _MAX_APP_GR OU P_EVEN T_N AME 25
#def ine C H R _MAX_APP_GR OU P_EVEN T_C OMMEN T 129
#def ine C H R _MAX_C H AN N EL_N AME
33
#def i ne C H R _M A X _R E C E I V E R _N A M E
33
#def ine C H R _MAX_C H AN N EL_C OMMEN T
65
#def i ne C H R _M A X _R E C E I V E R _C OM M E N T
65
#def i ne C H R _S OC K E T _B U F F E R _ D E F A U LT
2147483647
/*
* H andle D ef init ions
*/
t y pedef uns igned long C H R _H AN D LE;
t y pedef C H R _H AN D LE
C H R _T E S T _H A N D LE ;
t y pedef C H R _H AN D LE
C H R _P A I R _H A N D LE ;
t y pedef C H R _H AN D LE
C H R _V OI P _P A I R _ H A N D LE ;
t y pedef C H R _H AN D LE
C H R _H A R D W A R E _P A I R _ H A N D LE ;
t y pedef C H R _H AN D LE
C H R _R U N OPTS_H AN D LE;
t y pedef C H R _H AN D LE
C H R _D GOP T S _H A N D LE ;
t y pedef C H R _H AN D LE
C H R _P R E S OP T S _H A N D LE ;
t y pedef C H R _H AN D LE
C H R _M GR OU P _H A N D LE ;
t y pedef C H R _H AN D LE
C H R _MPAI R _H AN D LE;
t y pedef C H R _H AN D LE
C H R _TI MI N GR EC _H AN D LE;
t y pedef C H R _H AN D LE
C H R _T R A C E R T _ P A I R _H A N D LE ;

- 756 -

IxChariot APIGuide
t y pedef C H R _H AN D LE
C H R _H OP R E C _H A N D LE ;
t y pedef C H R _H AN D LE
C H R _V I D E O_ P A I R _H A N D LE ;
t y pedef C H R _H AN D LE
C H R _V I D E O_M GR OU P _H A N D LE ;
t y pedef C H R _H AN D LE
C H R _APP_GR OU P_H AN D LE;
t y pedef C H R _H AN D LE
C H R _C H AN N EL_H AN D LE;
t y pedef C H R _H AN D LE
C H R _R E C E I V E R _H A N D LE ;
t y pedef C H R _H AN D LE
C H R _VPAI R _H AN D LE;
t y pedef C H R _H AN D LE
C H R _R E P OR T _H A N D LE ;
/*
* Ty pe D ef init ions and C ons t ant s
*/
t y pedef c har
C H R _C H AR ;
t y pedef uns igned c har C H R _BYTE;
t y pedef C H R _C H AR *
C H R _STR I N G;
t y pedef c ons t c har*
C H R _C ON ST_STR I N G;
t y pedef uns igned long C H R _LEN GTH ;
t y pedef uns igned long C H R _C OU N T;
t y pedef double
C H R _FLOAT;
t y pedef uns igned s hort C H R _POR T;
t y pedef int
C H R _MESSAGE_N U MBER ;
t y pedef int
C H R _API_R C ;
t y pedef long
C H R _LON G;
# i f d e f i n e d(_ M S C _ V E R )
t y pedef __ i nt 64
C H R _W LON G;
#els e
t y pedef long long
C H R _W LON G;
#endif
t y pedef C H R _C H A R C H R _A D D R _ S T R I N G[ C H R _M A X _A D D R _ S T R I N G] ;
#def i ne C H R _N U LL_H A N D LE 0
t y pedef c har C H R _BOOLEAN ;
#def ine C H R _TR U E 1
#def ine C H R _FALSE 0
#def ine C H R _I N FI N I TE 0x f f f f f f f f
/*
* Prot oc ol
*/
t y pedef c har C H R _PR OTOC OL;
#def i ne C H R _P R OT OC OL_A P P C _ N OT _S U P P OR T E D 1 / * A P P C i s no
longer s upport ed */
#def i ne C H R _P R OT OC OL_T C P
2
#def i ne C H R _P R OT OC OL_I P X
3
#def i ne C H R _P R OT OC OL_S P X
4
#def i ne C H R _P R OT OC OL_U D P
5
#def i ne C H R _P R OT OC OL_R T P
6
#def i ne C H R _P R OT OC OL_T C P 6
7
#def i ne C H R _P R OT OC OL_U D P 6
8
#def i ne C H R _P R OT OC OL_R T P 6
9
/*
*QoS t emplat e t y pes
*/
t y pedef c har C H R _QOS_TEMPLATE_TYPE;
#def i ne C H R _QOS _T E M P LA T E _T OS _B I T _M A S K
1
#def i ne C H R _QOS _T E M P LA T E _D I F F S E R V
2

- 757 -

IxChariot APIGuide
#def i ne C H R _QOS _T E M P LA T E _L2_ P R I OR I T Y
3
/*
* VoI P C odec s -- map t o C H R def s
*/
t y pedef I X _V OI P _ C OD E C C H R _ V OI P _C OD E C ;
#def i ne C H R _V OI P _C OD E C _ N ON E
I X _ V OI P _C OD E C _ N ON E
#def i ne C H R _V OI P _C OD E C _ G711u
I X _ V OI P _C OD E C _ G711u
#def i ne C H R _V OI P _C OD E C _ G723_ 1A I X _ V OI P _C OD E C _ G723_ 1A
#def i ne C H R _V OI P _C OD E C _ G723_ 1M I X _ V OI P _C OD E C _ G723_ 1M
#def i ne C H R _V OI P _C OD E C _ G729
I X _ V OI P _C OD E C _ G729
#def i ne C H R _V OI P _C OD E C _ G711a
I X _ V OI P _C OD E C _ G711a
#def i ne C H R _V OI P _C OD E C _ G726
I X _ V OI P _C OD E C _ G726
/*
* Video C odec s
*/
t y pedef c har C H R _VI D EO_C OD EC ;
#def ine C H R _VI D EO_C OD EC _N ON E
1
#def ine C H R _VI D EO_C OD EC _MPEG2
2
#def ine C H R _VI D EO_C OD EC _C U STOM
3
/*
* Port N umber
*/
#def i ne C H R _P OR T _A U T O 0
/*
* Error I nf ormat ion D et ail Lev el
*/
t y pedef uns i gned l ong C H R _D E T A I L_LE V E L;
#def i ne C H R _D E T A I L_LE V E L_N ON E
0x 0000
#def i ne C H R _D E T A I L_LE V E L_P R I M A R Y 0x 00a3
#def i ne C H R _D E T A I L_LE V E L_A D V A N C E D (0x 0014 | C H R _D E T A I L_
LEVEL_PR I MAR Y)
#def i ne C H R _D E T A I L_LE V E L_A LL
(0x 0148 | C H R _D E T A I L_LE V E L_
ADVANCED)
/*
* Throughput U nit s
*/
t y pedef c har C H R _TH R OU GH PU T_U N I TS;
#def i ne C H R _T H R OU GH P U T _U N I T S _K B 1
#def i ne C H R _T H R OU GH P U T _U N I T S _k B 2
#def i ne C H R _T H R OU GH P U T _U N I T S _K b 3
#def i ne C H R _T H R OU GH P U T _U N I T S _k b 4
#def i ne C H R _T H R OU GH P U T _U N I T S _M b 5
#def i ne C H R _T H R OU GH P U T _U N I T S _Gb 6
/*
* W hen To End Tes t
*/
t y pedef c har C H R _TEST_EN D ;
#def i ne C H R _T E S T _E N D _W H E N _ F I R S T _ C OM P LE T E S 1
#def i ne C H R _T E S T _E N D _W H E N _ A LL_C OM P LE T E
2
#def i ne C H R _T E S T _E N D _A F T E R _ F I X E D _ D U R A T I ON 3
/*
* H ow Tes t Ended
*/

- 758 -

IxChariot APIGuide
t y pedef c har C H R _TEST_H OW _EN D ED ;
#def i ne C H R _T E S T _H OW _E N D E D _ U S E R _ S T OP P E D 1
#def i ne C H R _T E S T _H OW _E N D E D _ E R R OR
2
#def i ne C H R _T E S T _H OW _E N D E D _ N OR M A L
3
/*
* Tes t R eport ing
*/
t y pedef c har C H R _TEST_R EPOR TI N G;
#def i ne C H R _T E S T _R E P OR T I N G_ R E A LT I M E
1
#def i ne C H R _T E S T _R E P OR T I N G_ B A T C H
2
/*
* Tes t R eport ing Firew all
*/
t y pedef c har C H R _TEST_R EPOR TI N G_FI R EW ALL;
#def i ne C H R _T E S T _R E P OR T I N G_ N O_ F I R E W A LL
11
#def i ne C H R _T E S T _R E P OR T I N G_ U S E _F I R E W A LL
12
/*
* Tes t Poll R et riev ing
*/
t y pedef c har C H R _TEST_R ETR I EVI N G;
#def i ne C H R _T E S T _R E T R I E V E _ N U M B E R
1
#def i ne C H R _T E S T _R E T R I E V E _ T I M I N G_R E C OR D
2
/*
* Tes t R es ult s
*/
t y pedef c har C H R _R ESU LTS;
#def ine C H R _R ESU LTS_TH R OU GH PU T
1
#def ine C H R _R ESU LTS_TR AN SAC TI ON _R ATE
2
#def i ne C H R _R E S U LT S _R E S P ON S E _T I M E
3
#def ine C H R _R ESU LTS_J I TTER
4
/ * R FC 1889 jit t er c alc ulat ion
*/
#def ine C H R _R ESU LTS_D ELAY_VAR I ATI ON
5
/ * t y pic ally c alled
jit t er
*/
#def ine C H R _R ESU LTS_C ON SEC U TI VE_LOST
6
#def ine C H R _R ESU LTS_MOS_ESTI MATE
7
#def i ne C H R _R E S U LT S _ R OU N D _ T R I P _D E LA Y
8
#def ine C H R _R ESU LTS_ON E_W AY_D ELAY
9
#def ine C H R _R ESU LTS_R _VALU E
10
#def i ne C H R _ R E S U LT S _ E N D _ T O_E N D _ D E LA Y
11
#def i ne C H R _R E S U LT S _ R S S I _E 1
12
#def i ne C H R _R E S U LT S _ R S S I _E 2
13
#def ine C H R _R ESU LTS_D F
14
#def ine C H R _R ESU LTS_MLR
15
#def i ne C H R _R E S U LT S _ J OI N _LA T E N C Y
16
#def ine C H R _R ESU LTS_LEAVE_LATEN C Y
17
/*
* Endpoint C onf ig paramet ers
*/
t y pedef c har C H R _C FG_PAR M;
#def i ne C H R _C F G_P A R M _E N D P OI N T _ V E R S I ON
1
#def i ne C H R _C F G_P A R M _E N D P OI N T _ B U I LD _ LE V E L
2

- 759 -

IxChariot APIGuide
#def i ne C H R _C F G_P A R M _E N D P OI N T _ P R OD U C T _ T Y P E
3
#def i ne C H R _C F G_P A R M _E N D P OI N T _ OS
4
#def i ne C H R _ C F G_P A R M _E N D P OI N T _ C P U _U T I L_S U P P OR T
5
#def i ne C H R _ C F G_ P A R M _E N D P OI N T _ OS _M A J OR _ V E R
6
#def i ne C H R _ C F G_ P A R M _E N D P OI N T _ OS _M I N OR _ V E R
7
#def i ne C H R _ C F G_ P A R M _E N D P OI N T _ OS _B U I LD _ N U M
8
#def i ne C H R _C F G_P A R M _E N D P OI N T _ C S D _V E R S I ON
9
#def i ne C H R _C F G_P A R M _E N D P OI N T _ M E M OR Y
10
#def i ne C H R _C F G_P A R M _E N D P OI N T _ A P P C _D E F A U LT _ S E N D _ N OT _
SU PPOR TED 11 / * APPC is no
longer s upport ed */
#def i ne C H R _C F G_P A R M _E N D P OI N T _ I P X _D E F A U LT _ S E N D
12
#def i ne C H R _C F G_P A R M _E N D P OI N T _ S P X _D E F A U LT _ S E N D
13
#def i ne C H R _C F G_P A R M _E N D P OI N T _ T C P _D E F A U LT _ S E N D
14
#def i ne C H R _C F G_P A R M _E N D P OI N T _ U D P _D E F A U LT _ S E N D
15
#def i ne C H R _C F G_P A R M _E N D P OI N T _ R T P _D E F A U LT _ S E N D
16
#def i ne C H R _C F G_P A R M _E N D P OI N T _ A P P C _S T A C K _ N OT _S U P P OR T E D
17 / * APPC is no
longer s upport ed */
#def i ne C H R _C F G_P A R M _E N D P OI N T _ A P P C _A P I _V E R S I ON _ N OT _
SU PPOR TED 18 / * APPC is no
longer s upport ed */
#def i ne C H R _C F G_P A R M _E N D P OI N T _ W I N S OC K _ A P I
19
#def i ne C H R _C F G_P A R M _E N D P OI N T _ W I N S OC K _ S T A C K _ V E R
20
#def i ne C H R _C F G_P A R M _E N D P OI N T _ W I N S OC K _ A P I _V E R
21
#def i ne C H R _C F G_P A R M _E N D P OI N T _ M E M OR Y _LI M I T _P A Y LOA D _ F I LE S
22
#def i ne C H R _C F G_P A R M _E N D P OI N T _ M A X _M E M OR Y _U S A GE _
PAYLOAD _FI LES 23
#def i ne C H R _C F G_P A R M _E N D P OI N T _ M A X _D I S K _U S A GE _ P A Y LOA D _
FI LES
24
#def i ne C H R _C F G_P A R M _E N D P OI N T _ U S E _E N C R Y P T E D _ F LOW S
25
#def i ne C H R _C F G_P A R M _E N D P OI N T _ M A N A GE M E N T _P OR T
26
#def i ne C H R _C F G_P A R M _E N D P OI N T _ LA S T
CHR_
C FG_PAR M_
E N D P OI N T _M A N A GE M E N T _ P OR T
/*
* Trac erout e run s t at us
*/
t y pedef c har C H R _TR AC ER T_R U N STATU S_TYPE;
#def ine C H R _TR AC ER T_R U N STATU S_U N I N I TI ALI ZED 0
#def ine C H R _TR AC ER T_R U N STATU S_I N I TI ALI ZI N G 1
#def ine C H R _TR AC ER T_R U N STATU S_R U N N I N G
2
#def ine C H R _TR AC ER T_R U N STATU S_STOPPI N G
3
#def ine C H R _TR AC ER T_R U N STATU S_ER R OR
4
#def ine C H R _TR AC ER T_R U N STATU S_FI N I SH ED
5
#def i ne C H R _T R A C E R T _ R U N S T A T U S _ U S E R _S T OP P E D 6
/*
* Pair run s t at us

- 760 -

IxChariot APIGuide
*/
t y pedef c har C H R _PAI R _R U N STATU S_TYPE;
#def i ne C H R _P A I R _R U N S T A T U S _ U N I N I T I A LI Z E D
0
#def i ne C H R _P A I R _R U N S T A T U S _ I N I T I A LI Z I N G_ 1
1
#def i ne C H R _P A I R _R U N S T A T U S _ I N I T I A LI Z I N G_ 2
2
#def i ne C H R _P A I R _R U N S T A T U S _ I N I T I A LI Z I N G_ 3
3
#def i ne C H R _P A I R _R U N S T A T U S _ I N I T I A LI Z E D
4
#def i ne C H R _P A I R _R U N S T A T U S _ R U N N I N G
5
#def i ne C H R _P A I R _R U N S T A T U S _ S T OP P I N G
6
#def i ne C H R _P A I R _R U N S T A T U S _ R E QU E S T E D _ S T OP
7
#def i ne C H R _P A I R _R U N S T A T U S _ E R R OR
8
#def i ne C H R _P A I R _R U N S T A T U S _ R E S OLV I N G_ N A M E S
9
#def i ne C H R _P A I R _R U N S T A T U S _ P OLLI N G
10
#def i ne C H R _P A I R _R U N S T A T U S _ F I N I S H E D
11
#def i ne C H R _P A I R _R U N S T A T U S _ R E QU E S T I N G_ S T OP
12
#def i ne C H R _P A I R _R U N S T A T U S _ F I N I S H E D _ W A R N I N GS 13
#def i ne C H R _P A I R _R U N S T A T U S _ T R A N S F E R R I N G_ P A Y LOA D 14
#def i ne C H R _ P A I R _R U N S T A T U S _ A P P LY I N G_ I X I A _C ON F I G 15
#def i ne C H R _P A I R _R U N S T A T U S _ W A I T I N G_ F OR _R E I N I T 16
#def i ne C H R _P A I R _R U N S T A T U S _ A B A N D ON E D
17
/*
* H PP meas ure/ s t at s opt ion.
*/
t y pedef c har C H R _MEASU R E_STATS;
#def i ne C H R _ M E A S U R E _ S T A T S _ N O_S T A T S _ F I LT E R S 0
#def ine C H R _MEASU R E_STATS_STATS_FI LTER S
1
#def ine C H R _MEASU R E_STATS_FI LTER S
2
/*
* Pair t y pe
*/
t y pedef c har C H R _PAI R _TYPE;
#def i ne C H R _P A I R _T Y P E _ R E GU LA R
1 / * Pairs w it h nons t reaming
s c ript s */
#def i ne C H R _P A I R _T Y P E _ S T R E A M I N G
2
#def i ne C H R _P A I R _T Y P E _ V OI P
3
#def i ne C H R _P A I R _T Y P E _ V I D E O
4
#def i ne C H R _P A I R _T Y P E _ H A R D W A R E
5
#def i ne C H R _P A I R _T Y P E _ H A R D W A R E _V OI P
6
/*
* Lic ens e t y pe
*/
t y pedef c har C H R _LI C EN SE_TYPE;
#def i ne C H R _LI C E N S E _ T Y P E _N ON E
1
#def i ne C H R _LI C E N S E _ T Y P E _N OD E _ LOC K E D
2
#def i ne C H R _LI C E N S E _ T Y P E _F LOA T I N G
3
#def i ne C H R _LI C E N S E _ T Y P E _F LOA T I N G_ B OR R OW
4
/**
* R eport it em.
*/
t y pedef c har C H R _R EPOR T_I TEM;
#def i ne C H R _R E P OR T _I T E M _ J OI N _LE A V E
1
/ **< J oin/ leav e lat enc ies . */

- 761 -

IxChariot APIGuide
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/*
C H R _GR OU P I N G_T Y P E
*/
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
t y pedef uns i gned c har C H R _GR OU P I N G_T Y P E ;
#def i ne C H R _ GR OU P I N G_T Y P E _ N O_GR OU P I N G
1
#def i ne C H R _GR OU P I N G_T Y P E _ E N D P OI N T 1
2
#def i ne C H R _GR OU P I N G_T Y P E _ E N D P OI N T 2
3
#def i ne C H R _GR OU P I N G_T Y P E _ P R OT OC OL
4
#def i ne C H R _GR OU P I N G_T Y P E _ S C R I P T
5
#def i ne C H R _GR OU P I N G_T Y P E _ S E R V I C E _QU A LI T Y
6
#def i ne C H R _GR OU P I N G_T Y P E _ U S E R _GR OU P
7
#def i ne C H R _GR OU P I N G_T Y P E _ P A I R _C OM M E N T
8
#def i ne C H R _ GR OU P I N G_T Y P E _ C ON S OLE _ E 1_A D D R
9
#def i ne C H R _ GR OU P I N G_T Y P E _ E 1_E 2_ A D D R
10
#def i ne C H R _GR OU P I N G_T Y P E _ R U N _S T A T U S
11
#def i ne C H R _ GR OU P I N G_T Y P E _ D Y N A M I C _ E 1_M GM T
12
#def i ne C H R _ GR OU P I N G_T Y P E _ D Y N A M I C _ E 2_M GM T
13
#def i ne C H R _ GR OU P I N G_T Y P E _ E 1_S E R V I C E _ QU A LI T Y
CHR_
GR OU P I N G_T Y P E _ S E R V I C E _
QU ALI TY
#def i ne C H R _ GR OU P I N G_T Y P E _ E 2_S E R V I C E _ QU A LI T Y
14
t y pedef uns i gned c har C H R _S OR T _OR D E R ;
#def i ne C H R _S OR T _OR D E R _ A S C E N D I N G
1
#def i ne C H R _S OR T _OR D E R _ D E S C E N D I N G
2
#if ndef C H R _API _FN
#def i ne C H R _ A P I _ F N _ _c dec l / * api & #39; s c al l i ng c onv ent i on * /
#endif
/*
* API U t ilit y Func t ions
*/
C H R _API_R C C H R _API_FN
C H R _api_get _max _pairs(
C H R _C OU N T* max Pairs );
C H R _API_R C C H R _API_FN
C H R _api_get _lic ens e_t y pe(
C H R _LI C EN SE_TYPE* lic ens eTy pe);
C H R _API_R C C H R _API_FN
C H R _api _get _l i c ens e_ex pi rat i on_t i m e(
C H R _LON G* ex pirat ionTime);
C H R _API_R C C H R _API_FN
C H R _api_get _report ing_port (
C H R _PR OTOC OL prot oc ol,
C H R _POR T* port );
C H R _API_R C C H R _API_FN
C H R _api _get _ret urn_m s g (
C H R _API _R C ret urnC ode,
C H R _STR I N G ret urnMs g,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ a p i _ g e t _ v e rs i o n(
C H R _STR I N G v ers ion,
C H R _LEN GTH max Lengt h,

- 762 -

IxChariot APIGuide
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _api_get _build_lev el(
C H R _STR I N G v ers ion,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ a p i _ g e t _ a p t i x i a _ v e rs i o n(
C H R _STR I N G v ers ion,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _api_init ializ e(
C H R _D E T A I L_LE V E L det ai l Lev el ,
C H R _STR I N G errorI nf o,
C H R _LEN GTH errorI nf oMax Lengt h,
C H R _LEN GTH * errorI nf oLengt h);
C H R _API_R C C H R _API_FN
C H R _api _i ni t i al i z e_w i t h_ l i c ens e_det ai l s (C H R _ D E T A I L_LE V E L
det ailLev el,
C H R _STR I N G errorI nf o, C H R _LEN GTH errorI nf oMax Lengt h,
C H R _LEN GTH * errorI nf oLengt h, C H R _STR I N G s erv erN ame,
C H R _C OU N T pairC ount , C H R _C OU N T day s ToBorrow );
C H R _API_R C C H R _API_FN
C H R _api_s et _report ing_port (
C H R _PR OTOC OL prot oc ol,
C H R _POR T port );
C H R _API_R C C H R _API_FN
C H R _ api _get _pai r_t y pe(
C H R _H AN D LE handle,
C H R _P A I R _T Y P E * t y pe);
/* Ixia */
C H R _API_R C C H R _API_FN
C H R _ api _ get _ port _m gm t _ i p_l i s t (
C H R _ C OU N T i p_addr_ c ount ,
C H R _A D D R _S T R I N G* i p_ l i s t ,
C H R _ C OU N T * i p_ addr_read);
C H R _API_R C C H R _API_FN
C H R _ api _ get _ net w ork _ i p_l i s t (
C H R _C H A R port _ m gm t _i p[ C H R _ M A X _A D D R _S T R I N G] ,
C H R _ C OU N T i p_addr_ c ount ,
C H R _A D D R _S T R I N G* i p_ l i s t ,
C H R _ C OU N T * i p_ addr_read);
/*
* Lic ens ing C ont rol Func t ions
*/
C H R _API_R C C H R _API_FN
C H R _ api _l i c ens e_ get _t es t _pai r_ c ount (
C H R _STR I N G t es t FileN ame,
C H R _LEN GTH t es t FileN ameLengt h,
C H R _C OU N T *pairC ount );
C H R _API_R C C H R _API_FN
C H R _api _l i c ens e_c hec k out _pai rs (

- 763 -

IxChariot APIGuide
C H R _C OU N T noPairs );
C H R _API_R C C H R _API_FN
C H R _api_lic ens e_c hec k in_pairs(v oid);
C H R _API_R C C H R _API_FN
C H R _api _l i c ens e_c hange_borrow _ t i m e(
C H R _C OU N T day s ToBorrow );
C H R _API_R C C H R _API_FN
C H R _api _l i c ens e_c hange_l i c ens e_s erv er(
C H R _STR I N G s erv erN ame);
C H R _API_R C C H R _API_FN
C H R _api_lic ens e_get _lic ens e_s erv er(
C H R _STR I N G *s erv erN ame,
C H R _LEN GTH max N ameLengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ api _ l i c ens e_ get _ borrow _day s _ rem ai ni ng(
C H R _C OU N T *day s R emaining);
/*
* QoS f unc t ions
*/
C H R _API_R C C H R _API_FN
C H R _api_new _qos _t os _t emplat e(
C H R _QOS _T E M P LA T E _T Y P E t em pl at eT y pe,
C H R _STR I N G t emplat eN ame,
C H R _LEN GTH t emplat eLengt h,
C H R _BYTE t os Mas k );
C H R _API_R C C H R _API_FN
C H R _api _del et e_qos _t em pl at e(
C H R _STR I N G t emplat eN ame,
C H R _LEN GTH t emplat eLengt h);
C H R _API_R C C H R _API_FN
C H R _api _m odi f y _qos _t os _t em pl at e(
C H R _QOS _T E M P LA T E _T Y P E t em pl at eT y pe,
C H R _STR I N G t emplat eN ame,
C H R _LEN GTH t emplat eLengt h,
C H R _BYTE t os Mas k );
/*
* C ommon Error Func t ions
* (C H R _ T E S T _H A N D LE / C H R _ P A I R _H A N D LE / C H R _ M GR OU P _
H A N D LE / C H R _M P A I R _H A N D LE )
*/
C H R _API_R C C H R _API_FN
C H R _c om m on_error_get _i nf o(
C H R _H AN D LE handle,
C H R _D E T A I L_LE V E L det ai l Lev el ,
C H R _STR I N G errorI nf o,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _c om m on_error_get _m s g_num (
C H R _H AN D LE handle,
C H R _MESSAGE_N U MBER * ms gN umber);
/*

- 764 -

IxChariot APIGuide
* C ommon R es ult s Ex t rac t ion Func t ions
* (C H R _ P A I R _H A N D LE / C H R _ M P A I R _ H A N D LE / C H R _T I M I N GR E C _
H AN D LE)
*/
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _by t es _rec v _ e1(
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _by t es _rec v _ e2(
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _by t es _s ent _ e1(
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _ c om m on_res ul t s _ get _dg_ dup_rec v _e1(
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _ c om m on_res ul t s _ get _dg_ dup_rec v _e2(
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _ c om m on_res ul t s _ get _dg_ dup_s ent _e1(
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _ c om m on_res ul t s _ get _dg_ dup_s ent _e2(
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _ c om m on_res ul t s _ get _ dg_ l os t _e1_ t o_e2(
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _ c om m on_res ul t s _ get _ dg_ out _ of _order (
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _ c om m on_res ul t s _ get _dg_ rec v _e1(
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _ c om m on_res ul t s _ get _dg_ rec v _e2(
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _ c om m on_res ul t s _ get _dg_ s ent _e1(
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN

- 765 -

IxChariot APIGuide
C H R _c om m on_res ul t s _get _es t _c l oc k _error (
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _ get _j i t t er_ buf f er_l os t (
C H R _H AN D LE handle,
C H R _C OU N T* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _m ax _c l oc k _error (
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _m eas _ t i m e(
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _rt d (
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _rt d_95pc t _c onf i denc e(
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _t rans _c ount (
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _e1_ s y n_t x (
C H R _H AN D LE handle,
C H R _C OU N T* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _e1_ s y n_rx (
C H R _H AN D LE handle,
C H R _C OU N T* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _e1_ s y n_f ai l ed(
C H R _H AN D LE handle,
C H R _C OU N T* res ult );
C H R _API_R C C H R _API_FN
C H R _ c om m on_res ul t s _ get _e1_ c onn_es t abl i s hed (
C H R _H AN D LE handle,
C H R _C OU N T* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _e1_ f i n_t x (
C H R _H AN D LE handle,
C H R _C OU N T* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _e1_ f i n_rx (
C H R _H AN D LE handle,
C H R _C OU N T* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _e1_ f i n_ac k _t x (

- 766 -

IxChariot APIGuide
C H R _H AN D LE handle,
C H R _C OU N T* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _e1_ f i n_ac k _rx (
C H R _H AN D LE handle,
C H R _C OU N T* res ult );
C H R _API_R C C H R _API_FN
C H R _ c om m on_res ul t s _ get _ e1_ ac k _ t o_f i n_ t x (
C H R _H AN D LE handle,
C H R _C OU N T* res ult );
C H R _API_R C C H R _API_FN
C H R _ c om m on_res ul t s _ get _ e1_ ac k _ t o_f i n_ rx (
C H R _H AN D LE handle,
C H R _C OU N T* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _e1_ rs t _t x (
C H R _H AN D LE handle,
C H R _C OU N T* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _e1_ rs t _rx (
C H R _H AN D LE handle,
C H R _C OU N T* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _e1_ t c p_ret rans m i s s i ons (
C H R _H AN D LE handle,
C H R _C OU N T* res ult );
C H R _API_R C C H R _API_FN
C H R _c om m on_res ul t s _get _e1_ t c p_t i m eout s (
C H R _H AN D LE handle,
C H R _C OU N T* res ult );
/*
* D at agram Opt ions Objec t Func t ions
* (C H R _ D GOP T S _H A N D LE )
*/
C H R _API_R C C H R _API_FN
C H R _dgopt s _get _rec v _ t i m eout (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T* rec v Timeout );
C H R _API_R C C H R _API_FN
C H R _dgopt s _get _ret rans _ c ount (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T* ret rans C ount );
C H R _API_R C C H R _API_FN
C H R _dgopt s _get _ret rans _ t i m eout (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T* ret rans Timeout );
C H R _API_R C C H R _API_FN
C H R _dgopt s _get _T T L (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T* t t l);
C H R _API_R C C H R _API_FN
C H R _dgopt s _get _w i ndow _ s i z e(
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,

- 767 -

IxChariot APIGuide
C H R _C OU N T* w indow Siz e);
C H R _API_R C C H R _API_FN
C H R _dgopt s _get _l ow _s ender_ j i t t er(
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _BOOLEAN * f lag);
C H R _API_R C C H R _API_FN
C H R _dgopt s _get _l i m i t _dat a_ rat e(
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _BOOLEAN * f lag);
C H R _API_R C C H R _API_FN
C H R _ dgopt s _get _dat a_ rat e_l i m i t (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T* dat aR at eLimit );
C H R _API_R C C H R _API_FN
C H R _dgopt s _get _m eas ured_ i nt erv al (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T* meas uredI nt erv al);
C H R _API_R C C H R _API_FN
C H R _dgopt s _get _R T P _us e_ex t ended_ headers (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _BOOLEAN * f lag);
C H R _API_R C C H R _API_FN
C H R _dgopt s _s et _rec v _ t i m eout (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T rec v Timeout );
C H R _API_R C C H R _API_FN
C H R _dgopt s _s et _ret rans _ c ount (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T ret rans C ount );
C H R _API_R C C H R _API_FN
C H R _dgopt s _s et _ret rans _ t i m eout (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T ret rans Timeout );
C H R _API_R C C H R _API_FN
C H R _dgopt s _s et _T T L (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T t t l);
C H R _API_R C C H R _API_FN
C H R _dgopt s _s et _w i ndow _ s i z e(
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T w indow Siz e);
C H R _API_R C C H R _API_FN
C H R _dgopt s _s et _l ow _s ender_ j i t t er(
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _BOOLEAN f lag);
C H R _API_R C C H R _API_FN
C H R _dgopt s _s et _l i m i t _dat a_ rat e(
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _BOOLEAN f lag);
C H R _API_R C C H R _API_FN
C H R _ dgopt s _s et _dat a_ rat e_l i m i t (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T dat aR at eLimit );

- 768 -

IxChariot APIGuide
C H R _API_R C C H R _API_FN
C H R _dgopt s _s et _m eas ured_ i nt erv al (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _C OU N T meas uredI nt erv al);
C H R _API_R C C H R _API_FN
C H R _dgopt s _s et _R T P _us e_ex t ended_ headers (
C H R _D GOP T S _H A N D LE dat agram Opt i ons H andl e,
C H R _BOOLEAN f lag);
/*
* Trac erout e H op R ec ord Objec t Func t ions
* (C H R _ H OP R E C _H A N D LE )
*/
C H R _API_R C C H R _API_FN
C H R _hoprec _get _hop_addres s (
C H R _H OP R E C _H A N D LE hoprec H andl e,
C H R _STR I N G hop_addres s ,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _hoprec _get _hop_l at enc y (
C H R _H OP R E C _H A N D LE hoprec H andl e,
C H R _C OU N T* hop_lat enc y );
C H R _API_R C C H R _API_FN
C H R _hoprec _get _hop_nam e(
C H R _H OP R E C _H A N D LE hoprec H andl e,
C H R _STR I N G hop_name,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _hoprec _get _hop_num ber(
C H R _H OP R E C _H A N D LE hoprec H andl e,
C H R _C OU N T* hop_number);
/*
* Mult ic as t Group Objec t Func t ions
* (C H R _ M GR OU P _H A N D LE )
*/
C H R _API_R C C H R _API_FN
C H R _m group_add_m pai r (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _MPAI R _H AN D LE mpairH andle);
C H R _API_R C C H R _API_FN
C H R _m group_c opy (
C H R _M GR OU P _H A N D LE t oM groupH andl e,
C H R _M GR OU P _H A N D LE f rom M groupH andl e);
C H R _API_R C C H R _API_FN
C H R _m group_del et e(
C H R _M GR OU P _H A N D LE m groupH andl e);
C H R _API_R C C H R _API_FN
C H R _m group_get _appl _ s c ri pt _nam e(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G s c ript N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);

- 769 -

IxChariot APIGuide
C H R _API_R C C H R _API_FN
C H R _m group_get _c om m ent (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G c omment ,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _m group_get _c ons ol e_ e1_ addr(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G c ons oleE1N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _m group_get _c ons ol e_ e1_ prot oc ol (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _PR OTOC OL* prot oc ol);
C H R _API_R C C H R _API_FN
C H R _m group_get _e1_ addr(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G e1N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _m group_get _e1_ c onf i g_v al ue (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _C FG_PAR M paramet er,
C H R _STR I N G v alue,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _m group_get _m pai r (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _C OU N T index ,
C H R _MPAI R _H AN D LE* mpairH andle);
C H R _API_R C C H R _API_FN
C H R _m group_get _m pai r_c ount (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _C OU N T* mpairC ount );
C H R _API_R C C H R _API_FN
C H R _m group_get _m ul t i c as t _ addr(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G addr,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _m group_get _m ul t i c as t _ port (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _POR T* port );
C H R _API_R C C H R _API_FN
C H R _m group_get _nam e(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G name,
C H R _LEN GTH max Lengt h,

- 770 -

IxChariot APIGuide
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _m group_get _prot oc ol (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _PR OTOC OL* prot oc ol);
C H R _API_R C C H R _API_FN
C H R _m group_get _qos _nam e(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G qos N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _m group_get _s c ri pt _ f i l enam e(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G f ileN ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _m group_get _us e_c ons ol e_ e1_ v al ues (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _BOOLEAN * us eValues );
C H R _API_R C C H R _API_FN
C H R _m group_get _s c ri pt _ v ari abl e(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G name,
C H R _LEN GTH nameLengt h,
C H R _STR I N G v alue,
C H R _LEN GTH v alueMax Lengt h,
C H R _LEN GTH * v alueLengt h);
C H R _API_R C C H R _API_FN
C H R _m group_get _s c ri pt _ em bedded_pay l oad (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G v ariableN ame,
C H R _LEN GTH v ariableN ameLengt h,
C H R _STR I N G pay load,
C H R _LEN GTH pay loadMax Lengt h,
C H R _LEN GTH * pay loadLengt h);
C H R _API_R C C H R _API_FN
C H R _m group_get _pay l oad_ f i l e(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G v ariableN ame,
C H R _LEN GTH v ariableN ameLengt h,
C H R _STR I N G f ilename,
C H R _LEN GTH f ilenameMax Lengt h,
C H R _LEN GTH * f ilenameLengt h,
C H R _BOOLEAN * embedded);
C H R _API_R C C H R _API_FN
C H R _m group_i s _ udp_R F C 768_s t ream i ng (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _BOOLEAN * us ed);
C H R _API_R C C H R _API_FN
C H R _m group_i s _ di s abl ed(
C H R _M GR OU P _H A N D LE m groupH andl e,

- 771 -

IxChariot APIGuide
C H R _BOOLEAN * dis abled);
C H R _API_R C C H R _API_FN
C H R _m group_new (
C H R _M GR OU P _H A N D LE * m groupH andl e);
C H R _API_R C C H R _API_FN
C H R _ m g r o u p _r e m o v e _ m p a i r(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _MPAI R _H AN D LE mpairH andle);
C H R _API_R C C H R _API_FN
C H R _m group_s et _c om m ent (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G c omment ,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _m group_s et _c ons ol e_ e1_ addr(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G c ons oleE1N ame,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _m group_s et _c ons ol e_ e1_ prot oc ol (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _PR OTOC OL prot oc ol);
C H R _API_R C C H R _API_FN
C H R _m group_s et _e1_ addr(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G e1N ame,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _m group_s et _l oc k (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _BOOLEAN loc k );
C H R _API_R C C H R _API_FN
C H R _m group_s et _m ul t i c as t _ addr(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G addr,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _m group_s et _m ul t i c as t _ port (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _POR T port );
C H R _API_R C C H R _API_FN
C H R _m group_s et _nam e(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G name,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _m group_s et _prot oc ol (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _PR OTOC OL prot oc ol);
C H R _API_R C C H R _API_FN
C H R _m group_s et _qos _nam e(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G qos N ame,

- 772 -

IxChariot APIGuide
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _m group_s et _s c ri pt _ v ari abl e(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G name,
C H R _LEN GTH nameLengt h,
C H R _STR I N G v alue,
C H R _LEN GTH v alueLengt h);
C H R _API_R C C H R _API_FN
C H R _m group_s et _s c ri pt _ em bedded_pay l oad (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G v ariableN ame,
C H R _LEN GTH v ariableN ameLengt h,
C H R _STR I N G pay load,
C H R _LEN GTH pay loadLengt h);
C H R _API_R C C H R _API_FN
C H R _m group_s et _pay l oad_ f i l e(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G v ariableN ame,
C H R _LEN GTH v ariableN ameLengt h,
C H R _STR I N G f ilename,
C H R _LEN GTH f ilenameLengt h,
C H R _BOOLEAN embedded);
C H R _API_R C C H R _API_FN
C H R _m group_s et _us e_c ons ol e_ e1_ v al ues (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _BOOLEAN us eValues );
C H R _API_R C C H R _API_FN
C H R _m group_us e_s c ri pt _ f i l enam e(
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G f ileN ame,
C H R _LEN GTH f ileN ameLengt h);
C H R _API_R C C H R _API_FN
C H R _m group_di s abl e (
C H R _M GR OU P _H A N D LE m groupH andl e,
C H R _BOOLEAN dis able);
/*
* Mult ic as t Pair Objec t Func t ions
* (C H R _MPAI R _H AN D LE)
*/
C H R _API_R C C H R _API_FN
C H R _mpair_delet e(
C H R _MPAI R _H AN D LE mpairH andle);
C H R _API_R C C H R _API_FN
C H R _ m pai r_ get _ e2_addr(
C H R _MPAI R _H AN D LE mpairH andle,
C H R _STR I N G e2N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ m p a i r_ g e t _ e 2 _c o n f i g _ v a l u e(
C H R _MPAI R _H AN D LE pairH andle,
C H R _C FG_PAR M paramet er,

- 773 -

IxChariot APIGuide
C H R _STR I N G v alue,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ m pai r_ get _ s et up_ e1_e2_ addr(
C H R _MPAI R _H AN D LE mpairH andle,
C H R _STR I N G e2N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _m pai r_get _t i m i ng_rec ord(
C H R _MPAI R _H AN D LE mpairH andle,
C H R _C OU N T index ,
C H R _TI MI N GR EC _H AN D LE* t imingR ec ordH andle);
C H R _API_R C C H R _API_FN
C H R _m pai r_get _t i m i ng_rec ord_ c ount (
C H R _MPAI R _H AN D LE mpairH andle,
C H R _C OU N T* c ount );
C H R _API_R C C H R _API_FN
C H R _ m pai r_ get _ us e_ s et up_ e1_e2_ v al ues (
C H R _MPAI R _H AN D LE mpairH andle,
C H R _BOOLEAN * us e);
C H R _API_R C C H R _API_FN
C H R _mpair_get _runSt at us(
C H R _MPAI R _H AN D LE mpairH andle,
C H R _P A I R _R U N S T A T U S _ T Y P E * runS t at us );
C H R _API_R C C H R _API_FN
C H R _mpair_new(
C H R _MPAI R _H AN D LE* mpairH andle);
C H R _API_R C C H R _API_FN
C H R _ m pai r_ s et _ e2_addr(
C H R _MPAI R _H AN D LE mpairH andle,
C H R _STR I N G e2N ame,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _mpair_s et _loc k (
C H R _MPAI R _H AN D LE mpairH andle,
C H R _BOOLEAN loc k );
C H R _API_R C C H R _API_FN
C H R _ m pai r_ s et _ s et up_ e1_e2_ addr(
C H R _MPAI R _H AN D LE mpairH andle,
C H R _STR I N G e2N ame,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _ m pai r_ s et _ us e_ s et up_ e1_e2_ v al ues (
C H R _MPAI R _H AN D LE mpairH andle,
C H R _BOOLEAN us e);
/*
* Pair Objec t Func t ions
* (C H R _ P A I R _H A N D LE )
*/
C H R _API_R C C H R _API_FN
C H R _ pai r_c opy (

- 774 -

IxChariot APIGuide
C H R _P A I R _H A N D LE t oP ai rH andl e,
C H R _P A I R _H A N D LE f rom P ai rH andl e);
C H R _API_R C C H R _API_FN
C H R _ pai r_del et e(
C H R _P A I R _H A N D LE pai rH andl e);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _appl _ s c ri pt _nam e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G s c ript N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _c om m ent (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G c omment ,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _c ons ol e_ e1_ addr(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G c ons oleE1N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _c ons ol e_ e1_ prot oc ol (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _PR OTOC OL* prot oc ol);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _e1_ addr(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G e1N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _e2_ addr(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G e2N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _e1_ c onf i g_v al ue (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _C FG_PAR M paramet er,
C H R _STR I N G v alue,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _e2_ c onf i g_v al ue (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _C FG_PAR M paramet er,
C H R _STR I N G v alue,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);

- 775 -

IxChariot APIGuide
C H R _API_R C C H R _API_FN
C H R _ pai r_get _prot oc ol (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _PR OTOC OL* prot oc ol);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _qos _ nam e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G qos N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _e1_ qos _ nam e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G qos N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _e2_ qos _ nam e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G qos N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _runS t at us (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _P A I R _R U N S T A T U S _ T Y P E * runS t at us );
C H R _API_R C C H R _API_FN
C H R _ pai r_get _s c ri pt _ f i l enam e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G f ileN ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _ s et up_ e1_ e2_addr(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G e1E2N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _t i m i ng_ rec ord(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _C OU N T index ,
C H R _TI MI N GR EC _H AN D LE* t imingR ec ordH andle);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _t i m i ng_ rec ord_c ount (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _C OU N T* c ount );
C H R _API_R C C H R _API_FN
C H R _ pai r_get _us e_ c ons ol e_ e1_ v al ues (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _BOOLEAN * us eValues );
C H R _API_R C C H R _API_FN
C H R _ pai r_get _ us e_ s et up_ e1_ e2_v al ues (

- 776 -

IxChariot APIGuide
C H R _P A I R _H A N D LE pai rH andl e,
C H R _BOOLEAN * us eValues );
C H R _API_R C C H R _API_FN
C H R _ pai r_i s _ udp_ R F C 768_s t ream i ng (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _BOOLEAN * us ed);
C H R _API_R C C H R _API_FN
C H R _ pai r_i s _ di s abl ed(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _BOOLEAN * dis abled);
C H R _API_R C C H R _API_FN
C H R _ pai r_new (
C H R _P A I R _H A N D LE * pai rH andl e);
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _c om m ent (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G c omment ,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _c ons ol e_ e1_ addr(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G c ons oleE1N ame,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _c ons ol e_ e1_ prot oc ol (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _PR OTOC OL prot oc ol);
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _e1_ addr(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G e1N ame,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _e2_ addr(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G e2N ame,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _l oc k (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _BOOLEAN loc k );
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _prot oc ol (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _PR OTOC OL prot oc ol);
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _qos _ nam e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G qos N ame,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _e1_ qos _ nam e(
C H R _P A I R _H A N D LE pai rH andl e,

- 777 -

IxChariot APIGuide
C H R _STR I N G qos N ame,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _e2_ qos _ nam e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G qos N ame,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _s c ri pt _ v ari abl e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G name,
C H R _LEN GTH nameLengt h,
C H R _STR I N G v alue,
C H R _LEN GTH v alueLengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _s c ri pt _ v ari abl e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G name,
C H R _LEN GTH nameLengt h,
C H R _STR I N G v alue,
C H R _LEN GTH v alueMax Lengt h,
C H R _LEN GTH * v alueLengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _s c ri pt _ em bedded_pay l oad (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G v ariableN ame,
C H R _LEN GTH v ariableN ameLengt h,
C H R _STR I N G pay load,
C H R _LEN GTH pay loadLengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _s c ri pt _ em bedded_pay l oad (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G v ariableN ame,
C H R _LEN GTH v ariableN ameLengt h,
C H R _STR I N G pay load,
C H R _LEN GTH pay loadMax Lengt h,
C H R _LEN GTH * pay loadLengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _pay l oad_ f i l e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G v ariableN ame,
C H R _LEN GTH v ariableN ameLengt h,
C H R _STR I N G f ilename,
C H R _LEN GTH f ilenameLengt h,
C H R _BOOLEAN embedded);
C H R _API_R C C H R _API_FN
C H R _ pai r_get _pay l oad_ f i l e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G v ariableN ame,
C H R _LEN GTH v ariableN ameLengt h,
C H R _STR I N G f ilename,
C H R _LEN GTH f ilenameMax Lengt h,
C H R _LEN GTH * f ilenameLengt h,

- 778 -

IxChariot APIGuide
C H R _BOOLEAN * embedded);
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _ s et up_ e1_ e2_addr(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G e1E2N ame,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _us e_ c ons ol e_ e1_ v al ues (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _BOOLEAN us eValues );
C H R _API_R C C H R _API_FN
C H R _ pai r_s et _ us e_ s et up_ e1_ e2_v al ues (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _BOOLEAN us eValues );
C H R _API_R C C H R _API_FN
C H R _ pai r_us e_ s c ri pt _ f i l enam e(
C H R _P A I R _H A N D LE pai rH andl e,
C H R _STR I N G f ileN ame,
C H R _LEN GTH f ileN ameLengt h);
C H R _API_R C C H R _API_FN
C H R _ pai r_di s abl e (
C H R _P A I R _H A N D LE pai rH andl e,
C H R _BOOLEAN
dis able);
C H R _API_R C C H R _API_FN
C H R _ pai r_s w ap_ endpoi nt s (
C H R _P A I R _H A N D LE pai rH andl e);
/*
* Pair/ Mult ic as t Group Pair R es ult s Ex t rac t ion Func t ions
* (C H R _ P A I R _H A N D LE / C H R _ M P A I R _ H A N D LE )
*/
C H R _API_R C C H R _API_FN
C H R _ pai r_res ul t s _ get _av erage (
C H R _H AN D LE handle,
C H R _R ESU LTS res ult Ty pe,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _ pai r_res ul t s _ get _C P U _ ut i l _ e1(
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _ pai r_res ul t s _ get _C P U _ ut i l _ e2(
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _ pai r_res ul t s _ get _m ax i m um (
C H R _H AN D LE handle,
C H R _R ESU LTS res ult Ty pe,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _ pai r_res ul t s _ get _m i ni m um (
C H R _H AN D LE handle,
C H R _R ESU LTS res ult Ty pe,
C H R _FLOAT* res ult );

- 779 -

IxChariot APIGuide
C H R _API_R C C H R _API_FN
C H R _ pai r_res ul t s _ get _rel _prec i s i on (
C H R _H AN D LE handle,
C H R _FLOAT* res ult );
C H R _API_R C C H R _API_FN
C H R _ pai r_res ul t s _ get _95pc t _ c onf i denc e(
C H R _H AN D LE handle,
C H R _R ESU LTS res ult Ty pe,
C H R _FLOAT* res ult );
/*
* R un Opt ions Objec t Func t ions
* (C H R _R U N OPTS_H AN D LE)
*/
C H R _API_R C C H R _API_FN
C H R _runopt s _get _c onnec t _t imeout(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T* c onnec t Timeout );
C H R _API_R C C H R _API_FN
C H R _runopt s _get _C PU _ut il(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * c puU t il);
C H R _API_R C C H R _API_FN
C H R _runopt s _get _c ollec t _TC P_s t at s(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * c ollec t TC PSt at s );
C H R _API_R C C H R _API_FN
C H R _ runopt s _ get _al l ow _ pai r_rei ni t (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * allow PairR einit );
C H R _API_R C C H R _API_FN
C H R _ runopt s _ get _pai r_rei ni t _ m ax (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T* pairR einit Max );
C H R _API_R C C H R _API_FN
C H R _ runopt s _ get _pai r_rei ni t _ ret ry _ i nt erv al (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T* pairR einit R et ry I nt erv al);
C H R _API_R C C H R _API_FN
C H R _ ru n o p t s _ g e t _ a l l o w _ p a i r_re i n i t _ ru n(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * allow PairR einit );
C H R _API_R C C H R _API_FN
C H R _ ru n o p t s _ g e t _ p a i r_re i n i t _ m a x _ ru n(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T* pairR einit Max );
C H R _API_R C C H R _API_FN
C H R _ runopt s _ get _pai r_rei ni t _ ret ry _ i nt erv al _run (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T* pairR einit R et ry I nt erv al);
C H R _API_R C C H R _API_FN
C H R _ runopt s _ get _ H W _t i m es t am ps (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * hw Times t amps );

- 780 -

IxChariot APIGuide
C H R _API_R C C H R _API_FN
C H R _runopt s _get _f ew er_s et up_c onnec t ions(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * f ew erC onnec t ions );
C H R _API_R C C H R _API_FN
C H R _runopt s _get _apply _dod_only (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * iep_dod_only );
C H R _API_R C C H R _API_FN
C H R _runopt s _get _dec onf igure_port s(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * f lag);
C H R _API_R C C H R _API_FN
C H R _runopt s _ get _num _res ul t _ranges (
C H R _R U N OPTS_H AN D LE handle,
C H R _R ESU LTS res ult Ty pe,
C H R _C OU N T* number);
C H R _API_R C C H R _API_FN
C H R _ runopt s _ get _ pol l _endpoi nt s (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * pollEndpoint s );
C H R _API_R C C H R _API_FN
C H R _ runopt s _ get _ pol l _i nt erv al (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T* pollI nt erv al);
C H R _API_R C C H R _API_FN
C H R _runopt s _get _random _new _s eed(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * randomN ew Seed);
C H R _API_R C C H R _API_FN
C H R _runopt s _get _report ing_t y pe(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _T E S T _R E P OR T I N G* t es t R eport i ng);
C H R _API_R C C H R _API_FN
C H R _ runopt s _ get _ pol l _ret ri ev i ng_ t y pe(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _T E S T _R E T R I E V I N G* t es t R et ri ev i ng);
C H R _API_R C C H R _API_FN
C H R _runopt s _get _report ing_f irew all(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _T E S T _R E P OR T I N G_ F I R E W A LL* t es t R eport i ngF i rew al l );
C H R _API_R C C H R _API_FN
C H R _runopt s _ get _res ul t _range (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _R ESU LTS res ult Ty pe,
C H R _C OU N T index ,
C H R _C OU N T *minValue,
C H R _C OU N T *max Value);
C H R _API_R C C H R _API_FN
C H R _ runopt s _ get _s t op_af t er_ num _ pai rs _ f ai l (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T* numPairs );
C H R _API_R C C H R _API_FN

- 781 -

IxChariot APIGuide
C H R _ runopt s _ get _ s t op_on_ i ni t _f ai l ure (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * s t opOnI nit Failure);
C H R _API_R C C H R _API_FN
C H R _ runopt s _ get _t es t _durat i on(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T* t es t D urat ion);
C H R _API_R C C H R _API_FN
C H R _ runopt s _ get _t es t _end (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _T E S T _E N D * t es t E nd);
C H R _API_R C C H R _API_FN
C H R _runopt s _get _v al i dat e_on_ rec v (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * v alidat eOnR ec v );
C H R _API_R C C H R _API_FN
C H R _runopt s _get _c l k s y nc _hardw are_t s (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * c lk s y nc _hardw are_t s );
C H R _API_R C C H R _API_FN
C H R _runopt s _get _c lk s y nc _ex t ernal(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN * c lk s y nc _ex t ernal);
C H R _API_R C C H R _API_FN
C H R _runopt s _get _ov erl apped_s ends _c ount (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T* v alue);
C H R _API_R C C H R _API_FN
C H R _runopt s _s et _c onnec t _t imeout(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T c onnec t Timeout );
C H R _API_R C C H R _API_FN
C H R _runopt s _s et _C PU _ut il(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN c puU t il);
C H R _API_R C C H R _API_FN
C H R _runopt s _s et _c ollec t _TC P_s t at s(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN c ollec t TC PSt at s );
C H R _API_R C C H R _API_FN
C H R _ runopt s _ s et _al l ow _ pai r_rei ni t (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN allow PairR einit );
C H R _API_R C C H R _API_FN
C H R _ runopt s _ s et _pai r_rei ni t _ m ax (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T pairR einit Max );
C H R _API_R C C H R _API_FN
C H R _ runopt s _ s et _pai r_rei ni t _ ret ry _ i nt erv al (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T pairR einit R et ry I nt erv al);
C H R _API_R C C H R _API_FN
C H R _ ru n o p t s _ s e t _ a l l o w _ p a i r_re i n i t _ ru n(

- 782 -

IxChariot APIGuide
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN allow PairR einit );
C H R _API_R C C H R _API_FN
C H R _ ru n o p t s _ s e t _ p a i r_re i n i t _ m a x _ ru n(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T pairR einit Max );
C H R _API_R C C H R _API_FN
C H R _ runopt s _ s et _pai r_rei ni t _ ret ry _ i nt erv al _run (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T pairR einit R et ry I nt erv al);
C H R _API_R C C H R _API_FN
C H R _ runopt s _ s et _ H W _t i m es t am ps (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN hw Times t amps );
C H R _API_R C C H R _API_FN
C H R _runopt s _s et _f ew er_s et up_c onnec t ions(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN f ew erC onnec t ions );
C H R _API_R C C H R _API_FN
C H R _runopt s _s et _apply _dod_only (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _ B OOLE A N ep_dod_ onl y );
C H R _API_R C C H R _API_FN
C H R _runopt s _s et _dec onf igure_port s(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN f lag);
C H R _API_R C C H R _API_FN
C H R _runopt s _ s et _num _res ul t _ranges (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _R ESU LTS res ult Ty pe,
C H R _C OU N T number);
C H R _API_R C C H R _API_FN
C H R _ runopt s _ s et _ pol l _endpoi nt s (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN pollEndpoint s );
C H R _API_R C C H R _API_FN
C H R _ runopt s _ s et _ pol l _i nt erv al (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T pollI nt erv al);
C H R _API_R C C H R _API_FN
C H R _runopt s _s et _random _new _s eed(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN randomN ew Seed);
C H R _API_R C C H R _API_FN
C H R _runopt s _s et _report ing_t y pe(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _T E S T _R E P OR T I N G t es t R eport i ng);
C H R _API_R C C H R _API_FN
C H R _ runopt s _ s et _ pol l _ret ri ev i ng_ t y pe(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _T E S T _R E T R I E V I N G t es t R et ri ev i ng);
C H R _API_R C C H R _API_FN
C H R _runopt s _s et _report ing_f irew all(

- 783 -

IxChariot APIGuide
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _T E S T _R E P OR T I N G_ F I R E W A LL t es t R eport i ngF i rew al l );
C H R _API_R C C H R _API_FN
C H R _runopt s _ s et _res ul t _range (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _R ESU LTS res ult Ty pe,
C H R _C OU N T index ,
C H R _C OU N T minValue,
C H R _C OU N T max Value);
C H R _API_R C C H R _API_FN
C H R _ runopt s _ s et _s t op_af t er_ num _ pai rs _ f ai l (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T numPairs );
C H R _API_R C C H R _API_FN
C H R _ runopt s _ s et _ s t op_on_ i ni t _f ai l ure (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN s t opOnI nit Failure);
C H R _API_R C C H R _API_FN
C H R _ runopt s _ s et _t es t _durat i on(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T t es t D urat ion);
C H R _API_R C C H R _API_FN
C H R _ runopt s _ s et _t es t _end (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _T E S T _E N D t es t E nd);
C H R _API_R C C H R _API_FN
C H R _runopt s _s et _v al i dat e_on_ rec v (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN v alidat eOnR ec v );
C H R _API_R C C H R _API_FN
C H R _runopt s _s et _c l k s y nc _hardw are_t s (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _B OOLE A N c l k s y nc _hardw are_t s );
C H R _API_R C C H R _API_FN
C H R _runopt s _s et _c lk s y nc _ex t ernal(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _BOOLEAN c lk s y nc _ex t ernal);
C H R _API_R C C H R _API_FN
C H R _runopt s _get _m anagem ent _qos _c ons ol e_nam e(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _STR I N G qos N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _runopt s _get _m anagem ent _qos _endpoi nt _ nam e(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _STR I N G qos N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _runopt s _s et _m anagem ent _qos _c ons ol e_nam e(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _STR I N G qos N ame,

- 784 -

IxChariot APIGuide
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _runopt s _s et _m anagem ent _qos _endpoi nt _ nam e(
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _STR I N G qos N ame,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _runopt s _s et _ov erl apped_s ends _c ount (
C H R _R U N OPTS_H AN D LE runOpt ions H andle,
C H R _C OU N T v alue);
/*
* Tes t Objec t Func t ions
* (C H R _ T E S T _H A N D LE )
*/
C H R _API_R C C H R _API_FN
C H R _ t es t _get _groupi ng(
C H R _TEST_H AN D LE
t es t H andle,
C H R _GR OU PI N G_ TYPE *groupingTy pe,
C H R _SOR T_OR D ER
*groupingOrder);
C H R _API_R C C H R _API_FN
C H R _ t es t _s et _groupi ng_ t y pe(
C H R _TEST_H AN D LE
t es t H andle,
C H R _GR OU PI N G_ TYPE groupingTy pe);
C H R _API_R C C H R _API_FN
C H R _ t e s t _s e t _ g r o u p i n g _ o r d e r(
C H R _TEST_H AN D LE
t es t H andle,
C H R _SOR T_OR D ER
groupingOrder);
C H R _API_R C C H R _API_FN
C H R _ t es t _abandon (
C H R _T E S T _H A N D LE t es t H andl e);
C H R _API_R C C H R _API_FN
C H R _ t es t _add_ m group(
C H R _T E S T _H A N D LE t es t H andl e,
C H R _M GR OU P _H A N D LE m groupH andl e);
C H R _API_R C C H R _API_FN
C H R _ t es t _add_ pai r(
C H R _T E S T _H A N D LE t es t H andl e,
C H R _P A I R _H A N D LE pai rH andl e);
C H R _API_R C C H R _API_FN
C H R _ t es t _c l ear_ res ul t s (
C H R _T E S T _H A N D LE t es t H andl e);
C H R _API_R C C H R _API_FN
C H R _ t es t _del et e(
C H R _T E S T _H A N D LE t es t H andl e);
C H R _API_R C C H R _API_FN
C H R _ t es t _f orc e_ del et e(
C H R _T E S T _H A N D LE t es t H andl e);
C H R _API_R C C H R _API_FN
C H R _ t es t _get _dgopt s (
C H R _T E S T _H A N D LE t es t H andl e,
C H R _D GOP T S _H A N D LE * dgopt s H andl e);
C H R _API_R C C H R _API_FN
C H R _ t es t _get _f i l enam e(

- 785 -

IxChariot APIGuide
C H R _T E S T _H A N D LE t es t H andl e,
C H R _STR I N G s av eFileN ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ t es t _get _how _ ended (
C H R _T E S T _H A N D LE t es t H andl e,
C H R _T E S T _H OW _E N D E D * how E nded);
C H R _API_R C C H R _API_FN
C H R _ t es t _get _l oc al _ s t art _ t i m e(
C H R _T E S T _H A N D LE t es t H andl e,
s t ruc t t m* loc als t art Time);
C H R _API_R C C H R _API_FN
C H R _ t es t _get _l oc al _ s t op_ t i m e(
C H R _T E S T _H A N D LE t es t H andl e,
s t ruc t t m* loc als t opTime);
C H R _API_R C C H R _API_FN
C H R _ t es t _get _m group(
C H R _T E S T _H A N D LE t es t H andl e,
C H R _C OU N T index ,
C H R _M GR OU P _H A N D LE * m groupH andl e);
C H R _API_R C C H R _API_FN
C H R _ t es t _get _m group_ c ount (
C H R _T E S T _H A N D LE t es t H andl e,
C H R _C OU N T* mgroupC ount );
C H R _API_R C C H R _API_FN
C H R _ t es t _get _pai r(
C H R _T E S T _H A N D LE t es t H andl e,
C H R _C OU N T index ,
C H R _P A I R _H A N D LE * pai rH andl e);
C H R _API_R C C H R _API_FN
C H R _ t es t _get _pai r_ c ount (
C H R _T E S T _H A N D LE t es t H andl e,
C H R _C OU N T* pairC ount );
C H R _API_R C C H R _API_FN
C H R _ t es t _get _runopt s (
C H R _T E S T _H A N D LE t es t H andl e,
C H R _R U N OPTS_H AN D LE* runopt s H andle);
C H R _API_R C C H R _API_FN
C H R _ t es t _get _s t art _ t i m e(
C H R _T E S T _H A N D LE t es t H andl e,
t i m e_t * s t art T i m e);
C H R _API_R C C H R _API_FN
C H R _ t es t _get _s t op_ t i m e(
C H R _T E S T _H A N D LE t es t H andl e,
t i m e_t * s t opT i m e);
C H R _API_R C C H R _API_FN
C H R _ t es t _get _t hroughput _ uni t s (
C H R _T E S T _H A N D LE t es t H andl e,
C H R _T H R OU GH P U T _U N I T S * t hroughput U ni t s );
C H R _API_R C C H R _API_FN
C H R _ t es t _l oad(
C H R _T E S T _H A N D LE t es t H andl e,

- 786 -

IxChariot APIGuide
C H R _STR I N G t es t FileN ame,
C H R _LEN GTH t es t FileN ameLengt h);
C H R _API_R C C H R _API_FN
C H R _ t es t _new (
C H R _T E S T _H A N D LE * t es t H andl e);
C H R _API_R C C H R _API_FN
C H R _ t es t _query _ s t op(
C H R _T E S T _H A N D LE t es t H andl e,
C H R _C OU N T t imeout );
C H R _API_R C C H R _API_FN
C H R _ t es t _s av e(
C H R _T E S T _H A N D LE t es t H andl e);
C H R _API_R C C H R _API_FN
C H R _ t es t _s et _f i l enam e(
C H R _T E S T _H A N D LE t es t H andl e,
C H R _STR I N G s av eFileN ame,
C H R _LEN GTH s av eFileN ameLengt h);
C H R _API_R C C H R _API_FN
C H R _ t es t _s et _t hroughput _ uni t s (
C H R _T E S T _H A N D LE t es t H andl e,
C H R _T H R OU GH P U T _U N I T S t hroughput U ni t s );
C H R _API_R C C H R _API_FN
C H R _ t es t _s t art (
C H R _T E S T _H A N D LE t es t H andl e);
C H R _API_R C C H R _API_FN
C H R _ t es t _s t op(
C H R _T E S T _H A N D LE t es t H andl e);
C H R _API_R C C H R _API_FN
C H R _ t es t _l oad_ app_ groups (
C H R _T E S T _H A N D LE
t es t H andle,
C H R _STR IN G
f ilename,
C H R _LEN GTH
f ilenameLengt h);
C H R _API_R C C H R _API_FN
C H R _ t es t _add_ app_ group (
C H R _T E S T _H A N D LE t es t H andl e,
C H R _APP_GR OU P_H AN D LE appGroupH andle);
C H R _API_R C C H R _API_FN
C H R _ t e s t _re m o v e _ a p p _ g ro u p(
C H R _T E S T _H A N D LE t es t H andl e,
C H R _APP_GR OU P_H AN D LE appGroupH andle);
C H R _API_R C C H R _API_FN
C H R _ t es t _get _app_ group_ by _ i ndex (
C H R _T E S T _H A N D LE t es t H andl e,
C H R _C OU N T index ,
C H R _APP_GR OU P_H AN D LE* appGroupH andle);
C H R _API_R C C H R _API_FN
C H R _ t es t _get _app_ group_ by _ nam e(
C H R _T E S T _H A N D LE t es t H andl e,
C H R _STR I N G name,
C H R _LEN GTH nameLengt h,
C H R _APP_GR OU P_H AN D LE* appGroupH andle);
C H R _API_R C C H R _API_FN
C H R _ t es t _get _app_ group_ c ount (

- 787 -

IxChariot APIGuide
C H R _T E S T _H A N D LE t es t H andl e,
C H R _C OU N T* appGroupC ount );
/*
* Thes e are I x ia hardw are s pec f ic f unc t ions t o
* manipulat e t he s t ac k manager c onf igurat ion in t he
* f ile.
*/
C H R _API_R C C H R _API_FN
C H R _ t es t _s et _t es t _ s erv er_s es s i on (
C H R _T E S T _H A N D LE t es t H andl e,
C H R _STR I N G t es t Serv erAddres s ,
C H R _C OU N T t es t Serv erSiz e,
C H R _C OU N T t es t Serv erPort ,
C H R _W LON G s es s ionObjec t I d );
C H R _API_R C C H R _API_FN
C H R _ t es t _get _t es t _ s erv er_s es s i on (
C H R _T E S T _H A N D LE t es t H andl e,
C H R _STR I N G t es t Serv erAddres s ,
C H R _C OU N T t es t Serv erAddres s Max Siz e,
C H R _C OU N T * t es t Serv erAddres s Siz e,
C H R _C OU N T * t es t Serv erPort ,
C H R _W LON G * s es s ionObjec t I d );
C H R _API_R C C H R _API_FN
C H R _ t es t _s et _ i x i a_ net w ork _ c onf i gurat i on(
C H R _T E S T _H A N D LE t es t H andl e,
C H R _BYTE * dat aPt r,
C H R _LEN GTH dat aSiz e );
C H R _API_R C C H R _API_FN
C H R _ t es t _get _ i x i a_ net w ork _ c onf i gurat i on(
C H R _T E S T _H A N D LE t es t H andl e,
C H R _BYTE * dat aPt r,
C H R _LEN GTH max imumSiz e,
C H R _LEN GTH * dat aSiz e );
C H R _API_R C C H R _API_FN
C H R _ t es t _l oad_ i x i a_net w ork _ c onf i gurat i on (
C H R _T E S T _H A N D LE t es t H andl e,
C H R _STR I N G f ileN ame,
C H R _LEN GTH f ileN ameLengt h );
C H R _API_R C C H R _API_FN
C H R _ t es t _s av e_ i x i a_net w ork _ c onf i gurat i on (
C H R _T E S T _H A N D LE t es t H andl e,
C H R _STR I N G f ileN ame,
C H R _LEN GTH f ileMax imumLengt h );
C H R _API_R C C H R _API_FN
C H R _ t es t _c l ear_ i x i a_ net w ork _ c onf i gurat i on(
C H R _T E S T _H A N D LE t es t H andl e );
/*
* Timing R ec ord Obec t Func t ions
* (C H R _TI MI N GR EC _H AN D LE)
*/
C H R _API_R C C H R _API_FN
C H R _ t i m i n g re c _ g e t _ e l a p s e d(
C H R _TI MI N GR EC _H AN D LE t imingrec H andle,

- 788 -

IxChariot APIGuide
C H R _FLOAT* elaps ed);
C H R _API_R C C H R _API_FN
C H R _ t i m i ngrec _ get _ end_ t o_end_ del ay (
C H R _TI MI N GR EC _H AN D LE t imingrec H andle,
C H R _FLOAT* delay );
C H R _API_R C C H R _API_FN
C H R _t imingrec _get _inac t iv e(
C H R _TI MI N GR EC _H AN D LE t imingrec H andle,
C H R _FLOAT* inac t iv e);
C H R _API_R C C H R _API_FN
C H R _t imingrec _get _jit t er(
C H R _TI MI N GR EC _H AN D LE t imingrec H andle,
C H R _FLOAT* jit t er);
C H R _API_R C C H R _API_FN
C H R _t imingrec _get _max _c ons ec ut iv e_los t (
C H R _TI MI N GR EC _H AN D LE t imingrec H andle,
C H R _C OU N T* los t );
C H R _API_R C C H R _API_FN
C H R _ t i m i n g re c _ g e t _ m a x _ d e l a y _ v a ri a t i o n(
C H R _TI MI N GR EC _H AN D LE t imingrec H andle,
C H R _C OU N T* v ariat ion);
C H R _API_R C C H R _API_FN
C H R _t imingrec _get _MOS_es t imat e(
C H R _TI MI N GR EC _H AN D LE t imingrec H andle,
C H R _FLOAT* es t imat e);
C H R _API_R C C H R _API_FN
C H R _t imingrec _get _one_w ay _delay(
C H R _TI MI N GR EC _H AN D LE t imingrec H andle,
C H R _C OU N T* delay );
C H R _API_R C C H R _API_FN
C H R _ t i m i n g re c _ g e t _ R _ v a l u e(
C H R _TI MI N GR EC _H AN D LE t imingrec H andle,
C H R _FLOAT* R v alue);
C H R _API_R C C H R _API_FN
C H R _t i m i ngrec _ get _res ul t _f requenc y (
C H R _TI MI N GR EC _H AN D LE t imingrec H andle,
C H R _R ESU LTS res ult Ty pe,
C H R _C OU N T index ,
C H R _C OU N T* f requenc y );
C H R _API_R C C H R _API_FN
C H R _ t i m i ngrec _ get _ e1_rs s i (
C H R _TI MI N GR EC _H AN D LE t imingrec H andle,
C H R _LON G* rs s i);
C H R _API_R C C H R _API_FN
C H R _ t i m i ngrec _ get _ e2_rs s i (
C H R _TI MI N GR EC _H AN D LE t imingrec H andle,
C H R _LON G* rs s i);
C H R _API_R C C H R _API_FN
C H R _ t i m i ngrec _ get _ e1_bs s i d (
C H R _TI MI N GR EC _H AN D LE t imingrec H andle,
C H R _STR I N G bs s id,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);

- 789 -

IxChariot APIGuide
C H R _API_R C C H R _API_FN
C H R _ t i m i ngrec _ get _ e2_bs s i d (
C H R _TI MI N GR EC _H AN D LE t imingrec H andle,
C H R _STR I N G bs s id,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _t imingrec _get _df (
C H R _TI MI N GR EC _H AN D LE t imingrec H andle,
C H R _C OU N T* df );
C H R _API_R C C H R _API_FN
C H R _ t i m i n g r e c _ g e t _ m l r(
C H R _TI MI N GR EC _H AN D LE t imingrec H andle,
C H R _FLOAT* mlr);
/**
* R et urns t he R eport Group I dent if ier f ield f rom t he t iming rec ord.
*
* @ param i_rec ordH andle
Timing rec ord handle.
* @ param o_report GroupI d R eport group ident if ier.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _t i m i ngrec _ get _report _group_i d(
C H R _TI MI N GR EC _H AN D LE
i_rec ordH andle,
C H R _C OU N T*
o_report GroupI d);
/*
* Trac erout e Objec t Func t ions
* (C H R _ T R A C E R T _ P A I R _H A N D LE )
*/
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_del et e(
C H R _T R A C E R T _ P A I R _H A N D LE pai rH andl e);
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_get _e1_ addr(
C H R _T R A C E R T _ P A I R _H A N D LE pai rH andl e,
C H R _STR I N G e1N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_get _e2_ addr(
C H R _T R A C E R T _ P A I R _H A N D LE pai rH andl e,
C H R _STR I N G e1N ame,
C H R _LEN GTH max Lengt h,
C H R _LEN GTH * lengt h);
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_get _hop_ rec ord(
C H R _T R A C E R T _ P A I R _H A N D LE t rpai rH andl e,
C H R _C OU N T index ,
C H R _H OP R E C _H A N D LE * hopR ec ordH andl e);
C H R _API_R C C H R _API_FN

- 790 -

IxChariot APIGuide
C H R _ t rac ert _ pai r_get _m ax _ hops (
C H R _T R A C E R T _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T* max _hops );
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_get _m ax _ t i m eout (
C H R _T R A C E R T _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T* max _t imeout );
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_get _res ol v e_ hop_ nam e(
C H R _T R A C E R T _ P A I R _H A N D LE pai rH andl e,
C H R _BOOLEAN * res olv e_name);
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_get _runS t at us (
C H R _T R A C E R T _ P A I R _H A N D LE pai rH andl e,
C H R _TR AC ER T_R U N STATU S_TYPE* s t at us );
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_new (
C H R _T R A C E R T _ P A I R _H A N D LE * pai rH andl e);
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_query _ s t op(
C H R _T R A C E R T _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T t imeout );
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_res ul t s _ get _hop_ c ount (
C H R _T R A C E R T _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T* c ount );
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_run (
C H R _T R A C E R T _ P A I R _H A N D LE pai rH andl e);
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_s et _e1_ addr(
C H R _T R A C E R T _ P A I R _H A N D LE pai rH andl e,
C H R _STR I N G e1N ame,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_s et _e2_ addr(
C H R _T R A C E R T _ P A I R _H A N D LE pai rH andl e,
C H R _STR I N G e1N ame,
C H R _LEN GTH lengt h);
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_s et _m ax _ hops (
C H R _T R A C E R T _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T max _hops );
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_s et _m ax _ t i m eout (
C H R _T R A C E R T _ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T max _t imeout );
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_s et _res ol v e_ hop_ nam e(
C H R _T R A C E R T _ P A I R _H A N D LE pai rH andl e,
C H R _BOOLEAN res olv e_name);
C H R _API_R C C H R _API_FN
C H R _ t rac ert _ pai r_s t op(

- 791 -

IxChariot APIGuide
C H R _T R A C E R T _ P A I R _H A N D LE pai rH andl e);
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/*
VoI P Pair f unc t ions
*/
/*
(C H R _V OI P _ P A I R _H A N D LE )
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ new (
C H R _V OI P _P A I R _ H A N D LE * pai rH andl e);
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ get _c odec (
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _V OI P _C OD E C * c odec );
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ s et _c odec (
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _V OI P _C OD E C c odec );
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ get _addi t i onal _del ay (
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _C OU N T* s iz e);
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ s et _addi t i onal _del ay (
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _C OU N T s iz e);
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ get _dat agram _del ay (
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _C OU N T* delay );
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ s et _dat agram _del ay (
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _C OU N T delay );
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ get _des t _port _ num(
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _POR T* port );
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ s et _des t _port _ num(
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _POR T port );
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ get _i ni t i al _ del ay (
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _STR I N G delay ,
C H R _LEN GTH len,
C H R _LEN GTH *rt nlen);
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ s et _i ni t i al _ del ay (
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _STR I N G delay ,
C H R _LEN GTH len);
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ get _j i t t er_buf f er_ s i z e(

- 792 -

*/

IxChariot APIGuide
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _C OU N T* s iz e);
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ s et _j i t t er_buf f er_ s i z e(
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _C OU N T s iz e);
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ get _s ourc e_port _ num(
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _POR T* port );
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ s et _s ourc e_port _ num(
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _POR T port );
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ get _ t r_durat i on(
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _C OU N T* s ec onds );
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ s et _ t r_durat i on(
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _C OU N T s ec onds );
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ get _ no_of _ t i m i ng_rec ords (
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _ C OU N T * no_ of _t r);
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ s et _ no_of _ t i m i ng_rec ords (
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _ C OU N T no_of _ t r);
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ get _us e_P LC (
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _BOOLEAN * us e);
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ s et _us e_P LC (
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _BOOLEAN us e);
C H R _API_R C C H R _API_FN
C H R _ v o i p _p a i r_ g e t _ u s e _ s i l e n c e _ s u p(
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _BOOLEAN * us e);
C H R _API_R C C H R _API_FN
C H R _ v o i p _p a i r_ s e t _ u s e _ s i l e n c e _ s u p(
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _BOOLEAN us e);
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ get _v oi c e_ ac t i v _ rat e(
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _C OU N T* rat e);
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ s et _v oi c e_ ac t i v _ rat e(
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,

- 793 -

IxChariot APIGuide
C H R _C OU N T rat e);
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ get _pay l oad_ f i l e(
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _STR IN G
f ilename,
C H R _LEN GTH
f ilenameLengt h,
C H R _LEN GTH *
rt nlen,
C H R _BOOLEAN *
embedded);
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ s et _pay l oad_ f i l e(
C H R _V OI P _P A I R _ H A N D LE pai rH andl e,
C H R _STR IN G
f ilename,
C H R _LEN GTH
f ilenameLengt h,
C H R _BOOLEAN
embedded);
C H R _API_R C C H R _API_FN
C H R _ v oi p_pai r_ s et _pay l oad_ random (
C H R _V OI P _P A I R _ H A N D LE pai rH andl e);
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/*
Video U nic as t Pair f unc t ions
*/
/*
(C H R _V I D E O_ P A I R _ H A N D LE )
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_new (
C H R _V I D E O_ P A I R _H A N D LE * pai rH andl e);
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_get _c odec (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _VI D EO_C OD EC *c odec );
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_s et _c odec (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _VI D EO_C OD EC c odec );
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_get _des t _ port _num (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _POR T *port );
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_s et _des t _ port _num (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _POR T port );
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_get _i ni t i al _ del ay (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _STR I N G delay ,
C H R _LEN GTH len,
C H R _LEN GTH *rt nlen);
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_s et _i ni t i al _ del ay (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _STR I N G delay ,
C H R _LEN GTH len);
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_get _s ourc e_ port _num (

- 794 -

*/

IxChariot APIGuide
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _POR T *port );
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_s et _s ourc e_ port _num (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _POR T port );
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_get _t r_ durat i on(
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T *s ec onds );
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_s et _t r_ durat i on(
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T s ec onds );
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_get _ no_ of _t i m i ng_ rec ords (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _ C OU N T * no_ of _t r);
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_s et _ no_ of _t i m i ng_ rec ords (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _ C OU N T no_of _ t r);
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_get _f ram es _ per_dat agram (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T *f rames );
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_s et _f ram es _ per_dat agram (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T f rames );
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_get _bi t rat e (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _FLOAT *bit rat e,
C H R _T H R OU GH P U T _U N I T S * rat e_um );
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_s et _bi t rat e (
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _FLOAT bit rat e,
C H R _T H R OU GH P U T _U N I T S rat e_ um );
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_get _rt p_pay l oad_ t y pe(
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _BYTE *rt p_pay load_t y pe);
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_s et _rt p_pay l oad_ t y pe(
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _BYTE rt p_pay load_t y pe);
C H R _API_R C C H R _API_FN
C H R _ v i deo_ pai r_get _m edi a_ f ram e_ s i z e(
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T * m edi a_f ram e_s i z e);
C H R _API_R C C H R _API_FN

- 795 -

IxChariot APIGuide
C H R _ v i deo_ pai r_s et _m edi a_ f ram e_ s i z e(
C H R _V I D E O_ P A I R _H A N D LE pai rH andl e,
C H R _C OU N T media_f rame_s iz e);
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/*
Video Mult ic as t Group f unc t ions
*/
/*
(C H R _ V I D E O_M GR OU P _H A N D LE )
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
C H R _API_R C C H R _API_FN
C H R _v i deo_m group_new (
C H R _V I D E O_M GR OU P _H A N D LE * m groupH andl e);
C H R _API_R C C H R _API_FN
C H R _v i deo_m group_get _c odec (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _VI D EO_C OD EC *c odec );
C H R _API_R C C H R _API_FN
C H R _v i deo_m group_s et _c odec (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _VI D EO_C OD EC c odec );
C H R _API_R C C H R _API_FN
C H R _v i deo_m group_get _i ni t i al _del ay (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G delay ,
C H R _LEN GTH len,
C H R _LEN GTH *rt nlen);
C H R _API_R C C H R _API_FN
C H R _v i deo_m group_s et _i ni t i al _del ay (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _STR I N G delay ,
C H R _LEN GTH len);
C H R _API_R C C H R _API_FN
C H R _ v i deo_ m group_get _s ourc e_ port _num (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _POR T *port );
C H R _API_R C C H R _API_FN
C H R _ v i deo_ m group_s et _s ourc e_ port _num (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _POR T port );
C H R _API_R C C H R _API_FN
C H R _v i deo_m group_get _t r_ durat i on(
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _C OU N T *s ec onds );
C H R _API_R C C H R _API_FN
C H R _v i deo_m group_s et _t r_ durat i on(
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _C OU N T s ec onds );
C H R _API_R C C H R _API_FN
C H R _ v i deo_ m group_get _ no_ of _t i m i ng_ rec ords (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _ C OU N T * no_ of _t r);
C H R _API_R C C H R _API_FN
C H R _ v i deo_ m group_s et _ no_ of _t i m i ng_ rec ords (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _ C OU N T no_of _ t r);

- 796 -

*/

IxChariot APIGuide
C H R _API_R C C H R _API_FN
C H R _v i deo_m group_get _f ram es _ per_dat agram (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _C OU N T *f rames );
C H R _API_R C C H R _API_FN
C H R _v i deo_m group_s et _f ram es _ per_dat agram (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _C OU N T f rames );
C H R _API_R C C H R _API_FN
C H R _v i deo_m group_get _bi t rat e (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _FLOAT *bit rat e,
C H R _T H R OU GH P U T _U N I T S * rat e_um );
C H R _API_R C C H R _API_FN
C H R _v i deo_m group_s et _bi t rat e (
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _FLOAT bit rat e,
C H R _T H R OU GH P U T _U N I T S rat e_ um );
C H R _API_R C C H R _API_FN
C H R _v i deo_m group_get _rt p_pay l oad_ t y pe(
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _BYTE *rt p_pay load_t y pe);
C H R _API_R C C H R _API_FN
C H R _v i deo_m group_s et _rt p_pay l oad_ t y pe(
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _BYTE rt p_pay load_t y pe);
C H R _API_R C C H R _API_FN
C H R _v i deo_m group_get _m edi a_f ram e_s i z e(
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _C OU N T * m edi a_f ram e_s i z e);
C H R _API_R C C H R _API_FN
C H R _v i deo_m group_s et _m edi a_f ram e_s i z e(
C H R _V I D E O_M GR OU P _H A N D LE m groupH andl e,
C H R _C OU N T media_f rame_s iz e);
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/*
H ardw are Perf ormanc e Pair f unc t ions
/*
(C H R _H A R D W A R E _ P A I R _H A N D LE )
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
C H R _API_R C C H R _API_FN
C H R _hardw are_pai r_ new (
C H R _H A R D W A R E _P A I R _ H A N D LE * pai rH andl e);
C H R _API_R C C H R _API_FN
C H R _ hardw are_pai r_ s et _ l i ne_rat e(
C H R _H A R D W A R E _P A I R _ H A N D LE pai rH andl e,
C H R _ F LOA T l i ne_rat e);
C H R _API_R C C H R _API_FN
C H R _hardw are_pai r_ get _ov erri de_l i ne_ rat e(
C H R _H A R D W A R E _P A I R _ H A N D LE pai rH andl e,
C H R _ B OOLE A N * ov erri de_ l i ne_rat e);
C H R _API_R C C H R _API_FN
C H R _hardw are_pai r_ s et _ov erri de_l i ne_ rat e(
C H R _H A R D W A R E _P A I R _ H A N D LE pai rH andl e,
C H R _B OOLE A N ov erri de_l i ne_ rat e);

- 797 -

*/
*/

IxChariot APIGuide
C H R _API_R C C H R _API_FN
C H R _ hardw are_pai r_ get _ l i ne_rat e(
C H R _H A R D W A R E _P A I R _ H A N D LE pai rH andl e,
C H R _FLOAT *line_rat e);
C H R _API_R C C H R _API_FN
C H R _hardw are_pai r_ s et _m eas ure_s t at i s t i c s (
C H R _H A R D W A R E _P A I R _ H A N D LE pai rH andl e,
C H R _MEASU R E_STATS meas ure_s t at is t ic s );
C H R _API_R C C H R _API_FN
C H R _hardw are_pai r_ get _m eas ure_s t at i s t i c s (
C H R _H A R D W A R E _P A I R _ H A N D LE pai rH andl e,
C H R _M E A S U R E _ S T A T S * m eas ure_s t at i s t i c s );
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/*
VoI P H ardw are Perf ormanc e Pair f unc t ions
/*
(C H R _H A R D W A R E _ P A I R _H A N D LE )
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
C H R _API_R C C H R _API_FN
C H R _ hardw are_v oi p_ pai r_new (
C H R _H A R D W A R E _P A I R _ H A N D LE * pai rH andl e);
C H R _API_R C C H R _API_FN
C H R _ hardw are_v oi p_ pai r_s et _c onc urrent _ v oi c e_ s t ream s (
C H R _H A R D W A R E _P A I R _ H A N D LE pai rH andl e,
i nt c onc urrent _v oi c e_s t ream s );
C H R _API_R C C H R _API_FN
C H R _ hardw are_v oi p_ pai r_get _c onc urrent _ v oi c e_ s t ream s (
C H R _H A R D W A R E _P A I R _ H A N D LE pai rH andl e,
int * c onc urrent _v oic e_s t reams );
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/*
Applic at ion Group f unc t ions
*/
/*
(C H R _A P P _GR OU P _ H A N D LE )
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
C H R _API_R C C H R _API_FN
C H R _app_group_new(
C H R _APP_GR OU P_H AN D LE*
appGroupH andle);
C H R _API_R C C H R _API_FN
C H R _app_group_s et _f ilename(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _STR IN G
f ilename,
C H R _LEN GTH
f ilenameLengt h);
C H R _API_R C C H R _API_FN
C H R _app_group_get _f ilename(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _STR IN G
buf f er,
C H R _LEN GTH
buf f erLengt h,
C H R _LEN GTH *
ret Lengt h);
C H R _API_R C C H R _API_FN
C H R _app_group_c opy (
C H R _APP_GR OU P_H AN D LE
t oAppGroupH andle,
C H R _APP_GR OU P_H AN D LE
f romAppGroupH andle);
C H R _API_R C C H R _API_FN
C H R _app_group_delet e(
C H R _APP_GR OU P_H AN D LE
appGroupH andle);
C H R _API_R C C H R _API_FN

- 798 -

*/
*/

*/

IxChariot APIGuide
C H R _app_group_s av e(
C H R _APP_GR OU P_H AN D LE
appGroupH andle);
C H R _API_R C C H R _API_FN
C H R _app_group_f orc e_delet e(
C H R _APP_GR OU P_H AN D LE
appGroupH andle);
C H R _API_R C C H R _API_FN
C H R _app_group_s et _name(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _STR IN G
name,
C H R _LEN GTH
lengt h);
C H R _API_R C C H R _API_FN
C H R _app_group_get _name(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _STR IN G
name,
C H R _LEN GTH
max Lengt h,
C H R _LEN GTH *
lengt h);
C H R _API_R C C H R _API_FN
C H R _app_group_s et _c omment(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _STR IN G
c omment ,
C H R _LEN GTH
lengt h);
C H R _API_R C C H R _API_FN
C H R _app_group_get _c omment(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _STR IN G
c omment ,
C H R _LEN GTH
max Lengt h,
C H R _LEN GTH *
lengt h);
C H R _API_R C C H R _API_FN
C H R _app_group_add_pair(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _P A I R _H A N D LE
pairH andle);
C H R _API_R C C H R _API_FN
C H R _app_group_rem ov e_pai r(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _P A I R _H A N D LE
pairH andle);
C H R _API_R C C H R _API_FN
C H R _ app_ group_ get _pai r_c ount (
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _C OU N T*
pairC ount );
C H R _API_R C C H R _API_FN
C H R _app_group_get _pair(
C H R _APP_GR OU P_H AN D LE appGroupH andle,
C H R _C OU N T index ,
C H R _P A I R _H A N D LE * pai rH andl e);
C H R _API_R C C H R _API_FN
C H R _app_group_add_ev ent(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _STR IN G
ev ent N ame,
C H R _LEN GTH
ev ent N ameLengt h,
C H R _STR IN G
ev ent C omment ,
C H R _LEN GTH
ev ent C omment Lengt h);
C H R _API_R C C H R _API_FN
C H R _app_group_rem ov e_ev ent (

- 799 -

IxChariot APIGuide
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _STR IN G
ev ent N ame,
C H R _LEN GTH
ev ent N ameLengt h);
C H R _API_R C C H R _API_FN
C H R _app_group_get _ev ent _c ount(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _C OU N T*
ev ent C ount );
C H R _API_R C C H R _API_FN
C H R _app_group_get _ev ent(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _C OU N T
index ,
C H R _STR IN G
ev ent N ame,
C H R _LEN GTH
ev ent N ameMax Lengt h,
C H R _LEN GTH *
ev ent N ameLengt h,
C H R _STR IN G
ev ent C omment ,
C H R _LEN GTH
ev ent C omment Max Lengt h,
C H R _LEN GTH *
ev ent C omment Lengt h);
C H R _API_R C C H R _API_FN
C H R _ app_ group_ s et _pai r_prot oc ol (
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _C OU N T
pairI ndex ,
C H R _PR OTOC OL
prot oc ol);
C H R _API_R C C H R _API_FN
C H R _ app_ group_ get _pai r_prot oc ol (
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _C OU N T
pairI ndex ,
C H R _PR OTOC OL*
prot oc ol);
C H R _API_R C C H R _API_FN
C H R _ app_ group_ s et _pai r_m anagem ent _ prot oc ol (
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _C OU N T
pairI ndex ,
C H R _PR OTOC OL
prot oc ol);
C H R _API_R C C H R _API_FN
C H R _ app_ group_ get _pai r_m anagem ent _ prot oc ol (
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _C OU N T
pairI ndex ,
C H R _PR OTOC OL*
prot oc ol);
C H R _API_R C C H R _API_FN
C H R _ app_ group_ s et _pai r_qos _ nam e(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _C OU N T
pairI ndex ,
C H R _STR IN G
qos N ame,
C H R _LEN GTH
qos N ameLengt h);
C H R _API_R C C H R _API_FN
C H R _ app_ group_ get _pai r_qos _ nam e(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _C OU N T
pairI ndex ,
C H R _STR IN G
qos N ame,
C H R _LEN GTH
max Lengt h,
C H R _LEN GTH *
lengt h);
C H R _API_R C C H R _API_FN
C H R _app_group_get _addres s _c ount(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,

- 800 -

IxChariot APIGuide
C H R _C OU N T*
addres s C ount );
C H R _API_R C C H R _API_FN
C H R _app_group_s et _addres s(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _C OU N T
addres s I ndex ,
C H R _STR IN G
addres s ,
C H R _LEN GTH
addres s Lengt h);
C H R _API_R C C H R _API_FN
C H R _app_group_get _addres s(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _C OU N T
addres s I ndex ,
C H R _STR IN G
addres s ,
C H R _LEN GTH
max Lengt h,
C H R _LEN GTH *
lengt h);
C H R _API_R C C H R _API_FN
C H R _app_group_get _m anagem ent _addres s _c ount (
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _C OU N T*
addres s C ount );
C H R _API_R C C H R _API_FN
C H R _app_group_s et _m anagem ent _addres s (
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _C OU N T
addres s I ndex ,
C H R _STR IN G
addres s ,
C H R _LEN GTH
addres s Lengt h);
C H R _API_R C C H R _API_FN
C H R _app_group_get _m anagem ent _addres s (
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _C OU N T
addres s I ndex ,
C H R _STR IN G
addres s ,
C H R _LEN GTH
max Lengt h,
C H R _LEN GTH *
lengt h);
C H R _API_R C C H R _API_FN
C H R _app_group_s et _loc k (
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _BOOLEAN
loc k );
C H R _API_R C C H R _API_FN
C H R _app_group_get _loc k (
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _BOOLEAN *
loc k );
C H R _API_R C C H R _API_FN
C H R _ app_ group_ i s _di s abl ed(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _BOOLEAN *
dis abled);
C H R _API_R C C H R _API_FN
C H R _ a p p _ g ro u p _ d i s a b l e(
C H R _APP_GR OU P_H AN D LE
appGroupH andle,
C H R _BOOLEAN
dis able);
C H R _API_R C C H R _API_FN
C H R _app_group_v alidat e(
C H R _APP_GR OU P_H AN D LE
appGroupH andle);
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/*
I PTV C hannel Objec t f unc t ions
*/
/*
(C H R _C H A N N E L_ H A N D LE )
*/

- 801 -

IxChariot APIGuide
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/**
* D elet es t he s pec if ied I PTV c hannel objec t .
*
* @ param i_c hannelH andle C hannel Objec t handle.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _ OB J E C T _ I N _U S E
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_delet e(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle);
/**
* Get s t he bit rat e v alue and unit of meas urement def ined f or t he giv en
* c hannel.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_bit rat e
Trans mis s ion bit rat e.
* @ param o_unit s
U nit of meas urement in w hic h t he
*
t rans mis s ion rat e is ex pres s ed.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ c h a n n e l _ g e t _ b i t ra t e(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _FLOAT*
o_bit rat e,
C H R _T H R OU GH P U T _U N I T S * o_uni t s );
/**
* R et urns t he c odec t y pe def ined f or t he s pec if ied I PTV c hannel.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_v ideoC odec
Video c odec t y pe (MPEG2 or C U STOM).
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_get _c odec(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,

- 802 -

IxChariot APIGuide
C H R _VI D EO_C OD EC *
o_v ideoC odec );
/**
* R et urns t he c omment s t ring f or t he s pec if ied c hannel objec t .
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_c omment
C harac t er buf f er t o rec eiv e t he c omment .
* @ param i_max Lengt h
Siz e of t he ret urn buf f er.
* @ param o_lengt h
Ac t ual number of by t es ret urned.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _BU FFER _TOO_SMALL
* - C H R _H AN D LE_I N VALI D
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_get _c omment(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _STR IN G
o_c omment ,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h);
/**
* R et urns t he s end buf f er s iz e t o be s pec if ied in t he C ON N EC T.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_buf f erSiz e
Send buf f er s iz e.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ c hannel _ get _c onn_s end_ buf f _s i z e(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C OU N T*
o_buf f erSiz e);
/**
* R et urns t he I P addres s of Endpoint 1 on t he management net w ork .
* This is t he addres s t he c ons ole w ill us e t o perf orm pair s et up.
*
* T hi s param et er w i l l onl y be us ed i f t he us e_ e1_ e2_v al ues at t ri but e i s
* f als e.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_mgmt Addr
C harac t er buf f er t o rec eiv e t he addres s .
* @ param i_max Lengt h
Siz e of t he I P addres s buf f er.
* @ param o_lengt h
Ac t ual number of by t es ret urned.
*
* @ ret urn C hariot API ret urn c ode.

- 803 -

IxChariot APIGuide
* - C H R _OK
* - C H R _BU FFER _TOO_SMALL
* - C H R _H AN D LE_I N VALI D
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ c hannel _ get _ c ons ol e_ e1_addr(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _STR IN G
o_mgmt Addr,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h);
/**
* R et urns t he net w ork prot oc ol t he c ons ole w ill us e w hen c onnec t ing t o
* Endpoint 1 t o perf orm pair s et up.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_prot oc ol
Management net w ork prot oc ol.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ c hannel _ get _ c ons ol e_ e1_prot oc ol (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _PR OTOC OL*
o_prot oc ol);
/**
* R et urns t he I P addres s of Endpoint 1 on t he t es t net w ork .
* The c hannel w ill us e t his as t he s ourc e I P addres s of t he mult ic as t .
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_addres s
Buf f er t o rec eiv e I P addres s .
* @ param i_max Lengt h
Siz e of t he ret urn buf f er.
* @ param o_lengt h
Ac t ual number of by t es ret urned.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _BU FFER _TOO_SMALL
* - C H R _H AN D LE_I N VALI D
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ c hannel _ get _ e1_addr(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _STR IN G
o_addres s ,
C H R _LEN GTH
i_max Lengt h,

- 804 -

IxChariot APIGuide
C H R _LEN GTH *
o_lengt h);
/**
* R et urns t he number of media f rames per dat agram def ined f or t he
* s pec if ied I PTV c hannel.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_f rames
N umber of media f rames per dat agram.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel _ get _f ram es _per_dat agram (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C OU N T*
o_f rames );
/**
* Get s t he media f rame s iz e def ined f or t he giv en I PTV c hannel.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_f rameSiz e
The media f rame s iz e.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_get _media_f rame_s iz e(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C OU N T*
o_f rameSiz e);
/**
* R et urns t he mult ic as t I P addres s of t he I PTV c hannel.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_mult ic as t Addr Buf f er t o rec eiv e t he mult ic as t addres s .
* @ param i_max Lengt h
Siz e of t he res ult buf f er.
* @ param o_lengt h
N umber of by t es s t ored in res ult buf f er.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _BU FFER _TOO_SMALL
* - C H R _H AN D LE_I N VALI D
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN

- 805 -

IxChariot APIGuide
C H R _c hannel_get _mult ic as t _addr(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _STR IN G
o_mult ic as t Addr,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h);
/**
* R et urns t he mult ic as t port number of t he I PTV c hannel.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_mult ic as t Port Mult ic as t port number.
*
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _POI N TER _I N VALI D
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_get _mult ic as t _port (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _POR T*
o_mult ic as t Port );
/**
* R et urns t he name as s igned t o t he s pec if ied I PTV c hannel.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_name
Buf f er t o rec eiv e t he c hannel name.
* @ param i_max Lengt h
Siz e of t he res ult buf f er.
* @ param o_lengt h
N umber of by t es s t ored in res ult buf f er.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _BU FFER _TOO_SMALL
* - C H R _H AN D LE_I N VALI D
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_get _name(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _STR IN G
o_name,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h);
/**
* R et urns t he t es t prot oc ol of t he I PTV c hannel.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_prot oc ol
Prot oc ol t y pe.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D

- 806 -

IxChariot APIGuide
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_get _prot oc ol(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _PR OTOC OL*
o_prot oc ol);
/**
* R et urns t he qualit y -of -s erv ic e t emplat e name f or t he c hannel.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_qos N ame
Buf f er t o rec eiv e t he qos name.
* @ param i_max Lengt h
Siz e of t he res ult buf f er.
* @ param o_lengt h
N umber of by t es s t ored in res ult buf f er.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _BU FFER _TOO_SMALL
* - C H R _H AN D LE_I N VALI D
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_get _qos _name(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _STR IN G
o_qos N ame,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h);
/**
* R et urns t he R TP pay load t y pe def ined f or t he giv en I PTV c hannel. This
* f unc t ion w ill only be s uc c es s f ul if t he c ode t y pe is s et t o C U STOM
* and t he prot oc ol is s et t o R TP or R TP6. Ot herw is e, t he f unc t ion
* ret urns C H R _N O_ S U C H _V A LU E .
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_pay loadTy pe
R TP pay load t y pe.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_get _rt p_pay load_t y pe(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _BYTE*
o_pay loadTy pe);
/**
* Get s t he U D P s ourc e port number f or t he s pec if ied I PTV c hannel.
*

- 807 -

IxChariot APIGuide
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_s ourc ePort
U D P s ourc e port number.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel _ get _s ourc e_port _ num(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _POR T*
o_s ourc ePort );
/**
* I ndic at es w het her t he c ons ole w ill us e t he management net w ork or t he
* t es t net w ork t o perf orm pair s et up.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_us eValues
C H R _TR U E if t he c ons ole w ill us e
*
t he management net w ork ; C H R _FALSE if it
*
w ill us e t he t es t net w ork .
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ c hannel _ get _ us e_ c ons ol e_ e1_v al ues (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _BOOLEAN *
o_us eValues );
/**
* C reat es a new I PTV c hannel objec t and init ializ es it t o t he def ault
* v alues .
*
* The handle ret urned by t his f unc t ion is needed f or ot her f unc t ion
* c alls t o operat e on t he c hannel objec t .
*
* @ param o_c hannelH andle C hannel Objec t handle.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _LI C EN SE_H AS_EXPI R ED
* - C H R _N O_MEMOR Y
* - C H R _N OT_LI C EN SED
* - C H R _POI N TER _I N VALI D
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN

- 808 -

IxChariot APIGuide
C H R _c hannel_new(
C H R _C H AN N EL_H AN D LE*
o_c hannelH andle);
/**
* Spec if ies t he bit rat e v alue and unit of meas urement f or t he giv en
* I PTV c hannel.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_bit rat e
Trans mis s ion rat e of c hannel.
* @ param i_unit s
U nit s in w hic h t rans mis s ion rat e is
*
s pec if ied.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _PGM_I N TER N AL_ER R OR
* - C H R _R ESU LTS_N OT_C LEAR ED
* - C H R _TEST_R U N N IN G
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ c h a n n e l _ s e t _ b i t ra t e(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _FLOAT
i_bit rat e,
C H R _T H R OU GH P U T _U N I T S
i_unit s );
/**
* Spec if ies t he t y pe of c odec f or t he I PTV c hannel objec t .
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_v ideoC odec
C odec t y pe.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _R ESU LTS_N OT_C LEAR ED
* - C H R _TEST_R U N N IN G
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_s et _c odec(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _VI D EO_C OD EC
i_v ideoC odec );
/**
* Spec if ies t he c omment s t ring f or t he c hannel objec t .
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_c omment
C omment s t ring t o be as s igned t o c hannel.
* @ param i_lengt h
Lengt h of c omment s t ring.

- 809 -

IxChariot APIGuide
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _POI N TER _I N VALI D
* - C H R _R ESU LTS_N OT_C LEAR ED
* - C H R _TEST_R U N N IN G
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_s et _c omment(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C ON ST_STR I N G
i_c omment ,
C H R _LEN GTH
i_lengt h);
/**
* Spec if ies t he s end buf f er s iz e t o be s pec if ied in t he C ON N EC T.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_buf f erSiz e
Send buf f er s iz e.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _R ESU LTS_N OT_C LEAR ED
* - C H R _TEST_R U N N IN G
*/
C H R _API_R C C H R _API_FN
C H R _ c hannel _ s et _c onn_s end_ buf f _s i z e(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C OU N T
i_buf f erSiz e);
/**
* Spec if ies t he I P addres s on t he management net w ork t hat t he c ons ole
* us es t o c onnec t t o Endpoint 1 during t es t s et up.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_mgmt Addr
Management addres s of Endpoint 1.
* @ param i_lengt h
Lengt h of management addres s .
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _POI N TER _I N VALI D
* - C H R _R ESU LTS_N OT_C LEAR ED
* - C H R _TEST_R U N N IN G
*
* @ s inc e I x C hariot 6. 50

- 810 -

IxChariot APIGuide
*/
C H R _API_R C C H R _API_FN
C H R _ c hannel _ s et _ c ons ol e_ e1_addr(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C ON ST_STR I N G
i_mgmt Addr,
C H R _LEN GTH
i_lengt h);
/**
* Spec if ies t he net w ork prot oc ol t he c ons ole w ill us e w hen c onnec t ing
* t o Endpoint 1 t o perf orm pair s et up.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_prot oc ol
Management net w ork prot oc ol.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _R ESU LTS_N OT_C LEAR ED
* - C H R _TEST_R U N N IN G
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ c hannel _ s et _ c ons ol e_ e1_prot oc ol (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _PR OTOC OL
i_prot oc ol);
/**
* Spec if ies t he I P addres s of Endpoint 1 on t he t es t net w ork . W ill be
* us ed as t he s ourc e I P addres s f or t he mult ic as t .
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_addres s
Sourc e I P addres s of c hannel.
* @ param i_lengt h
Lengt h of I P addres s .
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _POI N TER _I N VALI D
* - C H R _R ESU LTS_N OT_C LEAR ED
* - C H R _TEST_R U N N IN G
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ c hannel _ s et _ e1_addr(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C ON ST_STR I N G
i_addres s ,
C H R _LEN GTH
i_lengt h);
/**
* Spec if ies t he number of media f rames per dat agram f or t he c hannel.

- 811 -

IxChariot APIGuide
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_f rames
Media f rames per dat agram.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _R ESU LTS_N OT_C LEAR ED
* - C H R _TEST_R U N N IN G
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel _ s et _f ram es _per_dat agram (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C OU N T
i_f rames );
/**
* Spec if ies t he media f rame s iz e us ed f or t he c hannel.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_f rameSiz e
Media f rame s iz e.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _R ESU LTS_N OT_C LEAR ED
* - C H R _TEST_R U N N IN G
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_s et _media_f rame_s iz e(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C OU N T
i_f rameSiz e);
/**
* Spec if ies t he mult ic as t I P addres s on w hic h t raf f ic w ill be
* t rans mit t ed.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_mult ic as t Addr Mult ic as t addres s .
* @ param i_lengt h
Lengt h of mult ic as t addres s .
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _POI N TER _I N VALI D
* - C H R _R ESU LTS_N OT_C LEAR ED

- 812 -

IxChariot APIGuide
* - C H R _TEST_R U N N IN G
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_s et _mult ic as t _addr(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C ON ST_STR I N G
i_mult ic as t Addr,
C H R _LEN GTH
i_lengt h);
/**
* Spec if ies t he s ourc e port number on w hic h mult ic as t t raf f ic w ill be
* t rans mit t ed.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_mult ic as t Port Mult ic as t port number.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _R ESU LTS_N OT_C LEAR ED
* - C H R _TEST_R U N N IN G
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_s et _mult ic as t _port (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _POR T
i_mult ic as t Port );
/**
* Spec if ies t he name of t he c hannel.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_name
N ame t o be as s igned t o c hannel objec t .
* @ param i_lengt h
Lengt h of c hannel name.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _POI N TER _I N VALI D
* - C H R _R ESU LTS_N OT_C LEAR ED
* - C H R _TEST_R U N N IN G
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_s et _name(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C ON ST_STR I N G
i_name,
C H R _LEN GTH
i_lengt h);

- 813 -

IxChariot APIGuide
/**
* Spec if ies t he t es t prot oc ol of t he I PTV c hannel.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_prot oc ol
Prot oc ol t y pe.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _R ESU LTS_N OT_C LEAR ED
* - C H R _TEST_R U N N IN G
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_s et _prot oc ol(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _PR OTOC OL
i_prot oc ol);
/**
* Spec if ies t he qualit y -of -s erv ic e t emplat e f or t he c hannel.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_qos N ame
QoS t emplat e name.
* @ param i_lengt h
Lengt h of QoS t emplat e name.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _POI N TER _I N VALI D
* - C H R _R ESU LTS_N OT_C LEAR ED
* - C H R _TEST_R U N N IN G
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_s et _qos _name(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _C ON ST_STR I N G
i_qos N ame,
C H R _LEN GTH
i_lengt h);
/**
* Spec if ies t he R TP pay load t y pe f or t he giv en c hannel. This f unc t ion
* w ill only s uc c eed if t he c odec t y pe is s et t o C U STOM and t he prot oc ol
* is s et t o R TP or R TP6. Ot herw is e, t he f unc t ion ret urns
* C H R _VALU E_I N VALI D .
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_pay loadTy pe
R TP pay load t y pe.
*
* @ ret urn C hariot API ret urn c ode.

- 814 -

IxChariot APIGuide
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _R ESU LTS_N OT_C LEAR ED
* - C H R _TEST_R U N N IN G
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_s et _rt p_pay load_t y pe(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _BYTE
i_pay loadTy pe);
/**
* Spec if ies t he U D P s ourc e port f or t he I PTV c hannel.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_s ourc ePort
U D P s ourc e port number.
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _R ESU LTS_N OT_C LEAR ED
* - C H R _TEST_R U N N IN G
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _c hannel _ s et _s ourc e_port _ num(
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _POR T
i_s ourc ePort );
/**
* Spec if ies w het her t o us e t he management net w ork (t rue) or t he
* t es t net w ork (f als e) f or pair s et up.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_us eValues
C H R _TR U E t o us e t he management net w ork ;
C H R _FALSE
*
t o us e t he t es t net w ork .
*
* @ ret urn C hariot API ret urn c ode.
* - C H R _OK
* - C H R _H AN D LE_I N VALI D
* - C H R _N OT_SU PPOR TED
* - C H R _ OB J E C T _ I N _U S E
* - C H R _R ESU LTS_N OT_C LEAR ED
* - C H R _TEST_R U N N IN G
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN

- 815 -

IxChariot APIGuide
C H R _ c hannel _ s et _ us e_ c ons ol e_ e1_v al ues (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _BOOLEAN
i_us eValues );
/**
* Spec if ies w het her t he c hannel objec t is loc k ed.
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param o_us eValues
C H R _TR U E f or loc k ed; C H R _FALSE f or
*
unloc k ed.
*
* @ s inc e I x C hariot 6. 70
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_get _loc k (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _BOOLEAN *
o_us eValues );
/**
* Spec if ies w het her t o loc k or not t he c hannel objec t . Loc k ing
* allow s edit ing a c hannel ow ned by a t es t .
*
* @ param i_c hannelH andle C hannel Objec t handle.
* @ param i_us eValues
C H R _TR U E t o loc k ; C H R _FALSE t o
*
unloc k .
*
* @ s inc e I x C hariot 6. 70
*/
C H R _API_R C C H R _API_FN
C H R _c hannel_s et _loc k (
C H R _C H AN N EL_H AN D LE
i_c hannelH andle,
C H R _BOOLEAN
i_us eValues );
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/*
I PTV R ec eiv er Objec t f unc t ions
*/
/*
(C H R _R E C E I V E R _ H A N D LE )
*/
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/**
* Adds an I PTV pair t o t he lis t f or t his rec eiv er.
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param i_pairH andle
I PTV pair t o be added t o rec eiv er.
*
* @ ret urn C hariot API ret urn c ode.
*/
C H R _API_R C C H R _API_FN
C H R _rec ei v er_add_v pai r (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _VPAI R _H AN D LE
i_pairH andle);
/**
* R emov es an I PTV pair f rom t he lis t f or t his rec eiv er.
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param i_pairH andle
I PTV pair t o be remov ed.
*
* @ ret urn C hariot API ret urn c ode.

- 816 -

IxChariot APIGuide
*/
C H R _API_R C C H R _API_FN
C H R _ r e c e i v e r _r e m o v e _ v p a i r(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _VPAI R _H AN D LE
i_pairH andle);
/**
* D elet es t he s pec if ied I PTV rec eiv er objec t .
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t t o be delet ed.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _rec ei v er_del et e(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle);
/**
* R et urns t he c omment s t ring f or t he s pec if ied rec eiv er objec t .
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param o_c omment
Buf f er t o rec eiv e t he c omment s t ring.
* @ param i_max Lengt h
Siz e of t he ret urn buf f er.
* @ param o_lengt h
Ac t ual number of by t es ret urned.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _rec ei v er_get _c om m ent (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _STR IN G
o_c omment ,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h);
/**
* R et urns t he rec eiv e buf f er s iz e t o be s pec if ied in t he C ON N EC T.
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param o_buf f erSiz e
R ec eiv er buf f er s iz e.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ rec ei v er_get _c onn_ rec v _buf f _ s i z e(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C OU N T*
o_buf f erSiz e);
/**
* R et urns t he I P addres s of t he rec eiv er on t he t es t net w ork .
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .

- 817 -

IxChariot APIGuide
* @ param o_addres s
Buf f er t o rec eiv e t he I P addres s .
* @ param i_max Lengt h
Siz e of t he ret urn buf f er.
* @ param o_lengt h
Ac t ual number of by t es ret urned.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _rec ei v er_get _e2_ addr(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _STR IN G
o_addres s ,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h);
/**
* R et urns t he name as s igned t o t he rec eiv er objec t .
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param o_name
Buf f er t o rec eiv e t he rec eiv er name.
* @ param i_max Lengt h
Siz e of t he ret urn buf f er.
* @ param o_lengt h
Ac t ual number of by t es ret urned.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _rec ei v er_get _nam e(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _STR IN G
o_name,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h);
/**
* R et urns t he number of t imes t he J OI N / LEAVE loop w ill be repeat ed.
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param o_it erat ions
J OI N / LEAVE repeat c ount .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ rec ei v er_get _ no_ of _i t erat i ons (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C OU N T*
o_it erat ions );
/**
* R et urns t he s pec if ied I PTV pair objec t f rom t he lis t of pairs
* as s igned t o t his rec eiv er.
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param i_pairI ndex
I ndex of t he des ired ent ry in t he pair lis t ,
*
in t he range 0. . pair_c ount -1.

- 818 -

IxChariot APIGuide
* @ param o_pairH andle
H andle of t he I PTV pair objec t .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _rec ei v er_get _v pai r (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C OU N T
i_pairI ndex ,
C H R _VPAI R _H AN D LE*
o_pairH andle);
/**
* R et urns t he number of pairs t hat hav e been as s igned t o t his rec eiv er.
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param o_pairC ount
N umber of ent ries in t he pair lis t .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _rec ei v er_get _v pai r_c ount (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C OU N T*
o_pairC ount );
/**
* R et urns t he management I P addres s of t he rec eiv er.
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param o_addres s
Buf f er t o rec eiv e t he I P addres s .
* @ param i_max Lengt h
Siz e of t he ret urn buf f er.
* @ param o_lengt h
Ac t ual number of by t es ret urned.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ rec ei v er_get _ s et up_ e1_ e2_addr(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _STR IN G
o_addres s ,
C H R _LEN GTH
i_max Lengt h,
C H R _LEN GTH *
o_lengt h);
/**
* R et urns t he c hannel s w it c h delay (t he int erv al bet w een a LEAVE and
* t he nex t J OI N ).
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param o_s w it c hD elay
C hannel s w it c h delay , in millis ec onds .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50

- 819 -

IxChariot APIGuide
*/
C H R _API_R C C H R _API_FN
C H R _rec ei v er_get _s w i t c h_ del ay (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C OU N T*
o_s w it c hD elay );
/**
* I ndic at es w het her I x C hariot w ill us e t he management net w ork or t he
* t es t net w ork w hen s et t ing up t he t es t .
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param o_us eValues
C H R _TR U E if I x C hariot w ill us e t he
*
management net w ork ; C H R _FALSE if it w ill
*
perf orm pair s et up ov er t he t es t
*
net w ork .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ rec ei v er_get _ us e_ e1_ e2_v al ues (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _BOOLEAN *
o_us eValues );
C H R _API_R C C H R _API_FN
C H R _rec ei v er_i s _ di s abl ed(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _BOOLEAN *
o_dis abled);
/**
* C reat es a new I PTV rec eiv er objec t and init ializ es it t o t he def ault
* v alues .
*
* The handle ret urned by t his f unc t ion is needed f or ot her f unc t ion
* c alls t o operat e on t he rec eiv er objec t .
*
* @ param o_rec eiv erH andle H andle of rec eiv er objec t .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _rec ei v er_new (
C H R _R E C E I V E R _H A N D LE *
o_rec eiv erH andle);
/**
* Spec if ies t he c omment s t ring f or t he rec eiv er objec t .
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param i_c omment
C omment s t ring t o be as s igned t o rec eiv er.
* @ param i_lengt h
Lengt h of c omment s t ring.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50

- 820 -

IxChariot APIGuide
*/
C H R _API_R C C H R _API_FN
C H R _rec ei v er_s et _c om m ent (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C ON ST_STR I N G
i_c omment ,
C H R _LEN GTH
i_lengt h);
/**
* Spec if ies t he rec eiv e buf f er s iz e t o be us ed in t he C ON N EC T.
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param i_buf f erSiz e
R ec eiv er buf f er s iz e.
*
* @ ret urn C haript API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ rec ei v er_s et _c onn_ rec v _buf f _ s i z e(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C OU N T
i_buf f erSiz e);
/**
* Spec if ies t he I P addres s of t he rec eiv er on t he t es t net w ork .
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param i_addres s
I P addres s t o be as s igned t o rec eiv er.
* @ param i_lengt h
Lengt h of I P addres s .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _rec ei v er_s et _e2_ addr(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C ON ST_STR I N G
i_addres s ,
C H R _LEN GTH
i_lengt h);
/**
* Spec if ies t he name of t he rec eiv er objec t .
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param i_name
N ame t o be as s igned t o rec eiv er.
* @ param i_lengt h
Lengt h of name s t ring.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _rec ei v er_s et _nam e(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C ON ST_STR I N G
i_name,
C H R _LEN GTH
i_lengt h);
/**

- 821 -

IxChariot APIGuide
* Spec if ies t he number of t imes t he J OI N / LEAVE loop is t o be repeat ed.
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param i_it erat ions
N umber of J OI N s / LEAVEs t o perf orm.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ rec ei v er_s et _ no_ of _i t erat i ons (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C OU N T
i_it erat ions );
/**
* Spec if ies t he I P addres s of t he rec eiv er on t he management net w ork .
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param i_addres s
Management I P addres s .
* @ param i_lengt h
Lengt h of management I P addres s .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ rec ei v er_s et _ s et up_ e1_ e2_addr(
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C ON ST_STR I N G
i_addres s ,
C H R _LEN GTH
i_lengt h);
/**
* Spec if ies t he c hannel s w it c h delay (t he int erv al bet w een a LEAVE and
* t he nex t J OI N ).
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param i_s w it c hD elay
C hannel s w it c h delay , in millis ec onds .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _rec ei v er_s et _s w i t c h_ del ay (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _C OU N T
i_s w it c hD elay );
/**
* Spec if ies w het her I x C hariot s hould us e t he management net w ork
* (t rue) or t he t es t net w ork (f als e) f or pair s et up.
*
* @ param i_rec eiv erH andle H andle of rec eiv er objec t .
* @ param i_us eValues
C H R _TR U E t o us e t he management net w ork ;
*
C H R _FALSE t o us e t he t es t net w ork .
*
* @ ret urn C hariot API ret urn c ode.

- 822 -

IxChariot APIGuide
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ rec ei v er_s et _ us e_ e1_ e2_v al ues (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _BOOLEAN
i_us eValues );
C H R _API_R C C H R _API_FN
C H R _rec ei v er_di s abl e (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _BOOLEAN
i_dis able);
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/*
R eport Objec t f unc t ions
*/
/*
(C H R _R E P OR T _ H A N D LE )
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/**
* R et urns t he t y pe of t he s pec if ied report it em.
*
* @ param i_report H andle
R eport handle.
* @ param o_report I t em
R eport it em t y pe.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _report _get _i t em _ t y pe(
C H R _R E P OR T _H A N D LE
i_report H andle,
C H R _R E P OR T _I T E M *
o_report I t em);
/**
* R et urns t he join lat enc y f ield f rom t he s pec if ied report .
*
* @ param i_report H andle
R eport handle.
* @ param o_joinLat enc y
J oin lat enc y , in millis ec onds .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _report _get _j oi n_ l at enc y (
C H R _R E P OR T _H A N D LE
i_report H andle,
C H R _FLOAT*
o_joinLat enc y );
/**
* R et urns t he leav e lat enc y f ield f rom t he s pec if ied report .
*
* @ param i_report H andle
R eport handle.
* @ param o_leav eLat enc y
Leav e lat enc y , in millis ec onds .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/

- 823 -

*/

IxChariot APIGuide
C H R _API_R C C H R _API_FN
C H R _report _get _l eav e_l at enc y (
C H R _R E P OR T _H A N D LE
i_report H andle,
C H R _FLOAT*
o_leav eLat enc y );
/**
* R et urns t he report group ident if ier f rom t he s pec if ied report .
*
* @ param i_report H andle
R eport handle.
* @ param o_report GroupI d R eport group ident if ier.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _report _get _report _ group_i d(
C H R _R E P OR T _H A N D LE
i_report H andle,
C H R _C OU N T*
o_report GroupI d);
/**
* Spec if ies w het her t he rec eiv er objec t is loc k ed.
*
* @ param i_rec eiv erH andle R ec eiv er Objec t handle.
* @ param o_us eValues
C H R _TR U E f or loc k ed; C H R _FALSE f or
*
unloc k ed.
*
* @ s inc e I x C hariot 6. 70
*/
C H R _API_R C C H R _API_FN
C H R _rec ei v er_get _l oc k (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _BOOLEAN *
o_us eValues );
/**
* Spec if ies w het her t o loc k or not t he rec eiv er objec t . Loc k ing
* allow s edit ing a rec eiv er ow ned by a t es t .
*
* @ param i_rec eiv erH andle R ec eiv er Objec t handle.
* @ param i_us eValues
C H R _TR U E t o loc k ; C H R _FALSE t o
*
unloc k .
*
* @ s inc e I x C hariot 6. 70
*/
C H R _API_R C C H R _API_FN
C H R _rec ei v er_s et _l oc k (
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle,
C H R _BOOLEAN
i_us eValues );
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/*
I PTV Tes t Objec t f unc t ions
*/
/*
(C H R _T E S T _ H A N D LE )
*/
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/**
* Adds a c hannel objec t t o t he t es t .
*
* @ param i_t es t H andle
Tes t Objec t handle.

- 824 -

IxChariot APIGuide
* @ param i_c hannelH andle H andle of t he C hannel Objec t
*
t he c onf igurat ion.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ t es t _add_ c hannel (
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _C H AN N EL_H AN D LE
i_c hannelH andle);
/**
* R emov es a c hannel objec t f rom t he t es t .
*
* @ param i_t es t H andle
Tes t Objec t handle.
* @ param i_c hannelH andle H andle of t he C hannel Objec t
*
remov ed.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 70
*/
C H R _API_R C C H R _API_FN
C H R _ t es t _rem ov e_ c hannel(
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _C H AN N EL_H AN D LE
i_c hannelH andle);
/**
* Adds a rec eiv er objec t t o t he t es t .
*
* @ param i_t es t H andle
Tes t Objec t handle.
* @ param i_rec eiv erH andle H andle of t he R ec eiv er objec t
*
t he c onf igurat ion.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ t es t _add_ rec ei v er(
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle);
/**
* R emov es a rec eiv er objec t f rom t he t es t .
*
* @ param i_t es t H andle
Tes t Objec t handle.
* @ param i_rec eiv erH andle H andle of t he R ec eiv er objec t
*
remov ed
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 70
*/
C H R _API_R C C H R _API_FN

- 825 -

t o be added t o

t o be

t o be added t o

t o be

IxChariot APIGuide
C H R _ t es t _rem ov e_ rec ei v er(
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _R E C E I V E R _H A N D LE
i_rec eiv erH andle);
/**
* Get s t he s pec if ied c hannel objec t f rom t he t es t .
*
* @ param i_t es t H andle
Tes t Objec t handle.
* @ param i_lis t I ndex
I ndex of t he it em in t he lis t of c hannel
*
obj ec t s , i n t he range 0. . c hannel _c ount -1.
* @ param o_c hannelH andle H andle of t he reques t ed c hannel objec t .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ t es t _get _c hannel (
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _C OU N T
i_lis t I ndex ,
C H R _C H AN N EL_H AN D LE*
o_c hannelH andle);
/**
* R et urns t he c hannel objec t w it h t he s pec if ied name.
*
* @ param i_t es t H andle
Tes t Objec t handle.
* @ param i_c hannelN ame
St ring s pec if y ing t he name of t he c hannel.
* @ param i_nameLengt h
Lengt h of t he c hannel name s t ring.
* @ param o_c hannelH andle H andle of t he reques t ed c hannel objec t .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ t es t _get _c hannel _ by _ nam e(
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _C ON ST_STR I N G
i_c hannelN ame,
C H R _LEN GTH
i_nameLengt h,
C H R _C H AN N EL_H AN D LE*
o_c hannelH andle);
/**
* R et urns t he number of c hannel objec t s in t he t es t .
*
* @ param i_t es t H andle
Tes t Objec t handle.
* @ param o_c hannelC ount
The c hannel objec t c ount .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ t es t _get _c hannel _ c ount (
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _C OU N T*
o_c hannelC ount );
/**

- 826 -

IxChariot APIGuide
* Get s t he s pec if ied rec eiv er objec t f rom t he t es t .
*
* @ param i_t es t H andle
Tes t Objec t handle.
* @ param i_lis t I ndex
I ndex of t he objec t in t he rec eiv e lis t , in
*
t he range 0. . rec eiv er_c ount -1.
* @ param o_rec eiv erH andle H andle of t he reques t ed rec eiv er objec t .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ t es t _get _rec ei v er(
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _C OU N T
i_lis t I ndex ,
C H R _R E C E I V E R _H A N D LE *
o_rec eiv erH andle);
/**
* R et urns t he rec eiv er objec t w it h t he s pec if ied name.
*
* @ param i_t es t H andle
Tes t Objec t handle.
* @ param i_rec eiv erN ame
St ring s pec if y ing t he name of t he rec eiv er.
* @ param i_nameLengt h
Lengt h of t he rec eiv er name s t ring.
* @ param o_rec eiv erH andle H andle of t he reques t ed rec eiv er objec t .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ t es t _get _ rec ei v er_ by _nam e(
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _C ON ST_STR I N G
i_rec eiv erN ame,
C H R _LEN GTH
i_nameLengt h,
C H R _R E C E I V E R _H A N D LE *
o_rec eiv erH andle);
/**
* R et urns t he number of rec eiv er objec t s in t he t es t .
*
* @ param i_t es t H andle
Tes t Objec t handle.
* @ param o_rec eiv erC ount The rec eiv er objec t c ount .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ t es t _get _rec ei v er_ c ount (
C H R _T E S T _H A N D LE
i_t es t H andle,
C H R _C OU N T*
o_rec eiv erC ount );
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/*
I PTV Pair objec t f unc t ions
*/
/*
(C H R _V P A I R _ H A N D LE )
*/
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/**

- 827 -

IxChariot APIGuide
* D elet es t he s pec if ied I PTV pair objec t .
*
* @ param i_pairH andle
Pair handle.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _v pair_delet e(
C H R _VPAI R _H AN D LE
i_pairH andle);
/**
* R et urns t he c hannel w it h w hic h t his pair is as s oc iat ed.
*
* @ param i_pairH andle
Pair handle.
* @ param o_c hannelH andle C hannel handle.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _v pair_get _c hannel(
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C H AN N EL_H AN D LE*
o_c hannelH andle);
/**
* R et urns t he number of t iming rec ords t he pair s hould generat e.
*
* @ param i_pairH andle
Pair handle.
* @ param o_c ount
N umber of t iming rec ords .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ v pai r_ get _ no_of _ t i m i ng_rec ords (
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C OU N T*
o_c ount );
/**
* R et urns t he s pec if ied report f or t his pair.
*
* @ param i_pairH andle
Pair handle.
* @ param i_report I ndex
I ndex of t he reques t ed report (z ero-bas ed).
* @ param o_report H andle
R eport handle.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _v pair_get _report (
C H R _VPAI R _H AN D LE
i_pairH andle,

- 828 -

IxChariot APIGuide
C H R _C OU N T
i_report I ndex ,
C H R _R E P OR T _H A N D LE *
o_report H andle);
/**
* R et urns t he number of report s c ollec t ed f or t his pair.
*
* @ param i_pairH andle
Pair handle.
* @ param o_report C ount
N umber of report s c ollec t ed.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _v pai r_get _report _c ount (
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C OU N T*
o_report C ount );
/**
* R et urns t he s pec if ied t iming rec ord f or t his pair.
*
* @ param i_pairH andle
Pair handle.
* @ param i_rec ordI ndex
I ndex of t he reques t ed t iming rec ord.
* @ param o_rec ordH andle
Timing rec ord handle.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _v pai r_get _t i m i ng_rec ord(
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C OU N T
i_rec ordI ndex ,
C H R _TI MI N GR EC _H AN D LE* o_rec ordH andle);
/**
* R et urns t he number of t iming rec ords c ollec t ed f or t his pair.
*
* @ param i_pairH andle
Pair handle.
* @ param o_rec ordC ount
N umber of t iming rec ords c ollec t ed.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _v pai r_get _t i m i ng_rec ord_ c ount (
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C OU N T*
o_rec ordC ount );
/**
* R et urns t he t iming rec ord durat ion, in s ec onds .
*
* @ param i_pairH andle
Pair handle.
* @ param o_durat ion
Timing rec ord durat ion, in s ec onds .
*
* @ ret urn C hariot API ret urn c ode.

- 829 -

IxChariot APIGuide
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ v pai r_ get _ t r_durat i on(
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C OU N T*
o_durat ion);
/**
* C reat es a new I PTV pair objec t .
*
* @ param o_pairH andle
Pair handle.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _v pair_new(
C H R _VPAI R _H AN D LE*
o_pairH andle);
/**
* Spec if ies t he number of t iming rec ords t he pair s hould generat e.
*
* @ param i_pairH andle
Pair handle.
* @ param i_c ount
Timing rec ord c ount .
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ v pai r_ s et _ no_of _ t i m i ng_rec ords (
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C OU N T
i_c ount );
/**
* Spec if ies t he c hannel w it h w hic h t his pair is as s oc iat ed.
*
* @ param i_pairH andle
Pair handle.
* @ param i_c hannelH andle C hannel handle.
*
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _v pair_s et _c hannel(
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C H AN N EL_H AN D LE
i_c hannelH andle);
/**
* Spec if ies t he t iming rec ord durat ion, in s ec onds .
*
* @ param i_pairH andle
Pair handle.
* @ param i_durat ion
Timing rec ord durat ion, in s ec onds .
*

- 830 -

IxChariot APIGuide
* @ ret urn C hariot API ret urn c ode.
*
* @ s inc e I x C hariot 6. 50
*/
C H R _API_R C C H R _API_FN
C H R _ v pai r_ s et _ t r_durat i on(
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _C OU N T
i_durat ion);
/**
* R et urns t he runs t at us of t he s pec if ied pair
*
* @ param i_pairH andle
Pair handle.
* @ param runSt at us
R uns t at us t o be f illed in.
*
* @ ret urn C hariot API ret urn c ode.
*/
C H R _API_R C C H R _API_FN
C H R _v pair_get _runSt at us(
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _P A I R _R U N S T A T U S _ T Y P E * runS t at us );
/**
* Spec if ies w het her t he pair objec t is loc k ed.
*
* @ param i_pairH andle
Pair Objec t handle.
* @ param o_us eValues
C H R _TR U E f or loc k ed; C H R _FALSE f or
*
unloc k ed.
*
* @ s inc e I x C hariot 6. 70
*/
C H R _API_R C C H R _API_FN
C H R _v pair_get _loc k (
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _BOOLEAN *
o_us eValues );
/**
* Spec if ies w het her t o loc k or not t he pair objec t . Loc k ing
* allow s edit ing a pair ow ned by a t es t .
*
* @ param i_pairH andle
Pair Objec t handle.
* @ param i_us eValues
C H R _TR U E t o loc k ; C H R _FALSE t o
*
unloc k .
*
* @ s inc e I x C hariot 6. 70
*/
C H R _API_R C C H R _API_FN
C H R _v pair_s et _loc k (
C H R _VPAI R _H AN D LE
i_pairH andle,
C H R _BOOLEAN
i_us eValues );
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
/*
end of C def init ions
*/
/ * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- * /
#i f def _ _c pl us pl us
}
#endif

- 831 -

IxChariot APIGuide
#endif

/ * ! C H R API _H _I N C LU D ED */

- 832 -

IxChariot APIGuide

Chapter 5: Tcl Reference

The Tcl (Tool Command Language) Reference describes how to build Tcl scripts using the
IxChariot package. The IxChariot package has ten commands with numerous subcommands. This package is implemented in the C language and uses functions in the
IxChariot API C interface to operate on and with the IxChariot objects. Compilation of the
IxChariot package into the Tcl interpreter is not supported.
Each command name in the IxChariot package takes the form chrObject. The chr prefix
identifies the command as belonging to the IxChariot package. In general, the Object portion of the command name identifies the IxChariot object or set of objects that is referenced by the command. The first argument for all IxChariot package commands is a
subcommand name describing the action to be performed. All subcommands are listed
alphabetically within their respective commands. All IxChariot package subcommands
take an object handle as the second argument, except for the utility command chrApi and
the new subcommand.

- 833 -

IxChariot APIGuide

IxChariot API Objects

The following characteristics apply to the IxChariot API objects in the Tcl package:
n

Most objects have a chrObject new subcommand to create an instance of the

object. This subcommand returns a handle to the new instance. Some object
instances are explicitly created when their containing object instance is created
or as the result of running a test.

Objects having a chrObject new subcommand have a corresponding chrObject

delete subcommand. This subcommand deallocates an object instance and all
supporting structures, which cannot be directly freed by the Tcl interpreter. The
delete subcommand deallocates any object instances that are contained within
this object instance.

Some objects have a chrObject copy subcommand. This subcommand creates a

copy of the instance. Note that the copy subcommand copies other object
instances contained in the object instance but does not copy the results contained within.

Each object has a set of attributes. Some of the attributes are read/write and
others are read-only. For the read/write attributes, a set subcommand is
provided that takes the name of the attribute to be set and the new value as
arguments. Some set subcommands allow multiple name-value pairs to be specified. A get subcommand is provided to access all attribute values. Most of the
attributes of objects are read/write; any information generated by running a
test is accessible via read-only attributes.

Although it is understood that Tcl is a typeless language, data types are shown
in the get and set subcommand descriptions to indicate what can be expected
for returned data and to assist the Tcl programmer in providing the correct data
values for object attributes. Value ranges, valid values, and maximum permitted string lengths are also shown for all set subcommands, and are based on
what is required by the IxChariot API C interface for the applicable functions.

- 834 -

IxChariot APIGuide

Error Returns in Tcl

Error Returns include the following information:
n

Success is returned to the Tcl interpreter when the requested data is returned
or the requested action is successfully completed. If an error is returned by the
IxChariot API C interface function(s) used by a command, or a syntax error is
detected in the command arguments, failure is returned to the interpreter so
that it may terminate the invoking script. The catch command should be used to
prevent script termination and provide actions such as logging of the error or
recovery from specific error conditions.

A text message corresponding to the IxChariot API return code is returned as

data when failure is returned to the Tcl interpreter by the IxChariot package
commands. In the command descriptions, the returned message is shown with
the IxChariot API return code number in parenthesis.

Information about errors, including those detected during package initialization,

is available via the errorCode and errorInfo Tcl global variables. The variable
errorCode is set to a list with two elements. The first element is set to "CHRAPI"
to indicate that the error was detected by the IxChariot package. The second element of the list is set to the IxChariot API return code for the error. The text
message for the error that is returned as data is appended to the errorInfo variable.

- 835 -

IxChariot APIGuide

Extended Error Information

Some commands provide extended error information when the "Operation failed" or
"Object is invalid" message is returned. This extended error information is appended to the
errorInfo variable after the text message describing the error. The detail level for this
extended error information is controlled by the value set via the chrApi setDetail command. The subcommands for which extended error information is available are so noted in
their descriptions.
Extended error information for subcommand and test run errors can also be retrieved
using chrCommonError getInfo, to log the error, for example. This command takes an
optional argument to specify the detail level at which the information is returned, which
may be different than that used for all package commands. The following detail levels
apply:
n

NONE -- No extended error information provided.

PRIMARY -- The IxChariot component that detected the error, the time of error,
the return code, and a primary error message. This is useful for summarizing
error activity.

ADVANCED -- PRIMARY information, plus advanced and informational error messages, if they exist. This level is useful for display and logging.

ALL -- ADVANCED information, plus file information about where the error
occurred.
Extended error information should be logged at detail level ALL to receive
error diagnosis assistance from Ixia.

- 836 -

IxChariot APIGuide

Run Environment
Tcl can be downloaded from the Tcl Developer Xchange Web site at www.tcl.tk/
The Chariot package requires Tcl version 8.0.p2 or higher. The Chariot package has been
tested successfully with Tcl versions 8.0p2, 8.03, 8.04, 8.05, 8.3, and 8.4.
To create a test using IxChariot Tcl API, you must make the IxChariot installation directory
your current working directory. For example, for the default installation directory, you
need to issue this command:
C:\cd Program Files\Ixia\IxChariot
If your working directory is not the installation directory, IxChariot displays this error message:
"couldn't load library chariotext: this library or a dependent library could not be found in
the library path"

- 837 -

IxChariot APIGuide

Debugging Tips
To view the messages printed when a Chariot package command returns an error to the
interpreter, the Tcl shell (tclsh80) should be invoked from a command prompt window
rather than the Start menu or a desktop shortcut. Since the script is aborted by the interpreter when an error is returned by these commands and the Tcl shell window is closed,
the messages are no longer accessible when invoked from the Start menu or a shortcut.
The detail level used for extended error information can be changed via the chrApi setDetail command. The default detail level is ADVANCED. Set this value to ALL for more detail
and to PRIMARY for less detail. Setting this value to NONE means that no extended error
information should be provided.

- 838 -

IxChariot APIGuide

Package Initialization
The Chariot API must be successfully initialized before any Chariot package commands can
be successfully completed. It is initialized when the package is loaded into the Tcl interpreter. Note that the package require Chariot command by itself is not sufficient. The DLLs
must also be loaded for the interpreter to correctly access the Chariot commands.
Various errors can cause initialization failure. Extended error information about the cause
of the failure is printed to the Tcl shell window and is appended to the Tcl global variable
errorInfo for initialization errors. If the package was not successfully initialized, the "API
was not initialized" error will be returned for all subsequent package commands.

Tcl Version 8.0

To use the Chariot package commands in a Tcl script using Tcl version 8.0, one of the following sets of commands should be included in your script to load the package into the Tcl
interpreter:
n

Loading DLLs after the package is identified to the interpreter:

lappend auto_path "directory"
package require Chariot
global auto_index
eval $auto_index(Chariot)
where directory is the name of the directory where Chariot is installed.
This method loads the DLLs after the package is identified to the interpreter as
required. The PKGINDEX.TCL file, included in the Chariot API installation software, must be in the directory containing the DLLs. The lappend command
may be eliminated if the Chariot installation directory is added to auto_path in
the tcl\lib\tcl8.0\init.tcl script.
If the standard Chariot directory on the C: drive is used, these commands are
included in the script Chariot.tcl, located in the directory where you installed
Chariot for your convenience.

Loading DLLs before identifying the package to the interpreter:

load Chariot
package require Chariot
This method loads the DLLs first, then identifies the package as required. The
PKGINDEX.TCL file is not required to load the DLLs; use the Chariot package if
this method is used.

Tcl Version 8.x

To use the Chariot package commands in a Tcl script using Tcl versions newer than 8.0,
one of the following sets of commands should be included in your script to load the package into the Tcl interpreter:
n

Loading DLLs after the package is identified to the interpreter:

lappend auto_path "directory"
package require ChariotExt

- 839 -

IxChariot APIGuide
global auto_index
eval $auto_index(ChariotExt)
where directory is the name of the directory where Chariot is installed.
This method loads the DLLs after the package is identified to the interpreter as
required. The PKGINDEX.TCL file, included in the Chariot API installation software, must be in the directory containing the DLLs. The lappend command may
be eliminated if the Chariot installation directory is added to auto_path in the
tcl\lib\tcl8.0\init.tcl script.
If the standard Chariot directory on the C: drive is used, these commands are
included in the script ChariotExt.tcl, located in the directory where you
installed Chariot for your convenience.
n

Loading DLLs before identifying the package to the interpreter:

load ChariotExt
package require ChariotExt
This method loads the DLLs first, then identifies the package as required. The
PKGINDEX.TCL file is not required to load the DLLs; use the ChariotExt package
if this method is used.

- 840 -

IxChariot APIGuide

Licensing API - Initialization with license details from TCL

scripts
When using TCL commands to invoke IxChariot API functionality, the user has no control
over when API initialization is being executed, so you cannot specify license details (server
name, number of pairs to check out, number of borrow days) directly in the script. In
order to be able to initialize the licensing system using custom details, you will have to
define three environment variables:
l

l
l

CHARIOT_LIC_SERVERspecifies the name of the server to use when performing

license initialization and check out.
CHARIOT_LIC_PAIR_NOspecifies the number of pairs to check out from the server.
CHARIOT_LIC_BORROW_DAYSspecified the number of pairs to borrow days for. If
borrow days is specified as zero, the pairs will be checked out as release on exit.

If one of the above variables is not properly defined (that is, specifying a string instead of
a number for number of pairs, or similar discrepancy) or if its value is left undefined
(null), then API initialization without specific license details will be tried. This will simply
use the license details last specified by the IxChariot console or other API calls. Since initialization with license details modifies the license characteristics, it will not be permitted
while IxChariot console is open. In this case, API initialization will fail with "Operation has
failed. (108)".
Initializing with parameters will fail if there is a node locked license already installed for
the console. In this case, the error returned will be "Not supported. (124)".
Initializing a borrowed license with parameters will fail if another license has already been
borrowed from the same client and is still valid. In this case, the error returned will be "A
license has already been borrowed for this machine (144)". See also the corresponding C
function.

- 841 -

IxChariot APIGuide

Chapter 6: Tcl Functions

- 842 -

IxChariot APIGuide

API Utility Command

The API utility command is used to define and retrieve information for the IxChariot package that is independent of specific objects (tests, pairs, etc.). This command has seven
subcommands.

- 843 -

IxChariot APIGuide

chrApi deleteQosTemplate
DESCRIPTION
The chrApi deleteQosTemplate subcommand deletes the specified QoS template from the
IxChariot QoS template library. The template must be present in the servqual.dat file; otherwise the delete operation will fail.
c hrApi delet eQos Templat e name

ARGUMENTS
name
Provides the name of the QoS template that will be deleted. This string is limited to a
length of 64 characters.

RETURNED DATA
None.

ERROR RETURNS
l

Object is invalid (104)

API was not initialized. (113)

Value is invalid. (115)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 844 -

IxChariot APIGuide

chrApi getDetail
DESCRIPTION
The chrApi getDetail subcommand gets the detail level currently in use for the IxChariot
Tcl subcommands when extended error information is returned. Refer to Extended Error
Information for available levels.
c hrApi get D et ail

ARGUMENTS
None

RETURNED DATA
The returned data provides the detail level (Data type: String).

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 845 -

IxChariot APIGuide

chrApi getLicenseExpirationTime
DESCRIPTION
The chrApi getLicenseExpirationTime subcommand returns the expiration time for
borrowed licenses.
c hrApi get Lic ens eEx pirat ionTime

ARGUMENTS
None

RETURNED DATA
The returned data provides the expiration time for borrowed licenses. It returns zero for
node-locked and floating licenses.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 846 -

IxChariot APIGuide

chrApi getLicenseType
DESCRIPTION
The chrApi getLicenseType subcommand returns the value of the current Ixia license
type.
c hrApi get Lic ens eTy pe

ARGUMENTS
None

RETURNED DATA
The returned data provides the value of the current Ixia license type.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 847 -

IxChariot APIGuide

chrApi getMaxPairs
DESCRIPTION
The chrApi getMaxPairs subcommand gets the maximum number of pairs and multicast
pairs allowed in a test for this installation of IxChariot.
c hrApi get Max Pairs

ARGUMENTS
None

RETURNED DATA
The returned data provides the maximum number of pairs (Data type: Long). CHR_
INFINITE is returned for an unlimited Console.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 848 -

IxChariot APIGuide

chrApi getNetworkIPLIst
DESCRIPTION
The chrAPI getNetworkIPList subcommand gets the list of configured network
addresses for the specified management IP address.
c hrApi get Port Mgmt I PLis t mgmt I P

ARGUMENTS
mgmtIP
The management IP address to be used as input.

RETURNED DATA
A list containing the list of configured network IP addresses for a specified port management address.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 849 -

IxChariot APIGuide

chrApi getPairType
DESCRIPTION
The chrApi getPairType subcommand gets the pair type for a pair defined in a test. This
enables you to identify the specific parameters available for that pair. For example, if the
IxChariot test uses only regular pairs, then you can check for Average Throughput, Timing
Records completed, and so forth. If the test uses VoIP pairs, you can check for Average
MOS, Jitter delay variation, and so forth.
c hrApi get PairTy pe $handle

ARGUMENTS
$handle
A handle returned by chrPair new or chrMpair new.

RETURNED DATA
The returned data identifies the pair type. The pair-type values are:
l

REGULAR_PAIR (Pairs with non-streaming scripts)

STREAMING_PAIR

VOIP_PAIR

VIDEO_PAIR

HARDWARE_PAIR

HARDWARE_VOIP_PAIR
With video multicast groups, the returned pair type for a video pair inside the
multicast group will be STREAMING_PAIR, rather than VIDEO_PAIR.

ERROR RETURNS
l

Handle is invalid. (101)

Pointer is invalid. (103)

API was not initialized. (113)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 850 -

IxChariot APIGuide

chrApi getPortMgmtIPLIst
DESCRIPTION
The chrAPI getPortMgmtIPList subcommand gets the list of configured management IP
addresses available for a chassis configuration.
c hrApi get Port Mgmt I PLis t

ARGUMENTS
None

RETURNED DATA
A list containing the list of configured port management IP addresses.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 851 -

IxChariot APIGuide

chrApi getReportingPort
DESCRIPTION
The chrApi getReportingPort subcommand gets the port number used by Endpoint 1 to
report results to the IxChariot Console for the given protocol type.
c hrApi get R eport ingPort t y pe

ARGUMENTS
type
Provides one of the following value types: TCP or SPX.

RETURNED DATA
This returned data provides the port number (Data type: Long). Specifying a zero causes
IxChariot to automatically select the port when a test is run using the given protocol for
Console to Endpoint 1 communications.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Value is invalid. (115)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 852 -

IxChariot APIGuide

chrApi getReturnMsg
DESCRIPTION
The chrApi getReturnMsg subcommand gets the text message for the IxChariot API return
code stored into $errorCode by an error. When an error is detected by the Tcl package, $errorCode is set to a list containing two elements. The first contains the literal string
"CHRAPI" and the second contains the IxChariot API return code for the error.
To get the text for a return code at any time other than after an error that has set $errorCode, this command should be called, with a list defined as described above.
C hrApiR et urnMs g $errorC ode

ARGUMENTS
$errorCode
The Tcl global variable $errorCode.

RETURNED DATA
The returned data provides the return code text message (Data type: String).

ERROR RETURNS
l

API was not initialized. (113)

Value is invalid (115)

Out of memory. (120)

Program internal error. (121).

See Return Code Summary for a detailed description of each return code.

- 853 -

IxChariot APIGuide

chrApi getVersion
DESCRIPTION
The chrApi getVersion subcommand gets the version number of the IxChariot API.
c hrApi get Vers ion

ARGUMENTS
None

RETURNED DATA
This returned data provides the version number (Data type: String).

ERROR RETURNS
The following return codes indicates that an error occurred, and any returned data should
be ignored:
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 854 -

IxChariot APIGuide

chrApi licenseChangeBorrowTime
DESCRIPTION
The chrApi licenseChangeBorrowTime subcommand changes the expiration time for all
the current licenses (console, VoIP, video. pairs, and so forth). It will fail if the current
license type is neither FLOATING nor FLOATING_BORROW.
c hrApi lic ens eC hangeBorrow Time day s
This subcommand will check-in all the current features and then check them out using the
new expiration time. If the check-out fails, there will be no license for any feature.
This subcommand cannot be called while the IxChariot console is running. Calling
this subcommand while IxChariot console is running will result in an error code
being returnedThe floating license is in use by IxChariot console or another API program. (145).
They will also fail with "Not supported. (124)", if used for a node locked license.

ARGUMENTS
days
The number of days for which the license is borrowed. If days is zero, floating licenses will
be used.

RETURNED DATA
None.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Not supported. (124)

The floating license is in use by IxChariot console or another API program. (145)

See Return Code Summary for a detailed description of each return code.

- 855 -

IxChariot APIGuide

chrApi licenseChangeLicenseServer
DESCRIPTION
This subcommand changes the license server used to check out a floating license. It will
check in any previously checked out licenses and try a check out with the same license
parameters (pair count and borrow days) from the new server. It will fail if check out type
is not of type FLOATING or FLOATING_BORROW or if IxChariot console is running at the
time of the call. If the check out fails, there will be no license for any feature.
c hrApi lic ens eC hangeLic ens eServ er s erv erN ame

ARGUMENTS
serverName
The name of the new server to attempt the new license check out from.

RETURNED DATA
None.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Operation has failed. (108)

Not supported. (124)

The floating license is in use by IxChariot console or another API program. (145)

See Return Code Summary for a detailed description of each return code.

- 856 -

IxChariot APIGuide

chrApi licenseCheckinPairs
DESCRIPTION
The chrApi licenseCheckinPairs subcommand checks in to the license server any
pairs that are presently checked out. This function will fail if the license type is neither
FLOATING nor FLOATING_BORROW. It does nothing if there are no pairs checked-out.
c hrApi lic ens eC hec k inPairs
This subcommand cannot be called while the IxChariot console is running. Calling
this subcommand while IxChariot console is running will result in an error code
being returnedThe floating license is in use by IxChariot console or another API program. (145).
They will also fail with "Not supported. (124)", if used for a node locked license.

ARGUMENTS
None.

RETURNED DATA
None.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Not supported. (124)

The floating license is in use by IxChariot console or another API program. (145)

See Return Code Summary for a detailed description of each return code.

- 857 -

IxChariot APIGuide

chrApi licenseCheckoutPairs
DESCRIPTION
The chrApi licenseCheckoutPairs subcommand checks out the specified number of
pairs from the license server. This function is applicable only if the current license is either
FLOATING or FLOATING_BORROW.
c hrApi lic ens eC hec k out Pairs noPairs
This subcommand cannot be called while the IxChariot console is running. Calling
this subcommand while IxChariot console is running will result in an error code
being returnedThe floating license is in use by IxChariot console or another API program. (145).
They will also fail with "Not supported. (124)", if used for a node locked license.

ARGUMENTS
noPairs
The number of pairs to check out. The number of pairs specified must be positive. In addition, the actual number of pairs that will be checked-out from the server will be rounded to
the next highest multiple of 10. For example, if you specify 14 as the value for noPairs, 20
pairs will be checked out.
If any pairs are already checked-out, they will be checked-in and the number of pairs specified in noPairs will then be checked-out. If the check-out fails, there will be no license
for the pairs.

RETURNED DATA
None.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Not supported. (124)

The floating license is in use by IxChariot console or another API program. (145)

See Return Code Summary for a detailed description of each return code.

- 858 -

IxChariot APIGuide

chrApi licenseGetBorrowDaysRemaining
DESCRIPTION
This subcommand returns the number of borrow days remaining for the current license
check out:
l

0, if check out type is release on exit.

Number of days remaining if check out type is borrow.

CHR_NOT_SUPPORTED if check out type is node locked.

Since this subcommand does not modify the license characteristics, it can be used while
IxChariot console is open.
c hrApi lic ens eGet Borrow D ay s R emaining

ARGUMENTS
None

RETURNED DATA
A count of the number of borrow days remaining for the current check out.

ERROR RETURNS
l

Object is in use. (107)

Operation has failed. (108)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Not supported. (124)

See Return Code Summary for a detailed description of each return code.

- 859 -

IxChariot APIGuide

chrApi licenseGetLicenseServer
DESCRIPTION
This subcommand gets the name of the license server currently in use for license check
out.
c hrApi lic ens eGet Lic ens eServ er

ARGUMENTS
None

RETURNED DATA
The returned data provides the name of the license server (Data type: String).

ERROR RETURNS
l

API was not initialized. (113)

Value is invalid (115)

Out of memory. (120)

Program internal error. (121)

Not supported. (124)

See Return Code Summary for a detailed description of each return code.

- 860 -

IxChariot APIGuide

chrApi licenseGetTestPairCount
DESCRIPTION
The chrApi licenseGetTestPairCount subcommand returns a count of the number of
pairs configured for the specified IxChariot test. This subcommand can be executed even if
there is no license for the pairs.
c hrApi lic ens eGet Tes t PairC ount f ilename

ARGUMENTS
filename
The name of the IxChariot test file for which the count is required. The filename may be
specified with a full or relative pathname.

RETURNED DATA
A count of the number of pairs configured for the specified IxChariot test.

ERROR RETURNS
l

String is too long. (102)

Object is in use. (107)

Operation has failed. (108)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 861 -

IxChariot APIGuide

chrApi modifyQosTosTemplate
DESCRIPTION
The chrApi modifyQosTosTemplate subcommand modifies the specified TOS template. The
template must be present in the servqual.dat file; otherwise the modify operation will fail.
c hrApi modif y Qos Tos Templat e t y pe name mas k

ARGUMENTS
type
Provides one of the following values:
l

CHR_QOS_TEMPLATE_TOS_BIT_MASK

CHR_QOS_TEMPLATE_DIFFSERV

CHR_QOS_TEMPLATE_L2_PRIORITY

name
Provides the name of the QoS template that will be modified. This string is limited to a
length of 64 characters.

mask
Provides the new TOS mask value for the template, given as a decimal number. For
example, if the desired TOS mask is 0110 0000, you would enter 96 as the mask value. For
Layer 2, must be in the 0-7 interval.

RETURNED DATA
None.

ERROR RETURNS
l

Object is invalid. (104)

API was not initialized. (113)

Value is invalid. (115)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 862 -

IxChariot APIGuide

chrApi newQosTosTemplate
DESCRIPTION
The chrApi newQosTosTemplate subcommand creates a new TOS template that can be
used both on management traffic and test traffic. The template will be stored in the servqual.dat file.
c hrApi new Qos Tos Templat e t y pe name mas k
Note that you can receive a return code of 115 for either of these reasons: to indicate that
a template with the specified name already exists in the servqual.dat file; to indicate that
the template type passed as a parameter is not one of the valid values for the type argument; or, to indicate that the mask argument does not have a value in the 0-7 interval for
Layer 2.

ARGUMENTS
type
Provides one of the following values:
l

CHR_QOS_TEMPLATE_TOS_BIT_MASK

CHR_QOS_TEMPLATE_DIFFSERV

CHR_QOS_TEMPLATE_L2_PRIORITY

name
Provides the name of the QoS template that will be created. This string is limited to a
length of 64 characters.

mask
Provides the TOS mask value for the new template, given as a decimal number. For
example, if the desired TOS mask is 0110 0000, you would enter 96 as the mask value. For
Layer 2, must be in the 0-7 interval.

RETURNED DATA
None.

ERROR RETURNS
l

Object is invalid. (104)

API was not initialized. (113)

Value is invalid. (115)

Out of memory. (120)

See Return Code Summary for a detailed description of each return code.

- 863 -

IxChariot APIGuide

chrApi setDetail
DESCRIPTION
The chrApi setDetail subcommand sets the detail level to be used by the IxChariot Tcl subcommands when returning extended error information.
c hrApi s et D et ail det ail

ARGUMENTS
detail
Provides one of the following values: NONE, PRIMARY, ADVANCED, or ALL. Refer to Extended Error Information for available levels.

RETURNED DATA
None

ERROR RETURNS
l

API was not initialized. (113)

Value is invalid (115)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 864 -

IxChariot APIGuide

chrApi setReportingPort
DESCRIPTION
The chrApi setReportingPort subcommand sets or changes the port number used by Endpoint 1 to report results to the IxChariot Console using the specified protocol. Specifying a
zero causes IxChariot to automatically select the port when a test is run using the given
protocol for Console to Endpoint 1 communications.
c hrApi s et R eport ingPort t y pe port

ARGUMENTS
type
Provides type: TCP or SPX.

port
The port number in the range of 165535. Specifying a zero causes IxChariot to automatically select the port number when a test is run using the given protocol for Console to
Endpoint 1 communications.

RETURNED DATA
None

ERROR RETURNS
l

Test is running. (106)

Object is in use. (107)

API was not initialized. (113)

Value is invalid. (115)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 865 -

IxChariot APIGuide

Application Group Object Command

The application group object command is used to define and retrieve properties and values
for application groups. Application groups provide the means to synchronize the actions of
two or more pairs during a test. This allows you to simulate the behavior of applications
that use more than one simultaneous connection (such as FTP, which uses one connection
for control and the other for data transfer).
You can use the IxChariot application group functions to perform all of the following activities:
l

load one or more application groups from a file with an .iag extension.

save an application group to a file with an .iag extension.

copy one application group to another.

add an application group to a test.

remove an application group from a test.

create an (empty) application group.

edit some application group attributes (name, comment).

validate an application group (on request and when starting the test).

add a pair to an application group.

remove a pair from an application group.

get the handle of a pair from an application group.

add an event to an application group.

remove an event from an application group.

get the number of events from the application group.

get the name and the comment of a specific event.

Refer to the IxChariot Script Development and Editing Guide for a detailed description of
application groups.

- 866 -

IxChariot APIGuide

chrAppGroup addEvent
DESCRIPTION
The chrAppGroup addEvent subcommand adds an event to the designated application
group. Events are objects defined within application groups and passed as parameters to
the WAIT_EVENT and SIGNAL_EVENT script commands. An event is simply a unique name
(a character string) defined within an application group. An event does not specify any
actions. Rather, it acts as a token to trigger the scripts to pause or resume execution at
specific points in the scripts.
c hrAppGroup addEv ent appGroup ev N ame ev C omment

ARGUMENTS
appGroup
The handle for the application group, returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

evName
A name for the event. Note that:
l

An event name can be any non-empty string other than "Not Assigned" (otherwise,
error Value is invalid (115) will be returned).
The event name must be unique within that application group (otherwise, error Duplicate name (143) will be returned).

evComment
An optional comment for this event.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Object is in use. (107)

API was not initialized. (113)

Value is invalid. (115)

Out of memory. (120)

Program internal error. (121)

Duplicate name. (143)

See Return Code Summary for a detailed description of each return code.

- 867 -

IxChariot APIGuide

chrAppGroup addPair
DESCRIPTION
The chrAppGroup addPair subcommand adds an endpoint pair to the designated application
group.
c hrAppGroup addPair appGroup pair

ARGUMENTS
appGroup
The handle for the application group, returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

pair
The handle returned by chrPair new or chrTest getPair.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

Object is invalid. (112)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Script is too large. (127)

See Return Code Summary for a detailed description of each return code.

- 868 -

IxChariot APIGuide

chrAppGroup copy
DESCRIPTION
The chrAppGroup copy subcommand copies the attributes of the source application group
to the destination application group. This does not include any results information.
c hrAppGroup c opy des t AppGroup s ourc eAppGroup

ARGUMENTS
destAppGroup
The handle for the destination, returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

sourceAppGroup
The handle for the source, returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

Object in use (107)

Operation failed (108)

Pair limit exceeded (111)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Script too large (127)

Application group duplicate name (137)

See Return Code Summary for a detailed description of each return code.

- 869 -

IxChariot APIGuide

chrAppGroup delete
DESCRIPTION
The chrAppGroup delete subcommand frees all memory associated with the given application group object. This is necessary because the Tcl interpreter has no access to the associated structures supporting the object. An application group cannot be deleted if it is
owned by a test.
c hrAppGroup delet e appGroup [ f orc e]

ARGUMENTS
appGroup
The handle for the application group, returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

force
An optional parameter that, if specified, deletes the application group whether or not it has
been saved.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

Test is running (106)

Object in use (107)

Operation failed (108)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Test not saved (133)

See Return Code Summary for a detailed description of each return code.

- 870 -

IxChariot APIGuide

chrAppGroup getAddress
DESCRIPTION
The chrAppGroup getAddress subcommand returns the network address or management
address of a specific pair within the application group.
c hrAppGroup get Addres s appGroup index at t ribut eN ame

ARGUMENTS
appGroup
The handle for the application group, returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

index
The index for the specific pair, returned by chrAppGroup getCount.

attributeName
Can be NETWORK_ADDRESS or MANAGEMENT_ADDRESS.

RETURNED DATA
The chrAppGroup copy subcommand returns the a network address or management
address of the specified pair within the application group:

ERROR RETURNS
l

Handle is invalid. (101)

Pointer is invalid (103)

No such object (104)

API was not initialized. (113)

Buffer too small (119)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 871 -

IxChariot APIGuide

chrAppGroup get
DESCRIPTION
The chrAppGroup get subcommand returns the specified attribute for the application
group.
c hrAppGroup get appGroup at t ribut eN ame

ARGUMENTS
appGroup
The handle for the application group, returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

attributeName
Can be APP_GROUP_NAME, APP_GROUP_COMMENT, APP_GROUP_FILENAME, APP_GROUP_
LOCK, or IS_DISABLED.

RETURNED DATA
The chrAppGroup get subcommand returns one of the following attributes for the specified
application group:
Attribu te Nam e

W h at I s Retu rn ed

Data Ty pe

APP_GROU P_COMMENT

The appl i cati on gr oup comment

Str i ng

APP_GROU P_F I LENAME

The appl i cati on gr oup f i l ename

Str i ng

The application group lock value:

APP_GROU P_LOCK

APP_GROU P_NAME

TRUE if locked

FALSE if not locked

The appl i cati on gr oup name

Boolean

Str i ng

The state of the pairs in the application

group:
I S _D I S A B L E D
l

TRUE if disabled

FALSE if enabled

ERROR RETURNS
l

Handle is invalid. (101)

Pointer is invalid (103)

No such object (104)

API was not initialized. (113)

Buffer too small (119)

- 872 -

Boolean

IxChariot APIGuide

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 873 -

IxChariot APIGuide

chrAppGroup getCount
DESCRIPTION
The chrAppGroup getCount subcommand returns the number of unique objects of the specified type for the application group.
c hrAppGroup get C ount appGroup at t ribut eN ame

ARGUMENTS
appGroup
The handle for the application group, returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

attributeName
Can be NETWORK_ADDRESS, MANAGEMENT_ADDRESS, PAIR, or EVENT.

RETURNED DATA
The chrAppGroup copy subcommand returns the count of unique objects used in the application group. The objects are of the following types:
l

Network address

Management address

Pair address

Event

ERROR RETURNS
l

Handle is invalid. (101)

Pointer is invalid (103)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 874 -

IxChariot APIGuide

chrAppGroup getEventComment
DESCRIPTION
The chrAppGroup getEventComment subcommand gets the comment associated with an
event defined in the given application group.
c hrAppGroup get Ev ent C omment index

ARGUMENTS
index
A zero-based index that can take values between 0 and ChrAppGroupGetCount 1. The
index identifies a specific event within the application group. For example, if there are four
events in an application group, their index numbers are 0, 1, 2, and 3.

RETURNED DATA
The event comment.

ERROR RETURNS
l

Handle is invalid. (101)

Pointer is invalid. (103)

No such object. (104)

API was not initialized. (113)

Buffer is too small. (119)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 875 -

IxChariot APIGuide

chrAppGroup getEventName
DESCRIPTION
The chrAppGroup getEventName subcommand gets the name of an event defined in the
given application group.
c hrAppGroup get Ev ent N ame index

ARGUMENTS
index
A zero-based index that can take values between 0 and ChrAppGroupGetCount 1. The
index identifies a specific event within the application group. For example, if there are four
events in an application group, their index numbers are 0, 1, 2, and 3.

RETURNED DATA
The name of the event indicated by the index value.

ERROR RETURNS
l

Handle is invalid. (101)

Pointer is invalid. (103)

No such object. (104)

API was not initialized. (113)

Buffer is too small. (119)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 876 -

IxChariot APIGuide

chrAppGroup getPair
DESCRIPTION
The chrAppGroup getPair subcommand returns the handle of the specified pair within the
application group.
c hrAppGroup get Pair appGroup index
Before IxChariot 6.70, this subcommand required three parameters:
chrAppGroup getPair appGroup index attributeName
This form of the subcommand is still supported, but is considered to be deprecated.
The attributeName parameter in the deprecated form of the command takes any of
the following values: PROTOCOL, MANAGEMENT_PROTOCOL, or QOS.
The deprecated form of the subcommand returns one of the following attributes for
the specified pair:
l

Endpoint 1 to Endpoint 2 network protocol

Management protocol

QoS name

ARGUMENTS
appGroup
The handle for the application group, returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

index
A zero-based index that can take values between 0 and ChrAppGroupGetCount 1. The
index identifies a specific pair within the application group. For example, if there are four
pair in an application group, their index numbers are 0, 1, 2, and 3.

RETURNED DATA
The handle of the specified pair.

ERROR RETURNS
l

Handle is invalid. (101)

Pointer is invalid (103)

No such object (104)

API was not initialized. (113)

Buffer too small (119)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 877 -

IxChariot APIGuide

- 878 -

IxChariot APIGuide

chrAppGroup new
DESCRIPTION
The chrAppGroup new subcommand creates an application group and initializes it to
default values. See Application Group Object Default Values for a list of the default values.
c hrAppGroup new

ARGUMENTS
None.

RETURNED DATA
The returned data provides the handle to an initialized application group object. The handle
returned by this subcommand is needed for other subcommands to operate on the object.

ERROR RETURNS
l

Pointer is invalid (103)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 879 -

IxChariot APIGuide

chrAppGroup removeEvent
DESCRIPTION
The chrAppGroup removeEvent subcommand removes an event from the designated application group.
c hrAppGroup remov eEv ent appGroup ev N ame
l
l

The application group must be either unowned or locked.

The removed event will be set to "Not Assigned" in all the pairs that use it in the
application group.

ARGUMENTS
appGroup
The handle for the application group, returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

evName
The name of the event to remove.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

No such object. (104)

Object is in use. (107)

API was not initialized. (113)

Value is invalid. (115)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 880 -

IxChariot APIGuide

chrAppGroup removePair
DESCRIPTION
The chrAppGroup removePair subcommand removes an endpoint pair from the designated
application group.
c hrAppGroup remov ePair appGroup pair
l

The application group must be either unowned or locked.

All the event variables inside the pair script will be set to "Not Assigned".

ARGUMENTS
appGroup
The handle for the application group, returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

pair
The handle returned by chrPair new or chrTest getPair.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

No such object. (104)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 881 -

IxChariot APIGuide

chrAppGroup save
DESCRIPTION
The chrAppGroup save subcommand saves the specified application group.
c hrAppGroup s av e appGroup [ f ilename]
This command saves only one application group to the file, and that application group must
contain at least one pair.

ARGUMENTS
appGroup
The handle for the destination returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

filename
An optional parameter that, if specified, identifies the external file to which the application
group is to be written. If no filename is specified, the application group is saved only in
memory.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

Pointer is invalid (103)

No such object (104)

Test is running (106)

Operation failed (108)

No test file (109)

API was not initialized. (113)

No such value. (116)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 882 -

IxChariot APIGuide

chrAppGroup setAddress
DESCRIPTION
The chrAppGroup setAddress subcommand sets or changes one or more addresses for the
application group. A single command can set multiple network addresses and management
addresses.
c hrAppGroup s et Addres s appGroup index at t ribut eN ame1
v alue1 [ at t ribut eN ame2 v alue2 . . . ]

ARGUMENTS
appGroup
The handle for the application group, returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

index
The index for the specific pair, returned by chrAppGroup getCount.

attributeNamen
Can be NETWORK_ADDRESS or MANAGEMENT_ADDRESS.

valuen
The address to be set or changed.

RETURNED DATA
None:

ERROR RETURNS
l

Handle is invalid. (101)

String too long (102)

Pointer is invalid (103)

No such object (104)

Object in use (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 883 -

IxChariot APIGuide

chrAppGroup set
DESCRIPTION
The chrAppGroup set subcommand sets or changes one or more addresses for the application group. A single command can set values for multiple attributes.
c hrAppGroup s et appGroup at t ribut eN ame1 v alue1
[ at t ribut eN ame2 v alue2 . . . ]

ARGUMENTS
appGroup
The handle for the application group, returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

attributeNamen
Can be any of the following:
l

l
l

APP_GROUP_NAMEthe application group name (string value, 25 characters maximum).

APP_GROUP_COMMENTthe application group comment (string value, 129 characters
maximum).
APP_GROUP_FILENAMEthe application group filename, which may optionally include
the pathname (string value, 602 characters maximum).
APP_GROUP_LOCKthe application group lock value (Boolean value: 1 or 0).
DISABLEthe state of the pairs in the application group (Boolean value: 1 to disable, 0
to enable).

valuen
The value of the attribute to be set or changed.

RETURNED DATA
None:

ERROR RETURNS
l

Handle is invalid. (101)

String too long (102)

Pointer is invalid (103)

No such object (104)

Object in use (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 884 -

IxChariot APIGuide

chrAppGroup setPair
DESCRIPTION
The chrAppGroup setPair subcommand sets or changes the selected attribute for the specified pair within the application group. A single command can set multiple attributes.
c hrAppGroup s et Pair appGroup index at t ribut eN ame1 v alue1
[ at t ribut eN ame2 v alue2 . . . ]
This function has been deprecated as of IxChariot 6.70. The function is still available, but the recommend procedure is to get the handle of the pair and use the
pair API functions.

ARGUMENTS
appGroup
The handle for the application group, returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

index
The index for the specific pair, returned by chrAppGroup getCount.

attributeNamen
Can be one of the following:
l

PROTOCOLthe Endpoint 1 to Endpoint 2 network protocol for the pair.

MANAGEMENT_PROTOCOLthe management protocol for the pair.

QOSthe QoS name for the specified pair (QoS name is a string value, 65 characters
maximum).

valuen
The value of the attribute to be set or changed.

RETURNED DATA
None:

ERROR RETURNS
l

Handle is invalid. (101)

String too long (102)

Pointer is invalid (103)

No such object (104)

Object in use (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

- 885 -

IxChariot APIGuide
See Return Code Summary for a detailed description of each return code.

- 886 -

IxChariot APIGuide

chrAppGroup validate
DESCRIPTION
The chrAppGroup validate subcommand verifies the validity of the designated application
group.
c hrAppGroup v alidat e appGroup
Refer to the IxChariot Script Development and Editing Guide for a the requirements for
valid application groups.

ARGUMENTS
appGroup
The handle for the target application group. The handle is returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Application group is invalid. (136)

See Return Code Summary for a detailed description of each return code.

- 887 -

IxChariot APIGuide

Common Error Command

The common error command is used to retrieve extended error information and the
IxChariot message number that applies to that information for tests, pairs, multicast pairs,
and multicast groups. This command has two subcommands.

- 888 -

IxChariot APIGuide

chrCommonError getInfo
DESCRIPTION
The chrCommonError getInfo subcommand retrieves the extended error information for
subcommand and test run errors.
The extended error information is only meaningful after subcommand errors for test,
pairs, multicast pairs, and multicast groups when the error is Operation failed, Object is
invalid, or Application Group is invalid.
Extended error information about test run errors is available for tests, for pairs contained
by a test, and for multicast pairs owned by a multicast group contained by a test. See
Extended Error Information.
The extended error information for subcommand errors is not retained and is cleared each
time a subcommand is invoked for pairs, multicast pairs, and multicast groups until the
object or its container is owned by a test. The extended error information for test run
errors for pairs and multicast pairs is retained and stored with the test when it is saved.
For test, pair, multicast pair and multicast group objects, the extended error information
from a subcommand or test run error is cleared when the next subcommand invoked for
the object.
c hrC ommonError get I nf o handle ?det ail?

ARGUMENTS
handle
l

For tests, the handle returned by chrTest new.

For pairs, the handle returned by chrPair new or chrTest getPair.

For multicast groups, handle chrMGroup new or chrTest getMGroup.

For multicast pairs, the handle returned by chrMPair new or chrMGroup getMPair.

detail
The detail level for the error information (optional). Refer to Extended Error Information
for available levels.

DETAIL LEVEL
NONE, PRIMARY, ADVANCED, ALL

RETURNED DATA
Detailed IxChariot error information for the subcommand or test run error. (Data type:
String).

ERROR RETURNS
l

Handle is invalid. (101).

Test is running. (106)

- 889 -

IxChariot APIGuide

API was not initialized. (113)

Value is invalid. (115)

No such value. (116)*

This return means that there is no extended error information available for the
given object.

See Return Code Summary for a detailed description of each code.

- 890 -

IxChariot APIGuide

chrCommonError getMsgNum
DESCRIPTION
The chrCommonError getMsgNum subcommand gets the IxChariot error message number
that applies to the extended error information for the given object.
c hrC ommonError get Ms gN um handle

ARGUMENTS
handle
l

For tests, the handle returned by chrTest new.

For pairs, the handle returned by chrPair new or chrTest getPair.

For multicast groups, the handle returned by chrMGroup new or chrTest getMGroup.

For multicast pairs, the handle returned by chrMPair new or chrMGroup getMPair.

RETURNED DATA
IxChariot message number for the extended error information for the subcommand or test
run error. (Data type: String). See the Messages and Application Scripts guide for more
information on messages.

ERROR RETURNS
l

Handle is invalid. (101).

Test is running. (106)

API was not initialized. (113)

No such value. (116)*

This return means that there is no extended error information available for the
given object.

See Return Code Summary for a detailed description of each return code.

- 891 -

IxChariot APIGuide

Common Results Extraction Command

The Common Results Extraction command is used to obtain test results that are common
across endpoint pairs, multicast pairs, and timing records for either pair type. This command has one subcommand.

- 892 -

IxChariot APIGuide

chrCommonResults get
DESCRIPTION
The chrCommonResults get subcommand gets the results of the given type from the given
pair, multicast pair, VoIP pair, video pair, video multicast group, hardware performance
pair, VoIP hardware performance pair, or timing record object.
c hrC ommonR es ult s get handle t y pe

ARGUMENTS
handle
l

For an endpoint pair, the handle returned by chrPair new

or chrTest getPair.
For a multicast pair, the handle returned by chrMPair new
or chrMGroup getMPair.
For a VoIP pair, the handle returned by chrVoIPPair new
or chrTest getPair.
For a video pair, the handle returned by chrVideoPair new
or chrTest getPair.
For a video multicast group, the handle returned by chrVideoMGroup new
or chrTest getMGroup.
For a VoIP hardware pair, the handle returned by
chrHardwareVoipPair new or chrTest getPair.
For a timing record, the handle returned by chrPair getTimingRecord
or chrMPair getTimingRecord.

type
The given type of results for an endpoint pair, multicast pair, or timing record object.

RETURNED DATA
These types of results are returned if the command is successful. Zero (0) is always
returned for results type BYTES_RECV_E1, DG_DUP_RECV_E1, DG_DUP_SENT_E1, DG_
DUP_SENT_E2 and DG_RECV_E1 for streaming tests.
Resu lts Ty pe

W h at I s Retu rn ed

Data Ty pe

A C K _ T O _F I N _ R X _ E 1

Total number of TCP ACK

packets r ecei ved by Endpoi nt
1 f r o m Endpo i nt2 i n
Long
r esponse to a F I N packet
sent by Endpoi nt 1

A C K _ T O _F I N _ T X _ E 2

Total number of TCP ACK

packets tr ansmi tted by Endpoi nt 1 i n r esponse to a F I N
sent by Endpoi nt 2.

Long

B Y T E S _ R E C V _E 1

Number of bytes r ecei ved by

E1

Long

- 893 -

IxChariot APIGuide

Resu lts Ty pe

W h at I s Retu rn ed

Data Ty pe

B Y T E S _ R E C V _E 2

Number of bytes r ecei ved by

E2

Long

B Y T E S _ S E N T _E 1

Number of bytes sent by E1

Long

C ON N _E S T A B L I S H E D _
E1

Total number of TCP connecti ons successf ul l y establ i shed by E1.

Long

D G _D U P _ R E C V _ E 1

Number of dupl i cate datagr ams r ecei ved by E1

Float

D G _D U P _ R E C V _ E 2

Number of dupl i cate datagr ams r ecei ved by E2

Float

D G _D U P _ S E N T _ E 1

Total number of dupl i cate

datagr ams sent by E1

Float

D G _D U P _ S E N T _ E 2

Total number of dupl i cate

datagr ams sent by E2

Float

D G _L O S T _ E 1 _E 2

Total number of datagr ams

l ost between E1 and E2

Float

D G _O U T _ O F _ O R D E R

Total number of datagr ams

r ecei ved out of or der by E2

Float

D G _R E C V _ E 1

Total number of datagr ams

r ecei ved by E1

Float

D G _R E C V _ E 2

Total number of datagr ams

r ecei ved by E1

Float

D G _S E N T _ E 1

Total number of datagr ams

sent by E1

Float

EST_CLOCK_ERROR

Esti mated cl ock synchr oni zati on er r or

Float

F I N _ R X _E 1

Total number of TCP F I Ns

r ecei ved by E1.

Long

F I N _ T X _E 1

Total number of TCP F I Ns

sent by E1

Long

J I T T E R _B U F F E R _
L OS T _D G

Number of j i tter buf f er l ost

datagrams

Long

J OI N _L A T E N C Y

The ti me between a r equest

to j oi n a mul ti cast gr oup and
the r ecei pt of the f i r st byte
Float
of data f r om that mul ti cast
gr oup.

LEAVE_LATENCY

The ti me between a r equest

to l eave a mul ti cast gr oup
and the r ecei pt of the l ast
byte of data f r om that mul ti cast gr oup

Float

MAX_CLOCK_ERROR

Maxi mum cl ock synchr oni zati on er r or

Float

M E A S _T I M E

Measur ed ti me i n seconds

Float

- 894 -

IxChariot APIGuide

Resu lts Ty pe

W h at I s Retu rn ed

Data Ty pe

R S T _ T X _E 1

Total number of TCP RESETs

sent by E1.

Long

R S T _ R X _E 1

Total number of TCP RESETs

r ecei ved by E1.

Long

RTD

Round-tr i p del ay val ue

Float

RTD_95PCT_
CONF I DENCE

95% conf i dence i nter val f or

r ound-tr i p del ay val ues

Float

S Y N _ F A I L E D _E 1

Total number of connecti on

attempts f or whi ch TCP r eset
the connecti on bef or e synLong
chr oni zati on was establ i shed.

S Y N _ R X _E 1

Total number of SYNs

r ecei ved by E1.
Thi s i ncl udes SYN/ACK packets.

S Y N _ T X _E 1

Total number of SYNs sent by

Long
E1.

TCP_RETRANS
M I S S I ON S _E 1

Total number of TCP r etr ansmi ssi ons that occur r ed on

Long
E1.

T C P _ T I M E OU T S _E 1

Total number of TCP

ti meouts that occur r ed on
E1.

Long

TRANS_COU NT

Tr ansacti on count

Long

Long

The following table describes the pair types and protocols for which these attributes are
available.
Regular Pair

P air Ty pe
P rotocol

A C K _ T O _F I N _
R X _E 1

TCP

RTP

UDP

VoI P
Pair

Video
Pair

RTP

RTP

- 895 -

HW
Perf
Pair
N/A

VoI P
HW
Perf
Pair
N/A

IxChariot APIGuide

Regular Pair

P air Ty pe
P rotocol

TCP

A C K _ T O _F I N _
T X _E 1

BYTES_RECV_
E1

BYTES_RECV_
E2
BYTES_SENT_
E1
CONN_
ESTABLI SHED_
E1

RTP

UDP

Video
Pair

RTP

RTP

N/A

D G _D U P _
R E C V _E 1

D G _D U P _
R E C V _E 2

D G _D U P _
S E N T _E 1

D G _D U P _
S E N T _E 2

D G _L O S T _ E 1 _
E2

D G _O U T _ O F _
ORDER

D G _R E C V _ E 1

D G _R E C V _ E 2

D G _S E N T _ E 1

EST_CLOCK_
ERROR

F I N_ACK_RX_
E1

F I N_ACK_TX_
E1

F I N _ R X _E 1

F I N _ T X _E 1

JI TTER_
BU F F ER_
L OS T _D G

HW
Perf
Pair

VoI P
HW
Perf
Pair
N/A

x
x

VoI P
Pair

- 896 -

IxChariot APIGuide

Regular Pair

P air Ty pe
P rotocol

TCP

VoI P
Pair

Video
Pair
RTP

RTP

UDP

RTP

HW
Perf
Pair
N/A

VoI P
HW
Perf
Pair
N/A

MAX_CLOCK_
ERROR
M E A S _T I M E

R S T _ R X _E 1

R S T _ T X _E 1

RTD

RTD_95PCT_
CONF I DENCE

SYN_F AI LED_
E1

S Y N _ R X _E 1

S Y N _ T X _E 1

TCP_RETRANS
M I S S I ON S _E 1

TCP_
T I M E OU T S _E 1

TRANS_COU NT

ERROR RETURNS
l

Handle is invalid. (101)

Test was not run. (105)

API was not initialized. (113)

Results are not available. (114)

No such value. (116)*

Out of memory. (120)

Program internal error. (121)

No such value is always returned for DG_DUP_RECV_E2, DG_DUP_SENT_E1,
DG_DUP_SENT_E2, DG_ RECV_E1 for streaming tests and for DG_OUT_OF_
ORDER for non-streaming tests and is not indicative of an error for these result
types.

See Return Code Summary for a detailed description of each return code.

- 897 -

IxChariot APIGuide

Datagram Options Object Command

The datagram options object command is used to define and retrieve information about the
datagram options for a specific test. This command has two subcommands.

- 898 -

IxChariot APIGuide

chrDgOpts get
DESCRIPTION
The chrDgOpts get subcommand gets the value for the attribute specified by name from
the given datagram options object.
c hrD gOpt s get dgopt s name

ARGUMENTS
dgopts
The handle returned by chrTest getDgOpts.

name
The attribute to get.

RETURNED DATA
Attribu te Nam e

W h at I s Retu rn ed

Data Ty pe

D A T A _R A T E _ L I M I T

An i nteger val ue i n the 100 Long

200 r ange

L I M I T _ D A T A _R A T E

A Bool ean val ue: 1 i f tr ue, 0

if false

Boolean

L OW _ S E N D E R _J I T T E R

A Bool ean val ue: 1 i f tr ue, 0

if false

Boolean

M E A S U R E D _I N T E R V A L

An i nteger val ue i n the 1 999999 r ange

Long

R E C V _T I M E OU T

Mul ti cast datagr am r ecei ve

ti meout i n mi l l i seconds

Long

RETRANS_COU NT

Datagr am r etr ansmi ssi on

count

Long

RETRANS_TI MEOU T

Datagr am r etr ansmi ssi on

ti meout i n mi l l i seconds

Long

If the RTP datagram includes an extension header, it is 1. If the RTP datagram

does not include an extension header, it
is 0.

RTP_U SE_EXT_HDR

When 1, the RTP ti mestamp

f i el d contai ns a monotonous
ti mestamp val ue, whi l e the
Boolean
header extensi on contai ns a
ti me val ue der i ved f r om the
system cl ock. When 0, the
RTP datagr am does not
i ncl ude an extensi on header .
I n thi s case, the RTP
ti mestamp f i el d contai ns a

- 899 -

IxChariot APIGuide

Attribu te Nam e

W h at I s Retu rn ed

Data Ty pe

ti me val ue der i ved f r om the

system clock.

TTL

Mul ti cast datagr am ti me to

l i ve hops count

Long

W I N D OW _S I Z E

Datagr am wi ndow si ze i n
bytes

Long

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 900 -

IxChariot APIGuide

chrDgOpts set
DESCRIPTION
The chrDgOpts set subcommand sets the value for the attribute specified by name in the
given datagram options object. You are not allowed to set any of the datagram options for
a test that has results.
c hrD gOpt s s et dgopt s name v alue

ARGUMENTS
dgopts
The handle returned by chrTest getDgOpts.

name
The attribute to set.

value
The value to set for the given attribute.

ATTRIBUTES
Attribu te Nam e

What Is Set

Ran ge/Max
S trin g
L en gth

D A T A _R A T E _ L I M I T

The data r ate l i mi t f or al l the

str eami ng pai r s i n the test. The
data rate limit is expressed as a
per cent of the r equi r ed data r ate
100 to 200
def i ned i n the scr i pt. F or exampl e,
a val ue of 100 means that the
l i mi t i s equal to 100% of the
r equi r ed data r ate.

L I M I T _ D A T A _R A T E

The data r ate l i mi t f l ag f or al l the

str eami ng pai r s i n the test. Thi s
1 if TRUE
f l ag i s used to enabl e a data r ate
(thr oughput) l i mi t measur ed on
0 if FALSE
i nter val s much smal l er than a ti mi ng r ecor d i nter val .

LOW_SENDER_
JI TTER

The l ow sender j i tter f l ag f or al l

the str eami ng pai r s i n the test.
Thi s f l ag i s used to enabl e ver y
pr eci se ti mer s to r educe the j i tter
on the sender . When the f l ag i s
enabl ed, datagr ams ar e sent at
mor e pr eci se i nter val s.

MEASU RED_
I NTERVAL

The measur ed i nter val f or al l the

1 to
str eami ng pai r s i n the test. Thi s i s 999999

- 901 -

1 if TRUE
0 if FALSE

IxChariot APIGuide

Attribu te Nam e

What Is Set

Ran ge/Max
S trin g
L en gth

the i nter val (i n mi l l i seconds) over

whi ch I xChar i ot enf or ces the data
rate limit.
R E C V _T I M E OU T

Mul ti cast datagr am r ecei ve

ti meout i n mi l l i seconds

1 to
999999

RETRANS_COU NT

Datagr am r etr ansmi ssi on count

1 to 999

RTP_U SE_EXT_
HDR

Opti on to use an RTP ex tensi on

header . When 1, the RTP
ti mestamp f i el d contai ns a monotonous ti mestamp val ue, whi l e the
header extensi on contai ns a ti me
val ue der i ved f r om the system
cl ock. When 0, the RTP datagr am
does not i ncl ude an extensi on
header . I n thi s case, the RTP
ti mestamp f i el d contai ns a ti me
val ue der i ved f r om the system
clock.

1, 0

TTL

Mul ti cast datagr am ti me to l i ve

hop count

0 to 255

W I N D OW _S I Z E

Datagr am wi ndow si ze i n bytes

1 to
9999999

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

Test is running. (106)

Results were not cleared. (110)

API was not initialized. (113)

Value is invalid. (115)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 902 -

IxChariot APIGuide

Hop Record Object Command

The hop record object command is used to obtain hop-by-hop information for a traceroute
pair. This command has one subcommand.

- 903 -

IxChariot APIGuide

chrHopRec get
DESCRIPTION
The chrHopRec get subcommand gets the results of the given type from the given
traceroute.
c hrH opR ec get hrec ord t y pe

ARGUMENTS
hrecord
The handle returned by chrTracertPair getHopRecord.

type
The type of results to return.

RETURNED DATA
Resu lts Ty pe

W h at I s Retu rn ed

Data
Ty pe

HOP_ADDR

Addr ess of thi s hop

Str i ng

HOP_LATENCY

Latency of thi s hop

Long

HOP_NAME

Resol ved name f or thi s hop

Str i ng

HOP_NU MBER

Hop number

Long

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

No such value.* (116)

Out of memory. (120)

Program internal error. (121)

No such value may be returned for certain hop record results for some tests and
is not indicative of an error for these results types.

See Return Code Summary for a detailed description of each return code.

- 904 -

IxChariot APIGuide

IPTV Channel Object Commands

The channel object commands are used to define and retrieve information for IPTV channels. A channel object must be contained by a test object. The testing parameters available for a channel object include the channel name, test network parameters,
management network parameters, and IPTV traffic characteristics.
A related set of commands is provided for IPTV receiver objects and IPTV VPair objects.

- 905 -

IxChariot APIGuide

chrChannel delete
DESCRIPTION
The chrChannel delete command frees all memory associated with the given channel
object. This is necessary because the Tcl interpreter has no access to the associated structures supporting the object. A channel cannot be deleted if it is owned by a test.
c hrC hannel delet e c hannel

ARGUMENTS
channel
The handle returned by chrChannel new, chrTest getChannel, or
chrTestgetChannelByName.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 906 -

IxChariot APIGuide

chrChannel get
DESCRIPTION
The chrChannel get subcommand gets the value for the named attribute of the given
channel.
c hrC hannel get c hannel name

ARGUMENTS
channel
The handle returned by chrChannel new, chrTest getChannel, or
chrTestgetChannelByName.

name
The attribute to get.

NAMES
Attribu te Nam e

W h at I s Retu rn ed

Data
Ty pe

BITRATE

The bi t r ate of the I PTV channel

stream.

BI TRATE_U NI T_
O F _M E A S U R E M E N T

The uni t of measur ement f or the channel str eam data r ate. (Thi s i s the uni t
Str i ng
of measur ement i n whi ch the tr ansmission rate is expressed.)

CODEC

The codec type def i ned f or the speci f i ed I PTV channel obj ect.

COMMENT

A str i ng contai ni ng any ar bi tr ar y textual comment f or the channel obj ect. Str i ng
Maxi mum 64 bytes.

Float

Str i ng

The si ze of the socket connecti on buf C ON N _S E N D _ B U F F _ f e r t h a t t h i s c h a n n e l u s e s f o r s e n d

I nteger
SIZE
o pe r a ti o ns . V a l ue s a r e be tw e e n 0
2147483646 or DEF AU LT.
C O N S O L E _ E 1 _A D D R T h e I P a d d r e s s o f E n d p o i n t 1 o n t h e
management networ k.

Str i ng

CONSOLE_E1_
PROTOCOL

The networ k pr otocol that the consol e

wi l l use when connecti ng to
Str i ng
Endpo i nt1 to pe r f o r m I P TV pa i r
setup.

E 1 _A D D R

The I P addr ess of Endpoi nt 1 on the

test networ k. The channel uses thi s
as the sour ce I P addr ess of the mul ticast.

F R A M E S _P E R _

The number of medi a f r ames per data- I nteger

- 907 -

Str i ng

IxChariot APIGuide

Attribu te Nam e

DATAGRAM

W h at I s Retu rn ed

Data
Ty pe

gr am def i ned f or the speci f i ed I PTV

channel
A Boolean value that specifies whether or not the
channel object is locked:

LOCK
l

TRUE: The channel object is locked.

FALSE: The channel object is unlocked.

Boolean

MEDI A_F RAME_

SIZE

The medi a f r ame si ze def i ned f or the

gi ven I PTV channel .

MU LTI CAST_ADDR

The mul ti cast I P addr ess of the gi ven

Str i ng
I PTV channel .

MU LTI CAST_PORT

The mul ti cast por t number of the

gi ven I PTV channel .

Long

NAME

The name assi gned to the speci f i ed

I PTV channel .

Str i ng

PROTOCOL

The test networ k pr otocol of the speci f i ed I PTV channel .

Str i ng

QOS_NAME

The qual i ty -of -s e r v i c e te m pl ate nam e

Str i ng
f or the speci f i ed I PTV channel .

I nteger

The RTP payload type for the given channel object.

RTP_PAYLOAD_
TYPE
S OU R C E _P OR T _
NU MBER

This is valid only for custom codec and

RTP/RTP6 protocol.
The U DP sour ce por t number f or the
speci f i ed I PTV channel .

I nteger

Long

Indicates whether the console will use the management network or the test network to perform
pair setup:
U SE_CONSOLE_E1

If TRUE, the console will use the management

network to perform pair setup.
If FALSE, the will use the test network to perform pair setup.

ERROR RETURNS
l

Handle is invalid. (101)

Pointer is invalid. (103)

API was not initialized. (113)

Buffer is too small. (119)

Out of memory. (120)

Program internal error. (121)

Not licensed. (126)

License has expired. (128)

- 908 -

Boolean

IxChariot APIGuide
See Return Code Summary for a detailed description of each return code.

- 909 -

IxChariot APIGuide

chrChannel new
DESCRIPTION
The chrChannel new command creates a new IPTV channel object and initializes it to the
default values.
c hrC hannel new

ARGUMENTS
None

RETURNED DATA
The returned data provides the handle to an initialized channel object. The handle returned
by this subcommand is needed for other subcommands to operate on the object.

ERROR RETURNS
l

Pointer is invalid. (103)

Out of memory. (120)

Not licensed. (126)

License has expired. (128)

Duplicate channel name. (140)

See Return Code Summary for a detailed description of each return code.

- 910 -

IxChariot APIGuide

chrChannel set
DESCRIPTION
The chrChannel set subcommand sets or changes the value for the attributes specified
by name for the given pair.
c hrC hannel s et c hannel name v alue . . .
Multiple pairs of name/value can be set with the same command.

ARGUMENTS
channel
The handle returned by chrChannel new, chrTest getChannel, or
chrTestgetChannelByName.

name
The attribute to set.

value
The attribute value.

ATTRIBUTES
Attribu te
Name

BITRATE

What Is Set

The bi t r ate of the I PTV

channel str eam.

Ran ge/Max
S trin g L en gth

1 - 999, 999

Data
Ty pe

Float

"UNIT_kb",
The uni t of measur ement
BI TRATE_
f or the channel str eam
U N I T _OF _
data r ate. (Thi s i s the
MEASU REMENT uni t of measur ement i n
whi ch the tr ansmi ssi on
rate is expressed.)

"UNIT_Kb",
"UNIT_kB",
"UNIT_KB",

Str i ng

"UNIT_Mb",
"UNIT_Gb

CODEC

The codec type def i ned

f or the speci f i ed I PTV
channel obj ect.

"MPEG2",
"CU STOM"

Str i ng

COMMENT

A str i ng contai ni ng any

ar bi tr ar y textual comment f or the channel
obj ect. Maxi mum 64
bytes.

64 char acter s.

Str i ng

C ON N _S E N D _
B U F F _S I Z E

The desired size of the socket con- Range between 0

nection buffer that this channel
2147483646 or

- 911 -

I nteger

IxChariot APIGuide

Attribu te
Name

What Is Set

Ran ge/Max
S trin g L en gth

Data
Ty pe

DEFAULT.
should use for sending IPTV data
streams.
If the endpoint.ini file
specifies the send buffer
size (using the SOCKET_
SEND_BUFFER_SIZE
keyword), that value
overrides the value specified by this Tcl attribute.

The I P addr ess of EndCONSOLE_E1_

poi nt 1 on the manADDR
agement networ k.

The maximum value

is determined by the
operating
system on
which the
Performance
Endpoint is
running.

64 char acter s

The networ k pr otocol that

One of the following:
the consol e wi l l use when
CONSOLE_E1_
c o nne c ti ng to Endpo i nt1
l
SPX
PROTOCOL
to perform I PTV pair
l
TCP
setup.

E 1 _A D D R

The I P addr ess of Endpoi nt 1 on the test networ k. The channel uses
thi s as the sour ce I P
addr ess of the mul ti cast.

The number of medi a

F R A M E S _P E R _ f r a m e s p e r d a t a g r a m
DATAGRAM
def i ned f or the speci f i ed
I PTV channel .

64 char acter s

Str i ng

Str i ng

Str i ng

Al l i nteger val ues gr eater than I nteger

zero are valid.
One of the following:

LOCK

TRUE: Lock the chanLocks or unl ocks the channel object.

Boolean
nel obj ect.
FALSE: Unlocks the
channel object.

MEDI A_
F RAME_SI ZE

The medi a f r ame si ze

def i ned f or the gi ven
I PTV channel .

Al l i nteger val ues gr eater than I nteger

zero are valid.

MU LTI CAST_
ADDR

The mul ti cast I P addr ess

of the gi ven I PTV channel .

15 char acter s;
i n the r ange
Str i ng
224. 0. 0. 0 to
239. 255. 255. 255

MU LTI CAST_
PORT

The mul ti cast por t number of the gi ven I PTV

channel .

1 to 65535

- 912 -

Long

IxChariot APIGuide

Attribu te
Name

What Is Set

Ran ge/Max
S trin g L en gth

NAME

The name assi gned to the

64 char acter s
speci f i ed I PTV channel .

PROTOCOL

The test networ k pr otocol

of the speci f i ed I PTV
channel .

QOS_NAME

RTP_
PAYLOAD_
TYPE

The qual i ty-of - ser vi ce

templ ate name f or the
speci f i ed I PTV channel .
The RTP payload type for the given
channel object.

Data
Ty pe

Str i ng

One of the following:

l

UDP

RTP

Str i ng

64 char acter s

Str i ng

0-127
Only valid
for custom I n t e g e r
codec and
RTP/RTP6
protocol.

This is valid only for custom codec and

RTP/RTP6 protocol.

SOU RCE_
The U DP sour ce por t numP OR T _N U M B E R b e r f o r t h e s p e c i f i e d I P T V 0 ( a u t o ) - 6 5 5 3 5
channel .

Long

Indicates whether the console will

use the management network or
the test network to perform pair
setup:
U SE_
CONSOLE_E1

If TRUE, the console will use

the management network to
perform pair setup.

0=FALSE
Boolean
1=TRUE

If FALSE, the console will use

the test network to perform
pair setup

ERROR RETURNS
l

Handle is invalid. (101)

Pointer is invalid. (103)

Test is running. (106)

Object in use. (107)

Results not cleared. (110)

Program internal error. (121)

Not supported. (124)

See Return Code Summary for a detailed description of each return code.

- 913 -

IxChariot APIGuide

IPTV Pair Object Command

The IPTV pair object command is used to define IPTV pairs (vpairs) for a test and retrieve
information about an endpoint vpair.
A related set of commands is provided for IPTV channel objects and IPTV receiver objects.

- 914 -

IxChariot APIGuide

chrVPair delete
DESCRIPTION
The chrVPair delete command frees all memory associated with the given IPTV pair
object. This is necessary because the Tcl interpreter has no access to the associated structures supporting the object. A VPair object cannot be deleted if it is owned by a test.
c hrVPair delet e v pair

ARGUMENTS
vpair
The handle returned by chrVPair new or chrReceivergetVPair.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 915 -

IxChariot APIGuide

chrVPair get
DESCRIPTION
The chrVPair get subcommand gets the value for the named attribute of the given VPair.
c hrVPair get v pair name

ARGUMENTS
vpair
The handle returned by chrVPair new or chrReceivergetVPair.

name
The attribute to get.

RETURNED DATA
Attribu te Nam e

CHANNEL

W h at I s Retu rn ed

Data
Ty pe

The handl e of the channel obj ect wi th

I nteger
whi ch the pai r i s associ ated.
A Boolean value that specifies whether or not the
IPTV pair object is locked:

LOCK

N O _O F _ T I M I N G _
RECORDS

TRUE: The pair object is locked.

FALSE: The pair object is unlocked.

Boolean

The number of ti mi ng r ecor ds that the

pai r has been conf i gur ed to cr eate
I nteger
dur i ng the executi on of a test.
Status of an IPTV pair during a test run.
The list of run status strings is as follows:

RUNSTATUS

uninitialized

initializing 1

initializing 2

initializing 3

initialized

running

stopping

requested stop

error

resolving names

polling

finished

requesting stop

finished with warning

Str i ng

- 916 -

IxChariot APIGuide

Attribu te Nam e

T I M I N G _R E C OR D _
DU RATI ON

W h at I s Retu rn ed
l

transferring payload

applying Ixia config

waiting for reinit

abandoned

The ti mi ng r ecor d dur ati on, i n

seconds

ERROR RETURNS
l

Handle is invalid. (101)

Pointer is invalid. (103)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 917 -

Data
Ty pe

I nteger

IxChariot APIGuide

chrVPair getReport
DESCRIPTION
The chrVPair getReport command gets the specified report for this IPTV pair.
c hrVPair get R eport v pair report index

ARGUMENTS
vpair
The handle returned by chrVPair new or chrReceivergetVPair.

reportindex
Index of the requested report (zero-based).

RETURNED DATA
The handle of the requested report.

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 918 -

IxChariot APIGuide

chrVPair getReportCount
DESCRIPTION
The chrVPair getReportCount command returns the number of reports collected for this
IPTV pair.
c hrVPair get R eport C ount v pair

ARGUMENTS
vpair
The handle returned by chrVPair new or chrReceivergetVPair..

RETURNED DATA
A count of the number of reports collected for this IPTV pair.

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 919 -

IxChariot APIGuide

chrVPair getTimingRecord
DESCRIPTION
The chrVPair getTimingRecord command returns the specified timing record for this
IPTV pair.
c hrVPair get TimingR ec ord v pair rec ordindex

ARGUMENTS
vpair
The handle returned by chrVPair new or chrReceivergetVPair.

recordindex
The index of the requested timing record.

RETURNED DATA
The handle of the specified timing record.

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 920 -

IxChariot APIGuide

chrVPair getTimingRecordCount
DESCRIPTION
The chrVPair getTimingRecordCount command returns the number of timing records
collected for this IPTV pair.
c hrVPair get TimingR ec ordC ount v pair

ARGUMENTS
vpair
The handle returned by chrVPair new or chrReceivergetVPair.

RETURNED DATA
A count of the number of timing records collected for this IPTV pair.

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 921 -

IxChariot APIGuide

chrVPair new
DESCRIPTION
The chrVPair new command creates a new IPTV pair object and initializes it to the default
values.
c hrVPair new

ARGUMENTS
None

RETURNED DATA
The returned data provides the handle to an initialized VPair object. The handle returned
by this subcommand is needed for other subcommands to operate on the object.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Not licensed. (126)

License has expired. (128)

See Return Code Summary for a detailed description of each return code.

- 922 -

IxChariot APIGuide

chrVPair set
DESCRIPTION
The chrVPair set subcommand sets or changes the value for the named attributes of
the given IPTV pair.
c hrVPair s et v pair name v alue . . .
Note: Multiple pairs of name/value can be set with the same command.

ARGUMENTS
vpair
The handle returned by chrVPair new or chrReceivergetVPair.

name
The attribute to set.

value
The attribute value.

ATTRIBUTES
Attribu te
Name

CHANNEL

What Is Set

Ran ge/Max S trin g

L en gth

The handl e of the channel Al l i nteger val obj ect wi th whi ch thi s
ues gr eater than
pair is associated.
zero are valid

Data
Ty pe

I nteger

One of the following:

Locks or unl ocks the I PTV
pair obj ect.

TRUE: Lock the

pair object.

Boolean

FALSE: Unlock the

pair object.

N O _O F _
TI MI NG_
RECORDS

The number of ti mi ng
r ecor ds that the pai r has Al l i nteger val been conf i gur ed to cr eate ues gr eater than
dur i ng the executi on of a zer o ar e val i d.
test.

I nteger

TI MI NG_
RECORD_
DU RATI ON

The ti mi ng r ecor d dur ati on, i n seconds.

Al l i nteger val ues gr eater than

zero are valid.

I nteger

ERROR RETURNS
l

Handle is invalid. (101)

Object in use. (107)

- 923 -

IxChariot APIGuide

API was not initialized. (113)

Value is invalid. (115)

Out of memory. (120)

Program internal error. (121)

Duplicate channel name. (140)

See Return Code Summary for a detailed description of each return code.

- 924 -

IxChariot APIGuide

IPTV Receiver Object Commands

The IPTV receiver object functions are used to configure receiver group objects. Receiver
groups are the subscribers to the IPTV channels. Each channel is represented by a test pair
within a receiver group.
A related set of commands is provided for IPTV channel objects and IPTV VPair objects.

- 925 -

IxChariot APIGuide

chrReceiver addVPair
DESCRIPTION
The chrReceiver addVPair command adds an IPTV pair to the list for the designated
receiver.
c hrR ec eiv er addVPair rec eiv er v pair

ARGUMENTS
receiver
The handle returned by chrReceiver new, chrTest getReceiver, or chrTestgetReceiver
ByName.

vpair
The handle returned by chrVPair new.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 926 -

IxChariot APIGuide

chrReceiver delete
DESCRIPTION
The chrReceiver delete command frees all memory associated with the given receiver
object. This is necessary because the Tcl interpreter has no access to the associated structures supporting the object. A receiver object cannot be deleted if it is owned by a test.
c hrR ec eiv er delet e rec eiv er

ARGUMENTS
receiver
The handle returned by chrReceiver new, chrTest getReceiver, or chrTestgetReceiver
ByName.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 927 -

IxChariot APIGuide

chrReceiver get
DESCRIPTION
The chrReceiver get subcommand gets the value for the named attribute of the given
receiver.
c hrR ec eiv er get rec eiv er name

ARGUMENTS
receiver
The handle returned by chrReceiver new, chrTest getReceiver, or
chrTestgetReceiverByName.

name
The attribute to get.

NAMES
Attribu te Nam e

COMMENT

W h at I s Retu rn ed

A str i ng contai ni ng an ar bi tr ar y textual comment f or the r ecei ver gr oup

obj ect.

Data
Ty pe

Str i ng

The si ze of the socket connecti on buf C ON N _R E C V _ B U F F _ f e r t h a t t h i s r e c e i v e r u s e s f o r r e c e i v I nteger

SIZE
i ng I PTV data str eams. Val ues ar e
b e t w e e n 0 2
147483646 or DEF AU LT.
E 2 _A D D R

The networ k addr ess of the

Endpo i nt2 c o m pute r o r po r t.

Str i ng

A Boolean value that indicates whether the pairs in

the receiver object are disabled:
I S _D I S A B L E D

TRUE: All the pairs in the receiver object are

disabled.

Boolean

FALSE: The receiver object is unlocked.

A Boolean value that indicates whether or not the

receiver object is locked:
LOCK
l

TRUE: The receiver object is locked.

FALSE: The receiver object is unlocked.

Boolean

NAME

The name assi gned to the speci f i ed

r ecei ver gr oup.

N O _O F _
I TERATI ONS

The number of ti mes the r ecei ver wi l l

swi tch channel s (l eave one channel
I nteger
and j oi n another ).

S E T U P _ E 1 _E 2 _
ADDR

Addr ess at whi ch Endpoi nt 1 knows

Endpoi nt 2 f or setup.

- 928 -

Str i ng

Str i ng

IxChariot APIGuide

Attribu te Nam e

S E T U P _ E 1 _E 2 _
ADDR

W h at I s Retu rn ed

The number of mi l l i seconds that wi l l

el apse between l eavi ng one channel
and j oi ni ng another .

Data
Ty pe

I nteger

Indicates whether the console will use the management network or the test network to perform
pair setup:
U S E _ E 1 _E 2

If TRUE, the console will use the management

network to perform pair setup.
If FALSE, the console will use the test network
to perform pair setup.

ERROR RETURNS
l

Handle is invalid. (101)

Pointer is invalid. (103)

Object is in use. (107)

API was not initialized. (113)

Buffer is too small. (119)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 929 -

Boolean

IxChariot APIGuide

chrReceiver getVPair
DESCRIPTION
The chrReceiver getVPair command returns the specified IPTV pair object from the list
of pairs assigned to this receiver.
c hrR ec eiv er get VPair rec eiv er pairindex

ARGUMENTS
receiver
The handle returned by chrReceiver new, chrTest getReceiver, or chrTestgetReceiver
ByName.

pairindex
The Index of the desired entry in the pair list, in the following range:
0. . pair_c ount -1

RETURNED DATA
The handle of the selected IPTV pair object.

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 930 -

IxChariot APIGuide

chrReceiver getVPairCount
DESCRIPTION
The chrReceiver getVPairCount command returns the number of pairs that have been
assigned to this receiver.
c hrR ec eiv er get VPairC ount rec eiv er

ARGUMENTS
receiver
The handle returned by chrReceiver new, chrTest getReceiver, or chrTestgetReceiver
ByName.

RETURNED DATA
The count of pairs that have been assigned to this receiver.

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 931 -

IxChariot APIGuide

chrReceiver new
DESCRIPTION
The chrReceiver new command creates a new IPTV receiver group object and initializes
it to the default values.
c hrR ec eiv er new

ARGUMENTS
None

RETURNED DATA
The returned data provides the handle to an initialized receiver object. The handle
returned by this subcommand is needed for other subcommands to operate on the object.

ERROR RETURNS
l

Pointer is invalid. (103)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Not licensed. (126)

License has expired. (128)

See Return Code Summary for a detailed description of each return code.

- 932 -

IxChariot APIGuide

chrReceiver removeVPair
DESCRIPTION
The chrReceiver removeVPair command removes an IPTV pair from the list for the designated receiver.
c hrR ec eiv er remov eVPair rec eiv er v pair
To use this function, the receiver object must be either unowned or locked.

ARGUMENTS
receiver
The handle returned by chrReceiver new, chrTest getReceiver, or chrTestgetReceiver
ByName.

vpair
The handle returned by chrVPair new.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

No such object. (104)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 933 -

IxChariot APIGuide

chrReceiver set
DESCRIPTION
The chrReceiver set subcommand sets or changes the value for the named attributes of
the given receiver.
c hrR ec eiv er s et rec eiv er name v alue . . .
Multiple pairs of name/value can be set with the same command.

ARGUMENTS
receiver
The handle returned by chrReceiver new, chrTest getReceiver, or
chrTestgetReceiverByName.

name
The attribute to set.

value
The attribute value.

ATTRIBUTES
Attribu te
Name

COMMENT

What Is Set

A str i ng contai ni ng any

ar bi tr ar y textual comment f or the r ecei ver
gr oup obj ect. Maxi mum
64 bytes.

Ran ge/Max S trin g

L en gth

64 char acter s

Data
Ty pe

Str i ng

Range is between 0
The desired size of the socket con- 2147483646 or
nection buffer that this receiver
DEFAULT.
should use for receiving IPTV data
The maxstreams.
imum value
If the endpoint.ini file
is determspecifies
the
receive
ined by the
C ON N _R E C V _
I nteger
buffer size (using the
operating sysB U F F _S I Z E
SOCKET_RECEIVE_
tem on which
BUFFER_SIZE
the Perkeyword), that value
formance
overrides the value speEndpoint is
cified by this Tcl attribrunning.
ute.

DI SABLE

Di sabl es or enabl es al l
the pai r s i n the r ecei ver

- 934 -

One of the following:

Boolean

IxChariot APIGuide

Attribu te
Name

What Is Set

Ran ge/Max S trin g

L en gth
l

obj ect.

E 2 _A D D R

The networ k addr ess of

the Endpo i nt2 c o m pute r
or port.

Data
Ty pe

TRUE: Disable all

the pairs in the
receiver object.
FALSE: Enable all
the pairs in the
receiver object.

Endpoi nt 2
address

Str i ng

One of the following:

LOCK

Locks or unl ocks the

receiver

TRUE: Lock the

receiver object

Boolean

FALSE: Unlock the

receiver object

NAME

The name assi gned to the

64 char acter s
speci f i ed r ecei ver gr oup.

N O _O F _
I TERATI ONS

The number of ti mes the

Al l i nteger val ues
r ecei ver wi l l swi tch changr eater than zer o I nteger
nel s (l eave one channel
are valid
and j oi n another )

SETU P_E1_
E 2 _A D D R

Addr ess at whi ch Endpoi nt 1 knows Endpoi nt 2

f o r s e t u p . ( S E T U P _E 1 _
E2_ADDR i s onl y used
w h e n U S E _ S E T U P _ E 1 _E 2
i s set to Tr ue (1). )

SWI TCH_
DELAY

The number of mi l l i seconds that wi l l el apse Al l i nteger val ues

between l eavi ng one
gr eater than zer o I nteger
channel and j oi ni ng
arevalid.
another .

Str i ng

Addr ess at whi ch

Endpoi nt 1 knows
Str i ng
Endpoi nt 2 f or
setup

Indicates whether the console will

use the management network or
the test network to perform pair
setup:
U S E _ E 1 _E 2

If TRUE, the console will use

the management network to
perform pair setup.
If FALSE, the console will use
the test network to perform
pair setup

- 935 -

0= False
Boolean
1=True

IxChariot APIGuide

ERROR RETURNS
l

Handle is invalid. (101)

Pointer is invalid. (103)

Object in use. (107)

API was not initialized. (113)

Value is invalid. (115)

Out of memory. (120)

Program internal error. (121)

Duplicate receiver name. (141)

See Return Code Summary for a detailed description of each return code.

- 936 -

IxChariot APIGuide

Multicast Group Object Command

The multicast group object command is used to define and retrieve information about a
multicast group. A separate command, called multicast pairs (mpairs), defines and
retrieves information about multicast group members. This command has eleven subcommands.

- 937 -

IxChariot APIGuide

chrMGroup addMPair
DESCRIPTION
The chrMGroup addMPair subcommand adds the given multicast pair to the given multicast
group. You are not allowed to add mpairs to a multicast group that is owned by a test. The
multicast pair handle is checked to ensure that it refers to a properly defined multicast pair
before it is added to the multicast group. A multicast pair handle can only be added to one
multicast group, and can only be added once to that multicast group. Extended error
information is available for this subcommand.
c hrMGroup addMPair mgroup mpair

ARGUMENTS
mgroup
The handle returned by chrMGroup new or chrTest getMGroup.

mpair
The handle returned by chrMPair new.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

Pair limit would be exceeded. (111)

Object is invalid. (112)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 938 -

IxChariot APIGuide

chrMGroup copy
DESCRIPTION
The chrMGroup copy subcommand copies the attributes of the source multicast group to
the destination multicast group. This does not include any results information.
c hrMGroup c opy des t s rc

ARGUMENTS
dest
The handle for the destination returned by chrMGroup new.

src
The handle for the source, returned by chrMGroup new or chrTest getMGroup.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 939 -

IxChariot APIGuide

chrMGroup delete
DESCRIPTION
The chrMGroup delete subcommand frees all memory associated with the given multicast
group object. This is necessary because the Tcl interpreter has no access to the associated
structures supporting the object. An mgroup cannot be deleted if it is owned by a test.
c hrMGroup delet e mgroup

ARGUMENTS
mgroup
The handle returned by chrMGroup new.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 940 -

IxChariot APIGuide

chrMGroup get
DESCRIPTION
The chrMGroup get subcommand gets the value for the attribute specified by name from
the given multicast group.
c hrMGroup get mgroup name

ARGUMENTS
mgroup
The handle returned by chrMGroup new, chrVideoMGroup new, or chrTestgetMGroup.

name
The attribute to get.

RETURNED DATA
Attribu te Nam e

W h at I s Retu rn ed

Data Ty pe

APPL_SCRIPT_NAME

Application script name.

String

COMMENT

Multicast group comment.

String

CONSOLE_E1_ADDR

Addr ess by whi ch Consol e

k nows Endpoi nt 1. CONSOLE_
E 1 _A D D R o n l y a p p l i e s w h e n
U SE_CONSOLE_E1 i s set Tr ue.

String

CONSOLE_E1_
PROTOCOL

Console to Endpoint 1 protocol.

CONSOLE_E1_PROTOCOL only applies
when USE_CONSOLE_E1 is set to True
(1).

String

CONSOLE_E1_QOS

Consol e to Endpoi nt 1 qual i ty

of ser v i ce name. CONSOLE_
E 1 _Q O S o n l y a p p l i e s w h e n
U SE_CONSOLE_E1 i s set to
Tr ue (1).

String

Note: Thi s attr i bute i s appl i cabl e onl y to APPC.

I x Cha r i o t6. 20 a nd hi ghe r no
l onger suppor t APPC.
E1_ADDR

Endpoint 1 address.

String

IS_DISABLED 1

TRUE if the pairs in the group are disabled

for the test.

Boolean

MULTICAST_ADDR

Multicast IP address.

String

- 941 -

IxChariot APIGuide

Attribu te Nam e

W h at I s Retu rn ed

Data Ty pe

MULTICAST_PORT

Multicast IP port number.

Long

NAME

Multicast group name.

String

PROTOCOL

Endpoint 1 to Endpoint 2 protocol.

String

QOS_NAME

Endpoint 1 to Endpoint 2 quality of service

name.

String

SCRIPT_FILENAME

Script filename.

String

USE_CONSOLE_E1

Whether to use the Console to Endpoint 1

values.

Boolean

USE_UDP_RFC768

Whether the streaming script sets the

option to use RFC768 UDP.

Boolean

1T h i s f u n c t i o n i s a l s o v a l i d f o r v i d e o m u l t i c a s t g r o u p s .

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 942 -

IxChariot APIGuide

chrMGroup getEndpointConfig
DESCRIPTION
The chrMGroup getEndpointConfig subcommand gets the value for endpoint configuration
parameters for Endpoint 1 for the given multicast group.
c hrMGroup get Endpoint C onf ig mgroup name

ARGUMENTS
mgroup
The handle returned by chrMGroup new or chrTest getMGroup

name
The endpoint configuration parameter to get

RETURNED DATA
Parameter Name

What is Returned

Data
Type

BUILD_LEVEL

Endpoint build level

String

CPU_UTIL

Whether CPU utilization measurement is supported

String

CSD_VERSION

Service pack version number

String

IPX_DEFAULT_SEND

Default send buffer size used for IPX tests

String

MEMORY

Amount of memory available at the endpoint

String

OS

Operating system type at endpoint

String

OS_BUILD_NUMBER

Operating system build number

String

OS_MAJOR_VER

Operating system major version number

String

OS_MINOR_VER

Operating system minor version number

String

PRODUCT_TYPE

Endpoint product type

String

RTP_DEFAULT_SEND

Default send buffer size used for RTP tests

String

SPX_DEFAULT_SEND

Default send buffer size used for SPX tests

String

TCP_DEFAULT_SEND

Default send buffer size used for TCP tests

String

VERSION

Endpoint version

String

UDP_DEFAULT_SEND

Default send buffer size used for UDP tests

String

WINSOCK_API

Provider of the WinSock stack at the endpoint

String

WINSOCK_API_VER

Version of the WinSock API that will be used

String

- 943 -

IxChariot APIGuide

Parameter Name

WINSOCK_STACK_
VER

What is Returned

The highest version of WinSock that the stack supports

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized (113)

No such value. (116)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 944 -

Data
Type

IxChariot APIGuide

chrMGroup getMPair
DESCRIPTION
The chrMGroup getMPair subcommand gets the handle for the multicast pair that corresponds to the given index number in the given multicast group. The handle returned by
this subcommand is needed for other subcommands to operate on the object.
c hrMGroup get MPair mgroup index

ARGUMENTS
mgroup
The handle returned by chrMGroup new or chrTest getMGroup.

index
The index into the array of multicast pairs. The index is determined by the order in which
multicast pairs were added to this multicast group.

RETURNED DATA
The returned data provides the handle to the requested multicast pair object.

ERROR RETURNS
l

Handle is invalid. (101)

No such object. (104)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 945 -

IxChariot APIGuide

chrMGroup getMPairCount
DESCRIPTION
The chrMGroup getMPairCount subcommand gets the number of multicast pairs owned by
the given multicast group.
c hrMGroup get MPairC ount mgroup

ARGUMENTS
mgroup
The handle returned by chrMGroup new or chrTest getMGroup.

RETURNED DATA
The returned data provides the number of multicast pairs (Data type: Long).

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 946 -

IxChariot APIGuide

chrMGroup getPayloadFile
DESCRIPTION
The chrMGroup getPayloadFile subcommand returns the path of the payload file that is
defined by the "send_datatype" variable in the script used by the given multicast group.
c hrMGroup get Pay loadFile mgroup v arN ame

ARGUMENTS
mgroup
The handle returned by chrMGroup new or chrTest getMGroup.

varName
A string specifying the variable name to get.

RETURNED DATA
The returned data provides the path of the payload file defined by the send_datatype variable in the script.

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Pointer is invalid. (103)

No such object. (104)

API was not initialized. (113)

No script in use. (117)

Buffer is too small. (119)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 947 -

IxChariot APIGuide

chrMGroup getPayloadFileIsEmbedded
DESCRIPTION
The chrMGroup getPayloadFileIsEmbedded subcommand returns a Boolean value indicating whether the payload file is referenced or embedded. (The payload file is defined by
the "send_datatype" variable in the script used by the given multicast group.)
c hrMGroup get Pay loadFileI s Embedded mgroup v arN ame

ARGUMENTS
mgroup
The handle returned by chrMGroup new or chrTest getMGroup.

varName
A string specifying the variable name to get.

RETURNED DATA
The function returns TRUE if the payload is embedded and FALSE if the payload is referenced.

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Pointer is invalid. (103)

No such object. (104)

API was not initialized. (113)

No script in use. (117)

Buffer is too small. (119)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 948 -

IxChariot APIGuide

chrMGroup getScriptEmbeddedPayload
DESCRIPTION
The chrMGroup getScriptEmbeddedPayload subcommand gets the embedded payload data
defined by the "send_datatype" variable in the script used by the given multicast group.
c hrMGroup get Sc ript EmbeddedPay load mgroup v arN ame

ARGUMENTS
mgroup
The handle returned by chrMGroup new or chrTest getMGroup.

varName
A string specifying the variable name to get.

RETURNED DATA
The returned data provides the embedded payload data defined by the send_datatype" variable in the script.

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Pointer is invalid. (103)

No such object. (104)

API was not initialized. (113)

No script in use. (117)

Buffer is too small. (119)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 949 -

IxChariot APIGuide

chrMGroup getScriptVar
DESCRIPTION
The chrMGroup getScriptVar subcommand gets the value of a specified variable from the
script defined for use in the given multicast group.
c hrMGroup get Sc ript Var mgroup v arN ame

ARGUMENTS
mgroup
The handle returned by chrMGroup new or chrTest getMGroup.

varName
A string specifying the variable name to get.

RETURNED DATA
The returned data provides the value of the requested script variable.

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Pointer is invalid. (103)

No such object. (104)

API was not initialized. (113)

No script in use. (117)

Buffer is too small. (119)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 950 -

IxChariot APIGuide

chrMGroup new
DESCRIPTION
The chrMGroup new subcommand creates a multicast group and initializes it to default values. The default values are not the user-defined defaults. See Multicast Group Object
Default Values for a list of the default values.
c hrMGroup new

ARGUMENTS
None.

RETURNED DATA
The returned data provides the handle to an initialized multicast group object. The handle
returned by this subcommand is needed for other subcommands to operate on the object.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 951 -

IxChariot APIGuide

chrMGroup removeMPair
DESCRIPTION
The chrMGroup removeMPair subcommand removes the given multicast pair from the
given multicast group. A multicast pair may only be removed from a multicast group that
is owned by a test if the multicast group is locked.
c hrMGroup remov eMPair mgroup mpair

ARGUMENTS
mgroup
The handle returned by chrMGroup new or chrTest getMGroup.

mpair
The handle returned by chrMPair new or chrMPair getMPair.

RETURNED DATA
None

ERROR RETURNS
l

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 952 -

IxChariot APIGuide

chrMGroup set
DESCRIPTION
The chrMGroup set subcommand sets the value for the attribute specified by name in the
given multicast group. You are not allowed to set the attributes of a multicast group that is
owned by a test. One or more name-value pairs may be specified for this subcommand.
c hrMGroup s et mgroup name v alue

ARGUMENTS
mgroup
The handle returned by chrMGroup new, chrVideoMGroup new, or chrTestgetMGroup.

name
The attribute to set.

value
The value to set for the given attribute.

ATTRIBUTES
Attribu te
Names

COMMENT

CONSOLE_E1_
ADDR

CONSOLE_E1_
PROTOCOL

Ran ge or Max
L en gth

What Is Set

Endpoint comment
Addr ess by whi ch the
Consol e knows Endpoi nt 1.
CONSOLE_E1_ADDR only
applies when USE_CONSOLE_
E1 is set to True (1).
Console to Endpoint 1 protocol.
CONSOLE_E1_PROTOCOL only
applies when USE_CONSOLE_
E1 is set to True (1).

Data Ty pe

64 characters

String

64 characters

String

One of the
following:

String

SPX

TCP

Consol e to Endpoi nt 1
qual i ty of ser vi ce
name.
CONSOLE_E1_
QOS

CONSOLE_E1_QOS only applies

when USE_CONSOLE_E1 is set 64 characters
to True (1).
This attribute is
applicable only to
APPC.

- 953 -

String

IxChariot APIGuide

Attribu te
Names

Ran ge or Max
L en gth

What Is Set

Data Ty pe

IxChariot6.20 and
higher no longer support APPC.
Specifies the action to perform:
l

DISABLE 1
l

If TRUE, disable all the

pairs in the group for this
test.

0 = False
1 = True

Boolean

If FALSE, enable all the

pairs in the group for this
test.

E1_ADDR

Endpoint 1 address

64 characters

String

LOCK

Object's locked or unlocked

status. If the value is set to
TRUE and the object is
unlocked, the object is locked.
If the value is set to FALSE and
the object is locked, the object
is unlocked.

0 = False
1 = True

Boolean

String

Long

An owned object must be

locked--disabled for validation--before any of its attributes can be modified (using the
set subcommand).
To enable validation, all
objects owned by a test (including multicast pairs owned by
the test's multicast groups)
must be unlocked before the
test can be run or saved. When
an attempt is made to unlock a
locked object, the object is validated. If the object is found to
be invalid, an error is returned
and the object remains locked.

MULTICAST_
ADDR

Multicast IP address

15 characters; in
the range
224.0.0.0 to
239.255.255.255

MULTICAST_
PORT

Multicast port number

1 to 65535

- 954 -

IxChariot APIGuide

Attribu te
Names

Ran ge or Max
L en gth

What Is Set

Data Ty pe

NAME

Multicast group name

64 characters

String

PROTOCOL

Endpoint 1 to Endpoint 2 protocol

One of the following:

RTP
UDP

String

QOS_NAME

Endpoint 1 to Endpoint 2 quality of service name

64 characters

String

USE_
CONSOLE_E1

Whether to use the Console to

Endpoint 1 values. If the value
is set to TRUE, the Console to
Endpoint 1 address and Console to Endpoint 1 Quality Of
Service name must be properly defined before the test is
run. The Console to Endpoint 1
protocol defaults to TCP and
may be changed if needed.

0=False
1=True

Boolean

1T h i s f u n c t i o n i s a l s o v a l i d f o r v i d e o m u l t i c a s t g r o u p s .

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Object is in use. (107)

API was not initialized. (113)

Value is invalid. (115)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 955 -

IxChariot APIGuide

chrMGroup setPayloadFile
DESCRIPTION
The chrMGroup setPayloadFile subcommand modifies the value of a send_datatype
variable in the script defined for use by the given multicast group. It allows a user to specify a file whose content will be used as payload when running the script. This subcommand sets the variable type to "Embedded payload" as well.
c hrMGroup s et Pay loadFile mgroup v ariableN ame f ileN ame
embedded

ARGUMENTS
mgroup
The handle returned by chrMGroup new or chrTest getMGroup.

variableName
A string containing the name of the script variable (maximum 24 characters). The script
variable name is checked to ensure that it exists and is of type send_datatype. "No Such
Object" is returned if the variable does not exist in the script, and "Value is invalid" is
returned if the variable is not of type send_datatype.

fileName
The name of the file containing the payload data. If the specified file does not exit, "No
such object" is returned. If the file size is greater than 1 billion bytes (953MB), "Payload
file too large" is returned.

embedded
If set to True, the payload file will be embedded within the script. If set to False, the script
will contain a reference to the external file. The recommended option is "True".

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

No such object. (104)

Test is running. (106)

Object is in use. (107)

API was not initialized. (113)

Value is invalid. (115)

No script is in use. (117)

Out of memory. (120)

- 956 -

IxChariot APIGuide

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 957 -

IxChariot APIGuide

chrMGroup setScriptEmbeddedPayload
DESCRIPTION
The chrMGroup setEmbedded subcommand modifies the value of a "send_datatype" variable in the script defined for use by the given multicast group. You are not allowed to set
script variables for a multicast group that is owned by a test. This subcommand sets the
type of the variable to "Embedded payload" as well.
c hrMGroup s et Sc ript EmbeddedPay load mgroup name pay load

ARGUMENTS
mgroup
The handle returned by chrMGroup new or chrTest getMGroup.

name
The name of the script variable to set (Data type: String, max 24 characters). "No such
object" is returned if the variable does not exist in the script.

payload
The value of the payload - a binary string which may contain any ASCII character, including 0. Tcl 8.1 or higher is required. (Data type: String).

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

No such object. (120)

Test is running. (106)

Object is in use. (121))

API was not initialized. (113)

Value is invalid. (115)

No script is in use. (117)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 958 -

IxChariot APIGuide

chrMGroup setScriptVar
DESCRIPTION
The chrMGroup setScriptVar subcommand modifies the value of a variable in the script
defined for use by the given multicast group. You are not allowed to set script variables for
a multicast group that is owned by a test.
c hrMGroup s et Sc ript Var mgroup name v alue

ARGUMENTS
mgroup
The handle returned by chrMGroup new or chrTest getMGroup.

name
The name of the script variable to set (Data type: String, max 24 characters). "No such
object" is returned if the variable does not exist in the script.

value
The value to which to set the variable. Use the following table to determine the valid values. (Data type: String, max 64 characters).

Ty pe of v ariable

Allowed valu es

"Reset" (default)
close_type
"Normal"

Integer

Option: nagle_algorithm_e1
nagle_algorithm_e2
udp_checksum_e1
udp_checksum_e2
Port Number:
source_port
destination_port
Send Data Size:

"0" - "2147483647." For send or receive buffer sizes,

"default" instructs IxChariot to automatically select the
default buffer size for the protocol and platform on which
it is running.
Enabled by default
"enabled"
"disabled"
"0" - "65535" or "auto." Specifying a port number of zero
instructs IxChariot to automatically select the port.
An integer (constant).

file_size

This variable specifies the number of bytes to send with

each SEND command.

SEND/RECEIVE Buffer Size:

An integer (constant) between 1 and 2147483647,or a

Random value expressed as "d[x,y]" where:

send_buffer_size
receive_buffer_size

d = u(uniform), n(normal), p(poisson), or e(exponential)

- 959 -

IxChariot APIGuide

Ty pe of v ariable

Allowed valu es

and x,y = integers between "1" and "2147483647" where

x < y, or "default." For send or receive buffer sizes,
"default" instructs Chariot to automatically select the
default buffer size for the protocol and platform on which
it is running.
Connection Buffer Size:

An integer (constant) between 0 and 2147483646.

send_buffer
receive_buffer

CONNECT_INITIATE and CONNECT_ACCEPT each define

both buffers (send_buffer and receive_buffer).
An integer (constant) between 1 and 999999999,

Sleep Time:
initial_delay
user_delay
transaction_delay

Transaction Count:
transactions_per_record

Timing Records:
number_of_timing_records

or a Random value expressed as "d[x,y]" where:

d = u(uniform), n(normal), p(poisson), or e(exponential)
and
x,y = integers between "0" and "999999999" where x <
y.
An i nteger (constant) - mi ni mum val ue i s
1.
This variable controls the number of transactions that
will be run for each timing record. Setting it to 1 causes
each transaction to have its own timing record.
An integer (constant).
An endpoint creates a timing record each time it goes
through a loop.
The word unlimited or a data rate expressed as:
xxxxxx[.yyy] units

Data Rate:
send_data_rate

There must not be more than six x's to the left of the
decimal and no more than three y's to the right of the
decimal point.
U ni ts shoul d be one of :
KB, Kb, kB, kb - 1024 bytes per second
Mb 1, 000, 000 bytes per second
Gb 1,000,000,000 bytes per second

The data rate may not be 0.0.

Data Type:
s e n d _d a t a t y p e

Default Files
Optional Files
Embedded Payload:
Referenced or Embedded Payload File:

- 960 -

IxChariot APIGuide

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

No such object. (120)

Test is running. (106)

Object is in use. (121))

API was not initialized. (113)

Value is invalid. (115)

No script is in use. (117)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 961 -

IxChariot APIGuide

chrMGroup useScript
DESCRIPTION
The chrMGroup useScript subcommand defines or changes the script to be used by the
given multicast group. You are not allowed to set a script for use by a multicast group that
is owned by a test. Extended error information is available for this subcommand.
c hrMGroup us eSc ript mgroup f ilename

ARGUMENTS
mgroup
The handle returned by chrMGroup new or chrTest getMGroup.

filename
The name of the script file to read for use (Data type: String, max 300 characters). The filename may be specified with a full or relative pathname.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Object is in use. (107)

Operation has failed. (108)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 962 -

IxChariot APIGuide

Multicast Pair Object Command

The multicast pair object command is used to define and retrieve information about a multicast pair. This command has seven subcommands.

- 963 -

IxChariot APIGuide

chrMPair delete
DESCRIPTION
The chrMPair delete subcommand frees all memory associated with the given multicast
pair object. This is necessary because the Tcl Interpreter has no access to the associated
structures supporting the object. An mpair cannot be deleted if it is owned by a multicast
group.
c hrMPair delet e mpair

ARGUMENTS
mpair
The handle returned by chrMPair new.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 964 -

IxChariot APIGuide

chrMPair get
DESCRIPTION
The chrMPair get subcommand gets the value for the attribute specified by name from the
given multicast pair.
c hrMPair get mpair name

ARGUMENTS
mpair
The handle returned by chrMPair new or chrMGroup getMPair.

name
The attribute to get.

RETURNED DATA
Attribu te
Name

E2_ADDR

W h at I s Retu rn ed

Endpoint 2 address

Data
Ty pe

String

Status of a multicast pair during a test run.

The list of run status strings is as follows:

RUNSTATUS

uninitialized

initializing 1

initializing 2

initializing 3

initialized

running

stopping

requested stop

error

resolving names

polling

finished

requesting stop

finished with warnings

transferring payload

applying Ixia config

waiting for reinit

abandoned

String

- 965 -

IxChariot APIGuide

Attribu te
Name

W h at I s Retu rn ed

Data
Ty pe

SETUP_E1_E2_
ADDR

Address at which Endpoint 1 knows Endpoint 2 for setup.

SETUP_E1_E2_ADDR is only used when USE_SETUP_E1_E2 is String
set to True.

USE_SETUP_
E1_E2

Whether to use the SETUP_E1_E2_ADDR values.

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 966 -

Boolean

IxChariot APIGuide

chrMPair getEndpointConfig
DESCRIPTION
The chrMPair getEndpointConfig subcommand gets the value for endpoint configuration
parameters for Endpoint 2 for the given multicast pair.
chrMPair getEndpointConfig mpair name

ARGUMENTS
mpair
The handle returned by chrMPair new or chrMGroup getMPair.

name
The endpoint configuration parameter to get.

RETURNED DATA
P aram eter
Name

W h at I s Retu rn ed

Data
Ty pe

BUILD_LEVEL

Endpoint build level

String

CPU_UTIL

Whether CPU utilization calculation is supported

String

CSD_VERSION

Service pack version number

String

IPX_DEFAULT_
SEND

Default send buffer size used for IPX tests

String

MEMORY

Amount of memory available at the endpoint

String

OS

Operating system type at endpoint

String

OS_BUILD_
NUMBER

Operating system build number

String

OS_MAJOR_
VER

Operating system major version number

String

OS_MINOR_
VER

Operating system minor version number

String

PRODU CT_
TYPE

Endpoi nt pr oduct type

RTP_
DEF AU LT_
SEND

Def aul t send buf f er si ze used f or RTP tests

SPX_
DEF AU LT_

Def aul t send buf f er si ze used f or SPX tests

- 967 -

Str i ng

Str i ng

Str i ng

IxChariot APIGuide

P aram eter
Name

W h at I s Retu rn ed

Data
Ty pe

SEND
TCP_
DEF AU LT_
SEND

Def aul t send buf f er si ze used f or TCP tests

UDP_
DEF AU LT_
SEND

Def aul t send buf f er si ze used f or U DP tests

VERSI ON

Endpoi nt ver si on

WI NSOCK_
API

Pr ovi der of the Wi nSock stack at the endpoi nt

Str i ng

WI NSOCK_
API _VER

Ver si on of the Wi nSock API that wi l l be used

Str i ng

Hi ghest ver si on of Wi nSock that the stack

suppor ts

Str i ng

WI NSOCK_
STACK_VER

Handle is invalid. (101)

API was not initialized (114)

No such value. (117)

Out of memory. (120)

Program internal error. (121)

Str i ng

Str i ng

ERROR RETURNS
l

Str i ng

See Return Code Summary for a detailed description of each return code.

- 968 -

IxChariot APIGuide

chrMPair getTimingRecord
DESCRIPTION
The chrMPair getTimingRecord subcommand gets the handle for the specified timing
record from the results for the given multicast pair. The handle returned by this subcommand is needed for other subcommands to operate on the object.
c hrMPair get TimingR ec ord mpair num

ARGUMENTS
mpair
A handle returned by chrMPair new or chrMGroup getMPair.

num
A number indicating which timing record. This number is determined by the order in which
the timing records were received.

RETURNED DATA
The returned data provides the handle to the requested timing record object.

ERROR RETURNS
l

Handle is invalid. (101)

No such object. (104)

Test was not run. (105)

API was not initialized. (113)

Results are not available. (114)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 969 -

IxChariot APIGuide

chrMPair getTimingRecordCount
DESCRIPTION
The chrMPair getTimingRecordCount subcommand gets the number of timing records in the
results for the given multicast pair. The handle returned by this subcommand is needed for
other subcommands to operate on the object.
c hrMPair get TimingR ec ordC ount mpair

ARGUMENTS
mpair
The handle returned by chrMPair new or chrMGroup getMPair.

RETURNED DATA
The number of timing records (Data type: Long).

ERROR RETURNS
l

Handle is invalid. (101)

Test was not run. (105)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 970 -

IxChariot APIGuide

chrMPair new
DESCRIPTION
The chrMPair new subcommand creates a multicast pair and initializes it to default values.
The handle returned by this subcommand is needed for other subcommands to operate on
the object. The default values are not the user-defined defaults. See Multicast Pair Object
Command for a listing of the default values.
c hrMPair new

ARGUMENTS
None

RETURNED DATA
The returned data provides the handle to a multicast pair object.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 971 -

IxChariot APIGuide

chrMPair set
DESCRIPTION
The chrMPair set command sets the value for the attribute specified by name in the given
multicast pair. You are not allowed to set the attributes for a multicast pair that is owned
by a multicast group.
c hrMPair s et mpair name v alue

ARGUMENTS
mpair
The handle returned by chrMPair new or chrMGroup getMPair.

name
The attribute to set.

value
The value to set for the given attribute.

ATTRIBUTES

Attribu te
Name

E2_ADDR

What Is Set

Endpoint 2 address

Ran ge or
Max
S trin g
L en gth

Data
Ty pe

64
characters

String

0 = False

Boolean

Object's locked or unlocked status. If the value

is set to TRUE and the object is unlocked, the
object is locked. If the value is set to FALSE
and the object is locked, the object is
unlocked.
LOCK

An owned object must be locked-disabled for

validation--before any of its attributes can be
modified (using the set subcommand).
To enable validation, all objects owned by a
test (including multicast pairs owned by the
test's multicast groups) must be unlocked
before the test can be run or saved.
When an attempt is made to unlock a locked
object, the object is validated. If the object is
found to be invalid, an error is returned and
the object remains locked.

- 972 -

1 = True

IxChariot APIGuide

Attribu te
Name

What Is Set

SETUP_E1_E2_
ADDR

Address at which Endpoint 1 knows Endpoint 2

for setup. SETUP_E1_E2_ADDR is only used
when USE_SETUP_E1_E2 is set to True.

USE_SETUP_
E1_E2

Whether to use the SETUP_E1_E2_ADDR values.

Ran ge or
Max
S trin g
L en gth

Data
Ty pe

64 characters

String

0 = False

Boolean

1 = True

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Object in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 973 -

IxChariot APIGuide

Pair Object Command

The pair object command is used to define and retrieve information about an endpoint
pair. This command has ten subcommands.

- 974 -

IxChariot APIGuide

chrPair copy
DESCRIPTION
The chrPair copy subcommand copies the attributes of the source pair to the destination
pair for an endpoint pair or hardware performance pair.
c hrPair c opy des t s rc

ARGUMENTS
dest
The handle for the destination, returned by chrPair new.

src
The handle for the source, returned by chrPair/chrHardwarePair new or chrTest getPair.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 975 -

IxChariot APIGuide

chrPair delete
DESCRIPTION
The chrPair delete subcommand frees all memory associated with the given pair object.
This is necessary because the Tcl interpreter has no access to the associated structures
supporting the object. A pair cannot be deleted if it is owned by a test.
c hrPair delet e pair

ARGUMENTS
Pair
The handle returned by chrPair/chrHardwarePair new.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 976 -

IxChariot APIGuide

chrPair get
DESCRIPTION
The chrPair get subcommand gets the value for the attribute specified by name from the
given pair.
c hrPair get pair name

ARGUMENTS
pair
The handle returned by chrPair/chrHardwarePair new or chrTest getPair.

name
The attribute to get.

ATTRIBUTES
Attributes marked with a * are valid for Hardware Performance Pairs

Attribu te Nam e

W h at I s Retu rn ed

Data
Ty pe

APPL_SCRIPT_
NAME 1

Application script name. Cannot be used for VoIP

pairs.

String

COMMENT a

Pair comment

String

Address by which the Console knows Endpoint 1.

CONSOLE_E1_ADDR only applies when USE_
CONSOLE_E1 is set to True (1).

String

CONSOLE_E1_
PROTOCOL

Console to Endpoint 1 protocol. CONSOLE_E1_

PROTOCOL only applies when USE_CONSOLE_E1 is set String
to True (1).

CONSOLE_E1_ADDR

Console to Endpoint 1 quality of service name.

CONSOLE_E1_QOS only applies when USE_CONSOLE_
E1 is set to True (1).
CONSOLE_E1_QOS

String
This attribute is applicable only to APPC.
IxChariot6.20 and higher no longer support APPC.

E 1 _A D D R

Endpoi nt 1 addr ess

Str i ng

E 2 _A D D R

Endpoi nt 2 addr ess

Str i ng

TRU E i f the pai r i s di sabl ed f or the

test.

Boolean

I S _D I S A B L E D
2

- 977 -

IxChariot APIGuide

Attribu te Nam e

W h at I s Retu rn ed

Data
Ty pe

PROTOCOL

Endpoi nt 1 to Endpoi nt 2 pr otocol

Str i ng

QOS_NAME3

Endpoi nt 1 qual i ty of ser vi ce name

Str i ng

E 1 _Q O S _ N A M E

Endpoi nt 1 qual i ty of ser vi ce name

Str i ng

E 2 _Q O S _ N A M E

Endpoi nt 2 qual i ty of ser vi ce name

Str i ng

Status of an endpoi nt pai r dur i ng a test

r un. The l i st of r un status str i ngs i s as
follows:

RUNSTATUS

SCRI PT_
F I LENAME

uninitialized

initializing 1

initializing 2

initializing 3

initialized

running

stopping

requested stop

error

resolving names

polling

finished

requesting stop

finished with warnings

transferring payload

applying Ixia config

waiting for reinit

abandoned

Str i ng

Scr i pt f i l ename. Cannot be used f or

VoI P pairs.

Str i ng

S E T U P _ E 1 _E 2 _
ADDR a

Addr ess at whi ch Endpoi nt 1 knows Endp o i n t 2 f o r s e t u p . S E T U P _ E 1 _E 2 _ A D D R

i s onl y used when U SE_SETU P_E1_E2 i s
set to Tr ue.

Str i ng

U SE_
CONSOLE_E1

Whether to use the Consol e to Endpoi nt

1 val ues

Boolean

U SE_SETU P_
E 1 _E 2

W h e t h e r t o u s e t h e S E T U P _ E 1 _E 2 _ A D D R
val ues.

Boolean

U SE_U DP_
RF C768

Whether the scr i pt sets the opti on to

use RF C768 U DP.

Boolean

- 978 -

IxChariot APIGuide

1T h i s a t t r i b u t e i s a l s o v a l i d f o r H a r d w a r e P e r f o r m a n c e p a i r s .
2T h i s a t t r i b u t e i s v a l i d f o r r e g u l a r p a i r s , H a r d w a r e P e r f o r m a n c e
pai r s, VoI P pai r s, VoI P Har dwar e Per f or mance pai r s, and vi deo
pai r s. However , thi s f uncti on i s not val i d f or pai r s wi thi n appl i cati on gr oups.
3P r e s e r v e d f o r c o m p a t i b i l i t y r e a s o n s , i s e q u i v a l e n t t o E 1 _ Q O S _
NAME.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

Pointer is invalid. (103)

API was not initialized. (113)

No such value. (116)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 979 -

IxChariot APIGuide

chrPair getEndpointConfig
DESCRIPTION
The chrPair getEndpointConfig subcommand gets the value for endpoint configuration parameters for the given endpoint for the given pair.
c hrPair get Endpoint C onf ig pair endpt name

ARGUMENTS
pair
The handle returned by chrPair new or chrTest getPair.

endpt
E1 or E2.

name
What endpoint configuration parameter to get.

RETURNED DATA
Parameter
Name

What Is Re tur ne d

Data
Type

BUILD_LEVEL

Endpoint build level

String

CPU_UTIL

Whether CPU utilization calculation is supported

String

CSD_VERSION

Service pack version number

String

IPX_DEFAULT_
SEND

Default send buffer size used for IPX tests

String

MEMORY

Amount of memory available at the endpoint

String

OS

Operating system type at endpoint

String

OS_BUILD_NUM

Operating system build number

String

OS_MAJOR_VER

Operating system major version number

String

O S _M I N O R _
VER

Oper ati ng sy stem mi nor v er si on number

PRODU CT_
TYPE

Endpoi nt pr oduct type

RTP_DEF AU LT_
SEND

Def aul t send buf f er si ze used f or RTP

tests

- 980 -

Str i ng

Str i ng

Str i ng

IxChariot APIGuide

Parameter
Name

What Is Re tur ne d

Data
Type

SPX_
DEF AU LT_
SEND

Def aul t send buf f er si ze used f or SPX

tests

Str i ng

TCP_DEF AU LT_
SEND

Def aul t send buf f er si ze used f or TCP

tests

Str i ng

UDP_
DEF AU LT_
SEND

Def aul t send buf f er si ze used f or U DP

tests

Str i ng

VERSI ON

Endpoi nt ver si on

WI NSOCK_API

Pr ovi der of the Wi nSock stack at the end- Str i ng

poi nt

WI NSOCK_
API _VER

Ver si on of the Wi nSock API that wi l l be

used

Str i ng

WI NSOCK_
STACK_VER

Hi ghest ver si on of Wi nSock that the

stack suppor ts

Str i ng

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized (113)

No such value. (116)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 981 -

Str i ng

IxChariot APIGuide

chrPair getPayloadFile
DESCRIPTION
The chrPair getPayloadFile subcommand returns the path of the payload file that is defined
by the "send_datatype" variable in the script used by the given endpoint pair.
c hrPair get Pay loadFile pair v arN ame

ARGUMENTS
pair
The handle returned by chrPair new or chrTest getPair.

varName
A string specifying the variable name to get.

RETURNED DATA
The returned data provides the path of the payload file that is defined by the "send_datatype" variable.

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Pointer is invalid. (103)

No such object. (104)

API was not initialized. (113)

No script in use. (117)

Buffer is too small. (119)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 982 -

IxChariot APIGuide

chrPair getPayloadFileIsEmbedded
DESCRIPTION
The chrPair getPayloadFileIsEmbedded subcommand returns a Boolean value indicating
whether the payload file is referenced or embedded. (The payload file is defined by the
"send_datatype" variable in the script used by the given pair.)
c hrPair get Pay loadFileI s Embedded pair v arN ame

ARGUMENTS
pair
The handle returned by chrPair new or chrTest getPair.

varName
A string specifying the variable name to get.

RETURNED DATA
The function returns TRUE if the payload is embedded and FALSE if the payload is referenced.

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Pointer is invalid. (103)

No such object. (104)

API was not initialized. (113)

No script in use. (117)

Buffer is too small. (119)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 983 -

IxChariot APIGuide

chrPair getScriptEmbeddedPayload
DESCRIPTION
The chrPair getScriptEmbeddedPayload subcommand gets the embedded payload data
defined by the "send_datatype" variable in the script used by the given endpoint pair.
c hrPair get Sc ript EmbeddedPay load pair v arN ame

ARGUMENTS
pair
The handle returned by chrPair new or chrTest getPair.

varName
A string specifying the variable name to get.

RETURNED DATA
The returned data provides the embedded payload data defined by the "send_datatype"
variable in the script.

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Pointer is invalid. (103)

No such object. (104)

API was not initialized. (113)

No script in use. (117)

Buffer is too small. (119)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 984 -

IxChariot APIGuide

chrPair getScriptVar
DESCRIPTION
The chrPair getScriptVar subcommand gets the value of the script variable indicated by
varName.
c hrPair get Sc ript Var pair v arN ame

ARGUMENTS
pair
The handle returned by chrPair new or chrTest getPair.

varName
A string specifying the variable name to get.

RETURNED DATA
The returned data provides the value of the requested script variable. The value will be
returned in the same format used by the set function.

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Pointer is invalid. (103)

No such object. (104)

API was not initialized. (113)

No script in use. (117)

Buffer is too small. (119)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 985 -

IxChariot APIGuide

chrPair getTimingRecord
DESCRIPTION
The chrPair getTimingRecord subcommand gets the handle to the timing record object
indicated by num. The handle returned by this subcommand is needed for other subcommands to operate on the object.
c hrPair get TimingR ec ord pair num

ARGUMENTS
pair
The handle returned by chrPair new or chrTest getPair.

num
A number indicating which timing record to get. The number is determined by the order in
which the timing records were received.

RETURNED DATA
The returned data provides the handle to the requested timing record.

ERROR RETURNS
l

Handle is invalid. (101)

No such object. (104)

Test was not run. (105)

API was not initialized. (113)

Results are not available. (114)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 986 -

IxChariot APIGuide

chrPair getTimingRecordCount
DESCRIPTION
The chrPair getTimingRecordCount subcommand gets the number of timing records in the
results for the given pair.
c hrPair get TimingR ec ordC ount pair

ARGUMENTS
pair
The handle returned by chrPair new or chrTest getPair.

RETURNED DATA
The returned data provides the number of timing records (Data type: Long).

ERROR RETURNS
l

Handle is invalid. (101)

Test was not run. (105)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 987 -

IxChariot APIGuide

chrPair new
DESCRIPTION
The chrPair new command creates a pair and initializes it to default values. Note that the
object default values do not use the default values specified in the IxChariot Options Menu.
See Pair Object Default Values for a list of the default values.
For voice over IP (VoIP) pairs, use CHRVoipPair_new.
c hrPair new

ARGUMENTS
None

RETURNED DATA
The returned data provides the handle to an initialized pair object. The handle returned by
this subcommand is needed for other subcommands to operate on the object.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 988 -

IxChariot APIGuide

chrPair set
DESCRIPTION
The chrPair set subcommand sets the value for the attribute specified by name in the given
pair. One or more name-value pairs may be specified for this subcommand. You are not
allowed to set the attributes for a pair that is owned by a test without unlocking the
chrPair object. (See attribute name LOCK for additional details).
c hrPair s et pair name v alue

ARGUMENTS
pair
The handle returned by any of the following functions: chrTest getPair, chrPairnew,
chrVideoPair new, chrVoIPPair new, or chrHardwarePair new.

name
The attribute to set.

value
The value to set for the given attribute.

ATTRIBUTES
Attribu te
Name

COMMENT 1

CONSOLE_E1_
ADDR a

CONSOLE_E1_
PROTOCOL

What Is Set

Endpoint comment

Ran ge or Max
S trin g L en gth

Data
Ty pe

64 characters

String

CONSOLE_E1_ADDR only applies

when USE_CONSOLE_E1 is set to True
(1).

64 characters

String

Console to Endpoint 1 protocol.

One of the
following:

Addr ess by whi ch the Consol e knows Endpoi nt 1.

CONSOLE_E1_PROTOCOL only applies

when USE_CONSOLE_E1 is set to True
(1).

SPX

TCP

String

Specifies the action to perform:

l

DISABLE2
l

If TRUE, disable the pair for the

test.

0 = False
1 = True

Boolean

If FALSE, enable the pair for the

test.

E1_ADDR a

Endpoint 1 address.

64 characters

String

E2_ADDR a

Endpoint 2 address.

64 characters

String

- 989 -

IxChariot APIGuide

Attribu te
Name

What Is Set

Ran ge or Max
S trin g L en gth

Data
Ty pe

Object's locked or unlocked status. If

the value is set to True (1)and the
object is unlocked, the object is
locked. If the value is set to False (0)
and the object is locked, the object is
unlocked.

LOCK

An owned object must be locked-disabled or validation-before any of its

attributes can be modified (using the
set subcommand).

0 = False

Boolean

1 = True

To enable validation, all objects

owned by a test must be unlocked
before the test can be run or saved.
When an attempt is made to unlock a
locked object, the object is validated.
If the object is found to be invalid, an
error is returned and the object
remains locked.
One of the following:

Endpoint 1 to Endpoint 2 protocol. Cannot be used for voice over IP (VoIP)

pairs.

IPX

RTP

SPX

TCP

UDP

TCP6 3

UDP6 c

RTP6 c

PROTOCOL
Only RTP and RTP6 can be used for
VoIP pairs; only applies if you're running the VoIP Test Module.

String

SETUP_E1_E2_
ADDR a

Address at which Endpoint 1 knows

Endpoint 2 for setup. SETUP_E1_E2_
ADDR is only used when USE_SETUP_
E1_E2 is set to True (1).

64 characters

String

QOS_NAME

Sets specified QoS template for both

Endpoint 1 and Endpoint 2.

64 characters

String

E 1 _Q O S _
NAME

Endpoint 1 quality of service template

name.

64 characters

String

- 990 -

IxChariot APIGuide

Attribu te
Name

E2_QOS_NAME4

What Is Set

Endpoint 2 quality of service template

name.

Ran ge or Max
S trin g L en gth

64 characters

Whether to use the Console to Endpoint 1 values. If the value is set to

True (1), the Console to Endpoint 1
address and Console to Endpoint 1
USE_CONSOLE_ Quality Of Service name must be prop- 0 = False
E1
erly defined before the test is run.
1 = True
The Console to Endpoint 1 protocol
defaults to TCP and may be changed if
needed. Must be set to True if you're
using an IPv6 protocol.
USE_SETUP_
E1_
E2

Whether to use the SETUP_E1_E2_

ADDR values. (Refer to Management
Addresses with Stack Manager for
related information.)

0 = False

Data
Ty pe

String

Boolean

Boolean

1 = True

1Valid for hardware performance pairs.

2This attribute is valid for regular pairs, Hardware Performance pairs, VoIP pairs, VoIP
Hardware Performance pairs, and video pairs. However, this function is not valid for
pairs within application groups.
3IPv6 Test Module only.
4When using the E2_QoS_NAME attribute for VoIP, video, or VoIP Hardware Performance
pairs, the function does not return an error code, but the QoS is not set, because these
pair types send traffic only from Endpoint 1 to Endpoint 2.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Object is in use. (107)

API was not initialized. (113)

Value is invalid. (115) *

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 991 -

IxChariot APIGuide

chrPair setPayloadFile
DESCRIPTION
The chrPair setPayloadFile subcommand specifies the payload of a particular SEND
command. It allows the user to specify a file whose content will be used as payload when
running the script. In addition to specifying the payload, this function also sets the send_
datatype to "Payload File".
c hrPair s et Pay loadFile pair v ariableN ame f ileN ame
embedded

ARGUMENTS
pair
The handle returned by chrPair new or chrTest getPair.

variableName
A string containing the name of the script variable (maximum 24 characters). The script
variable name is checked to ensure that it exists and is of type send_datatype. "No Such
Object" is returned if the variable does not exist in the script, and "Value is invalid" is
returned if the variable is not of type send_datatype.

fileName
The name of the file containing the payload data. If the specified file does not exit, "No
such object" is returned. If the file size is greater than 1 billion bytes (953MB), "Payload
file too large" is returned.

embedded
If set to True, the payload file will be embedded within the script. If set to False, the script
will contain a reference to the external file. The recommended option is "True".

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

No such object. (104)

Test is running. (106)

Object is in use. (107)

API was not initialized. (113)

Value is invalid. (115)

No script is in use. (117)

Out of memory. (120)

- 992 -

IxChariot APIGuide

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 993 -

IxChariot APIGuide

chrPair setScriptEmbeddedPayload
DESCRIPTION
The chrPair setEmbedded subcommand modifies the value of a "send_datatype" variable in
the script defined for use by the given multicast pair. You are not allowed to set script variables for a multicast pair that is owned by a test. This subcommand sets the type of the
variable to "Embedded payload" as well.
c hrPair s et Sc ript EmbeddedPay load pair name pay load

ARGUMENTS
pair
The handle returned by chrPair new or chrTest getPair.

name
The name of the script variable to set (Data type: String, max 24 characters). "No such
object" is returned if the variable does not exist in the script.

payload
The value of the payload - a binary string which may contain any ASCII character, including 0. Tcl 8.1 or higher is required. (Data type: String).

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

No such object. (120)

Test is running. (106)

Object is in use. (121)

API was not initialized. (113)

Value is invalid. (115)

No script is in use. (117)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 994 -

IxChariot APIGuide

chrPair setScriptVar
DESCRIPTION
The chrPair setScriptVar subcommand modifies the value of a variable in the script defined
for use by the given pair. The script variable name is checked to ensure that it exists in the
defined script. "No such object" is returned if the variable does not exist in the script. The
variable value is checked to ensure that it is valid for that variable in that script. You cannot set script variables for pairs that are owned by a test, or for voice over IP (VoIP) pairs.
The options related to Nagle, UDP checksum and MSS must have previously
been inserted into a saved script before being set with this command. This is
accomplished using the IxChariot script editor's insert menu.
c hrPair s et Sc ript Var pair name v alue

ARGUMENTS
pair
The handle returned by chrPair new or chrTest getPair.

name
The name of the script variable to set or change (Data type: String, max 24 characters).

value
The value to which to set the variable (Data type: String, name 25 characters, Value 64).
Use the following table to determine the valid string values.

Ty pe of v ariable

close_type

Integer

Option: nagle_algorithm_e1
nagle_algorithm_e2
udp_checksum_e1
udp_checksum_e2

Allowed valu es

"Reset" (def aul t)

"Normal"
"0" - "2147483647" For send or receive buffer sizes,
"default" instructs IxChariot to automatically select the
default buffer size for the protocol and platform on which
it is running.
Enabled by default. But for all VoIP pairs, udp_checksum
is disabled by default on operating systems that support
it.
"enabled"
"disabled"

Option: max_segment_size_
e1
max_segment_size_e2

Disabled by default. The transmit MSS associated with

either endpoint 1 or 2. This must be an integer value.

Port Number:

"0" - "65535" or "auto." Specifying a port number of zero

- 995 -

IxChariot APIGuide

Ty pe of v ariable

source_port
destination_port
Send Data Size:
file_size

Allowed valu es

instructs IxChariot to automatically select the port.

An integer (constant).
This variable specifies the number of bytes to send with
each SEND command.
An integer (constant) between 1 and 2147483647, or a
Random value expressed as "d[x,y]" where:

SEND/RECEIVE Buffer Size:

send_buffer_size
receive_buffer_size

d = u(uniform), n(normal), p(poisson), or e(exponential)

and x,y = integers between "1" and "2147483647" where
x < y , or "default."
For send or receive buffer sizes, "default" instructs
Chariot to automatically select the default buffer size for
the protocol and platform on which it is running.

Connection Buffer Size:

An integer (constant) between 0 and 2147483646.

send_buffer
receive_buffer

CONNECT_INITIATE and CONNECT_ACCEPT each define

both buffers (send_buffer and receive_buffer).

Sleep Time:
initial_delay
user_delay
transaction_delay

An integer (constant) between 1 and 999999999, or a

Random value expressed as "d[x,y]" where:
d = u(uniform), n(normal), p(poisson), or e(exponential)
and x,y = integers between "0" and "999999999" where
x < y.
An integer (constant) - minimum value is 1.

Transaction Count:
transactions_per_record

Timing Records:
number_of_timing_records

This variable controls the number of transactions that

will be run for each timing record. Setting it to 1 causes
each transaction to have its own timing record.
An integer (constant).
An endpoint creates a timing record each time it goes
through a loop.
The word unlimited or a data rate expressed as:
xxxxxx[.yyy] units

Data Rate:
send_data_rate

There must not be more than six x's to the left of the
decimal and no more than three y's to the right of the
decimal point.
Units should be one of:
l

KB, Kb, kB, kb - 1024 bytes per second

Mb 1,000,000 bytes per second

Gb 1,000,000,000 bytes per second

- 996 -

IxChariot APIGuide

Ty pe of v ariable

Allowed valu es

The data rate may not be 0.0.

Data Type:

Default Files

send_datatype

Optional Files
Embedded Payload:
Referenced or Embedded Payload File:
Specify the variable name (such as sync_event) as the
name parameter, and an application group event name
as the value parameter.
For example, if your script contains:
SIGNAL_EVENT
Event = sync_event (start_streaming)

Data Type:
SIGNAL_EVENT or WAIT_
EVENT

Then, name = sync_event, and value = start_streaming.

To unassign an event, use the string "Not Assigned" as
the event name.
A valid event name must meet the following criteria:
l
l

The pair must be part of an application group.

The event name must already be included in that
application group.

RETURNED DATA
None

ERROR RETURNS
The following return codes indicate that an error occurred and any returned data should be
ignored:
l

Handle is invalid. (101)

String is too long. (102)

No such object. (104)

Object is in use. (107)

API was not initialized. (113)

Value is invalid. (115)

No script is in use. (117)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a description of each return code.

- 997 -

IxChariot APIGuide

chrPair useScript
DESCRIPTION
The chrPair useScript subcommand defines or changes the script to be used by the given
pair. You are not allowed to set a script for use by a pair that is owned by a test, or for a
voice over IP (VoIP) pair. Extended error information is available for this subcommand.
c hrPair us eSc ript pair f ilename

ARGUMENTS
pair
The handle returned by chrPair/chrHardwarePair new or chrTest getPair.

filename
The name of the script file to read for use. The filename may be specified with a full or relative pathname. (Data type: String, max 300 characters).

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Object is in use. (107)

Operation has failed. (108)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 998 -

IxChariot APIGuide

chrPair swapEndpoints
DESCRIPTION
The chrPair swapEndpoints subcommand swaps (exchanges) endpoints (test and management addresses between E1 and E2). It is supported for regular pairs, VoIP, unicast
video, HPP, and vHPP.
c hrPair s w apEndpoint s pair

ARGUMENTS
pair
A handle returned by many functions, since chrPair swapEndpoints is supported for regular
pairs, VoIP, unicast video, HPP, and vHPP (e.g., chrPair new, chrVoIPPair new, etc.).

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

See Return Code Summary for a detailed description of each return code.

- 999 -

IxChariot APIGuide

Hardware Performance Pair Object Commands

Hardware Performance Pair object commands are used to define pairs for a test and
retrieve information about an endpoint pair. You are not allowed to set any pair information for a pair that is owned by a test. The following Pair Object Commands are used to
get/set values in the Hardware Performance Pair Object as well:
l

chrHardwarePair get

chrHardwarePair new

chrHardwarePair set

- 1000 -

IxChariot APIGuide

chrHardwarePair get
DESCRIPTION
The chrHardwarePair get subcommand gets the value for the attribute specified by name
from the given pair.
c hrH ardw arePair get pair name

ARGUMENTS
pair
The handle returned by chrHardwarePair new or chrTest getPair.

name
The attribute to get.

ATTRIBUTES
Attribu te
Name

What Is Set

OVERRI DE_
L I N E _R A T E

I n d i c a t e s t h a t t h e L I N E _R A T E v a l u e s h o u l d
over r i de the l i ne r ate set i n the har dwar e
per f or mance pai r ' s associ ated str eam.

L I N E _R A T E

The l i ne r ate f or the por t.

Float

Whether to measur e stati sti cs f or the pai r

or not.

Boolean

MEASU RE_
STATI STI CS

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Object is in use. (107)

API was not initialized. (113)

Value is invalid. (115) *

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1001 -

Data
Ty pe

Boolean

IxChariot APIGuide

chrHardwarePair new
DESCRIPTION
The chrHardwarePair new command creates a Hardware Performance pair and initializes
it to default values. Note that the object default values do not use the default values specified on the Run Options tab. See Hardware Performance Pair Object Default Values for a
list of the default values.
c hrH ardw arePair new

ARGUMENTS
None

RETURNED DATA
The returned data provides the handle to an initialized hardware pair object. The handle
returned by this subcommand is needed for other subcommands to operate on the object.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1002 -

IxChariot APIGuide

chrHardwarePair set
DESCRIPTION
The chrHardwarePair set subcommand sets or changes the value for the attribute specified
by name from the given pair.
c hrH ardw arePair s et pair name v alue

ARGUMENTS
pair
The handle returned by chrHardwarePair new or chrTest getPair.

name
The attribute to set.

value
The value to set for the given attribute.

ATTRIBUTES
Attribu te
Name

What Is Set

Ran ge or
Max
S trin g
L en gth

Data
Ty pe

OVERRIDE_
LINE_RATE

Indicates that the LINE_RATE value should over0 = false, 1 Boolean

ride the line rate set in the hardware per= true
formance pair's associated stream.

LINE_RATE

The line rate for the port.

0.1 to 100

MEASURE_
STATISTICS

Whether to measure statistics for the pair or

not.

0 = false, 1 Boolean
= true

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Object is in use. (107)

API was not initialized. (113)

Value is invalid. (115) *

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1003 -

Float

IxChariot APIGuide

- 1004 -

IxChariot APIGuide

Pair/Mpair Results Extraction Command

The pair/mpair results extraction command is used to obtain test results that are common
to pairs and multicast pairs. This command has one subcommand.

- 1005 -

IxChariot APIGuide

chrPairResults get
DESCRIPTION
The chrPairResults get subcommand gets the results of the given type from the given pair
or given multicast pair object.
c hrPairR es ult s get pair t y pe

ARGUMENTS
pair
l

For a pair, the handle returned by chrPair new or chrTest getPair.

For a multicast pair, the handle returned by chrMPair new or chrMGroup getMPair.

type
The type of results to return. The units for these values depend on the type:
l

l
l

For both endpoint 1 and endpoint 2 RSSI, the units are in dBm. Values for E1 are
returned when using non-streaming scripts and for E2 when using streaming scripts.
For throughput, the units are specified in the test.
For response time, the units are seconds. "No such value" is returned for streaming
tests.

Transaction rate has no units. "No such value" is returned for streaming tests.

Relative precision has no units.

CPU utilization is a percent (%).

RETURNED DATA
Attribute Name

What Is Returned

Data
Type

CONSECUTIVE_
LOST

List of maximum consecutive lost values

Float

CPU_UTIL_E1

CPU utilization by Endpoint 1

Float

CPU_UTIL_E2

CPU utilization by Endpoint 2

Float

DELAY_FACTOR

The Delay Factor, a video test measure of the maximum

difference between the arrival of media data and the
drain of that data, measured at the end of each media
stream packet. The Delay Factor indicates the amount of
time it takes to drain the buffer.

Float

DELAY_VARIATION

List of jitter (delay variation) maximum values

Float

END_TO_END_
DELAY

List of average end-to-end delay values measured in milliseconds. The measured one-way (network) delay, plus Long
all other delays (packetization delay, jitter buffer delay,

- 1006 -

IxChariot APIGuide

Attribute Name

What Is Returned

Data
Type

and any additional delay configured for the pair).

List of RFC 1889 jitter values in the following order:
JITTER

MEDIA_LOSS_RATE

average

minimum

maximum

Float

Media Loss Rate, a video test measure of the number of

lost or out-of-order flow packets over a selected time
interval (such as three seconds).

Float

List of Mean Opinion Score (MOS) values in the following

order:
MOS_ESTIMATE

average

minimum

maximum

Float

List of one-way delay values (in milliseconds) in the following order:

ONE_WAY_DELAY

average

minimum

maximum

R-value (calculated using the ITU G.107 E-model):

R_VALUE

Float
average

REL_PRECISION

relative precision

Float

List of response time values in the following order:

RESP_TIME

average

minimum

maximum

Float

The list of RSSI values for E1 in the following order:

RSSI_E1

average

minimum

maximum

Float

Only valid for non-streaming scripts.

The list of RSSI values for E2 in the following order:
RSSI_E2

average

minimum

maximum

Float

- 1007 -

IxChariot APIGuide

Attribute Name

Data
Type

What Is Returned

Only valid for streaming scripts.

List of throughput values in the following order:
THROUGHPUT

average

minimum

maximum

Float

List of transaction rate values in the following order:

TRANS_RATE

average

minimum

maximum

Float

The following table describes the pair types and protocols for which these attributes are
available. Note that CPU_UTIL_E1/2 statistics must be explicitly enabled in chrRunOpts
set.

P air ty pe
P rotocol

TCP

CONSECUTIVE_LOST

RTP

Pair

HW
Perf
Pair

RTP

N/A

VoIP

Regular Pair

Video

UDP

Pair

VoIP
HW
Perf
Pair
N/A

CPU_UTIL_E1

CPU_UTIL_E2

DELAY_FACTOR

DELAY_VARIATION

END_TO_END_DELAY

JITTER

MEDIA_LOSS_RATE

MOS_ESTIMATE

ONE_WAY_DELAY

R_VALUE

REL_PRECISION

RESP_TIME

THROUGHPUT

TRANS_RATE

X
X

X
X

- 1008 -

IxChariot APIGuide

ERROR RETURNS
l

Out of memory. (120)

Program internal error. (121)

Handle is invalid. (101)

Test was not run. (105)

API was not initialized. (113)

Results are not available. (114)

Value is invalid (115)

No such value. (116)

See Return Code Summary for a detailed description of each return code.

- 1009 -

IxChariot APIGuide

chrPairResults get95PctConfidence
DESCRIPTION
The chrPairResults get95PctConfidence subcommand gets the results of the 95 percent confidence interval for the given pair or given multicast pair object.
c hrPairR es ult s get 95Pc t C onf idenc e handle res ult Ty pe

ARGUMENTS
handle
l

For a pair, the handle returned by chrPair new or chrTest getPair.

For a multicast pair, the handle returned by chrMPair new or chrMGroup getMPair.

resultType
The type of results to return:
l

THROUGHPUT

TRANS_RATE

RESP_TIME

DELAY_FACTOR and MEDIA_LOSS_RATE.

TRANS_RATE and RESP_TIME are not valid for streaming pairs.

DELAY_FACTOR and MEDIA_LOSS_RATE are valid only for video pairs (or video multicast
pairs).

RETURNED DATA
The returned data provides the 95% confidence interval for throughput, response time,
delay, and so forth (Data type: Float).

ERROR RETURNS
The restrictions and error codes are the same as for the C API.
l

Handle is invalid. (101)

Pointer is invalid. (103)

API was not initialized. (113)

Results are not available. (114)

Value is invalid. (115)

No such value. (116)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1010 -

IxChariot APIGuide

Report Object Commands

The Report object functions handle information reported back by the endpoint that does not
fit into a timing record. There can be many types of reports, hence the ITEM_TYPE field.
The Join Latency and Leave Latency reports are used by the IPTV functions. These reports
are issued once per test iteration; many timing records may be generated during each iteration.
The REPORT_GROUP_ID field helps associate timing records with reports.

- 1011 -

IxChariot APIGuide

chrReport get
DESCRIPTION
The chrReport get subcommand gets the value for the named attribute of the given
report.
c hrR eport get report name

ARGUMENTS
report
The handle returned by chrVPair getReport.

name
The attribute to get.

NAMES
Attribu te
Name

W h at I s Retu rn ed

Data
Ty pe

ITEM_TYPE

The type of the specified report item. Only one report item is
currently defined: JOIN_LEAVE.

String

JOIN_LATENCY

The join latency value, in milliseconds, from the specified

report.

Float

LEAVE_
LATENCY

The leave latency value, in milliseconds, from the specified

report.

Float

REPORT_
GROUP_ID

The report group identifier from the specified report. The

group identifier associates timing records with reports.

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1012 -

Integer

IxChariot APIGuide

Run Options Object Command

The run options object command is used to define and retrieve information about the run
options for a specific test scenario. This command has two subcommands.

- 1013 -

IxChariot APIGuide

chrRunOpts get
DESCRIPTION
The chrRunOpts get subcommand gets the value for the attribute specified by name from
the given run options.
c hrR unOpt s get runopt s name

ARGUMENTS
runopts
The handle returned by chrTest getRunOpts.

name
The attribute to get.

RETURNED DATA
Attribu te Nam e

W h at I s Retu rn ed

Data
Ty pe

ALLOW_PAIR_
REINIT

Whether to allow pair reinitialization during the setup

phase of the test.

Boolean

ALLOW_PAIR_
REINIT_RUN

Whether to allow pair reinitialization once the test has

started running.

Boolean

APPLY_DOD_ONLY

Whether the "apply DoD only" run option is set.

Boolean

CLKSYNC_
EXTERNAL

Whether the endpoints in the test will attempt to use

external clocking as the timing source on the ixia
ports.

Boolean

CLKSYNC_
HARDWARE_TS

Whether the endpoints in the test will attempt to use

hardware timestamps as the timing source on the ixia
ports.

Boolean

COLLECT_TCP_
STATISTICS

Whether TCP statistics will be collected as part of the

IxChariot test.

Boolean

Time in minutes for which connection attempts are

CONNECT_TIMEOUT retried before it is considered an error. A value of
zero minutes means no retries are attempted.

Long

CPU_UTIL

Whether to collect endpoint CPU utilization.

Boolean

DECONFIGURE_
PORTS

Whether to release port ownership and deconfigure

ports after the test ends

Boolean

FEWER_SETUP_

Whether to use fewer connections during test ini-

Boolean

- 1014 -

IxChariot APIGuide

Attribu te Nam e

W h at I s Retu rn ed

Data
Ty pe

CONNECTIONS

tialization.

FORCE_
REPORTING_ACK

Whether to force an acknowledgement after each

report.

Boolean

HW_TIMESTAMPS

The hardware transmit timestamp. (Hardware

timestamps are used to determine the video test
source jitter and account for it in video test DF calculations.)

Long

INIT_RECV_
TIMEOUT

Time in seconds for a receive timeout for the initialization phase.

Long

MANAGEMENT_
QOS_CONSOLE_
NAME

The name of the QoS template in use for management

String
traffic sent from the console to Endpoint1.

MANAGEMENT_
QOS_ENDPOINT_
NAME

The name of the QoS template in use for (1) management traffic sent from Endpoint1 to the console,
and (2) management traffic exchanged by Endpoint1
and Endpoint2.

String

OVERLAPPED_
SENDS_COUNT

The number of buffers sent in parallel

Long

PAIR_REINIT_MAX

The maximum number of reinitialization attempts

that IxChariot will make for a pair that fails during
test initialization. This is applicable only if ALLOW_
PAIR_REINIT is True.

Long

PAIR_REINIT_MAX_
RUN

The maximum number of reinitialization attempts

that IxChariot will make for a pair that fails while a
test is running. This is applicable only if ALLOW_
PAIR_REINIT_RUN is True.

Long

P A I R _R E I N I T _
RETRY_
I NTERVAL

The ti me i nter val between the r ei ni ti al i zati on attempts that I xChar i ot wi l l

make f or a pai r that f ai l s dur i ng test
i ni ti al i zati on. Thi s i s appl i cabl e onl y i f
A L L OW _ P A I R _R E I N I T i s T r u e .

Long

The ti me i nter val between the r ei ni ti al i zati on attempts that I xChar i ot wi l l

make f or a pai r that f ai l s whi l e a test
i s r unni ng. Thi s i s appl i cabl e onl y i f
A L L OW _ P A I R _R E I N I T _ R U N i s T r u e .

Long

How to r etr i eve the ti mi ng r ecor ds.

Thi s appl i es onl y when REPORTI NG_
TYPE i s BATCH. Other wi se, i t wi l l
r e t u r n R E T R I E V E _ T I M I N G _R E C OR D .

Str i ng

P A I R _R E I N I T _
RETRY_
I N T E R V A L _R U N

POLL_
RETRI EVI NG_
TYPE

- 1015 -

IxChariot APIGuide

Attribu te Nam e

W h at I s Retu rn ed

Data
Ty pe

R A N D OM _N E W _
SEED

Whether the r andom number gener ator

is to be reseeded.

Boolean

REPORTI NG_
F I REWALL

Whether ther e i s a f i r ewal l between the

Co ns o l e a nd Endpo i nt1.

Boolean

REPORTI NG_
TYPE

How to r epor t the ti mi ng r ecor ds.

Str i ng

S T OP _A F T E R _
NU M_PAI RS_
FAIL

Number of pai r s that must f ai l to f or ce

the test to stop wi th an er r or .

Long

S T OP _ON _
I N I T _E R R

Whether the test i s to stop on i ni tialization errors.

TEST_
DU RATI ON

Ti me i n seconds test i s to r un.

T h e T E S T _D U R A T I ON v a l u e o n l y a p p l i e s
when TEST_END i s set to F I XED_
DU RATI ON.

Long

T E S T _E N D

How the test i s to end.

T h e T E S T _D U R A T I ON v a l u e o n l y a p p l i e s
when TEST_END i s set to F I XED_
DU RATI ON.

Str i ng

V A L I D A T E _ON _
RECV

Whether the data i s to be val i dated

when r ecei ved.

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Not licensed (126)

See Return Code Summary for a detailed description of each return code.

- 1016 -

Boolean

Boolean

IxChariot APIGuide

chrRunOpts getNumResultRanges
DESCRIPTION
The chrRunOpts getNumResultRanges subcommand gets the number of configured ranges
for a particular range type.
c hrR unOpt s get N umR es ult R anges runopt s res ult Ty pe

ARGUMENTS
runopts
The handle returned by chrTest getRunOpts.

resultType
The type of result range. Either CONSECUTIVE_LOST or DELAY_VARIATION.

RETURNED DATA
The number of consecutive lost datagram or jitter (delay variation) result ranges.

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1017 -

IxChariot APIGuide

chrRunOpts getResultRange
DESCRIPTION
The chrRunOpts getResultRange subcommand gets the value for the attribute specified by
name from the given run options.
c hrR unOpt s get R es ult R ange runopt s name index

ARGUMENTS
runopts
The handle returned by chrTest getRunOpts.

name
The attribute to get. Either CONSECUTIVE_LOST or DELAY_VARIATION.

index
The index of the range to be returned.

RETURNED DATA
A list of the minimum, maximum values for the specified index.

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

No such value. (106)

See Return Code Summary for a detailed description of each return code.

- 1018 -

IxChariot APIGuide

chrRunOpts set
DESCRIPTION
The chrRunOpts set subcommand sets the value for the attribute specified by name in the
given run options object. You are not allowed to set any of the run options for a test that
has results.
c hrR unOpt s s et runopt s name v alue

ARGUMENTS
runopts
The handle returned by chrTest getRunOpts.

name
The attribute to set.

value
The value to set for the given attribute.

ATTRIBUTES
Attribu te
Name

W h atI s S et

Ran ge or Max
S trin g L en gth

Data
Ty pe

ALLOW_PAIR_
REINIT

Whether to allow pair reinitialization during the setup

phase of the test.

0 = False
1 = True

Boolean

ALLOW_PAIR_
REINIT_RUN

Whether to allow pair rein0 = False

itialization once the test has star1 = True
ted running.

Boolean

APPLY_DOD_ONLY

When TRUE, enables the "Apply

only Endpoint DoD package" run
option. When FALSE, disables the
option.

0 = False
1 = True

Boolean

0 = False
1 = True

Boolean

When set to TRUE,

DECONFIGURE_PORTS is automatically set to FALSE.

CLKSYNC_
EXTERNAL

Whether the endpoints in the test

will use external clocking clocking as the timing source on the
Ixia ports.
When both hardware timestamps
and external clocking are set as
the timing source on the Ixia

- 1019 -

IxChariot APIGuide

Attribu te
Name

W h atI s S et

Ran ge or Max
S trin g L en gth

Data
Ty pe

ports, IxChariot first attempts to

use hardware timestamps. If the
Ixia port hardware timestamp is
not available to a specific endpoint pair, that pair will use the
external clock source. When only
external clocking is set, all pairs
obtain their timing values from
the external timing source.
Whether the endpoints in the test
will attempt to use hardware
timestamps as the timing source
on the ixia ports.

CLKSYNC_
HARDWARE_TS

COLLECT_TCP_
STATISTICS

When both hardware timestamps

and external clocking are set as
the timing source on the Ixia
ports, IxChariot first attempts to
use hardware timestamps. If the
Ixia port hardware timestamp is
not available to a specific endpoint pair, that pair will use the
external clock source. When only
external clocking is set, all pairs
obtain their timing values from
the external timing source.

0 = False
1 = True

The option that determines

whether TCP statistics will be collected as part of the IxChariot
test.
0 = False
1 = True
Refer to "Miscellaneous Run

Boolean

Boolean

Options" in the IxChariot User

Guide for more information
about collecting TCP statistics.
CONNECT_
TIMEOUT

Time in minutes waited for a connection before it is considered an 1 to 999

error.

Long

CPU_UTIL

Whether to collect CPU utilization

by the endpoints.

0 = False
1 = True

Boolean

0 = False
1 = True

Boolean

DECONFIGURE_
PORTS

When TRUE, enables the "Deconfigure ports" run option. When

FALSE, disables the option.
Fails when set to TRUE, if APPLY_
DOD_ONLY is already set to

- 1020 -

IxChariot APIGuide

Attribu te
Name

W h atI s S et

Ran ge or Max
S trin g L en gth

Data
Ty pe

TRUE.
F EWER_SETU P
_
CONNECTI ONS

Whether to use f ewer

connecti ons dur i ng test
i ni ti al i zati on.

0 = False
1 = Tr ue

Boolean

F ORCE_
REPORTI NG_
ACK

Whether to f or ce an
acknowl edgement af ter
each report.

0 = False
1 = Tr ue

Boolean

HW_
TI MESTAMPS

Whether to use har dwar e tr ansmi t

timestamps. (Hardware
ti mestamps ar e used to
deter mi ne the vi deo
test sour ce j i tter and
account f or i t i n vi deo
test DF cal cul ati ons.)

0 = False
1 = Tr ue

Boolean

I N I T _R E C V _
TI MEOU T

Ti me i n seconds f or a
r ecei ve ti meout f or the
i ni ti al i zati on phase.

1 to 999

Long

MANAGEMENT_
QOS_
CONSOLE_
NAME

The name of the QoS

templ ate to use f or management tr af f i c sent
f r om the consol e to
Endpo i nt1.

The str i ng has

a maxi mum
l ength of 64
char acter s.

Str i ng

MANAGEMENT_
QOS_
ENDPOI NT_
NAME

The name of the QoS

templ ate to use f or (1)
management tr af f i c sent
f r o m Endpo i nt1 to the
consol e, and (2) management tr af f i c
e x c ha nge d by Endpo i nt1
a nd Endpo i nt2.

The str i ng has

a maxi mum
l ength of 64
char acter s.

Str i ng

The number of buf f er s

sent i n par al l el .

2 to 999999

Long

The maxi mum number of

r ei ni ti al i zati on attempts
that I xChar i ot wi l l make
f or a pai r that f ai l s dur i ng test i ni ti al i zati on.
Thi s i s appl i cabl e onl y
i f A L L OW _ P A I R _R E I N I T
i s Tr ue.

1 to 99999

Long

OVERLAPPED_
SENDS_COU NT

P A I R _R E I N I T _
MAX

- 1021 -

IxChariot APIGuide

Attribu te
Name

W h atI s S et

P A I R _R E I N I T _
MAX_RU N

The maxi mum number of

r ei ni ti al i zati on attempts
that I xChar i ot wi l l make
f or a pai r that f ai l s
whi l e a test i s r unni ng.
Thi s i s appl i cabl e onl y
i f A L L OW _ P A I R _R E I N I T _
RU N i s Tr ue.

1 to 99999

Long

P A I R _R E I N I T _
RETRY_
I NTERVAL

The ti me i nter val

between the r ei nitialization attempts
that I xChar i ot wi l l make
f or a pai r that f ai l s dur i ng test i ni ti al i zati on.
Thi s i s appl i cabl e onl y
i f A L L OW _ P A I R _R E I N I T _
RU N i s Tr ue.

1 to 99999

Long

P A I R _R E I N I T _
RETRY_
I NTERVAL_
RUN

The ti me i nter val

between the r ei nitialization attempts
that I xChar i ot wi l l make
f or a pai r that f ai l s
whi l e a test i s r unni ng.
Thi s i s appl i cabl e onl y
i f A L L OW _ P A I R _R E I N I T _
RU N i s Tr ue.

1 to 99999

Long

POLL_
ENDPOI NTS

Whether to pol l the endpoi nts.

The POLL_I NTERVAL
val ue onl y appl i es when
POLL_ENDPOI NTS i s set
to Tr ue (1).

0 = False
1 = Tr ue

Boolean

P OL L _T I M E

I nter val i n mi nutes used

when endpoi nts ar e to
be polled.
The POLL_I NTERVAL
val ue onl y appl i es when
POLL_ENDPOI NTS i s set
to Tr ue (1).

1 to 9999

Long

POLL_
RETRI EVI NG_
TYPE

How to r etr i eve the ti mi ng r ecor ds. Thi s onl y

appl i es when
REPORTI NG_TYPE i s
BATCH, other wi se wi l l
r etur n RETRI EVE_

one of the f ol l owi ng:

RETRI EVE_
Str i ng
NU MBER,
RETRI EVE_
TI MI NG_

- 1022 -

Ran ge or Max
S trin g L en gth

Data
Ty pe

IxChariot APIGuide

Attribu te
Name

W h atI s S et

Ran ge or Max
S trin g L en gth

Data
Ty pe

TI MI NG_RECORD

RECORD

Whether the r andom

number gener ator i s to
be reseeded.

0 = False
1 = Tr ue

Whether ther e i s a f i r ewal l between the Consol e and Endpoi nt 1.

one of the f ol l owi ng:

F I REWALL_
Str i ng
U SE,
F I REWALL_
DONT_U SE

REPORTI NG_
TYPE

How to r epor t the ti mi ng r ecor ds.

one of the f ol l owi ng:

Str i ng
BATCH,
REALTI ME

S T OP _A F T E R _
NU M_PAI RS_
FAIL

Number of pai r s that

must f ai l to f or ce the
test to stop with an
error.

1 to 9999

Long

S T OP _ON _
I N I T _E R R

Whether the test i s to

stop on i ni ti al i zati on
errors.

0 = False
1 = Tr ue

Boolean

TEST_
DU RATI ON

Ti me i n seconds test i s
to r un.
The TEST_DU RATI ON
val ue onl y appl i es when
TEST_END i s set to
F I XED_DU RATI ON.

1 to 359999

Long

T E S T _E N D

How the test i s to end.

The TEST_DU RATI ON
val ue onl y appl i es when
TEST_END i s set to
F I XED_DU RATI ON.

one of the f ol l owi ng:

F I XED_
DU RATI ON,
Str i ng
WHEN_ALL_
COMPLETE,
WHEN_F I RST_
COMPLETES

VALI DATE_
O N _R E C V

Whether the data i s to

be val i dated when i t i s
received.

0 = False
1 = Tr ue

RANDOM_
NEW_SEED

REPORTI NG_
F I REWALL

RETURNED DATA
None

- 1023 -

Boolean

Boolean

IxChariot APIGuide

ERROR RETURNS
l

Not licensed (126)

See Return Code Summary for a detailed description of each return code.

- 1024 -

IxChariot APIGuide

chrRunOpts setNumResultRanges
DESCRIPTION
The chrRunOpts setNumResultRanges subcommand sets the number of ranges into which
different statistics are placed in VoIP test results.
c hrR unOpt s s et N umR es ult R anges runopt s res ult Ty pe number

ARGUMENTS
runopts
The handle returned by chrTest getRunOpts.

resultType
The desired result type. One of the following:
l

DELAY_VARIATION

CONSECUTIVE_LOST

If other CHR_RESULTS values are specified, the call returns CHR_VALUE_INVALID.

number
The number of configurable ranges to set. The maximum number of configurable ranges is
5 for CHR_RESULTS_DELAY_VARIATION and CHR_RESULTS_CONSECUTIVE_LOST. Ranges
must be contiguous. If a number of ranges is set that interferes with the contiguity of configured ranges, ranges are adjusted to be contiguous.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1025 -

IxChariot APIGuide

chrRunOpts setResultRange
DESCRIPTION
The chrRunOpts setResultRange subcommand sets the minimum and maximum values for
a specific index in a result range.
c hrR unOpt s s et R es ult R ange name index

ARGUMENTS
runopts
The handle returned by chrTest getRunOpts.

name
The result type to set. See "Attributes."

index
The index of the range value to set. The index value can be a value from 0 to the number
of configured ranges1, for a specified result type.
The number of configured ranges can be determined using chrRunOpts getnumResultRanges.

min
The minimum value for this particular range. All ranges must be increasing and contiguous. This value is currently ignored and is set to the previous range's maximum value
+ 1.

max
The maximum value for this particular range. Ranges must be contiguous. If a change is
made to the maximum range that ends the contiguity of the lower ranges, the lower
ranges are adjusted to be contiguous.

ATTRIBUTES
Attribu te Nam e

W h at I s Retu rn ed

Ran ge or
Max S trin g

Data
Ty pe

CONSECUTIVE_
LOST

The minimum and maximum values

for the specified index for the
CONSECUTIVE_LOST range.

1-9999999

Long

DELAY_VARIATION

The minimum and maximum values

for the specified index for the DELAY_
VARIATION range.

0-99999

Long

ERROR RETURNS
l

Handle is invalid. (101)

- 1026 -

IxChariot APIGuide

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1027 -

IxChariot APIGuide

Test Object Command

The test object command is used to define and retrieve information about a test and to control the running of a test.

- 1028 -

IxChariot APIGuide

chrTest abandon
DESCRIPTION
The chrTest abandon subcommand abandons running the given object test. This command
can and usually does return before the test has stopped. Use chrTest isStopped to determine when the object test has actually stopped.
This subcommand should be used as a last resort to stop a test, as it can prevent some test
resources from being relinquished. Always try chrTest stop first to stop a test.
chrTest abandon test

ARGUMENTS
test
The handle returned by chrTest new.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Test was not run. (105)

API was not initialized. (113)

Value is invalid (115)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1029 -

IxChariot APIGuide

chrTest addAppGroup
DESCRIPTION
The chrAppGroup save subcommand adds the given application group to the given test.
You are not allowed to add application groups to a test that has results. An application
group handle can be added to only one test, and can be added only once to that test. Extended error information is available for this subcommand.
c hrTes t addAppGroup t es t appGroup

ARGUMENTS
test
The handle returned by chrTest new.

appGroup
The handle for the application group, returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

Results were not cleared. (110)

Pair limit would be exceeded. (111)

Object is invalid. (112)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Script too large (127)

See Return Code Summary for a detailed description of each return code.

- 1030 -

IxChariot APIGuide

chrTest addChannel
DESCRIPTION
The chrTest addChannel subcommand adds the given IPTV channel object to the given
test.
c hrTes t addC hannel t es t c hannel

ARGUMENTS
test
The handle returned by chrTest new.

channel
The handle returned by chrChannel new.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

Results were not cleared. (110)

Pair limit would be exceeded. (111)

Object is invalid. (112)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Script too large (127)

Duplicate channel name. (140)

See Return Code Summary for a detailed description of each return code.

- 1031 -

IxChariot APIGuide

chrTest addMGroup
DESCRIPTION
The chrTest addMGroup subcommand adds the given multicast group to the given test. You
are not allowed to add multicast groups to a test that has results. A multicast group handle
can only be added to one test, and can only be added once to that test. Extended error
information is available for this subcommand.
c hrTes t addMGroup t es t mgroup

ARGUMENTS
test
The handle returned by chrTest new.

mgroup
The handle returned by chrMGroup new or chrTest getMGroup.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

Results were not cleared. (110)

Pair limit would be exceeded. (111)

Object is invalid. (112)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Script too large (127)

See Return Code Summary for a detailed description of each return code.

- 1032 -

IxChariot APIGuide

chrTest addPair
DESCRIPTION
The chrTest addPair subcommand adds the given pair to the given test. You are not
allowed to add pairs to a test that has results. A pair handle can only be added to one test,
and can only be added once to that test. Extended error information is available for this
subcommand.
c hrTes t addPair t es t pair

ARGUMENTS
test
The handle returned by chrTest new.

pair
The handle returned by chrPair new or chrTest getPair.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

Results were not cleared. (110)

Pair limit would be exceeded. (111)

Object is invalid. (112)

API was not initialized. (113)

Value is invalid. (115)

Out of memory. (120)

Program internal error. (121)

Script too large (127)

See Return Code Summary for a detailed description of each return code.

- 1033 -

IxChariot APIGuide

chrTest addReceiver
DESCRIPTION
The chrTest addReceiver subcommand adds the given IPTV receiver object to the given
test.
c hrTes t addR ec eiv er t es t rec eiv er

ARGUMENTS
test
The handle returned by chrTest new.

receiver
The handle returned by chrReceiver new.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

Results were not cleared. (110)

Pair limit would be exceeded. (111)

Object is invalid. (112)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Script too large (127)

Duplicate receiver name. (141)

See Return Code Summary for a detailed description of each return code.

- 1034 -

IxChariot APIGuide

chrTest clearIxiaConfiguration
DESCRIPTION
The chrTest clearIxiaConfiguration $test subcommand clears (unloads) an Ixia network configuration from the specified test.
c hrTes t c learI x iaC onf igurat ion t es t

ARGUMENTS
test
The handle returned by chrTest new.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Test is running. (106)

Operation has failed. (108)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1035 -

IxChariot APIGuide

chrTest clearResults
DESCRIPTION
The chrTest clearResults subcommand clears all results from the test, the multicast pairs
in its multicast groups, and its pairs. A test object cannot be deleted, pairs and multicast
groups cannot be added to the test, the associated run options and datagram options cannot be set, and a test cannot be loaded using an existing test handle if the test contains results.
c hrTes t c learR es ult s t es t

ARGUMENTS
test
The handle returned by chrTest new.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1036 -

IxChariot APIGuide

chrTest delete
DESCRIPTION
The chrTest delete subcommand frees all memory associated with the given test object,
including that associated with any objects owned by this test. This is necessary because
the Tcl interpreter has no access to the associated structures supporting the object. A test
cannot be deleted if it has not been saved. A test must be stopped before it can be deleted.
c hrTes t delet e t es t ?f orc e?

ARGUMENTS
test
The handle returned by chrTest new.

force
A literal to signal forced deletion (optional). Use the force option to force deletion of the
test whether it has been saved or not.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

Operation has failed. (108)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Test not saved (135)

See Return Code Summary for a detailed description of each return code.

- 1037 -

IxChariot APIGuide

chrTest get
DESCRIPTION
The chrTest get subcommand gets the value for the attribute specified by name from the
given test.
c hrTes t get t es t name ret urnVar

ARGUMENTS
test
The handle returned by chrTest new.

name
The attribute to get.

returnVar
An optional variable used only with the IXIA_NETWORK_CONFIGURATION attribute (see
below). The return value is placed into this variable.

RETURNED DATA
Attribu te Nam e

W h at I s Retu rn ed

Data
Ty pe

FILENAME

Name of the file in which the test is (to be) stored

String

IXIA_NETWORK_
CONFIGURATION

The Ixia network configuration associated with the test.

Byte *

THROUGHPUT_
UNITS

Throughput units

String

When the test was started. Formatted as character

string (month day year hh:mm:ss).

String

LOCAL_STOP_TIME

When the test was stopped. Formatted as character

string (month day year hh:mm:ss).

String

START_TIME

When the test was started. START_TIME may return

"Test was not run" or "No such value."

Long *

STOP_TIME

When the test was stopped.

Long *

HOW_ENDED

How the test was ended. HOW_ENDED

may r etur n "U ser Stopped," "Er r or ," or
"Normal".

Long

LOCAL_START_TIME

The value returned for START_TIME and STOP_TIME is the number of seconds
since midnight, January 1, 1970 (i.e., a "::time::unixtime" value).

- 1038 -

IxChariot APIGuide

ERROR RETURNS
l

Handle is invalid. (101)

Test was not run. (105)

Test is running. (106)

API was not initialized. (113)

No such value. (116)

Out of memory. (120)

Program internal error. (121)

No network configuration was found (129)

Error accessing test server session (131)

Function not supported (132)

See Return Code Summary for a detailed description of each return code.

- 1039 -

IxChariot APIGuide

chrTest getAppGroupByIndex
DESCRIPTION
The chrAppGroup getAppGroupByIndex subcommand gets the handle for a specific application group in the given test. The handle returned by this subcommand is needed for other
subcommands to operate on the object.
c hrTes t get AppGroupBy I ndex t es t index

ARGUMENTS
test
The handle returned by chrTest new.

index
An index into the application group list. The index is determined by the order in which
application groups were added to this test.

RETURNED DATA
The returned data provides the handle to a application group object.

ERROR RETURNS
l

Handle is invalid. (101)

Pointer invalid. (103)

No such object. (104)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1040 -

IxChariot APIGuide

chrTest getAppGroupByName
DESCRIPTION
The chrAppGroup getAppGroupByName subcommand gets the handle for a specific application group in the given test. The handle returned by this subcommand is needed for other
subcommands to operate on the object.
c hrTes t get AppGroupBy N ame t es t name

ARGUMENTS
test
The handle returned by chrTest new.

name
A string containing the name of the application group.

RETURNED DATA
The returned data provides the handle to a application group object.

ERROR RETURNS
l

Handle is invalid. (101)

String too long. (102

Pointer invalid. (103)

No such object. (104)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1041 -

IxChariot APIGuide

chrTest getAppGroupCount
DESCRIPTION
The chrAppGroup getAppGroupCount subcommand gets the number of application groups
owned by the given test.
c hrTes t get AppGroupC ount t es t

ARGUMENTS
test
The handle returned by chrTest new.

RETURNED DATA
The returned data provides the of application group object contained in the test (data type:
Long).

ERROR RETURNS
l

Handle is invalid. (101)

Pointer invalid. (103)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1042 -

IxChariot APIGuide

chrTest getChannel
DESCRIPTION
The chrTest getChannel subcommand gets the handle for a specific IPTV channel in the
given test. The handle returned by this subcommand is needed for other subcommands to
operate on the object.
c hrTes t get C hannel t es t index

ARGUMENTS
test
The handle returned by chrTest new.

index
Index of the item in the list of channel objects, in the following range:
0..channel_count-1.

RETURNED DATA
The returned data provides the handle of the IPTV channel object.

ERROR RETURNS
l

Handle is invalid. (101)

No such object. (104)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1043 -

IxChariot APIGuide

chrTest getChannelByName
DESCRIPTION
The chrTest getChannelByName subcommand gets the handle for a specific IPTV channel
in the given test. The handle returned by this subcommand is needed for other subcommands to operate on the object.
c hrTes t get C hannelBy N ame t es t name

ARGUMENTS
test
The handle returned by chrTest new.

name
A string containing the name of the IPTV channel.

RETURNED DATA
The returned data provides the handle of the IPTV channel object.

ERROR RETURNS
l

Handle is invalid. (101)

String too long. (102)

Pointer invalid. (103)

No such object. (104)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1044 -

IxChariot APIGuide

chrTest getChannelCount
DESCRIPTION
The chrTest getChannelCount subcommand returns the number of IPTV channel objects
owned by the given test.
c hrTes t get C hannelBy N ame t es t

ARGUMENTS
test
The handle returned by chrTest new.

RETURNED DATA
The returned data provides a count of IPTV channel objects owned by the given test (data
type: Long).

ERROR RETURNS
l

Handle is invalid. (101)

Pointer invalid. (103)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1045 -

IxChariot APIGuide

chrTest getDgOpts
DESCRIPTION
The chrTest getDgOpts subcommand gets the handle to the datagram options for the given
test. The handle returned by this subcommand is needed for other subcommands to operate on the object.
c hrTes t get D gOpt s t es t

ARGUMENTS
test
The handle returned by chrTest new.

RETURNED DATA
The returned data provides the handle to the associated datagram options object.

ERROR RETURNS
The following return codes indicate that an error occurred and any returned data should be
ignored:
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1046 -

IxChariot APIGuide

chrTest getGroupingOrder
DESCRIPTION
The chrTest getGroupingOrder subcommand gets the grouping order, for grouping endpoints in the test.
c hrTes t get GroupingOrder t es t s ort Order

ARGUMENTS
test
The handle returned by chrTest new.

RETURNED DATA
The returned data provides the grouping order, for grouping endpoints in the test.

ERROR RETURNS
The following return codes indicate that an error occurred and any returned data should be
ignored:
l

Handle is invalid. (101)

API was not initialized. (113)

Operation failed (108)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1047 -

IxChariot APIGuide

chrTest getGroupingType
DESCRIPTION
The chrTest getGroupingType subcommand gets the grouping type, for grouping endpoints
in the test.
c hrTes t get GroupingTy pe t es t groupingTy pe

ARGUMENTS
test
The handle returned by chrTest new.

RETURNED DATA
The returned data provides the grouping type, for grouping endpoints in the test.

ERROR RETURNS
The following return codes indicate that an error occurred and any returned data should be
ignored:
l

Handle is invalid. (101)

API was not initialized. (113)

Operation failed (108)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1048 -

IxChariot APIGuide

chrTest getMGroup
DESCRIPTION
The chrTest getMGroup subcommand gets the handle for a specific multicast in the given
test. The handle returned by this subcommand is needed for other subcommands to operate on the object.
c hrTes t get MGroup t es t index

ARGUMENTS
test
The handle returned by chrTest new.

index
An index into the multicast group list. The index is determined by the order in which multicast groups were added to this test.

RETURNED DATA
The returned data provides the handle to a multicast group object.

ERROR RETURNS
l

Handle is invalid. (101)

No such object. (104)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1049 -

IxChariot APIGuide

chrTest getMGroupCount
DESCRIPTION
The chrTest getMGroupCount subcommand gets the number of multicast groups owned by
the given test.
c hrTes t get MGroupC ount t es t

ARGUMENTS
test
The handle returned by chrTest new.

RETURNED DATA
The returned data provides the number of multicast groups (Data type: Long).

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1050 -

IxChariot APIGuide

chrTest getPair
DESCRIPTION
The chrTest getPair subcommand gets the handle for a specific pair in the given test. The
handle returned by this subcommand is needed for other subcommands to operate on the
object.
c hrTes t get Pair t es t index

ARGUMENTS
test
The handle returned by chrTest new.

index
An index into the pairs list. An index is determined by the order in which pairs were added
to this test.

RETURNED DATA
The returned data provides the handle to a pair object.

ERROR RETURNS
l

Handle is invalid. (101)

No such object. (104)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1051 -

IxChariot APIGuide

chrTest getPairCount
DESCRIPTION
The chrTest getPairCount subcommand gets the number of pairs owned by the given test.
c hrTes t get PairC ount t es t

ARGUMENTS
test
The handle returned by chrTest new.

RETURNED DATA
The returned data provides the number of pairs (Data type: Long).

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1052 -

IxChariot APIGuide

chrTest getReceiver
DESCRIPTION
The chrTest getReceiver subcommand gets the handle for a specific IPTV receiver in
the given test. The handle returned by this subcommand is needed for other subcommands
to operate on the object.
c hrTes t get R ec eiv er t es t index

ARGUMENTS
test
The handle returned by chrTest new.

index
Index of the item in the list of receiver objects, in the following range:
0..receiver_count-1.

RETURNED DATA
The returned data provides the handle of the IPTV receiver object.

ERROR RETURNS
l

Handle is invalid. (101)

No such object. (104)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1053 -

IxChariot APIGuide

chrTest getReceiverByName
DESCRIPTION
The chrTest getReceiverByName subcommand gets the handle for a specific IPTV
receiver in the given test. The handle returned by this subcommand is needed for other
subcommands to operate on the object.
c hrTes t get R ec eiv erBy N ame t es t name

ARGUMENTS
test
The handle returned by chrTest new.

name
A string containing the name of the IPTV receiver.

RETURNED DATA
The returned data provides the handle of the IPTV receiver object.

ERROR RETURNS
l

Handle is invalid. (101)

String too long. (102)

Pointer invalid. (103)

No such object. (104)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1054 -

IxChariot APIGuide

chrTest getReceiverCount
DESCRIPTION
The chrTest getReceiverCount subcommand returns the number of IPTV receiver
objects owned by the given test.
c hrTes t get R ec eiv erBy N ame t es t

ARGUMENTS
test
The handle returned by chrTest new.

RETURNED DATA
The returned data provides a count of IPTV receiver objects owned by the given test (data
type: Long).

ERROR RETURNS
l

Handle is invalid. (101)

Pointer invalid. (103)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1055 -

IxChariot APIGuide

chrTest getTestServerSession
DESCRIPTION
The chrTest getTestServerSession subcommand gets the TestServer address, port,
and object ID for the active Aptixia session.
c hrTes t get Tes t Serv erSes s ion t es t o_t es t Serv erAddres s o_
t es t Serv erPort o_s es s ionObjec t I d

ARGUMENTS
test
The handle returned by chrTest new.

o_testServer-Address
The returned address of TestServer.

o_testServer-Port
The returned TCP port of the TestServer.

o_sessionObject-Id
The returned session object ID.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Error accessing TestServer session. (131)

Function not supported. (132)

Error code 132 is returned if the Tcl shell is lower than revision level 8.4.
See Return Code Summary for a detailed description of each return code.

- 1056 -

IxChariot APIGuide

chrTest isStopped
DESCRIPTION
The chrTest isStopped subcommand waits until the test is stopped or the timeout is
reached.
c hrTes t is St opped t es t ?t imeout ?

ARGUMENTS
test
The handle returned by chrTest new.

timeout
The time in seconds to wait for the test to stop or CHR_INFINITE (optional). If timeout is
not provided, this subcommand returns immediately with the test status.

RETURNED DATA
The returned data provides True (1) if the test is stopped; False (0) if the timeout has
expired.

ERROR RETURNS
l

Handle is invalid. (101)

Test was not run. (105)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1057 -

IxChariot APIGuide

chrTest load
DESCRIPTION
The chrTest load subcommand loads a test. This subcommand uses the run options that
have been defined for the test.
c hrTes t load t es t f ilename
Extended error information is available for this subcommand.

ARGUMENTS
test
The handle returned by chrTest new.

filename
The name of the file from which to load the test (Data type: String, max 1024 characters).
The filename may be specified with a full or relative pathname.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Object is in use. (107)

Operation has failed. (108)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1058 -

IxChariot APIGuide

chrTest loadAppGroups
DESCRIPTION
The chrAppGroup loadAppGroups subcommand loads an application group test. Extended
error information is available for this subcommand.
c hrTes t loadAppGroups t es t f ilename

ARGUMENTS
test
The handle returned by chrTest new.

filename
The name of the file from which to load the application group test (Data type: String, max
1024 characters). The filename may be specified with a full or relative pathname.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Object is in use. (107)

Operation has failed. (108)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1059 -

IxChariot APIGuide

chrTest loadIxiaConfiguration
DESCRIPTION
The chrTest loadIxiaConfiguration subcommand loads an Ixia network configuration
into the specified test.
c hrTes t loadI x iaC onf igurat ion t es t f ilename

ARGUMENTS
test
The handle returned by chrTest new.

filename
The name of the file from which the Ixia network configuration is loaded. The filename
may be specified with a full or relative pathname.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Test is running (106)

Object is in use. (107)

Operation has failed. (108)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Invalid network configuration (130)

See Return Code Summary for a detailed description of each return code.

- 1060 -

IxChariot APIGuide

chrTest new
DESCRIPTION
The chrTest new subcommand creates a test object and initializes it to default values. This
includes the run options and datagram options objects associated with this test. Note that
the object default values do not use the default values specified in the IxChariot Options
Menu. See "Test Object" for a list of the default values.
c hrTes t new

ARGUMENTS
None

RETURNED DATA
The returned data provides the handle to a test object. The handle returned by this subcommand is needed for other subcommands to operate on the object.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1061 -

IxChariot APIGuide

chrTest removeAppGroup
DESCRIPTION
The chrAppGroup removeAppGroup subcommand removes an application group from a
test. Extended error information is available for this subcommand.
c hrTes t remov eAppGroup t es t appGroup

ARGUMENTS
test
The handle returned by chrTest new.

appGroup
The handle for the application group, returned by chrAppGroup new,
chrTestgetAppGroupByIndex, or chrTestgetAppGroupByName.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

Pointer invalid. (103)

Test running. (106)

Object is in use. (107)

Results not cleared. (110)

Pair limit exceeded. (111)

Object invalid. (112)

API was not initialized. (113)

Value invalid. (115)

Out of memory. (120)

Program internal error. (121)

Script too large. (127)

See Return Code Summary for a detailed description of each return code.

- 1062 -

IxChariot APIGuide

chrTest removeChannel
DESCRIPTION
The chrTest removeChannel subcommand removes the specified IPTV channel from a test.
c hrTes t remov eC hannel t es t c hannel

ARGUMENTS
test
The handle returned by chrTest new.

channel
The handle returned by chrChannel new, chrTest getChannel, or
chrTestgetChannelByName.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

No such object. (104)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1063 -

IxChariot APIGuide

chrTest removeReceiver
DESCRIPTION
The chrTest removeReceiver subcommand removes the specified IPTV receiver from a
test.
c hrTes t remov eR ec eiv er t es t rec eiv er

ARGUMENTS
test
The handle returned by chrTest new.

receiver
The handle returned by chrReceiver new, chrTest getReceiver, or chrTestgetReceiver
ByName.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

No such object. (104)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1064 -

IxChariot APIGuide

chrTest save
DESCRIPTION
The chrTest save subcommand saves the given test. A test must have at least one pair,
multicast group, or application group added to it before it can be saved. Extended error
information is available for this subcommand.
c hrTes t s av e t es t ?f ilename?

ARGUMENTS
test
The handle returned by chrTest new.

filename
The name of the file to which to save the test (optional). The filename may be specified
with a full or relative pathname. If the filename is not specified, the test is saved to the file
specified in the test object to which the test handle refers. (Data type: String, max 300
characters)

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Pointer is invalid. (103)

Test is running. (106)

Operation has failed. (108)

No test file. (109)

Object is invalid. (112)

API was not initialized. (113)

Value is invalid. (115)

Out of memory. (120)

Program internal error. (121)

IPTV invalid. (142)

See Return Code Summary for a detailed description of each return code.

- 1065 -

IxChariot APIGuide

chrTest saveIxiaConfiguration
DESCRIPTION
The chrTest saveIxiaConfiguration subcommand exports an Ixia network configuration from the specified test to a file.
c hrTes t s av eI x iaC onf igurat ion t es t f ilename

ARGUMENTS
test
The handle returned by chrTest new.

filename
The name of the file to which the Ixia network configuration is exported. The filename may
be specified with a full or relative pathname.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Test is running. (106)

Operation has failed. (108)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

No network configuration was found (129)

No network configuration (129)

See Return Code Summary for a detailed description of each return code.

- 1066 -

IxChariot APIGuide

chrTest set
DESCRIPTION
The chrTest set subcommand sets the value for the attribute specified by name in the
given test.
c hrTes t s et t es t name v alue

ARGUMENTS
test
The handle returned by chrTest new.

name
The attribute to set.

value
The value to set for the given attribute.

RETURNED DATA
None

ATTRIBUTES
Attribu te
Name

FILENAME

What Is Set

Name of the f i l e i n
whi ch the test i s (to be)
stored.

Ran ge or Max
S trin g L en gth

Data
Ty pe

300

String

One of the following:

UNIT_KB
UNIT_kB
UNIT_Kb
UNIT_kb
UNIT_Mb

String

N/A

Byte *

The filename may be specified

with a full or relative pathname.

THROUGHPUT_
UNITS

Throughput units.

IXIA_NETWORK_
The Ixia network configuration is
CONFIGURATION
applied to the specified test.

ERROR RETURNS
l

Handle is invalid. (101)

- 1067 -

IxChariot APIGuide

String is too long. (102)

Test is running (106)

Operation has failed (108)

API was not initialized. (113)

Value is invalid. (115)

Out of memory. (120)

Program internal error. (121)

Invalid network configuration (130)

Error accessing test server session (131)

Function not supported (132)

See Return Code Summary for a detailed description of each return code.

- 1068 -

IxChariot APIGuide

chrTest setGroupingOrder
DESCRIPTION
The chrTest setGroupingOrder subcommand sets the grouping order, for grouping endpoints in the test.
c hrTes t s et GroupingOrder t es t s ort Order

ARGUMENTS
test
The handle returned by chrTest new.

sortOrder
sortOrder can have one of the following values:
l

ORDER_ASCENDING

ORDER_DESCENDING

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Value invalid (115)

Operation failed (108)

Test running (106)

See Return Code Summary for a detailed description of each return code.

- 1069 -

IxChariot APIGuide

chrTest setGroupingType
DESCRIPTION
The chrTest setGroupingType subcommand sets the grouping type, for grouping endpoints in the test.
c hrTes t s et GroupingTy pe t es t groupingTy pe

ARGUMENTS
test
The handle returned by chrTest new.

groupingType
groupingType can have one of the following values:
l

NO_GROUPING

ENDPOINT1

ENDPOINT2

PROTOCOL

SCRIPT

E1_SERVICE_QUALITY

E2_SERVICE_QUALITY

USER_GROUP

PAIR_COMMENT

CONSOLE_E1_ADDR

E1_E2_ADDR

RUN_STATUS

DYNAMIC_E1_MGMT

DYNAMIC_E2_MGMT

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Value invalid (115)

Operation failed (108)

Test running (106)

See Return Code Summary for a detailed description of each return code.

- 1070 -

IxChariot APIGuide

chrTest setTestServerSession
DESCRIPTION
The chrTest setTestServerSession subcommand associates the test with an active session on the TestServer.
c hrTes t s et Tes t Serv erSes s ion t es t t es t Serv erAddres s
t es t Serv erPort s es s ionObjec t I d

ARGUMENTS
test
The handle returned by chrTest new.

testServerAddress
IP address of the TestServer.

testServerPort
TCP port of the TestServer.

sessionObjectId
The session object ID to set.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

No memory. (120)

Error accessing TestServer session. (131)

Function not supported. (132)

Error code 132 is returned if the Tcl shell is lower than revision level 8.4.
See Return Code Summary for a detailed description of each return code.

- 1071 -

IxChariot APIGuide

chrTest start
DESCRIPTION
The chrTest start subcommand starts running the given test.
c hrTes t s t art t es t

Usage Notes
l

Only one test may be running at a time on a computer.

All results from a previous run of this test are cleared when the test is started.

Before it can be started, the test must have at least one pair or multicast group.

If the test includes an application group, this function will validate the application
group before starting the test. The function will return CHR_APP_GROUP_INVALID if
the validation fails.

ARGUMENTS
test
The handle returned by chrTest new.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Test is running. (106)

Operation has failed (108)

Object is invalid. (112)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Not licensed. (126)

Application Group is invalid. (136)

IPTV is invalid. (142)

See Return Code Summary for a detailed description of each return code.

- 1072 -

IxChariot APIGuide

chrTest stop
DESCRIPTION
The chrTest stop subcommand stops running the given test. This command can and usually
does return before the test has stopped. Use chrTest isStopped to determine when the test
has actually stopped.
c hrTes t s t op t es t

ARGUMENTS
test
The handle returned by chrTest new.

RETURNED DATA
None

ERROR RETURNS
l

Out of memory. (120)

Program internal error. (121)

Handle is invalid. (101)

API was not initialized. (113)

See Return Code Summary for a detailed description of each return code.

- 1073 -

IxChariot APIGuide

Timing Record Object Command

The timing record object command is used to obtain test results that are unique to pair and
multicast pair timing records. This command has one subcommand.

- 1074 -

IxChariot APIGuide

chrTimingRec get
DESCRIPTION
The chrTimingRec get subcommand gets the results of the given type from the given timing record.
c hrTimingR ec get t rec ord t y pe

ARGUMENTS
trecord
The handle returned by chrPair getTimingRecord or chrMPair getTimingRecord.

type
The type of results to return.

RETURNED DATA
Resu lts Ty pe

W h at I s Retu rn ed

Data
Ty pe

BSSID_E1

BSSID for the endpoint 1 Access Point. Only valid for

non-streaming scripts.

String

BSSID_E2

BSSID for the endpoint 2 Access Point. Only valid for

streaming scripts.

String

DELAY_FACTOR

The Delay Factor, a video test measure of the maximum

difference between the arrival of media data and the
drain of that data, measured at the end of each media
stream packet. The Delay Factor indicates the amount of
time it takes to drain the buffer.

Float

ELAPSED_TIME

Elapsed time in seconds.

Float

END_TO_END_
DELAY

End-to-end delay measured in milliseconds. The measured one-way delay plus all other delays (packetization
delay, jitter buffer delay, and any additional delay configured in the pair).

Long

INACTIVE_TIME

Inactive time in seconds.

Float

JITTER_TIME

RFC 1889 Jitter time in seconds.

Float

MAX_
CONSECUTIVE_
LOST

Consecutive lost datagrams--maximum number of occurFloat

rences.

MAX_DELAY_
VARIATION

Maximum jitter (delay variation) in milliseconds.

Float

MEDIA_LOSS_RATE

Media Loss Rate, a video test measure of the number of

Float

- 1075 -

IxChariot APIGuide

Resu lts Ty pe

W h at I s Retu rn ed

Data
Ty pe

lost or out-of-order flow packets over a selected time

interval (such as three seconds).
MOS_ESTIMATE

Mean Opinion Score (MOS) estimate (1-5).

Float

ONE_WAY_DELAY

One way delay in milliseconds.

Long

R_VALUE

R-value score for the VoIP call (defined in ITU G.107)

Float

REPORT_GROUP_ID

The report group identifier associates timing records

with reports.

Long

RSSI_E1

RSSI for endpoint 1. Only valid for non-streaming

scripts.

String

RSSI_E2

RSSI for endpoint 2. Only valid for streaming scripts.

String

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

No such value.* (116)

Out of memory. (120)

Program internal error. (121)

No such value may be returned for certain timing record results for some tests
and is not indicative of an error for these results types.

See Return Code Summary for a detailed description of each return code.

- 1076 -

IxChariot APIGuide

chrTimingRec getResultFrequency
DESCRIPTION
The chrTimingRec getResultFrequency subcommand gets the results of the given type from
the given timing record.
c hrTimingR ec get t rec ord t y pe index

ARGUMENTS
trecord
The handle returned by chrPair getTimingRecord or chrMPair getTimingRecord.

type
The type of results to return.

index
The index for the result range requested.

RETURNED DATA
Resu lts Ty pe

W h at I s Retu rn ed

Data
Ty pe

CONSECUTIVE_
LOST

Consecutive lost datagram frequency for a result range.

Long

DELAY_VARIATION

Delay variation frequency for a result range.

Long

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

No such value. (116)

Out of memory. (120)

Program internal error. (121)

CONFIGURATION
The result ranges will have default values associated with them. If a result range is not
set, the defaults will be used. The defaults are as follows:

CHR_RESU LTS_DELAY_VARI ATI ON

I ndex

Mi ni mum

Maxi mum

10

- 1077 -

IxChariot APIGuide

11

20

21

30

31

50

51

up

CHR_RESU LTS_CONSECU TI VE_LOST

I ndex

Mi ni mum

Maxi mum

10

11

up

- 1078 -

IxChariot APIGuide

Traceroute Pair Object Command

The traceroute pair object command is used to define and retrieve information about a
traceroute pair. This command has nine subcommands.

- 1079 -

IxChariot APIGuide

chrTracertPair delete
DESCRIPTION
The chrTracertPair delete subcommand frees all memory associated with the given
traceroute pair object. This is necessary because the Tcl interpreter has no access to the
associated structures supporting the object.
c hrTrac ert Pair delet e t rac ert pair

ARGUMENTS
tracertpair
The handle returned by chrTracertPair new.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1080 -

IxChariot APIGuide

chrTracertPair get
DESCRIPTION
The chrTracertPair get subcommand gets the results of the given type from the given
traceroute.
c hrTrac ert Pair get t rac ert pair name

ARGUMENTS
tracertpair
The handle returned by chrTracertPair new.

name
The type of results to return.

NAMES
Attribu te Nam e

W h at I s Retu rn ed

Data
Ty pe

E1_ADDR

Endpoint 1 Address

String

E2_ADDR

Endpoint 2 Address

String

MAX_HOPS

Maximum hops to traverse

Long

MAX_TIMEOUT

Maximum time to wait for reply before timeout

Long

RESOLVE_HOP_
NAME

Resolve hop addresses to names

Boolean

Status of traceroute pair during test run. The traceroute

run status strings are as follows:

RUNSTATUS

UNINITIALIZED

INITIALIZING

RUNNING

STOPPING

ERROR

FINISHED

USER STOPPED.

String

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

- 1081 -

IxChariot APIGuide

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1082 -

IxChariot APIGuide

chrTracertPair getHopRecord
DESCRIPTION
The chrTracertPair getHopRecord subcommand gets the handle to the hop record object
indicated by num. The handle returned by this subcommand is needed for other subcommands to operate on the object.
c hrTrac ert Pair get H opR ec ord t rac ert pair num

ARGUMENTS
tracertpair
The handle returned by chrTracertPair new.

num
A number indicating which hop record to get. The number is determined by the order in
which the hop records were received. Hop record numbering starts at 0; to get the first
hop record, with a hop number of 1, use the number 0.

RETURNED DATA
The returned data provides the handle to the requested hop record.

ERROR RETURNS
l

Handle is invalid. (101)

No such object. (104)

Traceroute was not run. (122)

API was not initialized. (113)

Results are not available. (114)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1083 -

IxChariot APIGuide

chrTracertPair getHopRecordCount
DESCRIPTION
The chrTracertPair get HopRecordCount subcommand gets the number of hop records in
the results for the given traceroute pair.
c hrTrac ert Pair get H opR ec ordC ount t rac ert pair

ARGUMENTS
tracertpair
The handle returned by chrTracertPair new.

RETURNED DATA
The returned data provides the number of hop records (Data type: Long).

ERROR RETURNS
l

Handle is invalid. (101)

Traceroute was not run. (122)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1084 -

IxChariot APIGuide

chrTracertPair isStopped
DESCRIPTION
The chrTracertPair isStopped subcommand waits until the traceroute is stopped or the
timeout is reached.
c hrTrac ert Pair is St opped t rac ert pair ?t imeout ?

ARGUMENTS
tracertpair
The handle returned by chrTracertPair new.

timeout
The time in seconds to wait for the test to stop or CHR_INFINITE (optional). If timeout is
not provided, this subcommand returns immediately with the traceroute status.

RETURNED DATA
The returned data provides True (1) if the traceroute is stopped; False (0) if the timeout
has expired.

ERROR RETURNS
l

Handle is invalid. (101)

Traceroute was not run. (122)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1085 -

IxChariot APIGuide

chrTracertPair new
DESCRIPTION
The chrTracertPair new command creates a traceroute pair.
c hrTrac ert Pair new

ARGUMENTS
None

RETURNED DATA
The returned data provides the handle to an initialized traceroute pair object. The handle
returned by this subcommand is needed for other subcommands to operate on the object.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1086 -

IxChariot APIGuide

chrTracertPair run
DESCRIPTION
The chrTracertPair run subcommand starts running the given traceroute.
c hrTrac ert Pair run t rac ert pair

ARGUMENTS
tracertpair
The handle returned by chrTracertPair new.

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Operation has failed (108)

Object is invalid. (112)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Traceroute is already running. (123)

See Return Code Summary for a detailed description of each return code.

- 1087 -

IxChariot APIGuide

chrTracertPair set
DESCRIPTION
The chrTracertPair set subcommand sets the value for the attribute specified by name in
the given traceroute pair. One or more name-value pairs may be specified for this subcommand.
c hrTrac ert Pair s et t rac ert pair name v alue

ARGUMENTS
tracertpair
The handle returned by chrTracertPair new.

name
The attribute to set.

value
The value to set for the given attribute.

ATTRIBUTES
Attribu te Nam e

Ran ge
or Max
S trin g
L en gth

What Is Set

E1_ADDR

Address of Endpoint 1 in the traceroute pair.

64
characters

E2_ADDR

Address of Endpoint 2 in the traceroute pair.

64
characters

MAX_HOPS

Maximum number of hops before timeout

2-40

MAX_TIMEOUT

Maximum amount of time to wait for a traceroute to

complete before timeout

1-10,000

RESOLVE_HOP_
NAME

Whether to resolve hop addresses to names

0 = False
1 = True

DEFAULT SETTINGS
Attribu te

Value

MAX_HOPS

30

MAX_TIMEOUT

3000 milliseconds

RESOLVE_HOP_NAMES

true

- 1088 -

IxChariot APIGuide

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

String is too long. (102)

Object is in use. (107)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1089 -

IxChariot APIGuide

chrTracertPair stop
DESCRIPTION
The chrTracertPair stop subcommand stops running the given traceroute before it completes. This command can and usually does return before the traceroute has stopped. Use
chrTracertPair isStopped to determine when the object traceroute has actually stopped.
c hrTrac ert Pair s t op t rac ert pair

ARGUMENTS
tracertpair
The handle returned by chrTracertPair new.

RETURNED DATA
"Stop Succeeded" if successful.

ERROR RETURNS
l

Handle is invalid. (101)

Traceroute was not run. (122)

API was not initialized. (113)

Value is invalid (115)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1090 -

IxChariot APIGuide

Video Multicast Group Object Commands

The video multicast group object commands are used to define and retrieve information
for a video multicast group. A video multicast group object must be contained by a test
object. The testing parameters available for the video multicast group object include the
source port number, the length of the timing records generated, type of codec, the bitrate
of the video transmission, the frames per datagram, the initial delay, the RTP payload
type, and the media frame size. You cannot add members to or set the attributes of a multicast group object that is contained by a test object.
A separate set of commands is provided to define and retrieve information for video pairs
(unicast video).

- 1091 -

IxChariot APIGuide

chrVideoMGroup get
DESCRIPTION
The chrVideoMGroup get subcommand gets the value for the attribute specified by name
from the given video multicast group.
c hrVideoMGroup get mgroup name

ARGUMENTS
pair
The handle returned by chrVideoMGroup new or chrTest getMGroup.

name
The attribute to get.

NAMES
Attribu te Nam e

W h at I s Retu rn ed

Data
Ty pe

CODEC

Codec name

String

SOURCE_PORT_
NUMBER

UDP source port number

Long

INITIAL_DELAY

The delay distribution and the upper and lower limits,

formatted as:
"d[x,y]". (Refer to chrVideoPair set for a detailed
description.)

String

NO_OF_TIMING_
RECORDS

The number of timing records generated for the given

video multicast group.

Long

TIMING_RECORD_
DURATION

The time, in seconds, for a single timing record to complete

Integer

BITRATE

The media data rate of the video stream.

Float

BITRATE_UNIT_OF_
MEASUREMENT

The unit of measurement for the media data rate.

String

FRAMES_PER_
DATAGRAM

The number of media frames per datagram for the

given multicast video stream.

Integer

RTP_PAYLOAD_
TYPE

The RTP payload type for the given multicast video

stream.
This is valid only for custom codec and
RTP/RTP6 protocol.

- 1092 -

Integer

IxChariot APIGuide

Attribu te Nam e

MEDIA_FRAME_SIZE

W h at I s Retu rn ed

The media frame size used in the multicast video

stream.

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1093 -

Data
Ty pe

Integer

IxChariot APIGuide

chrVideoMGroup new
DESCRIPTION
The chrVideoMGroup new command creates a multicast video group and initializes it to
default values. Note that the object default values do not use the default values specified
on the Run Options tab. See Video Pair Object Default Values for more information.
c hrVideoMGroup new

ARGUMENTS
None

RETURNED DATA
The returned data provides the handle to an initialized multicast video object. The handle
returned by this subcommand is needed for other subcommands to operate on the object.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Not licensed. (126)

See Return Code Summary for a detailed description of each return code.

- 1094 -

IxChariot APIGuide

chrVideoMGroup set
DESCRIPTION
The chrVideoMGroup set subcommand sets or changes the value for the attributes specified by name for the given video multicast group.
c hrVideoMGroup s et mgroup name v alue . . .
Note: Multiple groups of name/value can be set with the same command.

ARGUMENTS
pair
The handle returned by chrVideoMGroup new or chrTest getMGroup.

name
The attribute to set.

value
The attribute value.

ATTRIBUTES
Attribu te Nam e

What Is Set

Ran ge or Max
S trin g L en gth

Data
Ty pe

CODEC

Codec name

"MPEG2", "CUSTOM"

String

SOURCE_PORT_
NUMBER

The source port number for

the multicast video test.

0 (auto) - 65535

Long

INITIAL_DELAY

The delay distribution

"d[x , y ]" w he r e :
d = u (uni f or m), n
( no r m a l ) , p( po i s son), or e (exponenti al )
and x,y =
i nteger s between
Boolean
"1" and
"999999999"
wher e x < y
or an i nteger (constant) between 1
and 999999999
or "default."

SOURCE_PORT
_NUMBER

The source port number for

the multicast video test.

0 (auto)65535

Long

NO_OF_TIMING_

The number of timing

1 - 999999999

Long

- 1095 -

IxChariot APIGuide

Attribu te Nam e

What Is Set

Ran ge or Max
S trin g L en gth

Data
Ty pe

RECORDS

records that the endpoint will

create during test execution.

TIMING_RECORD
_DURATION

The time, in seconds, for a

single timing record to complete.

BITRATE

The media data rate of the

video stream. Typical values
for MPEG2 are between 3 and 1 - 999999
15 megabits. The default is
3.75 megabits.

BITRATE_UNIT_OF_
MEASUREMENT

The unit measurement setting for the media data rate.

"UNIT_kb", "UNIT_Kb",
"UNIT_kB", "UNIT_KB",
"UNIT_Mb", "UNIT_Gb"

String

FRAMES_PER_
DATAGRAM

The number of media frames

that will be contained in a
datagram. For Ethernet,
there are typically seven
frames per datagram.

All integer values

greater than zero are
valid.

Integer

(The default is 50.)

1-3600
Values may be adjusted
slightly so that only full
buffers are sent.

Integer

Float

0 - 127.
RTP_PAYLOAD_
TYPE:

MEDIA_FRAME_
SIZE

The RTP payload type for the

given multicast video
stream.

The media frame size.

Only valid for

custom codec
and RTP/RTP6
protocol.
All integer values
greater than zero are
valid.

ERROR RETURNS
l

Handle is invalid. (101)

Object in use. (107)

API was not initialized. (113)

Value is invalid. (115)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1096 -

Integer

Integer

IxChariot APIGuide

Video Pair Object Commands

The video pair object commands are used to define and retrieve information for a video
pair. A video pair object must be contained by a test object. The testing parameters available for the video pair object include the source and destination port numbers, the length
of the timing records generated, type of codec, the bitrate of the video transmission, the
frames per datagram, the initial delay, the RTP payload type, and the media frame size.
You cannot add members to or set the attributes of a video pair object that is contained by
a test object.
A separate set of commands is provided to define and retrieve information about video
multicast groups.

- 1097 -

IxChariot APIGuide

chrVideoPair get
DESCRIPTION
The chrVideoPair get subcommand gets the value for the attribute specified by name from
the given pair.
c hrVideoPair get pair name

ARGUMENTS
pair
The handle returned by chrVideoPair new or chrTest getPair.

name
The attribute to get.

NAMES
Attribu te Nam e

W h at I s Retu rn ed

Data
Ty pe

CODEC

Codec name

String

DEST_PORT_
NUMBER

UDP destination port number

Long

SOURCE_PORT_
NUMBER

UDP source port number

Long

INITIAL_DELAY

The delay distribution and the upper and lower limits,

formatted as:
"d[x,y]". (Refer to chrVideoPair set for a detailed
description.)

String

TIMING_RECORD_
DURATION

The time, in seconds, for a single timing record to complete.

NO_OF_TIMING_
RECORDS

The number of timing records generated for the given

video pair.

Long

BITRATE

The media data rate of the video stream.

Float

BITRATE_UNIT_OF_
MEASUREMENT

The unit of measurement for the media data rate.

String

FRAMES_PER_
DATAGRAM

The number of media frames per datagram for the

given video pair.

Integer

Integer

The RTP payload type for the given video pair.

RTP_PAYLOAD_
TYPE

Integer
This is valid only for custom codec and RTP/RTP6 protocol.

- 1098 -

IxChariot APIGuide

Attribu te Nam e

MEDIA_FRAME_SIZE

W h at I s Retu rn ed

The media frame size used in the unicast video test.

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1099 -

Data
Ty pe

Integer

IxChariot APIGuide

chrVideoPair new
DESCRIPTION
The chrVideoPair new command creates a video pair and initializes it to default values.
Note that the object default values do not use the default values specified on the Run
Options tab. See Video Pair Object Default Values for more information.
c hrVideoPair new

ARGUMENTS
None

RETURNED DATA
The returned data provides the handle to an initialized pair object. The handle returned by
this subcommand is needed for other subcommands to operate on the object.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Not licensed.

See Return Code Summary for a detailed description of each return code.

- 1100 -

IxChariot APIGuide

chrVideoPair set
DESCRIPTION
The chrVideoPair set subcommand sets or changes the value for the attributes specified by
name for the given pair.
c hrVideoPair s et pair name v alue . . .
Multiple pairs of name/value can be set with the same command.

ARGUMENTS
pair
The handle returned by chrVideoPair new or chrTest getPair.

name
The attribute to set.

value
The attribute value.

ATTRIBUTES
Attribu te Nam e

What Is Set

Ran ge or Max
S trin g L en gth

Data
Ty pe

CODEC

Codec name

"MPEG2", "CUSTOM"

String

DEST_PORT_
NUMBER

The destination port number

for the unicast video test.

0 (auto) - 65535

Long

S OU R C E _P OR T _
NU MBER

The source port number for

the unicast video test.

0 (auto) - 65535

Long

"d[x , y ]" w he r e :
d = u (uniform), n(normal), p(poisson), or e
(exponential)

INITIAL_DELAY

The delay distribution

and x,y = integers

between "1" and
"999999999"
where x < y
or an integer (constant)
between 1 and
999999999
or "def aul t."

- 1101 -

Boolean

IxChariot APIGuide

Attribu te Nam e

What Is Set

NO_OF_TIMING_
RECORDS

The number of timing

records that the endpoint will
create during test execution.

TIMING_RECORD
_DURATION

The time, in seconds, for a

single timing record to complete.

Ran ge or Max
S trin g L en gth

Data
Ty pe

1 - 999999999
Long
(The default is 50.)
1-3600
Values may be adjusted
slightly so that only full
buffers are sent.

Integer

1 - 999999

Float

"UNIT_kb", "UNIT_Kb",
"UNIT_kB", "UNIT_KB",
"UNIT_Mb", "UNIT_Gb"

String

All integer values

greater than zero are
valid.

Integer

The media data rate of the

video stream.
BITRATE

Typical values for MPEG2 are

between 3 and 15 megabits.
The default is 3.75 megabits.

BITRATE_UNIT_OF_
MEASUREMENT

The unit measurement setting for the media data rate.

FRAMES_PER_
DATAGRAM

The number of media frames

that will be contained in a
datagram.
For Ethernet, there are typically seven frames per datagram.

0 - 127.
RTP_PAYLOAD_
TYPE:

MEDIA_FRAME_
SIZE

The RTP payload type for the

given video pair.

The media frame size.

Only valid for

custom codec
and RTP/RTP6
protocol.
All integer values
greater than zero are
valid.

ERROR RETURNS
l

Handle is invalid. (101)

Object in use. (107)

API was not initialized. (113)

Value is invalid. (115)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1102 -

Integer

Integer

IxChariot APIGuide

- 1103 -

IxChariot APIGuide

VoIP Pair Object Command

VoIP pair object commands are used in voice over IP tests. A VoIP pair object must be contained by a test object. The testing parameters available for the VoIP pair object include
the type of codec, the source and destination port numbers, whether to use silence suppression and its corresponding activity rate, the length of the timing records generated,
the initial delay, and the delay between packets.
You can get results for a VoIP test using chrTimingrec get or chrPairResults get.

- 1104 -

IxChariot APIGuide

chrVoIPPair get
DESCRIPTION
The chrVoIPPair get subcommand gets the value for the attribute specified by name from
the given pair.
c hrVoI PPair get pair name

ARGUMENTS
pair
The handle returned by chrVoIPPair new or chrTest getPair.

name
The attribute to get.

NAMES
Attribu te Nam e

W h at I s Retu rn ed

Data
Ty pe

CODEC

Codec name

String

DEST_PORT_
NUMBER

UDP destination port number

Long

SOURCE_PORT_
NUMBER

U DP sour ce por t number

Long

INITIAL_DELAY

The delay distribution and the upper and lower limits,

formatted as:
"d[x,y]". (Refer to chrVoIPPair set for a detailed
description.)

String

TIMING_RECORD_
DURATION

The time, in seconds, for a single timing record to

complete

Integer

NO_OF_TIMING_
RECORDS

The number of timing records generated for the given

VoIP pair.

Long

USE_SILENCE_SUP

Whether to use silence suppression. If the value is set

to TRUE, the voice activity rate is utilized.

Boolean

VOICE_ACTIV_RATE The voice activity rate as a percentage. Only used

when silence suppression is enabled.

Long

The delay between voice datagrams.

DATAGRAM_DELAY

Long
Equivalent to the datagram size.

JITTER_BUFFER_
SIZE

The size, in milliseconds, of the jitter buffer.

- 1105 -

Long

IxChariot APIGuide

Attribu te Nam e

W h at I s Retu rn ed

Data
Ty pe

ADDITIONAL_
DELAY

User-configurable delay value to account for known

device delays or other considerations.

Long

USE_PLC

Indicate whether to use PLC.

Boolean

PAYLOAD_FILE

A file whose content will be used as payload when running the VoIP pair (an empty string means random
String
payload is used)

PAYLOAD_I S_
EMBEDDED

Speci f i es whether the payl oad f i l e wi l l

be embedded wi thi n the scr i pt or r ef er enced as an exter nal f i l e.

ERROR RETURNS
l

Handle is invalid. (101)

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1106 -

Boolean

IxChariot APIGuide

chrVoIPPair new
DESCRIPTION
The chrVoIPPair new command creates a voice over IP pair and initializes it to default values. Note that the object default values do not use the default values specified on the Run
Options tab. See VoIP Pair Object Default Values for a list of the default values.
c hrVoI PPair new

ARGUMENTS
None

RETURNED DATA
The returned data provides the handle to an initialized pair object. The handle returned by
this subcommand is needed for other subcommands to operate on the object.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

Not licensed.

See Return Code Summary for a detailed description of each return code.

- 1107 -

IxChariot APIGuide

chrVoIPPair set
DESCRIPTION
The chrVoIPPair set subcommand sets or changes the value for the attribute specified by
name from the given pair.
c hrVoI PPair s et pair name v alue

ARGUMENTS
pair
The handle returned by chrVoIPPair new or chrTest getPair.

name
The attribute to get.

value
The attribute value.

ATTRIBUTES
Attribu te
Name

ADDITIONAL_
DELAY

CODEC

What Is Set

Ran ge or Max
S trin g L en gth

User-configurable delay value to

0 to 300 milaccount for known device delays
liseconds
or other considerations.
"G711u", "G711a",
"G723.1A",
"G723.1M",
"G726", "G729",
"AMR_NB_4_75",
"AMR_NB_5_15",
"AMR_NB_5_9",
"AMR_NB_6_7",
"AMR_NB_7_4",
"AMR_NB_7_95",
"AMR_NB_10_2",
"AMR_NB_12_2",
"AMR_WB_6_6",
"AMR_WB_8_85",
"AMR_WB_12_65",
"AMR_WB_14_25",
"AMR_WB_15_85",
"AMR_WB_18_25",
"AMR_WB_19_85",
"AMR_WB_23_05",

Codec name

- 1108 -

Data Ty pe

Long

String

IxChariot APIGuide

Attribu te
Name

What Is Set

Ran ge or Max
S trin g L en gth

Data Ty pe

"AMR_WB_23_85"

DATAGRAM_
DELAY

The delay between voice datagrams. Equivalent to the datagram size.

DEST_PORT_
NUMBER

The destination port number for

the voice over IP test.

20-200 (in ms) for

G711u, G711a and
G729
Long
30-200 (in ms) for
G.723.1A and
G723.1M
0 (auto) - 65535

Long

"d[x , y ]"
wher e:

INITIAL_DELAY

d = u (uniform), n
(normal), p(poisson), or e(exponential) and x,y =
integers between
"1" and
"999999999"
where x < y or an
integer (constant)
between 1 and
999999999 or
"default."

The delay distribution

Boolean

10-1600 (i n
ms),
or 0 (if you do not
want IxChariot to
emulate jitter buffering in your test)

JITTER_
BUFFER_SIZE

The size, in milliseconds, of the

jitter buffer.

SOURCE_
PORT_NUMBER

The source port number for the

voice over IP test.

NO_OF_
TIMING_
RECORDS

1 - 999999999
The number of timing records
that the endpoint will create dur- (The default is 50.) Long
ing test execution.

0 (auto)65535

Long

Long

1-3600
TIMING_
RECORD_
DURATION

The time, in seconds, for a

single timing record to complete.

Values may be
adjusted slightly
so that only full
buffers are sent.

USE_PLC

Use/do not use PLC with the

0 = do not use PLC

- 1109 -

Integer

Boolean

IxChariot APIGuide

Attribu te
Name

What Is Set

Ran ge or Max
S trin g L en gth

Data Ty pe

G711u or G711a codec

1 = use PLC

USE_SILENCE_
SUP

Whether to use silence suppression. If the value is set to

TRUE, the voice activity rate is
utilized.

0 = False
1 = True

Boolean

VOICE_ACTIV_
RATE

The voice activity rate as a percentage. Only used when silence

suppression is enabled.

1-100 (percentage)

Long

ERROR RETURNS
l

Handle is invalid. (101)

Object in use. (107)

API was not initialized. (113)

Value is invalid. (115)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1110 -

IxChariot APIGuide

chrVoIPPair setPayloadFile
DESCRIPTION
The chrVoIPPair setPayloadFile command allows a user to specify a file whose content will
be used as payload when running the VoIP pair.
c hrVoI PPair s et Pay loadFile pairH andle f ilename
embeddedFlag
You cannot set the timing record duration if payload files are used. If you attempt to do so,
chrVoIPPair set TIMING_RECORD_DURATION will return error code 124 (Not Supported).
For AMR codecs, if silence suppression is enabled, chrVoIPPair set PayloadFile will return
error code 124 (Not Supported).

ARGUMENTS
pairHandle
The handle returned by chrVoipPair new.

filename
The name of the file containing the payload data.

embeddedFlag
Specifies whether the payload file will be embedded within the script or referenced as an
external file:
l
l

1The payload file is embedded within the script.

0The payload data is contained in an external file that is referenced from within the
script.

The recommended option is 1embedded.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

String too long (102)

Pointer is invalid (103)

No such object (104)

Object in use (107)

Operation failed (108)

API was not initialized. (113)

Value is invalid (115)

No script in use (117)

- 1111 -

IxChariot APIGuide

Out of memory. (120)

Program internal error. (121)

Payload file too large (138)

See Return Code Summary for a detailed description of each return code.

- 1112 -

IxChariot APIGuide

chrVoIPPair setPayloadRandom
DESCRIPTION
The chrVoIPPair setPayloadRandom command sets the payload for a VoIP test to random
data.
c hrVoI PPair s et Pay loadR andom pairH andle
You cannot set the timing record duration if payload files are used. If you attempt to do so,
chrVoIPPair set TIMING_RECORD_DURATION will return error code 124 (Not Supported).

ARGUMENTS
pairHandle
The handle returned by chrVoipPair new.

RETURNED DATA
None.

ERROR RETURNS
l

Handle is invalid. (101)

No such object (104)

Object in use (107)

API was not initialized. (113)

No script in use (117)

Out of memory. (120)

See Return Code Summary for a detailed description of each return code.

- 1113 -

IxChariot APIGuide

VoIP Hardware Performance Pair Object Commands

VoIP Hardware Performance Pair object commands are used to define VoIP pairs for a test
and retrieve information about VoIP hardware performance pair. You are not allowed to
set any pair information for a pair that is owned by a test. The VoIP Pair Object Commands
are used to get/set values in the VoIP Hardware Performance Pair Object as well:
l

chrHardwareVoipPair get

chrHardwareVoipPair new

chrHardwareVoipPair set

- 1114 -

IxChariot APIGuide

chrHardwareVoipPair get
DESCRIPTION
The chrHardwareVoipPair get subcommand gets the value for the attribute specified by
name from the given pair.
c hrH ardw areVoipPair get pair name

ARGUMENTS
pair
The handle returned by chrHardwareVoipPair new or chrTest getPair.

name
The attribute to get.

ATTRIBUTES
Attribu te Nam e

CONCURRENT_VOICE_
STREAMS

W h at I s Retriev ed

The number of concurrent voice streams

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Value is invalid. (115) *

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1115 -

Data
Ty pe

Integer

IxChariot APIGuide

chrHardwareVoipPair new
DESCRIPTION
The chrHardwareVoipPair new command creates a new VoIP Hardware Performance pair
and initializes it to default values. Note that the object default values do not use the default
values specified on the Run Options tab. See VoIP Hardware Performance Pair Object
Default Values for a list of the default values.
c hrH ardw areVoipPair new

ARGUMENTS
None

RETURNED DATA
The returned data provides the handle to an initialized VoIP hardware pair object. The
handle returned by this subcommand is needed for other subcommands to operate on the
object.

ERROR RETURNS
l

API was not initialized. (113)

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1116 -

IxChariot APIGuide

chrHardwareVoipPair set
DESCRIPTION
The chrHardwareVoipPair set subcommand sets or changes the value for the attribute specified by name from the given pair.
c hrH ardw areVoipPair s et pair name v alue

ARGUMENTS
pair
The handle returned by chrHardwareVoipPair new or chrTest getPair.

name
The attribute to set.

value
The value to set for the given attribute.

ATTRIBUTES
Attribu te Nam e

Attr i bute Name

C ON C U R R E N T _V OI C E _
STREAMS

What Is Set

Data Ty pe

What' s Set

Data Type

The number of concur r ent voi ce str eams

I nteger

RETURNED DATA
None

ERROR RETURNS
l

Handle is invalid. (101)

Object is in use. (107)

API was not initialized. (113)

Value is invalid. (115) *

Out of memory. (120)

Program internal error. (121)

See Return Code Summary for a detailed description of each return code.

- 1117 -

IxChariot APIGuide

Chapter 7: The Stack Manager Tcl API Script Examples

Stack Manager is automatically installed with IxChariot (IxChariot Release 6.10 and
above). It is integrated within the IxChariot GUI, and provides a Tcl API with which you
can create your own scripts for automating the network stack setup for your IxChariot
tests.
Documentation for Stack Manager is provided in the following manuals:
l

Stack Manager User Guide

Stack Manager Tcl API Guide

The Stack Manager Tcl API Guide provides detailed information about the Stack Manager
Tcl API, and it includes several IxChariot script examples. Also refer to Management
Addresses with Stack Manager for information about the using management addresses in
the Stack Manager Tcl API.
This chapter provides several working Tcl script examples, each demonstrating how to
implement one of the Stack Manager plug-ins. The topics in this chapter include:
l

Using the Tcl Scripts

Sample IP Script

Sample MAC Range Script

Sample DHCP Script

Sample Impairment Script

Sample IPSec Script (port-to-port)

Sample IPSec Script (port-to-DUT)

Sample PPP Script (port-to-port)

Sample PPP Script (port-to-DUT)

Using the Tcl Scripts

The Tcl scripts that are described in this section are provided with the Stack Manager software. You can use them as a starting point for creating your own Tcl scripts. As you work
with these sample scripts, note the following:
l
l

The scripts contain comments that explain the tasks being performed.
The IP addresses used in the scripts are the Stack Manager default addresses, with
the exception of the IP addresses (as well as slot and port selection) of the Ixia
chassis referenced in the scripts.

Script Setup
You need to complete the following steps before running the scripts.
1. Install IxChariot on the client PC.
2. Start TestServer.exe from C:\Program Files\Ixia\IxChariot\Aptixia\bin\win
3. Ensure that the Ixia chassis is running IxOS 4.0 or higher.
4. Ensure that the Ixia chassis has two ports connected back to back.

- 1118 -

IxChariot APIGuide
Note that one of the scripts (Sample IPSec Script (port-to-DUT)) requires two Ixia
chassis and a DUT.
5. Modify the CHASSIS, SLOT, PORT variables in the scripts to values specific to your
chassis.
Refer to the "Tcl Reference" chapter in the IxChariot API Guide for information about initializing the IxChariot API.

- 1119 -

IxChariot APIGuide

Sample IP Script
This section presents a sample Tcl script for creating an IPv4 interface. This script implements an IP-over-Ethernet protocol stack, and uses static IP address allocation.

Test Topology
This script requires an Ixia chassis with two Ethernet ports connected back-to-back.

Plugin Layout
This script implements a basic IP over Ethernet plugin structure:

IP Plugin Test Tcl Script Listing

Following is the sample Tcl script for creating an IPv4 interface. The script file name is
ChrSM_IPPluginTest.tcl.
#***************************************************************
#
# I x C hariot API SD K
File: C hrSM_I PPluginTes t . t c l
#
# This module c ont ains c ode made av ailable by I x ia on an AS I S
# bas is . Any one rec eiv ing t he module is c ons idered t o be
# lic ens ed under I x ia c opy right s t o us e t he I x ia-prov ided
# s ourc e c ode in any w ay he or s he deems f it , inc luding c opy ing
# it , c ompiling it , modif y ing it , and redis t ribut ing it , w it h
# or w it hout modif ic at ions . N o lic ens e under any I x ia pat ent s
# or pat ent applic at ions is t o be implied f rom t his c opy right
# lic ens e.
#
# A us er of t he module s hould unders t and t hat I x ia c annot
# prov ide t ec hnic al s upport f or t he module and w ill not be
# res pons ible f or any c ons equenc es of us e of t he program.
#
# Any not ic es , inc luding t his one, are not t o be remov ed f rom
# t he module w it hout t he prior w rit t en c ons ent of I x ia.
#
# For more inf ormat ion, c ont ac t :
#
# Ixia
# 26601 W . Agoura R d.
# C alabas as , C A 91302 U SA
# W eb: ht t p: / / w w w . ix iac om. c om
# Phone: 818-871-1800
# Fax : 818-871-1805
#
# General I nf ormat ion:
#
e-mail: inf o@ ix iac om. c om

- 1120 -

IxChariot APIGuide
#
# Tec hnic al Support :
#
e-mail: s upport @ ix iac om. c om
#
#
# EXAMPLE: I x ia Endpoint Pairs Tes t
# This s c ript c reat es and runs a t es t w it h ix ia endpoint pairs
# us ing I P Plugin, t hen s av es t he t es t t o a f ile.
#
# All at t ribut es of t his t es t are def ined by t his s c ript .
#
#***************************************************************
#***************************************************************
# D at a f or t es t :
# C hange t hes e v alues f or y our net w ork if des ired.
#***************************************************************
s et t es t File " C : / Program Files / I x ia/ I x C hariot / Tes t s / c hrSM_ I PPluginTes t . t s t "
s et pairC ount 1
s et e1Addrs " 172. 16. 1. 1"
s et e2Addrs " 172. 16. 2. 1"
s et prot oc ols " TC P"
s et s c ript s " c : / Program Files / I x ia/ I x C hariot / Sc ript s / R es pons e_Time. s c r"
s et t imeout 5
s et max W ait 180
s et logFile " pairs Tes t . log"
s et C H A S S I S 1_I P 192. 168. 4. 170
s et e1_m gm t " 192. 168. 4. 170; 1; 1"
s et e2_m gm t " 192. 168. 4. 170; 1; 2"
s et e1Mgmt " 192. 168. 4. 170 / 01 / 01"
s et e2Mgmt " 192. 168. 4. 170 / 01 / 02"
s et gat ew ay 1 172. 16. 2. 1
s et gat ew ay 2 172. 16. 1. 1
#***************************************************************
# Proc edure t o c onf igure ix ia port us ing Apt ix ia API
#***************************************************************
proc c onf igureI x iaPort s {my H os t my Port my Ses s ion e1_mgmt e2_mgmt } {
global C H ASSI S1_I P e1Addrs e2Addrs gat ew ay 1 gat ew ay 2
# St art t es t Serv er and us e t he ins t anc e inv ok ed by ix c hariot
# -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -# This s ec t ion of c ode s et ' s
# t he " s erv er t rans ac t ion c ont ex t " `t c ' t o a part ic ular t es t s erv er
#
s et t c [ : : Apt ix iaC lient : : C ore: : Fac ilit y Get D ef ault Trans ac t ionC ont ex t ]
$t c I nit $my H os t $my Port
s e t : : m y S e s O b j [ : : A p t i x i a C l i e n t : : S e s s i o n % A U T O % -t r a n s a c t i o n c o n t e x t
$t c objec t id $my Ses s ion]
#
# Get ex is t ing t es t f rom our t es t s erv er s es s ion
#
s e t : : m y T e s t I d [ $ : : m y S e s O b j e d i t a b l e T e s t c g e t -o b j e c t i d ]
s et : : my Tes t [ : : Apt ix iaC lient : : Generic Tes t Model %AU TO% -

- 1121 -

IxChariot APIGuide
t rans ac t ionc ont ex t $t c
-o b j e c t i d $ : : m y T e s t I d ]
#
# Add s ome c has s is ' s int o t he t es t model
# t he c has s is ' s are in t he s ubobjec t pat hw ay
#
# c h a s s i s C o n f i g -> c h a s s i s C h a i n
#
$: : my Tes t c has s is C onf ig c has s is C hain AddTail
s et c c Obj [ $: : my Tes t c has s is C onf ig c has s is C hain Get 0]
$c c Obj dns S et " $C H A S S I S 1_I P " ; # s et c has s i s nam e
$c c Obj c ableLengt h Set 3
$c c Obj phy s ic alC hain Set f als e
###
# Set up f irs t port group
s et port Spec " $e1_mgmt "
s e t p g _i d x [ e x p r [ $ : : m y T e s t p o r t G r o u p L i s t S i z e ] -2 ]
s et pgObj [ $: : my Tes t port GroupLis t Get $pg_idx ]
$pgObj name Set " My f irs t port group"
$pgObj port Lis t AddTail $port Spec
# Set up Et hernet St ac k on " My f irs t port group" - pgObj
$pgObj _I ns t ant i at e s t ac k " E t hernet P l ugi n"
$pgObj s t ac k enabled Set t rue
$pgObj s t ac k mac Set " 00: 00: 00: 00: 01: 01"
# Set up I P plugin on " My f irs t port group" - pgObj
$pgObj s t ac k c hildrenLis t AddTail -it emt y pe " I pV4V6Plugin"
s et ippObj [ $pgObj s t ac k c hildrenLis t Get 0]
$ippObj rangeLis t AddTail
s et iprObj [ $ippObj rangeLis t Get 0]
$iprObj enabled Set t rue
$iprObj ipTy pe Set I Pv 4
$iprObj ipAddres s Set $e1Addrs
$iprObj inc rement By Set 0. 0. 0. 1
$iprObj pref ix Set 16
$iprObj c ount Set 1
$iprObj gat ew ay Addres s Set $gat ew ay 1
# Add s ec ond c has s is t o t he lis t
$: : my Tes t c has s is C onf ig c has s is C hain AddTail
s et c c Obj [ $: : my Tes t c has s is C onf ig c has s is C hain Get 1]
$c c Obj dns S et " $C H A S S I S 1_I P " ; # s et c has s i s nam e
$c c Obj c ableLengt h Set 3
$c c Obj phy s ic alC hain Set f als e
###
# Set up s ec ond port group
s et port Spec $e2_mgmt
s et pg_idx [ ex pr [ $: : my Tes t port GroupLis t Siz e] -1]
s et pgObj1 [ $: : my Tes t port GroupLis t Get $pg_idx ]
$pgObj1 name Set " My Sec ond Port Group"
$pgObj1 port Lis t AddTail $port Spec
# Set up Et hernet St ac k on " My s ec ond Port Group" - pgObj1
$pgObj1 _I ns t ant iat e s t ac k " Et hernet Plugin"
$pgObj1 s t ac k enabled Set t rue
$pgObj1 s t ac k mac Set " 00: 00: 00: 00: 02: 02"

- 1122 -

IxChariot APIGuide
# Set up I P plugin on " My s ec ond Port Group" - pgObj1
$ p g O b j 1 s t a c k c h i l d r e n L i s t A d d T a i l -i t e m t y p e " I p V 4 V 6 P l u g i n "
s et ippObj [ $pgObj1 s t ac k c hildrenLis t Get 0]
$ippObj rangeLis t AddTail
s et iprObj [ $ippObj rangeLis t Get 0]
$iprObj enabled Set t rue
$iprObj ipTy pe Set I Pv 4
$iprObj ipAddres s Set $e2Addrs
$iprObj inc rement By Set 0. 0. 0. 1
$iprObj gat ew ay Addres s Set $gat ew ay 2
$iprObj pref ix Set 16
$iprObj c ount Set 1
# prompt $int erac t iv e " hit ret urn t o Tes t C onf igure"
$: : my Tes t Tes t C onf igure ; # applied c onf ig on port s
# All enums f or objec t s are pre-def ined w it hin t he objec t c las s as
# r e a d -o n l y c l a s s v a r i a b l e s , l i k e
# `k D eep' `k Shallow ' et c . . .
s et x m l 1 [ l i ndex [ $: : m y T es t _Get X m l \
$: : Apt ix iaC lient : : XProt oc olObjec t : : eSerializ at ionD ept h: : k D eep \
t rue] 0]
put s s t dout $x ml1
ret urn $x ml1
}
#***************************************************************
# Proc edure t o log errors if t here is ex t ended inf o
#***************************************************************
proc pLogError {handle c ode w here} {
global logFile
# D ef ine s y mbols f or t he errors w e' re int eres t ed in.
s et C H R _OPER ATI ON _FAI LED " C H R API 108"
s et C H R _OB J E C T _I N V A LI D " C H R A P I 112"
# Somet hing f ailed: s how w hat happened.
put s " $w here f ailed: [ c hrApi get R et urnMs g $c ode] "
# See if t here is ex t ended error inf ormat ion av ailable.
# I t ' s is only meaningf ul f or c ert ain errors .
if {$c ode = = $C H R _OPER ATI ON _FAI LED
|| $c ode = = $C H R _ OB J E C T _I N V A LI D } {
# Try t o get t he ex t ended error inf ormat ion
s et rc [ c at c h {s et inf o [ c hrC ommonError get I nf o \
$handle " ALL" ] }]
if {$rc ! = 0} {
# W e c an ignore all non-s uc c es s ret urn c odes here
# bec aus e mos t s hould not oc c ur (t he api' s been
# init ializ ed and t he det ail lev el is ok ay ),
# and t he N O_S U C H _ V A LU E ret urn c ode here m eans
# t here is no inf o av ailable.
s et inf o " < N one> "
}
s et logFile [ open $logFile a+ ]
s et t imes t amp [ c loc k f ormat [ c loc k s ec onds ] ]
put s $logFile " $t imes t amp $w here f ailed"
put s $logFile " $t imes t amp $inf o"
# Flus h f orc es immediat e w rit e t o f ile

- 1123 -

IxChariot APIGuide
f lus h $logFile
}
}
#***************************************************************
#
# Sc ript main
#
# c at c h is us ed w hen t here c ould be ex t ended error inf ormat ion,
# s o w e c an log w hat happened.
#***************************************************************
# Load t he C hariot API .
#
# N OTE: I f y ou are us ing Tc l Vers ion 8. 0. p5 or older
# t hen y ou w ill need t o modif y t he f ollow ing lines t o load and
# us e C hariot ins t ead of C hariot Ex t . For ex ample:
# load C hariot
# pac k age require C hariot
l append : : aut o_pat h " c : / P rogram \ F i l es / i x i a/ i x c hari ot / apt i x i a/ l i b/ c om m on/
t c lc lient "
load C hariot Ex t
pac k age require C hariot Ex t
pac k age require Apt ix iaC lient 2. 0
# C reat e a new t es t .
put s " C reat e t he t es t . . . "
s et t es t [ c hrTes t new ]
# N ow get t he c urrent ref erenc e t o t he t es t s erv er
put s " Get t ing t he t es t s erv er ref erenc e"
if {[ c at c h {c hrTes t get Tes t Serv erSes s ion $t es t my H os t my Port my Ses s ion}] } {
pLogError $t es t $errorC ode " c hrTes t get Tes t Serv erSes s ion $t es t
my H os t my Port
my Ses s ion"
c hrTes t delet e $t es t
ret urn
}
# Set t he t es t f ilename f or s av ing lat er.
put s " Set t es t f ilename. . . "
if {[ c at c h {c hrTes t s et $t es t FI LEN AME $t es t File}] } {
pLogError $t es t $errorC ode " c hrTes t s et FI LEN AME"
c hrTes t delet e $t es t
ret urn
}
# D ef ine s ome pairs f or t he t es t .
f or {s et index 0} {$index < $pairC ount } {inc r index } {
# C reat e a pair.
put s " C reat e a pair. . . "
s et pair [ c hrPair new ]
# Set pair at t ribut es f rom our lis t s .
put s " Set pair at t t ribut es . . . "
c hrPair s et $pair C OMMEN T " Pair [ ex pr $index + 1] "
c hrP ai r s et $pai r E 1_A D D R $e1A ddrs
c hrP ai r s et $pai r E 2_A D D R $e2A ddrs
c hrPair s et $pair U SE_C ON SOLE_E1 True

- 1124 -

IxChariot APIGuide
c hrP ai r s et $pai r U S E _ S E T U P _ E 1_E 2 F al s e
c hrP ai r s et $pai r C ON S OLE _ E 1_A D D R $e1M gm t
c hrP ai r s et $pai r S E T U P _ E 1_E 2_ A D D R $e2A ddrs
c hrPair s et $pair PR OTOC OL $prot oc ols
# D ef ine a s c ript f or us e by t his pair.
# W e need t o c hec k f or errors w it h ex t ended inf o here.
s et s c ript $s c ript s
if {[ c at c h {c hrPair us eSc ript $pair $s c ript }] } {
pLogError $pair $errorC ode " c hrPair us eSc ript "
c hrTes t delet e $t es t
ret urn
}
# Add t he pair t o t he t es t .
put s " Add t he pair t o t he t es t . . . "
if {[ c at c h {c hrTes t addPair $t es t $pair}] } {
pLogError $t es t $errorC ode " c hrTes t addPair"
c hrTes t delet e $t es t
ret urn
}
}
put s " C onf igure ix ia endpoint s us ing Apt I x ia. . . "
s et my C onf ig [ c onf igureI x iaPort s $my H os t $my Port $my Ses s ion $e1_
mgmt $e2_mgmt ]
put s " I mport ing t he ix ia c onf igurat ion. . . "
i f {[ c at c h {c hrT es t s et $t es t I X I A _N E T W OR K _ C ON F I GU R A T I ON $m y C onf ig}] } {
pLogE rror $t es t $errorC ode " c hrT es t s et $t es t I X I A _N E T W OR K _
C ON FI GU R ATI ON "
c hrTes t delet e $t es t
ret urn
}
# The t es t is c omplet e, s o now w e c an run it .
put s " R un t he t es t . . . "
if {[ c at c h {c hrTes t s t art $t es t }] } {
pLogError $t es t $errorC ode " c hrTes t s t art "
c hrTes t delet e $t es t
ret urn
}
# W ait f or t he t es t t o s t op.
# W e' ll c hec k in a loop here ev ery 5 s ec onds
# t hen c all it an error af t er t w o minut es if
# t he t es t is s t ill not s t opped.
s et t imer 0
s et is St opped 0
put s " W ait ing f or t he t es t t o s t op. . . "
w hile {! $is St opped && $t imer < $max W ait } {
s et is St opped [ c hrTes t is St opped $t es t $t imeout ]
if {! $is St opped} {
s et t imer [ ex pr $t imer + $t imeout ]
put s " W ait ing f or t es t t o s t op. . . ($t imer)"
}
}
if {! $is St opped} {

- 1125 -

IxChariot APIGuide
# Show t his as a t imed out error
s et rc " C H R API 118"
pLogError $t es t $rc " c hrTes t is St opped"
c hrTes t delet e $t es t
ret urn
}
# Sav e t he t es t s o w e c an s how res ult s lat er.
put s " Sav e t he t es t . . . "
if {[ c at c h {c hrTes t s av e $t es t }] } {
pLogError $t es t $errorC ode " c hrTes t s av e"
ret urn
}
c hrTes t delet e $t es t
# W e' re f inis hed!
ret urn

GUI Representation
If you load the XML file generated from the Tcl API script into the Stack Manager GUI, it
should appear as shown in the following figure.

- 1126 -

IxChariot APIGuide

Sample MAC Range Script

This section presents a sample Tcl script for creating a MAC Range. This script implements
an IP-over-Ethernet protocol stack.

Test Topology
This script requires an Ixia chassis with two Ethernet ports connected back-to-back.

Plugin Layout
This script implements a basic IP over Ethernet plugin structure:

MAC Range Tcl Script Listing

Following is the sample Tcl script for creating a MAC Range for use in an IP-over-Ethernet
protocol stack. The script file name is ChrSM_MacRangeTest.tcl.
#***************************************************************
#
# I x C hariot API SD K
File: C hrSM_Mac R angeTes t . t c l
#
# This module c ont ains c ode made av ailable by I x ia on an AS I S
# bas is . Any one rec eiv ing t he module is c ons idered t o be
# lic ens ed under I x ia c opy right s t o us e t he I x ia-prov ided
# s ourc e c ode in any w ay he or s he deems f it , inc luding c opy ing
# it , c ompiling it , modif y ing it , and redis t ribut ing it , w it h
# or w it hout modif ic at ions . N o lic ens e under any I x ia pat ent s
# or pat ent applic at ions is t o be implied f rom t his c opy right
# lic ens e.
#
# A us er of t he module s hould unders t and t hat I x ia c annot
# prov ide t ec hnic al s upport f or t he module and w ill not be
# res pons ible f or any c ons equenc es of us e of t he program.
#
# Any not ic es , inc luding t his one, are not t o be remov ed f rom
# t he module w it hout t he prior w rit t en c ons ent of I x ia.
#
# For more inf ormat ion, c ont ac t :
#
# Ixia
# 26601 W . Agoura R d.
# C alabas as , C A 91302 U SA
# W eb: ht t p: / / w w w . ix iac om. c om
# Phone: 818-871-1800
# Fax : 818-871-1805
#
# General I nf ormat ion:
#
e-mail: inf o@ ix iac om. c om

- 1127 -

IxChariot APIGuide
#
# Tec hnic al Support :
#
e-mail: s upport @ ix iac om. c om
#
#
# EXAMPLE: I x ia Endpoint Pairs Tes t
# This s c ript c reat es and runs a t es t w it h ix ia endpoint pairs
# demons t art es t he us age of mac ranges and how it binds t o t he
# ip int erf ac e in Apt ix ia, t hen s av es t he c hariot t es t t o a f ile.
#
# All at t ribut es of t his t es t are def ined by t his s c ript .
#
#***************************************************************
#***************************************************************
# D at a f or t es t :
# C hange t hes e v alues f or y our net w ork if des ired.
#***************************************************************
s et t es t File " C : / Program Files / I x ia/ I x C hariot / Tes t s / C hrSM_
Mac R angeTes t . t s t "
s et pairC ount 1
s et e1Addrs " 172. 16. 1. 1"
s et e2Addrs " 172. 16. 2. 1"
s et prot oc ols " TC P"
s et s c ript s " c : / Program Files / I x ia/ I x C hariot / Sc ript s / R es pons e_Time. s c r"
s et t imeout 5
s et max W ait 180
s et logFile " pairs Tes t . log"
s et C H A S S I S 1_I P 192. 168. 4. 170
s et e1_m gm t " 192. 168. 4. 170; 1; 1"
s et e2_m gm t " 192. 168. 4. 170; 1; 2"
s et e1Mgmt " 192. 168. 4. 170 / 01 / 01"
s et e2Mgmt " 192. 168. 4. 170 / 01 / 02"
s et gat ew ay 1 172. 16. 2. 1
s et gat ew ay 2 172. 16. 1. 1
#***************************************************************
# Proc edure t o c onf igure ix ia port us ing Apt ix ia API
#***************************************************************
proc c onf igureI x iaPort s {my H os t my Port my Ses s ion e1_mgmt e2_mgmt } {
global C H ASSI S1_I P e1Addrs e2Addrs gat ew ay 1 gat ew ay 2
# St art t es t Serv er and us e t he ins t anc e inv ok ed by ix c hariot
# -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -# This s ec t ion of c ode s et ' s
# t he " s erv er t rans ac t ion c ont ex t " `t c ' t o a part ic ular t es t s erv er
#
s et t c [ : : Apt ix iaC lient : : C ore: : Fac ilit y Get D ef ault Trans ac t ionC ont ex t ]
$t c I nit $my H os t $my Port
s e t : : m y S e s O b j [ : : A p t i x i a C l i e n t : : S e s s i o n % A U T O % -t r a n s a c t i o n c o n t e x t
$t c objec t id $my Ses s ion]
#
# Get ex is t ing t es t f rom our t es t s erv er s es s ion
#
s e t : : m y T e s t I d [ $ : : m y S e s O b j e d i t a b l e T e s t c g e t -o b j e c t i d ]

- 1128 -

IxChariot APIGuide
s et : : my Tes t [ : : Apt ix iaC lient : : Generic Tes t Model %AU TO% -t rans ac t ionc ont ex t $t c
-o b j e c t i d $ : : m y T e s t I d ]
#
# Add s ome c has s is ' s int o t he t es t model
# t he c has s is ' s are in t he s ubobjec t pat hw ay
#
# c h a s s i s C o n f i g -> c h a s s i s C h a i n
#
$: : my Tes t c has s is C onf ig c has s is C hain AddTail
s et c c Obj [ $: : my Tes t c has s is C onf ig c has s is C hain Get 0]
$c c Obj dns S et " $C H A S S I S 1_I P " ; # s et c has s i s nam e
$c c Obj c ableLengt h Set 3
$c c Obj phy s ic alC hain Set f als e
###
# Set up f irs t port group
s et port Spec " $e1_mgmt "
s e t p g _i d x [ e x p r [ $ : : m y T e s t p o r t G r o u p L i s t S i z e ] -2 ]
s et pgObj [ $: : my Tes t port GroupLis t Get $pg_idx ]
$pgObj name Set " My f irs t port group"
$pgObj port Lis t AddTail $port Spec
# Set up Et hernet St ac k on " My f irs t port group" - pgObj
$pgObj _I ns t ant i at e s t ac k " E t hernet P l ugi n"
$pgObj s t ac k enabled Set t rue
$pgObj s t ac k mac R angeLis t AddTail
s et mac R Obj [ $pgObj s t ac k mac R angeLis t Get 0]
$mac R Obj name Set " mac -range"
$mac R Obj mac Set " 00: 00: 00: 00: 00: 01"
# Set up I P plugin on " My f irs t port group" - pgObj
$pgObj s t ac k c hildrenLis t AddTail -it emt y pe " I pV4V6Plugin"
s et ippObj [ $pgObj s t ac k c hildrenLis t Get 0]
$ippObj rangeLis t AddTail
s et iprObj [ $ippObj rangeLis t Get 0]
# Bind t he ip range objec t t o t he mac range
$iprObj _Bind mac R ange $mac R Obj
$iprObj enabled Set t rue
$iprObj ipTy pe Set I Pv 4
$iprObj ipAddres s Set $e1Addrs
$iprObj inc rement By Set 0. 0. 0. 1
$iprObj pref ix Set 16
$iprObj c ount Set 1
$iprObj gat ew ay Addres s Set $gat ew ay 1
# Add s ec ond c has s is t o t he lis t
$: : my Tes t c has s is C onf ig c has s is C hain AddTail
s et c c Obj [ $: : my Tes t c has s is C onf ig c has s is C hain Get 1]
$c c Obj dns S et " $C H A S S I S 1_I P " ; # s et c has s i s nam e
$c c Obj c ableLengt h Set 3
$c c Obj phy s ic alC hain Set f als e
###
# Set up s ec ond port group
s et port Spec $e2_mgmt
s et pg_idx [ ex pr [ $: : my Tes t port GroupLis t Siz e] -1]
s et pgObj1 [ $: : my Tes t port GroupLis t Get $pg_idx ]

- 1129 -

IxChariot APIGuide

$pgObj1 name Set " My Sec ond Port Group"

$pgObj1 port Lis t AddTail $port Spec
Set up Et hernet St ac k on " My s ec ond Port Group" - pgObj1
$pgObj1 _I ns t ant iat e s t ac k " Et hernet Plugin"
$pgObj1 s t ac k enabled Set t rue
$pgObj1 s t ac k mac R angeLis t AddTail
s et mac R Obj1 [ $pgObj1 s t ac k mac R angeLis t Get 0]
$ m a c R O b j 1 n a m e S e t " m a c -r a n g e "
$mac R Obj1 mac Set " 00: 00: 00: 00: 02: 02"
Set up I P plugin on " My s ec ond Port Group" - pgObj1
$ p g O b j 1 s t a c k c h i l d r e n L i s t A d d T a i l -i t e m t y p e " I p V 4 V 6 P l u g i n "
s et ippObj [ $pgObj1 s t ac k c hildrenLis t Get 0]
$ippObj rangeLis t AddTail
s et iprObj [ $ippObj rangeLis t Get 0]
Bind t he ip range objec t t o t he mac range
$iprObj _Bind mac R ange $mac R Obj1
$iprObj enabled Set t rue
$iprObj ipTy pe Set I Pv 4
$iprObj ipAddres s Set $e2Addrs
$iprObj inc rement By Set 0. 0. 0. 1
$iprObj gat ew ay Addres s Set $gat ew ay 2
$iprObj pref ix Set 16
$iprObj c ount Set 1
prompt $int erac t iv e " hit ret urn t o Tes t C onf igure"
$: : my Tes t Tes t C onf igure ; # applied c onf ig on port s
# All enums f or objec t s are pre-def ined w it hin t he objec t c las s as
# r e a d -o n l y c l a s s v a r i a b l e s , l i k e
# `k D eep' `k Shallow ' et c . . .
s et x m l 1 [ l i ndex [ $: : m y T es t _Get X m l \
$: : Apt ix iaC lient : : XProt oc olObjec t : : eSerializ at ionD ept h: : k D eep \
t rue] 0]
put s s t dout $x ml1
ret urn $x ml1

}
#***************************************************************
# Proc edure t o log errors if t here is ex t ended inf o
#***************************************************************
proc pLogError {handle c ode w here} {
global logFile
# D ef ine s y mbols f or t he errors w e' re int eres t ed in.
s et C H R _OPER ATI ON _FAI LED " C H R API 108"
s et C H R _OB J E C T _I N V A LI D " C H R A P I 112"
# Somet hing f ailed: s how w hat happened.
put s " $w here f ailed: [ c hrApi get R et urnMs g $c ode] "
# See if t here is ex t ended error inf ormat ion av ailable.
# I t ' s is only meaningf ul f or c ert ain errors .
if {$c ode = = $C H R _OPER ATI ON _FAI LED
|| $c ode = = $C H R _ OB J E C T _I N V A LI D } {
# Try t o get t he ex t ended error inf ormat ion
s et rc [ c at c h {s et inf o [ c hrC ommonError get I nf o \
$handle " ALL" ] }]
if {$rc ! = 0} {
# W e c an ignore all non-s uc c es s ret urn c odes here

- 1130 -

IxChariot APIGuide
# bec aus e mos t s hould not oc c ur (t he api' s been
# init ializ ed and t he det ail lev el is ok ay ),
# and t he N O_S U C H _ V A LU E ret urn c ode here m eans
# t here is no inf o av ailable.
s et inf o " < N one> "
}
s et logFile [ open $logFile a+ ]
s et t imes t amp [ c loc k f ormat [ c loc k s ec onds ] ]
put s $logFile " $t imes t amp $w here f ailed"
put s $logFile " $t imes t amp $inf o"
# Flus h f orc es immediat e w rit e t o f ile
f lus h $logFile
}
}
#***************************************************************
#
# Sc ript main
#
# c at c h is us ed w hen t here c ould be ex t ended error inf ormat ion,
# s o w e c an log w hat happened.
#***************************************************************
# Load t he C hariot API .
#
# N OTE: I f y ou are us ing Tc l Vers ion 8. 0. p5 or older
# t hen y ou w ill need t o modif y t he f ollow ing lines t o load and
# us e C hariot ins t ead of C hariot Ex t . For ex ample:
# load C hariot
# pac k age require C hariot
l append : : aut o_pat h " c : / P rogram \ F i l es / i x i a/ i x c hari ot / apt i x i a/ l i b/ c om m on/
t c lc lient "
load C hariot Ex t
pac k age require C hariot Ex t
pac k age require Apt ix iaC lient 2. 0
# C reat e a new t es t .
put s " C reat e t he t es t . . . "
s et t es t [ c hrTes t new ]
# N ow get t he c urrent ref erenc e t o t he t es t s erv er
put s " Get t ing t he t es t s erv er ref erenc e"
if {[ c at c h {c hrTes t get Tes t Serv erSes s ion $t es t my H os t my Port my Ses s ion}] } {
pLogError $t es t $errorC ode " c hrTes t get Tes t Serv erSes s ion $t es t
my H os t my Port
my Ses s ion"
c hrTes t delet e $t es t
ret urn
}
# Set t he t es t f ilename f or s av ing lat er.
put s " Set t es t f ilename. . . "
if {[ c at c h {c hrTes t s et $t es t FI LEN AME $t es t File}] } {
pLogError $t es t $errorC ode " c hrTes t s et FI LEN AME"
c hrTes t delet e $t es t
ret urn
}

- 1131 -

IxChariot APIGuide
# D ef ine s ome pairs f or t he t es t .
f or {s et index 0} {$index < $pairC ount } {inc r index } {
# C reat e a pair.
put s " C reat e a pair. . . "
s et pair [ c hrPair new ]
# Set pair at t ribut es f rom our lis t s .
put s " Set pair at t t ribut es . . . "
c hrPair s et $pair C OMMEN T " Pair [ ex pr $index + 1] "
c hrP ai r s et $pai r E 1_A D D R $e1A ddrs
c hrP ai r s et $pai r E 2_A D D R $e2A ddrs
c hrPair s et $pair U SE_C ON SOLE_E1 True
c hrP ai r s et $pai r U S E _ S E T U P _ E 1_E 2 F al s e
c hrP ai r s et $pai r C ON S OLE _ E 1_A D D R $e1M gm t
c hrP ai r s et $pai r S E T U P _ E 1_E 2_ A D D R $e2A ddrs
c hrPair s et $pair PR OTOC OL $prot oc ols
# D ef ine a s c ript f or us e by t his pair.
# W e need t o c hec k f or errors w it h ex t ended inf o here.
s et s c ript $s c ript s
if {[ c at c h {c hrPair us eSc ript $pair $s c ript }] } {
pLogError $pair $errorC ode " c hrPair us eSc ript "
c hrTes t delet e $t es t
ret urn
}
# Add t he pair t o t he t es t .
put s " Add t he pair t o t he t es t . . . "
if {[ c at c h {c hrTes t addPair $t es t $pair}] } {
pLogError $t es t $errorC ode " c hrTes t addPair"
c hrTes t delet e $t es t
ret urn
}
}
put s " C onf igure ix ia endpoint s us ing Apt I x ia. . . "
s et my C onf ig [ c onf igureI x iaPort s $my H os t $my Port $my Ses s ion $e1_
mgmt $e2_mgmt ]
put s " I mport ing t he ix ia c onf igurat ion. . . "
i f {[ c at c h {c hrT es t s et $t es t I X I A _N E T W OR K _ C ON F I GU R A T I ON $m y C onf ig}] } {
pLogE rror $t es t $errorC ode " c hrT es t s et $t es t I X I A _N E T W OR K _
C ON FI GU R ATI ON "
c hrTes t delet e $t es t
ret urn
}
# The t es t is c omplet e, s o now w e c an run it .
put s " R un t he t es t . . . "
if {[ c at c h {c hrTes t s t art $t es t }] } {
pLogError $t es t $errorC ode " c hrTes t s t art "
c hrTes t delet e $t es t
ret urn
}
# W ait f or t he t es t t o s t op.
# W e' ll c hec k in a loop here ev ery 5 s ec onds
# t hen c all it an error af t er t w o minut es if
# t he t es t is s t ill not s t opped.

- 1132 -

IxChariot APIGuide
s et t imer 0
s et is St opped 0
put s " W ait ing f or t he t es t t o s t op. . . "
w hile {! $is St opped && $t imer < $max W ait } {
s et is St opped [ c hrTes t is St opped $t es t $t imeout ]
if {! $is St opped} {
s et t imer [ ex pr $t imer + $t imeout ]
put s " W ait ing f or t es t t o s t op. . . ($t imer)"
}
}
if {! $is St opped} {
# Show t his as a t imed out error
s et rc " C H R API 118"
pLogError $t es t $rc " c hrTes t is St opped"
c hrTes t delet e $t es t
ret urn
}
# Sav e t he t es t s o w e c an s how res ult s lat er.
put s " Sav e t he t es t . . . "
if {[ c at c h {c hrTes t s av e $t es t }] } {
pLogError $t es t $errorC ode " c hrTes t s av e"
ret urn
}
c hrTes t delet e $t es t
# W e' re f inis hed!
ret urn

GUI Representation
If you load the XML file generated from the Tcl API script into the Stack Manager GUI, it
should appear as shown in the following figure.

- 1133 -

IxChariot APIGuide

- 1134 -

IxChariot APIGuide

Sample DHCP Script

This section presents a sample Tcl script for creating an IPv4 interface, using dynamic IP
address allocation. This script implements an IP-over-Ethernet protocol stack.

Test Topology
This script requires an Ixia chassis with two Ethernet ports connected back-to-back.

Plugin Layout
This script implements a basic IP over Ethernet plugin structure:

DHCP Tcl Script Listing

Following is the sample Tcl script for creating an IPv4 interface that uses dynamic IP
address allocation. The script file name is ChrSM_DHCP_DUT_Test.tcl.
#***************************************************************
#
# I x C hariot API SD K
F i l e: C hrS M _ D H C P _D U T _T es t . t c l
#
# This module c ont ains c ode made av ailable by I x ia on an AS I S
# bas is . Any one rec eiv ing t he module is c ons idered t o be
# lic ens ed under I x ia c opy right s t o us e t he I x ia-prov ided
# s ourc e c ode in any w ay he or s he deems f it , inc luding c opy ing
# it , c ompiling it , modif y ing it , and redis t ribut ing it , w it h
# or w it hout modif ic at ions . N o lic ens e under any I x ia pat ent s
# or pat ent applic at ions is t o be implied f rom t his c opy right
# lic ens e.
#
# A us er of t he module s hould unders t and t hat I x ia c annot
# prov ide t ec hnic al s upport f or t he module and w ill not be
# res pons ible f or any c ons equenc es of us e of t he program.
#
# Any not ic es , inc luding t his one, are not t o be remov ed f rom
# t he module w it hout t he prior w rit t en c ons ent of I x ia.
#
# For more inf ormat ion, c ont ac t :
#
# Ixia
# 26601 W . Agoura R d.
# C alabas as , C A 91302 U SA
# W eb: ht t p: / / w w w . ix iac om. c om
# Phone: 818-871-1800
# Fax : 818-871-1805
#
# General I nf ormat ion:

- 1135 -

IxChariot APIGuide
#
e-mail: inf o@ ix iac om. c om
#
# Tec hnic al Support :
#
e-mail: s upport @ ix iac om. c om
#
#
# EXAMPLE: I x ia Endpoint Pairs Tes t
# This s c ript c reat es and runs a t es t w it h ix ia endpoint pairs
# us ing I P Plugin as a D H C P c lient on bot h ends . For t he s c ript t o w ork
# D H C P s erv er needs t o be enabled on t he D U T.
#
# All at t ribut es of t his t es t are def ined by t his s c ript .
#
#***************************************************************
#***************************************************************
# D at a f or t es t :
# C hange t hes e v alues f or y our net w ork if des ired.
#***************************************************************
s et t es t F i l e " C : / P rogram F i l es / I x i a/ I x C hari ot / T es t s / C hrS M _ D H C P _D U T _
Tes t . t s t "
s et pairC ount 1
s et prot oc ols " TC P"
s et s c ript s " c : / Program Files / I x ia/ I x C hariot / Sc ript s / R es pons e_Time. s c r"
s et t imeout 5
s et max W ait 180
s et logFile " pairs Tes t . log"
s et C H A S S I S 1_I P 192. 168. 7. 41
s et e1_m gm t " 192. 168. 7. 41; 1; 1"
s et e2_m gm t " 192. 168. 7. 41; 1; 2"
s et e1Mgmt " 192. 168. 7. 41 / 01 / 01"
s et e2Mgmt " 192. 168. 7. 41 / 01 / 02"
#***************************************************************
# Proc edure t o c onf igure ix ia port us ing Apt ix ia API
#***************************************************************
proc c onf igureI x iaPort s {my H os t my Port my Ses s ion e1_mgmt e2_mgmt } {
global C H ASSI S1_I P
# St art t es t Serv er and us e t he ins t anc e inv ok ed by ix c hariot
# -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -# This s ec t ion of c ode s et ' s
# t he " s erv er t rans ac t ion c ont ex t " `t c ' t o a part ic ular t es t s erv er
#
s et t c [ : : Apt ix iaC lient : : C ore: : Fac ilit y Get D ef ault Trans ac t ionC ont ex t ]
$t c I nit $my H os t $my Port
s e t : : m y S e s O b j [ : : A p t i x i a C l i e n t : : S e s s i o n % A U T O % -t r a n s a c t i o n c o n t e x t
$t c objec t id $my Ses s ion]
#
# Get ex is t ing t es t f rom our t es t s erv er s es s ion
#
s e t : : m y T e s t I d [ $ : : m y S e s O b j e d i t a b l e T e s t c g e t -o b j e c t i d ]
s et : : my Tes t [ : : Apt ix iaC lient : : Generic Tes t Model %AU TO% -t rans ac t ionc ont ex t $t c
-o b j e c t i d $ : : m y T e s t I d ]

- 1136 -

IxChariot APIGuide

#
# Add s ome c has s is ' s int o t he t es t model
# t he c has s is ' s are in t he s ubobjec t pat hw ay
#
# c h a s s i s C o n f i g -> c h a s s i s C h a i n
#
$: : my Tes t c has s is C onf ig c has s is C hain AddTail
s et c c Obj [ $: : my Tes t c has s is C onf ig c has s is C hain Get 0]
$c c Obj dns S et " $C H A S S I S 1_I P " ; # s et c has s i s nam e
$c c Obj c ableLengt h Set 3
$c c Obj phy s ic alC hain Set f als e
###
Set up f irs t port group
s et port Spec " $e1_mgmt "
s e t p g _i d x [ e x p r [ $ : : m y T e s t p o r t G r o u p L i s t S i z e ] -2 ]
s et pgObj [ $: : my Tes t port GroupLis t Get $pg_idx ]
$pgObj name Set " C lient N et w ork 1"
$pgObj port Lis t AddTail $port Spec
Set up Et hernet St ac k on " My f irs t port group" - pgObj
$pgObj _I ns t ant i at e s t ac k " E t hernet P l ugi n"
$pgObj s t ac k enabled Set t rue
$pgObj s t ac k mac Set " 00: 00: 00: 00: 01: 01"
Set up I P plugin on " My f irs t port group" - pgObj
$pgObj s t ac k c hildrenLis t AddTail -it emt y pe " I pV4V6Plugin"
s et ippObj [ $pgObj s t ac k c hildrenLis t Get 0]
$ippObj rangeLis t AddTail
s et iprObj [ $ippObj rangeLis t Get 0]
$iprObj enabled Set t rue
$iprObj ipTy pe Set I Pv 4
$iprObj addres s Alloc at ionMec hanis m Set " dhc p"
$iprObj _I ns t ant iat e dhc pSet t ings " D hc pSet t ings "
$iprObj dhc pSet t ings t imeOut Set 20
Add s ec ond c has s is t o t he lis t
$: : my Tes t c has s is C onf ig c has s is C hain AddTail
s et c c Obj [ $: : my Tes t c has s is C onf ig c has s is C hain Get 1]
$c c Obj dns S et " $C H A S S I S 1_I P " ; # s et c has s i s nam e
$c c Obj c ableLengt h Set 3
$c c Obj phy s ic alC hain Set f als e
###
Set up s ec ond port group
s et port Spec $e2_mgmt
s et pg_idx [ ex pr [ $: : my Tes t port GroupLis t Siz e] -1]
s et pgObj1 [ $: : my Tes t port GroupLis t Get $pg_idx ]
$pgObj1 name Set " C lient N et w ork 2"
$pgObj1 port Lis t AddTail $port Spec
Set up Et hernet St ac k on " My s ec ond Port Group" - pgObj1
$pgObj1 _I ns t ant iat e s t ac k " Et hernet Plugin"
$pgObj1 s t ac k enabled Set t rue
$pgObj1 s t ac k mac Set " 00: 00: 00: 00: 02: 02"
Set up I P plugin on " My s ec ond Port Group" - pgObj1
$ p g O b j 1 s t a c k c h i l d r e n L i s t A d d T a i l -i t e m t y p e " I p V 4 V 6 P l u g i n "
s et ippObj [ $pgObj1 s t ac k c hildrenLis t Get 0]
$ippObj rangeLis t AddTail

- 1137 -

IxChariot APIGuide
s et iprObj [ $ippObj rangeLis t Get 0]
$iprObj enabled Set t rue
$iprObj ipTy pe Set I Pv 4
$iprObj addres s Alloc at ionMec hanis m Set " dhc p"
$iprObj _I ns t ant iat e dhc pSet t ings " D hc pSet t ings "
$iprObj dhc pSet t ings t imeOut Set 20
# prompt $int erac t iv e " hit ret urn t o Tes t C onf igure"
$: : my Tes t Tes t C onf igure ; # applied c onf ig on port s
# All enums f or objec t s are pre-def ined w it hin t he objec t c las s as
# r e a d -o n l y c l a s s v a r i a b l e s , l i k e
# `k D eep' `k Shallow ' et c . . .
s et x m l 1 [ l i ndex [ $: : m y T es t _Get X m l \
$: : Apt ix iaC lient : : XProt oc olObjec t : : eSerializ at ionD ept h: : k D eep \
t rue] 0]
put s s t dout $x ml1
ret urn $x ml1
}
#***************************************************************
# Proc edure t o log errors if t here is ex t ended inf o
#***************************************************************
proc pLogError {handle c ode w here} {
global logFile
# D ef ine s y mbols f or t he errors w e' re int eres t ed in.
s et C H R _OPER ATI ON _FAI LED " C H R API 108"
s et C H R _OB J E C T _I N V A LI D " C H R A P I 112"
# Somet hing f ailed: s how w hat happened.
put s " $w here f ailed: [ c hrApi get R et urnMs g $c ode] "
# See if t here is ex t ended error inf ormat ion av ailable.
# I t ' s is only meaningf ul f or c ert ain errors .
if {$c ode = = $C H R _OPER ATI ON _FAI LED
|| $c ode = = $C H R _ OB J E C T _I N V A LI D } {
# Try t o get t he ex t ended error inf ormat ion
s et rc [ c at c h {s et inf o [ c hrC ommonError get I nf o \
$handle " ALL" ] }]
if {$rc ! = 0} {
# W e c an ignore all non-s uc c es s ret urn c odes here
# bec aus e mos t s hould not oc c ur (t he api' s been
# init ializ ed and t he det ail lev el is ok ay ),
# and t he N O_S U C H _ V A LU E ret urn c ode here m eans
# t here is no inf o av ailable.
s et inf o " < N one> "
}
s et logFile [ open $logFile a+ ]
s et t imes t amp [ c loc k f ormat [ c loc k s ec onds ] ]
put s $logFile " $t imes t amp $w here f ailed"
put s $logFile " $t imes t amp $inf o"
# Flus h f orc es immediat e w rit e t o f ile
f lus h $logFile
}
}
#***************************************************************
#
# Sc ript main

- 1138 -

IxChariot APIGuide
#
# c at c h is us ed w hen t here c ould be ex t ended error inf ormat ion,
# s o w e c an log w hat happened.
#***************************************************************
# Load t he C hariot API .
#
# N OTE: I f y ou are us ing Tc l Vers ion 8. 0. p5 or older
# t hen y ou w ill need t o modif y t he f ollow ing lines t o load and
# us e C hariot ins t ead of C hariot Ex t . For ex ample:
# load C hariot
# pac k age require C hariot
l append : : aut o_pat h " c : / P rogram \ F i l es / i x i a/ i x c hari ot / apt i x i a/ l i b/ c om m on/
t c lc lient "
load C hariot Ex t
pac k age require C hariot Ex t
pac k age require Apt ix iaC lient 2. 0
# C reat e a new t es t .
put s " C reat e t he t es t . . . "
s et t es t [ c hrTes t new ]
# N ow get t he c urrent ref erenc e t o t he t es t s erv er
put s " Get t ing t he t es t s erv er ref erenc e"
if {[ c at c h {c hrTes t get Tes t Serv erSes s ion $t es t my H os t my Port my Ses s ion}] } {
pLogError $t es t $errorC ode " c hrTes t get Tes t Serv erSes s ion $t es t
my H os t my Port
my Ses s ion"
c hrTes t delet e $t es t
ret urn
}
# Set t he t es t f ilename f or s av ing lat er.
put s " Set t es t f ilename. . . "
if {[ c at c h {c hrTes t s et $t es t FI LEN AME $t es t File}] } {
pLogError $t es t $errorC ode " c hrTes t s et FI LEN AME"
c hrTes t delet e $t es t
ret urn
}
put s " C onf igure ix ia endpoint s us ing Apt I x ia. . . "
s et my C onf ig [ c onf igureI x iaPort s $my H os t $my Port $my Ses s ion $e1_
mgmt $e2_mgmt ]
put s " I mport ing t he ix ia c onf igurat ion. . . "
i f {[ c at c h {c hrT es t s et $t es t I X I A _N E T W OR K _ C ON F I GU R A T I ON $m y C onf ig}] } {
pLogE rror $t es t $errorC ode " c hrT es t s et $t es t I X I A _N E T W OR K _
C ON FI GU R ATI ON "
c hrTes t delet e $t es t
ret urn
}
# D ef ine s ome pairs f or t he t es t .
f or {s et index 0} {$index < $pairC ount } {inc r index } {
# C reat e a pair.
put s " C reat e a pair. . . "
s et pair [ c hrPair new ]
# Set pair at t ribut es f rom our lis t s .

- 1139 -

IxChariot APIGuide
put s " Set pair at t t ribut es . . . "
c hrPair s et $pair C OMMEN T " Pair [ ex pr $index + 1] "
c hrP ai r s et $pai r E 1_A D D R " C l i ent N et w ork 1"
c hrP ai r s et $pai r E 2_A D D R " C l i ent N et w ork 2"
c hrPair s et $pair U SE_C ON SOLE_E1 True
c hrP ai r s et $pai r U S E _ S E T U P _ E 1_E 2 T rue
c hrP ai r s et $pai r C ON S OLE _ E 1_A D D R " U s e I x i a N et w ork C onf i gurat i on"
c hrP ai r s et $pai r S E T U P _ E 1_E 2_ A D D R " U s e I x i a N et w ork C onf igurat ion"
c hrPair s et $pair PR OTOC OL $prot oc ols
# D ef ine a s c ript f or us e by t his pair.
# W e need t o c hec k f or errors w it h ex t ended inf o here.
s et s c ript $s c ript s
if {[ c at c h {c hrPair us eSc ript $pair $s c ript }] } {
pLogError $pair $errorC ode " c hrPair us eSc ript "
c hrTes t delet e $t es t
ret urn
}
# Add t he pair t o t he t es t .
put s " Add t he pair t o t he t es t . . . "
if {[ c at c h {c hrTes t addPair $t es t $pair}] } {
pLogError $t es t $errorC ode " c hrTes t addPair"
c hrTes t delet e $t es t
ret urn
}
}
# The t es t is c omplet e, s o now w e c an run it .
put s " R un t he t es t . . . "
if {[ c at c h {c hrTes t s t art $t es t }] } {
pLogError $t es t $errorC ode " c hrTes t s t art "
c hrTes t delet e $t es t
ret urn
}
# W ait f or t he t es t t o s t op.
# W e' ll c hec k in a loop here ev ery 5 s ec onds
# t hen c all it an error af t er t w o minut es if
# t he t es t is s t ill not s t opped.
s et t imer 0
s et is St opped 0
put s " W ait ing f or t he t es t t o s t op. . . "
w hile {! $is St opped && $t imer < $max W ait } {
s et is St opped [ c hrTes t is St opped $t es t $t imeout ]
if {! $is St opped} {
s et t imer [ ex pr $t imer + $t imeout ]
put s " W ait ing f or t es t t o s t op. . . ($t imer)"
}
}
if {! $is St opped} {
# Show t his as a t imed out error
s et rc " C H R API 118"
pLogError $t es t $rc " c hrTes t is St opped"
c hrTes t delet e $t es t
ret urn

- 1140 -

IxChariot APIGuide
}
# Sav e t he t es t s o w e c an s how res ult s lat er.
put s " Sav e t he t es t . . . "
if {[ c at c h {c hrTes t s av e $t es t }] } {
pLogError $t es t $errorC ode " c hrTes t s av e"
ret urn
}
c hrTes t delet e $t es t
# W e' re f inis hed!
ret urn

GUI Representation
If you load the XML file generated from the Tcl API script into the Stack Manager GUI, it
should appear as shown in the following figure.

- 1141 -

IxChariot APIGuide

Sample Impairment Script

This section presents a sample Tcl script for creating an impaired IP packet.

Test Topology
This script requires an Ixia chassis with two Ethernet ports connected back-to-back.

Plugin Layout
This script implements a IP over Ethernet plugin structure that incorporates an Impairment
plugin and an Emulated Router plugin:

Impairment Test Tcl Script Listing

Following is the sample Tcl script for creating an impaired IP packet. The script file name
is ChrSM_Impairment_Test.tcl.
#***************************************************************
#
# I x C hariot API SD K
F i l e: C hrS M _I m pai rm ent _T es t . t c l
#
# This module c ont ains c ode made av ailable by I x ia on an AS I S
# bas is . Any one rec eiv ing t he module is c ons idered t o be
# lic ens ed under I x ia c opy right s t o us e t he I x ia-prov ided
# s ourc e c ode in any w ay he or s he deems f it , inc luding c opy ing
# it , c ompiling it , modif y ing it , and redis t ribut ing it , w it h
# or w it hout modif ic at ions . N o lic ens e under any I x ia pat ent s
# or pat ent applic at ions is t o be implied f rom t his c opy right
# lic ens e.
#
# A us er of t he module s hould unders t and t hat I x ia c annot
# prov ide t ec hnic al s upport f or t he module and w ill not be
# res pons ible f or any c ons equenc es of us e of t he program.
#
# Any not ic es , inc luding t his one, are not t o be remov ed f rom
# t he module w it hout t he prior w rit t en c ons ent of I x ia.
#
# For more inf ormat ion, c ont ac t :
#
# Ixia
# 26601 W . Agoura R d.
# C alabas as , C A 91302 U SA
# W eb: ht t p: / / w w w . ix iac om. c om
# Phone: 818-871-1800
# Fax : 818-871-1805
#
# General I nf ormat ion:
#
e-mail: inf o@ ix iac om. c om

- 1142 -

IxChariot APIGuide
#
# Tec hnic al Support :
#
e-mail: s upport @ ix iac om. c om
#
#
# EXAMPLE: I x ia Endpoint Pairs Tes t
# This s c ript c reat es and runs a t es t w it h ix ia endpoint pairs
# us ing impairment Plugin, t hen s av es t he c hariot t es t t o a f ile.
#
# All at t ribut es of t his t es t are def ined by t his s c ript .
#
#***************************************************************
#***************************************************************
# D at a f or t es t :
# C hange t hes e v alues f or y our net w ork if des ired.
#***************************************************************
s et t es t File " C : / Program Files / I x ia/ I x C hariot / Tes t s / C hrSM_ I mpairment _
Tes t . t s t "
s et pairC ount 1
s et e1Addrs " 172. 16. 1. 1"
s et e2Addrs " 172. 16. 2. 1"
s et prot oc ols " TC P"
s et s c ript s " c : / Program Files / I x ia/ I x C hariot / Sc ript s / Throughput . s c r"
s et t imeout 5
s et max W ait 180
s et logFile " pairs Tes t . log"
s et C H A S S I S 1_I P 192. 168. 4. 170
s et e1_m gm t " 192. 168. 4. 170; 1; 1"
s et e2_m gm t " 192. 168. 4. 170; 1; 2"
s et e1Mgmt " 192. 168. 4. 170 / 01 / 01"
s et e2Mgmt " 192. 168. 4. 170 / 01 / 02"
s et gat ew ay 1 172. 16. 2. 1
s et gat ew ay 2 172. 16. 1. 1
#***************************************************************
# Proc edure t o c onf igure ix ia port us ing Apt ix ia API
#***************************************************************
proc c onf igureI x iaPort s {my H os t my Port my Ses s ion e1_mgmt e2_mgmt } {
global C H ASSI S1_I P e1Addrs e2Addrs gat ew ay 1 gat ew ay 2
# St art t es t Serv er and us e t he ins t anc e inv ok ed by ix c hariot
# -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -# This s ec t ion of c ode s et ' s
# t he " s erv er t rans ac t ion c ont ex t " `t c ' t o a part ic ular t es t s erv er
#
s et t c [ : : Apt ix iaC lient : : C ore: : Fac ilit y Get D ef ault Trans ac t ionC ont ex t ]
$t c I nit $my H os t $my Port
s e t : : m y S e s O b j [ : : A p t i x i a C l i e n t : : S e s s i o n % A U T O % -t r a n s a c t i o n c o n t e x t
$t c objec t id $my Ses s ion]
#
# Get ex is t ing t es t f rom our t es t s erv er s es s ion
#
s e t : : m y T e s t I d [ $ : : m y S e s O b j e d i t a b l e T e s t c g e t -o b j e c t i d ]
s et : : my Tes t [ : : Apt ix iaC lient : : Generic Tes t Model %AU TO% -

- 1143 -

IxChariot APIGuide
t rans ac t ionc ont ex t $t c
-o b j e c t i d $ : : m y T e s t I d ]
#
# Add s ome c has s is ' s int o t he t es t model
# t he c has s is ' s are in t he s ubobjec t pat hw ay
#
# c h a s s i s C o n f i g -> c h a s s i s C h a i n
#
$: : my Tes t c has s is C onf ig c has s is C hain AddTail
s et c c Obj [ $: : my Tes t c has s is C onf ig c has s is C hain Get 0]
$c c Obj dns S et " $C H A S S I S 1_I P " ; # s et c has s i s nam e
$c c Obj c ableLengt h Set 3
$c c Obj phy s ic alC hain Set f als e
###
# Set up f irs t port group
s et port Spec " $e1_mgmt "
s e t p g _i d x [ e x p r [ $ : : m y T e s t p o r t G r o u p L i s t S i z e ] -2 ]
s et pgObj [ $: : my Tes t port GroupLis t Get $pg_idx ]
$pgObj name Set " My f irs t port group"
$pgObj port Lis t AddTail $port Spec
# Set up Et hernet St ac k on " My Firs t Port Group" - pgObj
$pgObj _I ns t ant i at e s t ac k " E t hernet P l ugi n"
$pgObj s t ac k enabled Set t rue
$pgObj s t ac k mac Set " 00: 00: 00: 00: 01: 01"
# Set up I mpairment plugin
$ p g O b j s t a c k c h i l d r e n L i s t A d d T a i l -i t e m t y p e " I m p a i r m e n t P l u g i n "
s et impObj [ $pgObj s t ac k c hildrenLis t Get 0]
# To add pk t los s
$impObj addD rop Set t rue
#perc ent age of pk t s t o drop
$impObj drop Set 3
# t o add lat enc y
# $impObj addD elay Set t rue
# f or pk t reordering
# $impObj addR eorder Set t rue
# t o s et add pk t duplic at es
# $impObj addD uplic at e Set t rue
# t o limit t he rat e of t raf f ic
# $impObj addBandw idt h Set t rue
# f or randomiz ing t he s eed f or impairment
# $impObj randomiz eSeed Set t rue
# delay in ms t o be added t o eac h pk t
# $impObj delay Set 10
# impairment applied only t o t his ipAddres s
# $impObj des t inat ionI p Set " $gat ew ay 1"
# t o add impair t o all int erf ac es in underly ing et h lay er
# $impObj global Set t rue
# Set up I P plugin on " My f irs t port group" - pgObj
$ i m p O b j c h i l d r e n L i s t A d d T a i l -i t e m t y p e " I p V 4 V 6 P l u g i n "
s et ippObj [ $impObj c hildrenLis t Get 0]
$ippObj rangeLis t AddTail
s et iprObj [ $ippObj rangeLis t Get 0]
$iprObj enabled Set t rue

- 1144 -

IxChariot APIGuide

$iprObj ipTy pe Set I Pv 4

$iprObj ipAddres s Set $e1Addrs
$iprObj inc rement By Set 0. 0. 0. 1
$iprObj pref ix Set 16
$iprObj c ount Set 1
$iprObj gat ew ay Addres s Set $gat ew ay 1
Add s ec ond c has s is t o t he lis t
$: : my Tes t c has s is C onf ig c has s is C hain AddTail
s et c c Obj [ $: : my Tes t c has s is C onf ig c has s is C hain Get 1]
$c c Obj dns S et " $C H A S S I S 1_I P " ; # s et c has s i s nam e
$c c Obj c ableLengt h Set 3
$c c Obj phy s ic alC hain Set f als e
###
Set up s ec ond port group
s et port Spec $e2_mgmt
s et pg_idx [ ex pr [ $: : my Tes t port GroupLis t Siz e] -1]
s et pgObj1 [ $: : my Tes t port GroupLis t Get $pg_idx ]
$pgObj1 name Set " My Sec ond Port Group"
$pgObj1 port Lis t AddTail $port Spec
Set up Et hernet St ac k on " My s ec ond Port Group" - pgObj1
$pgObj1 _I ns t ant iat e s t ac k " Et hernet Plugin"
$pgObj1 s t ac k enabled Set t rue
$pgObj1 s t ac k mac Set " 00: 00: 00: 00: 02: 02"
Set up I P plugin on " My s ec ond Port Group" - pgObj1
$ p g O b j 1 s t a c k c h i l d r e n L i s t A d d T a i l -i t e m t y p e " I p V 4 V 6 P l u g i n "
s et ippObj [ $pgObj1 s t ac k c hildrenLis t Get 0]
$ippObj rangeLis t AddTail
s et iprObj [ $ippObj rangeLis t Get 0]
$iprObj enabled Set t rue
$iprObj ipTy pe Set I Pv 4
$iprObj ipAddres s Set $e2Addrs
$iprObj inc rement By Set 0. 0. 0. 1
$iprObj gat ew ay Addres s Set $gat ew ay 2
$iprObj pref ix Set 16
$iprObj c ount Set 1
prompt $int erac t iv e " hit ret urn t o Tes t C onf igure"
$: : my Tes t Tes t C onf igure ; # applied c onf ig on port s
# All enums f or objec t s are pre-def ined w it hin t he objec t c las s as
# r e a d -o n l y c l a s s v a r i a b l e s , l i k e
# `k D eep' `k Shallow ' et c . . .
s et x m l 1 [ l i ndex [ $: : m y T es t _Get X m l \
$: : Apt ix iaC lient : : XProt oc olObjec t : : eSerializ at ionD ept h: : k D eep \
t rue] 0]
put s s t dout $x ml1
ret urn $x ml1

}
#***************************************************************
# Proc edure t o log errors if t here is ex t ended inf o
#***************************************************************
proc pLogError {handle c ode w here} {
global logFile
# D ef ine s y mbols f or t he errors w e' re int eres t ed in.
s et C H R _OPER ATI ON _FAI LED " C H R API 108"

- 1145 -

IxChariot APIGuide
s et C H R _OB J E C T _I N V A LI D " C H R A P I 112"
# Somet hing f ailed: s how w hat happened.
put s " $w here f ailed: [ c hrApi get R et urnMs g $c ode] "
# See if t here is ex t ended error inf ormat ion av ailable.
# I t ' s is only meaningf ul f or c ert ain errors .
if {$c ode = = $C H R _OPER ATI ON _FAI LED
|| $c ode = = $C H R _ OB J E C T _I N V A LI D } {
# Try t o get t he ex t ended error inf ormat ion
s et rc [ c at c h {s et inf o [ c hrC ommonError get I nf o \
$handle " ALL" ] }]
if {$rc ! = 0} {
# W e c an ignore all non-s uc c es s ret urn c odes here
# bec aus e mos t s hould not oc c ur (t he api' s been
# init ializ ed and t he det ail lev el is ok ay ),
# and t he N O_S U C H _ V A LU E ret urn c ode here m eans
# t here is no inf o av ailable.
s et inf o " < N one> "
}
s et logFile [ open $logFile a+ ]
s et t imes t amp [ c loc k f ormat [ c loc k s ec onds ] ]
put s $logFile " $t imes t amp $w here f ailed"
put s $logFile " $t imes t amp $inf o"
# Flus h f orc es immediat e w rit e t o f ile
f lus h $logFile
}
}
#***************************************************************
#
# Sc ript main
#
# c at c h is us ed w hen t here c ould be ex t ended error inf ormat ion,
# s o w e c an log w hat happened.
#***************************************************************
# Load t he C hariot API .
#
# N OTE: I f y ou are us ing Tc l Vers ion 8. 0. p5 or older
# t hen y ou w ill need t o modif y t he f ollow ing lines t o load and
# us e C hariot ins t ead of C hariot Ex t . For ex ample:
# load C hariot
# pac k age require C hariot
l append : : aut o_pat h " c : / P rogram \ F i l es / i x i a/ i x c hari ot / apt i x i a/ l i b/ c om m on/
t c lc lient "
load C hariot Ex t
pac k age require C hariot Ex t
pac k age require Apt ix iaC lient 2. 0
# C reat e a new t es t .
put s " C reat e t he t es t . . . "
s et t es t [ c hrTes t new ]
# N ow get t he c urrent ref erenc e t o t he t es t s erv er
put s " Get t ing t he t es t s erv er ref erenc e"
if {[ c at c h {c hrTes t get Tes t Serv erSes s ion $t es t my H os t my Port my Ses s ion}] } {
pLogError $t es t $errorC ode " c hrTes t get Tes t Serv erSes s ion $t es t

- 1146 -

IxChariot APIGuide
my H os t my Port
my Ses s ion"
c hrTes t delet e $t es t
ret urn
}
# Set t he t es t f ilename f or s av ing lat er.
put s " Set t es t f ilename. . . "
if {[ c at c h {c hrTes t s et $t es t FI LEN AME $t es t File}] } {
pLogError $t es t $errorC ode " c hrTes t s et FI LEN AME"
c hrTes t delet e $t es t
ret urn
}
# D ef ine s ome pairs f or t he t es t .
f or {s et index 0} {$index < $pairC ount } {inc r index } {
# C reat e a pair.
put s " C reat e a pair. . . "
s et pair [ c hrPair new ]
# Set pair at t ribut es f rom our lis t s .
put s " Set pair at t t ribut es . . . "
c hrPair s et $pair C OMMEN T " Pair [ ex pr $index + 1] "
c hrP ai r s et $pai r E 1_A D D R $e1A ddrs
c hrP ai r s et $pai r E 2_A D D R $e2A ddrs
c hrPair s et $pair U SE_C ON SOLE_E1 True
c hrP ai r s et $pai r U S E _ S E T U P _ E 1_E 2 F al s e
c hrP ai r s et $pai r C ON S OLE _ E 1_A D D R $e1M gm t
c hrP ai r s et $pai r S E T U P _ E 1_E 2_ A D D R $e2A ddrs
c hrPair s et $pair PR OTOC OL $prot oc ols
# D ef ine a s c ript f or us e by t his pair.
# W e need t o c hec k f or errors w it h ex t ended inf o here.
s et s c ript $s c ript s
if {[ c at c h {c hrPair us eSc ript $pair $s c ript }] } {
pLogError $pair $errorC ode " c hrPair us eSc ript "
c hrTes t delet e $t es t
ret urn
}
# Add t he pair t o t he t es t .
put s " Add t he pair t o t he t es t . . . "
if {[ c at c h {c hrTes t addPair $t es t $pair}] } {
pLogError $t es t $errorC ode " c hrTes t addPair"
c hrTes t delet e $t es t
ret urn
}
}
put s " C onf igure ix ia endpoint s us ing Apt I x ia. . . "
s et my C onf ig [ c onf igureI x iaPort s $my H os t $my Port $my Ses s ion $e1_
mgmt $e2_mgmt ]
put s " I mport ing t he ix ia c onf igurat ion. . . "
i f {[ c at c h {c hrT es t s et $t es t I X I A _N E T W OR K _ C ON F I GU R A T I ON $m y C onf ig}] } {
pLogE rror $t es t $errorC ode " c hrT es t s et $t es t I X I A _N E T W OR K _
C ON FI GU R ATI ON "
c hrTes t delet e $t es t
ret urn

- 1147 -

IxChariot APIGuide
}
# The t es t is c omplet e, s o now w e c an run it .
put s " R un t he t es t . . . "
if {[ c at c h {c hrTes t s t art $t es t }] } {
pLogError $t es t $errorC ode " c hrTes t s t art "
c hrTes t delet e $t es t
ret urn
}
# W ait f or t he t es t t o s t op.
# W e' ll c hec k in a loop here ev ery 5 s ec onds
# t hen c all it an error af t er t w o minut es if
# t he t es t is s t ill not s t opped.
s et t imer 0
s et is St opped 0
put s " W ait ing f or t he t es t t o s t op. . . "
w hile {! $is St opped && $t imer < $max W ait } {
s et is St opped [ c hrTes t is St opped $t es t $t imeout ]
if {! $is St opped} {
s et t imer [ ex pr $t imer + $t imeout ]
put s " W ait ing f or t es t t o s t op. . . ($t imer)"
}
}
if {! $is St opped} {
# Show t his as a t imed out error
s et rc " C H R API 118"
pLogError $t es t $rc " c hrTes t is St opped"
c hrTes t delet e $t es t
ret urn
}
# Sav e t he t es t s o w e c an s how res ult s lat er.
put s " Sav e t he t es t . . . "
if {[ c at c h {c hrTes t s av e $t es t }] } {
pLogError $t es t $errorC ode " c hrTes t s av e"
ret urn
}
c hrTes t delet e $t es t
# W e' re f inis hed!
ret urn

GUI Representation
If you load the XML file generated from the Tcl API script into the Stack Manager GUI, it
should appear as shown in the following figure.

- 1148 -

IxChariot APIGuide

- 1149 -

IxChariot APIGuide

Sample IPSec Script (port-to-port)

This section presents a sample Tcl script for creating an IPSec tunnel between two ports.

Test Topology
This script requires an Ixia chassis with two Ethernet ports connected back-to-back.

Plugin Layout
This script implements a IPSec over IP over an Emulated Router. The following diagram
represents the plugins, together with the IP addresses for each of the two ports at each
end of the tunnel:

IPSec Port-to-Port Tcl Script Listing

Following is the sample Tcl script for creating an IPSec tunnel between two ports. The
script file name is ChrSM_IPSec_P2P_Test.tcl.
#***************************************************************
#
# I x C hariot API SD K
File: C hrSM_I PSec _P2P_Tes t . t c l
#
# This module c ont ains c ode made av ailable by I x ia on an AS I S
# bas is . Any one rec eiv ing t he module is c ons idered t o be
# lic ens ed under I x ia c opy right s t o us e t he I x ia-prov ided
# s ourc e c ode in any w ay he or s he deems f it , inc luding c opy ing
# it , c ompiling it , modif y ing it , and redis t ribut ing it , w it h
# or w it hout modif ic at ions . N o lic ens e under any I x ia pat ent s
# or pat ent applic at ions is t o be implied f rom t his c opy right
# lic ens e.
#
# A us er of t he module s hould unders t and t hat I x ia c annot
# prov ide t ec hnic al s upport f or t he module and w ill not be
# res pons ible f or any c ons equenc es of us e of t he program.
#
# Any not ic es , inc luding t his one, are not t o be remov ed f rom
# t he module w it hout t he prior w rit t en c ons ent of I x ia.
#
# For more inf ormat ion, c ont ac t :
#
# Ixia
# 26601 W . Agoura R d.

- 1150 -

IxChariot APIGuide
# C alabas as , C A 91302 U SA
# W eb: ht t p: / / w w w . ix iac om. c om
# Phone: 818-871-1800
# Fax : 818-871-1805
#
# General I nf ormat ion:
#
e-mail: inf o@ ix iac om. c om
#
# Tec hnic al Support :
#
e-mail: s upport @ ix iac om. c om
#
#
# EXAMPLE: I x ia Endpoint Pairs Tes t
# This s c ript c reat es and runs a t es t w it h ix ia endpoint pairs
# ov er I PSec t unnels bet w een ix ia port s , t hen s av es t he t es t t o a f ile.
#
# All at t ribut es of t his t es t are def ined by t his s c ript .
#
#***************************************************************
#***************************************************************
# D at a f or t es t :
# C hange t hes e v alues f or y our net w ork if des ired.
#***************************************************************
s et t es t File " C : / Program Files / I x ia/ I x C hariot / Tes t s / C hrSM_ I PSec _P2P_
Tes t . t s t "
s et pairC ount 1
s et prot oc ols " TC P"
s et s c ript s " c : / Program Files / I x ia/ I x C hariot / Sc ript s / R es pons e_Time. s c r"
s et t imeout 5
s et max W ait 180
s et logFile " pairs Tes t . log"
s et C H A S S I S 1_I P 192. 168. 6. 97
s et e1_m gm t " 192. 168. 6. 97; 1; 1"
s et e2_m gm t " 192. 168. 6. 97; 1; 2"
s et e1Mgmt " 192. 168. 6. 97 / 01 / 01"
s et e2Mgmt " 192. 168. 6. 97 / 01 / 02"
#***************************************************************
# Proc edure t o c onf igure ix ia port us ing Apt ix ia API
#***************************************************************
proc c onf igureI x iaPort s {my H os t my Port my Ses s ion e1_mgmt e2_mgmt } {
global C H ASSI S1_I P
# St art t es t Serv er and us e t he ins t anc e inv ok ed by ix c hariot
# -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -# This s ec t ion of c ode s et ' s
# t he " s erv er t rans ac t ion c ont ex t " `t c ' t o a part ic ular t es t s erv er
#
s et t c [ : : Apt ix iaC lient : : C ore: : Fac ilit y Get D ef ault Trans ac t ionC ont ex t ]
$t c I nit $my H os t $my Port
s e t : : m y S e s O b j [ : : A p t i x i a C l i e n t : : S e s s i o n % A U T O % -t r a n s a c t i o n c o n t e x t
$t c objec t id $my Ses s ion]
#
# Get ex is t ing t es t f rom our t es t s erv er s es s ion

- 1151 -

IxChariot APIGuide
#
s e t : : m y T e s t I d [ $ : : m y S e s O b j e d i t a b l e T e s t c g e t -o b j e c t i d ]
s et : : my Tes t [ : : Apt ix iaC lient : : Generic Tes t Model %AU TO% -t rans ac t ionc ont ex t $t c
-o b j e c t i d $ : : m y T e s t I d ]
#
# Add s ome c has s is ' s int o t he t es t model
# t he c has s is ' s are in t he s ubobjec t pat hw ay
#
# c h a s s i s C o n f i g -> c h a s s i s C h a i n
#
$: : my Tes t c has s is C onf ig c has s is C hain AddTail
s et c c Obj [ $: : my Tes t c has s is C onf ig c has s is C hain Get 0]
$c c Obj dns S et " $C H A S S I S 1_I P " ; # s et c has s i s nam e
$c c Obj c ableLengt h Set 3
$c c Obj phy s ic alC hain Set f als e
###
# Set up f irs t port group
s et port Spec " $e1_mgmt "
s e t p g _i d x [ e x p r [ $ : : m y T e s t p o r t G r o u p L i s t S i z e ] -2 ]
s et pgObj [ $: : my Tes t port GroupLis t Get $pg_idx ]
$pgObj name Set " C lient N et w ork "
$pgObj port Lis t AddTail $port Spec
# Set up Et hernet St ac k on " My f irs t port group" - pgObj
$pgObj _I ns t ant i at e s t ac k " E t hernet P l ugi n"
$pgObj s t ac k enabled Set t rue
$pgObj s t ac k mac Set " 00: 00: 00: 00: 01: 01"
# Set up Emulat ed R out er Plugin
$pgObj s t ac k c hildrenLis t AddTail -it emt y pe " Emulat edR out erPlugin"
s et erpObj [ $pgObj s t ac k c hildrenLis t Get 0]
$erpObj ipTy pe Set " I Pv 4"
$erpObj ipAddres s Set " 172. 16. 1. 1"
$erpObj inc rement By Set " 0. 0. 0. 1"
$erpObj gat ew ay Addres s Set " 172. 16. 1. 2"
$erpObj pref ix Set " 24"
# Set up I P Plugin
$ e r p O b j c h i l d r e n L i s t A d d T a i l -i t e m t y p e " I p V 4 V 6 P l u g i n "
s et ippObj [ $erpObj c hildrenLis t Get 0]
$ippObj rangeLis t AddTail
s et iprObj [ $ippObj rangeLis t Get 0]
$iprObj name Set " ip-9"
$iprObj enabled Set t rue
$iprObj ipTy pe Set I Pv 4
$iprObj ipAddres s Set 172. 17. 1. 1
$iprObj inc rement By Set 0. 0. 0. 1
$iprObj pref ix Set 24
$iprObj c ount Set 1
# Set up I PSec Plugin
$ippObj c hildrenLis t AddTail -it emt y pe " I PSec Plugin"
s et ips Obj [ $ippObj c hildrenLis t Get 0]
$ips Obj ips ec N et w ork AddTail
s et is nObj [ $ips Obj ips ec N et w ork Get 0]
$is nObj t es t Ty pe Set " p2p"

- 1152 -

IxChariot APIGuide

$is nObj role Set " I nit iat or"

$is nObj emulat edSubnet Set " 70. 0. 0. 0"
$is nObj emulat edSubnet Suf f ix Set " 24"
$is nObj prot ec t edSubnet Set " 80. 0. 0. 0"
$is nObj prot ec t edSubnet Suf f ix Set " 24"
$is nObj peerPublic I P Set " 172. 18. 1. 1"
s e t i p r O b j I d [ $ i p r O b j c g e t -o b j e c t i d ]
$is nObj _Bind egR ange $iprObj
$ips Obj ips ec Phas e1 ps k Set " ix v pn"
Add s ec ond c has s is t o t he lis t
$: : my Tes t c has s is C onf ig c has s is C hain AddTail
s et c c Obj [ $: : my Tes t c has s is C onf ig c has s is C hain Get 1]
$c c Obj dns S et " $C H A S S I S 1_I P " ; # s et c has s i s nam e
$c c Obj c ableLengt h Set 3
$c c Obj phy s ic alC hain Set f als e
###
Set up s ec ond port group
s et port Spec $e2_mgmt
s et pg_idx [ ex pr [ $: : my Tes t port GroupLis t Siz e] -1]
s et pgObj1 [ $: : my Tes t port GroupLis t Get $pg_idx ]
$pgObj1 name Set " Serv er N et w ork "
$pgObj1 port Lis t AddTail $port Spec
Set up Et hernet St ac k on " My s ec ond Port Group" - pgObj1
$pgObj1 _I ns t ant iat e s t ac k " Et hernet Plugin"
$pgObj1 s t ac k enabled Set t rue
$pgObj1 s t ac k mac Set " 00: 00: 00: 00: 02: 02"
Set up Emulat ed R out er Plugin
$ p g O b j s t a c k c h i l d r e n L i s t A d d T a i l -i t e m t y p e " E m u l a t e d R o u t e r P l u g i n "
s et erpObj [ $pgObj s t ac k c hildrenLis t Get 0]
$erpObj ipTy pe Set " I Pv 4"
$erpObj ipAddres s Set " 172. 16. 1. 2"
$erpObj inc rement By Set " 0. 0. 0. 1"
$erpObj gat ew ay Addres s Set " 172. 16. 1. 1"
$erpObj pref ix Set " 24"
Set up I P plugin
$ p g O b j 1 c h i l d r e n L i s t A d d T a i l -i t e m t y p e " I p V 4 V 6 P l u g i n "
s et ippObj [ $pgObj1 s t ac k c hildrenLis t Get 0]
$ippObj rangeLis t AddTail
s et iprObj [ $ippObj rangeLis t Get 0]
$iprObj name Set " ip-8"
$iprObj enabled Set t rue
$iprObj ipTy pe Set I Pv 4
$iprObj ipAddres s Set " 172. 18. 1. 1"
$iprObj inc rement By Set 0. 0. 0. 1
$iprObj pref ix Set 24
$iprObj c ount Set 1
Set up I PSec Plugin
$ippObj c hildrenLis t AddTail -it emt y pe " I PSec Plugin"
s et ips Obj [ $ippObj c hildrenLis t Get 0]
$ips Obj ips ec N et w ork AddTail
s et is nObj [ $ips Obj ips ec N et w ork Get 0]
$is nObj t es t Ty pe Set " p2p"
$is nObj role Set " R es ponder"

- 1153 -

IxChariot APIGuide
$is nObj emulat edSubnet Set " 80. 0. 0. 0"
$is nObj emulat edSubnet Suf f ix Set " 24"
$is nObj prot ec t edSubnet Set " 70. 0. 0. 0"
$is nObj prot ec t edSubnet Suf f ix Set " 24"
$is nObj peerPublic I P Set " 172. 17. 1. 1"
s e t i p r O b j I d [ $ i p r O b j c g e t -o b j e c t i d ]
$is nObj _Bind egR ange $iprObj
# prompt $int erac t iv e " hit ret urn t o Tes t C onf igure"
$: : my Tes t Tes t C onf igure ; # applied c onf ig on port s
# All enums f or objec t s are pre-def ined w it hin t he objec t c las s as
# r e a d -o n l y c l a s s v a r i a b l e s , l i k e
# `k D eep' `k Shallow ' et c . . .
s et x m l 1 [ l i ndex [ $: : m y T es t _Get X m l \
$: : Apt ix iaC lient : : XProt oc olObjec t : : eSerializ at ionD ept h: : k D eep \
t rue] 0]
put s s t dout $x ml1
ret urn $x ml1
}
#***************************************************************
# Proc edure t o log errors if t here is ex t ended inf o
#***************************************************************
proc pLogError {handle c ode w here} {
global logFile
# D ef ine s y mbols f or t he errors w e' re int eres t ed in.
s et C H R _OPER ATI ON _FAI LED " C H R API 108"
s et C H R _OB J E C T _I N V A LI D " C H R A P I 112"
# Somet hing f ailed: s how w hat happened.
put s " $w here f ailed: [ c hrApi get R et urnMs g $c ode] "
# See if t here is ex t ended error inf ormat ion av ailable.
# I t ' s is only meaningf ul f or c ert ain errors .
if {$c ode = = $C H R _OPER ATI ON _FAI LED
|| $c ode = = $C H R _ OB J E C T _I N V A LI D } {
# Try t o get t he ex t ended error inf ormat ion
s et rc [ c at c h {s et inf o [ c hrC ommonError get I nf o \
$handle " ALL" ] }]
if {$rc ! = 0} {
# W e c an ignore all non-s uc c es s ret urn c odes here
# bec aus e mos t s hould not oc c ur (t he api' s been
# init ializ ed and t he det ail lev el is ok ay ),
# and t he N O_S U C H _ V A LU E ret urn c ode here m eans
# t here is no inf o av ailable.
s et inf o " < N one> "
}
s et logFile [ open $logFile a+ ]
s et t imes t amp [ c loc k f ormat [ c loc k s ec onds ] ]
put s $logFile " $t imes t amp $w here f ailed"
put s $logFile " $t imes t amp $inf o"
# Flus h f orc es immediat e w rit e t o f ile
f lus h $logFile
}
}
#***************************************************************
#

- 1154 -

IxChariot APIGuide
# Sc ript main
#
# c at c h is us ed w hen t here c ould be ex t ended error inf ormat ion,
# s o w e c an log w hat happened.
#***************************************************************
# Load t he C hariot API .
#
# N OTE: I f y ou are us ing Tc l Vers ion 8. 0. p5 or older
# t hen y ou w ill need t o modif y t he f ollow ing lines t o load and
# us e C hariot ins t ead of C hariot Ex t . For ex ample:
# load C hariot
# pac k age require C hariot
l append : : aut o_pat h " c : / P rogram \ F i l es / i x i a/ i x c hari ot / apt i x i a/ l i b/ c om m on/
t c lc lient "
load C hariot Ex t
pac k age require C hariot Ex t
pac k age require Apt ix iaC lient 2. 0
# C reat e a new t es t .
put s " C reat e t he t es t . . . "
s et t es t [ c hrTes t new ]
# N ow get t he c urrent ref erenc e t o t he t es t s erv er
put s " Get t ing t he t es t s erv er ref erenc e"
if {[ c at c h {c hrTes t get Tes t Serv erSes s ion $t es t my H os t my Port my Ses s ion}] } {
pLogError $t es t $errorC ode " c hrTes t get Tes t Serv erSes s ion $t es t my H os t
my Port
my Ses s ion"
c hrTes t delet e $t es t
ret urn
}
# Set t he t es t f ilename f or s av ing lat er.
put s " Set t es t f ilename. . . "
if {[ c at c h {c hrTes t s et $t es t FI LEN AME $t es t File}] } {
pLogError $t es t $errorC ode " c hrTes t s et FI LEN AME"
c hrTes t delet e $t es t
ret urn
}
put s " C onf igure ix ia endpoint s us ing Apt I x ia. . . "
s et my C onf ig [ c onf igureI x iaPort s $my H os t $my Port $my Ses s ion $e1_
mgmt $e2_mgmt ]
put s " I mport ing t he ix ia c onf igurat ion. . . "
i f {[ c at c h {c hrT es t s et $t es t I X I A _N E T W OR K _ C ON F I GU R A T I ON $m y C onf ig}] } {
pLogE rror $t es t $errorC ode " c hrT es t s et $t es t I X I A _N E T W OR K _
C ON FI GU R ATI ON "
c hrTes t delet e $t es t
ret urn
}
# D ef ine s ome pairs f or t he t es t .
f or {s et index 0} {$index < $pairC ount } {inc r index } {
# C reat e a pair.
put s " C reat e a pair. . . "
s et pair [ c hrPair new ]

- 1155 -

IxChariot APIGuide
# Set pair at t ribut es f rom our lis t s .
put s " Set pair at t t ribut es . . . "
c hrPair s et $pair C OMMEN T " Pair [ ex pr $index + 1] "
c hrP ai r s et $pai r E 1_A D D R " C l i ent N et w ork "
c hrP ai r s et $pai r E 2_A D D R " S erv er N et w ork "
c hrPair s et $pair U SE_C ON SOLE_E1 True
c hrP ai r s et $pai r U S E _ S E T U P _ E 1_E 2 T rue
c hrP ai r s et $pai r C ON S OLE _ E 1_A D D R " U s e I x i a N et w ork C onf i gurat i on"
c hrP ai r s et $pai r S E T U P _ E 1_E 2_ A D D R " U s e I x i a N et w ork C onf igurat ion"
c hrPair s et $pair PR OTOC OL $prot oc ols
# D ef ine a s c ript f or us e by t his pair.
# W e need t o c hec k f or errors w it h ex t ended inf o here.
s et s c ript $s c ript s
if {[ c at c h {c hrPair us eSc ript $pair $s c ript }] } {
pLogError $pair $errorC ode " c hrPair us eSc ript "
c hrTes t delet e $t es t
ret urn
}
# Add t he pair t o t he t es t .
put s " Add t he pair t o t he t es t . . . "
if {[ c at c h {c hrTes t addPair $t es t $pair}] } {
pLogError $t es t $errorC ode " c hrTes t addPair"
c hrTes t delet e $t es t
ret urn
}
}
# The t es t is c omplet e, s o now w e c an run it .
put s " R un t he t es t . . . "
if {[ c at c h {c hrTes t s t art $t es t }] } {
pLogError $t es t $errorC ode " c hrTes t s t art "
c hrTes t delet e $t es t
ret urn
}
# W ait f or t he t es t t o s t op.
# W e' ll c hec k in a loop here ev ery 5 s ec onds
# t hen c all it an error af t er t w o minut es if
# t he t es t is s t ill not s t opped.
s et t imer 0
s et is St opped 0
put s " W ait ing f or t he t es t t o s t op. . . "
w hile {! $is St opped && $t imer < $max W ait } {
s et is St opped [ c hrTes t is St opped $t es t $t imeout ]
if {! $is St opped} {
s et t imer [ ex pr $t imer + $t imeout ]
put s " W ait ing f or t es t t o s t op. . . ($t imer)"
}
}
if {! $is St opped} {
# Show t his as a t imed out error
s et rc " C H R API 118"
pLogError $t es t $rc " c hrTes t is St opped"
c hrTes t delet e $t es t

- 1156 -

IxChariot APIGuide
ret urn
}
# Sav e t he t es t s o w e c an s how res ult s lat er.
put s " Sav e t he t es t . . . "
if {[ c at c h {c hrTes t s av e $t es t }] } {
pLogError $t es t $errorC ode " c hrTes t s av e"
ret urn
}
c hrTes t delet e $t es t
# W e' re f inis hed!
ret urn

GUI Representation
If you load the XML file generated from the Tcl API script into the Stack Manager GUI, it
should appear as shown in the following figure.

- 1157 -

IxChariot APIGuide

Sample IPSec Script (port-to-DUT)

This section presents a sample Tcl script for creating an end-to-end tunnel for two endpoint
nodes, each of which connects to a common DUT (a router, for example).

Test Topology
This script requires:
l

An Ixia chassis with an Ethernet port connected to an Ethernet interface on the DUT.

The DUT with two Ethernet ports, each connected to one of the Ixia ports.

A second Ixia chassis with an Ethernet port connected to an Ethernet interface on the
DUT.

Plugin Layout
This script implements an IPSec tunnel between ports on two Ixia chassis, each of which
are connected to a DUT. The following diagram represents the plugins, together with the IP
addresses for each of the two ports at each end of the tunnel:

IPSec Port-to-DUT Tcl Script Listing

Following is the sample Tcl script for creating an end-to-end tunnel for two endpoint nodes,
each of which is connected to a common DUT. The script file name is ChrSM_IPSec_P2D_
Test.tcl.
#***************************************************************
#
# I x C hariot API SD K
File: C hrSM_I PSec _P2D _Tes t . t c l
#
# This module c ont ains c ode made av ailable by I x ia on an AS I S
# bas is . Any one rec eiv ing t he module is c ons idered t o be
# lic ens ed under I x ia c opy right s t o us e t he I x ia-prov ided
# s ourc e c ode in any w ay he or s he deems f it , inc luding c opy ing
# it , c ompiling it , modif y ing it , and redis t ribut ing it , w it h
# or w it hout modif ic at ions . N o lic ens e under any I x ia pat ent s
# or pat ent applic at ions is t o be implied f rom t his c opy right
# lic ens e.
#
# A us er of t he module s hould unders t and t hat I x ia c annot
# prov ide t ec hnic al s upport f or t he module and w ill not be
# res pons ible f or any c ons equenc es of us e of t he program.

- 1158 -

IxChariot APIGuide
#
# Any not ic es , inc luding t his one, are not t o be remov ed f rom
# t he module w it hout t he prior w rit t en c ons ent of I x ia.
#
# For more inf ormat ion, c ont ac t :
#
# Ixia
# 26601 W . Agoura R d.
# C alabas as , C A 91302 U SA
# W eb: ht t p: / / w w w . ix iac om. c om
# Phone: 818-871-1800
# Fax : 818-871-1805
#
# General I nf ormat ion:
#
e-mail: inf o@ ix iac om. c om
#
# Tec hnic al Support :
#
e-mail: s upport @ ix iac om. c om
#
#
# EXAMPLE: I x ia Endpoint Pairs Tes t
# This s c ript c reat es and runs a t es t w it h ix ia endpoint pairs
# ov er I PSec t unnels bet w een ix ia port and D U T, t hen s av es t he
# t es t t o a f ile. The D U T needs t o be c onf igured c orrec t ly
# f or t he s c ript t o w ork .
#
# All at t ribut es of t his t es t are def ined by t his s c ript .
#
#***************************************************************
#***************************************************************
# D at a f or t es t :
# C hange t hes e v alues f or y our net w ork if des ired.
#***************************************************************
s et t es t File " C : / Program Files / I x ia/ I x C hariot / Tes t s / C hrSM_ I PSec _P2D _
Tes t . t s t "
s et pairC ount 1
s et prot oc ols " TC P"
s et s c ript s " c : / Program Files / I x ia/ I x C hariot / Sc ript s / R es pons e_Time. s c r"
s et t imeout 5
s et max W ait 180
s et logFile " pairs Tes t . log"
s et C H A S S I S 1_I P 192. 168. 4. 170
s et e1_m gm t " 192. 168. 4. 170; 1; 3"
s et e2_m gm t " 192. 168. 4. 170; 1; 4"
s et e1Mgmt " 192. 168. 4. 170 / 01 / 03"
s et e2Mgmt " 192. 168. 4. 170 / 01 / 04"
#***************************************************************
# Proc edure t o c onf igure ix ia port us ing Apt ix ia API
#***************************************************************
proc c onf igureI x iaPort s {my H os t my Port my Ses s ion e1_mgmt e2_mgmt } {
global C H ASSI S1_I P
# St art t es t Serv er and us e t he ins t anc e inv ok ed by ix c hariot
# -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --

- 1159 -

IxChariot APIGuide
# This s ec t ion of c ode s et ' s
# t he " s erv er t rans ac t ion c ont ex t " `t c ' t o a part ic ular t es t s erv er
#
s et t c [ : : Apt ix iaC lient : : C ore: : Fac ilit y Get D ef ault Trans ac t ionC ont ex t ]
$t c I nit $my H os t $my Port
s e t : : m y S e s O b j [ : : A p t i x i a C l i e n t : : S e s s i o n % A U T O % -t r a n s a c t i o n c o n t e x t
$t c objec t id $my Ses s ion]
#
# Get ex is t ing t es t f rom our t es t s erv er s es s ion
#
s e t : : m y T e s t I d [ $ : : m y S e s O b j e d i t a b l e T e s t c g e t -o b j e c t i d ]
s et : : my Tes t [ : : Apt ix iaC lient : : Generic Tes t Model %AU TO% -t rans ac t ionc ont ex t $t c
-o b j e c t i d $ : : m y T e s t I d ]
#
# Add s ome c has s is ' s int o t he t es t model
# t he c has s is ' s are in t he s ubobjec t pat hw ay
#
# c h a s s i s C o n f i g -> c h a s s i s C h a i n
#
$: : my Tes t c has s is C onf ig c has s is C hain AddTail
s et c c Obj [ $: : my Tes t c has s is C onf ig c has s is C hain Get 0]
$c c Obj dns S et " $C H A S S I S 1_I P " ; # s et c has s i s nam e
$c c Obj c ableLengt h Set 3
$c c Obj phy s ic alC hain Set f als e
###
# Set up f irs t port group
s et port Spec " $e1_mgmt "
s e t p g _i d x [ e x p r [ $ : : m y T e s t p o r t G r o u p L i s t S i z e ] -2 ]
s et pgObj [ $: : my Tes t port GroupLis t Get $pg_idx ]
$pgObj name Set " C lient N et w ork "
$pgObj port Lis t AddTail $port Spec
# Set up Et hernet St ac k on " My f irs t port group" - pgObj
$pgObj _I ns t ant i at e s t ac k " E t hernet P l ugi n"
$pgObj s t ac k enabled Set t rue
$pgObj s t ac k mac Set " 00: 00: 00: 00: 01: 01"
# Set up Emulat ed R out er Plugin
$pgObj s t ac k c hildrenLis t AddTail -it emt y pe " Emulat edR out erPlugin"
s et erpObj [ $pgObj s t ac k c hildrenLis t Get 0]
$erpObj ipTy pe Set " I Pv 4"
$erpObj ipAddres s Set " 172. 21. 254. 10"
$erpObj inc rement By Set " 0. 0. 0. 1"
$erpObj gat ew ay Addres s Set " 172. 21. 254. 1"
$erpObj pref ix Set " 16"
# Set up I P Plugin
$ e r p O b j c h i l d r e n L i s t A d d T a i l -i t e m t y p e " I p V 4 V 6 P l u g i n "
s et ippObj [ $erpObj c hildrenLis t Get 0]
$ippObj rangeLis t AddTail
s et iprObj [ $ippObj rangeLis t Get 0]
$iprObj name Set " ip-9"
$iprObj enabled Set t rue
$iprObj ipTy pe Set I Pv 4

- 1160 -

IxChariot APIGuide

$iprObj ipAddres s Set 172. 21. 254. 3

$iprObj inc rement By Set 0. 0. 0. 1
$iprObj pref ix Set 16
$iprObj c ount Set 1
Set up I PSec Plugin
$ippObj c hildrenLis t AddTail -it emt y pe " I PSec Plugin"
s et ips Obj [ $ippObj c hildrenLis t Get 0]
$ips Obj ips ec N et w ork AddTail
s et is nObj [ $ips Obj ips ec N et w ork Get 0]
$is nObj t es t Ty pe Set " p2d"
$is nObj role Set " I nit iat or"
$is nObj emulat edSubnet Set " 70. 0. 0. 0"
$is nObj emulat edSubnet Suf f ix Set " 24"
$is nObj prot ec t edSubnet Set " 80. 0. 0. 0"
$is nObj prot ec t edSubnet Suf f ix Set " 24"
$is nObj peerPublic I P Set " 172. 21. 254. 1"
s e t i p r O b j I d [ $ i p r O b j c g e t -o b j e c t i d ]
$is nObj _Bind egR ange $iprObj
$ips Obj ips ec Phas e1 ps k Set " ix v pn"
Add s ec ond c has s is t o t he lis t
$: : my Tes t c has s is C onf ig c has s is C hain AddTail
s et c c Obj [ $: : my Tes t c has s is C onf ig c has s is C hain Get 1]
$c c Obj dns S et " $C H A S S I S 1_I P " ; # s et c has s i s nam e
$c c Obj c ableLengt h Set 3
$c c Obj phy s ic alC hain Set f als e
###
Set up s ec ond port group
s et port Spec $e2_mgmt
s et pg_idx [ ex pr [ $: : my Tes t port GroupLis t Siz e] -1]
s et pgObj1 [ $: : my Tes t port GroupLis t Get $pg_idx ]
$pgObj1 name Set " Serv er N et w ork "
$pgObj1 port Lis t AddTail $port Spec
Set up Et hernet St ac k on " My s ec ond Port Group" - pgObj1
$pgObj1 _I ns t ant iat e s t ac k " Et hernet Plugin"
$pgObj1 s t ac k enabled Set t rue
$pgObj1 s t ac k mac Set " 00: 00: 00: 00: 02: 02"
Set up Emulat ed R out er Plugin
$pgObj1 s t ac k c hildrenLis t AddTail -it emt y pe " Emulat edR out erPlugin"
s et erpObj [ $pgObj1 s t ac k c hildrenLis t Get 0]
$erpObj ipTy pe Set " I Pv 4"
$erpObj ipAddres s Set " 172. 22. 254. 10"
$erpObj inc rement By Set " 0. 0. 0. 1"
$erpObj gat ew ay Addres s Set " 172. 22. 254. 1"
$erpObj pref ix Set " 16"
Set up I P plugin
$ e r p O b j c h i l d r e n L i s t A d d T a i l -i t e m t y p e " I p V 4 V 6 P l u g i n "
s et ippObj [ $erpObj c hildrenLis t Get 0]
$ippObj rangeLis t AddTail
s et iprObj [ $ippObj rangeLis t Get 0]
$iprObj name Set " ip-8"
$iprObj enabled Set t rue
$iprObj ipTy pe Set I Pv 4
$iprObj ipAddres s Set " 80. 0. 0. 1"

- 1161 -

IxChariot APIGuide
$iprObj inc rement By Set 0. 0. 0. 1
$iprObj pref ix Set 16
$iprObj c ount Set 1
# prompt $int erac t iv e " hit ret urn t o Tes t C onf igure"
$: : my Tes t Tes t C onf igure ; # applied c onf ig on port s
# All enums f or objec t s are pre-def ined w it hin t he objec t c las s as
# r e a d -o n l y c l a s s v a r i a b l e s , l i k e
# `k D eep' `k Shallow ' et c . . .
s et x m l 1 [ l i ndex [ $: : m y T es t _Get X m l \
$: : Apt ix iaC lient : : XProt oc olObjec t : : eSerializ at ionD ept h: : k D eep \
t rue] 0]
put s s t dout $x ml1
ret urn $x ml1
}
#***************************************************************
# Proc edure t o log errors if t here is ex t ended inf o
#***************************************************************
proc pLogError {handle c ode w here} {
global logFile
# D ef ine s y mbols f or t he errors w e' re int eres t ed in.
s et C H R _OPER ATI ON _FAI LED " C H R API 108"
s et C H R _OB J E C T _I N V A LI D " C H R A P I 112"
# Somet hing f ailed: s how w hat happened.
put s " $w here f ailed: [ c hrApi get R et urnMs g $c ode] "
# See if t here is ex t ended error inf ormat ion av ailable.
# I t ' s is only meaningf ul f or c ert ain errors .
if {$c ode = = $C H R _OPER ATI ON _FAI LED
|| $c ode = = $C H R _ OB J E C T _I N V A LI D } {
# Try t o get t he ex t ended error inf ormat ion
s et rc [ c at c h {s et inf o [ c hrC ommonError get I nf o \
$handle " ALL" ] }]
if {$rc ! = 0} {
# W e c an ignore all non-s uc c es s ret urn c odes here
# bec aus e mos t s hould not oc c ur (t he api' s been
# init ializ ed and t he det ail lev el is ok ay ),
# and t he N O_S U C H _ V A LU E ret urn c ode here m eans
# t here is no inf o av ailable.
s et inf o " < N one> "
}
s et logFile [ open $logFile a+ ]
s et t imes t amp [ c loc k f ormat [ c loc k s ec onds ] ]
put s $logFile " $t imes t amp $w here f ailed"
put s $logFile " $t imes t amp $inf o"
# Flus h f orc es immediat e w rit e t o f ile
f lus h $logFile
}
}
#***************************************************************
#
# Sc ript main
#
# c at c h is us ed w hen t here c ould be ex t ended error inf ormat ion,
# s o w e c an log w hat happened.

- 1162 -

IxChariot APIGuide
#***************************************************************
# Load t he C hariot API .
#
# N OTE: I f y ou are us ing Tc l Vers ion 8. 0. p5 or older
# t hen y ou w ill need t o modif y t he f ollow ing lines t o load and
# us e C hariot ins t ead of C hariot Ex t . For ex ample:
# load C hariot
# pac k age require C hariot
l append : : aut o_pat h " c : / P rogram \ F i l es / i x i a/ i x c hari ot / apt i x i a/ l i b/ c om m on/
t c lc lient "
load C hariot Ex t
pac k age require C hariot Ex t
pac k age require Apt ix iaC lient 2. 0
# C reat e a new t es t .
put s " C reat e t he t es t . . . "
s et t es t [ c hrTes t new ]
# N ow get t he c urrent ref erenc e t o t he t es t s erv er
put s " Get t ing t he t es t s erv er ref erenc e"
if {[ c at c h {c hrTes t get Tes t Serv erSes s ion $t es t my H os t my Port my Ses s ion}] } {
pLogError $t es t $errorC ode " c hrTes t get Tes t Serv erSes s ion $t es t my H os t
my Port
my Ses s ion"
c hrTes t delet e $t es t
ret urn
}
# Set t he t es t f ilename f or s av ing lat er.
put s " Set t es t f ilename. . . "
if {[ c at c h {c hrTes t s et $t es t FI LEN AME $t es t File}] } {
pLogError $t es t $errorC ode " c hrTes t s et FI LEN AME"
c hrTes t delet e $t es t
ret urn
}
put s " C onf igure ix ia endpoint s us ing Apt I x ia. . . "
s et my C onf ig [ c onf igureI x iaPort s $my H os t $my Port $my Ses s ion $e1_
mgmt $e2_mgmt ]
put s " I mport ing t he ix ia c onf igurat ion. . . "
i f {[ c at c h {c hrT es t s et $t es t I X I A _N E T W OR K _ C ON F I GU R A T I ON $m y C onf ig}] } {
pLogE rror $t es t $errorC ode " c hrT es t s et $t es t I X I A _N E T W OR K _
C ON FI GU R ATI ON "
c hrTes t delet e $t es t
ret urn
}
# D ef ine s ome pairs f or t he t es t .
f or {s et index 0} {$index < $pairC ount } {inc r index } {
# C reat e a pair.
put s " C reat e a pair. . . "
s et pair [ c hrPair new ]
# Set pair at t ribut es f rom our lis t s .
put s " Set pair at t t ribut es . . . "
c hrPair s et $pair C OMMEN T " Pair [ ex pr $index + 1] "
c hrP ai r s et $pai r E 1_A D D R " C l i ent N et w ork "

- 1163 -

IxChariot APIGuide
c hrP ai r s et $pai r E 2_A D D R " S erv er N et w ork "
c hrPair s et $pair U SE_C ON SOLE_E1 True
c hrP ai r s et $pai r U S E _ S E T U P _ E 1_E 2 T rue
c hrP ai r s et $pai r C ON S OLE _ E 1_A D D R " U s e I x i a N et w ork C onf i gurat i on"
c hrP ai r s et $pai r S E T U P _ E 1_E 2_ A D D R " U s e I x i a N et w ork C onf igurat ion"
c hrPair s et $pair PR OTOC OL $prot oc ols
# D ef ine a s c ript f or us e by t his pair.
# W e need t o c hec k f or errors w it h ex t ended inf o here.
s et s c ript $s c ript s
if {[ c at c h {c hrPair us eSc ript $pair $s c ript }] } {
pLogError $pair $errorC ode " c hrPair us eSc ript "
c hrTes t delet e $t es t
ret urn
}
# Add t he pair t o t he t es t .
put s " Add t he pair t o t he t es t . . . "
if {[ c at c h {c hrTes t addPair $t es t $pair}] } {
pLogError $t es t $errorC ode " c hrTes t addPair"
c hrTes t delet e $t es t
ret urn
}
}
# The t es t is c omplet e, s o now w e c an run it .
put s " R un t he t es t . . . "
if {[ c at c h {c hrTes t s t art $t es t }] } {
pLogError $t es t $errorC ode " c hrTes t s t art "
c hrTes t delet e $t es t
ret urn
}
# W ait f or t he t es t t o s t op.
# W e' ll c hec k in a loop here ev ery 5 s ec onds
# t hen c all it an error af t er t w o minut es if
# t he t es t is s t ill not s t opped.
s et t imer 0
s et is St opped 0
put s " W ait ing f or t he t es t t o s t op. . . "
w hile {! $is St opped && $t imer < $max W ait } {
s et is St opped [ c hrTes t is St opped $t es t $t imeout ]
if {! $is St opped} {
s et t imer [ ex pr $t imer + $t imeout ]
put s " W ait ing f or t es t t o s t op. . . ($t imer)"
}
}
if {! $is St opped} {
# Show t his as a t imed out error
s et rc " C H R API 118"
pLogError $t es t $rc " c hrTes t is St opped"
c hrTes t delet e $t es t
ret urn
}
# Sav e t he t es t s o w e c an s how res ult s lat er.
put s " Sav e t he t es t . . . "

- 1164 -

IxChariot APIGuide
if {[ c at c h {c hrTes t s av e $t es t }] } {
pLogError $t es t $errorC ode " c hrTes t s av e"
ret urn
}
c hrTes t delet e $t es t
# W e' re f inis hed!
ret urn

- 1165 -

IxChariot APIGuide

Sample PPP Script (port-to-port)

This section presents a sample Tcl script for configuring a basic PPPoE session between
two ports.

Test Topology
This script requires an Ixia chassis with two Ethernet ports connected back-to-back.

Plugin Layout
This script implements aa basic PPPoE session between two ports:

PPP Port-to-Port Tcl Script Listing

Following is the sample Tcl script for configuring a basic PPPoE session between two ports.
The script file name is ChrSM_PPP_P2P_Test.tcl.
#***************************************************************
#
# I x C hariot API SD K
File: C hrSM_PPP_P2P_Tes t . t c l
#
# This module c ont ains c ode made av ailable by I x ia on an AS I S
# bas is . Any one rec eiv ing t he module is c ons idered t o be
# lic ens ed under I x ia c opy right s t o us e t he I x ia-prov ided
# s ourc e c ode in any w ay he or s he deems f it , inc luding c opy ing
# it , c ompiling it , modif y ing it , and redis t ribut ing it , w it h
# or w it hout modif ic at ions . N o lic ens e under any I x ia pat ent s
# or pat ent applic at ions is t o be implied f rom t his c opy right
# lic ens e.
#
# A us er of t he module s hould unders t and t hat I x ia c annot
# prov ide t ec hnic al s upport f or t he module and w ill not be
# res pons ible f or any c ons equenc es of us e of t he program.
#
# Any not ic es , inc luding t his one, are not t o be remov ed f rom
# t he module w it hout t he prior w rit t en c ons ent of I x ia.
#
# For more inf ormat ion, c ont ac t :
#
# Ixia
# 26601 W . Agoura R d.
# C alabas as , C A 91302 U SA
# W eb: ht t p: / / w w w . ix iac om. c om
# Phone: 818-871-1800
# Fax : 818-871-1805
#
# General I nf ormat ion:
#
e-mail: inf o@ ix iac om. c om

- 1166 -

IxChariot APIGuide
#
# Tec hnic al Support :
#
e-mail: s upport @ ix iac om. c om
#
#
# EXAMPLE: I x ia Endpoint Pairs Tes t
# This s c ript c reat es and runs a t es t w it h ix ia endpoint pairs
# us ing PPP Plugin f or port t o port , t hen s av es t he t es t t o a f ile.
#
# All at t ribut es of t his t es t are def ined by t his s c ript .
#
#***************************************************************
#***************************************************************
# D at a f or t es t :
# C hange t hes e v alues f or y our net w ork if des ired.
#***************************************************************
s et t es t File " C : / Program Files / I x ia/ I x C hariot / Tes t s / C hrSM_ PPP_P2P_
Tes t . t s t "
s et pairC ount 1
s et prot oc ols " TC P"
s et s c ript s " c : / Program Files / I x ia/ I x C hariot / Sc ript s / R es pons e_Time. s c r"
s et t imeout 5
s et max W ait 180
s et logFile " pairs Tes t . log"
s et C H A S S I S 1_I P 192. 168. 6. 97
s et e1_m gm t " 192. 168. 6. 97; 1; 1"
s et e2_m gm t " 192. 168. 6. 97; 1; 2"
s et e1Mgmt " 192. 168. 6. 97 / 01 / 01"
s et e2Mgmt " 192. 168. 6. 97 / 01 / 02"
#***************************************************************
# Proc edure t o c onf igure ix ia port us ing Apt ix ia API
#***************************************************************
proc c onf igureI x iaPort s {my H os t my Port my Ses s ion e1_mgmt e2_mgmt } {
global C H ASSI S1_I P
# St art t es t Serv er and us e t he ins t anc e inv ok ed by ix c hariot
# -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -# This s ec t ion of c ode s et ' s
# t he " s erv er t rans ac t ion c ont ex t " `t c ' t o a part ic ular t es t s erv er
#
s et t c [ : : Apt ix iaC lient : : C ore: : Fac ilit y Get D ef ault Trans ac t ionC ont ex t ]
$t c I nit $my H os t $my Port
s e t : : m y S e s O b j [ : : A p t i x i a C l i e n t : : S e s s i o n % A U T O % -t r a n s a c t i o n c o n t e x t
$t c objec t id $my Ses s ion]
#
# Get ex is t ing t es t f rom our t es t s erv er s es s ion
#
s e t : : m y T e s t I d [ $ : : m y S e s O b j e d i t a b l e T e s t c g e t -o b j e c t i d ]
s et : : my Tes t [ : : Apt ix iaC lient : : Generic Tes t Model %AU TO% -t rans ac t ionc ont ex t $t c
-o b j e c t i d $ : : m y T e s t I d ]
#
# Add s ome c has s is ' s int o t he t es t model

- 1167 -

IxChariot APIGuide

# t he c has s is ' s are in t he s ubobjec t pat hw ay

#
# c h a s s i s C o n f i g -> c h a s s i s C h a i n
#
$: : my Tes t c has s is C onf ig c has s is C hain AddTail
s et c c Obj [ $: : my Tes t c has s is C onf ig c has s is C hain Get 0]
$c c Obj dns S et " $C H A S S I S 1_I P " ; # s et c has s i s nam e
$c c Obj c ableLengt h Set 3
$c c Obj phy s ic alC hain Set f als e
###
Set up f irs t port group
s et port Spec " $e1_mgmt "
s e t p g _i d x [ e x p r [ $ : : m y T e s t p o r t G r o u p L i s t S i z e ] -2 ]
s et pgC lient Obj [ $: : my Tes t port GroupLis t Get $pg_idx ]
$pgC lient Obj name Set " My Firs t Port Group"
$pgC lient Obj port Lis t AddTail $port Spec
Set up Et hernet St ac k on " My f irs t port group" - pgObj
$pgC l i ent Obj _I ns t ant i at e s t ac k " E t hernet P l ugi n"
$pgC lient Obj s t ac k enabled Set t rue
$pgC lient Obj s t ac k mac Set " 00: 00: 00: 00: 01: 01"
# Add PPP Plugin
$ p g C l i e n t O b j s t a c k c h i l d r e n L i s t A d d T a i l -i t e m t y p e " P p p o x P l u g i n "
s et pppox C lient Obj [ $pgC lient Obj s t ac k c hildrenLis t Get 0]
$pppox C l i ent Obj c om m ent S et " m y _pppox _ c l i ent _pl ugi n"
$pppox C lient Obj enabled Set " t rue"
$pppox C lient Obj role Set " c lient "
$pppox C lient Obj s et upR at e Set " 150"
$pppox C lient Obj enableThrot t ling Set " t rue"
$pppox C lient Obj max Out s t andingSes s ions Set " 50"
$pppox C lient Obj t eardow nR at e Set " 250"
$pppox C lient Obj numSes s ions Set " 100"
Add s ec ond c has s is t o t he lis t
$: : my Tes t c has s is C onf ig c has s is C hain AddTail
s et c c Obj [ $: : my Tes t c has s is C onf ig c has s is C hain Get 1]
$c c Obj dns S et " $C H A S S I S 1_I P " ; # s et c has s i s nam e
$c c Obj c ableLengt h Set 3
$c c Obj phy s ic alC hain Set f als e
###
Set up s ec ond port group
s et port Spec $e2_mgmt
s et pg_idx [ ex pr [ $: : my Tes t port GroupLis t Siz e] -1]
s et pgServ erObj [ $: : my Tes t port GroupLis t Get $pg_idx ]
$pgServ erObj name Set " My Sec ond Port Group"
$pgServ erObj port Lis t AddTail $port Spec
Set up Et hernet St ac k on " My s ec ond Port Group" - pgObj1
$pgS erv erObj _I ns t ant i at e s t ac k " E t hernet P l ugi n"
$pgServ erObj s t ac k enabled Set t rue
$pgServ erObj s t ac k mac Set " 00: 00: 00: 00: 02: 02"
Set up I P plugin on " My s ec ond Port Group" - pgObj1
$ p g S e r v e r O b j s t a c k c h i l d r e n L i s t A d d T a i l -i t e m t y p e " P p p o x P l u g i n "
s et pppox Serv erObj [ $pgServ erObj s t ac k c hildrenLis t Get 0]
$pppox S erv erObj c om m ent S et " m y _pppox _s erv er_pl ugi n"
$pppox Serv erObj enabled Set " t rue"

- 1168 -

IxChariot APIGuide
$pppox Serv erObj role Set " s erv er"
$pppox Serv erObj s et upR at e Set " 150"
$pppox Serv erObj enableThrot t ling Set " t rue"
$pppox Serv erObj max Out s t andingSes s ions Set " 50"
$pppox Serv erObj t eardow nR at e Set " 250"
$pppox Serv erObj numSes s ions Set " 100"
# prompt $int erac t iv e " hit ret urn t o Tes t C onf igure"
$: : my Tes t Tes t C onf igure ; # applied c onf ig on port s
# All enums f or objec t s are pre-def ined w it hin t he objec t c las s as
# r e a d -o n l y c l a s s v a r i a b l e s , l i k e
# `k D eep' `k Shallow ' et c . . .
s et x m l 1 [ l i ndex [ $: : m y T es t _Get X m l \
$: : Apt ix iaC lient : : XProt oc olObjec t : : eSerializ at ionD ept h: : k D eep \
t rue] 0]
put s s t dout $x ml1
ret urn $x ml1
}
#***************************************************************
# Proc edure t o log errors if t here is ex t ended inf o
#***************************************************************
proc pLogError {handle c ode w here} {
global logFile
# D ef ine s y mbols f or t he errors w e' re int eres t ed in.
s et C H R _OPER ATI ON _FAI LED " C H R API 108"
s et C H R _OB J E C T _I N V A LI D " C H R A P I 112"
# Somet hing f ailed: s how w hat happened.
put s " $w here f ailed: [ c hrApi get R et urnMs g $c ode] "
# See if t here is ex t ended error inf ormat ion av ailable.
# I t ' s is only meaningf ul f or c ert ain errors .
if {$c ode = = $C H R _OPER ATI ON _FAI LED
|| $c ode = = $C H R _ OB J E C T _I N V A LI D } {
# Try t o get t he ex t ended error inf ormat ion
s et rc [ c at c h {s et inf o [ c hrC ommonError get I nf o \
$handle " ALL" ] }]
if {$rc ! = 0} {
# W e c an ignore all non-s uc c es s ret urn c odes here
# bec aus e mos t s hould not oc c ur (t he api' s been
# init ializ ed and t he det ail lev el is ok ay ),
# and t he N O_S U C H _ V A LU E ret urn c ode here m eans
# t here is no inf o av ailable.
s et inf o " < N one> "
}
s et logFile [ open $logFile a+ ]
s et t imes t amp [ c loc k f ormat [ c loc k s ec onds ] ]
put s $logFile " $t imes t amp $w here f ailed"
put s $logFile " $t imes t amp $inf o"
# Flus h f orc es immediat e w rit e t o f ile
f lus h $logFile
}
}
#***************************************************************
#
# Sc ript main

- 1169 -

IxChariot APIGuide
#
# c at c h is us ed w hen t here c ould be ex t ended error inf ormat ion,
# s o w e c an log w hat happened.
#***************************************************************
# Load t he C hariot API .
#
# N OTE: I f y ou are us ing Tc l Vers ion 8. 0. p5 or older
# t hen y ou w ill need t o modif y t he f ollow ing lines t o load and
# us e C hariot ins t ead of C hariot Ex t . For ex ample:
# load C hariot
# pac k age require C hariot
l append : : aut o_pat h " c : / P rogram \ F i l es / i x i a/ i x c hari ot / apt i x i a/ l i b/ c om m on/
t c lc lient "
load C hariot Ex t
pac k age require C hariot Ex t
pac k age require Apt ix iaC lient 2. 0
# C reat e a new t es t .
put s " C reat e t he t es t . . . "
s et t es t [ c hrTes t new ]
# N ow get t he c urrent ref erenc e t o t he t es t s erv er
put s " Get t ing t he t es t s erv er ref erenc e"
if {[ c at c h {c hrTes t get Tes t Serv erSes s ion $t es t my H os t my Port my Ses s ion}] } {
pLogError $t es t $errorC ode " c hrTes t get Tes t Serv erSes s ion $t es t
my H os t my Port
my Ses s ion"
c hrTes t delet e $t es t
ret urn
}
# Set t he t es t f ilename f or s av ing lat er.
put s " Set t es t f ilename. . . "
if {[ c at c h {c hrTes t s et $t es t FI LEN AME $t es t File}] } {
pLogError $t es t $errorC ode " c hrTes t s et FI LEN AME"
c hrTes t delet e $t es t
ret urn
}
put s " C onf igure ix ia endpoint s us ing Apt I x ia. . . "
s et my C onf ig [ c onf igureI x iaPort s $my H os t $my Port $my Ses s ion $e1_
mgmt $e2_mgmt ]
put s " I mport ing t he ix ia c onf igurat ion. . . "
i f {[ c at c h {c hrT es t s et $t es t I X I A _N E T W OR K _ C ON F I GU R A T I ON $m y C onf ig}] } {
pLogE rror $t es t $errorC ode " c hrT es t s et $t es t I X I A _N E T W OR K _
C ON FI GU R ATI ON "
c hrTes t delet e $t es t
ret urn
}
f or {s et index 0} {$index < $pairC ount } {inc r index } {
# C reat e a pair.
put s " C reat e a pair. . . "
s et pair [ c hrPair new ]
# Set pair at t ribut es f rom our lis t s .
put s " Set pair at t t ribut es . . . "

- 1170 -

IxChariot APIGuide
c hrPair s et $pair C OMMEN T " Pair [ ex pr $index + 1] "
c hrP ai r s et $pai r E 1_A D D R " M y F i rs t P ort Group"
c hrP ai r s et $pai r E 2_A D D R " M y S ec ond P ort Group"
c hrPair s et $pair U SE_C ON SOLE_E1 True
c hrP ai r s et $pai r U S E _ S E T U P _ E 1_E 2 T rue
c hrP ai r s et $pai r C ON S OLE _ E 1_A D D R " U s e I x i a N et w ork C onf i gurat i on"
c hrP ai r s et $pai r S E T U P _ E 1_E 2_ A D D R " U s e I x i a N et w ork C onf igurat ion"
c hrPair s et $pair PR OTOC OL $prot oc ols
# D ef ine a s c ript f or us e by t his pair.
# W e need t o c hec k f or errors w it h ex t ended inf o here.
s et s c ript $s c ript s
if {[ c at c h {c hrPair us eSc ript $pair $s c ript }] } {
pLogError $pair $errorC ode " c hrPair us eSc ript "
c hrTes t delet e $t es t
ret urn
}
# Add t he pair t o t he t es t .
put s " Add t he pair t o t he t es t . . . "
if {[ c at c h {c hrTes t addPair $t es t $pair}] } {
pLogError $t es t $errorC ode " c hrTes t addPair"
c hrTes t delet e $t es t
ret urn
}
}
# The t es t is c omplet e, s o now w e c an run it .
put s " R un t he t es t . . . "
if {[ c at c h {c hrTes t s t art $t es t }] } {
pLogError $t es t $errorC ode " c hrTes t s t art "
c hrTes t delet e $t es t
ret urn
}
# W ait f or t he t es t t o s t op.
# W e' ll c hec k in a loop here ev ery 5 s ec onds
# t hen c all it an error af t er t w o minut es if
# t he t es t is s t ill not s t opped.
s et t imer 0
s et is St opped 0
put s " W ait ing f or t he t es t t o s t op. . . "
w hile {! $is St opped && $t imer < $max W ait } {
s et is St opped [ c hrTes t is St opped $t es t $t imeout ]
if {! $is St opped} {
s et t imer [ ex pr $t imer + $t imeout ]
put s " W ait ing f or t es t t o s t op. . . ($t imer)"
}
}
if {! $is St opped} {
# Show t his as a t imed out error
s et rc " C H R API 118"
pLogError $t es t $rc " c hrTes t is St opped"
c hrTes t delet e $t es t
ret urn
}

- 1171 -

IxChariot APIGuide
# Sav e t he t es t s o w e c an s how res ult s lat er.
put s " Sav e t he t es t . . . "
if {[ c at c h {c hrTes t s av e $t es t }] } {
pLogError $t es t $errorC ode " c hrTes t s av e"
ret urn
}
c hrTes t delet e $t es t
# W e' re f inis hed!
ret urn

GUI Representation
If you load the XML file generated from the Tcl API script into the Stack Manager GUI, it
should appear as shown in the following figure.

- 1172 -

IxChariot APIGuide

Sample PPP Script (port-to-DUT)

This section presents a sample Tcl script for configuring a basic PPPoE session between an
Ixia port and a DUT.

Test Topology
This script requires an Ixia chassis with one Ethernet port connected to a DUT (such as a
router).

Plugin Layout
This script implements aa basic PPPoE session between an Ixia port and a DUT:

PPP Port-to-Port Tcl Script Listing

Following is the sample Tcl script for configuring a basic PPPoE session between an Ixia
port and a DUT. The script file name is ChrSM_PPP_P2D_Test.tcl.
#***************************************************************
#
# I x C hariot API SD K
File: C hrSM_PPP_P2D _Tes t . t c l
#
# This module c ont ains c ode made av ailable by I x ia on an AS I S
# bas is . Any one rec eiv ing t he module is c ons idered t o be
# lic ens ed under I x ia c opy right s t o us e t he I x ia-prov ided
# s ourc e c ode in any w ay he or s he deems f it , inc luding c opy ing
# it , c ompiling it , modif y ing it , and redis t ribut ing it , w it h
# or w it hout modif ic at ions . N o lic ens e under any I x ia pat ent s
# or pat ent applic at ions is t o be implied f rom t his c opy right
# lic ens e.
#
# A us er of t he module s hould unders t and t hat I x ia c annot
# prov ide t ec hnic al s upport f or t he module and w ill not be
# res pons ible f or any c ons equenc es of us e of t he program.
#
# Any not ic es , inc luding t his one, are not t o be remov ed f rom
# t he module w it hout t he prior w rit t en c ons ent of I x ia.
#
# For more inf ormat ion, c ont ac t :
#
# Ixia
# 26601 W . Agoura R d.
# C alabas as , C A 91302 U SA
# W eb: ht t p: / / w w w . ix iac om. c om
# Phone: 818-871-1800
# Fax : 818-871-1805
#
# General I nf ormat ion:

- 1173 -

IxChariot APIGuide
#
e-mail: inf o@ ix iac om. c om
#
# Tec hnic al Support :
#
e-mail: s upport @ ix iac om. c om
#
#
# EXAMPLE: I x ia Endpoint Pairs Tes t
# This s c ript c reat es and runs a t es t w it h ix ia endpoint pairs
# us ing PPP Plugin f or port t o D U T s c enario.
#
# The D U T needs t o be c onf igured c orrec t ly f or t he s c ript t o
# w ork .
#
#***************************************************************
#***************************************************************
# D at a f or t es t :
# C hange t hes e v alues f or y our net w ork if des ired.
#***************************************************************
s et t es t File " C : / Program Files / I x ia/ I x C hariot / Tes t s / C hrSM_ PPP_P2D _
Tes t . t s t "
s et pairC ount 1
s et prot oc ols " TC P"
s et s c ript s " c : / Program Files / I x ia/ I x C hariot / Sc ript s / R es pons e_Time. s c r"
s et t imeout 5
s et max W ait 180
s et logFile " pairs Tes t . log"
s et C H A S S I S 1_I P 192. 168. 6. 163
s et e1_m gm t " 192. 168. 6. 163; 4; 1"
s et e2_m gm t " 192. 168. 6. 163; 4; 2"
s et e1Mgmt " 192. 168. 6. 163 / 04 / 01"
s et e2Mgmt " 192. 168. 6. 163 / 04 / 02"
#***************************************************************
# Proc edure t o c onf igure ix ia port us ing Apt ix ia API
#***************************************************************
proc c onf igureI x iaPort s {my H os t my Port my Ses s ion e1_mgmt e2_mgmt } {
global C H ASSI S1_I P
# St art t es t Serv er and us e t he ins t anc e inv ok ed by ix c hariot
# -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -# This s ec t ion of c ode s et ' s
# t he " s erv er t rans ac t ion c ont ex t " `t c ' t o a part ic ular t es t s erv er
#
s et t c [ : : Apt ix iaC lient : : C ore: : Fac ilit y Get D ef ault Trans ac t ionC ont ex t ]
$t c I nit $my H os t $my Port
s e t : : m y S e s O b j [ : : A p t i x i a C l i e n t : : S e s s i o n % A U T O % -t r a n s a c t i o n c o n t e x t
$t c objec t id $my Ses s ion]
#
# Get ex is t ing t es t f rom our t es t s erv er s es s ion
#
s e t : : m y T e s t I d [ $ : : m y S e s O b j e d i t a b l e T e s t c g e t -o b j e c t i d ]
s et : : my Tes t [ : : Apt ix iaC lient : : Generic Tes t Model %AU TO% -t rans ac t ionc ont ex t $t c
-o b j e c t i d $ : : m y T e s t I d ]

- 1174 -

IxChariot APIGuide

#
# Add s ome c has s is ' s int o t he t es t model
# t he c has s is ' s are in t he s ubobjec t pat hw ay
#
# c h a s s i s C o n f i g -> c h a s s i s C h a i n
#
$: : my Tes t c has s is C onf ig c has s is C hain AddTail
s et c c Obj [ $: : my Tes t c has s is C onf ig c has s is C hain Get 0]
$c c Obj dns S et " $C H A S S I S 1_I P " ; # s et c has s i s nam e
$c c Obj c ableLengt h Set 3
$c c Obj phy s ic alC hain Set f als e
###
Set up f irs t port group
s et port Spec " $e1_mgmt "
s e t p g _i d x [ e x p r [ $ : : m y T e s t p o r t G r o u p L i s t S i z e ] -2 ]
s et pgC lient Obj [ $: : my Tes t port GroupLis t Get $pg_idx ]
$pgC lient Obj name Set " C lient N et w ork "
$pgC lient Obj port Lis t AddTail $port Spec
Set up Et hernet St ac k on " My f irs t port group" - pgObj
$pgC l i ent Obj _I ns t ant i at e s t ac k " E t hernet P l ugi n"
$pgC lient Obj s t ac k enabled Set t rue
$pgC lient Obj s t ac k mac Set " 00: 00: 00: 00: 01: 01"
# Add PPP Plugin
$ p g C l i e n t O b j s t a c k c h i l d r e n L i s t A d d T a i l -i t e m t y p e " P p p o x P l u g i n "
s et pppox C lient Obj [ $pgC lient Obj s t ac k c hildrenLis t Get 0]
$pppox C l i ent Obj c om m ent S et " pppox _c l i ent _ pl ugi n"
$pppox C lient Obj enabled Set " t rue"
$pppox C lient Obj role Set " c lient "
$pppox C lient Obj s et upR at e Set " 150"
$pppox C lient Obj enableThrot t ling Set " t rue"
$pppox C lient Obj max Out s t andingSes s ions Set " 50"
$pppox C lient Obj t eardow nR at e Set " 250"
$pppox C lient Obj numSes s ions Set " 1"
Add s ec ond c has s is t o t he lis t
$: : my Tes t c has s is C onf ig c has s is C hain AddTail
s et c c Obj [ $: : my Tes t c has s is C onf ig c has s is C hain Get 1]
$c c Obj dns S et " $C H A S S I S 1_I P " ; # s et c has s i s nam e
$c c Obj c ableLengt h Set 3
$c c Obj phy s ic alC hain Set f als e
###
Set up s ec ond port group
s et port Spec $e2_mgmt
s et pg_idx [ ex pr [ $: : my Tes t port GroupLis t Siz e] -1]
s et pgServ erObj [ $: : my Tes t port GroupLis t Get $pg_idx ]
$pgServ erObj name Set " Serv er N et w ork "
$pgServ erObj port Lis t AddTail $port Spec
Set up Et hernet St ac k
$pgS erv erObj _I ns t ant i at e s t ac k " E t hernet P l ugi n"
$pgServ erObj s t ac k enabled Set t rue
$pgServ erObj s t ac k mac Set " 00: 00: 00: 00: 02: 02"
Set up v lan range
$pgServ erObj s t ac k v lanR angeLis t AddTail
s et v lanR Obj [ $pgServ erObj s t ac k v lanR angeLis t Get 0]

- 1175 -

IxChariot APIGuide
$v lanR Obj enable Set t rue
$v lanR Obj f irs t I d Set " 3"
# Set up I P plugin on " Serv er N et w ork "
$pgServ erObj s t ac k c hildrenLis t AddTail -it emt y pe " I pV4V6Plugin"
s et ippObj [ $pgServ erObj s t ac k c hildrenLis t Get 0]
$ippObj rangeLis t AddTail
s et iprObj [ $ippObj rangeLis t Get 0]
# Bind t he ip range objec t t o t he v lan range abov e
$iprObj _Bind v lanR ange $v lanR Obj
$iprObj name Set " ip-2"
$iprObj enabled Set t rue
$iprObj ipTy pe Set I Pv 4
$iprObj ipAddres s Set " 31. 0. 10. 1"
$iprObj pref ix Set 8
$iprObj c ount Set 1
$iprObj gat ew ay Addres s Set " 31. 0. 0. 1"
# prompt $int erac t iv e " hit ret urn t o Tes t C onf igure"
$: : my Tes t Tes t C onf igure ; # applied c onf ig on port s
# All enums f or objec t s are pre-def ined w it hin t he objec t c las s as
# r e a d -o n l y c l a s s v a r i a b l e s , l i k e
# `k D eep' `k Shallow ' et c . . .
s et x m l 1 [ l i ndex [ $: : m y T es t _Get X m l \
$: : Apt ix iaC lient : : XProt oc olObjec t : : eSerializ at ionD ept h: : k D eep \
t rue] 0]
put s s t dout $x ml1
ret urn $x ml1
}
#***************************************************************
# Proc edure t o log errors if t here is ex t ended inf o
#***************************************************************
proc pLogError {handle c ode w here} {
global logFile
# D ef ine s y mbols f or t he errors w e' re int eres t ed in.
s et C H R _OPER ATI ON _FAI LED " C H R API 108"
s et C H R _OB J E C T _I N V A LI D " C H R A P I 112"
# Somet hing f ailed: s how w hat happened.
put s " $w here f ailed: [ c hrApi get R et urnMs g $c ode] "
# See if t here is ex t ended error inf ormat ion av ailable.
# I t ' s is only meaningf ul f or c ert ain errors .
if {$c ode = = $C H R _OPER ATI ON _FAI LED
|| $c ode = = $C H R _ OB J E C T _I N V A LI D } {
# Try t o get t he ex t ended error inf ormat ion
s et rc [ c at c h {s et inf o [ c hrC ommonError get I nf o \
$handle " ALL" ] }]
if {$rc ! = 0} {
# W e c an ignore all non-s uc c es s ret urn c odes here
# bec aus e mos t s hould not oc c ur (t he api' s been
# init ializ ed and t he det ail lev el is ok ay ),
# and t he N O_S U C H _ V A LU E ret urn c ode here m eans
# t here is no inf o av ailable.
s et inf o " < N one> "
}
s et logFile [ open $logFile a+ ]

- 1176 -

IxChariot APIGuide
s et t imes t amp [ c loc k f ormat [ c loc k s ec onds ] ]
put s $logFile " $t imes t amp $w here f ailed"
put s $logFile " $t imes t amp $inf o"
# Flus h f orc es immediat e w rit e t o f ile
f lus h $logFile
}
}
#***************************************************************
#
# Sc ript main
#
# c at c h is us ed w hen t here c ould be ex t ended error inf ormat ion,
# s o w e c an log w hat happened.
#***************************************************************
# Load t he C hariot API .
#
# N OTE: I f y ou are us ing Tc l Vers ion 8. 0. p5 or older
# t hen y ou w ill need t o modif y t he f ollow ing lines t o load and
# us e C hariot ins t ead of C hariot Ex t . For ex ample:
# load C hariot
# pac k age require C hariot
l append : : aut o_pat h " c : / P rogram \ F i l es / i x i a/ i x c hari ot / apt i x i a/ l i b/ c om m on/
t c lc lient "
load C hariot Ex t
pac k age require C hariot Ex t
pac k age require Apt ix iaC lient 2. 0
# C reat e a new t es t .
put s " C reat e t he t es t . . . "
s et t es t [ c hrTes t new ]
# N ow get t he c urrent ref erenc e t o t he t es t s erv er
put s " Get t ing t he t es t s erv er ref erenc e"
if {[ c at c h {c hrTes t get Tes t Serv erSes s ion $t es t my H os t my Port my Ses s ion}] } {
pLogError $t es t $errorC ode " c hrTes t get Tes t Serv erSes s ion $t es t
my H os t my Port
my Ses s ion"
c hrTes t delet e $t es t
ret urn
}
# Set t he t es t f ilename f or s av ing lat er.
put s " Set t es t f ilename. . . "
if {[ c at c h {c hrTes t s et $t es t FI LEN AME $t es t File}] } {
pLogError $t es t $errorC ode " c hrTes t s et FI LEN AME"
c hrTes t delet e $t es t
ret urn
}
put s " C onf igure ix ia endpoint s us ing Apt I x ia. . . "
s et my C onf ig [ c onf igureI x iaPort s $my H os t $my Port $my Ses s ion $e1_
mgmt $e2_mgmt ]
put s " I mport ing t he ix ia c onf igurat ion. . . "
i f {[ c at c h {c hrT es t s et $t es t I X I A _N E T W OR K _ C ON F I GU R A T I ON $m y C onf ig}] } {
pLogE rror $t es t $errorC ode " c hrT es t s et $t es t I X I A _N E T W OR K _

- 1177 -

IxChariot APIGuide
C ON FI GU R ATI ON "
c hrTes t delet e $t es t
ret urn
}
f or {s et index 0} {$index < $pairC ount } {inc r index } {
# C reat e a pair.
put s " C reat e a pair. . . "
s et pair [ c hrPair new ]
# Set pair at t ribut es f rom our lis t s .
put s " Set pair at t t ribut es . . . "
c hrPair s et $pair C OMMEN T " Pair [ ex pr $index + 1] "
c hrP ai r s et $pai r E 1_A D D R " C l i ent N et w ork "
c hrP ai r s et $pai r E 2_A D D R " S erv er N et w ork "
c hrPair s et $pair U SE_C ON SOLE_E1 True
c hrP ai r s et $pai r U S E _ S E T U P _ E 1_E 2 T rue
c hrP ai r s et $pai r C ON S OLE _ E 1_A D D R " U s e I x i a N et w ork C onf i gurat i on"
c hrP ai r s et $pai r S E T U P _ E 1_E 2_ A D D R " U s e I x i a N et w ork C onf igurat ion"
c hrPair s et $pair PR OTOC OL $prot oc ols
# D ef ine a s c ript f or us e by t his pair.
# W e need t o c hec k f or errors w it h ex t ended inf o here.
s et s c ript $s c ript s
if {[ c at c h {c hrPair us eSc ript $pair $s c ript }] } {
pLogError $pair $errorC ode " c hrPair us eSc ript "
c hrTes t delet e $t es t
ret urn
}
# Add t he pair t o t he t es t .
put s " Add t he pair t o t he t es t . . . "
if {[ c at c h {c hrTes t addPair $t es t $pair}] } {
pLogError $t es t $errorC ode " c hrTes t addPair"
c hrTes t delet e $t es t
ret urn
}
}
# The t es t is c omplet e, s o now w e c an run it .
put s " R un t he t es t . . . "
if {[ c at c h {c hrTes t s t art $t es t }] } {
pLogError $t es t $errorC ode " c hrTes t s t art "
c hrTes t delet e $t es t
ret urn
}
# W ait f or t he t es t t o s t op.
# W e' ll c hec k in a loop here ev ery 5 s ec onds
# t hen c all it an error af t er t w o minut es if
# t he t es t is s t ill not s t opped.
s et t imer 0
s et is St opped 0
put s " W ait ing f or t he t es t t o s t op. . . "
w hile {! $is St opped && $t imer < $max W ait } {
s et is St opped [ c hrTes t is St opped $t es t $t imeout ]
if {! $is St opped} {
s et t imer [ ex pr $t imer + $t imeout ]

- 1178 -

IxChariot APIGuide
put s " W ait ing f or t es t t o s t op. . . ($t imer)"
}
}
if {! $is St opped} {
# Show t his as a t imed out error
s et rc " C H R API 118"
pLogError $t es t $rc " c hrTes t is St opped"
c hrTes t delet e $t es t
ret urn
}
# Sav e t he t es t s o w e c an s how res ult s lat er.
put s " Sav e t he t es t . . . "
if {[ c at c h {c hrTes t s av e $t es t }] } {
pLogError $t es t $errorC ode " c hrTes t s av e"
ret urn
}
c hrTes t delet e $t es t
# W e' re f inis hed!
ret urn

- 1179 -

IxChariot APIGuide

Appendix A: Return Code Summary

The following topics provide a list of return codes for the IxChariot API, with an accompanying explanation of each return code and a summary of any required actions.
Most unsuccessful return codes indicate a logic problem in your program. Therefore, the
names and descriptions of these return codes are designed to aid you in your diagnosis of
the problem. The routine CHR_api_get_return_msg() returns a text message associated
with the corresponding return code, which can save you time while you are developing
your program.
Some unsuccessful return codes are not a result of a logic problem, however. They may
indicate that some other condition caused a failure. You should write your program to
expect these return codes and plan to take the appropriate action.

- 1180 -

IxChariot APIGuide

0 CHR_OK
Message Returned
The operation completed successfully.

Explanation
The function or command successfully completed the required action.

Action Required
None.

- 1181 -

IxChariot APIGuide

101 CHR_HANDLE_INVALID
Message Returned
Handle is invalid.

Explanation
At least one of the object handles passed to the function or command is invalid. There
could be several reasons for this return: the referenced object no longer exists; the handle
has not been initialized via a get or new function or command; or the handle is not appropriate for the function or command.

Action Required
Make sure that you are not passing a handle to an object instance that has been deleted.
Also check to make sure that the handle was acquired from an appropriate new function or
command.

- 1182 -

IxChariot APIGuide

139 CHR_NO_APPLIFIER_CONFIGURATION
Explanation
CHR_api_get_port_mgmt_ip_list() or CHR_api_get_network_ip_list() specified an
Ixia configuration file.

Action Required
These functions cannot use Ixia configuration files: they must specify IxApplifier configuration files.

- 1183 -

IxChariot APIGuide

138 CHR_PAYLOAD_FILE_TOO_LARGE
Explanation
The payload file is larger than 953 MB.

Action Required
Reduce the size of the payload file to ensure that it does not exceed the maximum limit of
953 MB.

- 1184 -

IxChariot APIGuide

137 CHR_APP_GROUP_DUPLICATE_NAME
Explanation
The test already contains an application group with the same name.

Action Required
Save the application group using a new (and unique) name.

- 1185 -

IxChariot APIGuide

136 CHR_APP_GROUP_INVALID
Explanation
The application group is invalid.

Action Required
Validate all the application groups that are part of the test.

- 1186 -

IxChariot APIGuide

135 CHR_APP_GROUP_NOT_VALIDATED
Explanation
The test contains an application group that was not validated.

Action Required
Use the IxChariot GUI to validate all the application groups that are part of the test.

- 1187 -

IxChariot APIGuide

134 CHR_LICENSE_WILL_EXPIRE
Explanation
An operation tried to run a test with a fixed duration that is set to exceed the expiration
time of the license. That is, the license has not yet expired, but will expire if the test were
to be run.

Action Required
Either reduce the fixed duration of the test such that it will run through to completion
before the license expires, or obtain a new license before re-running the test.

- 1188 -

IxChariot APIGuide

133 CHR_TEST_NOT_SAVED
Explanation
You are trying to delete an unsaved test.

Action Required
Either save the test before deleting or use force delete.

- 1189 -

IxChariot APIGuide

132 CHR_FUNCTION_NOT_SUPPORTED
Explanation
The command is not supported by this version of TCL.

Action Required
User needs TCL Version 8.4 or higher for this command to work.

- 1190 -

IxChariot APIGuide

131 CHR_ERROR_ACCESSING_TESTSERVER_SESSION
Explanation
The user tried to set the test server session of a remote test server but an error occurred
doing so.

Action Required
Check the test server address and port are valid. Check the session object is valid.

- 1191 -

IxChariot APIGuide

130 CHR_INVALID_NETWORK_CONFIGURATION
Explanation
An operation tried to set an Ixia network configuration but it was invalid.

Action Required
Verify the inserted object/file represent valid configurations.

- 1192 -

IxChariot APIGuide

129 CHR_NO_NETWORK_CONFIGURATION
Explanation
An operation was called that needed an Ixia network configuration to be embedded in the
Test object but none was found.

Action Required
Insert an Ixia network configuration before attempting this operation.

- 1193 -

IxChariot APIGuide

128 CHR_LICENSE_HAS_EXPIRED
Explanation
Your license has expired.

Action Required
Obtain a new license for your console and/or ports.

- 1194 -

IxChariot APIGuide

127 CHR_SCRIPT_TOO_LARGE
Explanation
The script is too large.

Action Required
The maximum size of the script was exceeded. If embedded payloads are used, check that
their size did not cause this overflow.

- 1195 -

IxChariot APIGuide

126 CHR_NOT_LICENSED
Explanation
An attempt was made to perform a function that is not allowed or is not supported by the
current product license.

Action Required
Don't perform a set for this function, which is not supported. Or upgrade your IxChariot
license to include this function.

- 1196 -

IxChariot APIGuide

125 CHR_NO_CODEC_IN_USE
Message Returned
No codec is in use.

Explanation
You tried to perform a codec function, but no codec has been specified.

Action Required
Specify a codec and then try the function again.

- 1197 -

IxChariot APIGuide

124 CHR_NOT_SUPPORTED
Message Returned
Function is not supported.

Explanation
An attempt was made to perform a function that is not allowed or is not supported by the
Console.

Action Required
Don't perform a set for this function, which is not supported.

- 1198 -

IxChariot APIGuide

123 CHR_TRACERT_RUNNING
Message Returned
Traceert running.

Explanation
You tried to start a traceroute that is already running.

Action Required
Stop the traceroute before trying to start it again.

- 1199 -

IxChariot APIGuide

122 CHR_TRACERT_NOT_RUN
Message Returned
Tracert not running.

Explanation
You tried to extract information from a traceroute that has not yet run.

Action Required
Run the traceroute on this traceroute pair before attempting to extract results or status
information.

- 1200 -

IxChariot APIGuide

121 CHR_PGM_INTERNAL_ERROR
Appendix A: Return Code Summary

Message Returned
Program internal error.

Explanation
This IxChariot API detected an internal programming error.

Action Required
Report the failure to Ixia Support (e-mail: support@ixiacom.com).

- 1201 -

IxChariot APIGuide

120 CHR_NO_MEMORY
Message Returned
Out of memory.

Explanation
The underlying IxChariot API code failed to allocate enough memory. The system is out of
memory. This message can be returned by any of the IxChariot API functions or commands.

Action Required
Check your program for memory leaks. If the program does not have any leaks, close
other applications or increase the memory and swap file size. Alternatively, you can
decrease the size of your test or recycle your Tcl shell.

- 1202 -

IxChariot APIGuide

119 CHR_BUFFER_TOO_SMALL
Message Returned
Buffer is too small.

Explanation
The size of the buffer specified for an output string is too small.

Action Required
See the constants defined in chrapi.h for appropriate lengths of the buffers.

- 1203 -

IxChariot APIGuide

118 CHR_TIMED_OUT
Message Returned
Operation has timed out.

Explanation
The running test did not complete itself in the amount of time specified as the timeout for
the function CHR_test_query_stop(), or for the chrTest isStopped Tcl command.

Action Required
You can abandon the running test, either via a call to CHR_test_abandon() or by invoking
the chrTest abandon Tcl command. Alternatively, you can wait for the test to stop: call the
function CHR_test_query_stop(), or invoke the chrTest isStopped Tcl command.

- 1204 -

IxChariot APIGuide

117 CHR_NO_SCRIPT_IN_USE
Message Returned
No script is in use.

Explanation
The value of an IxChariot script variable has been set before an IxChariot script is
assigned to a pair or multicast group object instance.

Action Required
Assign an IxChariot script to the pair or multicast group object instance before setting a
script variable.

- 1205 -

IxChariot APIGuide

116 CHR_NO_SUCH_VALUE
Message Returned
No such value.

Explanation
The requested attribute does not apply to the object instance on a get function call. For
example, this message is returned if datagram results are requested for a pair object
instance that does not use a datagram protocol (IPX, UDP, RTP).
The CHR_NO_SUCH_VALUE return code indicates that a value does not apply for the
requested attribute. When you write a generalized results extraction program, expecting
this value spares you the complex procedure for querying the pair's attributes (to determine what kind of results to expect). This value corresponds to the n/a on the IxChariot Console.

Action Required
Do not perform a get for attributes that do not apply.

- 1206 -

IxChariot APIGuide

115 CHR_VALUE_INVALID
Message Returned
Value is invalid.

Explanation
At least one of the values passed to the function or command does not fall within the valid
range.

Action Required
Provide a valid value. See the specific function or command in the C Reference or Tcl Reference for acceptable values.

- 1207 -

IxChariot APIGuide

114 CHR_NO_RESULTS
Message Returned
Results are not available.
Appendix A: Return Code Summary

Explanation
The test was run, but no results were collected for this pair. This return code indicates that
requested results are not available. Missing results may be due to an error that occurred
during the running of a test. Use the CHR_common_error_get_msg_num() and CHR_common_error_get_info() calls to retrieve the error information and display or log it to a local
log.

Action Required
In C, call CHR_common_error_get_info(), and in Tcl invoke the chrCommonError getInfo
command to determine the cause of the pair failure.

- 1208 -

IxChariot APIGuide

113 CHR_API_NOT_INITIALIZED
Message Returned
API was not initialized.

Explanation
The IxChariot API was not successfully initialized before calling IxChariot API functions.

Action Required
In C, call CHR_api_initialize() before calling other IxChariot API functions.
The IxChariot API is automatically initialized in Tcl. Check the extended error information
to determine why the IxChariot API could not be initialized successfully.

- 1209 -

IxChariot APIGuide

112 CHR_OBJECT_INVALID
Message Returned
Object is invalid.

Explanation
An incomplete or improperly defined object instance has been added to a containing object
instance. An object instance is considered incomplete if not all of the required attributes
are defined. An object instance is also considered improperly defined if attribute values
contain conflicts. This return code means that an error occurred that the program could not
correct, but that the user of the program may be able to correct.
Your program should capture extended error information for this return code. Use the
CHR_common_error_get_info() function to access this information. This information may
be useful to save to a local log or display to the user of the program so that external corrective action may be taken.

Action Required
Correctly define the object instance. Use CHR_common_error_get_info() or the Tcl command chrCommonError getInfo to access the extended error information for details on
why the object is invalid.

- 1210 -

IxChariot APIGuide

111 CHR_PAIR_LIMIT_EXCEEDED
Message Returned
Pair limit would be exceeded.

Explanation
The program is attempting to add more pairs object instances to a test object instance
than are allowed by your IxChariot license. You must upgrade your IxChariot license to
allow tests with the number of pairs you need.

Action Required
In C, call CHR_api_get_max_pairs(), or in Tcl invoke chrAPI getMaxPairs to get the maximum number of pairs supported by the current license.

- 1211 -

IxChariot APIGuide

110 CHR_RESULTS_NOT_CLEARED
Message Returned
Results were not cleared.

Explanation
An attempt has been made to change a test that currently has results. Changing the test
invalidates the results because the results do not apply to the new test. Results must be
cleared before the test can be changed.

Action Required
Clear results by calling CHR_test_clear_results() or by invoking the chrTest clearResults
Tcl command. Then change the test.

- 1212 -

IxChariot APIGuide

109 CHR_NO_TEST_FILE
Message Returned
A test file has not been set.

Explanation
A test has been saved before a test filename has been specified.

Action Required
Provide a test filename before saving a test.

- 1213 -

IxChariot APIGuide

108 CHR_OPERATION_FAILED
Message Returned
Operation has failed.

Explanation
The requested operation could not be completed successfully. This return code means that
an error occurred that the program could not correct, but that the user of the program may
be able to correct. Your program should capture the data available in the extended error
information. Use the CHR_common_error_get_info() function to access the extended
information, which may be useful to save to a local log or to display to the user of the program so that external corrective action may be taken. An example of this type of failure
can occur when prompting a user for an IxChariot test file to load. If this file does not
exist, the CHR_test_load() fails and returns CHR_OPERATION_FAILED, and the extended
error information contains a message indicating that the file could not be found.

Action Required
Use CHR_common_error_get_info() or the Tcl command chrCommonError getInfo to
access the extended error information for details on the cause of the failure. Refer to Error
Detail Levels and Extended Error Information.

- 1214 -

IxChariot APIGuide

107 CHR_OBJECT_IN_USE
Message Returned
Object is in use.

Explanation
An attribute is set on an object instance that is already contained by another object
instance. For example, an attempt to set an attribute on a pair object instance that has
already been added to a test object instance will prompt this return code. This message is
also returned when the reporting port is changed after the process has already run a test.
In addition, this message can be returned if an attempt is made to add a multicast group,
multicast pair, or a pair that is already contained, to an object instance of the appropriate
type.

Action Required
Don't modify object instances that are owned by other object instances. Change the reporting port before the process runs the first test.

- 1215 -

IxChariot APIGuide

106 CHR_TEST_RUNNING
Message Returned
Test is running.

Explanation
Results have been extracted or the test has been saved while the test is running. This message is also returned if you attempt to run a test while another test is already running on
the computer.

Action Required
Wait for the test to finish by calling CHR_test_query_stop() or by invoking chrTest
isStopped before attempting other functions.

- 1216 -

IxChariot APIGuide

105 CHR_TEST_NOT_RUN
Message Returned
Test was not run.

Explanation
Attempts to extract results have been made before a test has run.

Action Required
Run the test before attempting to extract results.

- 1217 -

IxChariot APIGuide

104 CHR_NO_SUCH_OBJECT
Message Returned
No such object.

Explanation
An object instance corresponding to the specified index does not exist.

Action Required
Check to ensure that the index is not larger than the number of objects contained within
the object instance.

- 1218 -

IxChariot APIGuide

103 CHR_POINTER_INVALID
Message Returned
Pointer is invalid.

Explanation
A pointer passed into a function is invalid.

Action Required
Provide a valid pointer for the function.

- 1219 -

IxChariot APIGuide

102 CHR_STRING_TOO_LONG
Message Returned
String is too long.

Explanation
Each string attribute has a maximum size. The provided string is too long for the target
attribute.

Action Required
See the constants defined in chrapi.h for maximum lengths of strings allowed for the various attributes.

- 1220 -

IxChariot APIGuide

140 CHR_CHANNEL_DUPLICATE_NAME
Explanation
The test already contains an IPTV channel object with the same name.

Action Required
Save the IPTV channel object using a new (and unique) name.

- 1221 -

IxChariot APIGuide

141 CHR_RECEIVER_DUPLICATE_NAME
Explanation
The test already contains an IPTV receiver object with the same name.

Action Required
Save the IPTV receiver object using a new (and unique) name.

- 1222 -

IxChariot APIGuide

142 CHR_IPTV_INVALID
Explanation
Not all the IPTV pairs in the test are listening to channels from the same test. This error
occurs if a vpair is associated with a channel, but the channel has not been added to the
test or was removed from the test.

Action Required
Ensure that the vpair is associated with a channel, and the channel is added to the test.

- 1223 -

IxChariot APIGuide

143 CHR_DUPLICATE_NAME
Explanation
A specified object (such as an IPTV channel or receiver name) must have a unique name
but the object name is a duplicate of another name.

Action Required
Assign the specified IPTV channel or receiver a unique name.

- 1224 -

IxChariot APIGuide

144 CHR_LICENSE_ALREADY_BORROWED
Explanation
A license has already been borrowed for this machine.
Indicates the fact that another borrowed license has already been checked out for the current client and is still valid.

Action Required
For borrowed licenses, a new checkout with specific license details cannot be performed
until the last valid license has been released (by setting borrow days to zero).

- 1225 -

(Undefined variable: NTO_User_Guide.Title)

CHR_api_get_license_type 114

Index

CHR_api_get_max_pairs 115
CHR_api_get_network_ip_list 116

A
abandon run 585, 1029

CHR_api_get_pair_type 118

abandon test 44

CHR_api_get_port_mgmt_ip_list 120

additional delay 739

CHR_api_get_reporting_port 122

addresses 1081, 1088

CHR_api_get_return_msg 123

ADVANCED 838

CHR_api_get_version 124

ALLOW_PAIR_REINIT 1014, 1019

CHR_api_initialize 125-126

ALLOW_PAIR_REINIT_RUN 1014

CHR_api_license_change_borrow_
time 128-129

API

CHR_api_license_checkin_pairs 130

object-based interface 37

CHR_api_license_checkout_pairs 131

objects 37, 104

CHR_api_license_get_pair_count 132-134

overview 37

chr_api_modify_qos_tos_template 135

API Utility Command 843

chr_api_new_qos_tos_template 137

chrApi deleteQosTemplate 844

CHR_api_set_reporting_port 139

chrApi getDetail 845

Application Group Object Command

chrApi getLicenseExpirationTime 846

chrAppGroup addEvent 867

chrApi getLicenseType 847

chrAppGroup addPair 868

chrApi getMaxPairs 848

chrAppGroup copy 869

chrApi getNetworkIPList 849

chrAppGroup delete 870

chrApi getPairType 850

chrAppGroup get 872

chrApi getPortMgmtIPList 851

chrAppGroup getAddress 871

chrApi getReportingPort 852

chrAppGroup getCount 874

chrApi getReturnMsg 853

chrAppGroup getEventComment 875

chrApi getVersion 854

chrAppGroup getEventName 876

chrApi licenseChangeBorrowTime 855

chrAppGroup removeEvent 880

chrApi licenseCheckinPairs 857

chrAppGroup removePair 881

chrApi licenseCheckoutPairs 858

Application Group Object Functions

chrApi licenseGetTestPairCount 861

CHR_app_group_add_event 141

chrApi modifyQosTemplate 862

CHR_app_group_add_pair 143

chrApi newQosTosTemplate 863

CHR_app_group_copy 144

chrApi setDetail 864

CHR_app_group_delete 146

chrApi setReportingPort 865

CHR_app_group_disable 147

API Utility Functions 84, 111

CHR_app_group_force_delete 148

CHR_api_delete_qos_template 112

CHR_app_group_get_address 149

CHR_api_get_license_expiration_time 113

- 1226 -

(Undefined variable: NTO_User_Guide.Title)

CHR_app_group_get_address_count 151
CHR_app_group_get_comment 152
CHR_app_group_get_event 153
CHR_app_group_get_event_count 155

application groups 586, 595-597, 622, 866,

1040-1042, 1059, 1062
application script name 420
APPLY_DOD_ONLY 1014, 1019
B

CHR_app_group_get_filename 156
CHR_app_group_get_lock 157

BSSID 643, 645

CHR_app_group_get_management_
address 158

bytes received 195-196

CHR_app_group_get_management_
address_count 160

CHR_app_group_get_name 161
CHR_app_group_get_pair 162
CHR_app_group_get_pair_count 163
CHR_app_group_get_pair_management_
protocol 164
CHR_app_group_get_pair_protocol 165
CHR_app_group_get_pair_qos_
name 166
CHR_app_group_is_disabled 168
CHR_app_group_new 169
CHR_app_group_remove_event 170
CHR_app_group_remove_pair 171
CHR_app_group_save 172
CHR_app_group_set_address 173
CHR_app_group_set_comment 175
CHR_app_group_set_filename 176
CHR_app_group_set_lock 178
CHR_app_group_set_management_
address 179
CHR_app_group_set_name 181
CHR_app_group_set_pair_management_
protocol 183
CHR_app_group_set_pair_protocol 185
CHR_app_group_set_pair_qos_
name 187
CHR_app_group_validate 189

- 1227 of 1244-

IBM VisualAge 615-616

C Reference
Introduction 102
C sample program 86
C_samp 86
Channel Object Command
chrChannel delete 906
chrChannel get 907
chrChannel new 910
chrChannel set 911
Channel Object Commands 905
CHR_api. See API Utility Functions 111
chr_api_delete_qos_template 112
chr_api_modify_qos_tos_template 135
chr_api_new_qos_tos_template 137
CHR_API_NOT_INITIALIZED 1209
CHR_BUFFER_TOO_SMALL 1203
CHR_channel See IPTV Channel Object Functions 253
CHR_common_error See Common Error
Functions 190
CHR_common_results See Common Results
Extraction Functions 194
CHR_DETAIL_LEVEL 1214
CHR_dgopts 59

(Undefined variable: NTO_User_Guide.Title)

CHR_dgopts See Datagram Options Object Functions 226

CHR_runopts See Run Options Object

Functions 512

CHR_HANDLE_INVALID 1182

CHR_STRING_TOO_LONG 1220

CHR_hoprec 67, 248

CHR_test 46

CHR_LICENSE_HAS_EXPIRED 1194

CHR_test_clear_results 80, 1212

CHR_mgroup 54

CHR_test_load 1214

CHR_mgroup See Multicast Group Object Functions 342

CHR_test_new 616

CHR_mpair 56

CHR_test_query_stop 1216
CHR_test See Test Object Functions 584

CHR_mpair See Multicast Pair Object

Functions 398

CHR_test_abandon 1204
CHR_TEST_NOT_RUN 1217

CHR_NO_CODEC_IN_USE 1197

CHR_test_query_stop 1204

CHR_NO_MEMORY 1202

CHR_TEST_RUNNING 1216

CHR_NO_RESULTS 1208

CHR_test_stop 585

CHR_NO_SCRIPT_IN_USE 1205

CHR_TIMED_OUT 1204

CHR_NO_SUCH_OBJECT 1218

CHR_timingrec 64, 641

CHR_NO_SUCH_VALUE 1206

CHR_timingrec See Timing Record Object Functions 641

CHR_NO_TEST_FILE 1213
CHR_NOT_LICENSED 1196

CHR_TRACEROUTE_NOT_RUN 1200

CHR_NOT_SUPPORTED 1198

CHR_TRACEROUTE_RUNNING 1199

CHR_OBJECT_IN_USE 1215

CHR_tracert 65

CHR_OBJECT_INVALID 1210

CHR_tracert_pair_get_hop_record 249

CHR_OK 1181

CHR_tracert_pair_new 65

CHR_OPERATION_FAILED 1214

CHR_tracert See Traceroute Pair Object Functions 659

CHR_pair 48, 50
CHR_pair_results 80

CHR_tracert_pair_get_hop_record 250

CHR_pair_results_get_average 80

CHR_VALUE_INVALID 1207

CHR_pair See Pair Object Functions 415

CHR_video_mgroup See Video Multicast Group

Object Functions 678, 1091

CHR_PAIR_LIMIT_EXCEEDED 1211

CHR_video_pair See Video Pair Object

Functions 699

CHR_pair_set 49, 52
CHR_PGM_INTERNAL_ERROR 1201

CHR_voip_pair 68-69

CHR_POINTER_INVALID 1219
CHR_receiver See IPTV Receiver Object Functions 311

CHR_voip_pair See VoIP Pair Object

Functions 722
chr_voip_pair, chrvoippair, voip pair object

CHR_report See Report Object Functions 507

CHR_RESULTS_NOT_CLEARED 1212
CHR_runopts 61, 63

default values 69
CHR_vpair See IPTV PairObject Functions 294
chrApi 843

- 1228 -

(Undefined variable: NTO_User_Guide.Title)

chrApi deleteQosTemplate 844

ChrTestResults.c 101

chrApi modifyQosTemplate 862

ChrTestResults.tcl 101

chrApi newQosTosTemplate 863

chrTimingRec See Timing Record Object Command 1074

chrApi See API Utility Command 843

chrapi.h 103
chrCommonError 888
chrCommonResults 80, 892-893
chrDgOpts 59, 899, 901

chrTracertPair See Traceroute Pair Object

Command 1079
ChrVoipPair 68
CLKSYNC_EXTERNAL 1014, 1019
CLKSYNC_HARDWARE_TS 1014, 1020

chrDgOpts See Datagram Options Object Command 898

Close Type 393, 470, 958-959, 994-995

chrHopRec 904

codec 680, 691, 701, 713, 724-725, 1092,

1098, 1105, 1197

chrHopRec See Hop Record Object

Command 903

COLLECT_TCP_STATISTICS 1014, 1020

ChrLBSimple.c 86, 101

chrLBSimple.tcl 95
ChrLBSimple.tcl 95, 101
chrMGroup 54, 953
chrMGroup See Multicast Group Object Command 937
ChrMGroupsTest.c 101

Command Language 833

Common Error Command 888
chrCommonError getInfo 889
chrCommonError getMsgNum 891
Common Error Functions 190
CHR_common_error 191
CHR_common_error_get_msg_num 193

ChrMGroupsTest.tcl 101

Common Results Extraction Command 892

chrMPair 56

Common Results Extraction Functions 194

chrMPair See Multicast Pair Object

Command 963

CHR_common_results get_bytes_sent_
e1 197

chrPair 48, 50

CHR_common_results_get_bytes_recv_
e1 195

chrPair See Pair Object Command 974

chrPairResults 80
chrPairResults See Pair/MPair Results Extraction Command 1005
ChrPairsTest.c 101

CHR_common_results_get_bytes_recv_
e2 196
CHR_common_results_get_dg_dup_
recv_e1 198

ChrPairsTest.tcl 101

CHR_common_results_get_dg_dup_
recv_e2 199

chrRunOpts See Run Options Object Command 1013

CHR_common_results_get_dg_dup_
sent_e1 200

chrRunOpts setNumResultRanges 1025

CHR_common_results_get_dg_dup_
sent_e2 201

chrRunOpts setResultRange 1026

chrTest See Test Object Command 1028

- 1229 of 1244-

CHR_common_results_get_dg_lost_e1_
to_e2 202

(Undefined variable: NTO_User_Guide.Title)

CHR_common_results_get_dg_out_of_
order 203
CHR_common_results_get_dg_recve2 205

CREATE 99
CSD_VERSION 943, 967, 980
ctime value 615-616
D

CHR_common_results_get_dg_recv_
e1 204

Data Files 470

CHR_common_results_get_dg_sent_
e1 206

datagram options 601, 1046

datagram options object 59, 898

CHR_common_results_get_est_clock_
error 219

default values 60

CHR_common_results_get_jittter_buffer_
lost 220

Datagram Options Object Functions 226

CHR_dgopts_get_data_rate_limit 227

CHR_common_results_get_max_clock_
error 221

CHR_dgopts_get_limit_data_rate 228
CHR_dgopts_get_low_sender_jitter 229

CHR_common_results_get_meas_
time 222

CHR_dgopts_get_measured_interval 230

CHR_common_results_get_rtd 223

CHR_dgopts_get_recv_timeout 231

CHR_common_results_get_rtd_95pct_confidence 224

CHR_dgopts_get_retrans_count 232
CHR_dgopts_get_retrans_timeout 233

CHR_common_results_get_trans_
count 225

CHR_dgopts_get_RTP_use_extended_headers 234

Compiling and Linking Programs

CHR_dgopts_get_TTL 235

C 109

CHR_dgopts_get_window_size 236

completion status 106

CHR_dgopts_set_data_rate_limit 237

connect timeout 519

CHR_dgopts_set_limit_data_rate 238

CONNECT_TIMEOUT 1014, 1019

CHR_dgopts_set_low_sender_jitter 239

consecutive lost 528-529, 566

CHR_dgopts_set_measured_interval 241

CONSECUTIVE_LOST 1077

CHR_dgopts_set_recv_timeout 242

Console to E1 48-49, 52, 55, 122, 953

CHR_dgopts_set_retrans_count 243

address 350, 422, 454

CHR_dgopts_set_retrans_timeout 244

port number 852, 865

protocol 423, 455

CHR_dgopts_set_RTP_use_extended_headers 245

QoS 424

CHR_dgopts_set_TTL 246

values 475

CHR_dgopts_set_window_size 247

Console to Endpoint 1 977, 989, 1001, 1003,

1115, 1117
Console to Endpoint 1 quality of service 456
copy pair 416

datagram retransmissions 243

datagram window size 236, 247
datagrams lost 202

CPU utilization 63, 500-501, 520, 556, 1006,

1019
CPU_UTIL 1014

datagram retransmission timeout 233, 244

datagrams out of order 203

datagrams received 204-205

- 1230 -

(Undefined variable: NTO_User_Guide.Title)

datagrams sent 206

debugging tips

FEWER_SETUP_CONNECTIONS 522-523,
558-559, 1014, 1019

Tcl 838
default data 393

filename 602

default data files 958-959, 994

FIXED_DURATION 1019

Default Data Files 995

FORCE_REPORTING_ACK 1015
G

DELAY_VARIATION 1077
get attribute 104

delete pair 418, 976

delete test 593

destination port 743

Hardware Pair Object 480

DLL 36

Hardware Pair Object Command 1000

loading 839

chrHardwarePair get 1001

duplicate datagrams received 198-199

chrHardwarePair new 1002

duplicate datagrams sent 200-201

chrHardwarePair set 1003

chrHardwareVoipPair get 1115

elapsed time 1075

chrHardwareVoipPair new 1116

end-to-end delay 648

chrHardwareVoipPair set 1117

endpoint 662, 953, 977

Hardware Pair Object Functions

addresses 458, 965, 977, 1088

CHR_hardware_pair_get_line_rate 481

configuration 943

CHR_hardware_pair_get_measure_statistics 483

Endpoint 1 to Endpoint 2 977

endpoint address 410, 426, 429, 457

CHR_hardware_pair_get_override_line_
rate 482

endpoint configuration 427, 430, 967, 980

CHR_hardware_pair_new 484

error checking 41

CHR_hardware_pair_set_line_rate 486

error information 106

CHR_hardware_pair_set_measure_statistics 488

extended 835
error returns 191, 193, 1180
Tcl 835
estimated clock error 219, 893
examples 101
extended error information 107, 836, 889,
1214

CHR_hardware_pair_set_override_line_
rate 487
CHR_hardware_voip_pair_new 485
header file 102
hop latency 250
hop name 251
hop record object 67, 248, 903, 1084

- 1231 of 1244-

(Undefined variable: NTO_User_Guide.Title)

Hop Record Object Functions

CHR_channel_get_use_console_e1_
values 274

CHR_hoprec_get_hop_address 249

CHR_channel_new 275

CHR_hoprec_get_hop_latency 250

CHR_channel_set_bitrate 276

CHR_hoprec_get_hop_name 251

CHR_channel_set_codec 277

CHR_hoprec_get_hop_number 252

CHR_channel_set_comment 278

HOW_ENDED 1038

CHR_channel_set_conn_buff_size 279

HW_TIMESTAMPS 1015

CHR_channel_set_console_e1_addr 280

CHR_channel_set_e1_addr 282
inactive time 649, 1075
CHR_channel_set_e1_protocol 281
include file
CHR_channel_set_frames_per_
datagram 283

compiling in C 109
INIT_RECV_TIMEOUT 1015

CHR_channel_set_lock 284

inter-object relationships in API 39

CHR_channel_set_media_frame_size 285

IP Multicast 941, 953

CHR_channel_set_multicast_addr 286

IP Multicast address 385

CHR_channel_set_multicast_port 287

IP Multicast port 387

CHR_channel_set_name 288

IPTV Channel Object Functions

CHR_channel_set_protocol 289

CHR_channel_delete 254

CHR_channel_set_qos_name 290

CHR_channel_get_bitrate 255

CHR_channel_set_rtp_payload_type 291

CHR_channel_get_codec 256

CHR_channel_set_source_port_num 292

CHR_channel_get_comment 257

CHR_channel_set_use_console_e1_
values 293

CHR_channel_get_conn_buff_size 259

CHR_receiver_get_conn_buff_size 317,
334

CHR_channel_get_console_e1_addr 260
CHR_channel_get_e1_addr 263

CHR_receiver_get_lock 320

CHR_channel_get_e1_protocol 262

CHR_receiver_remove_vpair 332

CHR_channel_get_frames_per_
datagram 264

CHR_receiver_set_lock 336

CHR_channel_get_lock 265

CHR_vpair_get_lock 297

CHR_channel_get_media_frame_size 266

CHR_vpair_set_lock 307
IPTV Pair Object Command 914

CHR_channel_get_multicast_addr 267
CHR_channel_get_multicast_port 268

chrVPair delete 915

CHR_channel_get_name 269

chrVPair get 916

CHR_channel_get_protocol 270

chrVPair getReport 918

CHR_channel_get_qos_name 271

chrVPair getReportCount 919

CHR_channel_get_rtp_payload_type 272

chrVPair getTimingRecord 920

CHR_channel_get_source_port_num 273

chrVPair getTimingRecordCount 921

chrVPair new 922

- 1232 -

(Undefined variable: NTO_User_Guide.Title)

chrVPair set 923

IPTV Pair Object Functions

CHR_receiver_new 331
CHR_receiver_set_comment 333

CHR_vpair_delete 295

CHR_receiver_set_e2_addr 335

CHR_vpair_get_channel 296

CHR_receiver_set_name 337

CHR_vpair_get_no_of_timing_
records 298

CHR_receiver_set_no_of_iterations 338

CHR_vpair_get_report 299

CHR_receiver_set_setup_e1_e2_
addr 339

CHR_vpair_get_report_count 300

CHR_receiver_set_switch_delay 340

CHR_vpair_get_report_timing_
record 303

CHR_receiver_set_use_e1_e2_
values 341

CHR_vpair_get_runStatus 301

IPv6 Test Module 183, 185, 463

CHR_vpair_get_timing_record_
count 304

IxChariot 36, 50, 838, 1205

CHR_vpair_get_tr_duration 305
CHR_vpair_new 306
CHR_vpair_set_channel 309

API Guide 36
IxChariot API 36-37
IxChariot API objects 833
C 104

CHR_vpair_set_no_of_timing_
records 308

IxChariot Console 37, 46

CHR_vpair_set_tr_duration 310

IxChariot Options Menu 374, 452, 484-487,

624, 988, 1002, 1061, 1116

IPTV receiver object 925

IPTV Receiver Object Functions 311
CHR_receiver_add_vpair 312
CHR_receiver_delete 313
CHR_receiver_disable 314
CHR_receiver_get_comment 315
CHR_receiver_get_e2_addr 318
CHR_receiver_get_name 321
CHR_receiver_get_no_of_iterations 323
CHR_receiver_get_setup_e1_e2_
addr 326

Ixia Port Configuration Functions 489

CHR_test_clear_ixia_port_
configuration 490
CHR_test_get_ixia_port_
configuration 491
CHR_test_load_ixia_port_
configuration 492
CHR_test_save_ixia_port_
configuration 493
CHR_test_set_ixia_port_
configuration 494
J

CHR_receiver_get_switch_delay 328

jitter 528-529, 566, 1006, 1075

CHR_receiver_get_use_e1_e2_
values 329

jitter (delay variation) maximum 652, 1075

CHR_receiver_get_vpair 324
CHR_receiver_get_vpair_count 325
CHR_receiver_is_disabled 330

- 1233 of 1244-

jitter buffer lost datagrams 220, 893

jitter buffers 220, 745, 893

(Undefined variable: NTO_User_Guide.Title)

Multicast Group Object Command 937

chrMGroup addMPair 938

library file

chrMGroup copy 939

compiling in C 109
license control functions 113-114, 128-134,
846-847, 855, 857-858, 861

chrMGroup delete 940

local_start_time 605

chrMGroup get MPair 945

LOCAL_START_TIME 1038

chrMGroup getEndpointConfig 943

local_stop_time 606

chrMGroup getMPairCount 946

LOCAL_STOP_TIME 1038

chrMGroup getPayloadFile 947

LOCK 383, 411, 459, 953, 972, 989

chrMGroup getPayloadFileIsEmbedded 948

lock object 989

chrMGroup getScriptEmbeddedPayload 949

loopback 86, 95, 101

chrMGroup getScriptVar 950

Loopback Test 101

chrMGroup new 951

chrMGroup get 941

chrMGroup removeMPair 952

MANAGEMENT_QOS_CONSOLE_NAME 1015,
1021

chrMGroup setPayloadFile 956

chrMGroup setScriptEmbeddedPayload 958

MANAGEMENT_QOS_ENDPOINT_NAME 1015,
1021

chrMGroup setScriptVar 959

Max String Length 989

chrMGroup useScript 962

MAX_HOPS 1081, 1088

Multicast Group Object Functions

MAX_TIMEOUT 1081, 1088

CHR_mgroup_add_mpair 343

maximum clock error 221, 893

CHR_mgroup_copy 344

maximum consecutive lost 1075

CHR_mgroup_delete 346

maximum consecutive lost datagrams 651

CHR_mgroup_disable 347

maximum hops 66

CHR_mgroup_get_appl_script_name 348

maximum timeout 66

CHR_mgroup_get_comment 349

measured time 222

CHR_mgroup_get_console_e1_addr 350

message number 193, 891

CHR_mgroup_get_console_e1_
protocol 351

Message Reference 193

Microsoft Visual C++ 108

CHR_mgroup_get_console_e1_qos_
name 352

MOS estimate 654, 1006, 1075

CHR_mgroup_get_e1_addr 354

multicast address 359

CHR_mgroup_get_e1_config_value 355

multicast group 361-362, 366, 369, 432

CHR_mgroup_get_mpair 357

multicast group object 54, 342

CHR_mgroup_get_mpair_count 358

default values 55

CHR_mgroup_get_multicast_addr 359

Multicast Group Object 101

CHR_mgroup_get_multicast_port 360
CHR_mgroup_get_name 361

- 1234 -

(Undefined variable: NTO_User_Guide.Title)

CHR_mgroup_get_payload_file 362

Multicast Pair Object 56, 398

CHR_mgroup_get_protocol 364

Multicast Pair Object Command 963

CHR_mgroup_get_qos_name 365

chrMPair delete 964

CHR_mgroup_get_script_embedded_payload 366

chrMPair get 965

CHR_mgroup_get_script_filename 368
CHR_mgroup_get_script_variable 369
CHR_mgroup_get_use_console_e1_values 371
CHR_mgroup_is_disabled 372
CHR_mgroup_is_udp_RFC768_
streaming 373

chrMPair getEndpointConfig 967

chrMPair getTimingRecord 969
chrMPair getTimingRecordCount 970
chrMPair new 971
chrMPair set 972
Multicast Pair Object Functions
CHR_mpair_delete 399

CHR_mgroup_new 374

CHR_mpair_get_e2_addr 400

CHR_mgroup_remove_mpair 375

CHR_mpair_get_e2_config_value 401

CHR_mgroup_set_comment 376

CHR_mpair_get_runStatus 403

CHR_mgroup_set_console_e1_addr 377

CHR_mpair_get_setup_e1_e2_addr 405

CHR_mgroup_set_console_e1_
protocol 378

CHR_mpair_get_timing_record 406

CHR_mgroup_set_console_e1_qos_
name 379

CHR_mpair_get_timing_record_
count 407

CHR_mgroup_set_e1_addr 380

CHR_mpair_get_use_setup_e1_e2_values 408

CHR_mgroup_set_lock 383

CHR_mpair_new 409

CHR_mgroup_set_multicast_addr 385

CHR_mpair_set_e2_addr 410

CHR_mgroup_set_multicast_port 387

CHR_mpair_set_lock 411

CHR_mgroup_set_name 388

CHR_mpair_set_setup_e1_e2_addr 413

CHR_mgroup_set_payload_file 389

CHR_mpair_set_use_setup_e1_e2_values 414

CHR_mgroup_set_protocol 391
CHR_mgroup_set_qos_name 392
CHR_mgroup_set_script_embedded_payload 381
CHR_mgroup_set_script_variable 393

multicast port 268, 360, 387, 697

N
Nagle algorithm 393, 470, 958-959, 994995

CHR_mgroup_set_use_console_e1_values 396

network protocol 434, 455, 977, 989

CHR_mgroup_use_script_filename 397

new function 104

CHR_pair_get_payload_file 432

new hardware pair 1002, 1116

multicast pair 343, 357-358

- 1235 of 1244-

IPv6 183, 185, 463

new pair 988

(Undefined variable: NTO_User_Guide.Title)

new video multicast group 688

Pair Object Functions

new video pair 710

CHR_pair_copy 416

null terminator 105

CHR_pair_delete 418
O

CHR_pair_disable 419

object-based interface 37

CHR_pair_get_appl_script_name 420

one-way delay 654-655, 1075

CHR_pair_get_comment 421

optional data files 393, 958-959, 994-995

CHR_pair_get_console_e1_addr 422

OS_BUILD_NUMBER 943, 967, 980

CHR_pair_get_console_e1_protocol 423

OVERLAPPED_SENDS_COUNT 1015

CHR_pair_get_console_e1_qos_name 424
CHR_pair_get_e1_addr 426

CHR_pair_get_e1_config_value 427

package initialization

CHR_pair_get_e2_addr 429

Tcl 839
packet loss concealment 752, 1108

CHR_pair_get_e2_config_value 430

pair comment 421, 453

CHR_pair_get_protocol 434

pair object 48, 50

CHR_pair_get_qos_name 435-437
CHR_pair_get_runStatus 438

default values 49, 52

CHR_pair_get_script_embedded_
payload 440

Pair Object 415, 974

Pair Object Command

CHR_pair_get_script_filename 442

chrPair copy 975

CHR_pair_get_script_variable 443

chrPair delete 976

CHR_pair_get_setup_e1_e2_addr 445

chrPair get 977

CHR_pair_get_timing_record 446

chrPair getEndpointconfig 980

CHR_pair_get_timing_record_count 447

chrPair getPayloadFile 982

CHR_pair_get_use_console_e1_values 448

chrPair getPayloadFileIsEmbedded 983

chrPair getScriptEmbeddedPayload 984

CHR_pair_get_use_setup_e1_e2_
values 449

chrPair getScriptVar 985

CHR_pair_is_disabled 450

chrPair getTimingRecord 986

CHR_pair_is_udp_RFC768_streaming 451

chrPair getTimingRecordCount 987

CHR_pair_new 452

chrPair new 988

CHR_pair_set_comment 453

chrPair set 989

CHR_pair_set_console_e1_addr 454

chrPair setPayloadFile 992

CHR_pair_set_console_e1_protocol 455

chrPair setScriptEmbeddedPayload 994

CHR_pair_set_console_e1_qos_name 456

chrPair setScriptVar 995

CHR_pair_set_e1_addr 457

chrPair swapEndpoints 999

CHR_pair_set_e2_addr 458

chrPair useScript 998

CHR_pair_set_lock 459
CHR_pair_set_payload_file 461

- 1236 -

(Undefined variable: NTO_User_Guide.Title)

CHR_pair_set_protocol 463

poll endpoints 571

CHR_pair_set_qos_name 465-467

POLL_ENDPOINTS 1019

CHR_pair_set_script_embedded_
payload 468

POLL_RETRIEVING_TYPE 1015

CHR_pair_set_script_variable 470
CHR_pair_set_setup_e1_e2_addr 474
CHR_pair_set_use_console_e1_
values 475
CHR_pair_set_use_setup_e1_e2_
values 478
CHR_pair_swap_endpoints 479
CHR_pair_use_script_filename 476

POLL_TIME 1019
polling endpoints 534
polling interval 535, 572
port number 393, 470, 958-959, 994-995
print results 101
Program Notes 99
protocol
IPv6 183, 185, 463

pair setup address 405, 445, 449, 474, 478479

pair type 118
Pair/MPair Results Extraction 495
Pair/Mpair Results Extraction
Command 1005

Q
QoS 396, 424, 435-437, 456, 465-467, 953
QoS template functions 112, 135, 137
Quality Of Service 396, 424, 435-437, 456,
465-467, 953
R

chrPairResults get 1006

chrPairResults get95PctConfidence 1010
Pair/MPair Results Extraction Functions
CHR_pair_results_get_95pct_
confidence 496
CHR_pair_results_get_average 498
CHR_pair_results_get_CPU_util_e1 500
CHR_pair_results_get_CPU_util_e2 501
CHR_pair_results_get_maximum 502
CHR_pair_results_get_minimum 504
CHR_pair_results_get_rel_precision 506
PAIR_REINIT_MAX 1015, 1019
PAIR_REINIT_MAX_RUN 1015
PAIR_REINIT_RETRY_INTERVAL 1015,
1019

R-value 656, 1075, 1108

random buffer sizes 393, 470, 958-959,
994-995
random new seed 521, 537, 557, 574
Random Sleep Time 393, 470, 995
random sleep times 958-959, 994
RANDOM_NEW_SEED 1016, 1019
receive timeout 242
Receiver Object Command
chrReceiver addVPair 926
chrReceiver delete 927
chrReceiver get 928
chrReceiver getVPair 930
chrReceiver getVPairCount 931

PAIR_REINIT_RETRY_INTERVAL_RUN 1015

chrReceiver new 932

PKGINDEX.TCL file 839

chrReceiver removeVPair 933

PLC (packet loss concealment) 752, 1108

chrReceiver set 934

- 1237 of 1244-

(Undefined variable: NTO_User_Guide.Title)

Receiver Object Functions 925

Run Environment

report group identifier 657

Tcl 41, 837

Report Object Functions 507, 1011

run options object 61

CHR_report_get_item_type 508

default values 63

CHR_report_get_join_latency 509

Run Options Object Command 1013

CHR_report_get_leave_latency 510

chrRunOpts get 1014

CHR_report_get_report_group_id 511

chrRunOpts getNumResultRanges 1017

chrReport get 1012

chrRunOpts getResultRange 1018

reporting port 139

chrRunOpts set 1019

reporting type 576

chrRunOpts setNumResultRanges 1025

REPORTING_FIREWALL 1016

chrRunOpts setResultRange 1026

REPORTING_TYPE 1016, 1019

Run Options Object Functions 512

Resolve Hop Names 1088

CHR_runopts_get_allow_pair_reinit 513

RESOLVE_HOP_NAME 1081

CHR_runopts_get_allow_pair_reinit_
run 514

result frequency 658

result ranges 528-529, 540, 564, 566, 577,
1017-1018
defaults 1077

CHR_runopts_get_apply_dod_only 515
CHR_runopts_get_clksync_external 516
CHR_runopts_get_clksync_hardware_
ts 517

results 84, 122, 194, 498

CHR_runopts_get_collect_tcp_
statistics 518

IxChariot Console 84
multicast 56

CHR_runopts_get_connect_timeout 519

Results Extraction 80

CHR_runopts_get_CPU_util 520

Return Code Summary 1180

CHR_runopts_get_fewer_setup_connections 522-523

Return Codes 346

CHR_runopts_get_HW_timestampls 524525

C 106
Returned Data 951

chr_runopts_get_management_qos_console_name 526

RFC 1889 jitter 1006, 1075

RFC 768 option 373, 451

chr_runopts_get_management_qos_endpoint_name 527

round-trip delay 223-224, 893

CHR_runopts_get_num_result_
ranges 528-529, 566

rsolve hop names 66

RSSI 644, 646

CHR_runopts_get_pair_reinit_max 530
RTP 943
CHR_runopts_get_pair_reinit_max_
run 531

RTP extension headers 234, 245

RTP for IPv6 183, 185, 463

CHR_runopts_get_pair_reinit_retry_interval 532

RTP payload 685, 696, 707, 719

CHR_runopts_get_pair_reinit_retry_interval_run 533

RTP_DEFAULT_SEND 943, 967, 980

- 1238 -

(Undefined variable: NTO_User_Guide.Title)

CHR_runopts_get_poll_endpoints 534
CHR_runopts_get_poll_interval 535
CHR_runopts_get_poll_retrieving_
type 536
CHR_runopts_get_random_new_
seed 521, 537, 557
CHR_runopts_get_reporting_firewall 538
CHR_runopts_get_reporting_type 539
CHR_runopts_get_result_range 540
CHR_runopts_get_stop_after_num_
pairs_fail 542
CHR_runopts_get_stop_on_init_
failure 543
CHR_runopts_get_test_duration 544
CHR_runopts_get_test_end 545
CHR_runopts_get_validate_on_recv 546
CHR_runopts_set_allow_pair_reinit 547
CHR_runopts_set_allow_pair_reinit_
run 548
CHR_runopts_set_apply_dod_only 549
CHR_runopts_set_clksync_external 550
CHR_runopts_set_clksync_hardware_
ts 551

CHR_runopts_set_pair_reinit_max_
run 568
CHR_runopts_set_pair_reinit_retry_interval 569
CHR_runopts_set_pair_reinit_retry_interval_run 570
CHR_runopts_set_poll_endpoints 571
CHR_runopts_set_poll_interval 572
CHR_runopts_set_poll_retrieving_
type 573
CHR_runopts_set_random_new_
seed 574
CHR_runopts_set_reporting_firewall 575
CHR_runopts_set_reporting_type 576
CHR_runopts_set_result_range 577
CHR_runopts_set_stop_after_num_
pairs_fail 579
CHR_runopts_set_stop_on_init_
failure 580
CHR_runopts_set_test_duration 581
CHR_runopts_set_test_end 582
CHR_runopts_set_validate_on_recv 583
runstatus 301, 403, 438, 667, 965, 977978, 1081

CHR_runopts_set_collect_tcp_
statistics 553
CHR_runopts_set_connect_timeout 555
CHR_runopts_set_CPI_util 556

S
sample program 85
C 86

CHR_runopts_set_fewer_setup_connections 558-559

SamplesC 86

CHR_runopts_set_HW_timestamps 560561

save test 629

SamplesTcl directory 95

Scriptics 837
chr_runopts_set_management_qos_console_name 562
chr_runopts_set_management_qos_endpoint_name 563
CHR_runopts_set_num_result_
ranges 564
CHR_runopts_set_pair_reinit_max 567

- 1239 of 1244-

SDK 101
SDK directory 86, 95
Send Data Rate 393, 470, 958-959, 994995
Send Data Type 381, 393, 468, 470, 958959, 994-995

(Undefined variable: NTO_User_Guide.Title)

set attribute 104

Test Object Command 1028

setup connections 63, 522-523, 558-559,

1019

chrTest abandon 1029

chrTest addChannel 1031

silence suppression 753, 1108

chrTest addMGroup 1032

SPX_DEFAULT_SEND 943, 967, 980

chrTest addPair 1033

start test 638

chrTest addReceiver 1034

start time 615

chrTest clearIxiaConfiguration 1035

START_TIME 1038

chrTest clearResults 1036

stop test 44, 640, 1073

chrTest delete 1037

stop time 616

chrTest get 1038

STOP_AFTER_NUM_PAIRS_FAIL 1016, 1019

STOP_ON_INIT_ERR 1016, 1019

chrTest getAppGroupByIndex 1040

chrTest getAppGroupByName 1041

STOP_TIME 1038

chrTest getAppGroupCount 1042

string parameters in C 105

chrTest getChannel 1043

chrTest getChannelByName 1044

Tcl 36

chrTest getChannelCount 1045

attributes 834

chrTest getDgOpts 1046

catch command 835

chrTest getGroupingOrder 1047

copy subcommand 834

chrTest getGroupingType 1048

delete subcommand 834

chrTest getMGroup 1049

error returns 835

chrTest getMGroupCount 1050

get subcommand 834

chrTest getPair 1051

new subcommand 834

chrTest getPairCount 1052

Tcl Interpreter 964

chrTest getReceiver 1053

Tcl Introduction 833

chrTest getReceiverByName 1054

Tcl Script 95

chrTest getReceiverCount 1055

Tcl versions 837

chrTest getTestServerSession 1056

Tcl_samp 95

chrTest isStopped 1057

tclsh 41, 838

chrTest load 1058

TCP 49, 52, 943

chrTest loadAppGroups 1059

defaults 396, 953, 989

chrTest loadIxiaConfiguration 1060

test

chrTest new 1061

stopping 44

chrTest removeAppGroup 1062

test filename 1038, 1067

chrTest removeChannel 1063

test object 46

chrTest removeReceiver 1064

default values 47

chrTest save 1065

Test Object 584

- 1240 -

(Undefined variable: NTO_User_Guide.Title)

chrTest saveIxiaConfiguration 1066

CHR_test_get_receiver_by_name 612

chrTest set 1067

CHR_test_get_receiver_count 613

chrTest setGroupingOrder 1069

CHR_test_get_runopts 614

chrTest setGroupingType 1070

CHR_test_get_start_time 615

chrTest setTestServerSession 1071

CHR_test_get_stop_time 616

chrTest start 1072

CHR_test_get_test_server_session 617

chrTest stop 1073

CHR_test_get_throughput_units 619

Test Object Functions

CHR_test_load 620

CHR_test_abandon 585

CHR_test_load_app_groups 622

CHR_test_add_app_group 586

CHR_test_new 624

CHR_test_add_channel 588

CHR_test_query_stop 625

CHR_test_add_mgroup 589

CHR_test_remove_app_group 626

CHR_test_add_pair 590

CHR_test_remove_channel 627

CHR_test_add_receiver 591

CHR_test_remove_receiver 628

CHR_test_clear_results 592

CHR_test_save 629

CHR_test_delete 593

CHR_test_set_filename 630

CHR_test_force_delete 594

CHR_test_set_grouping_order 632

CHR_test_get_app_group_by_index 595

CHR_test_set_grouping_type 633

CHR_test_get_app_group_by_name 596

CHR_test_set_test_server_session 635

CHR_test_get_app_group_count 597

CHR_test_set_throughput_units 637

CHR_test_get_channel 598

CHR_test_start 638

CHR_test_get_channel_by_name 599

CHR_test_stop 640

CHR_test_get_channel_count 600

TEST_DURATION 1016, 1019

CHR_test_get_dgopts 601

TEST_END 1016, 1019

CHR_test_get_filename 602

throughput_units 393, 470, 958-959, 994995, 1038, 1067

CHR_test_get_grouping 603
CHR_test_get_how_ended 604
CHR_test_get_local_start_time 605
CHR_test_get_local_stop_time 606
CHR_test_get_mgroup 607
CHR_test_get_mgroup_count 608
CHR_test_get_pair 609
CHR_test_get_pair_count 610
CHR_test_get_receiver 611

- 1241 of 1244-

time to live 235, 246

timing record 406, 446
timing record count 447
timing record object 64, 641
Timing Record Object Command 1074
chrTimingRec get 1075
chrTimingRec getResultFrequency 1077

(Undefined variable: NTO_User_Guide.Title)

Timing Record Object Functions

Traceroute Pair Object Functions

CHR_timingrec_get_df 642

CHR_tracert_pair_delete 660

CHR_timingrec_get_e1_BSSID 643

CHR_tracert_pair_get_e1_addr 661

CHR_timingrec_get_e1_RSSI 644

CHR_tracert_pair_get_e2_addr 662

CHR_timingrec_get_e2_BSSID 645

CHR_tracert_pair_get_hop_record 663

CHR_timingrec_get_e2_RSSI 646

CHR_tracert_pair_get_max_hops 664

CHR_timingrec_get_elapsed 647

CHR_tracert_pair_get_max_timeout 665

CHR_timingrec_get_end_to_end_
delay 648

CHR_tracert_pair_get_resolve_hop_
name 666

CHR_timingrec_get_inactive 649

CHR_tracert_pair_get_runstatus 667

CHR_timingrec_get_jitter 650

CHR_tracert_pair_new 668

CHR_timingrec_get_max_consecutive_
lost 651

CHR_tracert_pair_query_stop 669
CHR_tracert_pair_results_get_hop_
count 670

CHR_timingrec_get_max_delay_
variation 652

CHR_tracert_pair_run 671

CHR_timingrec_get_mlr 653

CHR_tracert_pair_set_e1_addr 672

CHR_timingrec_get_MOS_estimate 654

CHR_tracert_pair_set_e2_addr 673

CHR_timingrec_get_one_way_delay 655

CHR_tracert_pair_set_max_hops 674

CHR_timingrec_get_R_value 656

CHR_tracert_pair_set_max_timeout 675

CHR_timingrec_get_report_group_id 657

CHR_tracert_pair_set_resolve_hop_
name 676

CHR_timingrec_get_result_frequency 658
traceroute 39, 67, 252, 670, 1080

CHR_tracert_pair_stop 677

hop record 663

troubleshooting 107, 836

maximum timeout 675

TTL 235, 246

traceroute pair object 65-66

Traceroute Pair Object 659

UDP 55, 943

Traceroute Pair Object Command 1079

UDP checksum 470

chrTracertPair delete 1080

UDP_DEFAULT_SEND 943, 967, 980

chrTracertPair get 1081

chrTracertPair getHopRecord 1083

validate received data 546, 583

chrTracertPair getHopRecordCount 1084

VALIDATE_ON_RECV 1016, 1019, 1023

chrTracertPair isStopped 1085

variables in scripts

chrTracertPair new 1086

setting 958-959, 994

chrTracertPair run 1087

VERSION 943, 967, 980

chrTracertPair set 1088

version of API 854

chrTracertPair stop 1090

Video Multicast Group Object Command

chrVideoMGroup get 1092

- 1242 -

(Undefined variable: NTO_User_Guide.Title)

chrVideoMGroup new 1094

chrVideoMGroup set 1095
Video Multicast Group Object Functions

chrVideoPair set 1101

Video Pair Object Functions 699, 1097
CHR_video_pair_get_bitrate 700

CHR_video_mgroup_get_bitrate 679

CHR_video_pair_get_codec 701

CHR_video_mgroup_get_codec 680

CHR_video_pair_get_dest_port_
num 702

CHR_video_mgroup_get_frames_per_
datagram 681
CHR_video_mgroup_get_initial_
delay 682

CHR_video_pair_get_frames_per_datagram 703
CHR_video_pair_get_initial_delay 704

CHR_video_mgroup_get_media_frame_
size 683

CHR_video_pair_get_media_frame_
size 705

CHR_video_mgroup_get_no_of_timing_
records 684

CHR_video_pair_get_no_of_timing_
records 706

CHR_video_mgroup_get_rtp_payload_
type 685

CHR_video_pair_get_rtp_payload_
type 707

CHR_video_mgroup_get_source_port_
num 686

CHR_video_pair_get_source_port_
num 708

CHR_video_mgroup_get_tr_
duration 687

CHR_video_pair_get_tr_duration 709

CHR_video_mgroup_new 688
CHR_video_mgroup_set_bitrate 689
CHR_video_mgroup_set_codec 691
CHR_video_mgroup_set_frames_per_
datagram 692
CHR_video_mgroup_set_initial_
delay 693
CHR_video_mgroup_set_media_frame_
size 694
CHR_video_mgroup_set_no_of_timing_
records 695
CHR_video_mgroup_set_rtp_payload_
type 696
CHR_video_mgroup_set_source_port_
num 697
CHR_video_mgroup_set_tr_
duration 698
Video Pair Object Command
chrVideoPair get 1098
chrVideoPair new 1100

- 1243 of 1244-

CHR_video_pair_new 710
CHR_video_pair_set_bitrate 711
CHR_video_pair_set_codec 713
CHR_video_pair_set_dest_port_
num 714
CHR_video_pair_set_frames_per_datagram 715
CHR_video_pair_set_initial_delay 716
CHR_video_pair_set_media_frame_
size 717
CHR_video_pair_set_no_of_timing_
records 718
CHR_video_pair_set_rtp_payload_
type 719
CHR_video_pair_set_source_port_
num 720
CHR_video_pair_set_tr_duration 721
voice activity rate 754
voice over IP 722
VoIP Hardware Pair Object Command 1114

(Undefined variable: NTO_User_Guide.Title)

VoIP pair object 68

CHR_voip_pair_set_tr_duration 751

VoIP Pair Object Command 1104

CHR_voip_pair_set_use_PLC 752

chrVoipPair get 1105

CHR_voip_pair_set_use_silence_sup 753

chrVoIPPair new 1107

CHR_voip_pair_set_voice_activ_rate 754

chrVoipPair set 1108

chrVoIPPair setPayloadFile 1111

window size 236

chrVoIPPair setPayloadRandom 1113

WINSOCK_API 943, 967, 980

VoIP Pair Object Functions 722

WINSOCK_STACK_VER 943, 967, 980

CHR_voip_pair_get_additional_delay 723
CHR_voip_pair_get_codec 724

Z
ZEROS 995

CHR_voip_pair_get_concurrent_
streams 725
CHR_voip_pair_get_datagram_delay 726
CHR_voip_pair_get_dest_port_num 727
CHR_voip_pair_get_initial_delay 728
CHR_voip_pair_get_jitter_buffer_size 729
CHR_voip_pair_get_no_of_timing_
records 732
CHR_voip_pair_get_payload_file 736
CHR_voip_pair_get_source_port_num 730
CHR_voip_pair_get_tr_duration 731
CHR_voip_pair_get_use_PLC 733
CHR_voip_pair_get_use_silence_sup 734
CHR_voip_pair_get_voice_activ_rate 735
CHR_voip_pair_new 738
CHR_voip_pair_set_additional_delay 739
CHR_voip_pair_set_codec 740
CHR_voip_pair_set_concurrent_voice_
streams 741
CHR_voip_pair_set_datagram_delay 742
CHR_voip_pair_set_dest_port_num 743
CHR_voip_pair_set_initial_delay 744
CHR_voip_pair_set_jitter_buffer_size 745
CHR_voip_pair_set_no_of_timing_
records 746
CHR_voip_pair_set_payload_file 747
CHR_voip_pair_set_payload_random 749
CHR_voip_pair_set_source_port_num 750

- 1244 -